1 $DragonFly: src/share/doc/handbook/Attic/handbook.txt,v 1.2 2007/11/07 17:42:50 dillon Exp $
5 The DragonFly Documentation Project
7 Copyright (c) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
8 The FreeBSD Documentation Project
10 Copyright (c) 2004, 2005, 2006 The DragonFly Documentation Project
12 Welcome to DragonFly! This handbook covers the installation and day to day
13 use of the DragonFly operating system. This manual is a work in progress
14 and is the work of many individuals. Many sections do not yet exist and
15 some of those that do exist need to be updated. If you are interested in
16 helping with this project, send email to the DragonFly Documentation
17 project mailing list. The latest version of this document is always
18 available from the DragonFly web site or mirror sites, in a variety of
21 Portions of this document originally documented use of the FreeBSD
22 operating system. While many functions should be similar on DragonFly,
23 some differences should be expected. If you find instructions here that no
24 longer apply to DragonFly, please contact the documentation mailing list
25 at DragonFly Documentation project mailing list .
27 Redistribution and use in source (SGML DocBook) and 'compiled' forms
28 (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
29 modification, are permitted provided that the following conditions are
32 1. Redistributions of source code (SGML DocBook) must retain the above
33 copyright notice, this list of conditions and the following disclaimer
34 as the first lines of this file unmodified.
36 2. Redistributions in compiled form (transformed to other DTDs, converted
37 to PDF, PostScript, RTF and other formats) must reproduce the above
38 copyright notice, this list of conditions and the following disclaimer
39 in the documentation and/or other materials provided with the
42 Important: THIS DOCUMENTATION IS PROVIDED BY THE DRAGONFLYBSD PROJECT
43 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
44 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
45 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE DRAGONFLYBSD
46 PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
47 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
48 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
49 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
50 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
51 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
52 DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
54 DragonFlyBSD is a registered trademark of the DragonFlyBSD Project.
56 FreeBSD is a registered trademark of Wind River Systems, Inc. This is
57 expected to change soon.
59 NetBSD is a registered trademark of The NetBSD Foundation, Inc.
61 3Com and HomeConnect are registered trademarks of 3Com Corporation.
63 3ware and Escalade are registered trademarks of 3ware Inc.
65 ARM is a registered trademark of ARM Limited.
67 Adaptec is a registered trademark of Adaptec, Inc.
69 Adobe, Acrobat, Acrobat Reader, and PostScript are either registered
70 trademarks or trademarks of Adobe Systems Incorporated in the United
71 States and/or other countries.
73 Apple, FireWire, Mac, Macintosh, Mac OS, Quicktime, and TrueType are
74 trademarks of Apple Computer, Inc., registered in the United States and
77 Corel and WordPerfect are trademarks or registered trademarks of Corel
78 Corporation and/or its subsidiaries in Canada, the United States and/or
81 Sound Blaster is a trademark of Creative Technology Ltd. in the United
82 States and/or other countries.
84 CVSup is a registered trademark of John D. Polstra.
86 Heidelberg, Helvetica, Palatino, and Times Roman are either registered
87 trademarks or trademarks of Heidelberger Druckmaschinen AG in the U.S. and
90 IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, and ThinkPad
91 are trademarks of International Business Machines Corporation in the
92 United States, other countries, or both.
94 IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical
95 and Electronics Engineers, Inc. in the United States.
97 Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, and Xeon are
98 trademarks or registered trademarks of Intel Corporation or its
99 subsidiaries in the United States and other countries.
101 Intuit and Quicken are registered trademarks and/or registered service
102 marks of Intuit Inc., or one of its subsidiaries, in the United States and
105 Linux is a registered trademark of Linus Torvalds in the United States.
107 LSI Logic, AcceleRAID, eXtremeRAID, MegaRAID and Mylex are trademarks or
108 registered trademarks of LSI Logic Corp.
110 M-Systems and DiskOnChip are trademarks or registered trademarks of
111 M-Systems Flash Disk Pioneers, Ltd.
113 Macromedia, Flash, and Shockwave are trademarks or registered trademarks
114 of Macromedia, Inc. in the United States and/or other countries.
116 Microsoft, FrontPage, MS-DOS, Outlook, Windows, Windows Media, and Windows
117 NT are either registered trademarks or trademarks of Microsoft Corporation
118 in the United States and/or other countries.
120 Netscape and the Netscape Navigator are registered trademarks of Netscape
121 Communications Corporation in the U.S. and other countries.
123 GateD and NextHop are registered and unregistered trademarks of NextHop in
124 the U.S. and other countries.
126 Motif, OSF/1, and UNIX are registered trademarks and IT DialTone and The
127 Open Group are trademarks of The Open Group in the United States and other
130 Oracle is a registered trademark of Oracle Corporation.
132 pkgsrc is a registered trademark of The NetBSD Foundation, Inc.
134 PowerQuest and PartitionMagic are registered trademarks of PowerQuest
135 Corporation in the United States and/or other countries.
137 RealNetworks, RealPlayer, and RealAudio are the registered trademarks of
140 Red Hat, RPM, are trademarks or registered trademarks of Red Hat, Inc. in
141 the United States and other countries.
143 SAP, R/3, and mySAP are trademarks or registered trademarks of SAP AG in
144 Germany and in several other countries all over the world.
146 Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer Pages, JDK,
147 JSP, JVM, Netra, Solaris, StarOffice, Sun Blade, Sun Enterprise, Sun Fire,
148 SunOS, and Ultra are trademarks or registered trademarks of Sun
149 Microsystems, Inc. in the United States and other countries.
151 Symantec and Ghost are registered trademarks of Symantec Corporation in
152 the United States and other countries.
154 MATLAB is a registered trademark of The MathWorks, Inc.
156 SpeedTouch is a trademark of Thomson
158 U.S. Robotics and Sportster are registered trademarks of U.S. Robotics
161 VMware is a trademark of VMware, Inc.
163 Waterloo Maple and Maple are trademarks or registered trademarks of
166 Mathematica is a registered trademark of Wolfram Research, Inc.
168 XFree86 is a trademark of The XFree86 Project, Inc.
170 Ogg Vorbis and Xiph.Org are trademarks of Xiph.Org.
172 Many of the designations used by manufacturers and sellers to distinguish
173 their products are claimed as trademarks. Where those designations appear
174 in this document, and the FreeBSD Project was aware of the trademark
175 claim, the designations have been followed by the ``(TM)'' or the ``(R)''
178 ----------------------------------------------------------------------
190 1.2 Welcome to DragonFly!
192 1.3 About the DragonFly Project
194 2 Installation from CD
196 2.1 CD Installation Overview
198 2.2 CD Installation - Making room
200 2.3 CD Installation - Disk setup
202 2.4 Installing to Disk from CD
204 2.5 CD Installation - Post-install cleanup
206 2.6 CD Installation - New system setup
212 3.2 Virtual Consoles and Terminals
216 3.4 Directory Structure
218 3.5 Disk Organization
220 3.6 Mounting and Unmounting File Systems
224 3.8 Daemons, Signals, and Killing Processes
230 3.11 Devices and Device Nodes
234 3.13 For More Information
236 4 Installing Applications using NetBSD's pkgsrc framework
240 4.2 Overview of Software Installation
242 4.3 Finding Your Application
244 4.4 Using the Binary Packages System
246 4.5 Using the pkgsrc(R) Source Tree
248 4.6 Post-installation Activities
250 4.7 Dealing with Broken Packages
252 5 The X Window System
258 5.3 Installing XFree86(TM)
260 5.4 XFree86 Configuration
262 5.5 Using Fonts in XFree86
264 5.6 The X Display Manager
266 5.7 Desktop Environments
268 II. System Administration
270 6 Configuration and Tuning
274 6.2 Initial Configuration
276 6.3 Core Configuration
278 6.4 Application Configuration
280 6.5 Starting Services
282 6.6 Configuring the cron Utility
284 6.7 Using rc under DragonFly
286 6.8 Setting Up Network Interface Cards
290 6.10 Configuration Files
292 6.11 Tuning with sysctl
296 6.13 Tuning Kernel Limits
298 6.14 Adding Swap Space
300 6.15 Power and Resource Management
302 6.16 Using and Debugging DragonFly ACPI
304 7 The DragonFly Booting Process
308 7.2 The Booting Problem
310 7.3 The Boot Manager and Boot Stages
312 7.4 Kernel Interaction During Boot
314 7.5 Init: Process Control Initialization
316 7.6 Shutdown Sequence
318 8 Users and Basic Account Management
324 8.3 The Superuser Account
330 8.6 Modifying Accounts
334 8.8 Personalizing Users
338 9 Configuring the DragonFly Kernel
342 9.2 Why Build a Custom Kernel?
344 9.3 Building and Installing a Custom Kernel
346 9.4 The Configuration File
348 9.5 Making Device Nodes
350 9.6 If Something Goes Wrong
358 10.3 Securing DragonFly
360 10.4 DES, MD5, and Crypt
362 10.5 One-time Passwords
382 11.4 Advanced Printer Setup
386 11.6 Alternatives to the Standard Spooler
400 12.5 Creating and Using Optical Media (CDs)
402 12.6 Creating and Using Optical Media (DVDs)
404 12.7 Creating and Using Floppy Disks
406 12.8 Creating and Using Data Tapes
408 12.9 Backups to Floppies
412 12.11 Network, Memory, and File-Backed File
415 12.12 File System Quotas
417 13 The Vinum Volume Manager
421 13.2 Disks Are Too Small
423 13.3 Access Bottlenecks
433 13.8 Configuring Vinum
435 13.9 Using Vinum for the Root Filesystem
437 14 Localization - I18N/L10N Usage and Setup
443 14.3 Using Localization
445 14.4 Compiling I18N Programs
447 14.5 Localizing DragonFly to Specific Languages
449 15 Desktop Applications
457 15.4 Document Viewers
467 16.2 Setting Up the Sound Card
473 16.5 Setting Up TV Cards
475 17 Serial Communications
485 17.5 Dial-out Service
487 17.6 Setting Up the Serial Console
495 18.3 Using Kernel PPP
497 18.4 Troubleshooting PPP Connections
499 18.5 Using PPP over Ethernet (PPPoE)
503 19 Advanced Networking
507 19.2 Gateways and Routes
509 19.3 Wireless Networking
517 19.7 Diskless Operation
529 19.13 Network Address Translation
531 19.14 The inetd ``Super-Server''
533 19.15 Parallel Line IP (PLIP)
541 20.2 Using Electronic Mail
543 20.3 sendmail Configuration
545 20.4 Changing Your Mail Transfer Agent
553 20.8 Setting up to send only
555 20.9 Using Mail with a Dialup Connection
557 20.10 SMTP Authentication
559 20.11 Mail User Agents
561 20.12 Using fetchmail
565 21 Updating DragonFly
571 21.3 Preparing to Update
573 21.4 Updating the System
575 22 Linux Binary Compatibility
581 22.3 Installing Mathematica(R)
583 22.4 Installing Maple(TM)
585 22.5 Installing MATLAB(R)
587 22.6 Installing Oracle(R)
589 22.7 Installing SAP(R) R/3(R)
595 A. Obtaining DragonFly
597 A.1 CDROM and DVD Publishers
607 B.1 Books & Magazines Specific to BSD
611 B.3 Administrators' Guides
613 B.4 Programmers' Guides
615 B.5 Operating System Internals
617 B.6 Security Reference
619 B.7 Hardware Reference
623 B.9 Magazines and Journals
625 C. Resources on the Internet
629 C.2 Usenet Newsgroups
631 C.3 World Wide Web Servers
641 3-1. Disk Device Codes
643 12-1. Physical Disk Naming Conventions
645 13-1. Vinum Plex Organizations
647 19-1. Wiring a Parallel Cable for Networking
649 19-2. Reserved IPv6 addresses
653 13-1. Concatenated Organization
655 13-2. Striped Organization
657 13-3. RAID-5 Organization
659 13-4. A Simple Vinum Volume
661 13-5. A Mirrored Vinum Volume
663 13-6. A Striped Vinum Volume
665 13-7. A Mirrored, Striped Vinum Volume
669 3-1. Sample Disk, Slice, and Partition Names
671 3-2. Conceptual Model of a Disk
673 4-1. Downloading a Package Manually and Installing It Locally
675 6-1. Creating a Swapfile
677 7-1. boot0 Screenshot
679 7-2. boot2 Screenshot
681 7-3. An Insecure Console in /etc/ttys
683 8-1. Configuring adduser and adding a user
685 8-2. rmuser Interactive Account Removal
687 8-3. Interactive chpass by Superuser
689 8-4. Interactive chpass by Normal User
691 8-5. Changing Your Password
693 8-6. Changing Another User's Password as the Superuser
695 8-7. Adding a Group Using pw(8)
697 8-8. Adding Somebody to a Group Using pw(8)
699 8-9. Using id(1) to Determine Group Membership
701 10-1. Using SSH to Create a Secure Tunnel for SMTP
703 12-1. Using dump over ssh
705 12-2. Using dump over ssh with RSH set
707 12-3. A Script for Creating a Bootable Floppy
709 12-4. Using vnconfig to Mount an Existing File System Image
711 12-5. Creating a New File-Backed Disk with vnconfig
715 17-1. Adding Terminal Entries to /etc/ttys
717 19-1. Mounting an Export with amd
719 19-2. Branch Office or Home Network
721 19-3. Head Office or Other LAN
723 19-4. Sending inetd a HangUP Signal
725 20-1. Configuring the sendmail Access Database
729 20-3. Example Virtual Domain Mail Map
731 ----------------------------------------------------------------------
737 The DragonFly newcomer will find that the first section of this book
738 guides the user through the DragonFly installation process and gently
739 introduces the concepts and conventions that underpin UNIX(R). Working
740 through this section requires little more than the desire to explore, and
741 the ability to take on board new concepts as they are introduced.
743 Once you have travelled this far, the second, far larger, section of the
744 Handbook is a comprehensive reference to all manner of topics of interest
745 to DragonFly system administrators. Some of these chapters may recommend
746 that you do some prior reading, and this is noted in the synopsis at the
747 beginning of each chapter.
749 For a list of additional sources of information, please see Appendix B.
751 Organization of This Book
753 This book is split into three logically distinct sections. The first
754 section, Getting Started, covers the installation and basic usage of
755 DragonFly. It is expected that the reader will follow these chapters in
756 sequence, possibly skipping chapters covering familiar topics. The second
757 section, System Administration, covers a broad collection of subjects that
758 are of interest to more advanced DragonFly users. Each section begins with
759 a succinct synopsis that describes what the chapter covers and what the
760 reader is expected to already know. This is meant to allow the casual
761 reader to skip around to find chapters of interest. The third section
762 contains appendices of reference information.
764 Chapter 1, Introduction
766 Introduces DragonFly to a new user. It describes the history of
767 the DragonFly Project, its goals and development model.
769 Chapter 2, Installation
771 Walks a user through the entire installation process. Some
772 advanced installation topics, such as installing through a serial
773 console, are also covered.
775 Chapter 3, UNIX Basics
777 Covers the basic commands and functionality of the DragonFly
778 operating system. If you are familiar with Linux or another flavor
779 of UNIX then you can probably skip this chapter.
781 Chapter 4, Installing Applications
783 Covers the installation of third-party software using NetBSD(R)'s
784 Packages Collection pkgsrc(R).
786 Chapter 5, The X Window System
788 Describes the X Window System in general and using XFree86(TM) and
789 X.org on DragonFly in particular. Also describes common desktop
790 environments such as KDE and GNOME.
792 Chapter 6, Configuration and Tuning
794 Describes the parameters available for system administrators to
795 tune a DragonFly system for optimum performance. Also describes
796 the various configuration files used in DragonFly and where to
799 Chapter 7, Booting Process
801 Describes the DragonFly boot process and explains how to control
802 this process with configuration options.
804 Chapter 8, Users and Basic Account Management
806 Describes the creation and manipulation of user accounts. Also
807 discusses resource limitations that can be set on users and other
808 account management tasks.
810 Chapter 9, Configuring the DragonFly Kernel
812 Explains why you might need to configure a new kernel and provides
813 detailed instructions for configuring, building, and installing a
818 Describes many different tools available to help keep your
819 DragonFly system secure, including Kerberos, IPsec, OpenSSH, and
824 Describes managing printers on DragonFly, including information
825 about banner pages, printer accounting, and initial setup.
829 Describes how to manage storage media and filesystems with
830 DragonFly. This includes physical disks, RAID arrays, optical and
831 tape media, memory-backed disks, and network filesystems.
835 Describes how to use Vinum, a logical volume manager which
836 provides device-independent logical disks, and software RAID-0,
839 Chapter 14, Localization
841 Describes how to use DragonFly in languages other than English.
842 Covers both system and application level localization.
844 Chapter 15, Desktop Applications
846 Lists some common desktop applications, such as web browsers and
847 productivity suites, and describes how to install them on
850 Chapter 16, Multimedia
852 Shows how to set up sound and video playback support for your
853 system. Also describes some sample audio and video applications.
855 Chapter 17, Serial Communications
857 Explains how to connect terminals and modems to your DragonFly
858 system for both dial in and dial out connections.
860 Chapter 18, PPP and SLIP
862 Describes how to use PPP, SLIP, or PPP over Ethernet to connect to
863 remote systems with DragonFly.
865 Chapter 19, Advanced Networking
867 Describes many networking topics, including sharing an Internet
868 connection with other computers on your LAN, using network
869 filesystems, sharing account information via NIS, setting up a
870 name server, and much more.
872 Chapter 20, Electronic Mail
874 Explains the different components of an email server and dives
875 into simple configuration topics for the most popular mail server
878 Section 21.1, Updating DragonFly
880 Describes the development paths of DragonFly, and how to stay
883 Chapter 22, Linux Binary Compatibility
885 Describes the Linux compatibility features of DragonFly. Also
886 provides detailed installation instructions for many popular Linux
887 applications such as Oracle(R), SAP(R) R/3(R), and Mathematica(R).
889 Appendix A, Obtaining DragonFly
891 Lists different sources for obtaining DragonFly media on CDROM or
892 DVD as well as different sites on the Internet that allow you to
893 download and install DragonFly.
895 Appendix B, Bibliography
897 This book touches on many different subjects that may leave you
898 hungry for a more detailed explanation. The bibliography lists
899 many excellent books that are referenced in the text.
901 Appendix C, Resources on the Internet
903 Describes the many forums available for DragonFly users to post
904 questions and engage in technical conversations about DragonFly.
908 Lists the PGP fingerprints of several DragonFly Developers.
910 Conventions used in this book
912 To provide a consistent and easy to read text, several conventions are
913 followed throughout the book.
915 Typographic Conventions
919 An italic font is used for filenames, URLs, emphasized text, and
920 the first usage of technical terms.
924 A monospaced font is used for error messages, commands,
925 environment variables, names of ports, hostnames, user names,
926 group names, device names, variables, and code fragments.
930 A bold font is used for applications, commands, and keys.
934 Keys are shown in bold to stand out from other text. Key combinations that
935 are meant to be typed simultaneously are shown with `+' between the keys,
940 Meaning the user should type the Ctrl, Alt,and Del keys at the same time.
942 Keys that are meant to be typed in sequence will be separated with commas,
947 Would mean that the user is expected to type the Ctrl and X keys
948 simultaneously and then to type the Ctrl and S keys simultaneously.
952 Examples starting with # indicate a command that must be invoked as the
953 superuser in DragonFly. You can login as root to type the command, or
954 login as your normal account and use su(1) to gain superuser privileges.
956 # dd if=kern.flp of=/dev/fd0
958 Examples starting with % indicate a command that should be invoked from a
959 normal user account. Unless otherwise noted, C-shell syntax is used for
960 setting environment variables and other shell commands.
964 Examples starting with E:\> indicate a MS-DOS(R) command. Unless otherwise
965 noted, these commands may be executed from a ``Command Prompt'' window in
966 a modern Microsoft(R) Windows(R) environment.
968 E:\> tools\fdimage floppies\kern.flp A:
972 The book you are holding represents the efforts of many hundreds of people
973 around the world. Whether they sent in fixes for typos, or submitted
974 complete chapters, all the contributions have been useful.
976 The DragonFly Handbook was originally built from an edition of the FreeBSD
977 Handbook. The FreeBSD Handbook was created by the collective hard work of
978 hundreds of people, and the DragonFly Documentation Team appreciates all
979 their labor. Included here is a list of all individually identified people
980 and corporations that contributed resources to this handbook.
982 Eric Anderson, Satoshi Asami, Bojan Bistrovic, Neil Blakey-Milner, Andrew
983 Boothman, Harti Brandt, Jim Brown, BSDi, Andrey A. Chernov, Peter Childs,
984 Munish Chopra, Joe Marcus Clarke, Nik Clayton, Mark Dapoz, Matt Dillon,
985 Jean-Franc,ois Dockes, Alex Dupre, Josef El-Rayes, Udo Erdelhoff, Marc
986 Fonvieille, Dirk Fro:mberg, Robert Getschmann, James Gorham, Lucky Green,
987 Coranth Gryphon, Jake Hamby, Brian N. Handy, Guy Helmer, Al Hoang, Tillman
988 Hodgson, Jordan Hubbard, Robert Huff, Tom Hukins, Christophe Juniet,
989 Poul-Henning Kamp, Aaron Kaplan, Martin Karlsson, Sean Kelly, Seth
990 Kingsley, Holger Kipp, Nate Lawson, Chern Lee, Greg Lehey, John Lind, Ross
991 Lippert, Bill Lloyd, Pav Lucistnik, Julio Merino, Mike Meyer, Hellmuth
992 Michaelis, Jim Mock, Marcel Moolenaar, Moses Moore, Bill Moran, Rich
993 Murphey, Mark Murray, Alex Nash, Gregory Neil Shapiro, David O'Brien, Eric
994 Ogren, Gary Palmer, Hiten M. Pandya, Bill Paul, Dan Pelleg, Steve
995 Peterson, John Polstra, Andy Polyakov, Randy Pratt, Jeremy C. Reed, Tom
996 Rhodes, Trev Roydhouse, Peter Schultz, Piero Serini, Christopher Shumway,
997 Marc Silver, Mike Smith, Brian Somers, Gennady B. Sorokopud, Wylie
998 Stilwell, Murray Stokely, Greg Sutter, Bill Swingle, Valentino Vaschetto,
999 Robert Watson, Wind River Systems, Michael C. Wu, and Kazutaka YOKOTA.
1003 This part of the DragonFly Handbook is for users and administrators who
1004 are new to DragonFly. These chapters:
1006 * Introduce you to DragonFly.
1008 * Guide you through the installation process.
1010 * Teach you UNIX basics and fundamentals.
1012 * Show you how to install the wealth of third party applications
1013 available for DragonFly.
1015 * Introduce you to X, the UNIX windowing system, and detail how to
1016 configure a desktop environment that makes you more productive.
1018 We have tried to keep the number of forward references in the text to a
1019 minimum so that you can read this section of the Handbook from front to
1020 back with the minimum page flipping required.
1026 2 Installation from CD
1030 4 Installing Applications using NetBSD's pkgsrc framework
1032 5 The X Window System
1034 ----------------------------------------------------------------------
1036 Chapter 1 Introduction
1038 Restructured, reorganized, and parts rewritten by Jim Mock.
1042 Thank you for your interest in DragonFly! The following chapter covers
1043 various aspects of the DragonFly Project, such as its history, goals,
1044 development model, and so on.
1046 After reading this chapter, you will know:
1048 * How DragonFly relates to other computer operating systems.
1050 * The history of the DragonFly Project.
1052 * The goals of the DragonFly Project.
1054 * The basics of the DragonFly open-source development model.
1056 * And of course: where the name ``DragonFly'' comes from.
1058 ----------------------------------------------------------------------
1060 1.2 Welcome to DragonFly!
1062 DragonFly is a 4.4BSD-Lite based operating system for Intel (x86). A port
1063 to AMD64 is in progress. You can also read about the history of DragonFly,
1064 or the current release.
1066 ----------------------------------------------------------------------
1068 1.2.1 What Can DragonFly Do?
1070 DragonFly has many noteworthy features. Some of these are:
1072 * Preemptive multitasking with dynamic priority adjustment to ensure
1073 smooth and fair sharing of the computer between applications and
1074 users, even under the heaviest of loads.
1076 * Multi-user facilities which allow many people to use a DragonFly
1077 system simultaneously for a variety of things. This means, for
1078 example, that system peripherals such as printers and tape drives are
1079 properly shared between all users on the system or the network and
1080 that individual resource limits can be placed on users or groups of
1081 users, protecting critical system resources from over-use.
1083 * Strong TCP/IP networking with support for industry standards such as
1084 SLIP, PPP, NFS, DHCP, and NIS. This means that your DragonFly machine
1085 can interoperate easily with other systems as well as act as an
1086 enterprise server, providing vital functions such as NFS (remote file
1087 access) and email services or putting your organization on the
1088 Internet with WWW, FTP, routing and firewall (security) services.
1090 * Memory protection ensures that applications (or users) cannot
1091 interfere with each other. One application crashing will not affect
1094 * DragonFly is a 32-bit operating system.
1096 * The industry standard X Window System (X11R6) provides a graphical
1097 user interface (GUI) for the cost of a common VGA card and monitor and
1098 comes with full sources.
1100 * Binary compatibility with many programs built for Linux, SCO, SVR4,
1103 * Thousands of ready-to-run applications are available from the pkgsrc
1104 packages collection. Why search the net when you can find it all right
1107 * Thousands of additional and easy-to-port applications are available on
1108 the Internet. DragonFly is source code compatible with most popular
1109 commercial UNIX systems and thus most applications require few, if
1110 any, changes to compile.
1112 * Demand paged virtual memory and ``merged VM/buffer cache'' design
1113 efficiently satisfies applications with large appetites for memory
1114 while still maintaining interactive response to other users.
1116 * SMP support for machines with multiple CPUs.
1118 * A full complement of C, C++, Fortran, and Perl development tools. Many
1119 additional languages for advanced research and development are also
1120 available in the ports and packages collection.
1122 * Source code for the entire system means you have the greatest degree
1123 of control over your environment. Why be locked into a proprietary
1124 solution at the mercy of your vendor when you can have a truly open
1127 * Extensive online documentation.
1131 DragonFly is based on the 4.4BSD-Lite release from Computer Systems
1132 Research Group (CSRG) at the University of California at Berkeley, along
1133 with later development of FreeBSD by the FreeBSD Project. It carries on
1134 the distinguished tradition of BSD systems development. In addition to the
1135 fine work provided by CSRG, the DragonFly Project has put in many
1136 thousands of hours in fine tuning the system for maximum performance and
1137 reliability in real-life load situations. As many of the commercial giants
1138 struggle to field PC operating systems with such features, performance and
1139 reliability, DragonFly can offer them now!
1141 The applications to which DragonFly can be put are truly limited only by
1142 your own imagination. From software development to factory automation,
1143 inventory control to azimuth correction of remote satellite antennae; if
1144 it can be done with a commercial UNIX product then it is more than likely
1145 that you can do it with DragonFly too! DragonFly also benefits
1146 significantly from literally thousands of high quality applications
1147 developed by research centers and universities around the world, often
1148 available at little to no cost. Commercial applications are also available
1149 and appearing in greater numbers every day.
1151 Because the source code for DragonFly itself is generally available, the
1152 system can also be customized to an almost unheard of degree for special
1153 applications or projects, and in ways not generally possible with
1154 operating systems from most major commercial vendors. Here is just a
1155 sampling of some of the applications in which people are currently using
1158 * Internet Services: The robust TCP/IP networking built into DragonFly
1159 makes it an ideal platform for a variety of Internet services such as:
1163 * World Wide Web servers (standard or secure [SSL])
1165 * Firewalls and NAT (``IP masquerading'') gateways
1167 * Electronic Mail servers
1169 * USENET News or Bulletin Board Systems
1173 With DragonFly, you can easily start out small with an inexpensive 386
1174 class PC and upgrade all the way up to a quad-processor Xeon with RAID
1175 storage as your enterprise grows.
1177 * Education: Are you a student of computer science or a related
1178 engineering field? There is no better way of learning about operating
1179 systems, computer architecture and networking than the hands on, under
1180 the hood experience that DragonFly can provide. A number of freely
1181 available CAD, mathematical and graphic design packages also make it
1182 highly useful to those whose primary interest in a computer is to get
1185 * Research: With source code for the entire system available, DragonFly
1186 is an excellent platform for research in operating systems as well as
1187 other branches of computer science. DragonFly's freely available
1188 nature also makes it possible for remote groups to collaborate on
1189 ideas or shared development without having to worry about special
1190 licensing agreements or limitations on what may be discussed in open
1193 * Networking: Need a new router? A name server (DNS)? A firewall to keep
1194 people out of your internal network? DragonFly can easily turn that
1195 unused older PC sitting in the corner into an advanced router with
1196 sophisticated packet-filtering capabilities.
1198 * X Window workstation: DragonFly is a fine choice for an inexpensive X
1199 terminal solution, either using the freely available XFree86 or X.org
1200 servers or one of the excellent commercial servers provided by Xi
1201 Graphics. Unlike an X terminal, DragonFly allows many applications to
1202 be run locally if desired, thus relieving the burden on a central
1203 server. DragonFly can even boot ``diskless'', making individual
1204 workstations even cheaper and easier to administer.
1206 * Software Development: The basic DragonFly system comes with a full
1207 complement of development tools including the renowned GNU C/C++
1208 compiler and debugger.
1210 DragonFly is available via anonymous FTP or CVS. Please see Appendix A for
1211 more information about obtaining DragonFly.
1213 ----------------------------------------------------------------------
1215 1.3 About the DragonFly Project
1217 The following section provides some background information on the project,
1218 including a brief history, project goals, and the development model of the
1221 ----------------------------------------------------------------------
1223 1.3.1 A Brief History of DragonFly
1225 Matthew Dillon, one of the developers for FreeBSD, was growing
1226 increasingly frustrated with the FreeBSD Project's direction for release
1227 5. The FreeBSD 5 release had been delayed multiple times, and had
1228 performance problems compared to earlier releases of FreeBSD.
1230 DragonFly was announced in June of 2003. The code base was taken from the
1231 4.8 release of FreeBSD, which offered better performance and more complete
1234 Development has proceeded at a very quick rate since then, with Matt
1235 Dillon and a small group of developers fixing longstanding BSD bugs and
1236 modernizing the new DragonFly system.
1238 ----------------------------------------------------------------------
1240 1.3.2 DragonFly Project Goals
1242 DragonFly is an effort to maintain the traditional BSD format -- lean,
1243 stable code -- along with modern features such as lightweight threads, a
1244 workable packaging system, and a revised VFS. Underpinning all this work
1245 is efficient support for multiple processors, something rare among open
1246 source systems. Because DragonFly is built on an existing very stable code
1247 base, it is possible to make these radical changes as part of an
1248 incremental process.
1250 ----------------------------------------------------------------------
1252 1.3.3 The DragonFly Development Model
1254 Written by Justin Sherrill.
1256 DragonFly is developed by many people around the world. There is no
1257 qualification process; anyone may submit his or her code, documentation,
1258 or designs, for use in the Project. Here is a general description of the
1259 Project's organizational structure.
1263 Source for DragonFly is kept in CVS (Concurrent Versions System),
1264 which is available with each DragonFly install. The primary CVS
1265 repository resides on a machine in California, USA. Documentation
1266 on obtaining the DragonFly source is available elsewhere in this
1271 The best way of getting changes made to the DragonFly source is to
1272 mail the submit mailing list. Including desired source code
1273 changes (unified diff format is best) is the most useful format. A
1274 certain number of developers have access to commit changes to the
1275 DragonFly source, and can do so after review on that list.
1277 The DragonFly development model is loose; changes to the code are
1278 generally peer-reviewed and added when any objections have been corrected.
1279 There is no formal entry/rejection process, though final say on all code
1280 submissions goes to Matt Dillon, as originator of this project.
1282 ----------------------------------------------------------------------
1284 1.3.4 The Current DragonFly Release
1286 DragonFly is a freely available, full source 4.4BSD-Lite based release for
1287 Intel i386(TM), i486(TM), Pentium(R), Pentium Pro, Celeron(R), Pentium II,
1288 Pentium III, Pentium 4 (or compatible), and Xeon(TM) based computer
1289 systems. It is based primarily on FreeBSD 4.8, and includes enhancements
1290 from U.C. Berkeley's CSRG group, NetBSD, OpenBSD, 386BSD, and the Free
1291 Software Foundation.
1293 A number of additional documents which you may find very helpful in the
1294 process of installing and using DragonFly may now also be found in the
1295 /usr/share/doc directory on any machine.
1297 The most up-to-date documentation can be found at
1298 http://www.dragonflybsd.org/.
1300 ----------------------------------------------------------------------
1302 1.3.5 "DragonFly" Origin
1304 Matthew Dillon happened to take a picture of a dragonfly in his garden
1305 while trying to come up with a name for this new branch of BSD. Taking
1306 this as inspiration, "DragonFly" became the new name.
1308 ----------------------------------------------------------------------
1310 Chapter 2 Installation from CD
1312 Written by Markus Schatzl and Justin Sherrill.
1314 2.1 CD Installation Overview
1316 This document describes the installation of DragonFly BSD on a plain i386
1317 machine. This process uses a bootable DragonFly CD, usually referred to as
1320 This CD is available at one of the current mirrors, which distribute the
1321 images by various protocols. The authorative list can be found at the
1324 This document may be superseded by the /README file located on the live
1325 CD, which may reflect changes made after this document was last updated.
1326 Check that README for any last-minute changes and for an abbreviated
1327 version of this installation process.
1329 The DragonFly development team is working on an automatic installation
1330 tool, which simplifies the partitioning and installation processes. Until
1331 this tool is in place, the manual process here is required. Some
1332 experience with BSD-style tools is recommended.
1334 Caution: While this guide covers installing to a computer with an
1335 existing non-DragonFly operating system, take no chances! Back up any
1336 data on your disk drives that you want to save.
1338 When installing to an old machine, it may not be possible to boot from a
1339 CD. Use a bootmanager on a floppy in those cases, such as Smart
1342 Caution: Always be sure of the target disk for any command. Unless
1343 otherwise specified, each command here assumes the first disk in the IDE
1344 chain is the target. (ad0) Adjust commands as needed.
1346 ----------------------------------------------------------------------
1348 2.2 CD Installation - Making room
1350 2.2.1 DragonFly as the only operating system
1352 If DragonFly is to be the only operating system on the target computer,
1353 preparing the disk is a short and simple process. Boot with the live CD,
1354 and log in as root to reach a command prompt.
1356 First, the master boot record (MBR) must be cleared of any old
1357 information. This command clears all old data off your disk by writing
1358 zeros (if=/dev/zero) onto the system's master ata drive (of=/dev/ad0).
1360 # dd if=/dev/zero of=/dev/ad0 bs=32k count=16
1363 The now-empty disk must be formatted.
1365 Important: This will destroy any existing data on a disk. Do this only
1366 if you plan to dedicate this disk to DragonFly.
1372 ----------------------------------------------------------------------
1374 2.2.2 Multiple operating systems on one hard disk
1376 This example assumes that the target computer for installation has at
1377 least one operating system installed that needs to survive the
1378 installation process. A new partition for DragonFly needs to be created
1379 from the existing partition(s) that otherwise fill the disk. There must be
1380 unused space within the existing partition in order to resize it.
1382 Important: The new partition is created from empty space in an existing
1383 partition. For example, an 18 gigabyte disk that has 17 gigabytes of
1384 existing data in the existing partition will only have 1 gigabyte
1385 available for the new partition.
1387 Partition resizing needs to be accomplished with a third-party tool.
1388 Commercial programs such as Partition Magic can accomplish these tasks.
1389 Free tools exist that can be adapted to this task, such as 'GNU parted',
1390 found on the Knoppix CD, or PAUD.
1392 Create a new partition of at least 5-6 gigabytes. It is possible to
1393 install within a smaller amount of disk space, but this will create
1394 problems not covered by this document. The newly created partition does
1395 not need to be formatted; the rest of the installation process treats that
1396 new partiton as a new disk.
1398 ----------------------------------------------------------------------
1400 2.2.3 Multiple operating systems, multiple hard disks
1402 Installing DragonFly to a separate disk removes the need for partition
1403 resizing, and is generally safer when trying to preserve an existing
1404 operating system installation.
1406 This type of installation is very similar to installing DragonFly as the
1407 only operating system. The only difference is the disk named in each
1410 ----------------------------------------------------------------------
1412 2.3 CD Installation - Disk setup
1414 2.3.1 Disk formatting
1416 The slice layout on the newly formatted disk or partition needs to be set
1417 up, using this command.
1422 If there are multiple operating systems on the disk, pick the correct
1423 partition judging by what partitions were created earlier with a resizing
1426 ----------------------------------------------------------------------
1428 2.3.2 Boot block installation
1430 The 'ad0' here refers to the first disk on the first IDE bus of a
1431 computer. Increment the number if the target disk is farther down the
1432 chain. For example, the master disk on the second IDE controller would be
1439 -s SLICE, where SLICE is a number, controls which slice on disk is used by
1440 boot0cfg to start from. By default, this number is 1, and will only need
1441 modification if a different slice contains DragonFly.
1443 Use -o packet as an option to boot0cfg if the DragonFly partition is
1444 located beyond cylinder 1023 on the disk. This location problem usually
1445 only happens when another operating system is taking up more than the
1446 first 8 gigabytes of disk space. This problem cannot happen if DragonFly
1447 is installed to a dedicated disk
1449 ----------------------------------------------------------------------
1453 If DragonFly is installed anywhere but the first partition of the disk,
1454 the device entry for that partition will have to be created. Otherwise,
1455 the device entry is automatically created. Refer to this different
1456 partition instead of the 'ad0s1a' used in later examples.
1458 # cd /dev; ./MAKEDEV ad0s2
1461 The partition needs to be created on the DragonFly disk.
1463 # disklabel -B -r -w ad0s1 auto
1466 Using /etc/disklabel.ad0s1 as an example, issue the following command to
1467 edit the disklabel for the just-created partition.
1469 # disklabel -e ad0s1
1472 +----------------------------------------------------------------+
1473 | Partition | Size | Mountpoint |
1474 |-----------+-------------+--------------------------------------|
1475 | ad0s2a | 256m | / |
1476 |-----------+-------------+--------------------------------------|
1477 | ad0s2b | 1024m | swap |
1478 |-----------+-------------+--------------------------------------|
1479 | ad0s2c | leave alone | This represents the whole slice. |
1480 |-----------+-------------+--------------------------------------|
1481 | ad0s2d | 256m | /var |
1482 |-----------+-------------+--------------------------------------|
1483 | ad0s2e | 256m | /tmp ! |
1484 |-----------+-------------+--------------------------------------|
1485 | ad0s2f | 8192m | /usr - This should be at least 4096m |
1486 |-----------+-------------+--------------------------------------|
1487 | ad0s2g | * | /home - This holds 'everything else' |
1488 +----------------------------------------------------------------+
1490 ----------------------------------------------------------------------
1492 2.3.4 Partition Format
1494 newfs will format each individual partition.
1497 # newfs -U /dev/ad0s1d
1498 # newfs -U /dev/ad0s1e
1499 # newfs -U /dev/ad0s1f
1500 # newfs -U /dev/ad0s1g
1503 Note: The -U option is not used for the root partition, since / is
1504 usually relatively small. Softupdates can cause it to run out of space
1505 while under a lot of disk activity, such as a buildworld.
1507 Note: The command listing skips directly from ad0s1a to ad0s1d. This is
1508 because /dev/ad0s1b is used as swap and does not require formatting;
1509 ad0s1c refers to the entire disk and should not be formatted.
1511 ----------------------------------------------------------------------
1513 2.4 Installing to Disk from CD
1515 Since the Live CD contains all needed data to create a running DragonFly
1516 system, the simplest installation possible is to copy the Live CD data to
1517 the newly formatted disk/partition created in previous steps.
1519 These commands mount the newly created disk space and create the
1520 appropriate directories on it.
1522 # mount /dev/ad0s1a /mnt
1527 # mount /dev/ad0s1d /mnt/var
1528 # mount /dev/ad0s1e /mnt/tmp
1529 # mount /dev/ad0s1f /mnt/usr
1530 # mount /dev/ad0s1g /mnt/home
1533 cpdup duplicates data from one volume to another. These commands copy data
1534 from the Live CD to the newly created directories on the mounted disk.
1535 Each step can take some time, depending on disk speed.
1538 # cpdup /var /mnt/var
1539 # cpdup /etc /mnt/etc
1540 # cpdup /dev /mnt/dev
1541 # cpdup /usr /mnt/usr
1544 Note: Nothing is copied to the /tmp directory that was created in the
1545 previous step. This is not an error, since /tmp is intended only for
1548 ----------------------------------------------------------------------
1550 2.5 CD Installation - Post-install cleanup
1552 /tmp and /var/tmp are both often used as temporary directories. Since use
1553 is not consistent from application to application, it is worthwhile to
1554 create /tmp as a link to /var/tmp so space is not wasted in duplication.
1556 # chmod 1777 /mnt/tmp
1557 # rm -fr /mnt/var/tmp
1558 # ln -s /tmp /mnt/var/tmp
1561 Note: /tmp will not work until the computer is rebooted.
1563 The file /etc/fstab describes the disk partition layout. However, the
1564 version copied to the target disk only reflects the Live CD layout. The
1565 installed /mnt/fstab.example can be used as a starting point for creating
1568 # vi /mnt/etc/fstab.example
1569 # mv /mnt/etc/fstab.example /mnt/etc/fstab
1572 A corrupted disklabel will render a disk useless. While this is thankfully
1573 very rare, having a backup of the new install's disklabel may stave off
1574 disaster at some point in the future. This is optional. (Adjust the slice
1575 name to reflect the actual installation.)
1577 # disklabel ad0s1 > /mnt/etc/disklabel.backup
1580 Note: Nothing is copied to the /tmp directory that was created in the
1581 previous step. This is not an error, since /tmp is intended only for
1584 Remove some unnecessary files copied over from the Live CD.
1586 # rm /mnt/boot/loader.conf
1587 # rm /mnt/boot.catalog
1588 # rm -r /mnt/rr_moved
1591 The system can now be rebooted. Be sure to remove the Live CD from the
1592 CDROM drive so that the computer can boot from the newly-installed disk.
1597 Note: Use the reboot command so that the disk can be unmounted cleanly.
1598 Hitting the power or reset buttons, while it won't hurt the Live CD, can
1599 leave the mounted disk in a inconsistent state.
1601 If the system refuses to boot, there are several options to try:
1603 * Old bootblocks can interfere with the initialization-process. To avoid
1604 this, zero-out the MBR. "of" should be changed to the correct disk
1605 entry if ad0 is not the targeted installation disk.
1607 # dd if=/dev/zero of=/dev/ad0 bs=32 count=16
1610 * It is possible that the DragonFly slice is beyond cylinder 1023 on the
1611 hard disk, and can't be detected. Packet mode can fix this problem.
1613 # boot0cfg -o packet ad0
1616 * If you can select CHS or LBA mode in your BIOS, try changing the mode
1619 After a successful boot from the newly installed hard drive, the timezone
1620 should be set. Use the command tzsetup to set the appropriate time zone.
1625 ----------------------------------------------------------------------
1627 2.6 CD Installation - New system setup
1629 Once the new DragonFly system is booting from disk, there are a number of
1630 steps that may be useful before working further. The file /etc/rc.conf
1631 controls a number of options for booting the system.
1633 ----------------------------------------------------------------------
1635 2.6.1 Setting up rc.conf
1637 Depending on location, a different keyboard map may be needed. This is
1638 only necessary for computers outside of North America.
1644 Pick the appropriate keyboard map and remember the name. Place this name
1645 in /etc/rc.conf. For example:
1647 keymap="german.iso.kbd"
1650 The file /etc/rc.conf matches the one on the Live CD. Since it is now on
1651 an installed system are no longer running in a read-only environment, some
1652 changes should be made. Changes to this file will take effect after the
1653 next boot of the machine.
1655 These lines can be removed.
1661 For a system which uses USB, this line will need to be modified to a value
1666 inetd controls various small servers like telnet or ftp. By default, all
1667 servers are off, and must be individually uncommented in /etc/inetd.conf
1668 to start them. This is optional.
1670 inetd_enable="YES" # Run the network daemon dispatcher (YES/NO).
1671 inetd_program="/usr/sbin/inetd" # path to inetd, if you want a different one.
1672 inetd_flags="-wW" # Optional flags to inetd
1674 ----------------------------------------------------------------------
1678 For acquiring an IP address through DHCP, place this entry in
1679 /etc/rc.conf, using the appropriate card name. (ep0 is used as an example
1685 For a fixed IP, /etc/rc.conf requires a few more lines of data. (Again,
1686 ep0 is used as an example here.) Supply the correct local values for IP,
1687 netmask, and default router. The hostname should reflect what is entered
1688 in DNS for this computer.
1690 ifconfig_ep0="inet 123.234.345.456 netmask 255.255.255.0"
1691 hostname="myhostname"
1692 defaultrouter="654.543.432.321"
1695 ----------------------------------------------------------------------
1697 Chapter 3 UNIX Basics
1699 Rewritten by Chris Shumway.
1703 The following chapter will cover the basic commands and functionality of
1704 the DragonFly operating system. Much of this material is relevant for any
1705 UNIX-like operating system. Feel free to skim over this chapter if you are
1706 familiar with the material. If you are new to DragonFly, then you will
1707 definitely want to read through this chapter carefully.
1709 After reading this chapter, you will know:
1711 * How to use the ``virtual consoles'' of DragonFly.
1713 * How UNIX file permissions work along with understanding file flags in
1716 * The default DragonFly file system layout.
1718 * The DragonFly disk organization.
1720 * How to mount and unmount file systems.
1722 * What processes, daemons, and signals are.
1724 * What a shell is, and how to change your default login environment.
1726 * How to use basic text editors.
1728 * What devices and device nodes are.
1730 * What binary format is used under DragonFly.
1732 * How to read manual pages for more information.
1734 ----------------------------------------------------------------------
1736 3.2 Virtual Consoles and Terminals
1738 DragonFly can be used in various ways. One of them is typing commands to a
1739 text terminal. A lot of the flexibility and power of a UNIX operating
1740 system is readily available at your hands when using DragonFly this way.
1741 This section describes what ``terminals'' and ``consoles'' are, and how
1742 you can use them in DragonFly.
1744 ----------------------------------------------------------------------
1748 If you have not configured DragonFly to automatically start a graphical
1749 environment during startup, the system will present you with a login
1750 prompt after it boots, right after the startup scripts finish running. You
1751 will see something similar to:
1753 Additional ABI support:.
1754 Local package initialization:.
1755 Additional TCP options:.
1757 Fri Sep 20 13:01:06 EEST 2002
1759 DragonFlyBSD/i386 (pc3.example.org) (ttyv0)
1763 The messages might be a bit different on your system, but you will see
1764 something similar. The last two lines are what we are interested in right
1765 now. The second last line reads:
1767 DragonFlyBSD/i386 (pc3.example.org) (ttyv0)
1769 This line contains some bits of information about the system you have just
1770 booted. You are looking at a ``DragonFlyBSD'' console, running on an Intel
1771 or compatible processor of the x86 architecture[1]. The name of this
1772 machine (every UNIX machine has a name) is pc3.example.org, and you are
1773 now looking at its system console--the ttyv0 terminal.
1775 Finally, the last line is always:
1779 This is the part where you are supposed to type in your ``username'' to
1780 log into DragonFly. The next section describes how you can do this.
1782 ----------------------------------------------------------------------
1784 3.2.2 Logging into DragonFly
1786 DragonFly is a multiuser, multiprocessing system. This is the formal
1787 description that is usually given to a system that can be used by many
1788 different people, who simultaneously run a lot of programs on a single
1791 Every multiuser system needs some way to distinguish one ``user'' from the
1792 rest. In DragonFly (and all the UNIX-like operating systems), this is
1793 accomplished by requiring that every user must ``log into'' the system
1794 before being able to run programs. Every user has a unique name (the
1795 ``username'') and a personal, secret key (the ``password''). DragonFly
1796 will ask for these two before allowing a user to run any programs.
1798 Right after DragonFly boots and finishes running its startup scripts[2],
1799 it will present you with a prompt and ask for a valid username:
1803 For the sake of this example, let us assume that your username is john.
1804 Type john at this prompt and press Enter. You should then be presented
1805 with a prompt to enter a ``password'':
1810 Type in john's password now, and press Enter. The password is not echoed!
1811 You need not worry about this right now. Suffice it to say that it is done
1812 for security reasons.
1814 If you have typed your password correctly, you should by now be logged
1815 into DragonFly and ready to try out all the available commands.
1817 You should see the MOTD or message of the day followed by a command prompt
1818 (a #, $, or % character). This indicates you have successfully logged into
1821 ----------------------------------------------------------------------
1823 3.2.3 Multiple Consoles
1825 Running UNIX commands in one console is fine, but DragonFly can run many
1826 programs at once. Having one console where commands can be typed would be
1827 a bit of a waste when an operating system like DragonFly can run dozens of
1828 programs at the same time. This is where ``virtual consoles'' can be very
1831 DragonFly can be configured to present you with many different virtual
1832 consoles. You can switch from one of them to any other virtual console by
1833 pressing a couple of keys on your keyboard. Each console has its own
1834 different output channel, and DragonFly takes care of properly redirecting
1835 keyboard input and monitor output as you switch from one virtual console
1838 Special key combinations have been reserved by DragonFly for switching
1839 consoles[3]. You can use Alt-F1, Alt-F2, through Alt-F8 to switch to a
1840 different virtual console in DragonFly.
1842 As you are switching from one console to the next, DragonFly takes care of
1843 saving and restoring the screen output. The result is an ``illusion'' of
1844 having multiple ``virtual'' screens and keyboards that you can use to type
1845 commands for DragonFly to run. The programs that you launch on one virtual
1846 console do not stop running when that console is not visible. They
1847 continue running when you have switched to a different virtual console.
1849 ----------------------------------------------------------------------
1851 3.2.4 The /etc/ttys File
1853 The default configuration of DragonFly will start up with eight virtual
1854 consoles. This is not a hardwired setting though, and you can easily
1855 customize your installation to boot with more or fewer virtual consoles.
1856 The number and settings of the virtual consoles are configured in the
1859 You can use the /etc/ttys file to configure the virtual consoles of
1860 DragonFly. Each uncommented line in this file (lines that do not start
1861 with a # character) contains settings for a single terminal or virtual
1862 console. The default version of this file that ships with DragonFly
1863 configures nine virtual consoles, and enables eight of them. They are the
1864 lines that start with ttyv:
1866 # name getty type status comments
1868 ttyv0 "/usr/libexec/getty Pc" cons25 on secure
1870 ttyv1 "/usr/libexec/getty Pc" cons25 on secure
1871 ttyv2 "/usr/libexec/getty Pc" cons25 on secure
1872 ttyv3 "/usr/libexec/getty Pc" cons25 on secure
1873 ttyv4 "/usr/libexec/getty Pc" cons25 on secure
1874 ttyv5 "/usr/libexec/getty Pc" cons25 on secure
1875 ttyv6 "/usr/libexec/getty Pc" cons25 on secure
1876 ttyv7 "/usr/libexec/getty Pc" cons25 on secure
1877 ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure
1879 For a detailed description of every column in this file and all the
1880 options you can use to set things up for the virtual consoles, consult the
1881 ttys(5) manual page.
1883 ----------------------------------------------------------------------
1885 3.2.5 Single User Mode Console
1887 A detailed description of what ``single user mode'' is can be found in
1888 Section 7.5.2. It is worth noting that there is only one console when you
1889 are running DragonFly in single user mode. There are no virtual consoles
1890 available. The settings of the single user mode console can also be found
1891 in the /etc/ttys file. Look for the line that starts with console:
1893 # name getty type status comments
1895 # If console is marked "insecure", then init will ask for the root password
1896 # when going to single-user mode.
1897 console none unknown off secure
1899 Note: As the comments above the console line indicate, you can edit this
1900 line and change secure to insecure. If you do that, when DragonFly boots
1901 into single user mode, it will still ask for the root password.
1903 Be careful when changing this to insecure. If you ever forget the root
1904 password, booting into single user mode is a bit involved. It is still
1905 possible, but it might be a bit hard for someone who is not very
1906 comfortable with the DragonFly booting process and the programs
1909 ----------------------------------------------------------------------
1913 DragonFly, being a direct descendant of BSD UNIX, is based on several key
1914 UNIX concepts. The first and most pronounced is that DragonFly is a
1915 multi-user operating system. The system can handle several users all
1916 working simultaneously on completely unrelated tasks. The system is
1917 responsible for properly sharing and managing requests for hardware
1918 devices, peripherals, memory, and CPU time fairly to each user.
1920 Because the system is capable of supporting multiple users, everything the
1921 system manages has a set of permissions governing who can read, write, and
1922 execute the resource. These permissions are stored as three octets broken
1923 into three pieces, one for the owner of the file, one for the group that
1924 the file belongs to, and one for everyone else. This numerical
1925 representation works like this:
1927 Value Permission Directory Listing
1928 0 No read, no write, no execute ---
1929 1 No read, no write, execute --x
1930 2 No read, write, no execute -w-
1931 3 No read, write, execute -wx
1932 4 Read, no write, no execute r--
1933 5 Read, no write, execute r-x
1934 6 Read, write, no execute rw-
1935 7 Read, write, execute rwx
1937 You can use the -l command line argument to ls(1) to view a long directory
1938 listing that includes a column with information about a file's permissions
1939 for the owner, group, and everyone else. For example, a ls -l in an
1940 arbitrary directory may show:
1944 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
1945 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
1946 -rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt
1949 Here is how the first column of ls -l is broken up:
1953 The first (leftmost) character tells if this file is a regular file, a
1954 directory, a special character device, a socket, or any other special
1955 pseudo-file device. In this case, the - indicates a regular file. The next
1956 three characters, rw- in this example, give the permissions for the owner
1957 of the file. The next three characters, r--, give the permissions for the
1958 group that the file belongs to. The final three characters, r--, give the
1959 permissions for the rest of the world. A dash means that the permission is
1960 turned off. In the case of this file, the permissions are set so the owner
1961 can read and write to the file, the group can read the file, and the rest
1962 of the world can only read the file. According to the table above, the
1963 permissions for this file would be 644, where each digit represents the
1964 three parts of the file's permission.
1966 This is all well and good, but how does the system control permissions on
1967 devices? DragonFly actually treats most hardware devices as a file that
1968 programs can open, read, and write data to just like any other file. These
1969 special device files are stored on the /dev directory.
1971 Directories are also treated as files. They have read, write, and execute
1972 permissions. The executable bit for a directory has a slightly different
1973 meaning than that of files. When a directory is marked executable, it
1974 means it can be traversed into, that is, it is possible to ``cd'' (change
1975 directory) into it. This also means that within the directory it is
1976 possible to access files whose names are known (subject, of course, to the
1977 permissions on the files themselves).
1979 In particular, in order to perform a directory listing, read permission
1980 must be set on the directory, whilst to delete a file that one knows the
1981 name of, it is necessary to have write and execute permissions to the
1982 directory containing the file.
1984 There are more permission bits, but they are primarily used in special
1985 circumstances such as setuid binaries and sticky directories. If you want
1986 more information on file permissions and how to set them, be sure to look
1987 at the chmod(1) manual page.
1989 ----------------------------------------------------------------------
1991 3.3.1 Symbolic Permissions
1993 Contributed by Tom Rhodes.
1995 Symbolic permissions, sometimes referred to as symbolic expressions, use
1996 characters in place of octal values to assign permissions to files or
1997 directories. Symbolic expressions use the syntax of (who) (action)
1998 (permissions), where the following values are available:
2000 Option Letter Represents
2004 (who) a All (``world'')
2005 (action) + Adding permissions
2006 (action) - Removing permissions
2007 (action) = Explicitly set permissions
2008 (permissions) r Read
2009 (permissions) w Write
2010 (permissions) x Execute
2011 (permissions) t Sticky bit
2012 (permissions) s Set UID or GID
2014 These values are used with the chmod(1) command just like before, but with
2015 letters. For an example, you could use the following command to block
2016 other users from accessing FILE:
2020 A comma separated list can be provided when more than one set of changes
2021 to a file must be made. For example the following command will remove the
2022 groups and ``world'' write permission on FILE, then it adds the execute
2023 permissions for everyone:
2025 % chmod go-w,a+x FILE
2027 ----------------------------------------------------------------------
2029 3.3.2 DragonFly File Flags
2031 Contributed by Tom Rhodes.
2033 In addition to file permissions discussed previously, DragonFly supports
2034 the use of ``file flags.'' These flags add an additional level of security
2035 and control over files, but not directories.
2037 These file flags add an additional level of control over files, helping to
2038 ensure that in some cases not even the root can remove or alter files.
2040 File flags are altered by using the chflags(1) utility, using a simple
2041 interface. For example, to enable the system undeletable flag on the file
2042 file1, issue the following command:
2047 And to disable the system undeletable flag, simply issue the previous
2048 command with ``no'' in front of the sunlink. Observe:
2053 To view the flags of this file, use the ls(1) with the -lo flags:
2058 The output should look like the following:
2060 -rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54
2063 Several flags may only added or removed to files by the root user. In
2064 other cases, the file owner may set these flags. It is recommended an
2065 administrator read over the chflags(1) and chflags(2) manual pages for
2068 ----------------------------------------------------------------------
2070 3.4 Directory Structure
2072 The DragonFly directory hierarchy is fundamental to obtaining an overall
2073 understanding of the system. The most important concept to grasp is that
2074 of the root directory, ``/''. This directory is the first one mounted at
2075 boot time and it contains the base system necessary to prepare the
2076 operating system for multi-user operation. The root directory also
2077 contains mount points for every other file system that you may want to
2080 A mount point is a directory where additional file systems can be grafted
2081 onto the root file system. This is further described in Section 3.5.
2082 Standard mount points include /usr, /var, /tmp, /mnt, and /cdrom. These
2083 directories are usually referenced to entries in the file /etc/fstab.
2084 /etc/fstab is a table of various file systems and mount points for
2085 reference by the system. Most of the file systems in /etc/fstab are
2086 mounted automatically at boot time from the script rc(8) unless they
2087 contain the noauto option. Details can be found in Section 3.6.1.
2089 A complete description of the file system hierarchy is available in
2090 hier(7). For now, a brief overview of the most common directories will
2093 Directory Description
2094 / Root directory of the file system.
2095 /bin/ User utilities fundamental to both single-user and
2096 multi-user environments.
2097 /boot/ Programs and configuration files used during operating
2099 /boot/defaults/ Default bootstrapping configuration files; see
2101 /dev/ Device nodes; see intro(4).
2102 /etc/ System configuration files and scripts.
2103 /etc/defaults/ Default system configuration files; see rc(8).
2104 /etc/mail/ Configuration files for mail transport agents such as
2106 /etc/namedb/ named configuration files; see named(8).
2107 /etc/periodic/ Scripts that are run daily, weekly, and monthly, via
2108 cron(8); see periodic(8).
2109 /etc/ppp/ ppp configuration files; see ppp(8).
2110 /mnt/ Empty directory commonly used by system administrators as
2111 a temporary mount point.
2112 /proc/ Process file system; see procfs(5), mount_procfs(8).
2113 /root/ Home directory for the root account.
2114 /sbin/ System programs and administration utilities fundamental
2115 to both single-user and multi-user environments.
2116 /stand/ Programs used in a standalone environment.
2117 Temporary files. The contents of /tmp are usually NOT
2118 /tmp/ preserved across a system reboot. A memory-based file
2119 system is often mounted at /tmp. This can be automated
2120 with an entry in /etc/fstab; see mfs(8).
2121 /usr/ The majority of user utilities and applications.
2122 /usr/bin/ Common utilities, programming tools, and applications.
2123 /usr/include/ Standard C include files.
2124 /usr/lib/ Archive libraries.
2125 /usr/libdata/ Miscellaneous utility data files.
2126 /usr/libexec/ System daemons & system utilities (executed by other
2128 Local executables, libraries, etc. Within /usr/local, the
2129 general layout sketched out by hier(7) for /usr should be
2130 /usr/local/ used. An exceptions is the man directory, which is
2131 directly under /usr/local rather than under
2133 /usr/obj/ Architecture-specific target tree produced by building the
2135 Used as the default destination for the files installed
2136 /usr/pkg via the pkgsrc framework or pkgsrc packages (optional).
2137 The configuration directory is tunable, but the default
2138 location is /usr/pkg/etc.
2139 /usr/pkgsrc The pkgsrc collection for installing packages (optional).
2140 /usr/sbin/ System daemons & system utilities (executed by users).
2141 /usr/share/ Architecture-independent files.
2142 /usr/src/ BSD and/or local source files.
2143 /usr/X11R6/ X11R6 distribution executables, libraries, etc (optional).
2144 Multi-purpose log, temporary, transient, and spool files.
2145 /var/ A memory-based file system is sometimes mounted at /var.
2146 This can be automated with an entry in /etc/fstab; see
2148 /var/log/ Miscellaneous system log files.
2149 /var/mail/ User mailbox files.
2150 /var/spool/ Miscellaneous printer and mail system spooling
2152 /var/tmp/ Temporary files. The files are usually preserved across a
2153 system reboot, unless /var is a memory-based file system.
2156 ----------------------------------------------------------------------
2158 3.5 Disk Organization
2160 The smallest unit of organization that DragonFly uses to find files is the
2161 filename. Filenames are case-sensitive, which means that readme.txt and
2162 README.TXT are two separate files. DragonFly does not use the extension
2163 (.txt) of a file to determine whether the file is a program, or a
2164 document, or some other form of data.
2166 Files are stored in directories. A directory may contain no files, or it
2167 may contain many hundreds of files. A directory can also contain other
2168 directories, allowing you to build up a hierarchy of directories within
2169 one another. This makes it much easier to organize your data.
2171 Files and directories are referenced by giving the file or directory name,
2172 followed by a forward slash, /, followed by any other directory names that
2173 are necessary. If you have directory foo, which contains directory bar,
2174 which contains the file readme.txt, then the full name, or path to the
2175 file is foo/bar/readme.txt.
2177 Directories and files are stored in a file system. Each file system
2178 contains exactly one directory at the very top level, called the root
2179 directory for that file system. This root directory can then contain other
2182 So far this is probably similar to any other operating system you may have
2183 used. There are a few differences; for example, MS-DOS uses \ to separate
2184 file and directory names, while Mac OS(R) uses :.
2186 DragonFly does not use drive letters, or other drive names in the path.
2187 You would not write c:/foo/bar/readme.txt on DragonFly.
2189 Instead, one file system is designated the root file system. The root file
2190 system's root directory is referred to as /. Every other file system is
2191 then mounted under the root file system. No matter how many disks you have
2192 on your DragonFly system, every directory appears to be part of the same
2195 Suppose you have three file systems, called A, B, and C. Each file system
2196 has one root directory, which contains two other directories, called A1,
2197 A2 (and likewise B1, B2 and C1, C2).
2199 Call A the root file system. If you used the ls command to view the
2200 contents of this directory you would see two subdirectories, A1 and A2.
2201 The directory tree looks like this:
2209 A file system must be mounted on to a directory in another file system. So
2210 now suppose that you mount file system B on to the directory A1. The root
2211 directory of B replaces A1, and the directories in B appear accordingly:
2223 Any files that are in the B1 or B2 directories can be reached with the
2224 path /A1/B1 or /A1/B2 as necessary. Any files that were in /A1 have been
2225 temporarily hidden. They will reappear if B is unmounted from A.
2227 If B had been mounted on A2 then the diagram would look like this:
2239 and the paths would be /A2/B1 and /A2/B2 respectively.
2241 File systems can be mounted on top of one another. Continuing the last
2242 example, the C file system could be mounted on top of the B1 directory in
2243 the B file system, leading to this arrangement:
2259 Or C could be mounted directly on to the A file system, under the A1
2276 If you are familiar with MS-DOS, this is similar, although not identical,
2277 to the join command.
2279 This is not normally something you need to concern yourself with.
2280 Typically you create file systems when installing DragonFly and decide
2281 where to mount them, and then never change them unless you add a new disk.
2283 It is entirely possible to have one large root file system, and not need
2284 to create any others. There are some drawbacks to this approach, and one
2287 Benefits of Multiple File Systems
2289 * Different file systems can have different mount options. For example,
2290 with careful planning, the root file system can be mounted read-only,
2291 making it impossible for you to inadvertently delete or edit a
2292 critical file. Separating user-writable file systems, such as /home,
2293 from other file systems also allows them to be mounted nosuid; this
2294 option prevents the suid/guid bits on executables stored on the file
2295 system from taking effect, possibly improving security.
2297 * DragonFly automatically optimizes the layout of files on a file
2298 system, depending on how the file system is being used. So a file
2299 system that contains many small files that are written frequently will
2300 have a different optimization to one that contains fewer, larger
2301 files. By having one big file system this optimization breaks down.
2303 * DragonFly's file systems are very robust should you lose power.
2304 However, a power loss at a critical point could still damage the
2305 structure of the file system. By splitting your data over multiple
2306 file systems it is more likely that the system will still come up,
2307 making it easier for you to restore from backup as necessary.
2309 Benefit of a Single File System
2311 * File systems are a fixed size. If you create a file system when you
2312 install DragonFly and give it a specific size, you may later discover
2313 that you need to make the partition bigger. The growfs(8) command
2314 makes it possible to increase the size of a file system on the fly.
2316 File systems are contained in partitions. This does not have the same
2317 meaning as the common usage of the term partition (for example, MS-DOS
2318 partition), because of DragonFly's UNIX heritage. Each partition is
2319 identified by a letter from a through to h. Each partition can contain
2320 only one file system, which means that file systems are often described by
2321 either their typical mount point in the file system hierarchy, or the
2322 letter of the partition they are contained in.
2324 DragonFly also uses disk space for swap space. Swap space provides
2325 DragonFly with virtual memory. This allows your computer to behave as
2326 though it has much more memory than it actually does. When DragonFly runs
2327 out of memory it moves some of the data that is not currently being used
2328 to the swap space, and moves it back in (moving something else out) when
2331 Some partitions have certain conventions associated with them.
2333 Partition Convention
2334 a Normally contains the root file system
2335 b Normally contains swap space
2336 Normally the same size as the enclosing slice. This allows
2337 c utilities that need to work on the entire slice (for example, a
2338 bad block scanner) to work on the c partition. You would not
2339 normally create a file system on this partition.
2340 Partition d used to have a special meaning associated with it,
2341 d although that is now gone. To this day, some tools may operate
2342 oddly if told to work on partition d.
2344 Each partition-that-contains-a-file-system is stored in what DragonFly
2345 calls a slice. Slice is DragonFly's term for what the common call
2346 partitions, and again, this is because of DragonFly's UNIX background.
2347 Slices are numbered, starting at 1, through to 4.
2349 Slice numbers follow the device name, prefixed with an s, starting at 1.
2350 So ``da0s1'' is the first slice on the first SCSI drive. There can only be
2351 four physical slices on a disk, but you can have logical slices inside
2352 physical slices of the appropriate type. These extended slices are
2353 numbered starting at 5, so ``ad0s5'' is the first extended slice on the
2354 first IDE disk. These devices are used by file systems that expect to
2357 Slices, ``dangerously dedicated'' physical drives, and other drives
2358 contain partitions, which are represented as letters from a to h. This
2359 letter is appended to the device name, so ``da0a'' is the a partition on
2360 the first da drive, which is ``dangerously dedicated''. ``ad1s3e'' is the
2361 fifth partition in the third slice of the second IDE disk drive.
2363 Finally, each disk on the system is identified. A disk name starts with a
2364 code that indicates the type of disk, and then a number, indicating which
2365 disk it is. Unlike slices, disk numbering starts at 0. Common codes that
2366 you will see are listed in Table 3-1.
2368 When referring to a partition DragonFly requires that you also name the
2369 slice and disk that contains the partition, and when referring to a slice
2370 you should also refer to the disk name. Do this by listing the disk name,
2371 s, the slice number, and then the partition letter. Examples are shown in
2374 Example 3-2 shows a conceptual model of the disk layout that should help
2375 make things clearer.
2377 In order to install DragonFly you must first configure the disk slices,
2378 then create partitions within the slice you will use for DragonFly, and
2379 then create a file system (or swap space) in each partition, and decide
2380 where that file system will be mounted.
2382 Table 3-1. Disk Device Codes
2386 da SCSI direct access disk
2387 acd ATAPI (IDE) CDROM
2391 Example 3-1. Sample Disk, Slice, and Partition Names
2394 ad0s1a The first partition (a) on the first slice (s1) on the first IDE
2396 da1s2e The fifth partition (e) on the second slice (s2) on the second SCSI
2399 Example 3-2. Conceptual Model of a Disk
2401 This diagram shows DragonFly's view of the first IDE disk attached to the
2402 system. Assume that the disk is 4 GB in size, and contains two 2 GB slices
2403 (MS-DOS partitions). The first slice contains a MS-DOS disk, C:, and the
2404 second slice contains a DragonFly installation. This example DragonFly
2405 installation has three partitions, and a swap partition.
2407 The three partitions will each hold a file system. Partition a will be
2408 used for the root file system, e for the /var directory hierarchy, and f
2409 for the /usr directory hierarchy.
2411 .-----------------. --.
2414 : : > First slice, ad0s1
2417 :=================: ==: --.
2418 | | | Partition a, mounted as / |
2419 | | > referred to as ad0s2a |
2421 :-----------------: ==: |
2422 | | | Partition b, used as swap |
2423 | | > referred to as ad0s2b |
2425 :-----------------: ==: | Partition c, no
2426 | | | Partition e, used as /var > file system, all
2427 | | > referred to as ad0s2e | of DragonFly slice,
2429 :-----------------: ==: |
2431 : : | Partition f, used as /usr |
2432 : : > referred to as ad0s2f |
2436 `-----------------' --'
2438 ----------------------------------------------------------------------
2440 3.6 Mounting and Unmounting File Systems
2442 The file system is best visualized as a tree, rooted, as it were, at /.
2443 /dev, /usr, and the other directories in the root directory are branches,
2444 which may have their own branches, such as /usr/local, and so on.
2446 There are various reasons to house some of these directories on separate
2447 file systems. /var contains the directories log/, spool/, and various
2448 types of temporary files, and as such, may get filled up. Filling up the
2449 root file system is not a good idea, so splitting /var from / is often
2452 Another common reason to contain certain directory trees on other file
2453 systems is if they are to be housed on separate physical disks, or are
2454 separate virtual disks, such as Network File System mounts, or CDROM
2457 ----------------------------------------------------------------------
2459 3.6.1 The fstab File
2461 During the boot process, file systems listed in /etc/fstab are
2462 automatically mounted (unless they are listed with the noauto option).
2464 The /etc/fstab file contains a list of lines of the following format:
2466 device /mount-point fstype options dumpfreq passno
2470 A device name (which should exist), as explained in Section 12.2.
2474 A directory (which should exist), on which to mount the file
2479 The file system type to pass to mount(8). The default DragonFly
2484 Either rw for read-write file systems, or ro for read-only file
2485 systems, followed by any other options that may be needed. A
2486 common option is noauto for file systems not normally mounted
2487 during the boot sequence. Other options are listed in the mount(8)
2492 This is used by dump(8) to determine which file systems require
2493 dumping. If the field is missing, a value of zero is assumed.
2497 This determines the order in which file systems should be checked.
2498 File systems that should be skipped should have their passno set
2499 to zero. The root file system (which needs to be checked before
2500 everything else) should have its passno set to one, and other file
2501 systems' passno should be set to values greater than one. If more
2502 than one file systems have the same passno then fsck(8) will
2503 attempt to check file systems in parallel if possible.
2505 Consult the fstab(5) manual page for more information on the format of the
2506 /etc/fstab file and the options it contains.
2508 ----------------------------------------------------------------------
2510 3.6.2 The mount Command
2512 The mount(8) command is what is ultimately used to mount file systems.
2514 In its most basic form, you use:
2516 # mount device mountpoint
2518 There are plenty of options, as mentioned in the mount(8) manual page, but
2519 the most common are:
2525 Mount all the file systems listed in /etc/fstab. Except those
2526 marked as ``noauto'', excluded by the -t flag, or those that are
2531 Do everything except for the actual mount system call. This option
2532 is useful in conjunction with the -v flag to determine what
2533 mount(8) is actually trying to do.
2537 Force the mount of an unclean file system (dangerous), or forces
2538 the revocation of write access when downgrading a file system's
2539 mount status from read-write to read-only.
2543 Mount the file system read-only. This is identical to using the
2544 rdonly argument to the -o option.
2548 Mount the given file system as the given file system type, or
2549 mount only file systems of the given type, if given the -a option.
2551 ``ufs'' is the default file system type.
2555 Update mount options on the file system.
2563 Mount the file system read-write.
2565 The -o option takes a comma-separated list of the options, including the
2570 Do not interpret special devices on the file system. This is a
2571 useful security option.
2575 Do not allow execution of binaries on this file system. This is
2576 also a useful security option.
2580 Do not interpret setuid or setgid flags on the file system. This
2581 is also a useful security option.
2583 ----------------------------------------------------------------------
2585 3.6.3 The umount Command
2587 The umount(8) command takes, as a parameter, one of a mountpoint, a device
2588 name, or the -a or -A option.
2590 All forms take -f to force unmounting, and -v for verbosity. Be warned
2591 that -f is not generally a good idea. Forcibly unmounting file systems
2592 might crash the computer or damage data on the file system.
2594 -a and -A are used to unmount all mounted file systems, possibly modified
2595 by the file system types listed after -t. -A, however, does not attempt to
2596 unmount the root file system.
2598 ----------------------------------------------------------------------
2602 DragonFly is a multi-tasking operating system. This means that it seems as
2603 though more than one program is running at once. Each program running at
2604 any one time is called a process. Every command you run will start at
2605 least one new process, and there are a number of system processes that run
2606 all the time, keeping the system functional.
2608 Each process is uniquely identified by a number called a process ID, or
2609 PID, and, like files, each process also has one owner and group. The owner
2610 and group information is used to determine what files and devices the
2611 process can open, using the file permissions discussed earlier. Most
2612 processes also have a parent process. The parent process is the process
2613 that started them. For example, if you are typing commands to the shell
2614 then the shell is a process, and any commands you run are also processes.
2615 Each process you run in this way will have your shell as its parent
2616 process. The exception to this is a special process called init(8). init
2617 is always the first process, so its PID is always 1. init is started
2618 automatically by the kernel when DragonFly starts.
2620 Two commands are particularly useful to see the processes on the system,
2621 ps(1) and top(1). The ps command is used to show a static list of the
2622 currently running processes, and can show their PID, how much memory they
2623 are using, the command line they were started with, and so on. The top
2624 command displays all the running processes, and updates the display every
2625 few seconds, so that you can interactively see what your computer is
2628 By default, ps only shows you the commands that are running and are owned
2629 by you. For example:
2632 PID TT STAT TIME COMMAND
2633 298 p0 Ss 0:01.10 tcsh
2634 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
2635 37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
2636 48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
2637 48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
2638 72210 p0 R+ 0:00.00 ps
2639 390 p1 Is 0:01.14 tcsh
2640 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
2641 6688 p3 IWs 0:00.00 tcsh
2642 10735 p4 IWs 0:00.00 tcsh
2643 20256 p5 IWs 0:00.00 tcsh
2644 262 v0 IWs 0:00.00 -tcsh (tcsh)
2645 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
2646 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
2647 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
2648 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish
2650 As you can see in this example, the output from ps(1) is organized into a
2651 number of columns. PID is the process ID discussed earlier. PIDs are
2652 assigned starting from 1, go up to 99999, and wrap around back to the
2653 beginning when you run out. The TT column shows the tty the program is
2654 running on, and can safely be ignored for the moment. STAT shows the
2655 program's state, and again, can be safely ignored. TIME is the amount of
2656 time the program has been running on the CPU--this is usually not the
2657 elapsed time since you started the program, as most programs spend a lot
2658 of time waiting for things to happen before they need to spend time on the
2659 CPU. Finally, COMMAND is the command line that was used to run the
2662 ps(1) supports a number of different options to change the information
2663 that is displayed. One of the most useful sets is auxww. a displays
2664 information about all the running processes, not just your own. u displays
2665 the username of the process' owner, as well as memory usage. x displays
2666 information about daemon processes, and ww causes ps(1) to display the
2667 full command line, rather than truncating it once it gets too long to fit
2670 The output from top(1) is similar. A sample session looks like this:
2673 last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
2674 47 processes: 1 running, 46 sleeping
2675 CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
2676 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
2677 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
2679 PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
2680 72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
2681 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
2682 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
2683 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
2684 48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
2685 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
2686 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
2689 The output is split into two sections. The header (the first five lines)
2690 shows the PID of the last process to run, the system load averages (which
2691 are a measure of how busy the system is), the system uptime (time since
2692 the last reboot) and the current time. The other figures in the header
2693 relate to how many processes are running (47 in this case), how much
2694 memory and swap space has been taken up, and how much time the system is
2695 spending in different CPU states.
2697 Below that are a series of columns containing similar information to the
2698 output from ps(1). As before you can see the PID, the username, the amount
2699 of CPU time taken, and the command that was run. top(1) also defaults to
2700 showing you the amount of memory space taken by the process. This is split
2701 into two columns, one for total size, and one for resident size--total
2702 size is how much memory the application has needed, and the resident size
2703 is how much it is actually using at the moment. In this example you can
2704 see that Netscape(R) has required almost 30 MB of RAM, but is currently
2707 top(1) automatically updates this display every two seconds; this can be
2708 changed with the s option.
2710 ----------------------------------------------------------------------
2712 3.8 Daemons, Signals, and Killing Processes
2714 When you run an editor it is easy to control the editor, tell it to load
2715 files, and so on. You can do this because the editor provides facilities
2716 to do so, and because the editor is attached to a terminal. Some programs
2717 are not designed to be run with continuous user input, and so they
2718 disconnect from the terminal at the first opportunity. For example, a web
2719 server spends all day responding to web requests, it normally does not
2720 need any input from you. Programs that transport email from site to site
2721 are another example of this class of application.
2723 We call these programs daemons. Daemons were characters in Greek
2724 mythology; neither good or evil, they were little attendant spirits that,
2725 by and large, did useful things for mankind. Much like the web servers and
2726 mail servers of today do useful things. This is why the mascot for a
2727 number of BSD-based operating systems has, for a long time, been a
2728 cheerful looking daemon with sneakers and a pitchfork.
2730 There is a convention to name programs that normally run as daemons with a
2731 trailing ``d''. BIND is the Berkeley Internet Name Daemon (and the actual
2732 program that executes is called named), the Apache web server program is
2733 called httpd, the line printer spooling daemon is lpd and so on. This is a
2734 convention, not a hard and fast rule; for example, the main mail daemon
2735 for the Sendmail application is called sendmail, and not maild, as you
2738 Sometimes you will need to communicate with a daemon process. These
2739 communications are called signals, and you can communicate with a daemon
2740 (or with any other running process) by sending it a signal. There are a
2741 number of different signals that you can send--some of them have a
2742 specific meaning, others are interpreted by the application, and the
2743 application's documentation will tell you how that application interprets
2744 signals. You can only send a signal to a process that you own. If you send
2745 a signal to someone else's process with kill(1) or kill(2) permission will
2746 be denied. The exception to this is the root user, who can send signals to
2747 everyone's processes.
2749 DragonFly will also send applications signals in some cases. If an
2750 application is badly written, and tries to access memory that it is not
2751 supposed to, DragonFly sends the process the Segmentation Violation signal
2752 (SIGSEGV). If an application has used the alarm(3) system call to be
2753 alerted after a period of time has elapsed then it will be sent the Alarm
2754 signal (SIGALRM), and so on.
2756 Two signals can be used to stop a process, SIGTERM and SIGKILL. SIGTERM is
2757 the polite way to kill a process; the process can catch the signal,
2758 realize that you want it to shut down, close any log files it may have
2759 open, and generally finish whatever it is doing at the time before
2760 shutting down. In some cases a process may even ignore SIGTERM if it is in
2761 the middle of some task that can not be interrupted.
2763 SIGKILL can not be ignored by a process. This is the ``I do not care what
2764 you are doing, stop right now'' signal. If you send SIGKILL to a process
2765 then DragonFly will stop that process there and then[4].
2767 The other signals you might want to use are SIGHUP, SIGUSR1, and SIGUSR2.
2768 These are general purpose signals, and different applications will do
2769 different things when they are sent.
2771 Suppose that you have changed your web server's configuration file--you
2772 would like to tell the web server to re-read its configuration. You could
2773 stop and restart httpd, but this would result in a brief outage period on
2774 your web server, which may be undesirable. Most daemons are written to
2775 respond to the SIGHUP signal by re-reading their configuration file. So
2776 instead of killing and restarting httpd you would send it the SIGHUP
2777 signal. Because there is no standard way to respond to these signals,
2778 different daemons will have different behavior, so be sure and read the
2779 documentation for the daemon in question.
2781 Signals are sent using the kill(1) command, as this example shows.
2783 Sending a Signal to a Process
2785 This example shows how to send a signal to inetd(8). The inetd
2786 configuration file is /etc/inetd.conf, and inetd will re-read this
2787 configuration file when it is sent SIGHUP.
2789 1. Find the process ID of the process you want to send the signal to. Do
2790 this using ps(1) and grep(1). The grep(1) command is used to search
2791 through output, looking for the string you specify. This command is
2792 run as a normal user, and inetd(8) is run as root, so the ax options
2793 must be given to ps(1).
2795 % ps -ax | grep inetd
2796 198 ?? IWs 0:00.00 inetd -wW
2798 So the inetd(8) PID is 198. In some cases the grep inetd command might
2799 also occur in this output. This is because of the way ps(1) has to
2800 find the list of running processes.
2802 2. Use kill(1) to send the signal. Because inetd(8) is being run by root
2803 you must use su(1) to become root first.
2807 # /bin/kill -s HUP 198
2809 In common with most UNIX commands, kill(1) will not print any output
2810 if it is successful. If you send a signal to a process that you do not
2811 own then you will see ``kill: PID: Operation not permitted''. If you
2812 mistype the PID you will either send the signal to the wrong process,
2813 which could be bad, or, if you are lucky, you will have sent the
2814 signal to a PID that is not currently in use, and you will see ``kill:
2815 PID: No such process''.
2817 Why Use /bin/kill?: Many shells provide the kill command as a built
2818 in command; that is, the shell will send the signal directly, rather
2819 than running /bin/kill. This can be very useful, but different
2820 shells have a different syntax for specifying the name of the signal
2821 to send. Rather than try to learn all of them, it can be simpler
2822 just to use the /bin/kill ... command directly.
2824 Sending other signals is very similar, just substitute TERM or KILL in the
2825 command line as necessary.
2827 Important: Killing random process on the system can be a bad idea. In
2828 particular, init(8), process ID 1, is very special. Running /bin/kill -s
2829 KILL 1 is a quick way to shutdown your system. Always double check the
2830 arguments you run kill(1) with before you press Return.
2832 ----------------------------------------------------------------------
2836 In DragonFly, a lot of everyday work is done in a command line interface
2837 called a shell. A shell's main job is to take commands from the input
2838 channel and execute them. A lot of shells also have built in functions to
2839 help everyday tasks such as file management, file globbing, command line
2840 editing, command macros, and environment variables. DragonFly comes with a
2841 set of shells, such as sh, the Bourne Shell, and tcsh, the improved
2842 C-shell. Many other shells are available from pkgsrc, such as zsh and
2845 Which shell do you use? It is really a matter of taste. If you are a C
2846 programmer you might feel more comfortable with a C-like shell such as
2847 tcsh. If you have come from Linux or are new to a UNIX command line
2848 interface you might try bash. The point is that each shell has unique
2849 properties that may or may not work with your preferred working
2850 environment, and that you have a choice of what shell to use.
2852 One common feature in a shell is filename completion. Given the typing of
2853 the first few letters of a command or filename, you can usually have the
2854 shell automatically complete the rest of the command or filename by
2855 hitting the Tab key on the keyboard. Here is an example. Suppose you have
2856 two files called foobar and foo.bar. You want to delete foo.bar. So what
2857 you would type on the keyboard is: rm fo[Tab].[Tab].
2859 The shell would print out rm foo[BEEP].bar.
2861 The [BEEP] is the console bell, which is the shell telling me it was
2862 unable to totally complete the filename because there is more than one
2863 match. Both foobar and foo.bar start with fo, but it was able to complete
2864 to foo. If you type in ., then hit Tab again, the shell would be able to
2865 fill in the rest of the filename for you.
2867 Another feature of the shell is the use of environment variables.
2868 Environment variables are a variable key pair stored in the shell's
2869 environment space. This space can be read by any program invoked by the
2870 shell, and thus contains a lot of program configuration. Here is a list of
2871 common environment variables and what they mean:
2873 Variable Description
2874 USER Current logged in user's name.
2875 PATH Colon separated list of directories to search for binaries.
2876 DISPLAY Network name of the X11 display to connect to, if available.
2877 SHELL The current shell.
2878 TERM The name of the user's terminal. Used to determine the
2879 capabilities of the terminal.
2880 TERMCAP Database entry of the terminal escape codes to perform various
2882 OSTYPE Type of operating system. e.g., DragonFly.
2883 MACHTYPE The CPU architecture that the system is running on.
2884 EDITOR The user's preferred text editor.
2885 PAGER The user's preferred text pager.
2886 MANPATH Colon separated list of directories to search for manual pages.
2888 Setting an environment variable differs somewhat from shell to shell. For
2889 example, in the C-Style shells such as tcsh and csh, you would use setenv
2890 to set environment variables. Under Bourne shells such as sh and bash, you
2891 would use export to set your current environment variables. For example,
2892 to set or modify the EDITOR environment variable, under csh or tcsh a
2893 command like this would set EDITOR to /usr/local/bin/emacs:
2895 % setenv EDITOR /usr/local/bin/emacs
2897 Under Bourne shells:
2899 % export EDITOR="/usr/local/bin/emacs"
2901 You can also make most shells expand the environment variable by placing a
2902 $ character in front of it on the command line. For example, echo $TERM
2903 would print out whatever $TERM is set to, because the shell expands $TERM
2904 and passes it on to echo.
2906 Shells treat a lot of special characters, called meta-characters as
2907 special representations of data. The most common one is the * character,
2908 which represents any number of characters in a filename. These special
2909 meta-characters can be used to do filename globbing. For example, typing
2910 in echo * is almost the same as typing in ls because the shell takes all
2911 the files that match * and puts them on the command line for echo to see.
2913 To prevent the shell from interpreting these special characters, they can
2914 be escaped from the shell by putting a backslash (\) character in front of
2915 them. echo $TERM prints whatever your terminal is set to. echo \$TERM
2918 ----------------------------------------------------------------------
2920 3.9.1 Changing Your Shell
2922 The easiest way to change your shell is to use the chsh command. Running
2923 chsh will place you into the editor that is in your EDITOR environment
2924 variable; if it is not set, you will be placed in vi. Change the
2925 ``Shell:'' line accordingly.
2927 You can also give chsh the -s option; this will set your shell for you,
2928 without requiring you to enter an editor. For example, if you wanted to
2929 change your shell to bash, the following should do the trick:
2931 % chsh -s /usr/local/bin/bash
2933 Note: The shell that you wish to use must be present in the /etc/shells
2934 file. If you have installed a shell from the pkgsrc collection, then
2935 this should have been done for you already. If you installed the shell
2936 by hand, you must do this.
2938 For example, if you installed bash by hand and placed it into
2939 /usr/local/bin, you would want to:
2941 # echo "/usr/local/bin/bash" >> /etc/shells
2945 ----------------------------------------------------------------------
2949 A lot of configuration in DragonFly is done by editing text files. Because
2950 of this, it would be a good idea to become familiar with a text editor.
2951 DragonFly comes with a few as part of the base system, and many more are
2952 available in the pkgsrc collections.
2954 The easiest and simplest editor to learn is an editor called ee, which
2955 stands for easy editor. To start ee, one would type at the command line ee
2956 filename where filename is the name of the file to be edited. For example,
2957 to edit /etc/rc.conf, type in ee /etc/rc.conf. Once inside of ee, all of
2958 the commands for manipulating the editor's functions are listed at the top
2959 of the display. The caret ^ character represents the Ctrl key on the
2960 keyboard, so ^e expands to the key combination Ctrl+e. To leave ee, hit
2961 the Esc key, then choose leave editor. The editor will prompt you to save
2962 any changes if the file has been modified.
2964 DragonFly also comes with more powerful text editors such as vi as part of
2965 the base system, while other editors, like emacs and vim, are part of the
2966 pkgsrc collection. These editors offer much more functionality and power
2967 at the expense of being a little more complicated to learn. However if you
2968 plan on doing a lot of text editing, learning a more powerful editor such
2969 as vim or emacs will save you much more time in the long run.
2971 ----------------------------------------------------------------------
2973 3.11 Devices and Device Nodes
2975 A device is a term used mostly for hardware-related activities in a
2976 system, including disks, printers, graphics cards, and keyboards. When
2977 DragonFly boots, the majority of what DragonFly displays are devices being
2978 detected. You can look through the boot messages again by viewing
2979 /var/run/dmesg.boot.
2981 For example, acd0 is the first IDE CDROM drive, while kbd0 represents the
2984 Most of these devices in a UNIX operating system must be accessed through
2985 special files called device nodes, which are located in the /dev
2988 ----------------------------------------------------------------------
2990 3.11.1 Creating Device Nodes with MAKEDEV
2992 When adding a new device to your system, or compiling in support for
2993 additional devices, you may need to create one or more device nodes for
2996 Device nodes are created using the MAKEDEV(8) script as shown below:
3002 This example would make the proper device nodes for the second IDE drive
3005 ----------------------------------------------------------------------
3009 To understand why DragonFly uses the elf(5) format, you must first know a
3010 little about the three currently ``dominant'' executable formats for UNIX:
3014 The oldest and ``classic'' UNIX object format. It uses a short and
3015 compact header with a magic number at the beginning that is often used
3016 to characterize the format (see a.out(5) for more details). It
3017 contains three loaded segments: .text, .data, and .bss plus a symbol
3018 table and a string table.
3022 The SVR3 object format. The header now comprises a section table, so
3023 you can have more than just .text, .data, and .bss sections.
3027 The successor to COFF, featuring multiple sections and 32-bit or
3028 64-bit possible values. One major drawback: ELF was also designed with
3029 the assumption that there would be only one ABI per system
3030 architecture. That assumption is actually quite incorrect, and not
3031 even in the commercial SYSV world (which has at least three ABIs:
3032 SVR4, Solaris, SCO) does it hold true.
3034 DragonFly tries to work around this problem somewhat by providing a
3035 utility for branding a known ELF executable with information about the
3036 ABI it is compliant with. See the manual page for brandelf(1) for more
3037 information. DragonFly runs ELF.
3039 So, why are there so many different formats?
3041 Back in the dim, dark past, there was simple hardware. This simple
3042 hardware supported a simple, small system. a.out was completely adequate
3043 for the job of representing binaries on this simple system (a PDP-11). As
3044 people ported UNIX from this simple system, they retained the a.out format
3045 because it was sufficient for the early ports of UNIX to architectures
3046 like the Motorola 68k, VAXen, etc.
3048 Then some bright hardware engineer decided that if he could force software
3049 to do some sleazy tricks, then he would be able to shave a few gates off
3050 the design and allow his CPU core to run faster. While it was made to work
3051 with this new kind of hardware (known these days as RISC), a.out was
3052 ill-suited for this hardware, so many formats were developed to get to a
3053 better performance from this hardware than the limited, simple a.out
3054 format could offer. Things like COFF, ECOFF, and a few obscure others were
3055 invented and their limitations explored before things seemed to settle on
3058 In addition, program sizes were getting huge and disks (and physical
3059 memory) were still relatively small so the concept of a shared library was
3060 born. The VM system also became more sophisticated. While each one of
3061 these advancements was done using the a.out format, its usefulness was
3062 stretched more and more with each new feature. In addition, people wanted
3063 to dynamically load things at run time, or to junk parts of their program
3064 after the init code had run to save in core memory and swap space.
3065 Languages became more sophisticated and people wanted code called before
3066 main automatically. Lots of hacks were done to the a.out format to allow
3067 all of these things to happen, and they basically worked for a time. In
3068 time, a.out was not up to handling all these problems without an ever
3069 increasing overhead in code and complexity. While ELF solved many of these
3070 problems, it would be painful to switch from the system that basically
3071 worked. So ELF had to wait until it was more painful to remain with a.out
3072 than it was to migrate to ELF.
3074 ELF is more expressive than a.out and allows more extensibility in the
3075 base system. The ELF tools are better maintained, and offer cross
3076 compilation support, which is important to many people. ELF may be a
3077 little slower than a.out, but trying to measure it can be difficult. There
3078 are also numerous details that are different between the two in how they
3079 map pages, handle init code, etc. None of these are very important, but
3080 they are differences.
3082 ----------------------------------------------------------------------
3084 3.13 For More Information
3088 The most comprehensive documentation on DragonFly is in the form of manual
3089 pages. Nearly every program on the system comes with a short reference
3090 manual explaining the basic operation and various arguments. These manuals
3091 can be viewed with the man command. Use of the man command is simple:
3095 command is the name of the command you wish to learn about. For example,
3096 to learn more about ls command type:
3100 The online manual is divided up into numbered sections:
3104 2. System calls and error numbers.
3106 3. Functions in the C libraries.
3112 6. Games and other diversions.
3114 7. Miscellaneous information.
3116 8. System maintenance and operation commands.
3118 9. Kernel internals.
3120 In some cases, the same topic may appear in more than one section of the
3121 online manual. For example, there is a chmod user command and a chmod()
3122 system call. In this case, you can tell the man command which one you want
3123 by specifying the section:
3127 This will display the manual page for the user command chmod. References
3128 to a particular section of the online manual are traditionally placed in
3129 parenthesis in written documentation, so chmod(1) refers to the chmod user
3130 command and chmod(2) refers to the system call.
3132 This is fine if you know the name of the command and simply wish to know
3133 how to use it, but what if you cannot recall the command name? You can use
3134 man to search for keywords in the command descriptions by using the -k
3139 With this command you will be presented with a list of commands that have
3140 the keyword ``mail'' in their descriptions. This is actually functionally
3141 equivalent to using the apropos command.
3143 So, you are looking at all those fancy commands in /usr/bin but do not
3144 have the faintest idea what most of them actually do? Simply do:
3154 which does the same thing.
3156 ----------------------------------------------------------------------
3158 3.13.2 GNU Info Files
3160 DragonFly includes many applications and utilities produced by the Free
3161 Software Foundation (FSF). In addition to manual pages, these programs
3162 come with more extensive hypertext documents called info files which can
3163 be viewed with the info command or, if you installed emacs, the info mode
3166 To use the info(1) command, simply type:
3170 For a brief introduction, type h. For a quick command reference, type ?.
3172 ----------------------------------------------------------------------
3174 Chapter 4 Installing Applications using NetBSD's pkgsrc framework
3178 DragonFly is bundled with a rich collection of system tools as part of the
3179 base system. However, there is only so much one can do before needing to
3180 install an additional third-party application to get real work done.
3181 DragonFly utilizes NetBSD's pkgsrc framework (pkgsrc.org) for installing
3182 third party software on your system. This system may be used to install
3183 the newest version of your favorite applications from local media or
3184 straight off the network.
3186 After reading this chapter, you will know:
3188 * How to install third-party binary software packages from the pkgsrc
3191 * How to build third-party software from the pkgsrc collection.
3193 * Where to find DragonFly-specific changes to packages.
3195 * How to remove previously installed packages.
3197 * How to override the default values that the pkgsrc collection uses.
3199 * How to upgrade your packages.
3201 ----------------------------------------------------------------------
3203 4.2 Overview of Software Installation
3205 If you have used a UNIX system before you will know that the typical
3206 procedure for installing third party software goes something like this:
3208 1. Download the software, which might be distributed in source code
3209 format, or as a binary.
3211 2. Unpack the software from its distribution format (typically a tarball
3212 compressed with compress(1), gzip(1), or bzip2(1)).
3214 3. Locate the documentation (perhaps an INSTALL or README file, or some
3215 files in a doc/ subdirectory) and read up on how to install the
3218 4. If the software was distributed in source format, compile it. This may
3219 involve editing a Makefile, or running a configure script, and other
3222 5. Test and install the software.
3224 And that is only if everything goes well. If you are installing a software
3225 package that was not deliberately ported to DragonFly you may even have to
3226 go in and edit the code to make it work properly.
3228 Should you want to, you can continue to install software the
3229 ``traditional'' way with DragonFly. However, DragonFly provides technology
3230 from NetBSD, which can save you a lot of effort: pkgsrc. At the time of
3231 writing, over 6,000 third party applications have been made available in
3234 For any given application, the DragonFly Binary package for that
3235 application is a single file which you must download. The package contains
3236 pre-compiled copies of all the commands for the application, as well as
3237 any configuration files or documentation. A downloaded package file can be
3238 manipulated with DragonFly package management commands, such as
3239 pkg_add(1), pkg_delete(1), pkg_info(1), and so on. Installing a new
3240 application can be carried out with a single command.
3242 In addition the pkgsrc collection supplies a collection of files designed
3243 to automate the process of compiling an application from source code.
3245 Remember that there are a number of steps you would normally carry out if
3246 you compiled a program yourself (downloading, unpacking, patching,
3247 compiling, installing). The files that make up a pkgsrc source collection
3248 contain all the necessary information to allow the system to do this for
3249 you. You run a handful of simple commands and the source code for the
3250 application is automatically downloaded, extracted, patched, compiled, and
3253 In fact, the pkgsrc source subsystem can also be used to generate packages
3254 which can later be manipulated with pkg_add and the other package
3255 management commands that will be introduced shortly.
3257 Pkgsrc understands dependencies. Suppose you want to install an
3258 application that depends on a specific library being installed. Both the
3259 application and the library have been made available through the pkgsrc
3260 collection. If you use the pkg_add command or the pkgsrc subsystem to add
3261 the application, both will notice that the library has not been installed,
3262 and automatically install the library first.
3264 You might be wondering why pkgsrc bothers with both. Binary packages and
3265 the source tree both have their own strengths, and which one you use will
3266 depend on your own preference.
3268 Binary Package Benefits
3270 * A compressed package tarball is typically smaller than the compressed
3271 tarball containing the source code for the application.
3273 * Packages do not require any additional compilation. For large
3274 applications, such as Mozilla, KDE, or GNOME this can be important,
3275 particularly if you are on a slow system.
3277 * Packages do not require any understanding of the process involved in
3278 compiling software on DragonFly.
3280 Pkgsrc source Benefits
3282 * Binary packages are normally compiled with conservative options,
3283 because they have to run on the maximum number of systems. By
3284 installing from the source, you can tweak the compilation options to
3285 (for example) generate code that is specific to a Pentium IV or Athlon
3288 * Some applications have compile time options relating to what they can
3289 and cannot do. For example, Apache can be configured with a wide
3290 variety of different built-in options. By building from the source you
3291 do not have to accept the default options, and can set them yourself.
3293 In some cases, multiple packages will exist for the same application
3294 to specify certain settings. For example, vim is available as a vim
3295 package and a vim-gtk package, depending on whether you have installed
3296 an X11 server. This sort of rough tweaking is possible with packages,
3297 but rapidly becomes impossible if an application has more than one or
3298 two different compile time options.
3300 * The licensing conditions of some software distributions forbid binary
3301 distribution. They must be distributed as source code.
3303 * Some people do not trust binary distributions. With source code, it is
3304 possible to check for any vulnerabilities built into the program
3305 before installing it to an otherwise secure system. Few people perform
3306 this much review, however.
3308 * If you have local patches, you will need the source in order to apply
3311 * Some people like having code around, so they can read it if they get
3312 bored, hack it, borrow from it (license permitting, of course), and so
3315 To keep track of updated pkgsrc releases subscribe to the netBSD pkgsrc
3316 users mailing list and the netBSD pkgsrc users mailing list. It's also
3317 useful to watch the DragonFly User related mailing list as errors with
3318 pkgsrc on DragonFly should be reported there.
3320 Warning: Before installing any application, you should check
3321 http://www.pkgsrc.org/ for security issues related to your application.
3323 You can also install security/audit-packages which will automatically
3324 check all installed applications for known vulnerabilities, a check will
3325 be also performed before any application build. Meanwhile, you can use
3326 the command audit-packages -d after you have installed some packages.
3328 The remainder of this chapter will explain how to use the pkgsrc system to
3329 install and manage third party software on DragonFly.
3331 ----------------------------------------------------------------------
3333 4.3 Finding Your Application
3335 Before you can install any applications you need to know what you want,
3336 and what the application is called.
3338 DragonFly's list of available applications is growing all the time.
3339 Fortunately, there are a number of ways to find what you want:
3341 * There is a pkgsrc related web site that maintains an up-to-date
3342 searchable list of all the available applications, at
3343 http://pkgsrc.se. The packages and the corresponding source tree are
3344 divided into categories, and you may either search for an application
3345 by name (if you know it), or see all the applications available in a
3348 ----------------------------------------------------------------------
3350 4.4 Using the Binary Packages System
3352 Original FreeBSD documentation contributed by DragonFly BSD customizations
3353 contributed by Chern Lee and Adrian Nida.
3355 4.4.1 Installing a Binary Package
3357 You can use the pkg_add(1) utility to install a pkgsrc software package
3358 from a local file or from a server on the network.
3360 Example 4-1. Downloading a Package Manually and Installing It Locally
3362 # ftp -a packages.stura.uni-rostock.de
3363 Connected to fsr.uni-rostock.de.
3364 220 packages.stura.uni-rostock.de FTP server (Version 6.00LS) ready.
3365 331 Guest login ok, send your email address as password.
3366 230 Guest login ok, access restrictions apply.
3367 Remote system type is UNIX.
3368 Using binary mode to transfer files.
3369 ftp> cd /pkgsrc-current/DragonFly/RELEASE/i386/All/
3370 250 CWD command successful.
3371 ftp> get 0verkill-0.15.tgz
3372 local: 0verkill-0.15.tgz remote: 0verkill-0.15.tgz
3373 229 Entering Extended Passive Mode (|||61652|)
3374 150 Opening BINARY mode data connection for '0verkill-0.15.tgz' (174638 bytes).
3375 100% |*************************************| 170 KB 159.37 KB/s 00:00 ETA
3376 226 Transfer complete.
3377 174638 bytes received in 00:01 (159.30 KB/s)
3380 # pkg_add 0verkill-0.15.tgz
3382 Note: It should be noted that simply issuing:
3384 # pkg_add ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/RELEASE/i386/All/0verkill-0.15.tgz
3386 will yield the same result as the above example.
3388 Unlike the FreeBSD version, the Pkgsrc pkg_add(1) does not need to be
3389 passed the -r option. As can be seen from the second example, you just
3390 need to pass in the URL of the package. The utility will also always
3391 automatically fetch and install all dependencies.
3393 The example above would download the correct package and add it without
3394 any further user intervention. If you want to specify an alternative
3395 DragonFly Packages Mirror, instead of the main distribution site, you have
3396 to set PACKAGESITE accordingly, to override the default settings.
3397 pkg_add(1) uses fetch(3) to download the files, which honors various
3398 environment variables, including FTP_PASSIVE_MODE, FTP_PROXY, and
3399 FTP_PASSWORD. You may need to set one or more of these if you are behind a
3400 firewall, or need to use an FTP/HTTP proxy. See fetch(3) for the complete
3403 Binary package files are distributed in .tgz formats. You can find them at
3404 the default location ftp://goBSD.com//packages/, among other sites. The
3405 layout of the packages is similar to that of the /usr/pkgsrc tree. Each
3406 category has its own directory, and every package can be found within the
3409 The directory structure of the binary package system matches the source
3410 tree layout; they work with each other to form the entire package system.
3412 ----------------------------------------------------------------------
3414 4.4.2 Managing Packages
3416 pkg_info(1) is a utility that lists and describes the various packages
3420 digest-20050731 Message digest wrapper utility
3421 screen-4.0.2nb4 Multi-screen window manager
3424 pkg_version(1) is a utility that summarizes the versions of all installed
3425 packages. It compares the package version to the current version found in
3428 ----------------------------------------------------------------------
3430 4.4.3 Deleting a Package
3432 To remove a previously installed software package, use the pkg_delete(1)
3435 # pkg_delete xchat-1.7.1
3437 ----------------------------------------------------------------------
3441 All package information is stored within the /var/db/pkg directory. The
3442 installed file list and descriptions of each package can be found within
3443 subdirectories of this directory.
3445 ----------------------------------------------------------------------
3447 4.5 Using the pkgsrc(R) Source Tree
3449 The following sections provide basic instructions on using the pkgsrc
3450 source tree to install or remove programs from your system.
3452 ----------------------------------------------------------------------
3454 4.5.1 Obtaining the pkgsrc Source Tree
3456 Before you can install pkgsrc packages from source, you must first obtain
3457 the pkgsrc source tree--which is essentially a set of Makefiles, patches,
3458 and description files placed in /usr/pkgsrc.
3460 The primary method to obtain and keep your pkgsrc collection up to date is
3465 This is a quick method for getting the pkgsrc collection using CVS.
3470 # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
3472 2. Running the following command later will download and apply all the
3473 recent changes to your source tree.
3478 ----------------------------------------------------------------------
3480 4.5.2 Installing Packages from Source
3482 The first thing that should be explained when it comes to the source tree
3483 is what is actually meant by a ``skeleton''. In a nutshell, a source
3484 skeleton is a minimal set of files that tell your DragonFly system how to
3485 cleanly compile and install a program. Each source skeleton should
3488 * A Makefile. The Makefile contains various statements that specify how
3489 the application should be compiled and where it should be installed on
3492 * A distinfo file. This file contains information about the files that
3493 must be downloaded to build the port and their checksums, to verify
3494 that files have not been corrupted during the download using md5(1).
3496 * A files directory. This directory contains the application specific
3497 files that are needed for the programs appropriate run-time
3500 This directory may also contain other files used to build the port.
3502 * A patches directory. This directory contains patches to make the
3503 program compile and install on your DragonFly system. Patches are
3504 basically small files that specify changes to particular files. They
3505 are in plain text format, and basically say ``Remove line 10'' or
3506 ``Change line 26 to this ...''. Patches are also known as ``diffs''
3507 because they are generated by the diff(1) program.
3509 * A DESCR file. This is a more detailed, often multiple-line,
3510 description of the program.
3512 * A PLIST file. This is a list of all the files that will be installed
3513 by the port. It also tells the pkgsrc system what files to remove upon
3516 Some pkgsrc source skeletons have other files, such as MESSAGE. The pkgsrc
3517 system uses these files to handle special situations. If you want more
3518 details on these files, and on pkgsrc in general, check out The pkgsrc
3519 guide, available at the NetBSD website.
3521 Now that you have enough background information to know what the pkgsrc
3522 source tree is used for, you are ready to install your first compiled
3523 package. There are two ways this can be done, and each is explained below.
3525 Before we get into that, however, you will need to choose an application
3526 to install. There are a few ways to do this, with the easiest method being
3527 the pkgsrc listing on Joerg Sonnenberger's web site. You can browse
3528 through the packages listed there.
3530 Another way to find a particular source tree is by using the pkgsrc
3531 collection's built-in search mechanism. To use the search feature, you
3532 will need to be in the /usr/pkgsrc directory. Once in that directory, run
3533 bmake search key="program-name" where program-name is the name of the
3534 program you want to find. This searches packages names, comments,
3535 descriptions and dependencies and can be used to find packages which
3536 relate to a particular subject if you don't know the name of the program
3537 you are looking for. For example, if you were looking for apache2:
3540 # bmake search key="apache2"
3541 Extracting complete dependency database. This may take a while...
3542 ....................................................................................................
3544 ....................................................................................................
3548 ....................................................................................................
3550 .................................................................................................Reading database file
3551 Flattening dependencies
3552 Flattening build dependencies
3553 Generating INDEX file
3554 Indexed 5999 packages
3556 Pkg: apache-2.0.55nb7
3558 Info: Apache HTTP (Web) server, version 2
3559 Maint: tron@NetBSD.org
3561 B-deps: perl>=5.0 apr>=0.9.7.2.0.55nb2 expat>=2.0.0nb1 libtool-base>=1.5.22nb1 gmake>=3.78 gettext-lib>=0.14.5 pkg-config>=0.19
3562 R-deps: perl>=5.0 apr>=0.9.7.2.0.55nb2 expat>=2.0.0nb1
3565 The part of the output you want to pay particular attention to is the
3566 ``Path:'' line, since that tells you where to find the source tree for the
3567 requested application. The other information provided is not needed in
3568 order to install the package, so it will not be covered here.
3570 The search string is case-insensitive. Searching for ``APACHE'' will yield
3571 the same results as searching for ``apache''.
3573 Note: It should be noted that ``Extracting [the] complete dependency
3574 database'' does indeed take a while.
3576 Note: You must be logged in as root to install packages.
3578 Now that you have found an application you would like to install, you are
3579 ready to do the actual installation. The source package includes
3580 instructions on how to build source code, but does not include the actual
3581 source code. You can get the source code from a CD-ROM or from the
3582 Internet. Source code is distributed in whatever manner the software
3583 author desires. Frequently this is a tarred and gzipped file, but it might
3584 be compressed with some other tool or even uncompressed. The program
3585 source code, whatever form it comes in, is called a ``distfile''. You can
3586 get the distfile from a CD-ROM or from the Internet.
3588 Warning: Before installing any application, you should be sure to have
3589 an up-to-date source tree and you should check http://www.pkgsrc.org/
3590 for security issues related to your port.
3592 A security vulnerabilities check can be automatically done by
3593 audit-packages before any new application installation. This tool can be
3594 found in the pkgsrc collection (security/audit-packages). Consider
3595 running auditpackages -d before installing a new package, to fetch the
3596 current vulnerabilities database. A security audit and an update of the
3597 database will be performed during the daily security system check. For
3598 more informations read the audit-packages and periodic(8) manual pages.
3600 Note: It should be noted that the current setup of DragonFly requires
3601 the use of bmake instead of make. This is because the current version of
3602 make on DragonFly does not support all the parameters that NetBSD's
3605 Note: You can save an extra step by just running bmake install instead
3606 of bmake and bmake install as two separate steps.
3608 Note: Some shells keep a cache of the commands that are available in the
3609 directories listed in the PATH environment variable, to speed up lookup
3610 operations for the executable file of these commands. If you are using
3611 one of these shells, you might have to use the rehash command after
3612 installing a package, before the newly installed commands can be used.
3613 This is true for both shells that are part of the base-system (such as
3614 tcsh) and shells that are available as packages (for instance,
3617 ----------------------------------------------------------------------
3619 4.5.2.1 Installing Packages from the Internet
3621 As with the last section, this section makes an assumption that you have a
3622 working Internet connection. If you do not, you will need to put a copy of
3623 the distfile into /usr/pkgsrc/distfiles manually.
3625 Installing a package from the Internet is done exactly the same way as it
3626 would be if you already had the distfile. The only difference between the
3627 two is that the distfile is downloaded from the Internet on demand.
3629 Here are the steps involved:
3631 # cd /usr/pkgsrc/chat/ircII
3632 # bmake install clean
3633 => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
3634 => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
3636 Connected to ircii.warped.com.
3637 220 bungi.sjc.warped.net FTP server (tnftpd 20040810) ready.
3638 331 Guest login ok, type your name as password.
3640 A SERVICE OF WARPED.COM - FOR MORE INFORMATION: http://www.warped.com
3643 Please read the file README
3644 it was last modified on Mon Feb 9 18:43:17 2004 - 794 days ago
3645 230 Guest login ok, access restrictions apply.
3646 Remote system type is UNIX.
3647 Using binary mode to transfer files.
3649 250 CWD command successful.
3650 250 CWD command successful.
3651 local: ircii-20040820.tar.bz2 remote: ircii-20040820.tar.bz2
3652 229 Entering Extended Passive Mode (|||60090|)
3653 150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
3654 100% |***************************************| 550 KB 110.34 KB/s 00:00 ETA
3655 226 Transfer complete.
3656 559843 bytes received in 00:04 (110.34 KB/s)
3658 Data traffic for this session was 559843 bytes in 1 file.
3659 Total traffic for this session was 560993 bytes in 1 transfer.
3660 221 Thank you for using the FTP service on bungi.sjc.warped.net.
3661 => Checksum SHA1 OK for ircii-20040820.tar.bz2.
3662 => Checksum RMD160 OK for ircii-20040820.tar.bz2.
3663 work -> /usr/obj/pkgsrc/chat/ircII/work
3664 ===> Extracting for ircII-20040820
3665 ==========================================================================
3666 The supported build options for this package are:
3670 You can select which build options to use by setting PKG_DEFAULT_OPTIONS
3671 or the following variable. Its current value is shown:
3673 PKG_OPTIONS.ircII (not defined)
3675 ==========================================================================
3676 ==========================================================================
3677 The following variables will affect the build process of this package,
3678 ircII-20040820. Their current value is shown below:
3682 You may want to abort the process now with CTRL-C and change their value
3683 before continuing. Be sure to run `/usr/pkg/bin/bmake clean' after
3685 ==========================================================================
3686 ===> Patching for ircII-20040820
3687 ===> Applying pkgsrc patches for ircII-20040820
3688 ===> Overriding tools for ircII-20040820
3689 ===> Creating toolchain wrappers for ircII-20040820
3690 ===> Configuring for ircII-20040820
3692 [configure output snipped]
3694 ===> Building for ircII-20040820
3696 [compilation output snipped]
3698 ===> Installing for ircII-20040820
3700 [installation output snipped]
3702 ===> [Automatic manual page handling]
3703 ===> Registering installation for ircII-20040820
3704 ===> Cleaning for ircII-20040820
3707 As you can see, the only difference are the lines that tell you where the
3708 system is fetching the package's distfile from.
3710 The pkgsrc system uses ftp(1) to download the files, which honors various
3711 environment variables, including FTP_PASSIVE_MODE, FTP_PROXY, and
3712 FTP_PASSWORD. You may need to set one or more of these if you are behind a
3713 firewall, or need to use an FTP/HTTP proxy. See ftp(1) for the complete
3716 For users which cannot be connected all the time, the bmake fetch option
3717 is provided. Just run this command at the top level directory
3718 (/usr/pkgsrc) and the required files will be downloaded for you. This
3719 command will also work in the lower level categories, for example:
3720 /usr/pkgsrc/net. Note that if a package depends on libraries or other
3721 packages this will not fetch the distfiles of those packages as well.
3723 Note: You can build all the packages in a category or as a whole by
3724 running bmake in the top level directory, just like the aforementioned
3725 bmake fetch method. This is dangerous, however, as some applications
3726 cannot co-exist. In other cases, some packages can install two different
3727 files with the same filename.
3729 In some rare cases, users may need to acquire the tarballs from a site
3730 other than the MASTER_SITES (the location where files are downloaded
3731 from). You can override the MASTER_SORT, MASTER_SORT_REGEX and
3732 INET_COUNTRY options either within the /etc/mk.conf.
3734 Note: Some packages allow (or even require) you to provide build options
3735 which can enable/disable parts of the application which are unneeded,
3736 certain security options, and other customizations. A few which come to
3737 mind are www/mozilla, security/gpgme, and mail/sylpheed-claws. To find
3738 out what build options the application you are installing requires type:
3740 # bmake show-options
3742 To change the build process, either change the values of
3743 PKG_DEFAULT_OPTIONS or PKG_OPTIONS.PackageName in /etc/mk.conf or on the
3746 # bmake PKG_OPTIONS.ircII="-ssl"
3748 An option is enabled if listed. It is disabled if it is prefixed by a
3751 ----------------------------------------------------------------------
3753 4.5.2.2 Dealing with imake
3755 Some applications that use imake (a part of the X Window System) do not
3756 work well with PREFIX, and will insist on installing under /usr/X11R6.
3757 Similarly, some Perl ports ignore PREFIX and install in the Perl tree.
3758 Making these applications respect PREFIX is a difficult or impossible job.
3760 ----------------------------------------------------------------------
3762 4.5.3 Removing Installed Packages
3764 Now that you know how to install packages, you are probably wondering how
3765 to remove them, just in case you install one and later on decide that you
3766 installed the wrong program. We will remove our previous example (which
3767 was ircII for those of you not paying attention). As with installing
3768 packages, the first thing you must do is change to the package directory,
3769 /usr/pkgsrc/chat/ircII. After you change directories, you are ready to
3770 uninstall ircII. This is done with the bmake deinstall command:
3772 # cd /usr/pkgsrc/chat/ircII
3774 ===> Deinstalling for ircII-20040820
3776 That was easy enough. You have removed ircII from your system. If you
3777 would like to reinstall it, you can do so by running bmake reinstall from
3778 the /usr/ports/chat/ircII directory.
3780 The bmake deinstall and bmake reinstall sequence does not work once you
3781 have run bmake clean. If you want to deinstall a package after cleaning,
3782 use pkg_delete(1) as discussed in the Pkgsrc section of the Handbook.
3784 ----------------------------------------------------------------------
3786 4.5.4 Packages and Disk Space
3788 Using the pkgsrc collection can definitely eat up your disk space. For
3789 this reason you should always remember to clean up the work directories
3790 using the bmake clean option. This will remove the work directory after a
3791 package has been built, and installed. You can also remove the tar files
3792 from the distfiles directory, and remove the installed package when their
3795 ----------------------------------------------------------------------
3797 4.5.5 Upgrading Packages
3799 Note: Once you have updated your pkgsrc collection, before attempting a
3800 package upgrade, you should check the /usr/pkgsrc/UPDATING file. This
3801 file describes various issues and additional steps users may encounter
3802 and need to perform when updating a port.
3804 Keeping your packages up to date can be a tedious job. For instance, to
3805 upgrade a package you would go to the package directory, build the
3806 package, deinstall the old package , install the new package, and then
3807 clean up after the build. Imagine doing that for five packages, tedious
3808 right? This was a large problem for system administrators to deal with,
3809 and now we have utilities which do this for us. For instance the pkg_chk
3810 utility will do everything for you!
3812 pkg_chk requires a few steps in order to work correctly. They are listed
3815 # pkg_chk -g # make initial list of installed packages
3816 # pkg_chk -r # remove all packages that are not up to date and packages that depend on them
3817 # pkg_chk -a # install all missing packages (use binary packages, this is the default)
3818 # pkg_chk -as # install all missing packages (build from source)
3821 ----------------------------------------------------------------------
3823 4.6 Post-installation Activities
3825 After installing a new application you will normally want to read any
3826 documentation it may have included, edit any configuration files that are
3827 required, ensure that the application starts at boot time (if it is a
3830 The exact steps you need to take to configure each application will
3831 obviously be different. However, if you have just installed a new
3832 application and are wondering ``What now?'' these tips might help:
3834 * Use pkg_info(1) to find out which files were installed, and where. For
3835 example, if you have just installed FooPackage version 1.0.0, then
3838 # pkg_info -L foopackage-1.0.0 | less
3840 will show all the files installed by the package. Pay special
3841 attention to files in man/ directories, which will be manual pages,
3842 etc/ directories, which will be configuration files, and doc/, which
3843 will be more comprehensive documentation.
3845 If you are not sure which version of the application was just
3846 installed, a command like this
3848 # pkg_info | grep -i foopackage
3850 will find all the installed packages that have foopackage in the
3851 package name. Replace foopackage in your command line as necessary.
3853 * Once you have identified where the application's manual pages have
3854 been installed, review them using man(1). Similarly, look over the
3855 sample configuration files, and any additional documentation that may
3858 * If the application has a web site, check it for additional
3859 documentation, frequently asked questions, and so forth. If you are
3860 not sure of the web site address it may be listed in the output from
3862 # pkg_info foopackage-1.0.0
3864 A WWW: line, if present, should provide a URL for the application's
3867 * Packages that should start at boot (such as Internet servers) will
3868 usually install a sample script in /usr/pkg/etc/rc.d. You should
3869 review this script for correctness and edit or rename it if needed.
3870 See Starting Services for more information.
3872 ----------------------------------------------------------------------
3874 4.7 Dealing with Broken Packages
3876 If you come across a package that does not work for you, there are a few
3877 things you can do, including:
3879 1. Fix it! The pkgsrc Guide includes detailed information on the
3880 ``pkgsrc'' infrastructure so that you can fix the occasional broken
3881 package or even submit your own!
3883 2. Gripe--by email only! Send email to the maintainer of the package
3884 first. Type bmake maintainer or read the Makefile to find the
3885 maintainer's email address. Remember to include the name and version
3886 of the port (send the $NetBSD: line from the Makefile) and the output
3887 leading up to the error when you email the maintainer. If you do not
3888 get a response from the maintainer, you can try users .
3890 3. Grab the package from an FTP site near you. The ``master'' package
3891 collection is on packages.stura.uni-rostock.de in the All directory.
3892 These are more likely to work than trying to compile from source and
3893 are a lot faster as well. Use the pkg_add(1) program to install the
3894 package on your system.
3896 ----------------------------------------------------------------------
3898 Chapter 5 The X Window System
3902 DragonFly uses XFree86 to provide users with a powerful graphical user
3903 interface. XFree86 is an open-source implementation of the X Window
3904 System. This chapter will cover installation and configuration of XFree86
3905 on a DragonFly system. For more information on XFree86 and video hardware
3906 that it supports, check the XFree86 web site.
3908 Warning: This chapter contains a number of outdated references to the
3909 FreeBSD ports collection. Most instructions still apply to pkgsrc, but
3910 proceed with caution until this chapter is updated.
3912 After reading this chapter, you will know:
3914 * The various components of the X Window System, and how they
3917 * How to install and configure XFree86.
3919 * How to install and use different window managers.
3921 * How to use TrueType(R) fonts in XFree86.
3923 * How to set up your system for graphical logins (XDM).
3925 Before reading this chapter, you should:
3927 * Know how to install additional third-party software (Chapter 4).
3929 ----------------------------------------------------------------------
3933 Using X for the first time can be somewhat of a shock to someone familiar
3934 with other graphical environments, such as Microsoft Windows or Mac OS.
3936 It is not necessary to understand all of the details of various X
3937 components and how they interact; however, some basic knowledge makes it
3938 possible to take advantage of X's strengths.
3940 ----------------------------------------------------------------------
3944 X is not the first window system written for UNIX, but it is the most
3945 popular. X's original development team had worked on another window system
3946 before writing X. That system's name was ``W'' (for ``Window''). X is just
3947 the next letter in the Roman alphabet.
3949 X can be called ``X'', ``X Window System'', ``X11'', and other terms.
3950 Calling X11 ``X Windows'' can offend some people; see X(7) for a bit more
3953 ----------------------------------------------------------------------
3955 5.2.2 The X Client/Server Model
3957 X was designed from the beginning to be network-centric, and adopts a
3958 ``client-server'' model. In the X model, the ``X server'' runs on the
3959 computer that has the keyboard, monitor, and mouse attached. The server is
3960 responsible for managing the display, handling input from the keyboard and
3961 mouse, and so on. Each X application (such as XTerm, or Netscape) is a
3962 ``client''. A client sends messages to the server such as ``Please draw a
3963 window at these coordinates'', and the server sends back messages such as
3964 ``The user just clicked on the OK button''.
3966 If there is only one computer involved, such as in a home or small office
3967 environment, the X server and the X clients will be running on the same
3968 computer. However, it is perfectly possible to run the X server on a less
3969 powerful desktop computer, and run X applications (the clients) on, say,
3970 the powerful and expensive machine that serves the office. In this
3971 scenario the communication between the X client and server takes place
3974 This confuses some people, because the X terminology is exactly backward
3975 to what they expect. They expect the ``X server'' to be the big powerful
3976 machine down the hall, and the ``X client'' to be the machine on their
3979 Remember that the X server is the machine with the monitor and keyboard,
3980 and the X clients are the programs that display the windows.
3982 There is nothing in the protocol that forces the client and server
3983 machines to be running the same operating system, or even to be running on
3984 the same type of computer. It is certainly possible to run an X server on
3985 Microsoft Windows or Apple's Mac OS, and there are various free and
3986 commercial applications available that do exactly that.
3988 The X server that ships with DragonFly is called XFree86, and is available
3989 for free, under a license very similar to the DragonFly license.
3990 Commercial X servers for FreeBSD are also available, and ought to work
3991 with DragonFly . (Unconfirmed as of this writing.)
3993 ----------------------------------------------------------------------
3995 5.2.3 The Window Manager
3997 The X design philosophy is much like the UNIX design philosophy, ``tools,
3998 not policy''. This means that X does not try to dictate how a task is to
3999 be accomplished. Instead, tools are provided to the user, and it is the
4000 user's responsibility to decide how to use those tools.
4002 This philosophy extends to X not dictating what windows should look like
4003 on screen, how to move them around with the mouse, what keystrokes should
4004 be used to move between windows (i.e., Alt+Tab, in the case of
4005 Microsoft Windows), what the title bars on each window should look like,
4006 whether or not they have close buttons on them, and so on.
4008 Instead, X delegates this responsibility to an application called a
4009 ``Window Manager''. There are dozens of window managers available for X:
4010 AfterStep, Blackbox, ctwm, Enlightenment, fvwm, Sawfish, twm, Window
4011 Maker, and more. Each of these window managers provides a different look
4012 and feel; some of them support ``virtual desktops''; some of them allow
4013 customized keystrokes to manage the desktop; some have a ``Start'' button
4014 or similar device; some are ``themeable'', allowing a complete change of
4015 look-and-feel by applying a new theme. These window managers, and many
4016 more, are available in the wm category of pkgsrc.
4018 In addition, the KDE and GNOME desktop environments both have their own
4019 window managers which integrate with the desktop.
4021 Each window manager also has a different configuration mechanism; some
4022 expect configuration file written by hand, others feature GUI tools for
4023 most of the configuration tasks; at least one (sawfish) has a
4024 configuration file written in a dialect of the Lisp language.
4026 Focus Policy: Another feature the window manager is responsible for is
4027 the mouse ``focus policy''. Every windowing system needs some means of
4028 choosing a window to be actively receiving keystrokes, and should
4029 visibly indicate which window is active as well.
4031 A familiar focus policy is called ``click-to-focus''. This is the model
4032 utilized by Microsoft Windows, in which a window becomes active upon
4033 receiving a mouse click.
4035 X does not support any particular focus policy. Instead, the window
4036 manager controls which window has the focus at any one time. Different
4037 window managers will support different focus methods. All of them
4038 support click to focus, and the majority of them support several others.
4040 The most popular focus policies are:
4044 The window that is under the mouse pointer is the window that
4045 has the focus. This may not necessarily be the window that is on
4046 top of all the other windows. The focus is changed by pointing
4047 at another window, there is no need to click in it as well.
4051 This policy is a small extension to focus-follows-mouse. With
4052 focus-follows-mouse, if the mouse is moved over the root window
4053 (or background) then no window has the focus, and keystrokes are
4054 simply lost. With sloppy-focus, focus is only changed when the
4055 cursor enters a new window, and not when exiting the current
4060 The active window is selected by mouse click. The window may
4061 then be ``raised'', and appear in front of all other windows.
4062 All keystrokes will now be directed to this window, even if the
4063 cursor is moved to another window.
4065 Many window managers support other policies, as well as variations on
4066 these. Be sure to consult the documentation for the window manager
4069 ----------------------------------------------------------------------
4073 The X approach of providing tools and not policy extends to the widgets
4074 seen on screen in each application.
4076 ``Widget'' is a term for all the items in the user interface that can be
4077 clicked or manipulated in some way; buttons, check boxes, radio buttons,
4078 icons, lists, and so on. Microsoft Windows calls these ``controls''.
4080 Microsoft Windows and Apple's Mac OS both have a very rigid widget policy.
4081 Application developers are supposed to ensure that their applications
4082 share a common look and feel. With X, it was not considered sensible to
4083 mandate a particular graphical style, or set of widgets to adhere to.
4085 As a result, do not expect X applications to have a common look and feel.
4086 There are several popular widget sets and variations, including the
4087 original Athena widget set from MIT, Motif(R) (on which the widget set in
4088 Microsoft Windows was modeled, all bevelled edges and three shades of
4089 grey), OpenLook, and others.
4091 Most newer X applications today will use a modern-looking widget set,
4092 either Qt, used by KDE, or GTK, used by the GNOME project. In this
4093 respect, there is some convergence in look-and-feel of the UNIX desktop,
4094 which certainly makes things easier for the novice user.
4096 ----------------------------------------------------------------------
4098 5.3 Installing XFree86(TM)
4100 Warning: This section is out of date; please consult the DragonFly BSD
4101 wiki or mailing lists for recent discussion.
4103 A binary package to use with pkg_add(1) tool is also available for XFree86
4104 4.X. When the remote fetching feature of pkg_add(1) is used, the version
4105 number of the package must be removed. pkg_add(1) will automatically fetch
4106 the latest version of the application. So to fetch and install the package
4107 of XFree86 4.X, simply type:
4111 You can also use the ports collection to install XFree86 4.X, for that you
4112 simply need to type the following commands:
4114 # cd /usr/ports/x11/XFree86-4
4115 # make install clean
4117 Note: The examples above will install the complete XFree86 distribution
4118 including the servers, clients, fonts etc. Separate packages for
4119 different parts of XFree86 4.X are also available.
4121 The rest of this chapter will explain how to configure XFree86, and how to
4122 set up a productive desktop environment.
4124 ----------------------------------------------------------------------
4126 5.4 XFree86 Configuration
4128 Contributed by Christopher Shumway.
4130 ----------------------------------------------------------------------
4132 5.4.1 Before Starting
4134 Before configuration of XFree86 4.X, the following information about the
4135 target system is needed:
4137 * Monitor specifications
4139 * Video Adapter chipset
4141 * Video Adapter memory
4143 The specifications for the monitor are used by XFree86 to determine the
4144 resolution and refresh rate to run at. These specifications can usually be
4145 obtained from the documentation that came with the monitor or from the
4146 manufacturer's website. There are two ranges of numbers that are needed,
4147 the horizontal scan rate and the vertical synchronization rate.
4149 The video adapter's chipset defines what driver module XFree86 uses to
4150 talk to the graphics hardware. With most chipsets, this can be
4151 automatically determined, but it is still useful to know in case the
4152 automatic detection does not work correctly.
4154 Video memory on the graphic adapter determines the resolution and color
4155 depth which the system can run at. This is important to know so the user
4156 knows the limitations of the system.
4158 ----------------------------------------------------------------------
4160 5.4.2 Configuring XFree86 4.X
4162 Configuration of XFree86 4.X is a multi-step process. The first step is to
4163 build an initial configuration file with the -configure option to XFree86.
4164 As the super user, simply run:
4166 # XFree86 -configure
4168 This will generate a skeleton XFree86 configuration file in the /root
4169 directory called XF86Config.new (in fact the directory used is the one
4170 covered by the environment variable $HOME, and it will depend from the way
4171 you got the superuser rights). The XFree86 program will attempt to probe
4172 the graphics hardware on the system and will write a configuration file to
4173 load the proper drivers for the detected hardware on the target system.
4175 The next step is to test the existing configuration to verify that XFree86
4176 can work with the graphics hardware on the target system. To perform this
4177 task, the user needs to run:
4179 # XFree86 -xf86config XF86Config.new
4181 If a black and grey grid and an X mouse cursor appear, the configuration
4182 was successful. To exit the test, just press Ctrl+Alt+Backspace
4185 Note: If the mouse does not work, be sure the device has been
4186 configured. See moused(8) for more information
4188 Next, tune the XF86Config.new configuration file to taste. Open the file
4189 in a text editor such as emacs(1) or ee(1). First, add the frequencies for
4190 the target system's monitor. These are usually expressed as a horizontal
4191 and vertical synchronization rate. These values are added to the
4192 XF86Config.new file under the "Monitor" section:
4195 Identifier "Monitor0"
4196 VendorName "Monitor Vendor"
4197 ModelName "Monitor Model"
4202 The HorizSync and VertRefresh keywords may not exist in the configuration
4203 file. If they do not, they need to be added, with the correct horizontal
4204 synchronization rate placed after the HorizSync keyword and the vertical
4205 synchronization rate after the VertRefresh keyword. In the example above
4206 the target monitor's rates were entered.
4208 X allows DPMS (Energy Star) features to be used with capable monitors. The
4209 xset(1) program controls the time-outs and can force standby, suspend, or
4210 off modes. If you wish to enable DPMS features for your monitor, you must
4211 add the following line to the monitor section:
4215 While the XF86Config.new configuration file is still open in an editor,
4216 select the default resolution and color depth desired. This is defined in
4217 the "Screen" section:
4220 Identifier "Screen0"
4224 SubSection "Display"
4230 The DefaultDepth keyword describes the color depth to run at by default.
4231 This can be overridden with the -bpp command line switch to XFree86(1).
4232 The Modes keyword describes the resolution to run at for the given color
4233 depth. Note that only VESA standard modes are supported as defined by the
4234 target system's graphics hardware. In the example above, the default color
4235 depth is twenty-four bits per pixel. At this color depth, the accepted
4236 resolution is one thousand twenty-four pixels by seven hundred and
4239 Finally, write the configuration file and test it using the test mode
4240 given above. If all is well, the configuration file needs to be installed
4241 in a common location where XFree86(1) can find it. This is typically
4242 /etc/X11/XF86Config or /usr/X11R6/etc/X11/XF86Config.
4244 # cp XF86Config.new /etc/X11/XF86Config
4246 Once the configuration file has been placed in a common location,
4247 configuration is complete. In order to start XFree86 4.X with startx(1),
4248 install the x11/wrapper port. XFree86 4.X can also be started with xdm(1).
4250 Note: There is also a graphical tool for configuration, xf86cfg(1), that
4251 comes with the XFree86 4.X distribution. It allows to interactively
4252 define your configuration by choosing the appropriate drivers and
4253 settings. This program can be used under console as well, just use the
4254 command xf86cfg -textmode. For more details, refer to the xf86cfg(1)
4257 ----------------------------------------------------------------------
4259 5.4.3 Advanced Configuration Topics
4261 5.4.3.1 Configuration with Intel(R) i810 Graphics Chipsets
4263 Configuration with Intel(R) i810 integrated chipsets requires the agpgart
4264 AGP programming interface for XFree86 to drive the card. The agp(4) driver
4265 is in the GENERIC kernel since releases 4.8-RELEASE and 5.0-RELEASE. On
4266 prior releases, you will have to add the following line:
4270 in your kernel configuration file and rebuild a new kernel. Instead, you
4271 may want to load the agp.ko kernel module automatically with the loader(8)
4272 at boot time. For that, simply add this line to /boot/loader.conf:
4276 Next, a device node needs to be created for the programming interface. To
4277 create the AGP device node, run MAKEDEV(8) in the /dev directory:
4280 # sh MAKEDEV agpgart
4282 This will allow configuration of the hardware as any other graphics board.
4283 Note on systems without the agp(4) driver compiled in the kernel, trying
4284 to load the module with kldload(8) will not work. This driver has to be in
4285 the kernel at boot time through being compiled in or using
4288 If you are using XFree86 4.1.0 (or later) and messages about unresolved
4289 symbols like fbPictureInit appear, try adding the following line after
4290 Driver "i810" in the XFree86 configuration file:
4294 ----------------------------------------------------------------------
4296 5.5 Using Fonts in XFree86
4298 Contributed by Murray Stokely.
4302 The default fonts that ship with XFree86 are less than ideal for typical
4303 desktop publishing applications. Large presentation fonts show up jagged
4304 and unprofessional looking, and small fonts in Netscape are almost
4305 completely unintelligible. However, there are several free, high quality
4306 Type1 (PostScript(R)) fonts available which can be readily used with
4307 XFree86, either version 3.X or version 4.X. For instance, the URW font
4308 collection (x11-fonts/urwfonts) includes high quality versions of standard
4309 type1 fonts (Times Roman(R), Helvetica(R), Palatino(R) and others). The
4310 Freefonts collection (x11-fonts/freefonts) includes many more fonts, but
4311 most of them are intended for use in graphics software such as the Gimp,
4312 and are not complete enough to serve as screen fonts. In addition, XFree86
4313 can be configured to use TrueType fonts with a minimum of effort: see the
4314 section on TrueType fonts later.
4316 To install the above Type1 font collections from the ports collection, run
4317 the following commands:
4319 # cd /usr/ports/x11-fonts/urwfonts
4320 # make install clean
4322 And likewise with the freefont or other collections. To tell the X server
4323 that these fonts exist, add an appropriate line to the XF86Config file (in
4324 /etc/ for XFree86 version 3, or in /etc/X11/ for version 4), which reads:
4326 FontPath "/usr/X11R6/lib/X11/fonts/URW/"
4328 Alternatively, at the command line in the X session run:
4330 % xset fp+ /usr/X11R6/lib/X11/fonts/URW
4333 This will work but will be lost when the X session is closed, unless it is
4334 added to the startup file (~/.xinitrc for a normal startx session, or
4335 ~/.xsession when logging in through a graphical login manager like XDM). A
4336 third way is to use the new XftConfig file: see the section on
4339 ----------------------------------------------------------------------
4341 5.5.2 TrueType(R) Fonts
4343 XFree86 4.X has built in support for rendering TrueType fonts. There are
4344 two different modules that can enable this functionality. The freetype
4345 module is used in this example because it is more consistent with the
4346 other font rendering back-ends. To enable the freetype module just add the
4347 following line to the "Module" section of the /etc/X11/XF86Config file.
4351 For XFree86 3.3.X, a separate TrueType font server is needed. Xfstt is
4352 commonly used for this purpose. To install Xfstt, simply install the port
4355 Now make a directory for the TrueType fonts (for example,
4356 /usr/X11R6/lib/X11/fonts/TrueType) and copy all of the TrueType fonts into
4357 this directory. Keep in mind that TrueType fonts cannot be directly taken
4358 from a Macintosh(R); they must be in UNIX/DOS/Windows format for use by
4359 XFree86. Once the files have been copied into this directory, use ttmkfdir
4360 to create a fonts.dir file, so that the X font renderer knows that these
4361 new files have been installed. ttmkfdir is available from the FreeBSD
4362 Ports Collection as x11-fonts/ttmkfdir or the pkgsrc collection at
4365 # cd /usr/X11R6/lib/X11/fonts/TrueType
4366 # ttmkfdir > fonts.dir
4368 Now add the TrueType directory to the font path. This is just the same as
4369 described above for Type1 fonts, that is, use
4371 % xset fp+ /usr/X11R6/lib/X11/fonts/TrueType
4374 or add a FontPath line to the XF86Config file.
4376 That's it. Now Netscape, Gimp, StarOffice(TM), and all of the other X
4377 applications should now recognize the installed TrueType fonts. Extremely
4378 small fonts (as with text in a high resolution display on a web page) and
4379 extremely large fonts (within StarOffice) will look much better now.
4381 ----------------------------------------------------------------------
4383 5.5.3 Anti-Aliased Fonts
4385 Updated for XFree86 4.3 by Joe Marcus Clarke.
4387 Anti-aliasing has been available in XFree86 since 4.0.2. However, font
4388 configuration was cumbersome before the introduction of XFree86 4.3.0.
4389 Starting in version 4.3.0, all fonts in /usr/X11R6/lib/X11/fonts/ and
4390 ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware
4391 applications. Not all applications are Xft-aware yet, but many have
4392 received Xft support. Examples of Xft-aware applications include Qt 2.3
4393 and higher (the toolkit for the KDE desktop), Gtk+ 2.0 and higher (the
4394 toolkit for the GNOME desktop), and Mozilla 1.2 and higher.
4396 In order to control which fonts are anti-aliased, or to configure
4397 anti-aliasing properties, create (or edit, if it already exists) the file
4398 /usr/X11R6/etc/fonts/local.conf. Several advanced features of the Xft font
4399 system can be tuned using this file; this section describes only some
4400 simple possibilities. For more details, please see fonts-conf(5).
4402 This file must be in XML format. Pay careful attention to case, and make
4403 sure all tags are properly closed. The file begins with the usual XML
4404 header followed by a DOCTYPE definition, and then the <fontconfig> tag:
4406 <?xml version="1.0"?>
4407 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
4411 As previously stated, all fonts in /usr/X11R6/lib/X11/fonts/ as well as
4412 ~/.fonts/ are already made available to Xft-aware applications. If you
4413 wish to add another directory outside of these two directory trees, add a
4414 line similar to the following to /usr/X11R6/etc/fonts/local.conf:
4416 <dir>/path/to/my/fonts</dir>
4418 After adding new fonts, and especially new font directories, you should
4419 run the following command to rebuild the font caches:
4423 Anti-aliasing makes borders slightly fuzzy, which makes very small text
4424 more readable and removes ``staircases'' from large text, but can cause
4425 eyestrain if applied to normal text. To exclude point sizes smaller than
4426 14 point from anti-aliasing, include these lines:
4428 <match target="font">
4429 <test name="size" compare="less">
4432 <edit name="antialias" mode="assign">
4437 Spacing for some monospaced fonts may also be inappropriate with
4438 anti-aliasing. This seems to be an issue with KDE, in particular. One
4439 possible fix for this is to force the spacing for such fonts to be 100.
4440 Add the following lines:
4442 <match target="pattern" name="family">
4443 <test qual="any" name="family">
4444 <string>fixed</string>
4446 <edit name="family" mode="assign">
4447 <string>mono</string>
4450 <match target="pattern" name="family">
4451 <test qual="any" name="family">
4452 <string>console</string>
4454 <edit name="family" mode="assign">
4455 <string>mono</string>
4459 (this aliases the other common names for fixed fonts as "mono"), and then
4462 <match target="pattern" name="family">
4463 <test qual="any" name="family">
4464 <string>mono</string>
4466 <edit name="spacing" mode="assign">
4471 Certain fonts, such as Helvetica, may have a problem when anti-aliased.
4472 Usually this manifests itself as a font that seems cut in half vertically.
4473 At worst, it may cause applications such as Mozilla to crash. To avoid
4474 this, consider adding the following to local.conf:
4476 <match target="pattern" name="family">
4477 <test qual="any" name="family">
4478 <string>Helvetica</string>
4480 <edit name="family" mode="assign">
4481 <string>sans-serif</string>
4485 Once you have finished editing local.conf make sure you end the file with
4486 the </fontconfig> tag. Not doing this will cause your changes to be
4489 The default font set that comes with XFree86 is not very desirable when it
4490 comes to anti-aliasing. A much better set of default fonts can be found in
4491 the x11-fonts/bitstream-vera port. This port will install a
4492 /usr/X11R6/etc/fonts/local.conf file if one does not exist already. If the
4493 file does exist, the port will create a
4494 /usr/X11R6/etc/fonts/local.conf-vera file. Merge the contents of this file
4495 into /usr/X11R6/etc/fonts/local.conf, and the Bitstream fonts will
4496 automatically replace the default XFree86 Serif, Sans Serif, and
4499 Finally, users can add their own settings via their personal .fonts.conf
4500 files. To do this, each user should simply create a ~/.fonts.conf. This
4501 file must also be in XML format.
4503 One last point: with an LCD screen, sub-pixel sampling may be desired.
4504 This basically treats the (horizontally separated) red, green and blue
4505 components separately to improve the horizontal resolution; the results
4506 can be dramatic. To enable this, add the line somewhere in the local.conf
4509 <match target="font">
4510 <test qual="all" name="rgba">
4511 <const>unknown</const>
4513 <edit name="rgba" mode="assign">
4519 Note: Depending on the sort of display, rgb may need to be changed to
4520 bgr, vrgb or vbgr: experiment and see which works best.
4522 Anti-aliasing should be enabled the next time the X server is started.
4523 However, programs must know how to take advantage of it. At present, the
4524 Qt toolkit does, so the entire KDE environment can use anti-aliased fonts
4525 (see Section 5.7.3.2 on KDE for details). Gtk+ and GNOME can also be made
4526 to use anti-aliasing via the ``Font'' capplet (see Section 5.7.1.3 for
4527 details). By default, Mozilla 1.2 and greater will automatically use
4528 anti-aliasing. To disable this, rebuild Mozilla with the -DWITHOUT_XFT
4531 ----------------------------------------------------------------------
4533 5.6 The X Display Manager
4535 Contributed by Seth Kingsley.
4539 The X Display Manager (XDM) is an optional part of the X Window System
4540 that is used for login session management. This is useful for several
4541 types of situations, including minimal ``X Terminals'', desktops, and
4542 large network display servers. Since the X Window System is network and
4543 protocol independent, there are a wide variety of possible configurations
4544 for running X clients and servers on different machines connected by a
4545 network. XDM provides a graphical interface for choosing which display
4546 server to connect to, and entering authorization information such as a
4547 login and password combination.
4549 Think of XDM as providing the same functionality to the user as the
4550 getty(8) utility (see Section 17.3.2 for details). That is, it performs
4551 system logins to the display being connected to and then runs a session
4552 manager on behalf of the user (usually an X window manager). XDM then
4553 waits for this program to exit, signaling that the user is done and should
4554 be logged out of the display. At this point, XDM can display the login and
4555 display chooser screens for the next user to login.
4557 ----------------------------------------------------------------------
4561 The XDM daemon program is located in /usr/X11R6/bin/xdm. This program can
4562 be run at any time as root and it will start managing the X display on the
4563 local machine. If XDM is to be run every time the machine boots up, a
4564 convenient way to do this is by adding an entry to /etc/ttys. For more
4565 information about the format and usage of this file, see Section 17.3.2.1.
4566 There is a line in the default /etc/ttys file for running the XDM daemon
4567 on a virtual terminal:
4569 ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure
4571 By default this entry is disabled; in order to enable it change the fifth
4572 field from off to on and restart init(8) using the directions in Section
4573 17.3.2.2. The first field, the name of the terminal this program will
4574 manage, is ttyv8. This means that XDM will start running on the 9th
4577 ----------------------------------------------------------------------
4579 5.6.3 Configuring XDM
4581 The XDM configuration directory is located in /usr/X11R6/lib/X11/xdm. In
4582 this directory there are several files used to change the behavior and
4583 appearance of XDM. Typically these files will be found:
4586 Xaccess Client authorization ruleset.
4587 Xresources Default X resource values.
4588 Xservers List of remote and local displays to manage.
4589 Xsession Default session script for logins.
4590 Xsetup_* Script to launch applications before the login interface.
4591 xdm-config Global configuration for all displays running on this machine.
4592 xdm-errors Errors generated by the server program.
4593 xdm-pid The process ID of the currently running XDM.
4595 Also in this directory are a few scripts and programs used to set up the
4596 desktop when XDM is running. The purpose of each of these files will be
4597 briefly described. The exact syntax and usage of all of these files is
4598 described in xdm(1).
4600 The default configuration is a simple rectangular login window with the
4601 hostname of the machine displayed at the top in a large font and
4602 ``Login:'' and ``Password:'' prompts below. This is a good starting point
4603 for changing the look and feel of XDM screens.
4605 ----------------------------------------------------------------------
4609 The protocol for connecting to XDM controlled displays is called the X
4610 Display Manager Connection Protocol (XDMCP). This file is a ruleset for
4611 controlling XDMCP connections from remote machines. By default, it allows
4612 any client to connect, but that does not matter unless the xdm-config is
4613 changed to listen for remote connections.
4615 ----------------------------------------------------------------------
4619 This is an application-defaults file for the display chooser and the login
4620 screens. This is where the appearance of the login program can be
4621 modified. The format is identical to the app-defaults file described in
4622 the XFree86 documentation.
4624 ----------------------------------------------------------------------
4628 This is a list of the remote displays the chooser should provide as
4631 ----------------------------------------------------------------------
4635 This is the default session script for XDM to run after a user has logged
4636 in. Normally each user will have a customized session script in
4637 ~/.xsession that overrides this script.
4639 ----------------------------------------------------------------------
4643 These will be run automatically before displaying the chooser or login
4644 interfaces. There is a script for each display being used, named Xsetup_
4645 followed by the local display number (for instance Xsetup_0). Typically
4646 these scripts will run one or two programs in the background such as
4649 ----------------------------------------------------------------------
4653 This contains settings in the form of app-defaults that are applicable to
4654 every display that this installation manages.
4656 ----------------------------------------------------------------------
4660 This contains the output of the X servers that XDM is trying to run. If a
4661 display that XDM is trying to start hangs for some reason, this is a good
4662 place to look for error messages. These messages are also written to the
4663 user's ~/.xsession-errors file on a per-session basis.
4665 ----------------------------------------------------------------------
4667 5.6.4 Running a Network Display Server
4669 In order for other clients to connect to the display server, edit the
4670 access control rules, and enable the connection listener. By default these
4671 are set to conservative values. To make XDM listen for connections, first
4672 comment out a line in the xdm-config file:
4674 ! SECURITY: do not listen for XDMCP or Chooser requests
4675 ! Comment out this line if you want to manage X terminals with xdm
4676 DisplayManager.requestPort: 0
4678 and then restart XDM. Remember that comments in app-defaults files begin
4679 with a ``!'' character, not the usual ``#''. More strict access controls
4680 may be desired. Look at the example entries in Xaccess, and refer to the
4683 ----------------------------------------------------------------------
4685 5.6.5 Replacements for XDM
4687 Several replacements for the default XDM program exist. One of them, KDM
4688 (bundled with KDE) is described later in this chapter. KDM offers many
4689 visual improvements and cosmetic frills, as well as the functionality to
4690 allow users to choose their window manager of choice at login time.
4692 ----------------------------------------------------------------------
4694 5.7 Desktop Environments
4696 Contributed by Valentino Vaschetto.
4698 This section describes the different desktop environments available for X
4699 on DragonFly . A ``desktop environment'' can mean anything ranging from a
4700 simple window manager to a complete suite of desktop applications, such as
4703 ----------------------------------------------------------------------
4709 GNOME is a user-friendly desktop environment that enables users to easily
4710 use and configure their computers. GNOME includes a panel (for starting
4711 applications and displaying status), a desktop (where data and
4712 applications can be placed), a set of standard desktop tools and
4713 applications, and a set of conventions that make it easy for applications
4714 to cooperate and be consistent with each other. Users of other operating
4715 systems or environments should feel right at home using the powerful
4716 graphics-driven environment that GNOME provides.
4718 ----------------------------------------------------------------------
4720 5.7.1.2 Installing GNOME
4722 The easiest way to install GNOME is with a package or through the ports
4725 To install the GNOME package from the network, simply type:
4729 To build GNOME from source, use the ports tree:
4731 # cd /usr/ports/x11/gnome2
4732 # make install clean
4734 Once GNOME is installed, the X server must be told to start GNOME instead
4735 of a default window manager. If a custom .xinitrc is already in place,
4736 simply replace the line that starts the current window manager with one
4737 that starts /usr/X11R6/bin/gnome-session instead. If nothing special has
4738 been done to configuration file, then it is enough to simply type:
4740 % echo "/usr/X11R6/bin/gnome-session" > ~/.xinitrc
4742 Next, type startx, and the GNOME desktop environment will be started.
4744 Note: If a display manager, like XDM, is being used, this will not work.
4745 Instead, create an executable .xsession file with the same command in
4746 it. To do this, edit the file and replace the existing window manager
4747 command with /usr/X11R6/bin/gnome-session:
4749 % echo "#!/bin/sh" > ~/.xsession
4750 % echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession
4751 % chmod +x ~/.xsession
4753 Another option is to configure the display manager to allow choosing the
4754 window manager at login time; the section on KDE details explains how to
4755 do this for kdm, the display manager of KDE.
4757 ----------------------------------------------------------------------
4759 5.7.1.3 Anti-aliased Fonts with GNOME
4761 Starting with version 4.0.2, XFree86 supports anti-aliasing via its
4762 ``RENDER'' extension. Gtk+ 2.0 and greater (the toolkit used by GNOME) can
4763 make use of this functionality. Configuring anti-aliasing is described in
4764 Section 5.5.3. So, with up-to-date software, anti-aliasing is possible
4765 within the GNOME desktop. Just go to Applications->Desktop
4766 Preferences->Font, and select either Best shapes, Best contrast, or
4767 Subpixel smoothing (LCDs). For a Gtk+ application that is not part of the
4768 GNOME desktop, set the environment variable GDK_USE_XFT to 1 before
4769 launching the program.
4771 ----------------------------------------------------------------------
4775 ----------------------------------------------------------------------
4779 KDE is an easy to use contemporary desktop environment. Some of the things
4780 that KDE brings to the user are:
4782 * A beautiful contemporary desktop
4784 * A desktop exhibiting complete network transparency
4786 * An integrated help system allowing for convenient, consistent access
4787 to help on the use of the KDE desktop and its applications
4789 * Consistent look and feel of all KDE applications
4791 * Standardized menu and toolbars, keybindings, color-schemes, etc.
4793 * Internationalization: KDE is available in more than 40 languages
4795 * Centralized consisted dialog driven desktop configuration
4797 * A great number of useful KDE applications
4799 KDE has an office application suite based on KDE's ``KParts'' technology
4800 consisting of a spread-sheet, a presentation application, an organizer, a
4801 news client and more. KDE also comes with a web browser called Konqueror,
4802 which represents a solid competitor to other existing web browsers on UNIX
4803 systems. More information on KDE can be found on the KDE website.
4805 ----------------------------------------------------------------------
4807 5.7.2.2 Installing KDE
4809 Just as with GNOME or any other desktop environment, the easiest way to
4810 install KDE is from a package or from the ports collection:
4812 To install the KDE package from the network, simply type:
4816 pkg_add(1) will automatically fetch the latest version of the application.
4818 To build KDE from source, use the ports tree:
4820 # cd /usr/ports/x11/kde3
4821 # make install clean
4823 After KDE has been installed, the X server must be told to launch this
4824 application instead of the default window manager. This is accomplished by
4825 editing the .xinitrc file:
4827 % echo "exec startkde" > ~/.xinitrc
4829 Now, whenever the X Window System is invoked with startx, KDE will be the
4832 If a display manager such as xdm is being used, the configuration is
4833 slightly different. Edit the .xsession file instead. Instructions for kdm
4834 are described later in this chapter.
4836 ----------------------------------------------------------------------
4838 5.7.3 More Details on KDE
4840 Now that KDE is installed on the system, most things can be discovered
4841 through the help pages, or just by pointing and clicking at various menus.
4842 Windows or Mac(R) users will feel quite at home.
4844 The best reference for KDE is the on-line documentation. KDE comes with
4845 its own web browser, Konqueror, dozens of useful applications, and
4846 extensive documentation. The remainder of this section discusses the
4847 technical items that are difficult to learn by random exploration.
4849 ----------------------------------------------------------------------
4851 5.7.3.1 The KDE Display Manager
4853 An administrator of a multi-user system may wish to have a graphical login
4854 screen to welcome users. xdm can be used, as described earlier. However,
4855 KDE includes an alternative, kdm, which is designed to look more
4856 attractive and include more login-time options. In particular, users can
4857 easily choose (via a menu) which desktop environment (KDE, GNOME, or
4858 something else) to run after logging on.
4860 To begin with, run the KDE control panel, kcontrol, as root. It is
4861 generally considered unsafe to run the entire X environment as root.
4862 Instead, run the window manager as a normal user, open a terminal window
4863 (such as xterm or KDE's konsole), become root with su (the user must be in
4864 the wheel group in /etc/group for this), and then type kcontrol.
4866 Click on the icon on the left marked System, then on Login manager. On the
4867 right there are various configurable options, which the KDE manual will
4868 explain in greater detail. Click on sessions on the right. Click New type
4869 to add various window managers and desktop environments. These are just
4870 labels, so they can say KDE and GNOME rather than startkde or
4871 gnome-session. Include a label failsafe.
4873 Play with the other menus as well, they are mainly cosmetic and
4874 self-explanatory. When you are done, click on Apply at the bottom, and
4875 quit the control center.
4877 To make sure kdm understands what the labels (KDE, GNOME etc) mean, edit
4878 the files used by xdm.
4880 Note: In KDE 2.2 this has changed: kdm now uses its own configuration
4881 files. Please see the KDE 2.2 documentation for details.
4883 In a terminal window, as root, edit the file
4884 /usr/X11R6/lib/X11/xdm/Xsession. There is a section in the middle like
4891 exec xterm -geometry 80x24-0-0
4896 A few lines need to be added to this section. Assuming the labels from
4897 used were ``KDE'' and ``GNOME'', use the following:
4903 exec /usr/local/bin/startkde
4906 exec /usr/X11R6/bin/gnome-session
4909 exec xterm -geometry 80x24-0-0
4914 For the KDE login-time desktop background to be honored, the following
4915 line needs to be added to /usr/X11R6/lib/X11/xdm/Xsetup_0:
4917 /usr/local/bin/kdmdesktop
4919 Now, make sure kdm is listed in /etc/ttys to be started at the next
4920 bootup. To do this, simply follow the instructions from the previous
4921 section on xdm and replace references to the /usr/X11R6/bin/xdm program
4922 with /usr/local/bin/kdm.
4924 ----------------------------------------------------------------------
4926 5.7.3.2 Anti-aliased Fonts
4928 Starting with version 4.0.2, XFree86 supports anti-aliasing via its
4929 ``RENDER'' extension, and starting with version 2.3, Qt (the toolkit used
4930 by KDE) supports this extension. Configuring this is described in Section
4931 5.5.3 on antialiasing X11 fonts. So, with up-to-date software,
4932 anti-aliasing is possible on a KDE desktop. Just go to the KDE menu, go to
4933 Preferences->Look and Feel->Fonts, and click on the check box Use
4934 Anti-Aliasing for Fonts and Icons. For a Qt application which is not part
4935 of KDE, the environment variable QT_XFT needs to be set to true before
4936 starting the program.
4938 ----------------------------------------------------------------------
4944 XFce is a desktop environment based on the GTK toolkit used by GNOME, but
4945 is much more lightweight and meant for those who want a simple, efficient
4946 desktop which is nevertheless easy to use and configure. Visually, it
4947 looks very much like CDE, found on commercial UNIX systems. Some of XFce's
4950 * A simple, easy-to-handle desktop
4952 * Fully configurable via mouse, with drag and drop, etc
4954 * Main panel similar to CDE, with menus, applets and applications
4957 * Integrated window manager, file manager, sound manager, GNOME
4958 compliance module, and other things
4960 * Themeable (since it uses GTK)
4962 * Fast, light and efficient: ideal for older/slower machines or machines
4963 with memory limitations
4965 More information on XFce can be found on the XFce website.
4967 ----------------------------------------------------------------------
4969 5.7.4.2 Installing XFce
4971 A binary package for XFce exists (at the time of writing). To install,
4976 Alternatively, to build from source, use the ports collection:
4978 # cd /usr/ports/x11-wm/xfce4
4979 # make install clean
4981 Now, tell the X server to launch XFce the next time X is started. Simply
4984 % echo "/usr/X11R6/bin/startxfce4" > ~/.xinitrc
4986 The next time X is started, XFce will be the desktop. As before, if a
4987 display manager like xdm is being used, create an .xsession, as described
4988 in the section on GNOME, but with the /usr/X11R6/bin/startxfce4 command;
4989 or, configure the display manager to allow choosing a desktop at login
4990 time, as explained in the section on kdm.
4992 II. System Administration
4994 The remaining chapters of the DragonFly Handbook cover all aspects of
4995 DragonFly system administration. Each chapter starts by describing what
4996 you will learn as a result of reading the chapter, and also details what
4997 you are expected to know before tackling the material.
4999 These chapters are designed to be read when you need the information. You
5000 do not have to read them in any particular order, nor do you need to read
5001 all of them before you can begin using DragonFly.
5005 6 Configuration and Tuning
5007 7 The DragonFly Booting Process
5009 8 Users and Basic Account Management
5011 9 Configuring the DragonFly Kernel
5019 13 The Vinum Volume Manager
5021 14 Localization - I18N/L10N Usage and Setup
5023 15 Desktop Applications
5027 17 Serial Communications
5031 19 Advanced Networking
5035 21 Updating DragonFly
5037 22 Linux Binary Compatibility
5039 ----------------------------------------------------------------------
5041 Chapter 6 Configuration and Tuning
5043 Written by Chern Lee. Based on a tutorial written by Mike Smith. Also
5044 based on tuning(7) written by Matt Dillon.
5048 One of the important aspects of DragonFly is system configuration. Correct
5049 system configuration will help prevent headaches during future upgrades.
5050 This chapter will explain much of the DragonFly configuration process,
5051 including some of the parameters which can be set to tune a DragonFly
5054 After reading this chapter, you will know:
5056 * How to efficiently work with file systems and swap partitions.
5058 * The basics of rc.conf configuration and rc.d startup systems.
5060 * How to configure and test a network card.
5062 * How to configure virtual hosts on your network devices.
5064 * How to use the various configuration files in /etc.
5066 * How to tune DragonFly using sysctl variables.
5068 * How to tune disk performance and modify kernel limitations.
5070 Before reading this chapter, you should:
5072 * Understand UNIX and DragonFly basics (Chapter 3).
5074 * Be familiar with the basics of kernel configuration/compilation
5077 ----------------------------------------------------------------------
5079 6.2 Initial Configuration
5081 6.2.1 Partition Layout
5083 ----------------------------------------------------------------------
5085 6.2.1.1 Base Partitions
5087 When laying out file systems with disklabel(8) remember that hard drives
5088 transfer data faster from the outer tracks to the inner. Thus smaller and
5089 heavier-accessed file systems should be closer to the outside of the
5090 drive, while larger partitions like /usr should be placed toward the
5091 inner. It is a good idea to create partitions in a similar order to: root,
5094 The size of /var reflects the intended machine usage. /var is used to hold
5095 mailboxes, log files, and printer spools. Mailboxes and log files can grow
5096 to unexpected sizes depending on how many users exist and how long log
5097 files are kept. Most users would never require a gigabyte, but remember
5098 that /var/tmp must be large enough to contain packages.
5100 The /usr partition holds much of the files required to support the system,
5101 the pkgsrc collection (recommended) and the source code (optional). At
5102 least 2 gigabytes would be recommended for this partition.
5104 When selecting partition sizes, keep the space requirements in mind.
5105 Running out of space in one partition while barely using another can be a
5108 ----------------------------------------------------------------------
5110 6.2.1.2 Swap Partition
5112 As a rule of thumb, the swap partition should be about double the size of
5113 system memory (RAM). For example, if the machine has 128 megabytes of
5114 memory, the swap file should be 256 megabytes. Systems with less memory
5115 may perform better with more swap. Less than 256 megabytes of swap is not
5116 recommended and memory expansion should be considered. The kernel's VM
5117 paging algorithms are tuned to perform best when the swap partition is at
5118 least two times the size of main memory. Configuring too little swap can
5119 lead to inefficiencies in the VM page scanning code and might create
5120 issues later if more memory is added.
5122 On larger systems with multiple SCSI disks (or multiple IDE disks
5123 operating on different controllers), it is recommend that a swap is
5124 configured on each drive (up to four drives). The swap partitions should
5125 be approximately the same size. The kernel can handle arbitrary sizes but
5126 internal data structures scale to 4 times the largest swap partition.
5127 Keeping the swap partitions near the same size will allow the kernel to
5128 optimally stripe swap space across disks. Large swap sizes are fine, even
5129 if swap is not used much. It might be easier to recover from a runaway
5130 program before being forced to reboot.
5132 ----------------------------------------------------------------------
5134 6.2.1.3 Why Partition?
5136 Several users think a single large partition will be fine, but there are
5137 several reasons why this is a bad idea. First, each partition has
5138 different operational characteristics and separating them allows the file
5139 system to tune accordingly. For example, the root and /usr partitions are
5140 read-mostly, without much writing. While a lot of reading and writing
5141 could occur in /var and /var/tmp.
5143 By properly partitioning a system, fragmentation introduced in the smaller
5144 write heavy partitions will not bleed over into the mostly-read
5145 partitions. Keeping the write-loaded partitions closer to the disk's edge,
5146 will increase I/O performance in the partitions where it occurs the most.
5147 Now while I/O performance in the larger partitions may be needed, shifting
5148 them more toward the edge of the disk will not lead to a significant
5149 performance improvement over moving /var to the edge. Finally, there are
5150 safety concerns. A smaller, neater root partition which is mostly
5151 read-only has a greater chance of surviving a bad crash.
5153 ----------------------------------------------------------------------
5155 6.3 Core Configuration
5157 The principal location for system configuration information is within
5158 /etc/rc.conf. This file contains a wide range of configuration
5159 information, principally used at system startup to configure the system.
5160 Its name directly implies this; it is configuration information for the
5163 An administrator should make entries in the rc.conf file to override the
5164 default settings from /etc/defaults/rc.conf. The defaults file should not
5165 be copied verbatim to /etc - it contains default values, not examples. All
5166 system-specific changes should be made in the rc.conf file itself.
5168 A number of strategies may be applied in clustered applications to
5169 separate site-wide configuration from system-specific configuration in
5170 order to keep administration overhead down. The recommended approach is to
5171 place site-wide configuration into another file, such as
5172 /etc/rc.conf.site, and then include this file into /etc/rc.conf, which
5173 will contain only system-specific information.
5175 As rc.conf is read by sh(1) it is trivial to achieve this. For example:
5180 hostname="node15.example.com"
5181 network_interfaces="fxp0 lo0"
5182 ifconfig_fxp0="inet 10.1.1.1"
5186 defaultrouter="10.1.1.254"
5190 The rc.conf.site file can then be distributed to every system using rsync
5191 or a similar program, while the rc.conf file remains unique.
5193 Upgrading the system using make world will not overwrite the rc.conf file,
5194 so system configuration information will not be lost.
5196 ----------------------------------------------------------------------
5198 6.4 Application Configuration
5200 Typically, installed applications have their own configuration files, with
5201 their own syntax, etc. It is important that these files be kept separate
5202 from the base system, so that they may be easily located and managed by
5203 the package management tools.
5205 Typically, these files are installed in /usr/local/etc. In the case where
5206 an application has a large number of configuration files, a subdirectory
5207 will be created to hold them.
5209 Normally, when a port or package is installed, sample configuration files
5210 are also installed. These are usually identified with a .default suffix.
5211 If there are no existing configuration files for the application, they
5212 will be created by copying the .default files.
5214 For example, consider the contents of the directory /usr/local/etc/apache:
5216 -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf
5217 -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default
5218 -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf
5219 -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default
5220 -rw-r--r-- 1 root wheel 12205 May 20 1998 magic
5221 -rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default
5222 -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types
5223 -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default
5224 -rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
5225 -rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default
5227 The file sizes show that only the srm.conf file has been changed. A later
5228 update of the Apache port would not overwrite this changed file.
5230 ----------------------------------------------------------------------
5232 6.5 Starting Services
5234 It is common for a system to host a number of services. These may be
5235 started in several different fashions, each having different advantages.
5237 Software installed from a port or the packages collection will often place
5238 a script in /usr/local/etc/rc.d which is invoked at system startup with a
5239 start argument, and at system shutdown with a stop argument. This is the
5240 recommended way for starting system-wide services that are to be run as
5241 root, or that expect to be started as root. These scripts are registered
5242 as part of the installation of the package, and will be removed when the
5245 A generic startup script in /usr/local/etc/rc.d looks like:
5252 /usr/local/bin/foobar
5255 kill -9 `cat /var/run/foobar.pid`
5258 echo "Usage: `basename $0` {start|stop}" >&2
5266 The startup scripts of DragonFly will look in /usr/local/etc/rc.d for
5267 scripts that have an .sh extension and are executable by root. Those
5268 scripts that are found are called with an option start at startup, and
5269 stop at shutdown to allow them to carry out their purpose. So if you
5270 wanted the above sample script to be picked up and run at the proper time
5271 during system startup, you should save it to a file called FooBar.sh in
5272 /usr/local/etc/rc.d and make sure it is executable. You can make a shell
5273 script executable with chmod(1) as shown below:
5275 # chmod 755 FooBar.sh
5277 Some services expect to be invoked by inetd(8) when a connection is
5278 received on a suitable port. This is common for mail reader servers (POP
5279 and IMAP, etc.). These services are enabled by editing the file
5280 /etc/inetd.conf. See inetd(8) for details on editing this file.
5282 Some additional system services may not be covered by the toggles in
5283 /etc/rc.conf. These are traditionally enabled by placing the command(s) to
5284 invoke them in /etc/rc.local (which does not exist by default). Note that
5285 rc.local is generally regarded as the location of last resort; if there is
5286 a better place to start a service, do it there.
5288 Note: Do not place any commands in /etc/rc.conf. To start daemons, or
5289 run any commands at boot time, place a script in /usr/local/etc/rc.d
5292 It is also possible to use the cron(8) daemon to start system services.
5293 This approach has a number of advantages, not least being that because
5294 cron(8) runs these processes as the owner of the crontab, services may be
5295 started and maintained by non-root users.
5297 This takes advantage of a feature of cron(8): the time specification may
5298 be replaced by @reboot, which will cause the job to be run when cron(8) is
5299 started shortly after system boot.
5301 ----------------------------------------------------------------------
5303 6.6 Configuring the cron Utility
5305 Contributed by Tom Rhodes.
5307 One of the most useful utilities in DragonFly is cron(8). The cron utility
5308 runs in the background and constantly checks the /etc/crontab file. The
5309 cron utility also checks the /var/cron/tabs directory, in search of new
5310 crontab files. These crontab files store information about specific
5311 functions which cron is supposed to perform at certain times.
5313 The cron utility uses two different types of configuration files, the
5314 system crontab and user crontabs. The only difference between these two
5315 formats is the sixth field. In the system crontab, the sixth field is the
5316 name of a user for the command to run as. This gives the system crontab
5317 the ability to run commands as any user. In a user crontab, the sixth
5318 field is the command to run, and all commands run as the user who created
5319 the crontab; this is an important security feature.
5321 Note: User crontabs allow individual users to schedule tasks without the
5322 need for root privileges. Commands in a user's crontab run with the
5323 permissions of the user who owns the crontab.
5325 The root user can have a user crontab just like any other user. This one
5326 is different from /etc/crontab (the system crontab). Because of the
5327 system crontab, there's usually no need to create a user crontab for
5330 Let us take a look at the /etc/crontab file (the system crontab):
5332 # /etc/crontab - root's crontab for DragonFly
5337 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin (2)
5341 #minute hour mday month wday who command (3)
5344 */5 * * * * root /usr/libexec/atrun (4)
5347 Like most DragonFly configuration files, the # character
5348 represents a comment. A comment can be placed in the file as a
5349 reminder of what and why a desired action is performed. Comments
5350 cannot be on the same line as a command or else they will be
5351 interpreted as part of the command; they must be on a new line.
5352 Blank lines are ignored.
5354 First, the environment must be defined. The equals (=) character
5355 is used to define any environment settings, as with this example
5356 where it is used for the SHELL, PATH, and HOME options. If the
5357 shell line is omitted, cron will use the default, which is sh. If
5358 the PATH variable is omitted, no default will be used and file
5359 locations will need to be absolute. If HOME is omitted, cron will
5360 use the invoking users home directory.
5362 This line defines a total of seven fields. Listed here are the
5363 values minute, hour, mday, month, wday, who, and command. These
5364 are almost all self explanatory. minute is the time in minutes the
5365 command will be run. hour is similar to the minute option, just in
5366 hours. mday stands for day of the month. month is similar to hour
5367 and minute, as it designates the month. The wday option stands for
5368 day of the week. All these fields must be numeric values, and
5369 follow the twenty-four hour clock. The who field is special, and
5370 only exists in the /etc/crontab file. This field specifies which
5371 user the command should be run as. When a user installs his or her
5372 crontab file, they will not have this option. Finally, the command
5373 option is listed. This is the last field, so naturally it should
5374 designate the command to be executed.
5376 This last line will define the values discussed above. Notice here
5377 we have a */5 listing, followed by several more * characters.
5378 These * characters mean ``first-last'', and can be interpreted as
5379 every time. So, judging by this line, it is apparent that the
5380 atrun command is to be invoked by root every five minutes
5381 regardless of what day or month it is. For more information on the
5382 atrun command, see the atrun(8) manual page.
5384 Commands can have any number of flags passed to them; however,
5385 commands which extend to multiple lines need to be broken with the
5386 backslash ``\'' continuation character.
5388 This is the basic set up for every crontab file, although there is one
5389 thing different about this one. Field number six, where we specified the
5390 username, only exists in the system /etc/crontab file. This field should
5391 be omitted for individual user crontab files.
5393 ----------------------------------------------------------------------
5395 6.6.1 Installing a Crontab
5397 Important: You must not use the procedure described here to edit/install
5398 the system crontab. Simply use your favorite editor: the cron utility
5399 will notice that the file has changed and immediately begin using the
5400 updated version. If you use crontab to load the /etc/crontab file you
5401 may get an error like ``root: not found'' because of the system
5402 crontab's additional user field.
5404 To install a freshly written user crontab, first use your favorite editor
5405 to create a file in the proper format, and then use the crontab utility.
5406 The most common usage is:
5408 % crontab crontab-file
5410 In this example, crontab-file is the filename of a crontab that was
5413 There is also an option to list installed crontab files: just pass the -l
5414 option to crontab and look over the output.
5416 For users who wish to begin their own crontab file from scratch, without
5417 the use of a template, the crontab -e option is available. This will
5418 invoke the selected editor with an empty file. When the file is saved, it
5419 will be automatically installed by the crontab command.
5421 If you later want to remove your user crontab completely, use crontab with
5424 ----------------------------------------------------------------------
5426 6.7 Using rc under DragonFly
5428 Contributed by Tom Rhodes.
5430 DragonFly uses the NetBSD rc.d system for system initialization. Users
5431 should notice the files listed in the /etc/rc.d directory. Many of these
5432 files are for basic services which can be controlled with the start, stop,
5433 and restart options. For instance, sshd(8) can be restarted with the
5436 # /etc/rc.d/sshd restart
5438 This procedure is similar for other services. Of course, services are
5439 usually started automatically as specified in rc.conf(5). For example,
5440 enabling the Network Address Translation daemon at startup is as simple as
5441 adding the following line to /etc/rc.conf:
5445 If a natd_enable="NO" line is already present, then simply change the NO
5446 to YES. The rc scripts will automatically load any other dependent
5447 services during the next reboot, as described below.
5449 Since the rc.d system is primarily intended to start/stop services at
5450 system startup/shutdown time, the standard start, stop and restart options
5451 will only perform their action if the appropriate /etc/rc.conf variables
5452 are set. For instance the above sshd restart command will only work if
5453 sshd_enable is set to YES in /etc/rc.conf. To start, stop or restart a
5454 service regardless of the settings in /etc/rc.conf, the commands should be
5455 prefixed with ``force''. For instance to restart sshd regardless of the
5456 current /etc/rc.conf setting, execute the following command:
5458 # /etc/rc.d/sshd forcerestart
5460 It is easy to check if a service is enabled in /etc/rc.conf by running the
5461 appropriate rc.d script with the option rcvar. Thus, an administrator can
5462 check that sshd is in fact enabled in /etc/rc.conf by running:
5464 # /etc/rc.d/sshd rcvar
5468 Note: The second line (# sshd) is the output from the rc.d script, not a
5471 To determine if a service is running, a status option is available. For
5472 instance to verify that sshd is actually started:
5474 # /etc/rc.d/sshd status
5475 sshd is running as pid 433.
5477 It is also possible to reload a service. This will attempt to send a
5478 signal to an individual service, forcing the service to reload its
5479 configuration files. In most cases this means sending the service a SIGHUP
5482 The rcNG structure is used both for network services and system
5483 initialization. Some services are run only at boot; and the RCNG system is
5486 Many system services depend on other services to function properly. For
5487 example, NIS and other RPC-based services may fail to start until after
5488 the rpcbind (portmapper) service has started. To resolve this issue,
5489 information about dependencies and other meta-data is included in the
5490 comments at the top of each startup script. The rcorder(8) program is then
5491 used to parse these comments during system initialization to determine the
5492 order in which system services should be invoked to satisfy the
5493 dependencies. The following words may be included at the top of each
5496 * PROVIDE: Specifies the services this file provides.
5498 * REQUIRE: Lists services which are required for this service. This file
5499 will run after the specified services.
5501 * BEFORE: Lists services which depend on this service. This file will
5502 run before the specified services.
5504 * KEYWORD: When rcorder(8) uses the -k option, then only the rc.d files
5505 matching this keyword are used. [5] For example, when using -k
5506 shutdown, only the rc.d scripts defining the shutdown keyword are
5509 With the -s option, rcorder(8) will skip any rc.d script defining the
5510 corresponding keyword to skip. For example, scripts defining the
5511 nostart keyword are skipped at boot time.
5513 By using this method, an administrator can easily control system services
5514 without the hassle of ``runlevels'' like some other UNIX operating
5517 Additional information about the DragonFly rc.d system can be found in the
5518 rc(8), rc.conf(5), and rc.subr(8) manual pages.
5520 ----------------------------------------------------------------------
5522 6.8 Setting Up Network Interface Cards
5524 Contributed by Marc Fonvieille.
5526 Nowadays we can not think about a computer without thinking about a
5527 network connection. Adding and configuring a network card is a common task
5528 for any DragonFly administrator.
5530 ----------------------------------------------------------------------
5532 6.8.1 Locating the Correct Driver
5534 Before you begin, you should know the model of the card you have, the chip
5535 it uses, and whether it is a PCI or ISA card. DragonFly supports a wide
5536 variety of both PCI and ISA cards. Check the Hardware Compatibility List
5537 for your release to see if your card is supported.
5539 Once you are sure your card is supported, you need to determine the proper
5540 driver for the card. The file /usr/src/sys/i386/conf/LINT will give you
5541 the list of network interfaces drivers with some information about the
5542 supported chipsets/cards. If you have doubts about which driver is the
5543 correct one, read the manual page of the driver. The manual page will give
5544 you more information about the supported hardware and even the possible
5545 problems that could occur.
5547 If you own a common card, most of the time you will not have to look very
5548 hard for a driver. Drivers for common network cards are present in the
5549 GENERIC kernel, so your card should show up during boot, like so:
5551 dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
5552 000ff irq 15 at device 11.0 on pci0
5553 dc0: Ethernet address: 00:a0:cc:da:da:da
5554 miibus0: <MII bus> on dc0
5555 ukphy0: <Generic IEEE 802.3u media interface> on miibus0
5556 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
5557 dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
5558 000ff irq 11 at device 12.0 on pci0
5559 dc1: Ethernet address: 00:a0:cc:da:da:db
5560 miibus1: <MII bus> on dc1
5561 ukphy1: <Generic IEEE 802.3u media interface> on miibus1
5562 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
5564 In this example, we see that two cards using the dc(4) driver are present
5567 To use your network card, you will need to load the proper driver. This
5568 may be accomplished in one of two ways. The easiest way is to simply load
5569 a kernel module for your network card with kldload(8). A module is not
5570 available for all network card drivers (ISA cards and cards using the
5571 ed(4) driver, for example). Alternatively, you may statically compile the
5572 support for your card into your kernel. Check /usr/src/sys/i386/conf/LINT
5573 and the manual page of the driver to know what to add in your kernel
5574 configuration file. For more information about recompiling your kernel,
5575 please see Chapter 9. If your card was detected at boot by your kernel
5576 (GENERIC) you do not have to build a new kernel.
5578 ----------------------------------------------------------------------
5580 6.8.2 Configuring the Network Card
5582 Once the right driver is loaded for the network card, the card needs to be
5583 configured. As with many other things, the network card may have been
5584 configured at installation time.
5586 To display the configuration for the network interfaces on your system,
5587 enter the following command:
5590 dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
5591 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
5592 ether 00:a0:cc:da:da:da
5593 media: Ethernet autoselect (100baseTX <full-duplex>)
5595 dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
5596 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
5597 ether 00:a0:cc:da:da:db
5598 media: Ethernet 10baseT/UTP
5600 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
5601 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
5602 inet 127.0.0.1 netmask 0xff000000
5603 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
5605 Note: Note that entries concerning IPv6 (inet6 etc.) were omitted in
5608 In this example, the following devices were displayed:
5610 * dc0: The first Ethernet interface
5612 * dc1: The second Ethernet interface
5614 * lp0: The parallel port interface
5616 * lo0: The loopback device
5618 * tun0: The tunnel device used by ppp
5620 DragonFly uses the driver name followed by the order in which one the card
5621 is detected at the kernel boot to name the network card, starting the
5622 count at zero. For example, sis2 would be the third network card on the
5623 system using the sis(4) driver.
5625 In this example, the dc0 device is up and running. The key indicators are:
5627 1. UP means that the card is configured and ready.
5629 2. The card has an Internet (inet) address (in this case 192.168.1.3).
5631 3. It has a valid subnet mask (netmask; 0xffffff00 is the same as
5634 4. It has a valid broadcast address (in this case, 192.168.1.255).
5636 5. The MAC address of the card (ether) is 00:a0:cc:da:da:da
5638 6. The physical media selection is on autoselection mode (media: Ethernet
5639 autoselect (100baseTX <full-duplex>)). We see that dc1 was configured
5640 to run with 10baseT/UTP media. For more information on available media
5641 types for a driver, please refer to its manual page.
5643 7. The status of the link (status) is active, i.e. the carrier is
5644 detected. For dc1, we see status: no carrier. This is normal when an
5645 Ethernet cable is not plugged into the card.
5647 If the ifconfig(8) output had shown something similar to:
5649 dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
5650 ether 00:a0:cc:da:da:da
5652 it would indicate the card has not been configured.
5654 To configure your card, you need root privileges. The network card
5655 configuration can be done from the command line with ifconfig(8) as root.
5657 # ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
5659 Manually configuring the care has the disadvantage that you would have to
5660 do it after each reboot of the system. The file /etc/rc.conf is where to
5661 add the network card's configuration.
5663 Open /etc/rc.conf in your favorite editor. You need to add a line for each
5664 network card present on the system, for example in our case, we added
5667 ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
5668 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
5670 You have to replace dc0, dc1, and so on, with the correct device for your
5671 cards, and the addresses with the proper ones. You should read the card
5672 driver and ifconfig(8) manual pages for more details about the allowed
5673 options and also rc.conf(5) manual page for more information on the syntax
5676 If you configured the network during installation, some lines about the
5677 network card(s) may be already present. Double check /etc/rc.conf before
5680 You will also have to edit the file /etc/hosts to add the names and the IP
5681 addresses of various machines of the LAN, if they are not already there.
5682 For more information please refer to hosts(5) and to
5683 /usr/share/examples/etc/hosts.
5685 ----------------------------------------------------------------------
5687 6.8.3 Testing and Troubleshooting
5689 Once you have made the necessary changes in /etc/rc.conf, you should
5690 reboot your system. This will allow the change(s) to the interface(s) to
5691 be applied, and verify that the system restarts without any configuration
5694 Once the system has been rebooted, you should test the network interfaces.
5696 ----------------------------------------------------------------------
5698 6.8.3.1 Testing the Ethernet Card
5700 To verify that an Ethernet card is configured correctly, you have to try
5701 two things. First, ping the interface itself, and then ping another
5704 First test the local interface:
5706 % ping -c5 192.168.1.3
5707 PING 192.168.1.3 (192.168.1.3): 56 data bytes
5708 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
5709 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
5710 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
5711 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
5712 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
5714 --- 192.168.1.3 ping statistics ---
5715 5 packets transmitted, 5 packets received, 0% packet loss
5716 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
5718 Now we have to ping another machine on the LAN:
5720 % ping -c5 192.168.1.2
5721 PING 192.168.1.2 (192.168.1.2): 56 data bytes
5722 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
5723 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
5724 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
5725 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
5726 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
5728 --- 192.168.1.2 ping statistics ---
5729 5 packets transmitted, 5 packets received, 0% packet loss
5730 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
5732 You could also use the machine name instead of 192.168.1.2 if you have set
5733 up the /etc/hosts file.
5735 ----------------------------------------------------------------------
5737 6.8.3.2 Troubleshooting
5739 Troubleshooting hardware and software configurations is always a pain, and
5740 a pain which can be alleviated by checking the simple things first. Is
5741 your network cable plugged in? Have you properly configured the network
5742 services? Did you configure the firewall correctly? Is the card you are
5743 using supported by DragonFly? Always check the hardware notes before
5744 sending off a bug report. Update your version of DragonFly to the latest
5745 PREVIEW version. Check the mailing list archives, or perhaps search the
5748 If the card works, yet performance is poor, it would be worthwhile to read
5749 over the tuning(7) manual page. You can also check the network
5750 configuration as incorrect network settings can cause slow connections.
5752 Some users experience one or two ``device timeouts'', which is normal for
5753 some cards. If they continue, or are bothersome, you may wish to be sure
5754 the device is not conflicting with another device. Double check the cable
5755 connections. Perhaps you may just need to get another card.
5757 At times, users see a few ``watchdog timeout'' errors. The first thing to
5758 do here is to check your network cable. Many cards require a PCI slot
5759 which supports Bus Mastering. On some old motherboards, only one PCI slot
5760 allows it (usually slot 0). Check the network card and the motherboard
5761 documentation to determine if that may be the problem.
5763 ``No route to host'' messages occur if the system is unable to route a
5764 packet to the destination host. This can happen if no default route is
5765 specified, or if a cable is unplugged. Check the output of netstat -rn and
5766 make sure there is a valid route to the host you are trying to reach. If
5767 there is not, read on to Chapter 19.
5769 ``ping: sendto: Permission denied'' error messages are often caused by a
5770 misconfigured firewall. If ipfw is enabled in the kernel but no rules have
5771 been defined, then the default policy is to deny all traffic, even ping
5772 requests! Read on to Section 10.7 for more information.
5774 Sometimes performance of the card is poor, or below average. In these
5775 cases it is best to set the media selection mode from autoselect to the
5776 correct media selection. While this usually works for most hardware, it
5777 may not resolve this issue for everyone. Again, check all the network
5778 settings, and read over the tuning(7) manual page.
5780 ----------------------------------------------------------------------
5784 A very common use of DragonFly is virtual site hosting, where one server
5785 appears to the network as many servers. This is achieved by assigning
5786 multiple network addresses to a single interface.
5788 A given network interface has one ``real'' address, and may have any
5789 number of ``alias'' addresses. These aliases are normally added by placing
5790 alias entries in /etc/rc.conf.
5792 An alias entry for the interface fxp0 looks like:
5794 ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
5796 Note that alias entries must start with alias0 and proceed upwards in
5797 order, (for example, _alias1, _alias2, and so on). The configuration
5798 process will stop at the first missing number.
5800 The calculation of alias netmasks is important, but fortunately quite
5801 simple. For a given interface, there must be one address which correctly
5802 represents the network's netmask. Any other addresses which fall within
5803 this network must have a netmask of all 1s (expressed as either
5804 255.255.255.255 or 0xffffffff).
5806 For example, consider the case where the fxp0 interface is connected to
5807 two networks, the 10.1.1.0 network with a netmask of 255.255.255.0 and the
5808 202.0.75.16 network with a netmask of 255.255.255.240. We want the system
5809 to appear at 10.1.1.1 through 10.1.1.5 and at 202.0.75.17 through
5810 202.0.75.20. As noted above, only the first address in a given network
5811 range (in this case, 10.0.1.1 and 202.0.75.17) should have a real netmask;
5812 all the rest (10.1.1.2 through 10.1.1.5 and 202.0.75.18 through
5813 202.0.75.20) must be configured with a netmask of 255.255.255.255.
5815 The following entries configure the adapter correctly for this
5818 ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
5819 ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
5820 ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
5821 ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
5822 ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
5823 ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
5824 ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
5825 ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
5826 ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
5828 ----------------------------------------------------------------------
5830 6.10 Configuration Files
5834 There are a number of directories in which configuration information is
5835 kept. These include:
5837 /etc Generic system configuration information; data here is
5839 /etc/defaults Default versions of system configuration files.
5840 /etc/mail Extra sendmail(8) configuration, other MTA
5841 configuration files.
5842 /etc/ppp Configuration for both user- and kernel-ppp programs.
5843 /etc/namedb Default location for named(8) data. Normally
5844 named.conf and zone files are stored here.
5845 /usr/local/etc Configuration files for installed applications. May
5846 contain per-application subdirectories.
5847 /usr/local/etc/rc.d Start/stop scripts for installed applications.
5848 Automatically generated system-specific database
5849 /var/db files, such as the package database, the locate
5852 ----------------------------------------------------------------------
5856 ----------------------------------------------------------------------
5858 6.10.2.1 /etc/resolv.conf
5860 /etc/resolv.conf dictates how DragonFly's resolver accesses the Internet
5861 Domain Name System (DNS).
5863 The most common entries to resolv.conf are:
5865 The IP address of a name server the resolver should query. The
5866 nameserver servers are queried in the order listed with a maximum of
5868 search Search list for hostname lookup. This is normally determined by
5869 the domain of the local hostname.
5870 domain The local domain name.
5872 A typical resolv.conf:
5875 nameserver 147.11.1.11
5876 nameserver 147.11.100.30
5878 Note: Only one of the search and domain options should be used.
5880 If you are using DHCP, dhclient(8) usually rewrites resolv.conf with
5881 information received from the DHCP server.
5883 ----------------------------------------------------------------------
5887 /etc/hosts is a simple text database reminiscent of the old Internet. It
5888 works in conjunction with DNS and NIS providing name to IP address
5889 mappings. Local computers connected via a LAN can be placed in here for
5890 simplistic naming purposes instead of setting up a named(8) server.
5891 Additionally, /etc/hosts can be used to provide a local record of Internet
5892 names, reducing the need to query externally for commonly accessed names.
5896 # This file should contain the addresses and aliases
5897 # for local hosts that share this file.
5898 # In the presence of the domain name service or NIS, this file may
5899 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
5902 ::1 localhost localhost.my.domain myname.my.domain
5903 127.0.0.1 localhost localhost.my.domain myname.my.domain
5906 # Imaginary network.
5907 #10.0.0.2 myname.my.domain myname
5908 #10.0.0.3 myfriend.my.domain myfriend
5910 # According to RFC 1918, you can use the following IP networks for
5911 # private nets which will never be connected to the Internet:
5913 # 10.0.0.0 - 10.255.255.255
5914 # 172.16.0.0 - 172.31.255.255
5915 # 192.168.0.0 - 192.168.255.255
5917 # In case you want to be able to connect to the Internet, you need
5918 # real official assigned numbers. PLEASE PLEASE PLEASE do not try
5919 # to invent your own network numbers but instead get one from your
5920 # network provider (if any) or from the Internet Registry (ftp to
5921 # rs.internic.net, directory `/templates').
5924 /etc/hosts takes on the simple format of:
5926 [Internet address] [official hostname] [alias1] [alias2] ...
5930 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
5932 Consult hosts(5) for more information.
5934 ----------------------------------------------------------------------
5936 6.10.3 Log File Configuration
5938 ----------------------------------------------------------------------
5940 6.10.3.1 syslog.conf
5942 syslog.conf is the configuration file for the syslogd(8) program. It
5943 indicates which types of syslog messages are logged to particular log
5947 # Spaces ARE valid field separators in this file. However,
5948 # other *nix-like systems still insist on using tabs as field
5949 # separators. If you are sharing this file between systems, you
5950 # may want to use only tabs as field separators here.
5951 # Consult the syslog.conf(5) manual page.
5952 *.err;kern.debug;auth.notice;mail.crit /dev/console
5953 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
5954 security.* /var/log/security
5955 mail.info /var/log/maillog
5956 lpr.info /var/log/lpd-errs
5957 cron.* /var/log/cron
5959 *.notice;news.err root
5962 # uncomment this to log all writes to /dev/console to /var/log/console.log
5963 #console.info /var/log/console.log
5964 # uncomment this to enable logging of all log messages to /var/log/all.log
5965 #*.* /var/log/all.log
5966 # uncomment this to enable logging to a remote log host named loghost
5968 # uncomment these if you're running inn
5969 # news.crit /var/log/news/news.crit
5970 # news.err /var/log/news/news.err
5971 # news.notice /var/log/news/news.notice
5973 *.* /var/log/slip.log
5975 *.* /var/log/ppp.log
5977 Consult the syslog.conf(5) manual page for more information.
5979 ----------------------------------------------------------------------
5981 6.10.3.2 newsyslog.conf
5983 newsyslog.conf is the configuration file for newsyslog(8), a program that
5984 is normally scheduled to run by cron(8). newsyslog(8) determines when log
5985 files require archiving or rearranging. logfile is moved to logfile.0,
5986 logfile.0 is moved to logfile.1, and so on. Alternatively, the log files
5987 may be archived in gzip(1) format causing them to be named: logfile.0.gz,
5988 logfile.1.gz, and so on.
5990 newsyslog.conf indicates which log files are to be managed, how many are
5991 to be kept, and when they are to be touched. Log files can be rearranged
5992 and/or archived when they have either reached a certain size, or at a
5993 certain periodic time/date.
5995 # configuration file for newsyslog
5997 # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
5998 /var/log/cron 600 3 100 * Z
5999 /var/log/amd.log 644 7 100 * Z
6000 /var/log/kerberos.log 644 7 100 * Z
6001 /var/log/lpd-errs 644 7 100 * Z
6002 /var/log/maillog 644 7 * @T00 Z
6003 /var/log/sendmail.st 644 10 * 168 B
6004 /var/log/messages 644 5 100 * Z
6005 /var/log/all.log 600 7 * @T00 Z
6006 /var/log/slip.log 600 3 100 * Z
6007 /var/log/ppp.log 600 3 100 * Z
6008 /var/log/security 600 10 100 * Z
6009 /var/log/wtmp 644 3 * @01T05 B
6010 /var/log/daily.log 640 7 * @T00 Z
6011 /var/log/weekly.log 640 5 1 $W6D0 Z
6012 /var/log/monthly.log 640 12 * $M1D0 Z
6013 /var/log/console.log 640 5 100 * Z
6015 Consult the newsyslog(8) manual page for more information.
6017 ----------------------------------------------------------------------
6021 sysctl.conf looks much like rc.conf. Values are set in a variable=value
6022 form. The specified values are set after the system goes into multi-user
6023 mode. Not all variables are settable in this mode.
6025 A sample sysctl.conf turning off logging of fatal signal exits and letting
6026 Linux programs know they are really running under DragonFly:
6028 kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
6029 compat.linux.osname=DragonFly
6030 compat.linux.osrelease=4.3-STABLE
6032 ----------------------------------------------------------------------
6034 6.11 Tuning with sysctl
6036 sysctl(8) is an interface that allows you to make changes to a running
6037 DragonFly system. This includes many advanced options of the TCP/IP stack
6038 and virtual memory system that can dramatically improve performance for an
6039 experienced system administrator. Over five hundred system variables can
6040 be read and set using sysctl(8).
6042 At its core, sysctl(8) serves two functions: to read and to modify system
6045 To view all readable variables:
6049 To read a particular variable, for example, kern.maxproc:
6051 % sysctl kern.maxproc
6054 To set a particular variable, use the intuitive variable=value syntax:
6056 # sysctl kern.maxfiles=5000
6057 kern.maxfiles: 2088 -> 5000
6059 Settings of sysctl variables are usually either strings, numbers, or
6060 booleans (a boolean being 1 for yes or a 0 for no).
6062 If you want to set automatically some variables each time the machine
6063 boots, add them to the /etc/sysctl.conf file. For more information see the
6064 sysctl.conf(5) manual page and the Section 6.10.4.
6066 ----------------------------------------------------------------------
6068 6.11.1 sysctl(8) Read-only
6070 Contributed by Tom Rhodes.
6072 In some cases it may be desirable to modify read-only sysctl(8) values.
6073 While this is not recommended, it is also sometimes unavoidable.
6075 For instance on some laptop models the cardbus(4) device will not probe
6076 memory ranges, and fail with errors which look similar to:
6078 cbb0: Could not map register memory
6079 device_probe_and_attach: cbb0 attach returned 12
6081 Cases like the one above usually require the modification of some default
6082 sysctl(8) settings which are set read only. To overcome these situations a
6083 user can put sysctl(8) ``OIDs'' in their local /boot/loader.conf. Default
6084 settings are located in the /boot/defaults/loader.conf file.
6086 Fixing the problem mentioned above would require a user to set
6087 hw.pci.allow_unsupported_io_range=1 in the aforementioned file. Now
6088 cardbus(4) will work properly.
6090 ----------------------------------------------------------------------
6094 6.12.1 Sysctl Variables
6096 6.12.1.1 vfs.vmiodirenable
6098 The vfs.vmiodirenable sysctl variable may be set to either 0 (off) or 1
6099 (on); it is 1 by default. This variable controls how directories are
6100 cached by the system. Most directories are small, using just a single
6101 fragment (typically 1 K) in the file system and less (typically 512 bytes)
6102 in the buffer cache. With this variable turned off (to 0), the buffer
6103 cache will only cache a fixed number of directories even if ou have a huge
6104 amount of memory. When turned on (to 1), this sysctl allows the buffer
6105 cache to use the VM Page Cache to cache the directories, making all the
6106 memory available for caching directories. However, the minimum in-core
6107 memory used to cache a directory is the physical page size (typically 4 K)
6108 rather than 512 bytes. We recommend keeping this option on if you are
6109 running any services which manipulate large numbers of files. Such
6110 services can include web caches, large mail systems, and news systems.
6111 Keeping this option on will generally not reduce performance even with the
6112 wasted memory but you should experiment to find out.
6114 ----------------------------------------------------------------------
6116 6.12.1.2 vfs.write_behind
6118 The vfs.write_behind sysctl variable defaults to 1 (on). This tells the
6119 file system to issue media writes as full clusters are collected, which
6120 typically occurs when writing large sequential files. The idea is to avoid
6121 saturating the buffer cache with dirty buffers when it would not benefit
6122 I/O performance. However, this may stall processes and under certain
6123 circumstances you may wish to turn it off.
6125 ----------------------------------------------------------------------
6127 6.12.1.3 vfs.hirunningspace
6129 The vfs.hirunningspace sysctl variable determines how much outstanding
6130 write I/O may be queued to disk controllers system-wide at any given
6131 instance. The default is usually sufficient but on machines with lots of
6132 disks you may want to bump it up to four or five megabytes. Note that
6133 setting too high a value (exceeding the buffer cache's write threshold)
6134 can lead to extremely bad clustering performance. Do not set this value
6135 arbitrarily high! Higher write values may add latency to reads occurring
6138 There are various other buffer-cache and VM page cache related sysctls. We
6139 do not recommend modifying these values. The VM system does an extremely
6140 good job of automatically tuning itself.
6142 ----------------------------------------------------------------------
6144 6.12.1.4 vm.swap_idle_enabled
6146 The vm.swap_idle_enabled sysctl variable is useful in large multi-user
6147 systems where you have lots of users entering and leaving the system and
6148 lots of idle processes. Such systems tend to generate a great deal of
6149 continuous pressure on free memory reserves. Turning this feature on and
6150 tweaking the swapout hysteresis (in idle seconds) via
6151 vm.swap_idle_threshold1 and vm.swap_idle_threshold2 allows you to depress
6152 the priority of memory pages associated with idle processes more quickly
6153 then the normal pageout algorithm. This gives a helping hand to the
6154 pageout daemon. Do not turn this option on unless you need it, because the
6155 tradeoff you are making is essentially pre-page memory sooner rather than
6156 later; thus eating more swap and disk bandwidth. In a small system this
6157 option will have a determinable effect but in a large system that is
6158 already doing moderate paging this option allows the VM system to stage
6159 whole processes into and out of memory easily.
6161 ----------------------------------------------------------------------
6165 IDE drives lie about when a write completes. With IDE write caching turned
6166 on, IDE hard drives not only write data to disk out of order, but will
6167 sometimes delay writing some blocks indefinitely when under heavy disk
6168 loads. A crash or power failure may cause serious file system corruption.
6169 Turning off write caching will remove the danger of this data loss, but
6170 will also cause disk operations to proceed very slowly. Change this only
6171 if prepared to suffer with the disk slowdown.
6173 Changing this variable must be done from the boot loader at boot time.
6174 Attempting to do it after the kernel boots will have no effect.
6176 For more information, please see ata(4) manual page.
6178 ----------------------------------------------------------------------
6182 The tunefs(8) program can be used to fine-tune a file system. This program
6183 has many different options, but for now we are only concerned with
6184 toggling Soft Updates on and off, which is done by:
6186 # tunefs -n enable /filesystem
6187 # tunefs -n disable /filesystem
6189 A filesystem cannot be modified with tunefs(8) while it is mounted. A good
6190 time to enable Soft Updates is before any partitions have been mounted, in
6193 Note: It is possible to enable Soft Updates at filesystem creation time,
6194 through use of the -U option to newfs(8).
6196 Soft Updates drastically improves meta-data performance, mainly file
6197 creation and deletion, through the use of a memory cache. We recommend to
6198 use Soft Updates on all of your file systems. There are two downsides to
6199 Soft Updates that you should be aware of: First, Soft Updates guarantees
6200 filesystem consistency in the case of a crash but could very easily be
6201 several seconds (even a minute!) behind updating the physical disk. If
6202 your system crashes you may lose more work than otherwise. Secondly, Soft
6203 Updates delays the freeing of filesystem blocks. If you have a filesystem
6204 (such as the root filesystem) which is almost full, performing a major
6205 update, such as make installworld, can cause the filesystem to run out of
6206 space and the update to fail.
6208 ----------------------------------------------------------------------
6210 6.12.2.1 More Details about Soft Updates
6212 There are two traditional approaches to writing a file systems meta-data
6213 back to disk. (Meta-data updates are updates to non-content data like
6214 inodes or directories.)
6216 Historically, the default behavior was to write out meta-data updates
6217 synchronously. If a directory had been changed, the system waited until
6218 the change was actually written to disk. The file data buffers (file
6219 contents) were passed through the buffer cache and backed up to disk later
6220 on asynchronously. The advantage of this implementation is that it
6221 operates safely. If there is a failure during an update, the meta-data are
6222 always in a consistent state. A file is either created completely or not
6223 at all. If the data blocks of a file did not find their way out of the
6224 buffer cache onto the disk by the time of the crash, fsck(8) is able to
6225 recognize this and repair the filesystem by setting the file length to 0.
6226 Additionally, the implementation is clear and simple. The disadvantage is
6227 that meta-data changes are slow. An rm -r, for instance, touches all the
6228 files in a directory sequentially, but each directory change (deletion of
6229 a file) will be written synchronously to the disk. This includes updates
6230 to the directory itself, to the inode table, and possibly to indirect
6231 blocks allocated by the file. Similar considerations apply for unrolling
6232 large hierarchies (tar -x).
6234 The second case is asynchronous meta-data updates. This is the default for
6235 Linux/ext2fs and mount -o async for *BSD ufs. All meta-data updates are
6236 simply being passed through the buffer cache too, that is, they will be
6237 intermixed with the updates of the file content data. The advantage of
6238 this implementation is there is no need to wait until each meta-data
6239 update has been written to disk, so all operations which cause huge
6240 amounts of meta-data updates work much faster than in the synchronous
6241 case. Also, the implementation is still clear and simple, so there is a
6242 low risk for bugs creeping into the code. The disadvantage is that there
6243 is no guarantee at all for a consistent state of the filesystem. If there
6244 is a failure during an operation that updated large amounts of meta-data
6245 (like a power failure, or someone pressing the reset button), the
6246 filesystem will be left in an unpredictable state. There is no opportunity
6247 to examine the state of the filesystem when the system comes up again; the
6248 data blocks of a file could already have been written to the disk while
6249 the updates of the inode table or the associated directory were not. It is
6250 actually impossible to implement a fsck which is able to clean up the
6251 resulting chaos (because the necessary information is not available on the
6252 disk). If the filesystem has been damaged beyond repair, the only choice
6253 is to use newfs(8) on it and restore it from backup.
6255 The usual solution for this problem was to implement dirty region logging,
6256 which is also referred to as journaling, although that term is not used
6257 consistently and is occasionally applied to other forms of transaction
6258 logging as well. Meta-data updates are still written synchronously, but
6259 only into a small region of the disk. Later on they will be moved to their
6260 proper location. Because the logging area is a small, contiguous region on
6261 the disk, there are no long distances for the disk heads to move, even
6262 during heavy operations, so these operations are quicker than synchronous
6263 updates. Additionally the complexity of the implementation is fairly
6264 limited, so the risk of bugs being present is low. A disadvantage is that
6265 all meta-data are written twice (once into the logging region and once to
6266 the proper location) so for normal work, a performance ``pessimization''
6267 might result. On the other hand, in case of a crash, all pending meta-data
6268 operations can be quickly either rolled-back or completed from the logging
6269 area after the system comes up again, resulting in a fast filesystem
6272 Kirk McKusick, the developer of Berkeley FFS, solved this problem with
6273 Soft Updates: all pending meta-data updates are kept in memory and written
6274 out to disk in a sorted sequence (``ordered meta-data updates''). This has
6275 the effect that, in case of heavy meta-data operations, later updates to
6276 an item ``catch'' the earlier ones if the earlier ones are still in memory
6277 and have not already been written to disk. So all operations on, say, a
6278 directory are generally performed in memory before the update is written
6279 to disk (the data blocks are sorted according to their position so that
6280 they will not be on the disk ahead of their meta-data). If the system
6281 crashes, this causes an implicit ``log rewind'': all operations which did
6282 not find their way to the disk appear as if they had never happened. A
6283 consistent filesystem state is maintained that appears to be the one of 30
6284 to 60 seconds earlier. The algorithm used guarantees that all resources in
6285 use are marked as such in their appropriate bitmaps: blocks and inodes.
6286 After a crash, the only resource allocation error that occurs is that
6287 resources are marked as ``used'' which are actually ``free''. fsck(8)
6288 recognizes this situation, and frees the resources that are no longer
6289 used. It is safe to ignore the dirty state of the filesystem after a crash
6290 by forcibly mounting it with mount -f. In order to free resources that may
6291 be unused, fsck(8) needs to be run at a later time.
6293 The advantage is that meta-data operations are nearly as fast as
6294 asynchronous updates (i.e. faster than with logging, which has to write
6295 the meta-data twice). The disadvantages are the complexity of the code
6296 (implying a higher risk for bugs in an area that is highly sensitive
6297 regarding loss of user data), and a higher memory consumption.
6298 Additionally there are some idiosyncrasies one has to get used to. After a
6299 crash, the state of the filesystem appears to be somewhat ``older''. In
6300 situations where the standard synchronous approach would have caused some
6301 zero-length files to remain after the fsck, these files do not exist at
6302 all with a Soft Updates filesystem because neither the meta-data nor the
6303 file contents have ever been written to disk. Disk space is not released
6304 until the updates have been written to disk, which may take place some
6305 time after running rm. This may cause problems when installing large
6306 amounts of data on a filesystem that does not have enough free space to
6307 hold all the files twice.
6309 ----------------------------------------------------------------------
6311 6.13 Tuning Kernel Limits
6313 ----------------------------------------------------------------------
6315 6.13.1 File/Process Limits
6317 6.13.1.1 kern.maxfiles
6319 kern.maxfiles can be raised or lowered based upon your system
6320 requirements. This variable indicates the maximum number of file
6321 descriptors on your system. When the file descriptor table is full,
6322 ``file: table is full'' will show up repeatedly in the system message
6323 buffer, which can be viewed with the dmesg command.
6325 Each open file, socket, or fifo uses one file descriptor. A large-scale
6326 production server may easily require many thousands of file descriptors,
6327 depending on the kind and number of services running concurrently.
6329 kern.maxfile's default value is dictated by the MAXUSERS option in your
6330 kernel configuration file. kern.maxfiles grows proportionally to the value
6331 of MAXUSERS. When compiling a custom kernel, it is a good idea to set this
6332 kernel configuration option according to the uses of your system. From
6333 this number, the kernel is given most of its pre-defined limits. Even
6334 though a production machine may not actually have 256 users connected at
6335 once, the resources needed may be similar to a high-scale web server.
6337 Note: Setting MAXUSERS to 0 in your kernel configuration file will
6338 choose a reasonable default value based on the amount of RAM present in
6339 your system. It is set to 0 in the default GENERIC kernel.
6341 ----------------------------------------------------------------------
6343 6.13.1.2 kern.ipc.somaxconn
6345 The kern.ipc.somaxconn sysctl variable limits the size of the listen queue
6346 for accepting new TCP connections. The default value of 128 is typically
6347 too low for robust handling of new connections in a heavily loaded web
6348 server environment. For such environments, it is recommended to increase
6349 this value to 1024 or higher. The service daemon may itself limit the
6350 listen queue size (e.g. sendmail(8), or Apache) but will often have a
6351 directive in its configuration file to adjust the queue size. Large listen
6352 queues also do a better job of avoiding Denial of Service (DoS) attacks.
6354 ----------------------------------------------------------------------
6356 6.13.2 Network Limits
6358 The NMBCLUSTERS kernel configuration option dictates the amount of network
6359 Mbufs available to the system. A heavily-trafficked server with a low
6360 number of Mbufs will hinder DragonFly's ability. Each cluster represents
6361 approximately 2 K of memory, so a value of 1024 represents 2 megabytes of
6362 kernel memory reserved for network buffers. A simple calculation can be
6363 done to figure out how many are needed. If you have a web server which
6364 maxes out at 1000 simultaneous connections, and each connection eats a
6365 16 K receive and 16 K send buffer, you need approximately 32 MB worth of
6366 network buffers to cover the web server. A good rule of thumb is to
6367 multiply by 2, so 2x32 MB / 2 KB = 64 MB / 2 kB = 32768. We recommend
6368 values between 4096 and 32768 for machines with greater amounts of memory.
6369 Under no circumstances should you specify an arbitrarily high value for
6370 this parameter as it could lead to a boot time crash. The -m option to
6371 netstat(1) may be used to observe network cluster use.
6372 kern.ipc.nmbclusters loader tunable should be used to tune this at boot
6375 For busy servers that make extensive use of the sendfile(2) system call,
6376 it may be necessary to increase the number of sendfile(2) buffers via the
6377 NSFBUFS kernel configuration option or by setting its value in
6378 /boot/loader.conf (see loader(8) for details). A common indicator that
6379 this parameter needs to be adjusted is when processes are seen in the
6380 sfbufa state. The sysctl variable kern.ipc.nsfbufs is a read-only glimpse
6381 at the kernel configured variable. This parameter nominally scales with
6382 kern.maxusers, however it may be necessary to tune accordingly.
6384 Important: Even though a socket has been marked as non-blocking, calling
6385 sendfile(2) on the non-blocking socket may result in the sendfile(2)
6386 call blocking until enough struct sf_buf's are made available.
6388 ----------------------------------------------------------------------
6390 6.13.2.1 net.inet.ip.portrange.*
6392 The net.inet.ip.portrange.* sysctl variables control the port number
6393 ranges automatically bound to TCP and UDP sockets. There are three ranges:
6394 a low range, a default range, and a high range. Most network programs use
6395 the default range which is controlled by the net.inet.ip.portrange.first
6396 and net.inet.ip.portrange.last, which default to 1024 and 5000,
6397 respectively. Bound port ranges are used for outgoing connections, and it
6398 is possible to run the system out of ports under certain circumstances.
6399 This most commonly occurs when you are running a heavily loaded web proxy.
6400 The port range is not an issue when running servers which handle mainly
6401 incoming connections, such as a normal web server, or has a limited number
6402 of outgoing connections, such as a mail relay. For situations where you
6403 may run yourself out of ports, it is recommended to increase
6404 net.inet.ip.portrange.last modestly. A value of 10000, 20000 or 30000 may
6405 be reasonable. You should also consider firewall effects when changing the
6406 port range. Some firewalls may block large ranges of ports (usually
6407 low-numbered ports) and expect systems to use higher ranges of ports for
6408 outgoing connections -- for this reason it is recommended that
6409 net.inet.ip.portrange.first be lowered.
6411 ----------------------------------------------------------------------
6413 6.13.2.2 TCP Bandwidth Delay Product
6415 The TCP Bandwidth Delay Product Limiting is similar to TCP/Vegas in
6416 NetBSD. It can be enabled by setting net.inet.tcp.inflight_enable sysctl
6417 variable to 1. The system will attempt to calculate the bandwidth delay
6418 product for each connection and limit the amount of data queued to the
6419 network to just the amount required to maintain optimum throughput.
6421 This feature is useful if you are serving data over modems, Gigabit
6422 Ethernet, or even high speed WAN links (or any other link with a high
6423 bandwidth delay product), especially if you are also using window scaling
6424 or have configured a large send window. If you enable this option, you
6425 should also be sure to set net.inet.tcp.inflight_debug to 0 (disable
6426 debugging), and for production use setting net.inet.tcp.inflight_min to at
6427 least 6144 may be beneficial. However, note that setting high minimums may
6428 effectively disable bandwidth limiting depending on the link. The limiting
6429 feature reduces the amount of data built up in intermediate route and
6430 switch packet queues as well as reduces the amount of data built up in the
6431 local host's interface queue. With fewer packets queued up, interactive
6432 connections, especially over slow modems, will also be able to operate
6433 with lower Round Trip Times. However, note that this feature only effects
6434 data transmission (uploading / server side). It has no effect on data
6435 reception (downloading).
6437 Adjusting net.inet.tcp.inflight_stab is not recommended. This parameter
6438 defaults to 20, representing 2 maximal packets added to the bandwidth
6439 delay product window calculation. The additional window is required to
6440 stabilize the algorithm and improve responsiveness to changing conditions,
6441 but it can also result in higher ping times over slow links (though still
6442 much lower than you would get without the inflight algorithm). In such
6443 cases, you may wish to try reducing this parameter to 15, 10, or 5; and
6444 may also have to reduce net.inet.tcp.inflight_min (for example, to 3500)
6445 to get the desired effect. Reducing these parameters should be done as a
6448 ----------------------------------------------------------------------
6450 6.14 Adding Swap Space
6452 No matter how well you plan, sometimes a system does not run as you
6453 expect. If you find you need more swap space, it is simple enough to add.
6454 You have three ways to increase swap space: adding a new hard drive,
6455 enabling swap over NFS, and creating a swap file on an existing partition.
6457 ----------------------------------------------------------------------
6459 6.14.1 Swap on a New Hard Drive
6461 The best way to add swap, of course, is to use this as an excuse to add
6462 another hard drive. You can always use another hard drive, after all. If
6463 you can do this, go reread the discussion about swap space in Section 6.2
6464 for some suggestions on how to best arrange your swap.
6466 ----------------------------------------------------------------------
6468 6.14.2 Swapping over NFS
6470 Swapping over NFS is only recommended if you do not have a local hard disk
6471 to swap to. Even though DragonFly has an excellent NFS implementation, NFS
6472 swapping will be limited by the available network bandwidth and puts an
6473 additional burden on the NFS server.
6475 ----------------------------------------------------------------------
6479 You can create a file of a specified size to use as a swap file. In our
6480 example here we will use a 64MB file called /usr/swap0. You can use any
6481 name you want, of course.
6483 Example 6-1. Creating a Swapfile
6485 1. Be certain that your kernel configuration includes the vnode driver.
6486 It is not in recent versions of GENERIC.
6488 pseudo-device vn 1 #Vnode driver (turns a file into a device)
6490 2. Create a vn-device:
6495 3. Create a swapfile (/usr/swap0):
6497 # dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
6499 4. Set proper permissions on (/usr/swap0):
6501 # chmod 0600 /usr/swap0
6503 5. Enable the swap file in /etc/rc.conf:
6505 swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.
6507 6. Reboot the machine or to enable the swap file immediately, type:
6509 # vnconfig -e /dev/vn0b /usr/swap0 swap
6511 ----------------------------------------------------------------------
6513 6.15 Power and Resource Management
6515 Written by Hiten Pandya and Tom Rhodes.
6517 It is very important to utilize hardware resources in an efficient manner.
6518 Before ACPI was introduced, it was very difficult and inflexible for
6519 operating systems to manage the power usage and thermal properties of a
6520 system. The hardware was controlled by some sort of BIOS embedded
6521 interface, such as Plug and Play BIOS (PNPBIOS), or Advanced Power
6522 Management (APM) and so on. Power and Resource Management is one of the
6523 key components of a modern operating system. For example, you may want an
6524 operating system to monitor system limits (and possibly alert you) in case
6525 your system temperature increased unexpectedly.
6527 In this section, we will provide comprehensive information about ACPI.
6528 References will be provided for further reading at the end. Please be
6529 aware that ACPI is available on DragonFly systems as a default kernel
6532 ----------------------------------------------------------------------
6534 6.15.1 What Is ACPI?
6536 Advanced Configuration and Power Interface (ACPI) is a standard written by
6537 an alliance of vendors to provide a standard interface for hardware
6538 resources and power management (hence the name). It is a key element in
6539 Operating System-directed configuration and Power Management, i.e.: it
6540 provides more control and flexibility to the operating system (OS). Modern
6541 systems ``stretched'' the limits of the current Plug and Play interfaces
6542 (such as APM), prior to the introduction of ACPI. ACPI is the direct
6543 successor to APM (Advanced Power Management).
6545 ----------------------------------------------------------------------
6547 6.15.2 Shortcomings of Advanced Power Management (APM)
6549 The Advanced Power Management (APM) facility control's the power usage of
6550 a system based on its activity. The APM BIOS is supplied by the (system)
6551 vendor and it is specific to the hardware platform. An APM driver in the
6552 OS mediates access to the APM Software Interface, which allows management
6555 There are four major problems in APM. Firstly, power management is done by
6556 the (vendor-specific) BIOS, and the OS does not have any knowledge of it.
6557 One example of this, is when the user sets idle-time values for a hard
6558 drive in the APM BIOS, that when exceeded, it (BIOS) would spin down the
6559 hard drive, without the consent of the OS. Secondly, the APM logic is
6560 embedded in the BIOS, and it operates outside the scope of the OS. This
6561 means users can only fix problems in their APM BIOS by flashing a new one
6562 into the ROM; which, is a very dangerous procedure, and if it fails, it
6563 could leave the system in an unrecoverable state. Thirdly, APM is a
6564 vendor-specific technology, which, means that there is a lot or parity
6565 (duplication of efforts) and bugs found in one vendor's BIOS, may not be
6566 solved in others. Last but not the least, the APM BIOS did not have enough
6567 room to implement a sophisticated power policy, or one that can adapt very
6568 well to the purpose of the machine.
6570 Plug and Play BIOS (PNPBIOS) was unreliable in many situations. PNPBIOS is
6571 16-bit technology, so the OS has to use 16-bit emulation in order to
6572 ``interface'' with PNPBIOS methods.
6574 The DragonFly APM driver is documented in the apm(4) manual page.
6576 ----------------------------------------------------------------------
6578 6.15.3 Configuring ACPI
6580 The acpi.ko driver is loaded by default at start up by the loader(8) and
6581 should not be compiled into the kernel. The reasoning behind this is that
6582 modules are easier to work with, say if switching to another acpi.ko
6583 without doing a kernel rebuild. This has the advantage of making testing
6584 easier. Another reason is that starting ACPI after a system has been
6585 brought up is not too useful, and in some cases can be fatal. In doubt,
6586 just disable ACPI all together. This driver should not and can not be
6587 unloaded because the system bus uses it for various hardware interactions.
6588 ACPI can be disabled with the acpiconf(8) utility. In fact most of the
6589 interaction with ACPI can be done via acpiconf(8). Basically this means,
6590 if anything about ACPI is in the dmesg(8) output, then most likely it is
6593 Note: ACPI and APM cannot coexist and should be used separately. The
6594 last one to load will terminate if the driver notices the other running.
6596 In the simplest form, ACPI can be used to put the system into a sleep mode
6597 with acpiconf(8), the -s flag, and a 1-5 option. Most users will only need
6598 1. Option 5 will do a soft-off which is the same action as:
6602 The other options are available. Check out the acpiconf(8) manual page for
6605 ----------------------------------------------------------------------
6607 6.16 Using and Debugging DragonFly ACPI
6609 Written by Nate Lawson. With contributions from Peter Schultz and Tom
6612 ACPI is a fundamentally new way of discovering devices, managing power
6613 usage, and providing standardized access to various hardware previously
6614 managed by the BIOS. Progress is being made toward ACPI working on all
6615 systems, but bugs in some motherboards' ACPI Machine Language (AML)
6616 bytecode, incompleteness in DragonFly's kernel subsystems, and bugs in the
6617 Intel ACPI-CA interpreter continue to appear.
6619 This document is intended to help you assist the DragonFly ACPI
6620 maintainers in identifying the root cause of problems you observe and
6621 debugging and developing a solution. Thanks for reading this and we hope
6622 we can solve your system's problems.
6624 ----------------------------------------------------------------------
6626 6.16.1 Submitting Debugging Information
6628 Note: Before submitting a problem, be sure you are running the latest
6629 BIOS version and, if available, embedded controller firmware version.
6631 For those of you that want to submit a problem right away, please send the
6632 following information to bugs
6634 * Description of the buggy behavior, including system type and model and
6635 anything that causes the bug to appear. Also, please note as
6636 accurately as possible when the bug began occurring if it is new for
6639 * The dmesg output after ``boot -v'', including any error messages
6640 generated by you exercising the bug.
6642 * dmesg output from ``boot -v'' with ACPI disabled, if disabling it
6643 helps fix the problem.
6645 * Output from ``sysctl hw.acpi''. This is also a good way of figuring
6646 out what features your system offers.
6648 * URL where your ACPI Source Language (ASL) can be found. Do not send
6649 the ASL directly to the list as it can be very large. Generate a copy
6650 of your ASL by running this command:
6652 # acpidump -t -d > name-system.asl
6654 (Substitute your login name for name and manufacturer/model for
6655 system. Example: njl-FooCo6000.asl)
6657 ----------------------------------------------------------------------
6661 ACPI is present in all modern computers that conform to the ia32 (x86),
6662 ia64 (Itanium), and amd64 (AMD) architectures. The full standard has many
6663 features including CPU performance management, power planes control,
6664 thermal zones, various battery systems, embedded controllers, and bus
6665 enumeration. Most systems implement less than the full standard. For
6666 instance, a desktop system usually only implements the bus enumeration
6667 parts while a laptop might have cooling and battery management support as
6668 well. Laptops also have suspend and resume, with their own associated
6671 An ACPI-compliant system has various components. The BIOS and chipset
6672 vendors provide various fixed tables (e.g., FADT) in memory that specify
6673 things like the APIC map (used for SMP), config registers, and simple
6674 configuration values. Additionally, a table of bytecode (the
6675 Differentiated System Description Table DSDT) is provided that specifies a
6676 tree-like name space of devices and methods.
6678 The ACPI driver must parse the fixed tables, implement an interpreter for
6679 the bytecode, and modify device drivers and the kernel to accept
6680 information from the ACPI subsystem. For DragonFly, Intel has provided an
6681 interpreter (ACPI-CA) that is shared with Linux and NetBSD. The path to
6682 the ACPI-CA source code is src/sys/contrib/dev/acpica-unix-YYYYMMDD, where
6683 YYYYMMDD is the release date of the ACPI-CA source code. The glue code
6684 that allows ACPI-CA to work on DragonFly is in src/sys/dev/acpica5/Osd.
6685 Finally, drivers that implement various ACPI devices are found in
6686 src/sys/dev/acpica5, and architecture-dependent code resides in
6689 ----------------------------------------------------------------------
6691 6.16.3 Common Problems
6693 For ACPI to work correctly, all the parts have to work correctly. Here are
6694 some common problems, in order of frequency of appearance, and some
6695 possible workarounds or fixes.
6697 ----------------------------------------------------------------------
6699 6.16.3.1 Suspend/Resume
6701 ACPI has three suspend to RAM (STR) states, S1-S3, and one suspend to disk
6702 state (STD), called S4. S5 is ``soft off'' and is the normal state your
6703 system is in when plugged in but not powered up. S4 can actually be
6704 implemented two separate ways. S4BIOS is a BIOS-assisted suspend to disk.
6705 S4OS is implemented entirely by the operating system.
6707 Start by checking sysctl hw.acpi for the suspend-related items. Here are
6708 the results for my Thinkpad:
6710 hw.acpi.supported_sleep_state: S3 S4 S5
6714 This means that I can use acpiconf -s to test S3, S4OS, and S5. If s4bios
6715 was one (1), I would have S4BIOS support instead of S4 OS.
6717 When testing suspend/resume, start with S1, if supported. This state is
6718 most likely to work since it doesn't require much driver support. No one
6719 has implemented S2 but if you have it, it's similar to S1. The next thing
6720 to try is S3. This is the deepest STR state and requires a lot of driver
6721 support to properly reinitialize your hardware. If you have problems
6722 resuming, feel free to email the bugs list but do not expect the problem
6723 to be resolved since there are a lot of drivers/hardware that need more
6726 To help isolate the problem, remove as many drivers from your kernel as
6727 possible. If it works, you can narrow down which driver is the problem by
6728 loading drivers until it fails again. Typically binary drivers like
6729 nvidia.ko, X11 display drivers, and USB will have the most problems while
6730 Ethernet interfaces usually work fine. If you can load/unload the drivers
6731 ok, you can automate this by putting the appropriate commands in
6732 /etc/rc.suspend and /etc/rc.resume. There is a commented-out example for
6733 unloading and loading a driver. Try setting hw.acpi.reset_video to zero
6734 (0) if your display is messed up after resume. Try setting longer or
6735 shorter values for hw.acpi.sleep_delay to see if that helps.
6737 Another thing to try is load a recent Linux distribution with ACPI support
6738 and test their suspend/resume support on the same hardware. If it works on
6739 Linux, it's likely a DragonFly driver problem and narrowing down which
6740 driver causes the problems will help us fix the problem. Note that the
6741 ACPI maintainers do not usually maintain other drivers (e.g sound, ATA,
6742 etc.) so any work done on tracking down a driver problem should probably
6743 eventually be posted to the bugs list and mailed to the driver maintainer.
6744 If you are feeling adventurous, go ahead and start putting some debugging
6745 printf(3)s in a problematic driver to track down where in its resume
6748 Finally, try disabling ACPI and enabling APM instead. If suspend/resume
6749 works with APM, you may be better off sticking with APM, especially on
6750 older hardware (pre-2000). It took vendors a while to get ACPI support
6751 correct and older hardware is more likely to have BIOS problems with ACPI.
6753 ----------------------------------------------------------------------
6755 6.16.3.2 System Hangs (temporary or permanent)
6757 Most system hangs are a result of lost interrupts or an interrupt storm.
6758 Chipsets have a lot of problems based on how the BIOS configures
6759 interrupts before boot, correctness of the APIC (MADT) table, and routing
6760 of the System Control Interrupt (SCI).
6762 Interrupt storms can be distinguished from lost interrupts by checking the
6763 output of vmstat -i and looking at the line that has acpi0. If the counter
6764 is increasing at more than a couple per second, you have an interrupt
6765 storm. If the system appears hung, try breaking to DDB (CTRL+ALT+ESC on
6766 console) and type show interrupts.
6768 Your best hope when dealing with interrupt problems is to try disabling
6769 APIC support with hint.apic.0.disabled="1" in loader.conf.
6771 ----------------------------------------------------------------------
6775 Panics are relatively rare for ACPI and are the top priority to be fixed.
6776 The first step is to isolate the steps to reproduce the panic (if
6777 possible) and get a backtrace. Follow the advice for enabling options DDB
6778 and setting up a serial console (see Section 17.6.5.3) or setting up a
6779 dump(8) partition. You can get a backtrace in DDB with tr. If you have to
6780 handwrite the backtrace, be sure to at least get the lowest five (5) and
6781 top five (5) lines in the trace.
6783 Then, try to isolate the problem by booting with ACPI disabled. If that
6784 works, you can isolate the ACPI subsystem by using various values of
6785 debug.acpi.disable. See the acpi(4) manual page for some examples.
6787 ----------------------------------------------------------------------
6789 6.16.3.4 System Powers Up After Suspend or Shutdown
6791 First, try setting hw.acpi.disable_on_poweroff=``0'' in loader.conf(5).
6792 This keeps ACPI from disabling various events during the shutdown process.
6793 Some systems need this value set to ``1'' (the default) for the same
6794 reason. This usually fixes the problem of a system powering up
6795 spontaneously after a suspend or poweroff.
6797 ----------------------------------------------------------------------
6799 6.16.3.5 Other Problems
6801 If you have other problems with ACPI (working with a docking station,
6802 devices not detected, etc.), please email a description to the mailing
6803 list as well; however, some of these issues may be related to unfinished
6804 parts of the ACPI subsystem so they might take a while to be implemented.
6805 Please be patient and prepared to test patches we may send you.
6807 ----------------------------------------------------------------------
6809 6.16.4 ASL, acpidump, and IASL
6811 The most common problem is the BIOS vendors providing incorrect (or
6812 outright buggy!) bytecode. This is usually manifested by kernel console
6815 ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
6816 (Node 0xc3f6d160), AE_NOT_FOUND
6818 Often, you can resolve these problems by updating your BIOS to the latest
6819 revision. Most console messages are harmless but if you have other
6820 problems like battery status not working, they're a good place to start
6821 looking for problems in the AML. The bytecode, known as AML, is compiled
6822 from a source language called ASL. The AML is found in the table known as
6823 the DSDT. To get a copy of your ASL, use acpidump(8). You should use both
6824 the -t (show contents of the fixed tables) and -d (disassemble AML to ASL)
6825 options. See the Submitting Debugging Information section for an example
6828 The simplest first check you can do is to recompile your ASL to check for
6829 errors. Warnings can usually be ignored but errors are bugs that will
6830 usually prevent ACPI from working correctly. To recompile your ASL, issue
6831 the following command:
6835 ----------------------------------------------------------------------
6837 6.16.5 Fixing Your ASL
6839 In the long run, our goal is for almost everyone to have ACPI work without
6840 any user intervention. At this point, however, we are still developing
6841 workarounds for common mistakes made by the BIOS vendors. The Microsoft
6842 interpreter (acpi.sys and acpiec.sys) does not strictly check for
6843 adherence to the standard, and thus many BIOS vendors who only test ACPI
6844 under Windows never fix their ASL. We hope to continue to identify and
6845 document exactly what non-standard behavior is allowed by Microsoft's
6846 interpreter and replicate it so DragonFly can work without forcing users
6847 to fix the ASL. As a workaround and to help us identify behavior, you can
6848 fix the ASL manually. If this works for you, please send a diff(1) of the
6849 old and new ASL so we can possibly work around the buggy behavior in
6850 ACPI-CA and thus make your fix unnecessary.
6852 Here is a list of common error messages, their cause, and how to fix them:
6854 ----------------------------------------------------------------------
6856 6.16.5.1 _OS dependencies
6858 Some AML assumes the world consists of various Windows versions. You can
6859 tell DragonFly to claim it is any OS to see if this fixes problems you may
6860 have. An easy way to override this is to set hw.acpi.osname=``Windows
6861 2001'' in /boot/loader.conf or other similar strings you find in the ASL.
6863 ----------------------------------------------------------------------
6865 6.16.5.2 Missing Return statements
6867 Some methods do not explicitly return a value as the standard requires.
6868 While ACPI-CA does not handle this, DragonFly has a workaround that allows
6869 it to return the value implicitly. You can also add explicit Return
6870 statements where required if you know what value should be returned. To
6871 force iasl to compile the ASL, use the -f flag.
6873 ----------------------------------------------------------------------
6875 6.16.5.3 Overriding the Default AML
6877 After you customize your.asl, you will want to compile it, run:
6881 You can add the -f flag to force creation of the AML, even if there are
6882 errors during compilation. Remember that some errors (e.g., missing Return
6883 statements) are automatically worked around by the interpreter.
6885 DSDT.aml is the default output filename for iasl. You can load this
6886 instead of your BIOS's buggy copy (which is still present in flash memory)
6887 by editing /boot/loader.conf as follows:
6889 acpi_dsdt_load="YES"
6890 acpi_dsdt_name="/boot/DSDT.aml"
6892 Be sure to copy your DSDT.aml to the /boot directory.
6894 ----------------------------------------------------------------------
6896 6.16.6 Getting Debugging Output From ACPI
6898 The ACPI driver has a very flexible debugging facility. It allows you to
6899 specify a set of subsystems as well as the level of verbosity. The
6900 subsystems you wish to debug are specified as ``layers'' and are broken
6901 down into ACPI-CA components (ACPI_ALL_COMPONENTS) and ACPI hardware
6902 support (ACPI_ALL_DRIVERS). The verbosity of debugging output is specified
6903 as the ``level'' and ranges from ACPI_LV_ERROR (just report errors) to
6904 ACPI_LV_VERBOSE (everything). The ``level'' is a bitmask so multiple
6905 options can be set at once, separated by spaces. In practice, you will
6906 want to use a serial console to log the output if it is so long it flushes
6907 the console message buffer.
6909 Debugging output is not enabled by default. To enable it, add options
6910 ACPI_DEBUG to your kernel config if ACPI is compiled into the kernel. You
6911 can add ACPI_DEBUG=1 to your /etc/make.conf to enable it globally. If it
6912 is a module, you can recompile just your acpi.ko module as follows:
6914 # cd /sys/dev/acpica5
6918 Install acpi.ko in /boot/kernel and add your desired level and layer to
6919 loader.conf. This example enables debug messages for all ACPI-CA
6920 components and all ACPI hardware drivers (CPU, LID, etc.) It will only
6921 output error messages, the least verbose level.
6923 debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
6924 debug.acpi.level="ACPI_LV_ERROR"
6926 If the information you want is triggered by a specific event (say, a
6927 suspend and then resume), you can leave out changes to loader.conf and
6928 instead use sysctl to specify the layer and level after booting and
6929 preparing your system for the specific event. The sysctls are named the
6930 same as the tunables in loader.conf.
6932 ----------------------------------------------------------------------
6936 More information about ACPI may be found in the following locations:
6938 * The FreeBSD ACPI mailing list (This is FreeBSD-specific; posting
6939 DragonFly questions here may not generate much of an answer.)
6941 * The ACPI Mailing List Archives (FreeBSD)
6942 http://lists.freebsd.org/pipermail/freebsd-acpi/
6944 * The old ACPI Mailing List Archives (FreeBSD)
6945 http://home.jp.FreeBSD.org/mail-list/acpi-jp/
6947 * The ACPI 2.0 Specification http://acpi.info/spec.htm
6949 * DragonFly Manual pages: acpidump(8), acpiconf(8), acpidb(8)
6951 * DSDT debugging resource. (Uses Compaq as an example but generally
6954 ----------------------------------------------------------------------
6956 Chapter 7 The DragonFly Booting Process
6960 The process of starting a computer and loading the operating system is
6961 referred to as ``the bootstrap process'', or simply ``booting''.
6962 DragonFly's boot process provides a great deal of flexibility in
6963 customizing what happens when you start the system, allowing you to select
6964 from different operating systems installed on the same computer, or even
6965 different versions of the same operating system or installed kernel.
6967 This chapter details the configuration options you can set and how to
6968 customize the DragonFly boot process. This includes everything that
6969 happens until the DragonFly kernel has started, probed for devices, and
6970 started init(8). If you are not quite sure when this happens, it occurs
6971 when the text color changes from bright white to grey.
6973 After reading this chapter, you will know:
6975 * What the components of the DragonFly bootstrap system are, and how
6978 * The options you can give to the components in the DragonFly bootstrap
6979 to control the boot process.
6981 * The basics of device.hints(5).
6983 x86 Only: This chapter only describes the boot process for DragonFly
6984 running on x86 systems.
6986 ----------------------------------------------------------------------
6988 7.2 The Booting Problem
6990 Turning on a computer and starting the operating system poses an
6991 interesting dilemma. By definition, the computer does not know how to do
6992 anything until the operating system is started. This includes running
6993 programs from the disk. So if the computer can not run a program from the
6994 disk without the operating system, and the operating system programs are
6995 on the disk, how is the operating system started?
6997 This problem parallels one in the book The Adventures of Baron Munchausen.
6998 A character had fallen part way down a manhole, and pulled himself out by
6999 grabbing his bootstraps, and lifting. In the early days of computing the
7000 term bootstrap was applied to the mechanism used to load the operating
7001 system, which has become shortened to ``booting''.
7003 On x86 hardware the Basic Input/Output System (BIOS) is responsible for
7004 loading the operating system. To do this, the BIOS looks on the hard disk
7005 for the Master Boot Record (MBR), which must be located on a specific
7006 place on the disk. The BIOS has enough knowledge to load and run the MBR,
7007 and assumes that the MBR can then carry out the rest of the tasks involved
7008 in loading the operating system possibly with the help of the BIOS.
7010 The code within the MBR is usually referred to as a boot manager,
7011 especially when it interacts with the user. In this case the boot manager
7012 usually has more code in the first track of the disk or within some OS's
7013 file system. (A boot manager is sometimes also called a boot loader, but
7014 FreeBSD uses that term for a later stage of booting.) Popular boot
7015 managers include boot0 (a.k.a. Boot Easy, the standard DragonFly boot
7016 manager), Grub, GAG, and LILO. (Only boot0 fits within the MBR.)
7018 If you have only one operating system installed on your disks then a
7019 standard PC MBR will suffice. This MBR searches for the first bootable
7020 (a.k.a. active) slice on the disk, and then runs the code on that slice to
7021 load the remainder of the operating system. The MBR installed by fdisk(8),
7022 by default, is such an MBR. It is based on /boot/mbr.
7024 If you have installed multiple operating systems on your disks then you
7025 can install a different boot manager, one that can display a list of
7026 different operating systems, and allows you to choose the one to boot
7027 from. Two of these are discussed in the next subsection.
7029 The remainder of the DragonFly bootstrap system is divided into three
7030 stages. The first stage is run by the MBR, which knows just enough to get
7031 the computer into a specific state and run the second stage. The second
7032 stage can do a little bit more, before running the third stage. The third
7033 stage finishes the task of loading the operating system. The work is split
7034 into these three stages because the PC standards put limits on the size of
7035 the programs that can be run at stages one and two. Chaining the tasks
7036 together allows DragonFly to provide a more flexible loader.
7038 The kernel is then started and it begins to probe for devices and
7039 initialize them for use. Once the kernel boot process is finished, the
7040 kernel passes control to the user process init(8), which then makes sure
7041 the disks are in a usable state. init(8) then starts the user-level
7042 resource configuration which mounts file systems, sets up network cards to
7043 communicate on the network, and generally starts all the processes that
7044 usually are run on a DragonFly system at startup.
7046 ----------------------------------------------------------------------
7048 7.3 The Boot Manager and Boot Stages
7050 ----------------------------------------------------------------------
7052 7.3.1 The Boot Manager
7054 The code in the MBR or boot manager is sometimes referred to as stage zero
7055 of the boot process. This subsection discusses two of the boot managers
7056 previously mentioned: boot0 and LILO.
7058 The boot0 Boot Manager: The MBR installed by FreeBSD's installer or
7059 boot0cfg(8), by default, is based on /boot/boot0. (The boot0 program is
7060 very simple, since the program in the MBR can only be 446 bytes long
7061 because of the slice table and 0x55AA identifier at the end of the MBR.)
7062 If you have installed boot0 and multiple operating systems on your hard
7063 disks, then you will see a display similar to this one at boot time:
7065 Example 7-1. boot0 Screenshot
7075 Other operating systems, in particular Windows, have been known to
7076 overwrite an existing MBR with their own. If this happens to you, or you
7077 want to replace your existing MBR with the DragonFly MBR then use the
7080 # fdisk -B -b /boot/boot0 device
7082 where device is the device that you boot from, such as ad0 for the first
7083 IDE disk, ad2 for the first IDE disk on a second IDE controller, da0 for
7084 the first SCSI disk, and so on. Or, if you want a custom configuration of
7085 the MBR, use boot0cfg(8).
7087 The LILO Boot Manager: To install this boot manager so it will also boot
7088 DragonFly, first start Linux and add the following to your existing
7089 /etc/lilo.conf configuration file:
7093 loader=/boot/chain.b
7096 In the above, specify DragonFly's primary partition and drive using Linux
7097 specifiers, replacing X with the Linux drive letter and Y with the Linux
7098 primary partition number. If you are using a SCSI drive, you will need to
7099 change /dev/hd to read something similar to /dev/sd. The
7100 loader=/boot/chain.b line can be omitted if you have both operating
7101 systems on the same drive. Now run /sbin/lilo -v to commit your new
7102 changes to the system; this should be verified by checking its screen
7105 ----------------------------------------------------------------------
7107 7.3.2 Stage One, /boot/boot1, and Stage Two, /boot/boot2
7109 Conceptually the first and second stages are part of the same program, on
7110 the same area of the disk. Because of space constraints they have been
7111 split into two, but you would always install them together. They are
7112 copied from the combined file /boot/boot by the installer or disklabel
7115 They are located outside file systems, in the first track of the boot
7116 slice, starting with the first sector. This is where boot0, or any other
7117 boot manager, expects to find a program to run which will continue the
7118 boot process. The number of sectors used is easily determined from the
7121 They are found on the boot sector of the boot slice, which is where boot0,
7122 or any other program on the MBR expects to find the program to run to
7123 continue the boot process. The files in the /boot directory are copies of
7124 the real files, which are stored outside of the DragonFly file system.
7126 boot1 is very simple, since it can only be 512 bytes in size, and knows
7127 just enough about the DragonFly disklabel, which stores information about
7128 the slice, to find and execute boot2.
7130 boot2 is slightly more sophisticated, and understands the DragonFly file
7131 system enough to find files on it, and can provide a simple interface to
7132 choose the kernel or loader to run.
7134 Since the loader is much more sophisticated, and provides a nice
7135 easy-to-use boot configuration, boot2 usually runs it, but previously it
7136 was tasked to run the kernel directly.
7138 Example 7-2. boot2 Screenshot
7140 >> DragonFly/i386 BOOT
7141 Default: 0:ad(0,a)/boot/loader
7144 If you ever need to replace the installed boot1 and boot2 use
7147 # disklabel -B diskslice
7149 where diskslice is the disk and slice you boot from, such as ad0s1 for the
7150 first slice on the first IDE disk.
7152 ----------------------------------------------------------------------
7154 7.3.3 Stage Three, /boot/loader
7156 The loader is the final stage of the three-stage bootstrap, and is located
7157 on the file system, usually as /boot/loader.
7159 The loader is intended as a user-friendly method for configuration, using
7160 an easy-to-use built-in command set, backed up by a more powerful
7161 interpreter, with a more complex command set.
7163 ----------------------------------------------------------------------
7165 7.3.3.1 Loader Program Flow
7167 During initialization, the loader will probe for a console and for disks,
7168 and figure out what disk it is booting from. It will set variables
7169 accordingly, and an interpreter is started where user commands can be
7170 passed from a script or interactively.
7172 The loader will then read /boot/loader.rc, which by default reads in
7173 /boot/defaults/loader.conf which sets reasonable defaults for variables
7174 and reads /boot/loader.conf for local changes to those variables.
7175 loader.rc then acts on these variables, loading whichever modules and
7176 kernel are selected.
7178 Finally, by default, the loader issues a 10 second wait for key presses,
7179 and boots the kernel if it is not interrupted. If interrupted, the user is
7180 presented with a prompt which understands the easy-to-use command set,
7181 where the user may adjust variables, unload all modules, load modules, and
7182 then finally boot or reboot.
7184 ----------------------------------------------------------------------
7186 7.3.3.2 Loader Built-In Commands
7188 These are the most commonly used loader commands. For a complete
7189 discussion of all available commands, please see loader(8).
7193 Proceeds to boot the kernel if not interrupted within the time
7194 span given, in seconds. It displays a countdown, and the default
7195 time span is 10 seconds.
7197 boot [-options] [kernelname]
7199 Immediately proceeds to boot the kernel, with the given options,
7200 if any, and with the kernel name given, if it is.
7204 Goes through the same automatic configuration of modules based on
7205 variables as what happens at boot. This only makes sense if you
7206 use unload first, and change some variables, most commonly kernel.
7210 Shows help messages read from /boot/loader.help. If the topic
7211 given is index, then the list of available topics is given.
7213 include filename ...
7215 Processes the file with the given filename. The file is read in,
7216 and interpreted line by line. An error immediately stops the
7219 load [-t type] filename
7221 Loads the kernel, kernel module, or file of the type given, with
7222 the filename given. Any arguments after filename are passed to the
7227 Displays a listing of files in the given path, or the root
7228 directory, if the path is not specified. If -l is specified, file
7229 sizes will be shown too.
7233 Lists all of the devices from which it may be possible to load
7234 modules. If -v is specified, more details are printed.
7238 Displays loaded modules. If -v is specified, more details are
7243 Displays the files specified, with a pause at each LINES
7248 Immediately reboots the system.
7250 set variable, set variable=value
7252 Sets the loader's environment variables.
7256 Removes all loaded modules.
7258 ----------------------------------------------------------------------
7260 7.3.3.3 Loader Examples
7262 Here are some practical examples of loader usage:
7264 * To simply boot your usual kernel, but in single-user mode:
7268 * To unload your usual kernel and modules, and then load just your old
7269 (or another) kernel:
7274 You can use kernel.GENERIC to refer to the generic kernel that comes
7275 on the install disk, or kernel.old to refer to your previously
7276 installed kernel (when you have upgraded or configured your own
7277 kernel, for example).
7279 Note: Use the following to load your usual modules with another
7283 set kernel="kernel.old"
7286 * To load a kernel configuration script (an automated script which does
7287 the things you would normally do in the kernel boot-time
7290 load -t userconfig_script /boot/kernel.conf
7292 ----------------------------------------------------------------------
7294 7.4 Kernel Interaction During Boot
7296 Once the kernel is loaded by either loader (as usual) or boot2 (bypassing
7297 the loader), it examines its boot flags, if any, and adjusts its behavior
7300 ----------------------------------------------------------------------
7302 7.4.1 Kernel Boot Flags
7304 Here are the more common boot flags:
7308 during kernel initialization, ask for the device to mount as the
7317 run UserConfig, the boot-time kernel configurator
7321 boot into single-user mode
7325 be more verbose during kernel startup
7327 Note: There are other boot flags; read boot(8) for more information on
7330 ----------------------------------------------------------------------
7332 7.5 Init: Process Control Initialization
7334 Once the kernel has finished booting, it passes control to the user
7335 process init(8), which is located at /sbin/init, or the program path
7336 specified in the init_path variable in loader.
7338 ----------------------------------------------------------------------
7340 7.5.1 Automatic Reboot Sequence
7342 The automatic reboot sequence makes sure that the file systems available
7343 on the system are consistent. If they are not, and fsck(8) cannot fix the
7344 inconsistencies, init(8) drops the system into single-user mode for the
7345 system administrator to take care of the problems directly.
7347 ----------------------------------------------------------------------
7349 7.5.2 Single-User Mode
7351 This mode can be reached through the automatic reboot sequence, or by the
7352 user booting with the -s option or setting the boot_single variable in
7355 It can also be reached by calling shutdown(8) without the reboot (-r) or
7356 halt (-h) options, from multi-user mode.
7358 If the system console is set to insecure in /etc/ttys, then the system
7359 prompts for the root password before initiating single-user mode.
7361 Example 7-3. An Insecure Console in /etc/ttys
7363 # name getty type status comments
7365 # If console is marked "insecure", then init will ask for the root password
7366 # when going to single-user mode.
7367 console none unknown off insecure
7369 Note: An insecure console means that you consider your physical security
7370 to the console to be insecure, and want to make sure only someone who
7371 knows the root password may use single-user mode, and it does not mean
7372 that you want to run your console insecurely. Thus, if you want
7373 security, choose insecure, not secure.
7375 ----------------------------------------------------------------------
7377 7.5.3 Multi-User Mode
7379 If init(8) finds your file systems to be in order, or once the user has
7380 finished in single-user mode, the system enters multi-user mode, in which
7381 it starts the resource configuration of the system.
7383 ----------------------------------------------------------------------
7385 7.5.3.1 Resource Configuration (rc)
7387 The resource configuration system reads in configuration defaults from
7388 /etc/defaults/rc.conf, and system-specific details from /etc/rc.conf, and
7389 then proceeds to mount the system file systems mentioned in /etc/fstab,
7390 start up networking services, start up miscellaneous system daemons, and
7391 finally runs the startup scripts of locally installed packages.
7393 The rc(8) manual page is a good reference to the resource configuration
7394 system, as is examining the scripts themselves.
7396 ----------------------------------------------------------------------
7398 7.6 Shutdown Sequence
7400 Upon controlled shutdown, via shutdown(8), init(8) will attempt to run the
7401 script /etc/rc.shutdown, and then proceed to send all processes the TERM
7402 signal, and subsequently the KILL signal to any that do not terminate
7405 To power down a DragonFly machine on architectures and systems that
7406 support power management, simply use the command shutdown -p now to turn
7407 the power off immediately. To just reboot a DragonFly system, just use
7408 shutdown -r now. You need to be root or a member of operator group to run
7409 shutdown(8). The halt(8) and reboot(8) commands can also be used, please
7410 refer to their manual pages and to shutdown(8)'s one for more information.
7412 Note: Power management requires acpi(4) support in the kernel or loaded
7413 as a module, or apm(4) support.
7415 ----------------------------------------------------------------------
7417 Chapter 8 Users and Basic Account Management
7419 Contributed by Neil Blakey-Milner.
7423 DragonFly allows multiple users to use the computer at the same time.
7424 Obviously, only one of those users can be sitting in front of the screen
7425 and keyboard at any one time [6], but any number of users can log in
7426 through the network to get their work done. To use the system every user
7427 must have an account.
7429 After reading this chapter, you will know:
7431 * The differences between the various user accounts on a DragonFly
7434 * How to add user accounts.
7436 * How to remove user accounts.
7438 * How to change account details, such as the user's full name, or
7441 * How to set limits on a per-account basis, to control the resources
7442 such as memory and CPU time that accounts and groups of accounts are
7445 * How to use groups to make account management easier.
7447 Before reading this chapter, you should:
7449 * Understand the basics of UNIX and DragonFly (Chapter 3).
7451 ----------------------------------------------------------------------
7455 All access to the system is achieved via accounts, and all processes are
7456 run by users, so user and account management are of integral importance on
7459 Every account on a DragonFly system has certain information associated
7460 with it to identify the account.
7464 The user name as it would be typed at the login: prompt. User
7465 names must be unique across the computer; you may not have two
7466 users with the same user name. There are a number of rules for
7467 creating valid user names, documented in passwd(5); you would
7468 typically use user names that consist of eight or fewer all lower
7473 Each account has a password associated with it. The password may
7474 be blank, in which case no password will be required to access the
7475 system. This is normally a very bad idea; every account should
7480 The UID is a number, traditionally from 0 to 65535[7], used to
7481 uniquely identify the user to the system. Internally, DragonFly
7482 uses the UID to identify users--any DragonFly commands that allow
7483 you to specify a user name will convert it to the UID before
7484 working with it. This means that you can have several accounts
7485 with different user names but the same UID. As far as DragonFly is
7486 concerned, these accounts are one user. It is unlikely you will
7487 ever need to do this.
7491 The GID is a number, traditionally from 0 to 65535[7], used to
7492 uniquely identify the primary group that the user belongs to.
7493 Groups are a mechanism for controlling access to resources based
7494 on a user's GID rather than their UID. This can significantly
7495 reduce the size of some configuration files. A user may also be in
7496 more than one group.
7500 Login classes are an extension to the group mechanism that provide
7501 additional flexibility when tailoring the system to different
7504 Password change time
7506 By default DragonFly does not force users to change their
7507 passwords periodically. You can enforce this on a per-user basis,
7508 forcing some or all of your users to change their passwords after
7509 a certain amount of time has elapsed.
7513 By default DragonFly does not expire accounts. If you are creating
7514 accounts that you know have a limited lifespan, for example, in a
7515 school where you have accounts for the students, then you can
7516 specify when the account expires. After the expiry time has
7517 elapsed the account cannot be used to log in to the system,
7518 although the account's directories and files will remain.
7522 The user name uniquely identifies the account to DragonFly, but
7523 does not necessarily reflect the user's real name. This
7524 information can be associated with the account.
7528 The home directory is the full path to a directory on the system
7529 in which the user will start when logging on to the system. A
7530 common convention is to put all user home directories under
7531 /home/username or /usr/home/username. The user would store their
7532 personal files in their home directory, and any directories they
7533 may create in there.
7537 The shell provides the default environment users use to interact
7538 with the system. There are many different kinds of shells, and
7539 experienced users will have their own preferences, which can be
7540 reflected in their account settings.
7542 There are three main types of accounts: the Superuser, system users, and
7543 user accounts. The Superuser account, usually called root, is used to
7544 manage the system with no limitations on privileges. System users run
7545 services. Finally, user accounts are used by real people, who log on, read
7548 ----------------------------------------------------------------------
7550 8.3 The Superuser Account
7552 The superuser account, usually called root, comes preconfigured to
7553 facilitate system administration, and should not be used for day-to-day
7554 tasks like sending and receiving mail, general exploration of the system,
7557 This is because the superuser, unlike normal user accounts, can operate
7558 without limits, and misuse of the superuser account may result in
7559 spectacular disasters. User accounts are unable to destroy the system by
7560 mistake, so it is generally best to use normal user accounts whenever
7561 possible, unless you especially need the extra privilege.
7563 You should always double and triple-check commands you issue as the
7564 superuser, since an extra space or missing character can mean irreparable
7567 So, the first thing you should do after reading this chapter is to create
7568 an unprivileged user account for yourself for general usage if you have
7569 not already. This applies equally whether you are running a multi-user or
7570 single-user machine. Later in this chapter, we discuss how to create
7571 additional accounts, and how to change between the normal user and
7574 ----------------------------------------------------------------------
7578 System users are those used to run services such as DNS, mail, web
7579 servers, and so forth. The reason for this is security; if all services
7580 ran as the superuser, they could act without restriction.
7582 Examples of system users are daemon, operator, bind (for the Domain Name
7583 Service), and news. Often sysadmins create httpd to run web servers they
7586 nobody is the generic unprivileged system user. However, it is important
7587 to keep in mind that the more services that use nobody, the more files and
7588 processes that user will become associated with, and hence the more
7589 privileged that user becomes.
7591 ----------------------------------------------------------------------
7595 User accounts are the primary means of access for real people to the
7596 system, and these accounts insulate the user and the environment,
7597 preventing the users from damaging the system or other users, and allowing
7598 users to customize their environment without affecting others.
7600 Every person accessing your system should have a unique user account. This
7601 allows you to find out who is doing what, prevent people from clobbering
7602 each others' settings or reading each others' mail, and so forth.
7604 Each user can set up their own environment to accommodate their use of the
7605 system, by using alternate shells, editors, key bindings, and language.
7607 ----------------------------------------------------------------------
7609 8.6 Modifying Accounts
7611 There are a variety of different commands available in the UNIX
7612 environment to manipulate user accounts. The most common commands are
7613 summarized below, followed by more detailed examples of their usage.
7615 +------------------------------------------------------------------------+
7616 | Command | Summary |
7617 |------------+-----------------------------------------------------------|
7618 | adduser(8) | The recommended command-line application for adding new |
7620 |------------+-----------------------------------------------------------|
7621 | rmuser(8) | The recommended command-line application for removing |
7623 |------------+-----------------------------------------------------------|
7624 | chpass(1) | A flexible tool to change user database information. |
7625 |------------+-----------------------------------------------------------|
7626 | passwd(1) | The simple command-line tool to change user passwords. |
7627 |------------+-----------------------------------------------------------|
7628 | pw(8) | A powerful and flexible tool to modify all aspects of |
7629 | | user accounts. |
7630 +------------------------------------------------------------------------+
7632 ----------------------------------------------------------------------
7636 adduser(8) is a simple program for adding new users. It creates entries in
7637 the system passwd and group files. It will also create a home directory
7638 for the new user, copy in the default configuration files (``dotfiles'')
7639 from /usr/share/skel, and can optionally mail the new user a welcome
7642 To create the initial configuration file, use adduser -s -config_create.
7643 [8] Next, we configure adduser(8) defaults, and create our first user
7644 account, since using root for normal usage is evil and nasty.
7646 Example 8-1. Configuring adduser and adding a user
7649 Use option ``-silent'' if you don't want to see all warnings and questions.
7651 Check /etc/master.passwd
7653 Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
7654 Your default shell is: zsh -> /usr/local/bin/zsh
7655 Enter your default HOME partition: [/home]:
7656 Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
7657 Send message from file: /etc/adduser.message no
7658 [/etc/adduser.message]: no
7660 Use passwords (y/n) [y]: y
7662 Write your changes to /etc/adduser.conf? (y/n) [n]: y
7665 Don't worry about mistakes. I will give you the chance later to correct any input.
7666 Enter username [a-z0-9_-]: jru
7667 Enter full name []: J. Random User
7668 Enter shell csh date no sh tcsh zsh [zsh]:
7669 Enter home directory (full path) [/home/jru]:
7671 Enter login class: default []:
7672 Login group jru [jru]:
7673 Login group is ``jru''. Invite jru into other groups: guest no
7676 Enter password again []:
7680 Fullname: J. Random User
7686 Shell: /usr/local/bin/zsh
7689 Copy files from /usr/share/skel to /home/jru
7690 Add another user? (y/n) [y]: n
7694 In summary, we changed the default shell to zsh (an additional shell found
7695 in pkgsrc), and turned off the sending of a welcome mail to added users.
7696 We then saved the configuration, created an account for jru, and made sure
7697 jru is in wheel group (so that she may assume the role of root with the
7700 Note: The password you type in is not echoed, nor are asterisks
7701 displayed. Make sure you do not mistype the password twice.
7703 Note: Just use adduser(8) without arguments from now on, and you will
7704 not have to go through changing the defaults. If the program asks you to
7705 change the defaults, exit the program, and try the -s option.
7707 ----------------------------------------------------------------------
7711 You can use rmuser(8) to completely remove a user from the system.
7712 rmuser(8) performs the following steps:
7714 1. Removes the user's crontab(1) entry (if any).
7716 2. Removes any at(1) jobs belonging to the user.
7718 3. Kills all processes owned by the user.
7720 4. Removes the user from the system's local password file.
7722 5. Removes the user's home directory (if it is owned by the user).
7724 6. Removes the incoming mail files belonging to the user from /var/mail.
7726 7. Removes all files owned by the user from temporary file storage areas
7729 8. Finally, removes the username from all groups to which it belongs in
7732 Note: If a group becomes empty and the group name is the same as the
7733 username, the group is removed; this complements the per-user unique
7734 groups created by adduser(8).
7736 rmuser(8) cannot be used to remove superuser accounts, since that is
7737 almost always an indication of massive destruction.
7739 By default, an interactive mode is used, which attempts to make sure you
7740 know what you are doing.
7742 Example 8-2. rmuser Interactive Account Removal
7745 Matching password entry:
7746 jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
7747 Is this the entry you wish to remove? y
7748 Remove user's home directory (/home/jru)? y
7749 Updating password file, updating databases, done.
7750 Updating group file: trusted (removing group jru -- personal group is empty) done.
7751 Removing user's incoming mail file /var/mail/jru: done.
7752 Removing files belonging to jru from /tmp: done.
7753 Removing files belonging to jru from /var/tmp: done.
7754 Removing files belonging to jru from /var/tmp/vi.recover: done.
7757 ----------------------------------------------------------------------
7761 chpass(1) changes user database information such as passwords, shells, and
7762 personal information.
7764 Only system administrators, as the superuser, may change other users'
7765 information and passwords with chpass(1).
7767 When passed no options, aside from an optional username, chpass(1)
7768 displays an editor containing user information. When the user exists from
7769 the editor, the user database is updated with the new information.
7771 Example 8-3. Interactive chpass by Superuser
7773 #Changing user database information for jru.
7777 Gid [# or name]: 1001
7778 Change [month day year]:
7779 Expire [month day year]:
7781 Home directory: /home/jru
7782 Shell: /usr/local/bin/zsh
7783 Full Name: J. Random User
7789 The normal user can change only a small subset of this information, and
7790 only for themselves.
7792 Example 8-4. Interactive chpass by Normal User
7794 #Changing user database information for jru.
7795 Shell: /usr/local/bin/zsh
7796 Full Name: J. Random User
7802 Note: chfn(1) and chsh(1) are just links to chpass(1), as are
7803 ypchpass(1), ypchfn(1), and ypchsh(1). NIS support is automatic, so
7804 specifying the yp before the command is not necessary. If this is
7805 confusing to you, do not worry, NIS will be covered in Chapter 19.
7807 ----------------------------------------------------------------------
7811 passwd(1) is the usual way to change your own password as a user, or
7812 another user's password as the superuser.
7814 Note: To prevent accidental or unauthorized changes, the original
7815 password must be entered before a new password can be set.
7817 Example 8-5. Changing Your Password
7820 Changing local password for jru.
7823 Retype new password:
7824 passwd: updating the database...
7827 Example 8-6. Changing Another User's Password as the Superuser
7830 Changing local password for jru.
7832 Retype new password:
7833 passwd: updating the database...
7836 Note: As with chpass(1), yppasswd(1) is just a link to passwd(1), so NIS
7837 works with either command.
7839 ----------------------------------------------------------------------
7843 pw(8) is a command line utility to create, remove, modify, and display
7844 users and groups. It functions as a front end to the system user and group
7845 files. pw(8) has a very powerful set of command line options that make it
7846 suitable for use in shell scripts, but new users may find it more
7847 complicated than the other commands presented here.
7849 ----------------------------------------------------------------------
7853 If you have users, the ability to limit their system use may have come to
7854 mind. DragonFly provides several ways an administrator can limit the
7855 amount of system resources an individual may use. These limits are divided
7856 into two sections: disk quotas, and other resource limits.
7858 Disk quotas limit disk usage to users, and they provide a way to quickly
7859 check that usage without calculating it every time. Quotas are discussed
7862 The other resource limits include ways to limit the amount of CPU, memory,
7863 and other resources a user may consume. These are defined using login
7864 classes and are discussed here.
7866 Login classes are defined in /etc/login.conf. The precise semantics are
7867 beyond the scope of this section, but are described in detail in the
7868 login.conf(5) manual page. It is sufficient to say that each user is
7869 assigned to a login class (default by default), and that each login class
7870 has a set of login capabilities associated with it. A login capability is
7871 a name=value pair, where name is a well-known identifier and value is an
7872 arbitrary string processed accordingly depending on the name. Setting up
7873 login classes and capabilities is rather straight-forward and is also
7874 described in login.conf(5).
7876 Resource limits are different from plain vanilla login capabilities in two
7877 ways. First, for every limit, there is a soft (current) and hard limit. A
7878 soft limit may be adjusted by the user or application, but may be no
7879 higher than the hard limit. The latter may be lowered by the user, but
7880 never raised. Second, most resource limits apply per process to a specific
7881 user, not the user as a whole. Note, however, that these differences are
7882 mandated by the specific handling of the limits, not by the implementation
7883 of the login capability framework (i.e., they are not really a special
7884 case of login capabilities).
7886 And so, without further ado, below are the most commonly used resource
7887 limits (the rest, along with all the other login capabilities, may be
7888 found in login.conf(5)).
7892 The limit on the size of a core file generated by a program is,
7893 for obvious reasons, subordinate to other limits on disk usage
7894 (e.g., filesize, or disk quotas). Nevertheless, it is often used
7895 as a less-severe method of controlling disk space consumption:
7896 since users do not generate core files themselves, and often do
7897 not delete them, setting this may save them from running out of
7898 disk space should a large program (e.g., emacs) crash.
7902 This is the maximum amount of CPU time a user's process may
7903 consume. Offending processes will be killed by the kernel.
7905 Note: This is a limit on CPU time consumed, not percentage of
7906 the CPU as displayed in some fields by top(1) and ps(1). A limit
7907 on the latter is, at the time of this writing, not possible, and
7908 would be rather useless: legitimate use of a compiler, for
7909 instance, can easily use almost 100% of a CPU for some time.
7913 This is the maximum size of a file the user may possess. Unlike
7914 disk quotas, this limit is enforced on individual files, not the
7915 set of all files a user owns.
7919 This is the maximum number of processes a user may be running.
7920 This includes foreground and background processes alike. For
7921 obvious reasons, this may not be larger than the system limit
7922 specified by the kern.maxproc sysctl(8). Also note that setting
7923 this too small may hinder a user's productivity: it is often
7924 useful to be logged in multiple times or execute pipelines. Some
7925 tasks, such as compiling a large program, also spawn multiple
7926 processes (e.g., make(1), cc(1), and other intermediate
7931 This is the maximum amount a memory a process may have requested
7932 to be locked into main memory (e.g., see mlock(2)). Some
7933 system-critical programs, such as amd(8), lock into main memory
7934 such that in the event of being swapped out, they do not
7935 contribute to a system's trashing in time of trouble.
7939 This is the maximum amount of memory a process may consume at any
7940 given time. It includes both core memory and swap usage. This is
7941 not a catch-all limit for restricting memory consumption, but it
7946 This is the maximum amount of files a process may have open. In
7947 DragonFly, files are also used to represent sockets and IPC
7948 channels; thus, be careful not to set this too low. The
7949 system-wide limit for this is defined by the kern.maxfiles
7954 This is the limit on the amount of network memory, and thus mbufs,
7955 a user may consume. This originated as a response to an old DoS
7956 attack by creating a lot of sockets, but can be generally used to
7957 limit network communications.
7961 This is the maximum size a process' stack may grow to. This alone
7962 is not sufficient to limit the amount of memory a program may use;
7963 consequently, it should be used in conjunction with other limits.
7965 There are a few other things to remember when setting resource limits.
7966 Following are some general tips, suggestions, and miscellaneous comments.
7968 * Processes started at system startup by /etc/rc are assigned to the
7971 * Although the /etc/login.conf that comes with the system is a good
7972 source of reasonable values for most limits, only you, the
7973 administrator, can know what is appropriate for your system. Setting a
7974 limit too high may open your system up to abuse, while setting it too
7975 low may put a strain on productivity.
7977 * Users of the X Window System (X11) should probably be granted more
7978 resources than other users. X11 by itself takes a lot of resources,
7979 but it also encourages users to run more programs simultaneously.
7981 * Remember that many limits apply to individual processes, not the user
7982 as a whole. For example, setting openfiles to 50 means that each
7983 process the user runs may open up to 50 files. Thus, the gross amount
7984 of files a user may open is the value of openfiles multiplied by the
7985 value of maxproc. This also applies to memory consumption.
7987 For further information on resource limits and login classes and
7988 capabilities in general, please consult the relevant manual pages:
7989 cap_mkdb(1), getrlimit(2), login.conf(5).
7991 ----------------------------------------------------------------------
7993 8.8 Personalizing Users
7995 Localization is an environment set up by the system administrator or user
7996 to accommodate different languages, character sets, date and time
7997 standards, and so on. This is discussed in the localization chapter.
7999 ----------------------------------------------------------------------
8003 A group is simply a list of users. Groups are identified by their group
8004 name and GID (Group ID). In DragonFly (and most other UNIX like systems),
8005 the two factors the kernel uses to decide whether a process is allowed to
8006 do something is its user ID and list of groups it belongs to. Unlike a
8007 user ID, a process has a list of groups associated with it. You may hear
8008 some things refer to the ``group ID'' of a user or process; most of the
8009 time, this just means the first group in the list.
8011 The group name to group ID map is in /etc/group. This is a plain text file
8012 with four colon-delimited fields. The first field is the group name, the
8013 second is the encrypted password, the third the group ID, and the fourth
8014 the comma-delimited list of members. It can safely be edited by hand
8015 (assuming, of course, that you do not make any syntax errors!). For a more
8016 complete description of the syntax, see the group(5) manual page.
8018 If you do not want to edit /etc/group manually, you can use the pw(8)
8019 command to add and edit groups. For example, to add a group called teamtwo
8020 and then confirm that it exists you can use:
8022 Example 8-7. Adding a Group Using pw(8)
8024 # pw groupadd teamtwo
8025 # pw groupshow teamtwo
8028 The number 1100 above is the group ID of the group teamtwo. Right now,
8029 teamtwo has no members, and is thus rather useless. Let's change that by
8030 inviting jru to the teamtwo group.
8032 Example 8-8. Adding Somebody to a Group Using pw(8)
8034 # pw groupmod teamtwo -M jru
8035 # pw groupshow teamtwo
8038 The argument to the -M option is a comma-delimited list of users who are
8039 members of the group. From the preceding sections, we know that the
8040 password file also contains a group for each user. The latter (the user)
8041 is automatically added to the group list by the system; the user will not
8042 show up as a member when using the groupshow command to pw(8), but will
8043 show up when the information is queried via id(1) or similar tool. In
8044 other words, pw(8) only manipulates the /etc/group file; it will never
8045 attempt to read additionally data from /etc/passwd.
8047 Example 8-9. Using id(1) to Determine Group Membership
8050 uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)
8052 As you can see, jru is a member of the groups jru and teamtwo.
8054 For more information about pw(8), see its manual page, and for more
8055 information on the format of /etc/group, consult the group(5) manual page.
8057 ----------------------------------------------------------------------
8059 Chapter 9 Configuring the DragonFly Kernel
8061 Updated and restructured by Jim Mock. Originally contributed by Jake
8066 The kernel is the core of the DragonFly operating system. It is
8067 responsible for managing memory, enforcing security controls, networking,
8068 disk access, and much more. While more and more of DragonFly becomes
8069 dynamically configurable it is still occasionally necessary to reconfigure
8070 and recompile your kernel.
8072 After reading this chapter, you will know:
8074 * Why you might need to build a custom kernel.
8076 * How to write a kernel configuration file, or alter an existing
8079 * How to use the kernel configuration file to create and build a new
8082 * How to install the new kernel.
8084 * How to create any entries in /dev that may be required.
8086 * How to troubleshoot if things go wrong.
8088 ----------------------------------------------------------------------
8090 9.2 Why Build a Custom Kernel?
8092 Traditionally, DragonFly has had what is called a ``monolithic'' kernel.
8093 This means that the kernel was one large program, supported a fixed list
8094 of devices, and if you wanted to change the kernel's behavior then you had
8095 to compile a new kernel, and then reboot your computer with the new
8098 Today, DragonFly is rapidly moving to a model where much of the kernel's
8099 functionality is contained in modules which can be dynamically loaded and
8100 unloaded from the kernel as necessary. This allows the kernel to adapt to
8101 new hardware suddenly becoming available (such as PCMCIA cards in a
8102 laptop), or for new functionality to be brought into the kernel that was
8103 not necessary when the kernel was originally compiled. This is known as a
8104 modular kernel. Colloquially these are called KLDs.
8106 Despite this, it is still necessary to carry out some static kernel
8107 configuration. In some cases this is because the functionality is so tied
8108 to the kernel that it can not be made dynamically loadable. In others it
8109 may simply be because no one has yet taken the time to write a dynamic
8110 loadable kernel module for that functionality yet.
8112 Building a custom kernel is one of the most important rites of passage
8113 nearly every UNIX user must endure. This process, while time consuming,
8114 will provide many benefits to your DragonFly system. Unlike the GENERIC
8115 kernel, which must support a wide range of hardware, a custom kernel only
8116 contains support for your PC's hardware. This has a number of benefits,
8119 * Faster boot time. Since the kernel will only probe the hardware you
8120 have on your system, the time it takes your system to boot will
8121 decrease dramatically.
8123 * Less memory usage. A custom kernel often uses less memory than the
8124 GENERIC kernel, which is important because the kernel must always be
8125 present in real memory. For this reason, a custom kernel is especially
8126 useful on a system with a small amount of RAM.
8128 * Additional hardware support. A custom kernel allows you to add in
8129 support for devices such as sound cards, which are not present in the
8132 ----------------------------------------------------------------------
8134 9.3 Building and Installing a Custom Kernel
8136 First, let us take a quick tour of the kernel build directory. All
8137 directories mentioned will be relative to the main /usr/src/sys directory,
8138 which is also accessible through /sys. There are a number of
8139 subdirectories here representing different parts of the kernel, but the
8140 most important, for our purposes, are arch/conf, where you will edit your
8141 custom kernel configuration, and compile, which is the staging area where
8142 your kernel will be built. arch represents either i386 or amd64, at this
8143 point in development. Everything inside a particular architecture's
8144 directory deals with that architecture only; the rest of the code is
8145 common to all platforms to which DragonFly could potentially be ported.
8146 Notice the logical organization of the directory structure, with each
8147 supported device, file system, and option in its own subdirectory.
8149 Note: If there is not a /usr/src/sys directory on your system, then the
8150 kernel source has not been installed. The easiest way to do this is via
8153 Next, move to the arch/conf directory and copy the GENERIC configuration
8154 file to the name you want to give your kernel. For example:
8156 # cd /usr/src/sys/i386/conf
8157 # cp GENERIC MYKERNEL
8159 Traditionally, this name is in all capital letters and, if you are
8160 maintaining multiple DragonFly machines with different hardware, it is a
8161 good idea to name it after your machine's hostname. We will call it
8162 MYKERNEL for the purpose of this example.
8164 Tip: Storing your kernel config file directly under /usr/src can be a
8165 bad idea. If you are experiencing problems it can be tempting to just
8166 delete /usr/src and start again. Five seconds after you do that you
8167 realize that you have deleted your custom kernel config file. Do not
8168 edit GENERIC directly, as it may get overwritten the next time you
8169 update your source tree, and your kernel modifications will be lost.
8171 You might want to keep your kernel config file elsewhere, and then
8172 create a symbolic link to the file in the i386 directory.
8176 # cd /usr/src/sys/i386/conf
8177 # mkdir /root/kernels
8178 # cp GENERIC /root/kernels/MYKERNEL
8179 # ln -s /root/kernels/MYKERNEL
8181 Note: You must execute these and all of the following commands under the
8182 root account or you will get permission denied errors.
8184 Now, edit MYKERNEL with your favorite text editor. If you are just
8185 starting out, the only editor available will probably be vi, which is too
8186 complex to explain here, but is covered well in many books in the
8187 bibliography. However, DragonFly does offer an easier editor called ee
8188 which, if you are a beginner, should be your editor of choice. Feel free
8189 to change the comment lines at the top to reflect your configuration or
8190 the changes you have made to differentiate it from GENERIC.
8192 If you have built a kernel under SunOS(TM) or some other BSD operating
8193 system, much of this file will be very familiar to you. If you are coming
8194 from some other operating system such as DOS, on the other hand, the
8195 GENERIC configuration file might seem overwhelming to you, so follow the
8196 descriptions in the Configuration File section slowly and carefully.
8198 Note: Be sure to always check the file /usr/src/UPDATING, before you
8199 perform any update steps, in the case you sync your source tree with the
8200 latest sources of the DragonFly project. In this file all important
8201 issues with updating DragonFly are typed out. /usr/src/UPDATING always
8202 fits your version of the DragonFly source, and is therefore more
8203 accurate for new information than the handbook.
8207 1. Change to the /usr/src directory.
8211 2. Compile the kernel.
8213 # make buildkernel KERNCONF=MYKERNEL
8215 3. Install the new kernel.
8217 # make installkernel KERNCONF=MYKERNEL
8219 If you have not upgraded your source tree in any way since the last time
8220 you successfully completed a buildworld-installworld cycle (you have not
8221 run CVSup), then it is safe to use the quickworld and quickkernel,
8222 buildworld, buildkernel sequence.
8224 The new kernel will be copied to the root directory as /kernel and the old
8225 kernel will be moved to /kernel.old. Now, shutdown the system and reboot
8226 to use your new kernel. In case something goes wrong, there are some
8227 troubleshooting instructions at the end of this chapter. Be sure to read
8228 the section which explains how to recover in case your new kernel does not
8231 Note: If you have added any new devices (such as sound cards), you may
8232 have to add some device nodes to your /dev directory before you can use
8233 them. For more information, take a look at Making Device Nodes section
8234 later on in this chapter.
8236 ----------------------------------------------------------------------
8238 9.4 The Configuration File
8240 The general format of a configuration file is quite simple. Each line
8241 contains a keyword and one or more arguments. For simplicity, most lines
8242 only contain one argument. Anything following a # is considered a comment
8243 and ignored. The following sections describe each keyword, generally in
8244 the order they are listed in GENERIC, although some related keywords have
8245 been grouped together in a single section (such as Networking) even though
8246 they are actually scattered throughout the GENERIC file. An exhaustive
8247 list of options and more detailed explanations of the device lines is
8248 present in the LINT configuration file, located in the same directory as
8249 GENERIC. If you are in doubt as to the purpose or necessity of a line,
8250 check first in LINT.
8252 The following is an example GENERIC kernel configuration file with various
8253 additional comments where needed for clarity. This example should match
8254 your copy in /usr/src/sys/i386/conf/GENERIC fairly closely. For details of
8255 all the possible kernel options, see /usr/src/sys/i386/conf/LINT.
8259 # GENERIC -- Generic kernel configuration file for DragonFly/i386
8261 # Check the LINT configuration file in sys/i386/conf, for an
8262 # exhaustive list of options.
8265 The following are the mandatory keywords required in every kernel you
8270 This is the machine architecture. It must be either i386, or amd64.
8276 The above option specifies the type of CPU you have in your system. You
8277 may have multiple instances of the CPU line (i.e., you are not sure
8278 whether you should use I586_CPU or I686_CPU), however, for a custom
8279 kernel, it is best to specify only the CPU you have. If you are unsure of
8280 your CPU type, you can check the /var/run/dmesg.boot file to view your
8285 This is the identification of the kernel. You should change this to
8286 whatever you named your kernel, i.e. MYKERNEL if you have followed the
8287 instructions of the previous examples. The value you put in the ident
8288 string will print when you boot up the kernel, so it is useful to give the
8289 new kernel a different name if you want to keep it separate from your
8290 usual kernel (i.e. you want to build an experimental kernel).
8294 The maxusers option sets the size of a number of important system tables.
8295 This number is supposed to be roughly equal to the number of simultaneous
8296 users you expect to have on your machine.
8298 (Recommended) The system will auto-tune this setting for you if you
8299 explicitly set it to 0[9]. If you want to manage it yourself you will want
8300 to set maxusers to at least 4, especially if you are using the X Window
8301 System or compiling software. The reason is that the most important table
8302 set by maxusers is the maximum number of processes, which is set to 20 +
8303 16 * maxusers, so if you set maxusers to 1, then you can only have 36
8304 simultaneous processes, including the 18 or so that the system starts up
8305 at boot time, and the 15 or so you will probably create when you start the
8306 X Window System. Even a simple task like reading a manual page will start
8307 up nine processes to filter, decompress, and view it. Setting maxusers to
8308 64 will allow you to have up to 1044 simultaneous processes, which should
8309 be enough for nearly all uses. If, however, you see the dreaded proc table
8310 full error when trying to start another program, or are running a server
8311 with a large number of simultaneous users, you can always increase the
8314 Note: maxusers does not limit the number of users which can log into
8315 your machine. It simply sets various table sizes to reasonable values
8316 considering the maximum number of users you will likely have on your
8317 system and how many processes each of them will be running. One keyword
8318 which does limit the number of simultaneous remote logins and X terminal
8319 windows is pseudo-device pty 16.
8321 # Floating point support - do not disable.
8322 device npx0 at nexus? port IO_NPX irq 13
8324 npx0 is the interface to the floating point math unit in DragonFly, which
8325 is either the hardware co-processor or the software math emulator. This is
8328 # Pseudo devices - the number indicates how many units to allocate.
8329 pseudo-device loop # Network loopback
8331 This is the generic loopback device for TCP/IP. If you telnet or FTP to
8332 localhost (a.k.a., 127.0.0.1) it will come back at you through this
8333 device. This is mandatory.
8335 Everything that follows is more or less optional. See the notes underneath
8336 or next to each option for more information.
8338 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
8340 The normal build process of the DragonFly does not include debugging
8341 information when building the kernel and strips most symbols after the
8342 resulting kernel is linked, to save some space at the install location. If
8343 you are going to do tests of kernels in the DEVELOPMENT branch or develop
8344 changes of your own for the DragonFly kernel, you might want to uncomment
8345 this line. It will enable the use of the -g option which enables debugging
8346 information when passed to gcc(1).
8348 options MATH_EMULATE #Support for x87 emulation
8350 This line allows the kernel to simulate a math co-processor if your
8351 computer does not have one (386 or 486SX). If you have a 486DX, or a 386
8352 or 486SX (with a separate 387 or 487 chip), or higher (Pentium,
8353 Pentium II, etc.), you can comment this line out.
8355 Note: The normal math co-processor emulation routines that come with
8356 DragonFly are not very accurate. If you do not have a math co-processor,
8357 and you need the best accuracy, it is recommended that you change this
8358 option to GPL_MATH_EMULATE to use the GNU math support, which is not
8359 included by default for licensing reasons.
8361 options INET #InterNETworking
8363 Networking support. Leave this in, even if you do not plan to be connected
8364 to a network. Most programs require at least loopback networking (i.e.,
8365 making network connections within your PC), so this is essentially
8368 options INET6 #IPv6 communications protocols
8370 This enables the IPv6 communication protocols.
8372 options FFS #Berkeley Fast Filesystem
8373 options FFS_ROOT #FFS usable as root device [keep this!]
8375 This is the basic hard drive Filesystem. Leave it in if you boot from the
8378 options UFS_DIRHASH #Improve performance on big directories
8380 This option includes functionality to speed up disk operations on large
8381 directories, at the expense of using additional memory. You would normally
8382 keep this for a large server, or interactive workstation, and remove it if
8383 you are using DragonFly on a smaller system where memory is at a premium
8384 and disk access speed is less important, such as a firewall.
8386 options SOFTUPDATES #Enable FFS Soft Updates support
8388 This option enables Soft Updates in the kernel, this will help speed up
8389 write access on the disks. Even when this functionality is provided by the
8390 kernel, it must be turned on for specific disks. Review the output from
8391 mount(8) to see if Soft Updates is enabled for your system disks. If you
8392 do not see the soft-updates option then you will need to activate it using
8393 the tunefs(8) (for existing filesystems) or newfs(8) (for new filesystems)
8396 options MFS #Memory Filesystem
8397 options MD_ROOT #MD is a potential root device
8399 This is the memory-mapped filesystem. This is basically a RAM disk for
8400 fast storage of temporary files, useful if you have a lot of swap space
8401 that you want to take advantage of. A perfect place to mount an MFS
8402 partition is on the /tmp directory, since many programs store temporary
8403 data here. To mount an MFS RAM disk on /tmp, add the following line to
8406 /dev/ad1s2b /tmp mfs rw 0 0
8408 Now you simply need to either reboot, or run the command mount /tmp.
8410 options NFS #Network Filesystem
8411 options NFS_ROOT #NFS usable as root device, NFS required
8413 The network Filesystem. Unless you plan to mount partitions from a UNIX
8414 file server over TCP/IP, you can comment these out.
8416 options MSDOSFS #MSDOS Filesystem
8418 The MS-DOS Filesystem. Unless you plan to mount a DOS formatted hard drive
8419 partition at boot time, you can safely comment this out. It will be
8420 automatically loaded the first time you mount a DOS partition, as
8421 described above. Also, the excellent mtools software (in pkgsrc) allows
8422 you to access DOS floppies without having to mount and unmount them (and
8423 does not require MSDOSFS at all).
8425 options CD9660 #ISO 9660 Filesystem
8426 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
8428 The ISO 9660 Filesystem for CDROMs. Comment it out if you do not have a
8429 CDROM drive or only mount data CDs occasionally (since it will be
8430 dynamically loaded the first time you mount a data CD). Audio CDs do not
8431 need this Filesystem.
8433 options PROCFS #Process filesystem
8435 The process filesystem. This is a ``pretend'' filesystem mounted on /proc
8436 which allows programs like ps(1) to give you more information on what
8437 processes are running.
8439 options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]
8441 Compatibility with 4.3BSD. Leave this in; some programs will act strangely
8442 if you comment this out.
8444 options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI
8446 This causes the kernel to pause for 15 seconds before probing each SCSI
8447 device in your system. If you only have IDE hard drives, you can ignore
8448 this, otherwise you will probably want to lower this number, perhaps to
8449 five seconds (5000 ms), to speed up booting. Of course, if you do this,
8450 and DragonFly has trouble recognizing your SCSI devices, you will have to
8453 options UCONSOLE #Allow users to grab the console
8455 Allow users to grab the console, which is useful for X users. For example,
8456 you can create a console xterm by typing xterm -C, which will display any
8457 write(1), talk(1), and any other messages you receive, as well as any
8458 console messages sent by the kernel.
8460 options USERCONFIG #boot -c editor
8462 This option allows you to boot the configuration editor from the boot
8465 options VISUAL_USERCONFIG #visual boot -c editor
8467 This option allows you to boot the visual configuration editor from the
8470 options KTRACE #ktrace(1) support
8472 This enables kernel process tracing, which is useful in debugging.
8474 options SYSVSHM #SYSV-style shared memory
8476 This option provides for System V shared memory. The most common use of
8477 this is the XSHM extension in X, which many graphics-intensive programs
8478 will automatically take advantage of for extra speed. If you use X, you
8479 will definitely want to include this.
8481 options SYSVSEM #SYSV-style semaphores
8483 Support for System V semaphores. Less commonly used but only adds a few
8484 hundred bytes to the kernel.
8486 options SYSVMSG #SYSV-style message queues
8488 Support for System V messages. Again, only adds a few hundred bytes to the
8491 Note: The ipcs(1) command will list any processes using each of these
8492 System V facilities.
8494 options P1003_1B #Posix P1003_1B real-time extensions
8495 options _KPOSIX_PRIORITY_SCHEDULING
8497 Real-time extensions added in the 1993 POSIX(R). Certain applications in
8498 the ports collection use these (such as StarOffice).
8500 options ICMP_BANDLIM #Rate limit bad replies
8502 This option enables ICMP error response bandwidth limiting. You typically
8503 want this option as it will help protect the machine from denial of
8504 service packet attacks.
8506 # To make an SMP kernel, the next two are needed
8507 #options SMP # Symmetric MultiProcessor Kernel
8508 #options APIC_IO # Symmetric (APIC) I/O
8510 The above are both required for SMP support.
8514 All PCs supported by DragonFly have one of these. Do not remove, even if
8515 you have no ISA slots. If you have an IBM PS/2 (Micro Channel
8516 Architecture), DragonFly provides some limited support at this time. For
8517 more information about the MCA support, see /usr/src/sys/i386/conf/LINT.
8521 Include this if you have an EISA motherboard. This enables auto-detection
8522 and configuration support for all devices on the EISA bus.
8526 Include this if you have a PCI motherboard. This enables auto-detection of
8527 PCI cards and gatewaying from the PCI to ISA bus.
8531 Include this if you have an AGP card in the system. This will enable
8532 support for AGP, and AGP GART for boards which have these features.
8535 device fdc0 at isa? port IO_FD1 irq 6 drq 2
8536 device fd0 at fdc0 drive 0
8537 device fd1 at fdc0 drive 1
8539 This is the floppy drive controller. fd0 is the A: floppy drive, and fd1
8544 This driver supports all ATA and ATAPI devices. You only need one device
8545 ata line for the kernel to detect all PCI ATA/ATAPI devices on modern
8548 device atadisk # ATA disk drives
8550 This is needed along with device ata for ATA disk drives.
8552 device atapicd # ATAPI CDROM drives
8554 This is needed along with device ata for ATAPI CDROM drives.
8556 device atapifd # ATAPI floppy drives
8558 This is needed along with device ata for ATAPI floppy drives.
8560 device atapist # ATAPI tape drives
8562 This is needed along with device ata for ATAPI tape drives.
8564 options ATA_STATIC_ID #Static device numbering
8566 This makes the controller number static (like the old driver) or else the
8567 device numbers are dynamically allocated.
8569 # ATA and ATAPI devices
8570 device ata0 at isa? port IO_WD1 irq 14
8571 device ata1 at isa? port IO_WD2 irq 15
8573 Use the above for older, non-PCI systems.
8576 device ahb # EISA AHA1742 family
8577 device ahc # AHA2940 and onboard AIC7xxx devices
8578 device amd # AMD 53C974 (Teckram DC-390(T))
8579 device dpt # DPT Smartcache - See LINT for options!
8580 device isp # Qlogic family
8581 device ncr # NCR/Symbios Logic
8582 device sym # NCR/Symbios Logic (newer chipsets)
8590 SCSI controllers. Comment out any you do not have in your system. If you
8591 have an IDE only system, you can remove these altogether.
8594 device scbus # SCSI bus (required)
8595 device da # Direct Access (disks)
8596 device sa # Sequential Access (tape etc)
8598 device pass # Passthrough device (direct SCSI
8601 SCSI peripherals. Again, comment out any you do not have, or if you have
8602 only IDE hardware, you can remove them completely.
8604 Note: The USB umass(4) driver (and a few other drivers) use the SCSI
8605 subsystem even though they are not real SCSI devices. Therefore make
8606 sure not to remove SCSI support, if any such drivers are included in the
8607 kernel configuration.
8610 device ida # Compaq Smart RAID
8611 device amr # AMI MegaRAID
8612 device mlx # Mylex DAC960 family
8614 Supported RAID controllers. If you do not have any of these, you can
8615 comment them out or remove them.
8617 # atkbdc0 controls both the keyboard and the PS/2 mouse
8618 device atkbdc0 at isa? port IO_KBD
8620 The keyboard controller (atkbdc) provides I/O services for the AT keyboard
8621 and PS/2 style pointing devices. This controller is required by the
8622 keyboard driver (atkbd) and the PS/2 pointing device driver (psm).
8624 device atkbd0 at atkbdc? irq 1
8626 The atkbd driver, together with atkbdc controller, provides access to the
8627 AT 84 keyboard or the AT enhanced keyboard which is connected to the AT
8628 keyboard controller.
8630 device psm0 at atkbdc? irq 12
8632 Use this device if your mouse plugs into the PS/2 mouse port.
8636 The video card driver.
8638 # splash screen/screen saver
8639 pseudo-device splash
8641 Splash screen at start up! Screen savers require this too.
8643 # syscons is the default console driver, resembling an SCO console
8646 sc0 is the default console driver, which resembles a SCO console. Since
8647 most full-screen programs access the console through a terminal database
8648 library like termcap, it should not matter whether you use this or vt0,
8649 the VT220 compatible console driver. When you log in, set your TERM
8650 variable to scoansi if full-screen programs have trouble running under
8653 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
8655 #options XSERVER # support for X server on a vt console
8656 #options FAT_CURSOR # start with block cursor
8657 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
8658 #options PCVT_SCANSET=2 # IBM keyboards are non-std
8660 This is a VT220-compatible console driver, backward compatible to
8661 VT100/102. It works well on some laptops which have hardware
8662 incompatibilities with sc0. Also set your TERM variable to vt100 or vt220
8663 when you log in. This driver might also prove useful when connecting to a
8664 large number of different machines over the network, where termcap or
8665 terminfo entries for the sc0 device are often not available -- vt100
8666 should be available on virtually any platform.
8668 # Power management support (see LINT for more options)
8669 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
8671 Advanced Power Management support. Useful for laptops.
8673 # PCCARD (PCMCIA) support
8675 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
8676 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
8678 PCMCIA support. You want this if you are using a laptop.
8680 # Serial (COM) ports
8681 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
8682 device sio1 at isa? port IO_COM2 irq 3
8683 device sio2 at isa? disable port IO_COM3 irq 5
8684 device sio3 at isa? disable port IO_COM4 irq 9
8686 These are the four serial ports referred to as COM1 through COM4 in the
8687 MS-DOS/Windows world.
8689 Note: If you have an internal modem on COM4 and a serial port at COM2,
8690 you will have to change the IRQ of the modem to 2 (for obscure technical
8691 reasons, IRQ2 = IRQ 9) in order to access it from DragonFly. If you have
8692 a multiport serial card, check the manual page for sio(4) for more
8693 information on the proper values for these lines. Some video cards
8694 (notably those based on S3 chips) use IO addresses in the form of
8695 0x*2e8, and since many cheap serial cards do not fully decode the 16-bit
8696 IO address space, they clash with these cards making the COM4 port
8697 practically unavailable.
8699 Each serial port is required to have a unique IRQ (unless you are using
8700 one of the multiport cards where shared interrupts are supported), so
8701 the default IRQs for COM3 and COM4 cannot be used.
8704 device ppc0 at isa? irq 7
8706 This is the ISA-bus parallel port interface.
8708 device ppbus # Parallel port bus (required)
8710 Provides support for the parallel port bus.
8712 device lpt # Printer
8714 Support for parallel port printers.
8716 Note: All three of the above are required to enable parallel printer
8719 device plip # TCP/IP over parallel
8721 This is the driver for the parallel network interface.
8723 device ppi # Parallel port interface device
8725 The general-purpose I/O (``geek port'') + IEEE1284 I/O.
8727 #device vpo # Requires scbus and da
8729 This is for an Iomega Zip drive. It requires scbus and da support. Best
8730 performance is achieved with ports in EPP 1.9 mode.
8732 # PCI Ethernet NICs.
8733 device de # DEC/Intel DC21x4x (``Tulip'')
8734 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
8735 device tx # SMC 9432TX (83c170 ``EPIC'')
8736 device vx # 3Com 3c590, 3c595 (``Vortex'')
8737 device wx # Intel Gigabit Ethernet Card (``Wiseman'')
8739 Various PCI network card drivers. Comment out or remove any of these not
8740 present in your system.
8742 # PCI Ethernet NICs that use the common MII bus controller code.
8743 device miibus # MII bus support
8745 MII bus support is required for some PCI 10/100 Ethernet NICs, namely
8746 those which use MII-compliant transceivers or implement transceiver
8747 control interfaces that operate like an MII. Adding device miibus to the
8748 kernel config pulls in support for the generic miibus API and all of the
8749 PHY drivers, including a generic one for PHYs that are not specifically
8750 handled by an individual driver.
8752 device dc # DEC/Intel 21143 and various workalikes
8753 device rl # RealTek 8129/8139
8754 device sf # Adaptec AIC-6915 (``Starfire'')
8755 device sis # Silicon Integrated Systems SiS 900/SiS 7016
8756 device ste # Sundance ST201 (D-Link DFE-550TX)
8757 device tl # Texas Instruments ThunderLAN
8758 device vr # VIA Rhine, Rhine II
8759 device wb # Winbond W89C840F
8760 device xl # 3Com 3c90x (``Boomerang'', ``Cyclone'')
8762 Drivers that use the MII bus controller code.
8764 # ISA Ethernet NICs.
8765 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
8768 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
8769 # exists only as a PCMCIA device, so there is no ISA attachment needed
8770 # and resources will always be dynamically assigned by the pccard code.
8772 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
8773 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
8774 # mode (the factory default). If you set the switches on your ISA
8775 # card for a manually chosen I/O address and IRQ, you must specify
8776 # those parameters here.
8778 # The probe order of these is presently determined by i386/isa/isa_compat.c.
8779 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
8780 device fe0 at isa? port 0x300
8781 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
8782 device lnc0 at isa? port 0x280 irq 10 drq 0
8783 device cs0 at isa? port 0x300
8784 device sn0 at isa? port 0x300 irq 10
8785 # requires PCCARD (PCMCIA) support to be activated
8788 ISA Ethernet drivers. See /usr/src/sys/i386/conf/LINT for which cards are
8789 supported by which driver.
8791 pseudo-device ether # Ethernet support
8793 ether is only needed if you have an Ethernet card. It includes generic
8794 Ethernet protocol code.
8796 pseudo-device sl 1 # Kernel SLIP
8798 sl is for SLIP support. This has been almost entirely supplanted by PPP,
8799 which is easier to set up, better suited for modem-to-modem connection,
8800 and more powerful. The number after sl specifies how many simultaneous
8801 SLIP sessions to support.
8803 pseudo-device ppp 1 # Kernel PPP
8805 This is for kernel PPP support for dial-up connections. There is also a
8806 version of PPP implemented as a userland application that uses tun and
8807 offers more flexibility and features such as demand dialing. The number
8808 after ppp specifies how many simultaneous PPP connections to support. .
8810 device tun # Packet tunnel.
8812 This is used by the userland PPP software. A number after tun specifies
8813 the number of simultaneous PPP sessions to support. See the PPP section of
8814 this book for more information.
8816 pseudo-device pty # Pseudo-ttys (telnet etc)
8818 This is a ``pseudo-terminal'' or simulated login port. It is used by
8819 incoming telnet and rlogin sessions, xterm, and some other applications
8820 such as Emacs. The number after pty indicates the number of ptys to
8821 create. If you need more than the default of 16 simultaneous xterm windows
8822 and/or remote logins, be sure to increase this number accordingly, up to a
8825 pseudo-device md # Memory ``disks''
8827 Memory disk pseudo-devices.
8829 pseudo-device gif # IPv6 and IPv4 tunneling
8831 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4
8832 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
8834 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
8836 This pseudo-device captures packets that are sent to it and diverts them
8837 to the IPv4/IPv6 translation daemon.
8839 # The `bpf' device enables the Berkeley Packet Filter.
8840 # Be aware of the administrative consequences of enabling this!
8841 pseudo-device bpf # Berkeley packet filter
8843 This is the Berkeley Packet Filter. This pseudo-device allows network
8844 interfaces to be placed in promiscuous mode, capturing every packet on a
8845 broadcast network (e.g., an Ethernet). These packets can be captured to
8846 disk and or examined with the tcpdump(1) program.
8848 Note: The bpf(4) device is also used by dhclient(8) to obtain the IP
8849 address of the default router (gateway) and so on. If you use DHCP,
8850 leave this uncommented.
8853 #device uhci # UHCI PCI->USB interface
8854 #device ohci # OHCI PCI->USB interface
8855 #device usb # USB Bus (required)
8856 #device ugen # Generic
8857 #device uhid # ``Human Interface Devices''
8858 #device ukbd # Keyboard
8859 #device ulpt # Printer
8860 #device umass # Disks/Mass storage - Requires scbus and da
8862 # USB Ethernet, requires mii
8863 #device aue # ADMtek USB ethernet
8864 #device cue # CATC USB ethernet
8865 #device kue # Kawasaki LSI USB ethernet
8867 Support for various USB devices.
8869 For more information and additional devices supported by DragonFly, see
8870 /usr/src/sys/i386/conf/LINT.
8872 ----------------------------------------------------------------------
8874 9.5 Making Device Nodes
8876 Almost every device in the kernel has a corresponding ``node'' entry in
8877 the /dev directory. These nodes look like regular files, but are actually
8878 special entries into the kernel which programs use to access the device.
8879 The shell script /dev/MAKEDEV, which is executed when you first install
8880 the operating system, creates nearly all of the device nodes supported.
8881 However, it does not create all of them, so when you add support for a new
8882 device, it pays to make sure that the appropriate entries are in this
8883 directory, and if not, add them. Here is a simple example:
8885 Suppose you add the IDE CD-ROM support to the kernel. The line to add is:
8889 This means that you should look for some entries that start with acd0 in
8890 the /dev directory, possibly followed by a letter, such as c, or preceded
8891 by the letter r, which means a ``raw'' device. It turns out that those
8892 files are not there, so you must change to the /dev directory and type:
8896 When this script finishes, you will find that there are now acd0c and
8897 racd0c entries in /dev so you know that it executed correctly.
8899 For sound cards, the following command creates the appropriate entries:
8903 Note: When creating device nodes for devices such as sound cards, if
8904 other people have access to your machine, it may be desirable to protect
8905 the devices from outside access by adding them to the /etc/fbtab file.
8906 See fbtab(5) for more information.
8908 Follow this simple procedure for any other non-GENERIC devices which do
8911 Note: All SCSI controllers use the same set of /dev entries, so you do
8912 not need to create these. Also, network cards and SLIP/PPP
8913 pseudo-devices do not have entries in /dev at all, so you do not have to
8914 worry about these either.
8916 ----------------------------------------------------------------------
8918 9.6 If Something Goes Wrong
8920 There are five categories of trouble that can occur when building a custom
8925 If the config(8) command fails when you give it your kernel
8926 description, you have probably made a simple error somewhere.
8927 Fortunately, config(8) will print the line number that it had
8928 trouble with, so you can quickly skip to it with vi. For example,
8931 config: line 17: syntax error
8933 You can skip to the problem in vi by typing 17G in command mode.
8934 Make sure the keyword is typed correctly, by comparing it to the
8935 GENERIC kernel or another reference.
8939 If the make command fails, it usually signals an error in your
8940 kernel description, but not severe enough for config(8) to catch
8941 it. Again, look over your configuration, and if you still cannot
8942 resolve the problem, send mail to the DragonFly Bugs mailing list
8943 with your kernel configuration, and it should be diagnosed very
8946 Installing the new kernel fails:
8948 If the kernel compiled fine, but failed to install (the make
8949 install or make installkernel command failed), the first thing to
8950 check is if your system is running at securelevel 1 or higher (see
8951 init(8)). The kernel installation tries to remove the immutable
8952 flag from your kernel and set the immutable flag on the new one.
8953 Since securelevel 1 or higher prevents unsetting the immutable
8954 flag for any files on the system, the kernel installation needs to
8955 be performed at securelevel 0 or lower.
8957 The kernel does not boot:
8959 If your new kernel does not boot, or fails to recognize your
8960 devices, do not panic! Fortunately, DragonFly has an excellent
8961 mechanism for recovering from incompatible kernels. Simply choose
8962 the kernel you want to boot from at the DragonFly boot loader. You
8963 can access this when the system counts down from 10. Hit any key
8964 except for the Enter key, type unload and then type boot
8965 kernel.old, or the filename of any other kernel that will boot
8966 properly. When reconfiguring a kernel, it is always a good idea to
8967 keep a kernel that is known to work on hand.
8969 After booting with a good kernel you can check over your
8970 configuration file and try to build it again. One helpful resource
8971 is the /var/log/messages file which records, among other things,
8972 all of the kernel messages from every successful boot. Also, the
8973 dmesg(8) command will print the kernel messages from the current
8976 Note: If you are having trouble building a kernel, make sure to
8977 keep a GENERIC, or some other kernel that is known to work on
8978 hand as a different name that will not get erased on the next
8979 build. You cannot rely on kernel.old because when installing a
8980 new kernel, kernel.old is overwritten with the last installed
8981 kernel which may be non-functional. Also, as soon as possible,
8982 move the working kernel to the proper kernel location or
8983 commands such as ps(1) will not work properly. The proper
8984 command to ``unlock'' the kernel file that make installs (in
8985 order to move another kernel back permanently) is:
8987 # chflags noschg /kernel
8989 If you find you cannot do this, you are probably running at a
8990 securelevel(8) greater than zero. Edit kern_securelevel in
8991 /etc/rc.conf and set it to -1, then reboot. You can change it
8992 back to its previous setting when you are happy with your new
8995 And, if you want to ``lock'' your new kernel into place, or any
8996 file for that matter, so that it cannot be moved or tampered
8999 # chflags schg /kernel
9001 The kernel works, but ps(1) does not work any more:
9003 If you have installed a different version of the kernel from the
9004 one that the system utilities have been built with, many
9005 system-status commands like ps(1) and vmstat(8) will not work any
9006 more. You must recompile the libkvm library as well as these
9007 utilities. This is one reason it is not normally a good idea to
9008 use a different version of the kernel from the rest of the
9011 ----------------------------------------------------------------------
9015 Much of this chapter has been taken from the security(7) manual page by
9018 ----------------------------------------------------------------------
9022 This chapter will provide a basic introduction to system security
9023 concepts, some general good rules of thumb, and some advanced topics under
9024 DragonFly. A lot of the topics covered here can be applied to system and
9025 Internet security in general as well. The Internet is no longer a
9026 ``friendly'' place in which everyone wants to be your kind neighbor.
9027 Securing your system is imperative to protect your data, intellectual
9028 property, time, and much more from the hands of hackers and the like.
9030 DragonFly provides an array of utilities and mechanisms to ensure the
9031 integrity and security of your system and network.
9033 After reading this chapter, you will know:
9035 * Basic system security concepts, in respect to DragonFly.
9037 * About the various crypt mechanisms available in DragonFly, such as DES
9040 * How to set up one-time password authentication.
9042 * How to set up KerberosIV.
9044 * How to set up Kerberos5.
9046 * How to create firewalls using IPFW.
9048 * How to configure IPsec and create a VPN between DragonFly/Windows
9051 * How to configure and use OpenSSH, DragonFly's SSH implementation.
9053 Before reading this chapter, you should:
9055 * Understand basic DragonFly and Internet concepts.
9057 ----------------------------------------------------------------------
9061 Security is a function that begins and ends with the system administrator.
9062 While all BSD UNIX multi-user systems have some inherent security, the job
9063 of building and maintaining additional security mechanisms to keep those
9064 users ``honest'' is probably one of the single largest undertakings of the
9065 sysadmin. Machines are only as secure as you make them, and security
9066 concerns are ever competing with the human necessity for convenience. UNIX
9067 systems, in general, are capable of running a huge number of simultaneous
9068 processes and many of these processes operate as servers -- meaning that
9069 external entities can connect and talk to them. As yesterday's
9070 mini-computers and mainframes become today's desktops, and as computers
9071 become networked and internetworked, security becomes an even bigger
9074 Security is best implemented through a layered ``onion'' approach. In a
9075 nutshell, what you want to do is to create as many layers of security as
9076 are convenient and then carefully monitor the system for intrusions. You
9077 do not want to overbuild your security or you will interfere with the
9078 detection side, and detection is one of the single most important aspects
9079 of any security mechanism. For example, it makes little sense to set the
9080 schg flags (see chflags(1)) on every system binary because while this may
9081 temporarily protect the binaries, it prevents an attacker who has broken
9082 in from making an easily detectable change that may result in your
9083 security mechanisms not detecting the attacker at all.
9085 System security also pertains to dealing with various forms of attack,
9086 including attacks that attempt to crash, or otherwise make a system
9087 unusable, but do not attempt to compromise the root account (``break
9088 root''). Security concerns can be split up into several categories:
9090 1. Denial of service attacks.
9092 2. User account compromises.
9094 3. Root compromise through accessible servers.
9096 4. Root compromise via user accounts.
9098 5. Backdoor creation.
9100 A denial of service attack is an action that deprives the machine of
9101 needed resources. Typically, DoS attacks are brute-force mechanisms that
9102 attempt to crash or otherwise make a machine unusable by overwhelming its
9103 servers or network stack. Some DoS attacks try to take advantage of bugs
9104 in the networking stack to crash a machine with a single packet. The
9105 latter can only be fixed by applying a bug fix to the kernel. Attacks on
9106 servers can often be fixed by properly specifying options to limit the
9107 load the servers incur on the system under adverse conditions. Brute-force
9108 network attacks are harder to deal with. A spoofed-packet attack, for
9109 example, is nearly impossible to stop, short of cutting your system off
9110 from the Internet. It may not be able to take your machine down, but it
9111 can saturate your Internet connection.
9113 A user account compromise is even more common than a DoS attack. Many
9114 sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on
9115 their machines. These servers, by default, do not operate over encrypted
9116 connections. The result is that if you have any moderate-sized user base,
9117 one or more of your users logging into your system from a remote location
9118 (which is the most common and convenient way to login to a system) will
9119 have his or her password sniffed. The attentive system admin will analyze
9120 his remote access logs looking for suspicious source addresses even for
9123 One must always assume that once an attacker has access to a user account,
9124 the attacker can break root. However, the reality is that in a well
9125 secured and maintained system, access to a user account does not
9126 necessarily give the attacker access to root. The distinction is important
9127 because without access to root the attacker cannot generally hide his
9128 tracks and may, at best, be able to do nothing more than mess with the
9129 user's files, or crash the machine. User account compromises are very
9130 common because users tend not to take the precautions that sysadmins take.
9132 System administrators must keep in mind that there are potentially many
9133 ways to break root on a machine. The attacker may know the root password,
9134 the attacker may find a bug in a root-run server and be able to break root
9135 over a network connection to that server, or the attacker may know of a
9136 bug in a suid-root program that allows the attacker to break root once he
9137 has broken into a user's account. If an attacker has found a way to break
9138 root on a machine, the attacker may not have a need to install a backdoor.
9139 Many of the root holes found and closed to date involve a considerable
9140 amount of work by the attacker to cleanup after himself, so most attackers
9141 install backdoors. A backdoor provides the attacker with a way to easily
9142 regain root access to the system, but it also gives the smart system
9143 administrator a convenient way to detect the intrusion. Making it
9144 impossible for an attacker to install a backdoor may actually be
9145 detrimental to your security, because it will not close off the hole the
9146 attacker found to break in the first place.
9148 Security remedies should always be implemented with a multi-layered
9149 ``onion peel'' approach and can be categorized as follows:
9151 1. Securing root and staff accounts.
9153 2. Securing root -- root-run servers and suid/sgid binaries.
9155 3. Securing user accounts.
9157 4. Securing the password file.
9159 5. Securing the kernel core, raw devices, and filesystems.
9161 6. Quick detection of inappropriate changes made to the system.
9165 The next section of this chapter will cover the above bullet items in
9168 ----------------------------------------------------------------------
9170 10.3 Securing DragonFly
9172 Command vs. Protocol: Throughout this document, we will use bold text to
9173 refer to a command or application. This is used for instances such as
9174 ssh, since it is a protocol as well as command.
9176 The sections that follow will cover the methods of securing your DragonFly
9177 system that were mentioned in the last section of this chapter.
9179 ----------------------------------------------------------------------
9181 10.3.1 Securing the root Account and Staff Accounts
9183 First off, do not bother securing staff accounts if you have not secured
9184 the root account. Most systems have a password assigned to the root
9185 account. The first thing you do is assume that the password is always
9186 compromised. This does not mean that you should remove the password. The
9187 password is almost always necessary for console access to the machine.
9188 What it does mean is that you should not make it possible to use the
9189 password outside of the console or possibly even with the su(1) command.
9190 For example, make sure that your pty's are specified as being insecure in
9191 the /etc/ttys file so that direct root logins via telnet or rlogin are
9192 disallowed. If using other login services such as sshd, make sure that
9193 direct root logins are disabled there as well. You can do this by editing
9194 your /etc/ssh/sshd_config file, and making sure that PermitRootLogin is
9195 set to NO. Consider every access method -- services such as FTP often fall
9196 through the cracks. Direct root logins should only be allowed via the
9199 Of course, as a sysadmin you have to be able to get to root, so we open up
9200 a few holes. But we make sure these holes require additional password
9201 verification to operate. One way to make root accessible is to add
9202 appropriate staff accounts to the wheel group (in /etc/group). The staff
9203 members placed in the wheel group are allowed to su to root. You should
9204 never give staff members native wheel access by putting them in the wheel
9205 group in their password entry. Staff accounts should be placed in a staff
9206 group, and then added to the wheel group via the /etc/group file. Only
9207 those staff members who actually need to have root access should be placed
9208 in the wheel group. It is also possible, when using an authentication
9209 method such as Kerberos, to use Kerberos' .k5login file in the root
9210 account to allow a ksu(1) to root without having to place anyone at all in
9211 the wheel group. This may be the better solution since the wheel mechanism
9212 still allows an intruder to break root if the intruder has gotten hold of
9213 your password file and can break into a staff account. While having the
9214 wheel mechanism is better than having nothing at all, it is not
9215 necessarily the safest option.
9217 An indirect way to secure staff accounts, and ultimately root access is to
9218 use an alternative login access method and do what is known as
9219 ``starring'' out the encrypted password for the staff accounts. Using the
9220 vipw(8) command, one can replace each instance of an encrypted password
9221 with a single ``*'' character. This command will update the
9222 /etc/master.passwd file and user/password database to disable
9223 password-authenticated logins.
9225 A staff account entry such as:
9227 foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
9229 Should be changed to this:
9231 foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
9233 This change will prevent normal logins from occurring, since the encrypted
9234 password will never match ``*''. With this done, staff members must use
9235 another mechanism to authenticate themselves such as kerberos(1) or ssh(1)
9236 using a public/private key pair. When using something like Kerberos, one
9237 generally must secure the machines which run the Kerberos servers and your
9238 desktop workstation. When using a public/private key pair with ssh, one
9239 must generally secure the machine used to login from (typically one's
9240 workstation). An additional layer of protection can be added to the key
9241 pair by password protecting the key pair when creating it with
9242 ssh-keygen(1). Being able to ``star'' out the passwords for staff accounts
9243 also guarantees that staff members can only login through secure access
9244 methods that you have set up. This forces all staff members to use secure,
9245 encrypted connections for all of their sessions, which closes an important
9246 hole used by many intruders: sniffing the network from an unrelated, less
9249 The more indirect security mechanisms also assume that you are logging in
9250 from a more restrictive server to a less restrictive server. For example,
9251 if your main box is running all sorts of servers, your workstation should
9252 not be running any. In order for your workstation to be reasonably secure
9253 you should run as few servers as possible, up to and including no servers
9254 at all, and you should run a password-protected screen blanker. Of course,
9255 given physical access to a workstation an attacker can break any sort of
9256 security you put on it. This is definitely a problem that you should
9257 consider, but you should also consider the fact that the vast majority of
9258 break-ins occur remotely, over a network, from people who do not have
9259 physical access to your workstation or servers.
9261 Using something like Kerberos also gives you the ability to disable or
9262 change the password for a staff account in one place, and have it
9263 immediately affect all the machines on which the staff member may have an
9264 account. If a staff member's account gets compromised, the ability to
9265 instantly change his password on all machines should not be underrated.
9266 With discrete passwords, changing a password on N machines can be a mess.
9267 You can also impose re-passwording restrictions with Kerberos: not only
9268 can a Kerberos ticket be made to timeout after a while, but the Kerberos
9269 system can require that the user choose a new password after a certain
9270 period of time (say, once a month).
9272 ----------------------------------------------------------------------
9274 10.3.2 Securing Root-run Servers and SUID/SGID Binaries
9276 The prudent sysadmin only runs the servers he needs to, no more, no less.
9277 Be aware that third party servers are often the most bug-prone. For
9278 example, running an old version of imapd or popper is like giving a
9279 universal root ticket out to the entire world. Never run a server that you
9280 have not checked out carefully. Many servers do not need to be run as
9281 root. For example, the ntalk, comsat, and finger daemons can be run in
9282 special user sandboxes. A sandbox is not perfect, unless you go through a
9283 large amount of trouble, but the onion approach to security still stands:
9284 If someone is able to break in through a server running in a sandbox, they
9285 still have to break out of the sandbox. The more layers the attacker must
9286 break through, the lower the likelihood of his success. Root holes have
9287 historically been found in virtually every server ever run as root,
9288 including basic system servers. If you are running a machine through which
9289 people only login via sshd and never login via telnetd or rshd or rlogind,
9290 then turn off those services!
9292 DragonFly now defaults to running ntalkd, comsat, and finger in a sandbox.
9293 Another program which may be a candidate for running in a sandbox is
9294 named(8). /etc/defaults/rc.conf includes the arguments necessary to run
9295 named in a sandbox in a commented-out form. Depending on whether you are
9296 installing a new system or upgrading an existing system, the special user
9297 accounts used by these sandboxes may not be installed. The prudent
9298 sysadmin would research and implement sandboxes for servers whenever
9301 There are a number of other servers that typically do not run in
9302 sandboxes: sendmail, popper, imapd, ftpd, and others. There are
9303 alternatives to some of these, but installing them may require more work
9304 than you are willing to perform (the convenience factor strikes again).
9305 You may have to run these servers as root and rely on other mechanisms to
9306 detect break-ins that might occur through them.
9308 The other big potential root holes in a system are the suid-root and sgid
9309 binaries installed on the system. Most of these binaries, such as rlogin,
9310 reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe,
9311 the system-default suid and sgid binaries can be considered reasonably
9312 safe. Still, root holes are occasionally found in these binaries. A root
9313 hole was found in Xlib in 1998 that made xterm (which is typically suid)
9314 vulnerable. It is better to be safe than sorry and the prudent sysadmin
9315 will restrict suid binaries, that only staff should run, to a special
9316 group that only staff can access, and get rid of (chmod 000) any suid
9317 binaries that nobody uses. A server with no display generally does not
9318 need an xterm binary. Sgid binaries can be almost as dangerous. If an
9319 intruder can break an sgid-kmem binary, the intruder might be able to read
9320 /dev/kmem and thus read the encrypted password file, potentially
9321 compromising any passworded account. Alternatively an intruder who breaks
9322 group kmem can monitor keystrokes sent through pty's, including pty's used
9323 by users who login through secure methods. An intruder that breaks the tty
9324 group can write to almost any user's tty. If a user is running a terminal
9325 program or emulator with a keyboard-simulation feature, the intruder can
9326 potentially generate a data stream that causes the user's terminal to echo
9327 a command, which is then run as that user.
9329 ----------------------------------------------------------------------
9331 10.3.3 Securing User Accounts
9333 User accounts are usually the most difficult to secure. While you can
9334 impose Draconian access restrictions on your staff and ``star'' out their
9335 passwords, you may not be able to do so with any general user accounts you
9336 might have. If you do have sufficient control, then you may win out and be
9337 able to secure the user accounts properly. If not, you simply have to be
9338 more vigilant in your monitoring of those accounts. Use of ssh and
9339 Kerberos for user accounts is more problematic, due to the extra
9340 administration and technical support required, but still a very good
9341 solution compared to a crypted password file.
9343 ----------------------------------------------------------------------
9345 10.3.4 Securing the Password File
9347 The only sure fire way is to * out as many passwords as you can and use
9348 ssh or Kerberos for access to those accounts. Even though the encrypted
9349 password file (/etc/spwd.db) can only be read by root, it may be possible
9350 for an intruder to obtain read access to that file even if the attacker
9351 cannot obtain root-write access.
9353 Your security scripts should always check for and report changes to the
9354 password file (see the Checking file integrity section below).
9356 ----------------------------------------------------------------------
9358 10.3.5 Securing the Kernel Core, Raw Devices, and Filesystems
9360 If an attacker breaks root he can do just about anything, but there are
9361 certain conveniences. For example, most modern kernels have a packet
9362 sniffing device driver built in. Under DragonFly it is called the bpf
9363 device. An intruder will commonly attempt to run a packet sniffer on a
9364 compromised machine. You do not need to give the intruder the capability
9365 and most systems do not have the need for the bpf device compiled in.
9367 But even if you turn off the bpf device, you still have /dev/mem and
9368 /dev/kmem to worry about. For that matter, the intruder can still write to
9369 raw disk devices. Also, there is another kernel feature called the module
9370 loader, kldload(8). An enterprising intruder can use a KLD module to
9371 install his own bpf device, or other sniffing device, on a running kernel.
9372 To avoid these problems you have to run the kernel at a higher secure
9373 level, at least securelevel 1. The securelevel can be set with a sysctl on
9374 the kern.securelevel variable. Once you have set the securelevel to 1,
9375 write access to raw devices will be denied and special chflags flags, such
9376 as schg, will be enforced. You must also ensure that the schg flag is set
9377 on critical startup binaries, directories, and script files -- everything
9378 that gets run up to the point where the securelevel is set. This might be
9379 overdoing it, and upgrading the system is much more difficult when you
9380 operate at a higher secure level. You may compromise and run the system at
9381 a higher secure level but not set the schg flag for every system file and
9382 directory under the sun. Another possibility is to simply mount / and /usr
9383 read-only. It should be noted that being too Draconian in what you attempt
9384 to protect may prevent the all-important detection of an intrusion.
9386 ----------------------------------------------------------------------
9388 10.3.6 Checking File Integrity: Binaries, Configuration Files, Etc.
9390 When it comes right down to it, you can only protect your core system
9391 configuration and control files so much before the convenience factor
9392 rears its ugly head. For example, using chflags to set the schg bit on
9393 most of the files in / and /usr is probably counterproductive, because
9394 while it may protect the files, it also closes a detection window. The
9395 last layer of your security onion is perhaps the most important --
9396 detection. The rest of your security is pretty much useless (or, worse,
9397 presents you with a false sense of safety) if you cannot detect potential
9398 incursions. Half the job of the onion is to slow down the attacker, rather
9399 than stop him, in order to give the detection side of the equation a
9400 chance to catch him in the act.
9402 The best way to detect an incursion is to look for modified, missing, or
9403 unexpected files. The best way to look for modified files is from another
9404 (often centralized) limited-access system. Writing your security scripts
9405 on the extra-secure limited-access system makes them mostly invisible to
9406 potential attackers, and this is important. In order to take maximum
9407 advantage you generally have to give the limited-access box significant
9408 access to the other machines in the business, usually either by doing a
9409 read-only NFS export of the other machines to the limited-access box, or
9410 by setting up ssh key-pairs to allow the limited-access box to ssh to the
9411 other machines. Except for its network traffic, NFS is the least visible
9412 method -- allowing you to monitor the filesystems on each client box
9413 virtually undetected. If your limited-access server is connected to the
9414 client boxes through a switch, the NFS method is often the better choice.
9415 If your limited-access server is connected to the client boxes through a
9416 hub, or through several layers of routing, the NFS method may be too
9417 insecure (network-wise) and using ssh may be the better choice even with
9418 the audit-trail tracks that ssh lays.
9420 Once you give a limited-access box, at least read access to the client
9421 systems it is supposed to monitor, you must write scripts to do the actual
9422 monitoring. Given an NFS mount, you can write scripts out of simple system
9423 utilities such as find(1) and md5(1). It is best to physically md5 the
9424 client-box files at least once a day, and to test control files such as
9425 those found in /etc and /usr/local/etc even more often. When mismatches
9426 are found, relative to the base md5 information the limited-access machine
9427 knows is valid, it should scream at a sysadmin to go check it out. A good
9428 security script will also check for inappropriate suid binaries and for
9429 new or deleted files on system partitions such as / and /usr.
9431 When using ssh rather than NFS, writing the security script is much more
9432 difficult. You essentially have to scp the scripts to the client box in
9433 order to run them, making them visible, and for safety you also need to
9434 scp the binaries (such as find) that those scripts use. The ssh client on
9435 the client box may already be compromised. All in all, using ssh may be
9436 necessary when running over insecure links, but it is also a lot harder to
9439 A good security script will also check for changes to user and staff
9440 members access configuration files: .rhosts, .shosts, .ssh/authorized_keys
9441 and so forth... files that might fall outside the purview of the MD5
9444 If you have a huge amount of user disk space, it may take too long to run
9445 through every file on those partitions. In this case, setting mount flags
9446 to disallow suid binaries and devices on those partitions is a good idea.
9447 The nodev and nosuid options (see mount(8)) are what you want to look
9448 into. You should probably scan them anyway, at least once a week, since
9449 the object of this layer is to detect a break-in whether or not the
9450 break-in is effective.
9452 Process accounting (see accton(8)) is a relatively low-overhead feature of
9453 the operating system which might help as a post-break-in evaluation
9454 mechanism. It is especially useful in tracking down how an intruder has
9455 actually broken into a system, assuming the file is still intact after the
9458 Finally, security scripts should process the log files, and the logs
9459 themselves should be generated in as secure a manner as possible -- remote
9460 syslog can be very useful. An intruder tries to cover his tracks, and log
9461 files are critical to the sysadmin trying to track down the time and
9462 method of the initial break-in. One way to keep a permanent record of the
9463 log files is to run the system console to a serial port and collect the
9464 information on a continuing basis through a secure machine monitoring the
9467 ----------------------------------------------------------------------
9471 A little paranoia never hurts. As a rule, a sysadmin can add any number of
9472 security features, as long as they do not affect convenience, and can add
9473 security features that do affect convenience with some added thought. Even
9474 more importantly, a security administrator should mix it up a bit -- if
9475 you use recommendations such as those given by this document verbatim, you
9476 give away your methodologies to the prospective attacker who also has
9477 access to this document.
9479 ----------------------------------------------------------------------
9481 10.3.8 Denial of Service Attacks
9483 This section covers Denial of Service attacks. A DoS attack is typically a
9484 packet attack. While there is not much you can do about modern spoofed
9485 packet attacks that saturate your network, you can generally limit the
9486 damage by ensuring that the attacks cannot take down your servers.
9488 1. Limiting server forks.
9490 2. Limiting springboard attacks (ICMP response attacks, ping broadcast,
9493 3. Kernel Route Cache.
9495 A common DoS attack is against a forking server that attempts to cause the
9496 server to eat processes, file descriptors, and memory, until the machine
9497 dies. inetd (see inetd(8)) has several options to limit this sort of
9498 attack. It should be noted that while it is possible to prevent a machine
9499 from going down, it is not generally possible to prevent a service from
9500 being disrupted by the attack. Read the inetd manual page carefully and
9501 pay specific attention to the -c, -C, and -R options. Note that spoofed-IP
9502 attacks will circumvent the -C option to inetd, so typically a combination
9503 of options must be used. Some standalone servers have self-fork-limitation
9506 Sendmail has its -OMaxDaemonChildren option, which tends to work much
9507 better than trying to use sendmail's load limiting options due to the load
9508 lag. You should specify a MaxDaemonChildren parameter, when you start
9509 sendmail, high enough to handle your expected load, but not so high that
9510 the computer cannot handle that number of sendmails without falling on its
9511 face. It is also prudent to run sendmail in queued mode
9512 (-ODeliveryMode=queued) and to run the daemon (sendmail -bd) separate from
9513 the queue-runs (sendmail -q15m). If you still want real-time delivery you
9514 can run the queue at a much lower interval, such as -q1m, but be sure to
9515 specify a reasonable MaxDaemonChildren option for that sendmail to prevent
9518 Syslogd can be attacked directly and it is strongly recommended that you
9519 use the -s option whenever possible, and the -a option otherwise.
9521 You should also be fairly careful with connect-back services such as
9522 tcpwrapper's reverse-identd, which can be attacked directly. You generally
9523 do not want to use the reverse-ident feature of tcpwrappers for this
9526 It is a very good idea to protect internal services from external access
9527 by firewalling them off at your border routers. The idea here is to
9528 prevent saturation attacks from outside your LAN, not so much to protect
9529 internal services from network-based root compromise. Always configure an
9530 exclusive firewall, i.e., ``firewall everything except ports A, B, C, D,
9531 and M-Z''. This way you can firewall off all of your low ports except for
9532 certain specific services such as named (if you are primary for a zone),
9533 ntalkd, sendmail, and other Internet-accessible services. If you try to
9534 configure the firewall the other way -- as an inclusive or permissive
9535 firewall, there is a good chance that you will forget to ``close'' a
9536 couple of services, or that you will add a new internal service and forget
9537 to update the firewall. You can still open up the high-numbered port range
9538 on the firewall, to allow permissive-like operation, without compromising
9539 your low ports. Also take note that DragonFly allows you to control the
9540 range of port numbers used for dynamic binding, via the various
9541 net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can
9542 also ease the complexity of your firewall's configuration. For example,
9543 you might use a normal first/last range of 4000 to 5000, and a hiport
9544 range of 49152 to 65535, then block off everything under 4000 in your
9545 firewall (except for certain specific Internet-accessible ports, of
9548 Another common DoS attack is called a springboard attack -- to attack a
9549 server in a manner that causes the server to generate responses which
9550 overloads the server, the local network, or some other machine. The most
9551 common attack of this nature is the ICMP ping broadcast attack. The
9552 attacker spoofs ping packets sent to your LAN's broadcast address with the
9553 source IP address set to the actual machine they wish to attack. If your
9554 border routers are not configured to stomp on ping's to broadcast
9555 addresses, your LAN winds up generating sufficient responses to the
9556 spoofed source address to saturate the victim, especially when the
9557 attacker uses the same trick on several dozen broadcast addresses over
9558 several dozen different networks at once. Broadcast attacks of over a
9559 hundred and twenty megabits have been measured. A second common
9560 springboard attack is against the ICMP error reporting system. By
9561 constructing packets that generate ICMP error responses, an attacker can
9562 saturate a server's incoming network and cause the server to saturate its
9563 outgoing network with ICMP responses. This type of attack can also crash
9564 the server by running it out of mbuf's, especially if the server cannot
9565 drain the ICMP responses it generates fast enough. The DragonFly kernel
9566 has a new kernel compile option called ICMP_BANDLIM which limits the
9567 effectiveness of these sorts of attacks. The last major class of
9568 springboard attacks is related to certain internal inetd services such as
9569 the udp echo service. An attacker simply spoofs a UDP packet with the
9570 source address being server A's echo port, and the destination address
9571 being server B's echo port, where server A and B are both on your LAN. The
9572 two servers then bounce this one packet back and forth between each other.
9573 The attacker can overload both servers and their LANs simply by injecting
9574 a few packets in this manner. Similar problems exist with the internal
9575 chargen port. A competent sysadmin will turn off all of these
9576 inetd-internal test services.
9578 Spoofed packet attacks may also be used to overload the kernel route
9579 cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache
9580 sysctl parameters. A spoofed packet attack that uses a random source IP
9581 will cause the kernel to generate a temporary cached route in the route
9582 table, viewable with netstat -rna | fgrep W3. These routes typically
9583 timeout in 1600 seconds or so. If the kernel detects that the cached route
9584 table has gotten too big it will dynamically reduce the rtexpire but will
9585 never decrease it to less than rtminexpire. There are two problems:
9587 1. The kernel does not react quickly enough when a lightly loaded server
9588 is suddenly attacked.
9590 2. The rtminexpire is not low enough for the kernel to survive a
9593 If your servers are connected to the Internet via a T3 or better, it may
9594 be prudent to manually override both rtexpire and rtminexpire via
9595 sysctl(8). Never set either parameter to zero (unless you want to crash
9596 the machine). Setting both parameters to two seconds should be sufficient
9597 to protect the route table from attack.
9599 ----------------------------------------------------------------------
9601 10.3.9 Access Issues with Kerberos and SSH
9603 There are a few issues with both Kerberos and ssh that need to be
9604 addressed if you intend to use them. Kerberos V is an excellent
9605 authentication protocol, but there are bugs in the kerberized telnet and
9606 rlogin applications that make them unsuitable for dealing with binary
9607 streams. Also, by default Kerberos does not encrypt a session unless you
9608 use the -x option. ssh encrypts everything by default.
9610 ssh works quite well in every respect except that it forwards encryption
9611 keys by default. What this means is that if you have a secure workstation
9612 holding keys that give you access to the rest of the system, and you ssh
9613 to an insecure machine, your keys are usable. The actual keys themselves
9614 are not exposed, but ssh installs a forwarding port for the duration of
9615 your login, and if an attacker has broken root on the insecure machine he
9616 can utilize that port to use your keys to gain access to any other machine
9617 that your keys unlock.
9619 We recommend that you use ssh in combination with Kerberos whenever
9620 possible for staff logins. ssh can be compiled with Kerberos support. This
9621 reduces your reliance on potentially exposable ssh keys while at the same
9622 time protecting passwords via Kerberos. ssh keys should only be used for
9623 automated tasks from secure machines (something that Kerberos is unsuited
9624 to do). We also recommend that you either turn off key-forwarding in the
9625 ssh configuration, or that you make use of the from=IP/DOMAIN option that
9626 ssh allows in its authorized_keys file to make the key only usable to
9627 entities logging in from specific machines.
9629 ----------------------------------------------------------------------
9631 10.4 DES, MD5, and Crypt
9633 Parts rewritten and updated by Bill Swingle.
9635 Every user on a UNIX system has a password associated with their account.
9636 It seems obvious that these passwords need to be known only to the user
9637 and the actual operating system. In order to keep these passwords secret,
9638 they are encrypted with what is known as a ``one-way hash'', that is, they
9639 can only be easily encrypted but not decrypted. In other words, what we
9640 told you a moment ago was obvious is not even true: the operating system
9641 itself does not really know the password. It only knows the encrypted form
9642 of the password. The only way to get the ``plain-text'' password is by a
9643 brute force search of the space of possible passwords.
9645 Unfortunately the only secure way to encrypt passwords when UNIX came into
9646 being was based on DES, the Data Encryption Standard. This was not such a
9647 problem for users resident in the US, but since the source code for DES
9648 could not be exported outside the US, DragonFly had to find a way to both
9649 comply with US law and retain compatibility with all the other UNIX
9650 variants that still used DES.
9652 The solution was to divide up the encryption libraries so that US users
9653 could install the DES libraries and use DES but international users still
9654 had an encryption method that could be exported abroad. This is how
9655 DragonFly came to use MD5 as its default encryption method. MD5 is
9656 believed to be more secure than DES, so installing DES is offered
9657 primarily for compatibility reasons.
9659 ----------------------------------------------------------------------
9661 10.4.1 Recognizing Your Crypt Mechanism
9663 libcrypt.a provides a configurable password authentication hash library.
9664 Currently the library supports DES, MD5 and Blowfish hash functions. By
9665 default DragonFly uses MD5 to encrypt passwords.
9667 It is pretty easy to identify which encryption method DragonFly is set up
9668 to use. Examining the encrypted passwords in the /etc/master.passwd file
9669 is one way. Passwords encrypted with the MD5 hash are longer than those
9670 encrypted with the DES hash and also begin with the characters $1$.
9671 Passwords starting with $2a$ are encrypted with the Blowfish hash
9672 function. DES password strings do not have any particular identifying
9673 characteristics, but they are shorter than MD5 passwords, and are coded in
9674 a 64-character alphabet which does not include the $ character, so a
9675 relatively short string which does not begin with a dollar sign is very
9676 likely a DES password.
9678 The password format used for new passwords is controlled by the
9679 passwd_format login capability in /etc/login.conf, which takes values of
9680 des, md5 or blf. See the login.conf(5) manual page for more information
9681 about login capabilities.
9683 ----------------------------------------------------------------------
9685 10.5 One-time Passwords
9687 S/Key is a one-time password scheme based on a one-way hash function.
9688 DragonFly uses the MD4 hash for compatibility but other systems have used
9689 MD5 and DES-MAC. S/Key ia part of the FreeBSD base system, and is also
9690 used on a growing number of other operating systems. S/Key is a registered
9691 trademark of Bell Communications Research, Inc.
9693 There are three different sorts of passwords which we will discuss below.
9694 The first is your usual UNIX style or Kerberos password; we will call this
9695 a ``UNIX password''. The second sort is the one-time password which is
9696 generated by the S/Key key program or the OPIE opiekey(1) program and
9697 accepted by the keyinit or opiepasswd(1) programs and the login prompt; we
9698 will call this a ``one-time password''. The final sort of password is the
9699 secret password which you give to the key/opiekey programs (and sometimes
9700 the keyinit/opiepasswd programs) which it uses to generate one-time
9701 passwords; we will call it a ``secret password'' or just unqualified
9704 The secret password does not have anything to do with your UNIX password;
9705 they can be the same but this is not recommended. S/Key and OPIE secret
9706 passwords are not limited to eight characters like old UNIX passwords[10],
9707 they can be as long as you like. Passwords of six or seven word long
9708 phrases are fairly common. For the most part, the S/Key or OPIE system
9709 operates completely independently of the UNIX password system.
9711 Besides the password, there are two other pieces of data that are
9712 important to S/Key and OPIE. One is what is known as the ``seed'' or
9713 ``key'', consisting of two letters and five digits. The other is what is
9714 called the ``iteration count'', a number between 1 and 100. S/Key creates
9715 the one-time password by concatenating the seed and the secret password,
9716 then applying the MD4/MD5 hash as many times as specified by the iteration
9717 count and turning the result into six short English words. These six
9718 English words are your one-time password. The authentication system
9719 (primarily PAM) keeps track of the last one-time password used, and the
9720 user is authenticated if the hash of the user-provided password is equal
9721 to the previous password. Because a one-way hash is used it is impossible
9722 to generate future one-time passwords if a successfully used password is
9723 captured; the iteration count is decremented after each successful login
9724 to keep the user and the login program in sync. When the iteration count
9725 gets down to 1, S/Key and OPIE must be reinitialized.
9727 There are three programs involved in each system which we will discuss
9728 below. The key and opiekey programs accept an iteration count, a seed, and
9729 a secret password, and generate a one-time password or a consecutive list
9730 of one-time passwords. The keyinit and opiepasswd programs are used to
9731 initialize S/Key and OPIE respectively, and to change passwords, iteration
9732 counts, or seeds; they take either a secret passphrase, or an iteration
9733 count, seed, and one-time password. The keyinfo and opieinfo programs
9734 examine the relevant credentials files (/etc/skeykeys or /etc/opiekeys)
9735 and print out the invoking user's current iteration count and seed.
9737 There are four different sorts of operations we will cover. The first is
9738 using keyinit or opiepasswd over a secure connection to set up
9739 one-time-passwords for the first time, or to change your password or seed.
9740 The second operation is using keyinit or opiepasswd over an insecure
9741 connection, in conjunction with key or opiekey over a secure connection,
9742 to do the same. The third is using key/opiekey to log in over an insecure
9743 connection. The fourth is using key or opiekey to generate a number of
9744 keys which can be written down or printed out to carry with you when going
9745 to some location without secure connections to anywhere.
9747 ----------------------------------------------------------------------
9749 10.5.1 Secure Connection Initialization
9751 To initialize S/Key for the first time, change your password, or change
9752 your seed while logged in over a secure connection (e.g., on the console
9753 of a machine or via ssh), use the keyinit command without any parameters
9754 while logged in as yourself:
9758 Reminder - Only use this method if you are directly connected.
9759 If you are using telnet or rlogin exit with no password and use keyinit -s.
9760 Enter secret password:
9761 Again secret password:
9763 ID unfurl s/key is 99 to17757
9764 DEFY CLUB PRO NASH LACE SOFT
9766 For OPIE, opiepasswd is used instead:
9769 [grimreaper] ~ $ opiepasswd -f -c
9771 Only use this method from the console; NEVER from remote. If you are using
9772 telnet, xterm, or a dial-in, type ^C now or exit with no password.
9773 Then run opiepasswd without the -c parameter.
9774 Using MD5 to compute responses.
9775 Enter new secret pass phrase:
9776 Again new secret pass phrase:
9777 ID unfurl OTP key is 499 to4268
9778 MOS MALL GOAT ARM AVID COED
9780 At the Enter new secret pass phrase: or Enter secret password: prompts,
9781 you should enter a password or phrase. Remember, this is not the password
9782 that you will use to login with, this is used to generate your one-time
9783 login keys. The ``ID'' line gives the parameters of your particular
9784 instance: your login name, the iteration count, and seed. When logging in
9785 the system will remember these parameters and present them back to you so
9786 you do not have to remember them. The last line gives the particular
9787 one-time password which corresponds to those parameters and your secret
9788 password; if you were to re-login immediately, this one-time password is
9789 the one you would use.
9791 ----------------------------------------------------------------------
9793 10.5.2 Insecure Connection Initialization
9795 To initialize or change your secret password over an insecure connection,
9796 you will need to already have a secure connection to some place where you
9797 can run key or opiekey; this might be in the form of a desk accessory on a
9798 Macintosh, or a shell prompt on a machine you trust. You will also need to
9799 make up an iteration count (100 is probably a good value), and you may
9800 make up your own seed or use a randomly-generated one. Over on the
9801 insecure connection (to the machine you are initializing), use the keyinit
9807 Reminder you need the 6 English words from the key command.
9808 Enter sequence count from 1 to 9999: 100
9809 Enter new key [default to17759]:
9811 s/key access password:
9812 s/key access password:CURE MIKE BANE HIM RACY GORE
9814 For OPIE, you need to use opiepasswd:
9819 You need the response from an OTP generator.
9820 Old secret pass phrase:
9821 otp-md5 498 to4268 ext
9822 Response: GAME GAG WELT OUT DOWN CHAT
9823 New secret pass phrase:
9825 Response: LINE PAP MILK NELL BUOY TROY
9827 ID mark OTP key is 499 gr4269
9828 LINE PAP MILK NELL BUOY TROY
9830 To accept the default seed (which the keyinit program confusingly calls a
9831 key), press Return. Then before entering an access password, move over to
9832 your secure connection or S/Key desk accessory, and give it the same
9836 Reminder - Do not use this program while logged in via telnet or rlogin.
9837 Enter secret password: <secret password>
9838 CURE MIKE BANE HIM RACY GORE
9842 % opiekey 498 to4268
9843 Using the MD5 algorithm to compute response.
9844 Reminder: Don't use opiekey from telnet or dial-in sessions.
9845 Enter secret pass phrase:
9846 GAME GAG WELT OUT DOWN CHAT
9848 Now switch back over to the insecure connection, and copy the one-time
9849 password generated over to the relevant program.
9851 ----------------------------------------------------------------------
9853 10.5.3 Generating a Single One-time Password
9855 Once you have initialized S/Key, when you login you will be presented with
9858 % telnet example.com
9860 Connected to example.com
9861 Escape character is '^]'.
9863 DragonFly/i386 (example.com) (ttypa)
9871 % telnet example.com
9873 Connected to example.com
9874 Escape character is '^]'.
9876 DragonFly/i386 (example.com) (ttypa)
9879 otp-md5 498 gr4269 ext
9882 As a side note, the S/Key and OPIE prompts have a useful feature (not
9883 shown here): if you press Return at the password prompt, the prompter will
9884 turn echo on, so you can see what you are typing. This can be extremely
9885 useful if you are attempting to type in a password by hand, such as from a
9888 At this point you need to generate your one-time password to answer this
9889 login prompt. This must be done on a trusted system that you can run key
9890 or opiekey on. (There are versions of these for DOS, Windows and Mac OS as
9891 well.) They need both the iteration count and the seed as command line
9892 options. You can cut-and-paste these right from the login prompt on the
9893 machine that you are logging in to.
9895 On the trusted system:
9898 Reminder - Do not use this program while logged in via telnet or rlogin.
9899 Enter secret password:
9900 WELD LIP ACTS ENDS ME HAAG
9904 % opiekey 498 to4268
9905 Using the MD5 algorithm to compute response.
9906 Reminder: Don't use opiekey from telnet or dial-in sessions.
9907 Enter secret pass phrase:
9908 GAME GAG WELT OUT DOWN CHAT
9910 Now that you have your one-time password you can continue logging in:
9914 Password: <return to enable echo>
9916 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
9917 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ...
9919 ----------------------------------------------------------------------
9921 10.5.4 Generating Multiple One-time Passwords
9923 Sometimes you have to go places where you do not have access to a trusted
9924 machine or secure connection. In this case, it is possible to use the key
9925 and opiekey commands to generate a number of one-time passwords beforehand
9926 to be printed out and taken with you. For example:
9928 % key -n 5 30 zz99999
9929 Reminder - Do not use this program while logged in via telnet or rlogin.
9930 Enter secret password: <secret password>
9931 26: SODA RUDE LEA LIND BUDD SILT
9932 27: JILT SPY DUTY GLOW COWL ROT
9933 28: THEM OW COLA RUNT BONG SCOT
9934 29: COT MASH BARR BRIM NAN FLAG
9935 30: CAN KNEE CAST NAME FOLK BILK
9939 % opiekey -n 5 30 zz99999
9940 Using the MD5 algorithm to compute response.
9941 Reminder: Don't use opiekey from telnet or dial-in sessions.
9942 Enter secret pass phrase: <secret password>
9943 26: JOAN BORE FOSS DES NAY QUIT
9944 27: LATE BIAS SLAY FOLK MUCH TRIG
9945 28: SALT TIN ANTI LOON NEAL USE
9946 29: RIO ODIN GO BYE FURY TIC
9947 30: GREW JIVE SAN GIRD BOIL PHI
9949 The -n 5 requests five keys in sequence, the 30 specifies what the last
9950 iteration number should be. Note that these are printed out in reverse
9951 order of eventual use. If you are really paranoid, you might want to write
9952 the results down by hand; otherwise you can cut-and-paste into lpr. Note
9953 that each line shows both the iteration count and the one-time password;
9954 you may still find it handy to scratch off passwords as you use them.
9956 ----------------------------------------------------------------------
9958 10.5.5 Restricting Use of UNIX(R) Passwords
9960 S/Key can place restrictions on the use of UNIX passwords based on the
9961 host name, user name, terminal port, or IP address of a login session.
9962 These restrictions can be found in the configuration file
9963 /etc/skey.access. The skey.access(5) manual page has more information on
9964 the complete format of the file and also details some security cautions to
9965 be aware of before depending on this file for security.
9967 If there is no /etc/skey.access file (this is the default), then all users
9968 will be allowed to use UNIX passwords. If the file exists, however, then
9969 all users will be required to use S/Key unless explicitly permitted to do
9970 otherwise by configuration statements in the skey.access file. In all
9971 cases, UNIX passwords are permitted on the console.
9973 Here is a sample skey.access configuration file which illustrates the
9974 three most common sorts of configuration statements:
9976 permit internet 192.168.0.0 255.255.0.0
9980 The first line (permit internet) allows users whose IP source address
9981 (which is vulnerable to spoofing) matches the specified value and mask, to
9982 use UNIX passwords. This should not be considered a security mechanism,
9983 but rather, a means to remind authorized users that they are using an
9984 insecure network and need to use S/Key for authentication.
9986 The second line (permit user) allows the specified username, in this case
9987 fnord, to use UNIX passwords at any time. Generally speaking, this should
9988 only be used for people who are either unable to use the key program, like
9989 those with dumb terminals, or those who are uneducable.
9991 The third line (permit port) allows all users logging in on the specified
9992 terminal line to use UNIX passwords; this would be used for dial-ups.
9994 Here is a sample opieaccess file:
9996 permit 192.168.0.0 255.255.0.0
9998 This line allows users whose IP source address (which is vulnerable to
9999 spoofing) matches the specified value and mask, to use UNIX passwords at
10002 If no rules in opieaccess are matched, the default is to deny non-OPIE
10005 ----------------------------------------------------------------------
10009 Contributed by Tillman Hodgson. Based on a contribution by Mark Murray.
10011 The following information only applies to Kerberos5. Users who wish to use
10012 the KerberosIV package may install the security/krb4 port.
10014 Kerberos is a network add-on system/protocol that allows users to
10015 authenticate themselves through the services of a secure server. Services
10016 such as remote login, remote copy, secure inter-system file copying and
10017 other high-risk tasks are made considerably safer and more controllable.
10019 Kerberos can be described as an identity-verifying proxy system. It can
10020 also be described as a trusted third-party authentication system. Kerberos
10021 provides only one function -- the secure authentication of users on the
10022 network. It does not provide authorization functions (what users are
10023 allowed to do) or auditing functions (what those users did). After a
10024 client and server have used Kerberos to prove their identity, they can
10025 also encrypt all of their communications to assure privacy and data
10026 integrity as they go about their business.
10028 Therefore it is highly recommended that Kerberos be used with other
10029 security methods which provide authorization and audit services.
10031 The following instructions can be used as a guide on how to set up
10032 Kerberos as distributed for DragonFly. However, you should refer to the
10033 relevant manual pages for a complete description.
10035 For purposes of demonstrating a Kerberos installation, the various
10036 namespaces will be handled as follows:
10038 * The DNS domain (``zone'') will be example.org.
10040 * The Kerberos realm will be EXAMPLE.ORG.
10042 Note: Please use real domain names when setting up Kerberos even if you
10043 intend to run it internally. This avoids DNS problems and assures
10044 inter-operation with other Kerberos realms.
10046 ----------------------------------------------------------------------
10050 Kerberos was created by MIT as a solution to network security problems.
10051 The Kerberos protocol uses strong cryptography so that a client can prove
10052 its identity to a server (and vice versa) across an insecure network
10055 Kerberos is both the name of a network authentication protocol and an
10056 adjective to describe programs that implement the program (Kerberos
10057 telnet, for example). The current version of the protocol is version 5,
10058 described in RFC 1510.
10060 Several free implementations of this protocol are available, covering a
10061 wide range of operating systems. The Massachusetts Institute of Technology
10062 (MIT), where Kerberos was originally developed, continues to develop their
10063 Kerberos package. It is commonly used in the US as a cryptography product,
10064 as such it has historically been affected by US export regulations. The
10065 MIT Kerberos is available as a port (security/krb5). Heimdal Kerberos is
10066 another version 5 implementation, and was explicitly developed outside of
10067 the US to avoid export regulations (and is thus often included in
10068 non-commercial UNIX variants). The Heimdal Kerberos distribution is
10069 available as a port (security/heimdal), and a minimal installation of it
10070 is included in the base DragonFly install.
10072 In order to reach the widest audience, these instructions assume the use
10073 of the Heimdal distribution included in DragonFly.
10075 ----------------------------------------------------------------------
10077 10.6.2 Setting up a Heimdal KDC
10079 The Key Distribution Center (KDC) is the centralized authentication
10080 service that Kerberos provides -- it is the computer that issues Kerberos
10081 tickets. The KDC is considered ``trusted'' by all other computers in the
10082 Kerberos realm, and thus has heightened security concerns.
10084 Note that while running the Kerberos server requires very few computing
10085 resources, a dedicated machine acting only as a KDC is recommended for
10088 To begin setting up a KDC, ensure that your /etc/rc.conf file contains the
10089 correct settings to act as a KDC (you may need to adjust paths to reflect
10092 kerberos5_server_enable="YES"
10093 kadmind5_server_enable="YES"
10094 kerberos_stash="YES"
10096 Next we will set up your Kerberos config file, /etc/krb5.conf:
10099 default_realm = EXAMPLE.ORG
10102 kdc = kerberos.example.org
10105 .example.org = EXAMPLE.ORG
10107 Note that this /etc/krb5.conf file implies that your KDC will have the
10108 fully-qualified hostname of kerberos.example.org. You will need to add a
10109 CNAME (alias) entry to your zone file to accomplish this if your KDC has a
10110 different hostname.
10112 Note: For large networks with a properly configured BIND DNS server, the
10113 above example could be trimmed to:
10116 default_realm = EXAMPLE.ORG
10118 With the following lines being appended to the example.org zonefile:
10120 _kerberos._udp IN SRV 01 00 88 kerberos.example.org.
10121 _kerberos._tcp IN SRV 01 00 88 kerberos.example.org.
10122 _kpasswd._udp IN SRV 01 00 464 kerberos.example.org.
10123 _kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org.
10124 _kerberos IN TXT EXAMPLE.ORG.
10126 Next we will create the Kerberos database. This database contains the keys
10127 of all principals encrypted with a master password. You are not required
10128 to remember this password, it will be stored in a file
10129 (/var/heimdal/m-key). To create the master key, run kstash and enter a
10132 Once the master key has been created, you can initialize the database
10133 using the kadmin program with the -l option (standing for ``local''). This
10134 option instructs kadmin to modify the database files directly rather than
10135 going through the kadmind network service. This handles the
10136 chicken-and-egg problem of trying to connect to the database before it is
10137 created. Once you have the kadmin prompt, use the init command to create
10138 your realms initial database.
10140 Lastly, while still in kadmin, create your first principal using the add
10141 command. Stick to the defaults options for the principal for now, you can
10142 always change them later with the modify command. Note that you can use
10143 the ? command at any prompt to see the available options.
10145 A sample database creation session is shown below:
10148 Master key: xxxxxxxx
10149 Verifying password - Master key: xxxxxxxx
10152 kadmin> init EXAMPLE.ORG
10153 Realm max ticket life [unlimited]:
10154 kadmin> add tillman
10155 Max ticket life [unlimited]:
10156 Max renewable life [unlimited]:
10159 Verifying password - Password: xxxxxxxx
10161 Now it is time to start up the KDC services. Run /etc/rc.d/kerberos start
10162 and /etc/rc.d/kadmind start to bring up the services. Note that you won't
10163 have any kerberized daemons running at this point but you should be able
10164 to confirm the that the KDC is functioning by obtaining and listing a
10165 ticket for the principal (user) that you just created from the
10166 command-line of the KDC itself:
10169 tillman@EXAMPLE.ORG's Password:
10172 Credentials cache: FILE:/tmp/krb5cc_500
10173 Principal: tillman@EXAMPLE.ORG
10175 Issued Expires Principal
10176 Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
10178 ----------------------------------------------------------------------
10180 10.6.3 Kerberos enabling a server with Heimdal services
10182 First, we need a copy of the Kerberos configuration file, /etc/krb5.conf.
10183 To do so, simply copy it over to the client computer from the KDC in a
10184 secure fashion (using network utilities, such as scp(1), or physically via
10187 Next you need a /etc/krb5.keytab file. This is the major difference
10188 between a server providing Kerberos enabled daemons and a workstation --
10189 the server must have a keytab file. This file contains the servers host
10190 key, which allows it and the KDC to verify each others identity. It must
10191 be transmitted to the server in a secure fashion, as the security of the
10192 server can be broken if the key is made public. This explicitly means that
10193 transferring it via a clear text channel, such as FTP, is a very bad idea.
10195 Typically, you transfer to the keytab to the server using the kadmin
10196 program. This is handy because you also need to create the host principal
10197 (the KDC end of the krb5.keytab) using kadmin.
10199 Note that you must have already obtained a ticket and that this ticket
10200 must be allowed to use the kadmin interface in the kadmind.acl. See the
10201 section titled ``Remote administration'' in the Heimdal info pages (info
10202 heimdal) for details on designing access control lists. If you do not want
10203 to enable remote kadmin access, you can simply securely connect to the KDC
10204 (via local console, ssh(1) or Kerberos telnet(1)) and perform
10205 administration locally using kadmin -l.
10207 After installing the /etc/krb5.conf file, you can use kadmin from the
10208 Kerberos server. The add --random-key command will let you add the servers
10209 host principal, and the ext command will allow you to extract the servers
10210 host principal to its own keytab. For example:
10213 kadmin> add --random-key host/myserver.example.org
10214 Max ticket life [unlimited]:
10215 Max renewable life [unlimited]:
10217 kadmin> ext host/myserver.example.org
10220 Note that the ext command (short for ``extract'') stores the extracted key
10221 in /etc/krb5.keytab by default.
10223 If you do not have kadmind running on the KDC (possibly for security
10224 reasons) and thus do not have access to kadmin remotely, you can add the
10225 host principal (host/myserver.EXAMPLE.ORG) directly on the KDC and then
10226 extract it to a temporary file (to avoid over-writing the /etc/krb5.keytab
10227 on the KDC) using something like this:
10230 kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org
10233 You can then securely copy the keytab to the server computer (using scp or
10234 a floppy, for example). Be sure to specify a non-default keytab name to
10235 avoid over-writing the keytab on the KDC.
10237 At this point your server can communicate with the KDC (due to its
10238 krb5.conf file) and it can prove its own identity (due to the krb5.keytab
10239 file). It is now ready for you to enable some Kerberos services. For this
10240 example we will enable the telnet service by putting a line like this into
10241 your /etc/inetd.conf and then restarting the inetd(8) service with
10242 /etc/rc.d/inetd restart:
10244 telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user
10246 The critical bit is that the -a (for authentication) type is set to user.
10247 Consult the telnetd(8) manual page for more details.
10249 ----------------------------------------------------------------------
10251 10.6.4 Kerberos enabling a client with Heimdal
10253 Setting up a client computer is almost trivially easy. As far as Kerberos
10254 configuration goes, you only need the Kerberos configuration file, located
10255 at /etc/krb5.conf. Simply securely copy it over to the client computer
10258 Test your client computer by attempting to use kinit, klist, and kdestroy
10259 from the client to obtain, show, and then delete a ticket for the
10260 principal you created above. You should also be able to use Kerberos
10261 applications to connect to Kerberos enabled servers, though if that does
10262 not work and obtaining a ticket does the problem is likely with the server
10263 and not with the client or the KDC.
10265 When testing an application like telnet, try using a packet sniffer (such
10266 as tcpdump(1)) to confirm that your password is not sent in the clear. Try
10267 using telnet with the -x option, which encrypts the entire data stream
10270 The core Kerberos client applications (traditionally named kinit, klist,
10271 kdestroy, and kpasswd) are installed in the base DragonFly install. Note
10272 that DragonFly versions prior to 5.0 renamed them to k5init, k5list,
10273 k5destroy, k5passwd, and k5stash (though it is typically only used once).
10275 Various non-core Kerberos client applications are also installed by
10276 default. This is where the ``minimal'' nature of the base Heimdal
10277 installation is felt: telnet is the only Kerberos enabled service.
10279 The Heimdal port adds some of the missing client applications: Kerberos
10280 enabled versions of ftp, rsh, rcp, rlogin, and a few other less common
10281 programs. The MIT port also contains a full suite of Kerberos client
10284 ----------------------------------------------------------------------
10286 10.6.5 User configuration files: .k5login and .k5users
10288 Users within a realm typically have their Kerberos principal (such as
10289 tillman@EXAMPLE.ORG) mapped to a local user account (such as a local
10290 account named tillman). Client applications such as telnet usually do not
10291 require a user name or a principal.
10293 Occasionally, however, you want to grant access to a local user account to
10294 someone who does not have a matching Kerberos principal. For example,
10295 tillman@EXAMPLE.ORG may need access to the local user account
10296 webdevelopers. Other principals may also need access to that local
10299 The .k5login and .k5users files, placed in a users home directory, can be
10300 used similar to a powerful combination of .hosts and .rhosts, solving this
10301 problem. For example, if a .k5login with the following contents:
10303 tillman@example.org
10306 Were to be placed into the home directory of the local user webdevelopers
10307 then both principals listed would have access to that account without
10308 requiring a shared password.
10310 Reading the manual pages for these commands is recommended. Note that the
10311 ksu manual page covers .k5users.
10313 ----------------------------------------------------------------------
10315 10.6.6 Kerberos Tips, Tricks, and Troubleshooting
10317 * When using either the Heimdal or MIT Kerberos ports ensure that your
10318 PATH environment variable lists the Kerberos versions of the client
10319 applications before the system versions.
10321 * Is your time in sync? Are you sure? If the time is not in sync
10322 (typically within five minutes) authentication will fail.
10324 * MIT and Heimdal inter-operate nicely. Except for kadmin, the protocol
10325 for which is not standardized.
10327 * If you change your hostname, you also need to change your host/
10328 principal and update your keytab. This also applies to special keytab
10329 entries like the www/ principal used for Apache's www/mod_auth_kerb.
10331 * All hosts in your realm must be resolvable (both forwards and reverse)
10332 in DNS (or /etc/hosts as a minimum). CNAMEs will work, but the A and
10333 PTR records must be correct and in place. The error message isn't very
10334 intuitive: ``Kerberos5 refuses authentication because Read req failed:
10335 Key table entry not found''.
10337 * Some operating systems that may being acting as clients to your KDC do
10338 not set the permissions for ksu to be setuid root. This means that ksu
10339 does not work, which is a good security idea but annoying. This is not
10342 * With MIT Kerberos, if you want to allow a principal to have a ticket
10343 life longer than the default ten hours, you must use modify_principal
10344 in kadmin to change the maxlife of both the principal in question and
10345 the krbtgt principal. Then the principal can use the -l option with
10346 kinit to request a ticket with a longer lifetime.
10348 * Note: If you run a packet sniffer on your KDC to add in
10349 troubleshooting and then run kinit from a workstation, you will
10350 notice that your TGT is sent immediately upon running kinit -- even
10351 before you type your password! The explanation is that the Kerberos
10352 server freely transmits a TGT (Ticket Granting Ticket) to any
10353 unauthorized request; however, every TGT is encrypted in a key
10354 derived from the user's password. Therefore, when a user types their
10355 password it is not being sent to the KDC, it is being used to
10356 decrypt the TGT that kinit already obtained. If the decryption
10357 process results in a valid ticket with a valid time stamp, the user
10358 has valid Kerberos credentials. These credentials include a session
10359 key for establishing secure communications with the Kerberos server
10360 in the future, as well as the actual ticket-granting ticket, which
10361 is actually encrypted with the Kerberos server's own key. This
10362 second layer of encryption is unknown to the user, but it is what
10363 allows the Kerberos server to verify the authenticity of each TGT.
10365 * You have to keep the time in sync between all the computers in your
10366 realm. NTP is perfect for this. For more information on NTP, see
10369 * If you want to use long ticket lifetimes (a week, for example) and you
10370 are using OpenSSH to connect to the machine where your ticket is
10371 stored, make sure that Kerberos TicketCleanup is set to no in your
10372 sshd_config or else your tickets will be deleted when you log out.
10374 * Remember that host principals can have a longer ticket lifetime as
10375 well. If your user principal has a lifetime of a week but the host you
10376 are connecting to has a lifetime of nine hours, you will have an
10377 expired host principal in your cache and the ticket cache will not
10380 * When setting up a krb5.dict file to prevent specific bad passwords
10381 from being used (the manual page for kadmind covers this briefly),
10382 remember that it only applies to principals that have a password
10383 policy assigned to them. The krb5.dict files format is simple: one
10384 string per line. Creating a symbolic link to /usr/share/dict/words
10387 ----------------------------------------------------------------------
10389 10.6.7 Differences with the MIT port
10391 The major difference between the MIT and Heimdal installs relates to the
10392 kadmin program which has a different (but equivalent) set of commands and
10393 uses a different protocol. This has a large implications if your KDC is
10394 MIT as you will not be able to use the Heimdal kadmin program to
10395 administer your KDC remotely (or vice versa, for that matter).
10397 The client applications may also take slightly different command line
10398 options to accomplish the same tasks. Following the instructions on the
10399 MIT Kerberos web site (http://web.mit.edu/Kerberos/www/) is recommended.
10400 Be careful of path issues: the MIT port installs into /usr/local/ by
10401 default, and the ``normal'' system applications may be run instead of MIT
10402 if your PATH environment variable lists the system directories first.
10404 Note: With the MIT security/krb5 port that is provided by DragonFly, be
10405 sure to read the /usr/local/share/doc/krb5/README.FreeBSD file installed
10406 by the port if you want to understand why logins via telnetd and klogind
10407 behave somewhat oddly. Most importantly, correcting the ``incorrect
10408 permissions on cache file'' behavior requires that the login.krb5 binary
10409 be used for authentication so that it can properly change ownership for
10410 the forwarded credentials.
10412 ----------------------------------------------------------------------
10414 10.6.8 Mitigating limitations found in Kerberos
10416 ----------------------------------------------------------------------
10418 10.6.8.1 Kerberos is an all-or-nothing approach
10420 Every service enabled on the network must be modified to work with
10421 Kerberos (or be otherwise secured against network attacks) or else the
10422 users credentials could be stolen and re-used. An example of this would be
10423 Kerberos enabling all remote shells (via rsh and telnet, for example) but
10424 not converting the POP3 mail server which sends passwords in plaintext.
10426 ----------------------------------------------------------------------
10428 10.6.8.2 Kerberos is intended for single-user workstations
10430 In a multi-user environment, Kerberos is less secure. This is because it
10431 stores the tickets in the /tmp directory, which is readable by all users.
10432 If a user is sharing a computer with several other people simultaneously
10433 (i.e. multi-user), it is possible that the user's tickets can be stolen
10434 (copied) by another user.
10436 This can be overcome with the -c filename command-line option or
10437 (preferably) the KRB5CCNAME environment variable, but this is rarely done.
10438 In principal, storing the ticket in the users home directory and using
10439 simple file permissions can mitigate this problem.
10441 ----------------------------------------------------------------------
10443 10.6.8.3 The KDC is a single point of failure
10445 By design, the KDC must be as secure as the master password database is
10446 contained on it. The KDC should have absolutely no other services running
10447 on it and should be physically secured. The danger is high because
10448 Kerberos stores all passwords encrypted with the same key (the ``master''
10449 key), which in turn is stored as a file on the KDC.
10451 As a side note, a compromised master key is not quite as bad as one might
10452 normally fear. The master key is only used to encrypt the Kerberos
10453 database and as a seed for the random number generator. As long as access
10454 to your KDC is secure, an attacker cannot do much with the master key.
10456 Additionally, if the KDC is unavailable (perhaps due to a denial of
10457 service attack or network problems) the network services are unusable as
10458 authentication can not be performed, a recipe for a denial-of-service
10459 attack. This can alleviated with multiple KDCs (a single master and one or
10460 more slaves) and with careful implementation of secondary or fall-back
10461 authentication (PAM is excellent for this).
10463 ----------------------------------------------------------------------
10465 10.6.8.4 Kerberos Shortcomings
10467 Kerberos allows users, hosts and services to authenticate between
10468 themselves. It does not have a mechanism to authenticate the KDC to the
10469 users, hosts or services. This means that a trojanned kinit (for example)
10470 could record all user names and passwords. Something like
10471 security/tripwire or other file system integrity checking tools can
10474 ----------------------------------------------------------------------
10476 10.6.9 Resources and further information
10480 * Designing an Authentication System: a Dialogue in Four Scenes
10482 * RFC 1510, The Kerberos Network Authentication Service (V5)
10484 * MIT Kerberos home page
10486 * Heimdal Kerberos home page
10488 ----------------------------------------------------------------------
10492 Contributed by Gary Palmer and Alex Nash.
10494 Firewalls are an area of increasing interest for people who are connected
10495 to the Internet, and are even finding applications on private networks to
10496 provide enhanced security. This section will hopefully explain what
10497 firewalls are, how to use them, and how to use the facilities provided in
10498 the DragonFly kernel to implement them.
10500 Note: People often think that having a firewall between your internal
10501 network and the ``Big Bad Internet'' will solve all your security
10502 problems. It may help, but a poorly set up firewall system is more of a
10503 security risk than not having one at all. A firewall can add another
10504 layer of security to your systems, but it cannot stop a really
10505 determined cracker from penetrating your internal network. If you let
10506 internal security lapse because you believe your firewall to be
10507 impenetrable, you have just made the crackers job that much easier.
10509 ----------------------------------------------------------------------
10511 10.7.1 What Is a Firewall?
10513 There are currently two distinct types of firewalls in common use on the
10514 Internet today. The first type is more properly called a packet filtering
10515 router. This type of firewall utilizes a multi-homed machine and a set of
10516 rules to determine whether to forward or block individual packets. A
10517 multi-homed machine is simply a device with multiple network interfaces.
10518 The second type, known as a proxy server, relies on daemons to provide
10519 authentication and to forward packets, possibly on a multi-homed machine
10520 which has kernel packet forwarding disabled.
10522 Sometimes sites combine the two types of firewalls, so that only a certain
10523 machine (known as a bastion host) is allowed to send packets through a
10524 packet filtering router onto an internal network. Proxy services are run
10525 on the bastion host, which are generally more secure than normal
10526 authentication mechanisms.
10528 DragonFly comes with a kernel packet filter (known as IPFW), which is what
10529 the rest of this section will concentrate on. Proxy servers can be built
10530 on DragonFly from third party software, but there is such a variety of
10531 proxy servers available that it would be impossible to cover them in this
10534 ----------------------------------------------------------------------
10536 10.7.1.1 Packet Filtering Routers
10538 A router is a machine which forwards packets between two or more networks.
10539 A packet filtering router is programmed to compare each packet to a list
10540 of rules before deciding if it should be forwarded or not. Most modern IP
10541 routing software includes packet filtering functionality that defaults to
10542 forwarding all packets. To enable the filters, you need to define a set of
10545 To decide whether a packet should be passed on, the firewall looks through
10546 its set of rules for a rule which matches the contents of the packet's
10547 headers. Once a match is found, the rule action is obeyed. The rule action
10548 could be to drop the packet, to forward the packet, or even to send an
10549 ICMP message back to the originator. Only the first match counts, as the
10550 rules are searched in order. Hence, the list of rules can be referred to
10551 as a ``rule chain''.
10553 The packet-matching criteria varies depending on the software used, but
10554 typically you can specify rules which depend on the source IP address of
10555 the packet, the destination IP address, the source port number, the
10556 destination port number (for protocols which support ports), or even the
10557 packet type (UDP, TCP, ICMP, etc).
10559 ----------------------------------------------------------------------
10561 10.7.1.2 Proxy Servers
10563 Proxy servers are machines which have had the normal system daemons
10564 (telnetd, ftpd, etc) replaced with special servers. These servers are
10565 called proxy servers, as they normally only allow onward connections to be
10566 made. This enables you to run (for example) a proxy telnet server on your
10567 firewall host, and people can telnet in to your firewall from the outside,
10568 go through some authentication mechanism, and then gain access to the
10569 internal network (alternatively, proxy servers can be used for signals
10570 coming from the internal network and heading out).
10572 Proxy servers are normally more secure than normal servers, and often have
10573 a wider variety of authentication mechanisms available, including
10574 ``one-shot'' password systems so that even if someone manages to discover
10575 what password you used, they will not be able to use it to gain access to
10576 your systems as the password expires immediately after the first use. As
10577 they do not actually give users access to the host machine, it becomes a
10578 lot more difficult for someone to install backdoors around your security
10581 Proxy servers often have ways of restricting access further, so that only
10582 certain hosts can gain access to the servers. Most will also allow the
10583 administrator to specify which users can talk to which destination
10584 machines. Again, what facilities are available depends largely on what
10585 proxy software you choose.
10587 ----------------------------------------------------------------------
10589 10.7.2 What Does IPFW Allow Me to Do?
10591 IPFW, the software supplied with DragonFly, is a packet filtering and
10592 accounting system which resides in the kernel, and has a user-land control
10593 utility, ipfw(8). Together, they allow you to define and query the rules
10594 used by the kernel in its routing decisions.
10596 There are two related parts to IPFW. The firewall section performs packet
10597 filtering. There is also an IP accounting section which tracks usage of
10598 the router, based on rules similar to those used in the firewall section.
10599 This allows the administrator to monitor how much traffic the router is
10600 getting from a certain machine, or how much WWW traffic it is forwarding,
10603 As a result of the way that IPFW is designed, you can use IPFW on
10604 non-router machines to perform packet filtering on incoming and outgoing
10605 connections. This is a special case of the more general use of IPFW, and
10606 the same commands and techniques should be used in this situation.
10608 ----------------------------------------------------------------------
10610 10.7.3 Enabling IPFW on DragonFly
10612 As the main part of the IPFW system lives in the kernel, you will need to
10613 add one or more options to your kernel configuration file, depending on
10614 what facilities you want, and recompile your kernel. See "Reconfiguring
10615 your Kernel" (Chapter 9) for more details on how to recompile your kernel.
10617 Warning: IPFW defaults to a policy of deny ip from any to any. If you do
10618 not add other rules during startup to allow access, you will lock
10619 yourself out of the server upon rebooting into a firewall-enabled
10620 kernel. We suggest that you set firewall_type=open in your /etc/rc.conf
10621 file when first enabling this feature, then refining the firewall rules
10622 in /etc/rc.firewall after you have tested that the new kernel feature
10623 works properly. To be on the safe side, you may wish to consider
10624 performing the initial firewall configuration from the local console
10625 rather than via ssh. Another option is to build a kernel using both the
10626 IPFIREWALL and IPFIREWALL_DEFAULT_TO_ACCEPT options. This will change
10627 the default rule of IPFW to allow ip from any to any and avoid the
10628 possibility of a lockout.
10630 There are currently four kernel configuration options relevant to IPFW:
10634 Compiles into the kernel the code for packet filtering.
10636 options IPFIREWALL_VERBOSE
10638 Enables code to allow logging of packets through syslogd(8).
10639 Without this option, even if you specify that packets should be
10640 logged in the filter rules, nothing will happen.
10642 options IPFIREWALL_VERBOSE_LIMIT=10
10644 Limits the number of packets logged through syslogd(8) on a per
10645 entry basis. You may wish to use this option in hostile
10646 environments in which you want to log firewall activity, but do
10647 not want to be open to a denial of service attack via syslog
10650 When a chain entry reaches the packet limit specified, logging is
10651 turned off for that particular entry. To resume logging, you will
10652 need to reset the associated counter using the ipfw(8) utility:
10656 Where 4500 is the chain entry you wish to continue logging.
10658 options IPFIREWALL_DEFAULT_TO_ACCEPT
10660 This changes the default rule action from ``deny'' to ``allow''.
10661 This avoids the possibility of locking yourself out if you happen
10662 to boot a kernel with IPFIREWALL support but have not configured
10663 your firewall yet. It is also very useful if you often use ipfw(8)
10664 as a filter for specific problems as they arise. Use with care
10665 though, as this opens up the firewall and changes the way it
10668 ----------------------------------------------------------------------
10670 10.7.4 Configuring IPFW
10672 The configuration of the IPFW software is done through the ipfw(8)
10673 utility. The syntax for this command looks quite complicated, but it is
10674 relatively simple once you understand its structure.
10676 There are currently four different command categories used by the utility:
10677 addition/deletion, listing, flushing, and clearing. Addition/deletion is
10678 used to build the rules that control how packets are accepted, rejected,
10679 and logged. Listing is used to examine the contents of your rule set
10680 (otherwise known as the chain) and packet counters (accounting). Flushing
10681 is used to remove all entries from the chain. Clearing is used to zero out
10682 one or more accounting entries.
10684 ----------------------------------------------------------------------
10686 10.7.4.1 Altering the IPFW Rules
10688 The syntax for this form of the command is:
10690 ipfw [-N] command [index] action [log] protocol addresses [options]
10692 There is one valid flag when using this form of the command:
10696 Resolve addresses and service names in output.
10698 The command given can be shortened to the shortest unique form. The valid
10703 Add an entry to the firewall/accounting rule list
10707 Delete an entry from the firewall/accounting rule list
10709 Previous versions of IPFW used separate firewall and accounting entries.
10710 The present version provides packet accounting with each firewall entry.
10712 If an index value is supplied, it is used to place the entry at a specific
10713 point in the chain. Otherwise, the entry is placed at the end of the chain
10714 at an index 100 greater than the last chain entry (this does not include
10715 the default policy, rule 65535, deny).
10717 The log option causes matching rules to be output to the system console if
10718 the kernel was compiled with IPFIREWALL_VERBOSE.
10724 Drop the packet, and send an ICMP host or port unreachable (as
10725 appropriate) packet to the source.
10729 Pass the packet on as normal. (aliases: pass, permit, and accept)
10733 Drop the packet. The source is not notified via an ICMP message
10734 (thus it appears that the packet never arrived at the
10739 Update packet counters but do not allow/deny the packet based on
10740 this rule. The search continues with the next chain entry.
10742 Each action will be recognized by the shortest unambiguous prefix.
10744 The protocols which can be specified are:
10748 Matches any IP packet
10752 Matches ICMP packets
10756 Matches TCP packets
10760 Matches UDP packets
10762 The address specification is:
10764 from address/mask [port] to address/mask [port] [via interface]
10766 You can only specify port in conjunction with protocols which support
10767 ports (UDP and TCP).
10769 The via is optional and may specify the IP address or domain name of a
10770 local IP interface, or an interface name (e.g. ed0) to match only packets
10771 coming through this interface. Interface unit numbers can be specified
10772 with an optional wildcard. For example, ppp* would match all kernel PPP
10775 The syntax used to specify an address/mask is:
10785 address:mask-pattern
10787 A valid hostname may be specified in place of the IP address. mask-bits is
10788 a decimal number representing how many bits in the address mask should be
10789 set. e.g. specifying 192.216.222.1/24 will create a mask which will allow
10790 any address in a class C subnet (in this case, 192.216.222) to be matched.
10791 mask-pattern is an IP address which will be logically AND'ed with the
10792 address given. The keyword any may be used to specify ``any IP address''.
10794 The port numbers to be blocked are specified as:
10796 port [,port [,port [...]]]
10798 to specify either a single port or a list of ports, or
10802 to specify a range of ports. You may also combine a single range with a
10803 list, but the range must always be specified first.
10805 The options available are:
10809 Matches if the packet is not the first fragment of the datagram.
10813 Matches if the packet is on the way in.
10817 Matches if the packet is on the way out.
10821 Matches if the IP header contains the comma separated list of
10822 options specified in spec. The supported IP options are: ssrr
10823 (strict source route), lsrr (loose source route), rr (record
10824 packet route), and ts (time stamp). The absence of a particular
10825 option may be specified with a leading !.
10829 Matches if the packet is part of an already established TCP
10830 connection (i.e. it has the RST or ACK bits set). You can optimize
10831 the performance of the firewall by placing established rules early
10836 Matches if the packet is an attempt to establish a TCP connection
10837 (the SYN bit is set but the ACK bit is not).
10841 Matches if the TCP header contains the comma separated list of
10842 flags. The supported flags are fin, syn, rst, psh, ack, and urg.
10843 The absence of a particular flag may be indicated by a leading !.
10847 Matches if the ICMP type is present in the list types. The list
10848 may be specified as any combination of ranges and/or individual
10849 types separated by commas. Commonly used ICMP types are: 0 echo
10850 reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo
10851 request (ping request), and 11 time exceeded (used to indicate TTL
10852 expiration as with traceroute(8)).
10854 ----------------------------------------------------------------------
10856 10.7.4.2 Listing the IPFW Rules
10858 The syntax for this form of the command is:
10860 ipfw [-a] [-c] [-d] [-e] [-t] [-N] [-S] list
10862 There are seven valid flags when using this form of the command:
10866 While listing, show counter values. This option is the only way to
10867 see accounting counters.
10871 List rules in compact form.
10875 Show dynamic rules in addition to static rules.
10879 If -d was specified, also show expired dynamic rules.
10883 Display the last match times for each chain entry. The time
10884 listing is incompatible with the input syntax used by the ipfw(8)
10889 Attempt to resolve given addresses and service names.
10893 Show the set each rule belongs to. If this flag is not specified,
10894 disabled rules will not be listed.
10896 ----------------------------------------------------------------------
10898 10.7.4.3 Flushing the IPFW Rules
10900 The syntax for flushing the chain is:
10904 This causes all entries in the firewall chain to be removed except the
10905 fixed default policy enforced by the kernel (index 65535). Use caution
10906 when flushing rules; the default deny policy will leave your system cut
10907 off from the network until allow entries are added to the chain.
10909 ----------------------------------------------------------------------
10911 10.7.4.4 Clearing the IPFW Packet Counters
10913 The syntax for clearing one or more packet counters is:
10917 When used without an index argument, all packet counters are cleared. If
10918 an index is supplied, the clearing operation only affects a specific chain
10921 ----------------------------------------------------------------------
10923 10.7.5 Example Commands for ipfw
10925 This command will deny all packets from the host evil.crackers.org to the
10926 telnet port of the host nice.people.org:
10928 # ipfw add deny tcp from evil.crackers.org to nice.people.org 23
10930 The next example denies and logs any TCP traffic from the entire
10931 crackers.org network (a class C) to the nice.people.org machine (any
10934 # ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org
10936 If you do not want people sending X sessions to your internal network (a
10937 subnet of a class C), the following command will do the necessary
10940 # ipfw add deny tcp from any to my.org/28 6000 setup
10942 To see the accounting records:
10946 or in the short form
10950 You can also see the last time a chain entry was matched with:
10954 ----------------------------------------------------------------------
10956 10.7.6 Building a Packet Filtering Firewall
10958 Note: The following suggestions are just that: suggestions. The
10959 requirements of each firewall are different and we cannot tell you how
10960 to build a firewall to meet your particular requirements.
10962 When initially setting up your firewall, unless you have a test bench
10963 setup where you can configure your firewall host in a controlled
10964 environment, it is strongly recommend you use the logging version of the
10965 commands and enable logging in the kernel. This will allow you to quickly
10966 identify problem areas and cure them without too much disruption. Even
10967 after the initial setup phase is complete, I recommend using the logging
10968 for `deny' as it allows tracing of possible attacks and also modification
10969 of the firewall rules if your requirements alter.
10971 Note: If you use the logging versions of the accept command, be aware
10972 that it can generate large amounts of log data. One log entry will be
10973 generated for every packet that passes through the firewall, so large
10974 FTP/http transfers, etc, will really slow the system down. It also
10975 increases the latencies on those packets as it requires more work to be
10976 done by the kernel before the packet can be passed on. syslogd will also
10977 start using up a lot more processor time as it logs all the extra data
10978 to disk, and it could quite easily fill the partition /var/log is
10981 You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf.
10982 The associated manual page explains which knobs to fiddle and lists some
10983 preset firewall configurations. If you do not use a preset configuration,
10984 ipfw list will output the current ruleset into a file that you can pass to
10985 rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable
10986 your firewall, it is important to make sure your firewall is enabled
10987 before any IP interfaces are configured.
10989 The next problem is what your firewall should actually do! This is largely
10990 dependent on what access to your network you want to allow from the
10991 outside, and how much access to the outside world you want to allow from
10992 the inside. Some general rules are:
10994 * Block all incoming access to ports below 1024 for TCP. This is where
10995 most of the security sensitive services are, like finger, SMTP (mail)
10998 * Block all incoming UDP traffic. There are very few useful services
10999 that travel over UDP, and what useful traffic there is, is normally a
11000 security threat (e.g. Suns RPC and NFS protocols). This has its
11001 disadvantages also, since UDP is a connectionless protocol, denying
11002 incoming UDP traffic also blocks the replies to outgoing UDP traffic.
11003 This can cause a problem for people (on the inside) using external
11004 archie (prospero) servers. If you want to allow access to archie, you
11005 will have to allow packets coming from ports 191 and 1525 to any
11006 internal UDP port through the firewall. ntp is another service you may
11007 consider allowing through, which comes from port 123.
11009 * Block traffic to port 6000 from the outside. Port 6000 is the port
11010 used for access to X11 servers, and can be a security threat
11011 (especially if people are in the habit of doing xhost + on their
11012 workstations). X11 can actually use a range of ports starting at 6000,
11013 the upper limit being how many X displays you can run on the machine.
11014 The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063.
11016 * Check what ports any internal servers use (e.g. SQL servers, etc). It
11017 is probably a good idea to block those as well, as they normally fall
11018 outside the 1-1024 range specified above.
11020 Another checklist for firewall configuration is available from CERT at
11021 http://www.cert.org/tech_tips/packet_filtering.html
11023 As stated above, these are only guidelines. You will have to decide what
11024 filter rules you want to use on your firewall yourself. We cannot accept
11025 ANY responsibility if someone breaks into your network, even if you follow
11026 the advice given above.
11028 ----------------------------------------------------------------------
11030 10.7.7 IPFW Overhead and Optimization
11032 Many people want to know how much overhead IPFW adds to a system. The
11033 answer to this depends mostly on your rule set and processor speed. For
11034 most applications dealing with Ethernet and small rule sets, the answer is
11035 ``negligible''. For those of you that need actual measurements to satisfy
11036 your curiosity, read on.
11038 The following measurements were made using FreeBSD 2.2.5-STABLE on a
11039 486-66. (While IPFW has changed slightly in later releases of DragonFly,
11040 it still performs with similar speed.) IPFW was modified to measure the
11041 time spent within the ip_fw_chk routine, displaying the results to the
11042 console every 1000 packets.
11044 Two rule sets, each with 1000 rules, were tested. The first set was
11045 designed to demonstrate a worst case scenario by repeating the rule:
11047 # ipfw add deny tcp from any to any 55555
11049 This demonstrates a worst case scenario by causing most of IPFW's packet
11050 check routine to be executed before finally deciding that the packet does
11051 not match the rule (by virtue of the port number). Following the 999th
11052 iteration of this rule was an allow ip from any to any.
11054 The second set of rules were designed to abort the rule check quickly:
11056 # ipfw add deny ip from 1.2.3.4 to 1.2.3.4
11058 The non-matching source IP address for the above rule causes these rules
11059 to be skipped very quickly. As before, the 1000th rule was an allow ip
11062 The per-packet processing overhead in the former case was approximately
11063 2.703 ms/packet, or roughly 2.7 microseconds per rule. Thus the
11064 theoretical packet processing limit with these rules is around 370 packets
11065 per second. Assuming 10 Mbps Ethernet and a ~1500 byte packet size, we
11066 would only be able to achieve 55.5% bandwidth utilization.
11068 For the latter case each packet was processed in approximately 1.172 ms,
11069 or roughly 1.2 microseconds per rule. The theoretical packet processing
11070 limit here would be about 853 packets per second, which could consume
11071 10 Mbps Ethernet bandwidth.
11073 The excessive number of rules tested and the nature of those rules do not
11074 provide a real-world scenario -- they were used only to generate the
11075 timing information presented here. Here are a few things to keep in mind
11076 when building an efficient rule set:
11078 * Place an established rule early on to handle the majority of TCP
11079 traffic. Do not put any allow tcp statements before this rule.
11081 * Place heavily triggered rules earlier in the rule set than those
11082 rarely used (without changing the permissiveness of the firewall, of
11083 course). You can see which rules are used most often by examining the
11084 packet counting statistics with ipfw -a l.
11086 ----------------------------------------------------------------------
11090 OpenSSL provides a general-purpose cryptography library, as well as the
11091 Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1
11092 (TLSv1) network security protocols.
11094 However, one of the algorithms (specifically IDEA) included in OpenSSL is
11095 protected by patents in the USA and elsewhere, and is not available for
11096 unrestricted use. IDEA is included in the OpenSSL sources in DragonFly,
11097 but it is not built by default. If you wish to use it, and you comply with
11098 the license terms, enable the MAKE_IDEA switch in /etc/make.conf and
11099 rebuild your sources using make world.
11101 Today, the RSA algorithm is free for use in USA and other countries. In
11102 the past it was protected by a patent.
11104 ----------------------------------------------------------------------
11106 10.8.1 Source Code Installations
11108 OpenSSL is part of the src-crypto and src-secure CVSup collections. See
11109 the Obtaining DragonFly section for more information about obtaining and
11110 updating DragonFly source code.
11112 ----------------------------------------------------------------------
11114 10.9 VPN over IPsec
11116 Written by Nik Clayton.
11118 Creating a VPN between two networks, separated by the Internet, using
11119 DragonFly gateways.
11121 ----------------------------------------------------------------------
11123 10.9.1 Understanding IPsec
11125 Written by Hiten M. Pandya.
11127 This section will guide you through the process of setting up IPsec, and
11128 to use it in an environment which consists of DragonFly and
11129 Microsoft Windows 2000/XP machines, to make them communicate securely. In
11130 order to set up IPsec, it is necessary that you are familiar with the
11131 concepts of building a custom kernel (see Chapter 9).
11133 IPsec is a protocol which sits on top of the Internet Protocol (IP) layer.
11134 It allows two or more hosts to communicate in a secure manner (hence the
11135 name). The DragonFly IPsec ``network stack'' is based on the KAME
11136 implementation, which has support for both protocol families, IPv4 and
11139 IPsec consists of two sub-protocols:
11141 * Encapsulated Security Payload (ESP), protects the IP packet data from
11142 third party interference, by encrypting the contents using symmetric
11143 cryptography algorithms (like Blowfish, 3DES).
11145 * Authentication Header (AH), protects the IP packet header from third
11146 party interference and spoofing, by computing a cryptographic checksum
11147 and hashing the IP packet header fields with a secure hashing
11148 function. This is then followed by an additional header that contains
11149 the hash, to allow the information in the packet to be authenticated.
11151 ESP and AH can either be used together or separately, depending on the
11154 IPsec can either be used to directly encrypt the traffic between two hosts
11155 (known as Transport Mode); or to build ``virtual tunnels'' between two
11156 subnets, which could be used for secure communication between two
11157 corporate networks (known as Tunnel Mode). The latter is more commonly
11158 known as a Virtual Private Network (VPN). The ipsec(4) manual page should
11159 be consulted for detailed information on the IPsec subsystem in DragonFly.
11161 To add IPsec support to your kernel, add the following options to your
11162 kernel configuration file:
11164 options IPSEC #IP security
11165 options IPSEC_ESP #IP security (crypto; define w/ IPSEC)
11168 If IPsec debugging support is desired, the following kernel option should
11171 options IPSEC_DEBUG #debug for IP security
11174 ----------------------------------------------------------------------
11178 There's no standard for what constitutes a VPN. VPNs can be implemented
11179 using a number of different technologies, each of which have their own
11180 strengths and weaknesses. This article presents a number of scenarios, and
11181 strategies for implementing a VPN for each scenario.
11183 ----------------------------------------------------------------------
11185 10.9.3 Scenario #1: Two networks, connected to the Internet, to behave as one
11187 This is the scenario that caused me to first investigating VPNs. The
11188 premise is as follows:
11190 * You have at least two sites
11192 * Both sites are using IP internally
11194 * Both sites are connected to the Internet, through a gateway that is
11197 * The gateway on each network has at least one public IP address.
11199 * The internal addresses of the two networks can be public or private IP
11200 addresses, it doesn't matter. You can be running NAT on the gateway
11201 machine if necessary.
11203 * The internal IP addresses of the two networks do not collide. While I
11204 expect it is theoretically possible to use a combination of VPN
11205 technology and NAT to get this to work, I expect it to be a
11206 configuration nightmare.
11208 If you find that you are trying to connect two networks, both of which,
11209 internally, use the same private IP address range (e.g., both of them use
11210 192.168.1.x), then one of the networks will have to be renumbered.
11212 The network topology might look something like this:
11214 Network #1 [ Internal Hosts ] Private Net, 192.168.1.2-254
11219 .---[fxp1]---. Private IP, 192.168.1.1
11221 `---[fxp0]---' Public IP, A.B.C.D
11224 -=-=- Internet -=-=-
11227 .---[fxp0]---. Public IP, W.X.Y.Z
11229 `---[fxp1]---' Private IP, 192.168.2.1
11232 Network #2 [ Internal Hosts ]
11233 [ Win9x/NT/2K ] Private Net, 192.168.2.2-254
11236 Notice the two public IP addresses. I'll use the letters to refer to them
11237 in the rest of this article. Anywhere you see those letters in this
11238 article, replace them with your own public IP addresses. Note also that
11239 internally, the two gateway machines have .1 IP addresses, and that the
11240 two networks have different private IP addresses (192.168.1.x and
11241 192.168.2.x respectively). All the machines on the private networks have
11242 been configured to use the .1 machine as their default gateway.
11244 The intention is that, from a network point of view, each network should
11245 view the machines on the other network as though they were directly
11246 attached the same router -- albeit a slightly slow router with an
11247 occasional tendency to drop packets.
11249 This means that (for example), machine 192.168.1.20 should be able to run
11253 and have it work, transparently. Windows machines should be able to see
11254 the machines on the other network, browse file shares, and so on, in
11255 exactly the same way that they can browse machines on the local network.
11257 And the whole thing has to be secure. This means that traffic between the
11258 two networks has to be encrypted.
11260 Creating a VPN between these two networks is a multi-step process. The
11261 stages are as follows:
11263 1. Create a ``virtual'' network link between the two networks, across the
11264 Internet. Test it, using tools like ping(8), to make sure it works.
11266 2. Apply security policies to ensure that traffic between the two
11267 networks is transparently encrypted and decrypted as necessary. Test
11268 this, using tools like tcpdump(1), to ensure that traffic is
11271 3. Configure additional software on the DragonFly gateways, to allow
11272 Windows machines to see one another across the VPN.
11274 ----------------------------------------------------------------------
11276 10.9.3.1 Step 1: Creating and testing a ``virtual'' network link
11278 Suppose that you were logged in to the gateway machine on network #1 (with
11279 public IP address A.B.C.D, private IP address 192.168.1.1), and you ran
11280 ping 192.168.2.1, which is the private address of the machine with IP
11281 address W.X.Y.Z. What needs to happen in order for this to work?
11283 1. The gateway machine needs to know how to reach 192.168.2.1. In other
11284 words, it needs to have a route to 192.168.2.1.
11286 2. Private IP addresses, such as those in the 192.168.x range are not
11287 supposed to appear on the Internet at large. Instead, each packet you
11288 send to 192.168.2.1 will need to be wrapped up inside another packet.
11289 This packet will need to appear to be from A.B.C.D, and it will have
11290 to be sent to W.X.Y.Z. This process is called encapsulation.
11292 3. Once this packet arrives at W.X.Y.Z it will need to
11293 ``unencapsulated'', and delivered to 192.168.2.1.
11295 You can think of this as requiring a ``tunnel'' between the two networks.
11296 The two ``tunnel mouths'' are the IP addresses A.B.C.D and W.X.Y.Z, and
11297 the tunnel must be told the addresses of the private IP addresses that
11298 will be allowed to pass through it. The tunnel is used to transfer traffic
11299 with private IP addresses across the public Internet.
11301 This tunnel is created by using the generic interface, or gif devices on
11302 DragonFly. As you can imagine, the gif interface on each gateway host must
11303 be configured with four IP addresses; two for the public IP addresses, and
11304 two for the private IP addresses.
11306 Support for the gif device must be compiled in to the DragonFly kernel on
11307 both machines. You can do this by adding the line:
11311 to the kernel configuration files on both machines, and then compile,
11312 install, and reboot as normal.
11314 Configuring the tunnel is a two step process. First the tunnel must be
11315 told what the outside (or public) IP addresses are, using gifconfig(8).
11316 Then the private IP addresses must be configured using ifconfig(8).
11318 On the gateway machine on network #1 you would run the following two
11319 commands to configure the tunnel.
11321 gifconfig gif0 A.B.C.D W.X.Y.Z
11322 ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
11325 On the other gateway machine you run the same commands, but with the order
11326 of the IP addresses reversed.
11328 gifconfig gif0 W.X.Y.Z A.B.C.D
11329 ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
11336 to see the configuration. For example, on the network #1 gateway, you
11340 gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280
11341 inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff
11342 physical address inet A.B.C.D --> W.X.Y.Z
11345 As you can see, a tunnel has been created between the physical addresses
11346 A.B.C.D and W.X.Y.Z, and the traffic allowed through the tunnel is that
11347 between 192.168.1.1 and 192.168.2.1.
11349 This will also have added an entry to the routing table on both machines,
11350 which you can examine with the command netstat -rn. This output is from
11351 the gateway host on network #1.
11357 Destination Gateway Flags Refs Use Netif Expire
11359 192.168.2.1 192.168.1.1 UH 0 0 gif0
11363 As the ``Flags'' value indicates, this is a host route, which means that
11364 each gateway knows how to reach the other gateway, but they do not know
11365 how to reach the rest of their respective networks. That problem will be
11368 It is likely that you are running a firewall on both machines. This will
11369 need to be circumvented for your VPN traffic. You might want to allow all
11370 traffic between both networks, or you might want to include firewall rules
11371 that protect both ends of the VPN from one another.
11373 It greatly simplifies testing if you configure the firewall to allow all
11374 traffic through the VPN. You can always tighten things up later. If you
11375 are using ipfw(8) on the gateway machines then a command like
11377 ipfw add 1 allow ip from any to any via gif0
11379 will allow all traffic between the two end points of the VPN, without
11380 affecting your other firewall rules. Obviously you will need to run this
11381 command on both gateway hosts.
11383 This is sufficient to allow each gateway machine to ping the other. On
11384 192.168.1.1, you should be able to run
11388 and get a response, and you should be able to do the same thing on the
11389 other gateway machine.
11391 However, you will not be able to reach internal machines on either network
11392 yet. This is because of the routing -- although the gateway machines know
11393 how to reach one another, they do not know how to reach the network behind
11396 To solve this problem you must add a static route on each gateway machine.
11397 The command to do this on the first gateway would be:
11399 route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
11402 This says ``In order to reach the hosts on the network 192.168.2.0, send
11403 the packets to the host 192.168.2.1''. You will need to run a similar
11404 command on the other gateway, but with the 192.168.1.x addresses instead.
11406 IP traffic from hosts on one network will now be able to reach hosts on
11409 That has now created two thirds of a VPN between the two networks, in as
11410 much as it is ``virtual'' and it is a ``network''. It is not private yet.
11411 You can test this using ping(8) and tcpdump(1). Log in to the gateway host
11414 tcpdump dst host 192.168.2.1
11416 In another log in session on the same host run
11420 You will see output that looks something like this:
11422 16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request
11423 16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply
11424 16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request
11425 16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply
11426 16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request
11427 16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply
11430 As you can see, the ICMP messages are going back and forth unencrypted. If
11431 you had used the -s parameter to tcpdump(1) to grab more bytes of data
11432 from the packets you would see more information.
11434 Obviously this is unacceptable. The next section will discuss securing the
11435 link between the two networks so that it all traffic is automatically
11440 * Configure both kernels with ``pseudo-device gif''.
11442 * Edit /etc/rc.conf on gateway host #1 and add the following lines
11443 (replacing IP addresses as necessary).
11445 gifconfig_gif0="A.B.C.D W.X.Y.Z"
11446 ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
11447 static_routes="vpn"
11448 route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
11451 * Edit your firewall script (/etc/rc.firewall, or similar) on both
11454 ipfw add 1 allow ip from any to any via gif0
11456 * Make similar changes to /etc/rc.conf on gateway host #2, reversing the
11457 order of IP addresses.
11459 ----------------------------------------------------------------------
11461 10.9.3.2 Step 2: Securing the link
11463 To secure the link we will be using IPsec. IPsec provides a mechanism for
11464 two hosts to agree on an encryption key, and to then use this key in order
11465 to encrypt data between the two hosts.
11467 The are two areas of configuration to be considered here.
11469 1. There must be a mechanism for two hosts to agree on the encryption
11470 mechanism to use. Once two hosts have agreed on this mechanism there
11471 is said to be a ``security association'' between them.
11473 2. There must be a mechanism for specifying which traffic should be
11474 encrypted. Obviously, you don't want to encrypt all your outgoing
11475 traffic -- you only want to encrypt the traffic that is part of the
11476 VPN. The rules that you put in place to determine what traffic will be
11477 encrypted are called ``security policies''.
11479 Security associations and security policies are both maintained by the
11480 kernel, and can be modified by userland programs. However, before you can
11481 do this you must configure the kernel to support IPsec and the
11482 Encapsulated Security Payload (ESP) protocol. This is done by configuring
11489 and recompiling, reinstalling, and rebooting. As before you will need to
11490 do this to the kernels on both of the gateway hosts.
11492 You have two choices when it comes to setting up security associations.
11493 You can configure them by hand between two hosts, which entails choosing
11494 the encryption algorithm, encryption keys, and so forth, or you can use
11495 daemons that implement the Internet Key Exchange protocol (IKE) to do this
11498 I recommend the latter. Apart from anything else, it is easier to set up.
11500 Editing and displaying security policies is carried out using setkey(8).
11501 By analogy, setkey is to the kernel's security policy tables as route(8)
11502 is to the kernel's routing tables. setkey can also display the current
11503 security associations, and to continue the analogy further, is akin to
11504 netstat -r in that respect.
11506 There are a number of choices for daemons to manage security associations
11507 with DragonFly. This article will describe how to use one of these,
11508 racoon. racoon is in the FreeBSD ports collection, in the security/
11509 category, and is installed in the usual way.
11511 racoon must be run on both gateway hosts. On each host it is configured
11512 with the IP address of the other end of the VPN, and a secret key (which
11513 you choose, and must be the same on both gateways).
11515 The two daemons then contact one another, confirm that they are who they
11516 say they are (by using the secret key that you configured). The daemons
11517 then generate a new secret key, and use this to encrypt the traffic over
11518 the VPN. They periodically change this secret, so that even if an attacker
11519 were to crack one of the keys (which is as theoretically close to
11520 unfeasible as it gets) it won't do them much good -- by the time they've
11521 cracked the key the two daemons have chosen another one.
11523 racoon's configuration is stored in ${PREFIX}/etc/racoon. You should find
11524 a configuration file there, which should not need to be changed too much.
11525 The other component of racoon's configuration, which you will need to
11526 change, is the ``pre-shared key''.
11528 The default racoon configuration expects to find this in the file
11529 ${PREFIX}/etc/racoon/psk.txt. It is important to note that the pre-shared
11530 key is not the key that will be used to encrypt your traffic across the
11531 VPN link, it is simply a token that allows the key management daemons to
11534 psk.txt contains a line for each remote site you are dealing with. In this
11535 example, where there are two sites, each psk.txt file will contain one
11536 line (because each end of the VPN is only dealing with one other end).
11538 On gateway host #1 this line should look like this:
11542 That is, the public IP address of the remote end, whitespace, and a text
11543 string that provides the secret. Obviously, you shouldn't use ``secret''
11544 as your key -- the normal rules for choosing a password apply.
11546 On gateway host #2 the line would look like this
11550 That is, the public IP address of the remote end, and the same secret key.
11551 psk.txt must be mode 0600 (i.e., only read/write to root) before racoon
11554 You must run racoon on both gateway machines. You will also need to add
11555 some firewall rules to allow the IKE traffic, which is carried over UDP to
11556 the ISAKMP (Internet Security Association Key Management Protocol) port.
11557 Again, this should be fairly early in your firewall ruleset.
11559 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
11560 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
11563 Once racoon is running you can try pinging one gateway host from the
11564 other. The connection is still not encrypted, but racoon will then set up
11565 the security associations between the two hosts -- this might take a
11566 moment, and you may see this as a short delay before the ping commands
11569 Once the security association has been set up you can view it using
11574 on either host to view the security association information.
11576 That's one half of the problem. They other half is setting your security
11579 To create a sensible security policy, let's review what's been set up so
11580 far. This discussions hold for both ends of the link.
11582 Each IP packet that you send out has a header that contains data about the
11583 packet. The header includes the IP addresses of both the source and
11584 destination. As we already know, private IP addresses, such as the
11585 192.168.x.y range are not supposed to appear on the public Internet.
11586 Instead, they must first be encapsulated inside another packet. This
11587 packet must have the public source and destination IP addresses
11588 substituted for the private addresses.
11590 So if your outgoing packet started looking like this:
11592 .----------------------.
11593 | Src: 192.168.1.1 |
11594 | Dst: 192.168.2.1 |
11595 | <other header info> |
11596 +----------------------+
11598 `----------------------'
11600 Then it will be encapsulated inside another packet, looking something like
11603 .--------------------------.
11606 | <other header info> |
11607 +--------------------------+
11608 | .----------------------. |
11609 | | Src: 192.168.1.1 | |
11610 | | Dst: 192.168.2.1 | |
11611 | | <other header info> | |
11612 | +----------------------+ |
11613 | | <packet data> | |
11614 | `----------------------' |
11615 `--------------------------'
11617 This encapsulation is carried out by the gif device. As you can see, the
11618 packet now has real IP addresses on the outside, and our original packet
11619 has been wrapped up as data inside the packet that will be put out on the
11622 Obviously, we want all traffic between the VPNs to be encrypted. You might
11623 try putting this in to words, as:
11625 ``If a packet leaves from A.B.C.D, and it is destined for W.X.Y.Z, then
11626 encrypt it, using the necessary security associations.''
11628 ``If a packet arrives from W.X.Y.Z, and it is destined for A.B.C.D, then
11629 decrypt it, using the necessary security associations.''
11631 That's close, but not quite right. If you did this, all traffic to and
11632 from W.X.Y.Z, even traffic that was not part of the VPN, would be
11633 encrypted. That's not quite what you want. The correct policy is as
11636 ``If a packet leaves from A.B.C.D, and that packet is encapsulating
11637 another packet, and it is destined for W.X.Y.Z, then encrypt it, using the
11638 necessary security associations.''
11640 ``If a packet arrives from W.X.Y.Z, and that packet is encapsulating
11641 another packet, and it is destined for A.B.C.D, then encrypt it, using the
11642 necessary security associations.''
11644 A subtle change, but a necessary one.
11646 Security policies are also set using setkey(8). setkey(8) features a
11647 configuration language for defining the policy. You can either enter
11648 configuration instructions via stdin, or you can use the -f option to
11649 specify a filename that contains configuration instructions.
11651 The configuration on gateway host #1 (which has the public IP address
11652 A.B.C.D) to force all outbound traffic to W.X.Y.Z to be encrypted is:
11654 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11657 Put these commands in a file (e.g., /etc/ipsec.conf) and then run
11659 # setkey -f /etc/ipsec.conf
11661 spdadd tells setkey(8) that we want to add a rule to the secure policy
11662 database. The rest of this line specifies which packets will match this
11663 policy. A.B.C.D/32 and W.X.Y.Z/32 are the IP addresses and netmasks that
11664 identify the network or hosts that this policy will apply to. In this
11665 case, we want it to apply to traffic between these two hosts. ipencap
11666 tells the kernel that this policy should only apply to packets that
11667 encapsulate other packets. -P out says that this policy applies to
11668 outgoing packets, and ipsec says that the packet will be secured.
11670 The second line specifies how this packet will be encrypted. esp is the
11671 protocol that will be used, while tunnel indicates that the packet will be
11672 further encapsulated in an IPsec packet. The repeated use of A.B.C.D and
11673 W.X.Y.Z is used to select the security association to use, and the final
11674 require mandates that packets must be encrypted if they match this rule.
11676 This rule only matches outgoing packets. You will need a similar rule to
11677 match incoming packets.
11679 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11681 Note the in instead of out in this case, and the necessary reversal of the
11684 The other gateway host (which has the public IP address W.X.Y.Z) will need
11687 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11688 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11690 Finally, you need to add firewall rules to allow ESP and IPENCAP packets
11691 back and forth. These rules will need to be added to both hosts.
11693 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
11694 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
11695 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
11696 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
11699 Because the rules are symmetric you can use the same rules on each gateway
11702 Outgoing packets will now look something like this:
11704 .------------------------------. --------------------------.
11707 | <other header info> | | Encrypted
11708 +------------------------------+ | packet.
11709 | .--------------------------. | -------------. | contents
11710 | | Src: A.B.C.D | | | | are
11711 | | Dst: W.X.Y.Z | | | | completely
11712 | | <other header info> | | | |- secure
11713 | +--------------------------+ | | Encap'd | from third
11714 | | .----------------------. | | -. | packet | party
11715 | | | Src: 192.168.1.1 | | | | Original |- with real | snooping
11716 | | | Dst: 192.168.2.1 | | | | packet, | IP addr |
11717 | | | <other header info> | | | |- private | |
11718 | | +----------------------+ | | | IP addr | |
11719 | | | <packet data> | | | | | |
11720 | | `----------------------' | | -' | |
11721 | `--------------------------' | -------------' |
11722 `------------------------------' --------------------------'
11725 When they are received by the far end of the VPN they will first be
11726 decrypted (using the security associations that have been negotiated by
11727 racoon). Then they will enter the gif interface, which will unwrap the
11728 second layer, until you are left with the innermost packet, which can then
11729 travel in to the inner network.
11731 You can check the security using the same ping(8) test from earlier.
11732 First, log in to the A.B.C.D gateway machine, and run:
11734 tcpdump dst host 192.168.2.1
11736 In another log in session on the same host run
11740 This time you should see output like the following:
11744 Now, as you can see, tcpdump(1) shows the ESP packets. If you try to
11745 examine them with the -s option you will see (apparently) gibberish,
11746 because of the encryption.
11748 Congratulations. You have just set up a VPN between two remote sites.
11752 * Configure both kernels with:
11758 * Install security/racoon. Edit ${PREFIX}/etc/racoon/psk.txt on both
11759 gateway hosts, adding an entry for the remote host's IP address and a
11760 secret key that they both know. Make sure this file is mode 0600.
11762 * Add the following lines to /etc/rc.conf on each host:
11765 ipsec_file="/etc/ipsec.conf"
11768 * Create an /etc/ipsec.conf on each host that contains the necessary
11769 spdadd lines. On gateway host #1 this would be:
11771 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
11772 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11773 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
11774 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11776 On gateway host #2 this would be:
11778 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
11779 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11780 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
11781 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11783 * Add firewall rules to allow IKE, ESP, and IPENCAP traffic to both
11786 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
11787 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
11788 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
11789 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
11790 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
11791 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
11794 The previous two steps should suffice to get the VPN up and running.
11795 Machines on each network will be able to refer to one another using IP
11796 addresses, and all traffic across the link will be automatically and
11797 securely encrypted.
11799 ----------------------------------------------------------------------
11803 Contributed by Chern Lee.
11805 OpenSSH is a set of network connectivity tools used to access remote
11806 machines securely. It can be used as a direct replacement for rlogin, rsh,
11807 rcp, and telnet. Additionally, any other TCP/IP connections can be
11808 tunneled/forwarded securely through SSH. OpenSSH encrypts all traffic to
11809 effectively eliminate eavesdropping, connection hijacking, and other
11810 network-level attacks.
11812 OpenSSH is maintained by the OpenBSD project, and is based upon SSH
11813 v1.2.12 with all the recent bug fixes and updates. It is compatible with
11814 both SSH protocols 1 and 2.
11816 ----------------------------------------------------------------------
11818 10.10.1 Advantages of Using OpenSSH
11820 Normally, when using telnet(1) or rlogin(1), data is sent over the network
11821 in an clear, un-encrypted form. Network sniffers anywhere in between the
11822 client and server can steal your user/password information or data
11823 transferred in your session. OpenSSH offers a variety of authentication
11824 and encryption methods to prevent this from happening.
11826 ----------------------------------------------------------------------
11828 10.10.2 Enabling sshd
11830 Be sure to make the following addition to your rc.conf file:
11834 This will load sshd(8), the daemon program for OpenSSH, the next time your
11835 system initializes. Alternatively, you can simply run directly the sshd
11836 daemon by typing sshd on the command line.
11838 ----------------------------------------------------------------------
11842 The ssh(1) utility works similarly to rlogin(1).
11844 # ssh user@example.com
11845 Host key not found from the list of known hosts.
11846 Are you sure you want to continue connecting (yes/no)? yes
11847 Host 'example.com' added to the list of known hosts.
11848 user@example.com's password: *******
11850 The login will continue just as it would have if a session was created
11851 using rlogin or telnet. SSH utilizes a key fingerprint system for
11852 verifying the authenticity of the server when the client connects. The
11853 user is prompted to enter yes only when connecting for the first time.
11854 Future attempts to login are all verified against the saved fingerprint
11855 key. The SSH client will alert you if the saved fingerprint differs from
11856 the received fingerprint on future login attempts. The fingerprints are
11857 saved in ~/.ssh/known_hosts, or ~/.ssh/known_hosts2 for SSH v2
11860 By default, OpenSSH servers are configured to accept both SSH v1 and SSH
11861 v2 connections. The client, however, can choose between the two. Version 2
11862 is known to be more robust and secure than its predecessor.
11864 The ssh(1) command can be forced to use either protocol by passing it the
11865 -1 or -2 argument for v1 and v2, respectively.
11867 ----------------------------------------------------------------------
11869 10.10.4 Secure Copy
11871 The scp(1) command works similarly to rcp(1); it copies a file to or from
11872 a remote machine, except in a secure fashion.
11874 # scp user@example.com:/COPYRIGHT COPYRIGHT
11875 user@example.com's password: *******
11876 COPYRIGHT 100% |*****************************| 4735
11880 Since the fingerprint was already saved for this host in the previous
11881 example, it is verified when using scp(1) here.
11883 The arguments passed to scp(1) are similar to cp(1), with the file or
11884 files in the first argument, and the destination in the second. Since the
11885 file is fetched over the network, through SSH, one or more of the file
11886 arguments takes on the form user@host:<path_to_remote_file>.
11888 ----------------------------------------------------------------------
11890 10.10.5 Configuration
11892 The system-wide configuration files for both the OpenSSH daemon and client
11893 reside within the /etc/ssh directory.
11895 ssh_config configures the client settings, while sshd_config configures
11898 Additionally, the sshd_program (/usr/sbin/sshd by default), and sshd_flags
11899 rc.conf options can provide more levels of configuration.
11901 ----------------------------------------------------------------------
11905 Instead of using passwords, ssh-keygen(1) can be used to generate RSA keys
11906 to authenticate a user:
11908 % ssh-keygen -t rsa1
11909 Initializing random number generator...
11910 Generating p: .++ (distance 66)
11911 Generating q: ..............................++ (distance 498)
11912 Computing the keys...
11913 Key generation complete.
11914 Enter file in which to save the key (/home/user/.ssh/identity):
11916 Enter the same passphrase again:
11917 Your identification has been saved in /home/user/.ssh/identity.
11920 ssh-keygen(1) will create a public and private key pair for use in
11921 authentication. The private key is stored in ~/.ssh/identity, whereas the
11922 public key is stored in ~/.ssh/identity.pub. The public key must be placed
11923 in ~/.ssh/authorized_keys of the remote machine in order for the setup to
11926 This will allow connection to the remote machine based upon RSA
11927 authentication instead of passwords.
11929 Note: The -t rsa1 option will create RSA keys for use by SSH protocol
11930 version 1. If you want to use RSA keys with the SSH protocol version 2,
11931 you have to use the command ssh-keygen -t rsa.
11933 If a passphrase is used in ssh-keygen(1), the user will be prompted for a
11934 password each time in order to use the private key.
11936 A SSH protocol version 2 DSA key can be created for the same purpose by
11937 using the ssh-keygen -t dsa command. This will create a public/private DSA
11938 key for use in SSH protocol version 2 sessions only. The public key is
11939 stored in ~/.ssh/id_dsa.pub, while the private key is in ~/.ssh/id_dsa.
11941 DSA public keys are also placed in ~/.ssh/authorized_keys on the remote
11944 ssh-agent(1) and ssh-add(1) are utilities used in managing multiple
11945 passworded private keys.
11947 Warning: The various options and files can be different according to the
11948 OpenSSH version you have on your system, to avoid problems you should
11949 consult the ssh-keygen(1) manual page.
11951 ----------------------------------------------------------------------
11953 10.10.7 SSH Tunneling
11955 OpenSSH has the ability to create a tunnel to encapsulate another protocol
11956 in an encrypted session.
11958 The following command tells ssh(1) to create a tunnel for telnet:
11960 % ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
11963 The ssh command is used with the following options:
11967 Forces ssh to use version 2 of the protocol. (Do not use if you
11968 are working with older SSH servers)
11972 Indicates no command, or tunnel only. If omitted, ssh would
11973 initiate a normal session.
11977 Forces ssh to run in the background.
11981 Indicates a local tunnel in localport:remotehost:remoteport
11984 user@foo.example.com
11986 The remote SSH server.
11988 An SSH tunnel works by creating a listen socket on localhost on the
11989 specified port. It then forwards any connection received on the local
11990 host/port via the SSH connection to the specified remote host and port.
11992 In the example, port 5023 on localhost is being forwarded to port 23 on
11993 localhost of the remote machine. Since 23 is telnet, this would create a
11994 secure telnet session through an SSH tunnel.
11996 This can be used to wrap any number of insecure TCP protocols such as
11997 SMTP, POP3, FTP, etc.
11999 Example 10-1. Using SSH to Create a Secure Tunnel for SMTP
12001 % ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com
12002 user@mailserver.example.com's password: *****
12003 % telnet localhost 5025
12004 Trying 127.0.0.1...
12005 Connected to localhost.
12006 Escape character is '^]'.
12007 220 mailserver.example.com ESMTP
12009 This can be used in conjunction with an ssh-keygen(1) and additional user
12010 accounts to create a more seamless/hassle-free SSH tunneling environment.
12011 Keys can be used in place of typing a password, and the tunnels can be run
12012 as a separate user.
12014 ----------------------------------------------------------------------
12016 10.10.7.1 Practical SSH Tunneling Examples
12018 10.10.7.1.1 Secure Access of a POP3 Server
12020 At work, there is an SSH server that accepts connections from the outside.
12021 On the same office network resides a mail server running a POP3 server.
12022 The network, or network path between your home and office may or may not
12023 be completely trustable. Because of this, you need to check your e-mail in
12024 a secure manner. The solution is to create an SSH connection to your
12025 office's SSH server, and tunnel through to the mail server.
12027 % ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com
12028 user@ssh-server.example.com's password: ******
12030 When the tunnel is up and running, you can point your mail client to send
12031 POP3 requests to localhost port 2110. A connection here will be forwarded
12032 securely across the tunnel to mail.example.com.
12034 ----------------------------------------------------------------------
12036 10.10.7.1.2 Bypassing a Draconian Firewall
12038 Some network administrators impose extremely draconian firewall rules,
12039 filtering not only incoming connections, but outgoing connections. You may
12040 be only given access to contact remote machines on ports 22 and 80 for SSH
12043 You may wish to access another (perhaps non-work related) service, such as
12044 an Ogg Vorbis server to stream music. If this Ogg Vorbis server is
12045 streaming on some other port than 22 or 80, you will not be able to access
12048 The solution is to create an SSH connection to a machine outside of your
12049 network's firewall, and use it to tunnel to the Ogg Vorbis server.
12051 % ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org
12052 user@unfirewalled-system.example.org's password: *******
12054 Your streaming client can now be pointed to localhost port 8888, which
12055 will be forwarded over to music.example.com port 8000, successfully
12056 evading the firewall.
12058 ----------------------------------------------------------------------
12060 10.10.8 Further Reading
12064 ssh(1) scp(1) ssh-keygen(1) ssh-agent(1) ssh-add(1)
12066 sshd(8) sftp-server(8)
12068 ----------------------------------------------------------------------
12070 Chapter 11 Printing
12072 Contributed by Sean Kelly. Restructured and updated by Jim Mock.
12076 DragonFly can be used to print to a wide variety of printers, from the
12077 oldest impact printer to the latest laser printers, and everything in
12078 between, allowing you to produce high quality printed output from the
12079 applications you run.
12081 DragonFly can also be configured to act as a print server on a network; in
12082 this capacity DragonFly can receive print jobs from a variety of other
12083 computers, including other DragonFly computers, Windows and Mac OS hosts.
12084 DragonFly will ensure that one job at a time is printed, and can keep
12085 statistics on which users and machines are doing the most printing,
12086 produce ``banner'' pages showing who's printout is who's, and more.
12088 After reading this chapter, you will know:
12090 * How to configure the DragonFly print spooler.
12092 * How to install print filters, to handle special print jobs
12093 differently, including converting incoming documents to print formats
12094 that your printers understand.
12096 * How to enable header, or banner pages on your printout.
12098 * How to print to printers connected to other computers.
12100 * How to print to printers connected directly to the network.
12102 * How to control printer restrictions, including limiting the size of
12103 print jobs, and preventing certain users from printing.
12105 * How to keep printer statistics, and account for printer usage.
12107 * How to troubleshoot printing problems.
12109 Before reading this chapter, you should:
12111 * Know how to configure and install a new kernel (Chapter 9).
12113 ----------------------------------------------------------------------
12117 In order to use printers with DragonFly, you will need to set them up to
12118 work with the Berkeley line printer spooling system, also known as the LPD
12119 spooling system. It is the standard printer control system in DragonFly.
12120 This chapter introduces the LPD spooling system, often simply called LPD,
12121 and will guide you through its configuration.
12123 If you are already familiar with LPD or another printer spooling system,
12124 you may wish to skip to section Setting up the spooling system.
12126 LPD controls everything about a host's printers. It is responsible for a
12129 * It controls access to attached printers and printers attached to other
12130 hosts on the network.
12132 * It enables users to submit files to be printed; these submissions are
12135 * It prevents multiple users from accessing a printer at the same time
12136 by maintaining a queue for each printer.
12138 * It can print header pages (also known as banner or burst pages) so
12139 users can easily find jobs they have printed in a stack of printouts.
12141 * It takes care of communications parameters for printers connected on
12144 * It can send jobs over the network to a LPD spooler on another host.
12146 * It can run special filters to format jobs to be printed for various
12147 printer languages or printer capabilities.
12149 * It can account for printer usage.
12151 Through a configuration file (/etc/printcap), and by providing the special
12152 filter programs, you can enable the LPD system to do all or some subset of
12153 the above for a great variety of printer hardware.
12155 ----------------------------------------------------------------------
12157 11.2.1 Why You Should Use the Spooler
12159 If you are the sole user of your system, you may be wondering why you
12160 should bother with the spooler when you do not need access control, header
12161 pages, or printer accounting. While it is possible to enable direct access
12162 to a printer, you should use the spooler anyway since:
12164 * LPD prints jobs in the background; you do not have to wait for data to
12165 be copied to the printer.
12167 * LPD can conveniently run a job to be printed through filters to add
12168 date/time headers or convert a special file format (such as a TeX DVI
12169 file) into a format the printer will understand. You will not have to
12170 do these steps manually.
12172 * Many free and commercial programs that provide a print feature usually
12173 expect to talk to the spooler on your system. By setting up the
12174 spooling system, you will more easily support other software you may
12175 later add or already have.
12177 ----------------------------------------------------------------------
12181 To use printers with the LPD spooling system, you will need to set up both
12182 your printer hardware and the LPD software. This document describes two
12185 * See section Simple Printer Setup to learn how to connect a printer,
12186 tell LPD how to communicate with it, and print plain text files to the
12189 * See section Advanced Printer Setup to find out how to print a variety
12190 of special file formats, to print header pages, to print across a
12191 network, to control access to printers, and to do printer accounting.
12193 ----------------------------------------------------------------------
12195 11.3.1 Simple Printer Setup
12197 This section tells how to configure printer hardware and the LPD software
12198 to use the printer. It teaches the basics:
12200 * Section Hardware Setup gives some hints on connecting the printer to a
12201 port on your computer.
12203 * Section Software Setup shows how to set up the LPD spooler
12204 configuration file (/etc/printcap).
12206 If you are setting up a printer that uses a network protocol to accept
12207 data to print instead of a serial or parallel interface, see Printers With
12208 Networked Data Stream Interfaces.
12210 Although this section is called ``Simple Printer Setup'', it is actually
12211 fairly complex. Getting the printer to work with your computer and the LPD
12212 spooler is the hardest part. The advanced options like header pages and
12213 accounting are fairly easy once you get the printer working.
12215 ----------------------------------------------------------------------
12217 11.3.1.1 Hardware Setup
12219 This section tells about the various ways you can connect a printer to
12220 your PC. It talks about the kinds of ports and cables, and also the kernel
12221 configuration you may need to enable DragonFly to speak to the printer.
12223 If you have already connected your printer and have successfully printed
12224 with it under another operating system, you can probably skip to section
12227 ----------------------------------------------------------------------
12229 11.3.1.1.1 Ports and Cables
12231 Printers sold for use on PC's today generally come with one or more of the
12232 following three interfaces:
12234 * Serial interfaces, also known as RS232C or RS232D, or COM ports, use a
12235 serial port on your computer to send data to the printer. Serial
12236 interfaces are common in the computer industry and cables are readily
12237 available and also easy to construct. Serial interfaces sometimes need
12238 special cables and might require you to configure somewhat complex
12239 communications options. Most PC serial ports have a maximum
12240 transmission rate of 115200 bps, which makes printing large graphic
12241 print jobs with them impractical.
12243 * Parallel interfaces use a parallel port on your computer to send data
12244 to the printer. Parallel interfaces are common in the PC market and
12245 are faster than RS232 serial. Cables are readily available but more
12246 difficult to construct by hand. There are usually no communications
12247 options with parallel interfaces, making their configuration
12248 exceedingly simple.
12250 Parallel interfaces are sometimes known as ``Centronics'' interfaces,
12251 named after the connector type on the printer.
12253 * USB interfaces, named for the Universal Serial Bus, can run at even
12254 faster speeds than parallel or RS232 serial interfaces. Cables are
12255 simple and cheap. USB is superior to RS232 Serial and to Parallel for
12256 printing, but it is not as well supported under UNIX systems. A way to
12257 avoid this problem is to purchase a printer that has both a USB
12258 interface and a Parallel interface, as many printers do.
12260 In general, Parallel interfaces usually offer just one-way communication
12261 (computer to printer) while serial and USB gives you two-way. Newer
12262 parallel ports (EPP and ECP) and printers can communicate in both
12263 directions under DragonFly when a IEEE1284 compliant cable is used.
12265 Two-way communication to the printer over a parallel port is generally
12266 done one of two ways. The first method uses a custom built printer driver
12267 for DragonFly that speaks the proprietary language used by the printer.
12268 This is common with inkjet printers and can be used for reporting ink
12269 levels and other status information. The second method is used when the
12270 printer supports PostScript.
12272 PostScript jobs are actually programs sent to the printer; they need not
12273 produce paper at all and may return results directly to the computer.
12274 PostScript also uses two-way communication to tell the computer about
12275 problems, such as errors in the PostScript program or paper jams. Your
12276 users may be appreciative of such information. Furthermore, the best way
12277 to do effective accounting with a PostScript printer requires two-way
12278 communication: you ask the printer for its page count (how many pages it
12279 has printed in its lifetime), then send the user's job, then ask again for
12280 its page count. Subtract the two values and you know how much paper to
12283 ----------------------------------------------------------------------
12285 11.3.1.1.2 Parallel Ports
12287 To hook up a printer using a parallel interface, connect the Centronics
12288 cable between the printer and the computer. The instructions that came
12289 with the printer, the computer, or both should give you complete guidance.
12291 Remember which parallel port you used on the computer. The first parallel
12292 port is /dev/ppc0 to DragonFly; the second is /dev/ppc1, and so on. The
12293 printer device name uses the same scheme: /dev/lpt0 for the printer on the
12294 first parallel ports etc.
12296 ----------------------------------------------------------------------
12298 11.3.1.1.3 Serial Ports
12300 To hook up a printer using a serial interface, connect the proper serial
12301 cable between the printer and the computer. The instructions that came
12302 with the printer, the computer, or both should give you complete guidance.
12304 If you are unsure what the ``proper serial cable'' is, you may wish to try
12305 one of the following alternatives:
12307 * A modem cable connects each pin of the connector on one end of the
12308 cable straight through to its corresponding pin of the connector on
12309 the other end. This type of cable is also known as a ``DTE-to-DCE''
12312 * A null-modem cable connects some pins straight through, swaps others
12313 (send data to receive data, for example), and shorts some internally
12314 in each connector hood. This type of cable is also known as a
12315 ``DTE-to-DTE'' cable.
12317 * A serial printer cable, required for some unusual printers, is like
12318 the null-modem cable, but sends some signals to their counterparts
12319 instead of being internally shorted.
12321 You should also set up the communications parameters for the printer,
12322 usually through front-panel controls or DIP switches on the printer.
12323 Choose the highest bps (bits per second, sometimes baud rate) rate that
12324 both your computer and the printer can support. Choose 7 or 8 data bits;
12325 none, even, or odd parity; and 1 or 2 stop bits. Also choose a flow
12326 control protocol: either none, or XON/XOFF (also known as ``in-band'' or
12327 ``software'') flow control. Remember these settings for the software
12328 configuration that follows.
12330 ----------------------------------------------------------------------
12332 11.3.1.2 Software Setup
12334 This section describes the software setup necessary to print with the LPD
12335 spooling system in DragonFly.
12337 Here is an outline of the steps involved:
12339 1. Configure your kernel, if necessary, for the port you are using for
12340 the printer; section Kernel Configuration tells you what you need to
12343 2. Set the communications mode for the parallel port, if you are using a
12344 parallel port; section Setting the Communication Mode for the Parallel
12345 Port gives details.
12347 3. Test if the operating system can send data to the printer. Section
12348 Checking Printer Communications gives some suggestions on how to do
12351 4. Set up LPD for the printer by modifying the file /etc/printcap. You
12352 will find out how to do this later in this chapter.
12354 ----------------------------------------------------------------------
12356 11.3.1.2.1 Kernel Configuration
12358 The operating system kernel is compiled to work with a specific set of
12359 devices. The serial or parallel interface for your printer is a part of
12360 that set. Therefore, it might be necessary to add support for an
12361 additional serial or parallel port if your kernel is not already
12362 configured for one.
12364 To find out if the kernel you are currently using supports a serial
12367 # grep sioN /var/run/dmesg.boot
12369 Where N is the number of the serial port, starting from zero. If you see
12370 output similar to the following:
12372 sio2 at port 0x3e8-0x3ef irq 5 on isa
12375 then the kernel supports the port.
12377 To find out if the kernel supports a parallel interface, type:
12379 # grep ppcN /var/run/dmesg.boot
12381 Where N is the number of the parallel port, starting from zero. If you see
12382 output similar to the following:
12384 ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0
12385 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
12386 ppc0: FIFO with 16/16/8 bytes threshold
12388 then the kernel supports the port.
12390 You might have to reconfigure your kernel in order for the operating
12391 system to recognize and use the parallel or serial port you are using for
12394 To add support for a serial port, see the section on kernel configuration.
12395 To add support for a parallel port, see that section and the section that
12398 ----------------------------------------------------------------------
12400 11.3.1.3 Adding /dev Entries for the Ports
12402 Even though the kernel may support communication along a serial or
12403 parallel port, you will still need a software interface through which
12404 programs running on the system can send and receive data. That is what
12405 entries in the /dev directory are for.
12407 To add a /dev entry for a port:
12409 1. Become root with the su(1) command. Enter the root password when
12412 2. Change to the /dev directory:
12420 Where port is the device entry for the port you want to make. Use lpt0
12421 for the printer on the first parallel port, lpt1 for the printer on
12422 the second port, and so on; use ttyd0 for the first serial port, ttyd1
12423 for the second, and so on.
12429 to make sure the device entry got created.
12431 ----------------------------------------------------------------------
12433 11.3.1.3.1 Setting the Communication Mode for the Parallel Port
12435 When you are using the parallel interface, you can choose whether
12436 DragonFly should use interrupt-driven or polled communication with the
12437 printer. The generic printer device driver (lpt(4)) on DragonFly uses the
12438 ppbus(4) system, which controls the port chipset with the ppc(4) driver.
12440 * The interrupt-driven method is the default with the GENERIC kernel.
12441 With this method, the operating system uses an IRQ line to determine
12442 when the printer is ready for data.
12444 * The polled method directs the operating system to repeatedly ask the
12445 printer if it is ready for more data. When it responds ready, the
12446 kernel sends more data.
12448 The interrupt-driven method is usually somewhat faster but uses up a
12449 precious IRQ line. Some newer HP printers are claimed not to work
12450 correctly in interrupt mode, apparently due to some (not yet exactly
12451 understood) timing problem. These printers need polled mode. You should
12452 use whichever one works. Some printers will work in both modes, but are
12453 painfully slow in interrupt mode.
12455 You can set the communications mode in two ways: by configuring the kernel
12456 or by using the lptcontrol(8) program.
12458 To set the communications mode by configuring the kernel:
12460 1. Edit your kernel configuration file. Look for an ppc0 entry. If you
12461 are setting up the second parallel port, use ppc1 instead. Use ppc2
12462 for the third port, and so on.
12464 * If you want interrupt-driven mode, add the irq specifier:
12466 device ppc0 at isa? irq N
12468 Where N is the IRQ number for your computer's parallel port.
12470 * If you want polled mode, do not add the irq specifier. Use the
12471 following line in your kernel configuration file:
12473 device ppc0 at isa?
12475 2. Save the file. Then configure, build, and install the kernel, then
12476 reboot. See kernel configuration for more details.
12478 To set the communications mode with lptcontrol(8):
12482 # lptcontrol -i -d /dev/lptN
12484 to set interrupt-driven mode for lptN.
12488 # lptcontrol -p -d /dev/lptN
12490 to set polled-mode for lptN.
12492 You could put these commands in your /etc/rc.local file to set the mode
12493 each time your system boots. See lptcontrol(8) for more information.
12495 ----------------------------------------------------------------------
12497 11.3.1.3.2 Checking Printer Communications
12499 Before proceeding to configure the spooling system, you should make sure
12500 the operating system can successfully send data to your printer. It is a
12501 lot easier to debug printer communication and the spooling system
12504 To test the printer, we will send some text to it. For printers that can
12505 immediately print characters sent to them, the program lptest(1) is
12506 perfect: it generates all 96 printable ASCII characters in 96 lines.
12508 For a PostScript (or other language-based) printer, we will need a more
12509 sophisticated test. A small PostScript program, such as the following,
12513 100 100 moveto 300 300 lineto stroke
12514 310 310 moveto /Helvetica findfont 12 scalefont setfont
12515 (Is this thing working?) show
12518 The above PostScript code can be placed into a file and used as shown in
12519 the examples appearing in the following sections.
12521 Note: When this document refers to a printer language, it is assuming a
12522 language like PostScript, and not Hewlett Packard's PCL. Although PCL
12523 has great functionality, you can intermingle plain text with its escape
12524 sequences. PostScript cannot directly print plain text, and that is the
12525 kind of printer language for which we must make special accommodations.
12527 ----------------------------------------------------------------------
12529 11.3.1.3.2.1 Checking a Parallel Printer
12531 This section tells you how to check if DragonFly can communicate with a
12532 printer connected to a parallel port.
12534 To test a printer on a parallel port:
12536 1. Become root with su(1).
12538 2. Send data to the printer.
12540 * If the printer can print plain text, then use lptest(1). Type:
12542 # lptest > /dev/lptN
12544 Where N is the number of the parallel port, starting from zero.
12546 * If the printer understands PostScript or other printer language,
12547 then send a small program to the printer. Type:
12551 Then, line by line, type the program carefully as you cannot edit
12552 a line once you have pressed RETURN or ENTER. When you have
12553 finished entering the program, press CONTROL+D, or whatever your
12554 end of file key is.
12556 Alternatively, you can put the program in a file and type:
12558 # cat file > /dev/lptN
12560 Where file is the name of the file containing the program you
12561 want to send to the printer.
12563 You should see something print. Do not worry if the text does not look
12564 right; we will fix such things later.
12566 ----------------------------------------------------------------------
12568 11.3.1.3.2.2 Checking a Serial Printer
12570 This section tells you how to check if DragonFly can communicate with a
12571 printer on a serial port.
12573 To test a printer on a serial port:
12575 1. Become root with su(1).
12577 2. Edit the file /etc/remote. Add the following entry:
12579 printer:dv=/dev/port:br#bps-rate:pa=parity
12581 Where port is the device entry for the serial port (ttyd0, ttyd1,
12582 etc.), bps-rate is the bits-per-second rate at which the printer
12583 communicates, and parity is the parity required by the printer (either
12584 even, odd, none, or zero).
12586 Here is a sample entry for a printer connected via a serial line to
12587 the third serial port at 19200 bps with no parity:
12589 printer:dv=/dev/ttyd2:br#19200:pa=none
12591 3. Connect to the printer with tip(1). Type:
12595 If this step does not work, edit the file /etc/remote again and try
12596 using /dev/cuaaN instead of /dev/ttydN.
12598 4. Send data to the printer.
12600 * If the printer can print plain text, then use lptest(1). Type:
12604 * If the printer understands PostScript or other printer language,
12605 then send a small program to the printer. Type the program, line
12606 by line, very carefully as backspacing or other editing keys may
12607 be significant to the printer. You may also need to type a
12608 special end-of-file key for the printer so it knows it received
12609 the whole program. For PostScript printers, press CONTROL+D.
12611 Alternatively, you can put the program in a file and type:
12615 Where file is the name of the file containing the program. After
12616 tip(1) sends the file, press any required end-of-file key.
12618 You should see something print. Do not worry if the text does not look
12619 right; we will fix that later.
12621 ----------------------------------------------------------------------
12623 11.3.1.4 Enabling the Spooler: the /etc/printcap File
12625 At this point, your printer should be hooked up, your kernel configured to
12626 communicate with it (if necessary), and you have been able to send some
12627 simple data to the printer. Now, we are ready to configure LPD to control
12628 access to your printer.
12630 You configure LPD by editing the file /etc/printcap. The LPD spooling
12631 system reads this file each time the spooler is used, so updates to the
12632 file take immediate effect.
12634 The format of the printcap(5) file is straightforward. Use your favorite
12635 text editor to make changes to /etc/printcap. The format is identical to
12636 other capability files like /usr/share/misc/termcap and /etc/remote. For
12637 complete information about the format, see the cgetent(3).
12639 The simple spooler configuration consists of the following steps:
12641 1. Pick a name (and a few convenient aliases) for the printer, and put
12642 them in the /etc/printcap file; see the Naming the Printer section for
12643 more information on naming.
12645 2. Turn off header pages (which are on by default) by inserting the sh
12646 capability; see the Suppressing Header Pages section for more
12649 3. Make a spooling directory, and specify its location with the sd
12650 capability; see the Making the Spooling Directory section for more
12653 4. Set the /dev entry to use for the printer, and note it in
12654 /etc/printcap with the lp capability; see the Identifying the Printer
12655 Device for more information. Also, if the printer is on a serial port,
12656 set up the communication parameters with the ms# capability which is
12657 discussed in the Configuring Spooler Communications Parameters
12660 5. Install a plain text input filter; see the Installing the Text Filter
12661 section for details.
12663 6. Test the setup by printing something with the lpr(1) command. More
12664 details are available in the Trying It Out and Troubleshooting
12667 Note: Language-based printers, such as PostScript printers, cannot
12668 directly print plain text. The simple setup outlined above and described
12669 in the following sections assumes that if you are installing such a
12670 printer you will print only files that the printer can understand.
12672 Users often expect that they can print plain text to any of the printers
12673 installed on your system. Programs that interface to LPD to do their
12674 printing usually make the same assumption. If you are installing such a
12675 printer and want to be able to print jobs in the printer language and
12676 print plain text jobs, you are strongly urged to add an additional step to
12677 the simple setup outlined above: install an automatic
12678 plain-text-to-PostScript (or other printer language) conversion program.
12679 The section entitled Accommodating Plain Text Jobs on PostScript Printers
12680 tells how to do this.
12682 ----------------------------------------------------------------------
12684 11.3.1.4.1 Naming the Printer
12686 The first (easy) step is to pick a name for your printer It really does
12687 not matter whether you choose functional or whimsical names since you can
12688 also provide a number of aliases for the printer.
12690 At least one of the printers specified in the /etc/printcap should have
12691 the alias lp. This is the default printer's name. If users do not have the
12692 PRINTER environment variable nor specify a printer name on the command
12693 line of any of the LPD commands, then lp will be the default printer they
12696 Also, it is common practice to make the last alias for a printer be a full
12697 description of the printer, including make and model.
12699 Once you have picked a name and some common aliases, put them in the
12700 /etc/printcap file. The name of the printer should start in the leftmost
12701 column. Separate each alias with a vertical bar and put a colon after the
12704 In the following example, we start with a skeletal /etc/printcap that
12705 defines two printers (a Diablo 630 line printer and a Panasonic KX-P4455
12706 PostScript laser printer):
12709 # /etc/printcap for host rose
12711 rattan|line|diablo|lp|Diablo 630 Line Printer:
12713 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:
12715 In this example, the first printer is named rattan and has as aliases
12716 line, diablo, lp, and Diablo 630 Line Printer. Since it has the alias lp,
12717 it is also the default printer. The second is named bamboo, and has as
12718 aliases ps, PS, S, panasonic, and Panasonic KX-P4455 PostScript v51.4.
12720 ----------------------------------------------------------------------
12722 11.3.1.4.2 Suppressing Header Pages
12724 The LPD spooling system will by default print a header page for each job.
12725 The header page contains the user name who requested the job, the host
12726 from which the job came, and the name of the job, in nice large letters.
12727 Unfortunately, all this extra text gets in the way of debugging the simple
12728 printer setup, so we will suppress header pages.
12730 To suppress header pages, add the sh capability to the entry for the
12731 printer in /etc/printcap. Here is an example /etc/printcap with sh added:
12734 # /etc/printcap for host rose - no header pages anywhere
12736 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12739 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12742 Note how we used the correct format: the first line starts in the leftmost
12743 column, and subsequent lines are indented with a single TAB. Every line in
12744 an entry except the last ends in a backslash character.
12746 ----------------------------------------------------------------------
12748 11.3.1.4.3 Making the Spooling Directory
12750 The next step in the simple spooler setup is to make a spooling directory,
12751 a directory where print jobs reside until they are printed, and where a
12752 number of other spooler support files live.
12754 Because of the variable nature of spooling directories, it is customary to
12755 put these directories under /var/spool. It is not necessary to backup the
12756 contents of spooling directories, either. Recreating them is as simple as
12759 It is also customary to make the directory with a name that is identical
12760 to the name of the printer, as shown below:
12762 # mkdir /var/spool/printer-name
12764 However, if you have a lot of printers on your network, you might want to
12765 put the spooling directories under a single directory that you reserve
12766 just for printing with LPD. We will do this for our two example printers
12769 # mkdir /var/spool/lpd
12770 # mkdir /var/spool/lpd/rattan
12771 # mkdir /var/spool/lpd/bamboo
12773 Note: If you are concerned about the privacy of jobs that users print,
12774 you might want to protect the spooling directory so it is not publicly
12775 accessible. Spooling directories should be owned and be readable,
12776 writable, and searchable by user daemon and group daemon, and no one
12777 else. We will do this for our example printers:
12779 # chown daemon:daemon /var/spool/lpd/rattan
12780 # chown daemon:daemon /var/spool/lpd/bamboo
12781 # chmod 770 /var/spool/lpd/rattan
12782 # chmod 770 /var/spool/lpd/bamboo
12784 Finally, you need to tell LPD about these directories using the
12785 /etc/printcap file. You specify the pathname of the spooling directory
12786 with the sd capability:
12789 # /etc/printcap for host rose - added spooling directories
12791 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12792 :sh:sd=/var/spool/lpd/rattan:
12794 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12795 :sh:sd=/var/spool/lpd/bamboo:
12797 Note that the name of the printer starts in the first column but all other
12798 entries describing the printer should be indented with a tab and each line
12799 escaped with a backslash.
12801 If you do not specify a spooling directory with sd, the spooling system
12802 will use /var/spool/lpd as a default.
12804 ----------------------------------------------------------------------
12806 11.3.1.4.4 Identifying the Printer Device
12808 In the Adding /dev Entries for the Ports section, we identified which
12809 entry in the /dev directory DragonFly will use to communicate with the
12810 printer. Now, we tell LPD that information. When the spooling system has a
12811 job to print, it will open the specified device on behalf of the filter
12812 program (which is responsible for passing data to the printer).
12814 List the /dev entry pathname in the /etc/printcap file using the lp
12817 In our running example, let us assume that rattan is on the first parallel
12818 port, and bamboo is on a sixth serial port; here are the additions to
12822 # /etc/printcap for host rose - identified what devices to use
12824 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12825 :sh:sd=/var/spool/lpd/rattan:\
12828 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12829 :sh:sd=/var/spool/lpd/bamboo:\
12832 If you do not specify the lp capability for a printer in your
12833 /etc/printcap file, LPD uses /dev/lp as a default. /dev/lp currently does
12834 not exist in DragonFly.
12836 If the printer you are installing is connected to a parallel port, skip to
12837 the section entitled, Installing the Text Filter. Otherwise, be sure to
12838 follow the instructions in the next section.
12840 ----------------------------------------------------------------------
12842 11.3.1.4.5 Configuring Spooler Communication Parameters
12844 For printers on serial ports, LPD can set up the bps rate, parity, and
12845 other serial communication parameters on behalf of the filter program that
12846 sends data to the printer. This is advantageous since:
12848 * It lets you try different communication parameters by simply editing
12849 the /etc/printcap file; you do not have to recompile the filter
12852 * It enables the spooling system to use the same filter program for
12853 multiple printers which may have different serial communication
12856 The following /etc/printcap capabilities control serial communication
12857 parameters of the device listed in the lp capability:
12861 Sets the communications speed of the device to bps-rate, where
12862 bps-rate can be 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800,
12863 2400, 4800, 9600, 19200, 38400, 57600, or 115200 bits-per-second.
12867 Sets the options for the terminal device after opening the device.
12868 stty(1) explains the available options.
12870 When LPD opens the device specified by the lp capability, it sets the
12871 characteristics of the device to those specified with the ms# capability.
12872 Of particular interest will be the parenb, parodd, cs5, cs6, cs7, cs8,
12873 cstopb, crtscts, and ixon modes, which are explained in the stty(1) manual
12876 Let us add to our example printer on the sixth serial port. We will set
12877 the bps rate to 38400. For the mode, we will set no parity with -parenb,
12878 8-bit characters with cs8, no modem control with clocal and hardware flow
12879 control with crtscts:
12881 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12882 :sh:sd=/var/spool/lpd/bamboo:\
12883 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:
12885 ----------------------------------------------------------------------
12887 11.3.1.4.6 Installing the Text Filter
12889 We are now ready to tell LPD what text filter to use to send jobs to the
12890 printer. A text filter, also known as an input filter, is a program that
12891 LPD runs when it has a job to print. When LPD runs the text filter for a
12892 printer, it sets the filter's standard input to the job to print, and its
12893 standard output to the printer device specified with the lp capability.
12894 The filter is expected to read the job from standard input, perform any
12895 necessary translation for the printer, and write the results to standard
12896 output, which will get printed. For more information on the text filter,
12897 see the Filters section.
12899 For our simple printer setup, the text filter can be a small shell script
12900 that just executes /bin/cat to send the job to the printer. DragonFly
12901 comes with another filter called lpf that handles backspacing and
12902 underlining for printers that might not deal with such character streams
12903 well. And, of course, you can use any other filter program you want. The
12904 filter lpf is described in detail in section entitled lpf: a Text Filter.
12906 First, let us make the shell script /usr/local/libexec/if-simple be a
12907 simple text filter. Put the following text into that file with your
12908 favorite text editor:
12912 # if-simple - Simple text input filter for lpd
12913 # Installed in /usr/local/libexec/if-simple
12915 # Simply copies stdin to stdout. Ignores all filter arguments.
12920 Make the file executable:
12922 # chmod 555 /usr/local/libexec/if-simple
12924 And then tell LPD to use it by specifying it with the if capability in
12925 /etc/printcap. We will add it to the two printers we have so far in the
12926 example /etc/printcap:
12929 # /etc/printcap for host rose - added text filter
12931 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12932 :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\
12933 :if=/usr/local/libexec/if-simple:
12935 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12936 :sh:sd=/var/spool/lpd/bamboo:\
12937 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:\
12938 :if=/usr/local/libexec/if-simple:
12940 ----------------------------------------------------------------------
12942 11.3.1.4.7 Turn on LPD
12944 lpd(8) is run from /etc/rc, controlled by the lpd_enable variable. This
12945 variable defaults to NO. If you have not done so already, add the line:
12949 to /etc/rc.conf, and then either restart your machine, or just run lpd(8).
12953 ----------------------------------------------------------------------
12955 11.3.1.4.8 Trying It Out
12957 You have reached the end of the simple LPD setup. Unfortunately,
12958 congratulations are not quite yet in order, since we still have to test
12959 the setup and correct any problems. To test the setup, try printing
12960 something. To print with the LPD system, you use the command lpr(1), which
12961 submits a job for printing.
12963 You can combine lpr(1) with the lptest(1) program, introduced in section
12964 Checking Printer Communications to generate some test text.
12966 To test the simple LPD setup:
12970 # lptest 20 5 | lpr -Pprinter-name
12972 Where printer-name is a the name of a printer (or an alias) specified in
12973 /etc/printcap. To test the default printer, type lpr(1) without any -P
12974 argument. Again, if you are testing a printer that expects PostScript,
12975 send a PostScript program in that language instead of using lptest(1). You
12976 can do so by putting the program in a file and typing lpr file.
12978 For a PostScript printer, you should get the results of the program. If
12979 you are using lptest(1), then your results should look like the following:
12981 !"#$%&'()*+,-./01234
12982 "#$%&'()*+,-./012345
12983 #$%&'()*+,-./0123456
12984 $%&'()*+,-./01234567
12985 %&'()*+,-./012345678
12987 To further test the printer, try downloading larger programs (for
12988 language-based printers) or running lptest(1) with different arguments.
12989 For example, lptest 80 60 will produce 60 lines of 80 characters each.
12991 If the printer did not work, see the Troubleshooting section.
12993 ----------------------------------------------------------------------
12995 11.4 Advanced Printer Setup
12997 This section describes filters for printing specially formatted files,
12998 header pages, printing across networks, and restricting and accounting for
13001 ----------------------------------------------------------------------
13005 Although LPD handles network protocols, queuing, access control, and other
13006 aspects of printing, most of the real work happens in the filters. Filters
13007 are programs that communicate with the printer and handle its device
13008 dependencies and special requirements. In the simple printer setup, we
13009 installed a plain text filter--an extremely simple one that should work
13010 with most printers (section Installing the Text Filter).
13012 However, in order to take advantage of format conversion, printer
13013 accounting, specific printer quirks, and so on, you should understand how
13014 filters work. It will ultimately be the filter's responsibility to handle
13015 these aspects. And the bad news is that most of the time you have to
13016 provide filters yourself. The good news is that many are generally
13017 available; when they are not, they are usually easy to write.
13019 Also, DragonFly comes with one, /usr/libexec/lpr/lpf, that works with many
13020 printers that can print plain text. (It handles backspacing and tabs in
13021 the file, and does accounting, but that is about all it does.) There are
13022 also several filters and filter components in pkgsrc.
13024 Here is what you will find in this section:
13026 * Section How Filters Work, tries to give an overview of a filter's role
13027 in the printing process. You should read this section to get an
13028 understanding of what is happening ``under the hood'' when LPD uses
13029 filters. This knowledge could help you anticipate and debug problems
13030 you might encounter as you install more and more filters on each of
13033 * LPD expects every printer to be able to print plain text by default.
13034 This presents a problem for PostScript (or other language-based
13035 printers) which cannot directly print plain text. Section
13036 Accommodating Plain Text Jobs on PostScript Printers tells you what
13037 you should do to overcome this problem. You should read this section
13038 if you have a PostScript printer.
13040 * PostScript is a popular output format for many programs. Even some
13041 people (myself included) write PostScript code directly. But
13042 PostScript printers are expensive. Section Simulating PostScript on
13043 Non PostScript Printers tells how you can further modify a printer's
13044 text filter to accept and print PostScript data on a non PostScript
13045 printer. You should read this section if you do not have a PostScript
13048 * Section Conversion Filters tells about a way you can automate the
13049 conversion of specific file formats, such as graphic or typesetting
13050 data, into formats your printer can understand. After reading this
13051 section, you should be able to set up your printers such that users
13052 can type lpr -t to print troff data, or lpr -d to print TeX DVI data,
13053 or lpr -v to print raster image data, and so forth. I recommend
13054 reading this section.
13056 * Section Output Filters tells all about a not often used feature of
13057 LPD: output filters. Unless you are printing header pages (see Header
13058 Pages), you can probably skip that section altogether.
13060 * Section lpf: a Text Filter describes lpf, a fairly complete if simple
13061 text filter for line printers (and laser printers that act like line
13062 printers) that comes with DragonFly. If you need a quick way to get
13063 printer accounting working for plain text, or if you have a printer
13064 which emits smoke when it sees backspace characters, you should
13065 definitely consider lpf.
13067 ----------------------------------------------------------------------
13069 11.4.1.1 How Filters Work
13071 As mentioned before, a filter is an executable program started by LPD to
13072 handle the device-dependent part of communicating with the printer.
13074 When LPD wants to print a file in a job, it starts a filter program. It
13075 sets the filter's standard input to the file to print, its standard output
13076 to the printer, and its standard error to the error logging file
13077 (specified in the lf capability in /etc/printcap, or /dev/console by
13080 Which filter LPD starts and the filter's arguments depend on what is
13081 listed in the /etc/printcap file and what arguments the user specified for
13082 the job on the lpr(1) command line. For example, if the user typed lpr -t,
13083 LPD would start the troff filter, listed in the tf capability for the
13084 destination printer. If the user wanted to print plain text, it would
13085 start the if filter (this is mostly true: see Output Filters for details).
13087 There are three kinds of filters you can specify in /etc/printcap:
13089 * The text filter, confusingly called the input filter in LPD
13090 documentation, handles regular text printing. Think of it as the
13091 default filter. LPD expects every printer to be able to print plain
13092 text by default, and it is the text filter's job to make sure
13093 backspaces, tabs, or other special characters do not confuse the
13094 printer. If you are in an environment where you have to account for
13095 printer usage, the text filter must also account for pages printed,
13096 usually by counting the number of lines printed and comparing that to
13097 the number of lines per page the printer supports. The text filter is
13098 started with the following argument list:
13100 filter-name [-c] -wwidth -llength -iindent -n login -h host acct-file
13106 appears if the job is submitted with lpr -l
13110 is the value from the pw (page width) capability
13111 specified in /etc/printcap, default 132
13115 is the value from the pl (page length) capability,
13120 is the amount of the indentation from lpr -i, default 0
13124 is the account name of the user printing the file
13128 is the host name from which the job was submitted
13132 is the name of the accounting file from the af
13135 * A conversion filter converts a specific file format into one the
13136 printer can render onto paper. For example, ditroff typesetting data
13137 cannot be directly printed, but you can install a conversion filter
13138 for ditroff files to convert the ditroff data into a form the printer
13139 can digest and print. Section Conversion Filters tells all about them.
13140 Conversion filters also need to do accounting, if you need printer
13141 accounting. Conversion filters are started with the following
13144 filter-name -xpixel-width -ypixel-height -n login -h host acct-file
13146 where pixel-width is the value from the px capability (default 0) and
13147 pixel-height is the value from the py capability (default 0).
13148 * The output filter is used only if there is no text filter, or if
13149 header pages are enabled. In my experience, output filters are rarely
13150 used. Section Output Filters describe them. There are only two
13151 arguments to an output filter:
13153 filter-name -wwidth -llength
13155 which are identical to the text filters -w and -l arguments.
13157 Filters should also exit with the following exit status:
13161 If the filter printed the file successfully.
13165 If the filter failed to print the file but wants LPD to try to
13166 print the file again. LPD will restart a filter if it exits with
13171 If the filter failed to print the file and does not want LPD to
13172 try again. LPD will throw out the file.
13174 The text filter that comes with the DragonFly release,
13175 /usr/libexec/lpr/lpf, takes advantage of the page width and length
13176 arguments to determine when to send a form feed and how to account for
13177 printer usage. It uses the login, host, and accounting file arguments to
13178 make the accounting entries.
13180 If you are shopping for filters, see if they are LPD-compatible. If they
13181 are, they must support the argument lists described above. If you plan on
13182 writing filters for general use, then have them support the same argument
13183 lists and exit codes.
13185 ----------------------------------------------------------------------
13187 11.4.1.2 Accommodating Plain Text Jobs on PostScript(R) Printers
13189 If you are the only user of your computer and PostScript (or other
13190 language-based) printer, and you promise to never send plain text to your
13191 printer and to never use features of various programs that will want to
13192 send plain text to your printer, then you do not need to worry about this
13195 But, if you would like to send both PostScript and plain text jobs to the
13196 printer, then you are urged to augment your printer setup. To do so, we
13197 have the text filter detect if the arriving job is plain text or
13198 PostScript. All PostScript jobs must start with %! (for other printer
13199 languages, see your printer documentation). If those are the first two
13200 characters in the job, we have PostScript, and can pass the rest of the
13201 job directly. If those are not the first two characters in the file, then
13202 the filter will convert the text into PostScript and print the result.
13206 ----------------------------------------------------------------------
13208 11.4.1.3 Simulating PostScript on Non PostScript Printers
13210 PostScript is the de facto standard for high quality typesetting and
13211 printing. PostScript is, however, an expensive standard. Thankfully,
13212 Aladdin Enterprises has a free PostScript work-alike called Ghostscript
13213 that runs with DragonFly. Ghostscript can read most PostScript files and
13214 can render their pages onto a variety of devices, including many brands of
13215 non-PostScript printers. By installing Ghostscript and using a special
13216 text filter for your printer, you can make your non PostScript printer act
13217 like a real PostScript printer.
13219 Ghostscript is in pkgsrc, if you would like to install it from there. You
13220 can fetch, build, and install it quite easily yourself, as well.
13222 To simulate PostScript, we have the text filter detect if it is printing a
13223 PostScript file. If it is not, then the filter will pass the file directly
13224 to the printer; otherwise, it will use Ghostscript to first convert the
13225 file into a format the printer will understand.
13227 Here is an example: the following script is a text filter for Hewlett
13228 Packard DeskJet 500 printers. For other printers, substitute the -sDEVICE
13229 argument to the gs (Ghostscript) command. (Type gs -h to get a list of
13230 devices the current installation of Ghostscript supports.)
13234 # ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
13235 # Installed in /usr/local/libexec/ifhp
13238 # Treat LF as CR+LF:
13240 printf "\033&k2G" || exit 2
13243 # Read first two characters of the file
13245 IFS="" read -r first_line
13246 first_two_chars=`expr "$first_line" : '\(..\)'`
13248 if [ "$first_two_chars" = "%!" ]; then
13250 # It is PostScript; use Ghostscript to scan-convert and print it.
13252 # Note that PostScript files are actually interpreted programs,
13253 # and those programs are allowed to write to stdout, which will
13254 # mess up the printed output. So, we redirect stdout to stderr
13255 # and then make descriptor 3 go to stdout, and have Ghostscript
13256 # write its output there. Exercise for the clever reader:
13257 # capture the stderr output from Ghostscript and mail it back to
13258 # the user originating the print job.
13261 /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
13262 -sOutputFile=/dev/fd/3 - && exit 0
13265 # Plain text or HP/PCL, so just print it directly; print a form feed
13266 # at the end to eject the last page.
13268 echo "$first_line" && cat && printf "\033&l0H" &&
13274 Finally, you need to notify LPD of the filter via the if capability:
13276 :if=/usr/local/libexec/ifhp:
13278 That is it. You can type lpr plain.text and lpr whatever.ps and both
13279 should print successfully.
13281 ----------------------------------------------------------------------
13283 11.4.1.4 Conversion Filters
13285 After completing the simple setup described in Simple Printer Setup, the
13286 first thing you will probably want to do is install conversion filters for
13287 your favorite file formats (besides plain ASCII text).
13289 ----------------------------------------------------------------------
13291 11.4.1.4.1 Why Install Conversion Filters?
13293 Conversion filters make printing various kinds of files easy. As an
13294 example, suppose we do a lot of work with the TeX typesetting system, and
13295 we have a PostScript printer. Every time we generate a DVI file from TeX,
13296 we cannot print it directly until we convert the DVI file into PostScript.
13297 The command sequence goes like this:
13299 % dvips seaweed-analysis.dvi
13300 % lpr seaweed-analysis.ps
13302 By installing a conversion filter for DVI files, we can skip the hand
13303 conversion step each time by having LPD do it for us. Now, each time we
13304 get a DVI file, we are just one step away from printing it:
13306 % lpr -d seaweed-analysis.dvi
13308 We got LPD to do the DVI file conversion for us by specifying the -d
13309 option. Section Formatting and Conversion Options lists the conversion
13312 For each of the conversion options you want a printer to support, install
13313 a conversion filter and specify its pathname in /etc/printcap. A
13314 conversion filter is like the text filter for the simple printer setup
13315 (see section Installing the Text Filter) except that instead of printing
13316 plain text, the filter converts the file into a format the printer can
13319 ----------------------------------------------------------------------
13321 11.4.1.4.2 Which Conversions Filters Should I Install?
13323 You should install the conversion filters you expect to use. If you print
13324 a lot of DVI data, then a DVI conversion filter is in order. If you have
13325 got plenty of troff to print out, then you probably want a troff filter.
13327 The following table summarizes the filters that LPD works with, their
13328 capability entries for the /etc/printcap file, and how to invoke them with
13331 File type /etc/printcap capability lpr option
13339 plain text if none, -p, or -l
13341 In our example, using lpr -d means the printer needs a df capability in
13342 its entry in /etc/printcap.
13344 Despite what others might contend, formats like FORTRAN text and plot are
13345 probably obsolete. At your site, you can give new meanings to these or any
13346 of the formatting options just by installing custom filters. For example,
13347 suppose you would like to directly print Printerleaf files (files from the
13348 Interleaf desktop publishing program), but will never print plot files.
13349 You could install a Printerleaf conversion filter under the gf capability
13350 and then educate your users that lpr -g mean ``print Printerleaf files.''
13352 ----------------------------------------------------------------------
13354 11.4.1.4.3 Installing Conversion Filters
13356 Since conversion filters are programs you install outside of the base
13357 DragonFly installation, they should probably go under /usr/local. The
13358 directory /usr/local/libexec is a popular location, since they are
13359 specialized programs that only LPD will run; regular users should not ever
13362 To enable a conversion filter, specify its pathname under the appropriate
13363 capability for the destination printer in /etc/printcap.
13365 In our example, we will add the DVI conversion filter to the entry for the
13366 printer named bamboo. Here is the example /etc/printcap file again, with
13367 the new df capability for the printer bamboo.
13370 # /etc/printcap for host rose - added df filter for bamboo
13372 rattan|line|diablo|lp|Diablo 630 Line Printer:\
13373 :sh:sd=/var/spool/lpd/rattan:\
13375 :if=/usr/local/libexec/if-simple:
13377 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
13378 :sh:sd=/var/spool/lpd/bamboo:\
13379 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
13380 :if=/usr/local/libexec/psif:\
13381 :df=/usr/local/libexec/psdf:
13383 The DVI filter is a shell script named /usr/local/libexec/psdf. Here is
13388 # psdf - DVI to PostScript printer filter
13389 # Installed in /usr/local/libexec/psdf
13391 # Invoked by lpd when user runs lpr -d
13393 exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"
13395 This script runs dvips in filter mode (the -f argument) on standard input,
13396 which is the job to print. It then starts the PostScript printer filter
13397 lprps (see section Accommodating Plain Text Jobs on PostScript Printers)
13398 with the arguments LPD passed to this script. lprps will use those
13399 arguments to account for the pages printed.
13401 ----------------------------------------------------------------------
13403 11.4.1.4.4 More Conversion Filter Examples
13405 Since there is no fixed set of steps to install conversion filters, let me
13406 instead provide more examples. Use these as guidance to making your own
13407 filters. Use them directly, if appropriate.
13409 This example script is a raster (well, GIF file, actually) conversion
13410 filter for a Hewlett Packard LaserJet III-Si printer:
13414 # hpvf - Convert GIF files into HP/PCL, then print
13415 # Installed in /usr/local/libexec/hpvf
13417 PATH=/usr/X11R6/bin:$PATH; export PATH
13418 giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \
13422 It works by converting the GIF file into a portable anymap, converting
13423 that into a portable graymap, converting that into a portable bitmap, and
13424 converting that into LaserJet/PCL-compatible data.
13426 Here is the /etc/printcap file with an entry for a printer using the above
13430 # /etc/printcap for host orchid
13432 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
13433 :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
13434 :if=/usr/local/libexec/hpif:\
13435 :vf=/usr/local/libexec/hpvf:
13437 The following script is a conversion filter for troff data from the groff
13438 typesetting system for the PostScript printer named bamboo:
13442 # pstf - Convert groff's troff data into PS, then print.
13443 # Installed in /usr/local/libexec/pstf
13445 exec grops | /usr/local/libexec/lprps "$@"
13447 The above script makes use of lprps again to handle the communication with
13448 the printer. If the printer were on a parallel port, we would use this
13453 # pstf - Convert groff's troff data into PS, then print.
13454 # Installed in /usr/local/libexec/pstf
13458 That is it. Here is the entry we need to add to /etc/printcap to enable
13461 :tf=/usr/local/libexec/pstf:
13463 Here is an example that might make old hands at FORTRAN blush. It is a
13464 FORTRAN-text filter for any printer that can directly print plain text. We
13465 will install it for the printer teak:
13469 # hprf - FORTRAN text filter for LaserJet 3si:
13470 # Installed in /usr/local/libexec/hprf
13473 printf "\033&k2G" && fpr && printf "\033&l0H" &&
13477 And we will add this line to the /etc/printcap for the printer teak to
13478 enable this filter:
13480 :rf=/usr/local/libexec/hprf:
13482 ----------------------------------------------------------------------
13484 11.4.1.4.5 Automated Conversion: an Alternative to Conversion Filters
13486 All these conversion filters accomplish a lot for your printing
13487 environment, but at the cost forcing the user to specify (on the lpr(1)
13488 command line) which one to use. If your users are not particularly
13489 computer literate, having to specify a filter option will become annoying.
13490 What is worse, though, is that an incorrectly specified filter option may
13491 run a filter on the wrong type of file and cause your printer to spew out
13492 hundreds of sheets of paper.
13494 Rather than install conversion filters at all, you might want to try
13495 having the text filter (since it is the default filter) detect the type of
13496 file it has been asked to print and then automatically run the right
13497 conversion filter. Tools such as file can be of help here. Of course, it
13498 will be hard to determine the differences between some file types--and, of
13499 course, you can still provide conversion filters just for them.
13501 The pkgsrc collection has a text filter that performs automatic conversion
13502 called apsfilter. It can detect plain text, PostScript, and DVI files, run
13503 the proper conversions, and print.
13505 ----------------------------------------------------------------------
13507 11.4.1.5 Output Filters
13509 The LPD spooling system supports one other type of filter that we have not
13510 yet explored: an output filter. An output filter is intended for printing
13511 plain text only, like the text filter, but with many simplifications. If
13512 you are using an output filter but no text filter, then:
13514 * LPD starts an output filter once for the entire job instead of once
13515 for each file in the job.
13517 * LPD does not make any provision to identify the start or the end of
13518 files within the job for the output filter.
13520 * LPD does not pass the user's login or host to the filter, so it is not
13521 intended to do accounting. In fact, it gets only two arguments:
13523 filter-name -wwidth -llength
13525 Where width is from the pw capability and length is from the pl
13526 capability for the printer in question.
13528 Do not be seduced by an output filter's simplicity. If you would like each
13529 file in a job to start on a different page an output filter will not work.
13530 Use a text filter (also known as an input filter); see section Installing
13531 the Text Filter. Furthermore, an output filter is actually more complex in
13532 that it has to examine the byte stream being sent to it for special flag
13533 characters and must send signals to itself on behalf of LPD.
13535 However, an output filter is necessary if you want header pages and need
13536 to send escape sequences or other initialization strings to be able to
13537 print the header page. (But it is also futile if you want to charge header
13538 pages to the requesting user's account, since LPD does not give any user
13539 or host information to the output filter.)
13541 On a single printer, LPD allows both an output filter and text or other
13542 filters. In such cases, LPD will start the output filter to print the
13543 header page (see section Header Pages) only. LPD then expects the output
13544 filter to stop itself by sending two bytes to the filter: ASCII 031
13545 followed by ASCII 001. When an output filter sees these two bytes (031,
13546 001), it should stop by sending SIGSTOP to itself. When LPD's done running
13547 other filters, it will restart the output filter by sending SIGCONT to it.
13549 If there is an output filter but no text filter and LPD is working on a
13550 plain text job, LPD uses the output filter to do the job. As stated
13551 before, the output filter will print each file of the job in sequence with
13552 no intervening form feeds or other paper advancement, and this is probably
13553 not what you want. In almost all cases, you need a text filter.
13555 The program lpf, which we introduced earlier as a text filter, can also
13556 run as an output filter. If you need a quick-and-dirty output filter but
13557 do not want to write the byte detection and signal sending code, try lpf.
13558 You can also wrap lpf in a shell script to handle any initialization codes
13559 the printer might require.
13561 ----------------------------------------------------------------------
13563 11.4.1.6 lpf: a Text Filter
13565 The program /usr/libexec/lpr/lpf that comes with DragonFly is a text
13566 filter (input filter) that can indent output (job submitted with lpr -i),
13567 allow literal characters to pass (job submitted with lpr -l), adjust the
13568 printing position for backspaces and tabs in the job, and account for
13569 pages printed. It can also act like an output filter.
13571 lpf is suitable for many printing environments. And although it has no
13572 capability to send initialization sequences to a printer, it is easy to
13573 write a shell script to do the needed initialization and then execute lpf.
13575 In order for lpf to do page accounting correctly, it needs correct values
13576 filled in for the pw and pl capabilities in the /etc/printcap file. It
13577 uses these values to determine how much text can fit on a page and how
13578 many pages were in a user's job. For more information on printer
13579 accounting, see Accounting for Printer Usage.
13581 ----------------------------------------------------------------------
13583 11.4.2 Header Pages
13585 If you have lots of users, all of them using various printers, then you
13586 probably want to consider header pages as a necessary evil.
13588 Header pages, also known as banner or burst pages identify to whom jobs
13589 belong after they are printed. They are usually printed in large, bold
13590 letters, perhaps with decorative borders, so that in a stack of printouts
13591 they stand out from the real documents that comprise users' jobs. They
13592 enable users to locate their jobs quickly. The obvious drawback to a
13593 header page is that it is yet one more sheet that has to be printed for
13594 every job, their ephemeral usefulness lasting not more than a few minutes,
13595 ultimately finding themselves in a recycling bin or rubbish heap. (Note
13596 that header pages go with each job, not each file in a job, so the paper
13597 waste might not be that bad.)
13599 The LPD system can provide header pages automatically for your printouts
13600 if your printer can directly print plain text. If you have a PostScript
13601 printer, you will need an external program to generate the header page;
13602 see Header Pages on PostScript Printers.
13604 ----------------------------------------------------------------------
13606 11.4.2.1 Enabling Header Pages
13608 In the Simple Printer Setup section, we turned off header pages by
13609 specifying sh (meaning ``suppress header'') in the /etc/printcap file. To
13610 enable header pages for a printer, just remove the sh capability.
13612 Sounds too easy, right?
13614 You are right. You might have to provide an output filter to send
13615 initialization strings to the printer. Here is an example output filter
13616 for Hewlett Packard PCL-compatible printers:
13620 # hpof - Output filter for Hewlett Packard PCL-compatible printers
13621 # Installed in /usr/local/libexec/hpof
13623 printf "\033&k2G" || exit 2
13624 exec /usr/libexec/lpr/lpf
13626 Specify the path to the output filter in the of capability. See the Output
13627 Filters section for more information.
13629 Here is an example /etc/printcap file for the printer teak that we
13630 introduced earlier; we enabled header pages and added the above output
13634 # /etc/printcap for host orchid
13636 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
13637 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
13638 :if=/usr/local/libexec/hpif:\
13639 :vf=/usr/local/libexec/hpvf:\
13640 :of=/usr/local/libexec/hpof:
13642 Now, when users print jobs to teak, they get a header page with each job.
13643 If users want to spend time searching for their printouts, they can
13644 suppress header pages by submitting the job with lpr -h; see the Header
13645 Page Options section for more lpr(1) options.
13647 Note: LPD prints a form feed character after the header page. If your
13648 printer uses a different character or sequence of characters to eject a
13649 page, specify them with the ff capability in /etc/printcap.
13651 ----------------------------------------------------------------------
13653 11.4.2.2 Controlling Header Pages
13655 By enabling header pages, LPD will produce a long header, a full page of
13656 large letters identifying the user, host, and job. Here is an example
13657 (kelly printed the job named outline from host rose):
13667 k k eeee lll lll yyy y
13676 oooo u u ttttt l ii n nnn eeee
13677 o o u u t l i nn n e e
13678 o o u u t l i n n eeeeee
13679 o o u u t l i n n e
13680 o o u uu t t l i n n e e
13681 oooo uuu u tt lll iii n n eeee
13691 r rrr oooo ssss eeee
13705 Date: Sun Sep 17 11:04:58 1995
13707 LPD appends a form feed after this text so the job starts on a new page
13708 (unless you have sf (suppress form feeds) in the destination printer's
13709 entry in /etc/printcap).
13711 If you prefer, LPD can make a short header; specify sb (short banner) in
13712 the /etc/printcap file. The header page will look like this:
13714 rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995
13716 Also by default, LPD prints the header page first, then the job. To
13717 reverse that, specify hl (header last) in /etc/printcap.
13719 ----------------------------------------------------------------------
13721 11.4.2.3 Accounting for Header Pages
13723 Using LPD's built-in header pages enforces a particular paradigm when it
13724 comes to printer accounting: header pages must be free of charge.
13728 Because the output filter is the only external program that will have
13729 control when the header page is printed that could do accounting, and it
13730 is not provided with any user or host information or an accounting file,
13731 so it has no idea whom to charge for printer use. It is also not enough to
13732 just ``add one page'' to the text filter or any of the conversion filters
13733 (which do have user and host information) since users can suppress header
13734 pages with lpr -h. They could still be charged for header pages they did
13735 not print. Basically, lpr -h will be the preferred option of
13736 environmentally-minded users, but you cannot offer any incentive to use
13739 It is still not enough to have each of the filters generate their own
13740 header pages (thereby being able to charge for them). If users wanted the
13741 option of suppressing the header pages with lpr -h, they will still get
13742 them and be charged for them since LPD does not pass any knowledge of the
13743 -h option to any of the filters.
13745 So, what are your options?
13749 * Accept LPD's paradigm and make header pages free.
13751 * Install an alternative to LPD, such as LPRng. Section Alternatives to
13752 the Standard Spooler tells more about other spooling software you can
13753 substitute for LPD.
13755 * Write a smart output filter. Normally, an output filter is not meant
13756 to do anything more than initialize a printer or do some simple
13757 character conversion. It is suited for header pages and plain text
13758 jobs (when there is no text (input) filter). But, if there is a text
13759 filter for the plain text jobs, then LPD will start the output filter
13760 only for the header pages. And the output filter can parse the header
13761 page text that LPD generates to determine what user and host to charge
13762 for the header page. The only other problem with this method is that
13763 the output filter still does not know what accounting file to use (it
13764 is not passed the name of the file from the af capability), but if you
13765 have a well-known accounting file, you can hard-code that into the
13766 output filter. To facilitate the parsing step, use the sh (short
13767 header) capability in /etc/printcap. Then again, all that might be too
13768 much trouble, and users will certainly appreciate the more generous
13769 system administrator who makes header pages free.
13771 ----------------------------------------------------------------------
13773 11.4.2.4 Header Pages on PostScript Printers
13775 As described above, LPD can generate a plain text header page suitable for
13776 many printers. Of course, PostScript cannot directly print plain text, so
13777 the header page feature of LPD is useless--or mostly so.
13779 One obvious way to get header pages is to have every conversion filter and
13780 the text filter generate the header page. The filters should use the user
13781 and host arguments to generate a suitable header page. The drawback of
13782 this method is that users will always get a header page, even if they
13783 submit jobs with lpr -h.
13785 Let us explore this method. The following script takes three arguments
13786 (user login name, host name, and job name) and makes a simple PostScript
13791 # make-ps-header - make a PostScript header page on stdout
13792 # Installed in /usr/local/libexec/make-ps-header
13796 # These are PostScript units (72 to the inch). Modify for A4 or
13797 # whatever size paper you are using:
13806 if [ $# -ne 3 ]; then
13807 echo "Usage: `basename $0` <user> <host> <job>" 1>&2
13812 # Save these, mostly for readability in the PostScript, below.
13820 # Send the PostScript code to stdout.
13826 % Make sure we do not interfere with user's job that will follow
13831 % Make a thick, unpleasant border around the edge of the paper.
13833 $border $border moveto
13834 $page_width $border 2 mul sub 0 rlineto
13835 0 $page_height $border 2 mul sub rlineto
13836 currentscreen 3 -1 roll pop 100 3 1 roll setscreen
13837 $border 2 mul $page_width sub 0 rlineto closepath
13838 0.8 setgray 10 setlinewidth stroke 0 setgray
13841 % Display user's login name, nice and large and prominent
13843 /Helvetica-Bold findfont 64 scalefont setfont
13844 $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
13848 % Now show the boring particulars
13850 /Helvetica findfont 14 scalefont setfont
13852 [ (Job:) (Host:) (Date:) ] {
13853 200 y moveto show /y y 18 sub def }
13856 /Helvetica-Bold findfont 14 scalefont setfont
13858 [ ($job) ($host) ($date) ] {
13859 270 y moveto show /y y 18 sub def
13869 Now, each of the conversion filters and the text filter can call this
13870 script to first generate the header page, and then print the user's job.
13871 Here is the DVI conversion filter from earlier in this document, modified
13872 to make a header page:
13876 # psdf - DVI to PostScript printer filter
13877 # Installed in /usr/local/libexec/psdf
13879 # Invoked by lpd when user runs lpr -d
13889 while getopts "x:y:n:h:" option; do
13892 n) login=$OPTARG ;;
13894 *) echo "LPD started `basename $0` wrong." 1>&2
13900 [ "$login" ] || fail "No login name"
13901 [ "$host" ] || fail "No host name"
13903 ( /usr/local/libexec/make-ps-header $login $host "DVI File"
13904 /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args
13906 Notice how the filter has to parse the argument list in order to determine
13907 the user and host name. The parsing for the other conversion filters is
13908 identical. The text filter takes a slightly different set of arguments,
13909 though (see section How Filters Work).
13911 As we have mentioned before, the above scheme, though fairly simple,
13912 disables the ``suppress header page'' option (the -h option) to lpr. If
13913 users wanted to save a tree (or a few pennies, if you charge for header
13914 pages), they would not be able to do so, since every filter's going to
13915 print a header page with every job.
13917 To allow users to shut off header pages on a per-job basis, you will need
13918 to use the trick introduced in section Accounting for Header Pages: write
13919 an output filter that parses the LPD-generated header page and produces a
13920 PostScript version. If the user submits the job with lpr -h, then LPD will
13921 not generate a header page, and neither will your output filter.
13922 Otherwise, your output filter will read the text from LPD and send the
13923 appropriate header page PostScript code to the printer.
13925 If you have a PostScript printer on a serial line, you can make use of
13926 lprps, which comes with an output filter, psof, which does the above. Note
13927 that psof does not charge for header pages.
13929 ----------------------------------------------------------------------
13931 11.4.3 Networked Printing
13933 DragonFly supports networked printing: sending jobs to remote printers.
13934 Networked printing generally refers to two different things:
13936 * Accessing a printer attached to a remote host. You install a printer
13937 that has a conventional serial or parallel interface on one host.
13938 Then, you set up LPD to enable access to the printer from other hosts
13939 on the network. Section Printers Installed on Remote Hosts tells how
13942 * Accessing a printer attached directly to a network. The printer has a
13943 network interface in addition (or in place of) a more conventional
13944 serial or parallel interface. Such a printer might work as follows:
13946 * It might understand the LPD protocol and can even queue jobs from
13947 remote hosts. In this case, it acts just like a regular host
13948 running LPD. Follow the same procedure in section Printers
13949 Installed on Remote Hosts to set up such a printer.
13951 * It might support a data stream network connection. In this case,
13952 you ``attach'' the printer to one host on the network by making
13953 that host responsible for spooling jobs and sending them to the
13954 printer. Section Printers with Networked Data Stream Interfaces
13955 gives some suggestions on installing such printers.
13957 ----------------------------------------------------------------------
13959 11.4.3.1 Printers Installed on Remote Hosts
13961 The LPD spooling system has built-in support for sending jobs to other
13962 hosts also running LPD (or are compatible with LPD). This feature enables
13963 you to install a printer on one host and make it accessible from other
13964 hosts. It also works with printers that have network interfaces that
13965 understand the LPD protocol.
13967 To enable this kind of remote printing, first install a printer on one
13968 host, the printer host, using the simple printer setup described in the
13969 Simple Printer Setup section. Do any advanced setup in Advanced Printer
13970 Setup that you need. Make sure to test the printer and see if it works
13971 with the features of LPD you have enabled. Also ensure that the local host
13972 has authorization to use the LPD service in the remote host (see
13973 Restricting Jobs from Remote Printers).
13975 If you are using a printer with a network interface that is compatible
13976 with LPD, then the printer host in the discussion below is the printer
13977 itself, and the printer name is the name you configured for the printer.
13978 See the documentation that accompanied your printer and/or printer-network
13981 Tip: If you are using a Hewlett Packard Laserjet then the printer name
13982 text will automatically perform the LF to CRLF conversion for you, so
13983 you will not require the hpif script.
13985 Then, on the other hosts you want to have access to the printer, make an
13986 entry in their /etc/printcap files with the following:
13988 1. Name the entry anything you want. For simplicity, though, you probably
13989 want to use the same name and aliases as on the printer host.
13991 2. Leave the lp capability blank, explicitly (:lp=:).
13993 3. Make a spooling directory and specify its location in the sd
13994 capability. LPD will store jobs here before they get sent to the
13997 4. Place the name of the printer host in the rm capability.
13999 5. Place the printer name on the printer host in the rp capability.
14001 That is it. You do not need to list conversion filters, page dimensions,
14002 or anything else in the /etc/printcap file.
14004 Here is an example. The host rose has two printers, bamboo and rattan. We
14005 will enable users on the host orchid to print to those printers. Here is
14006 the /etc/printcap file for orchid (back from section Enabling Header
14007 Pages). It already had the entry for the printer teak; we have added
14008 entries for the two printers on the host rose:
14011 # /etc/printcap for host orchid - added (remote) printers on rose
14015 # teak is local; it is connected directly to orchid:
14017 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
14018 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
14019 :if=/usr/local/libexec/ifhp:\
14020 :vf=/usr/local/libexec/vfhp:\
14021 :of=/usr/local/libexec/ofhp:
14024 # rattan is connected to rose; send jobs for rattan to rose:
14026 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14027 :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
14030 # bamboo is connected to rose as well:
14032 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14033 :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:
14035 Then, we just need to make spooling directories on orchid:
14037 # mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo
14038 # chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo
14039 # chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo
14041 Now, users on orchid can print to rattan and bamboo. If, for example, a
14042 user on orchid typed
14044 % lpr -P bamboo -d sushi-review.dvi
14046 the LPD system on orchid would copy the job to the spooling directory
14047 /var/spool/lpd/bamboo and note that it was a DVI job. As soon as the host
14048 rose has room in its bamboo spooling directory, the two LPDs would
14049 transfer the file to rose. The file would wait in rose's queue until it
14050 was finally printed. It would be converted from DVI to PostScript (since
14051 bamboo is a PostScript printer) on rose.
14053 ----------------------------------------------------------------------
14055 11.4.3.2 Printers with Networked Data Stream Interfaces
14057 Often, when you buy a network interface card for a printer, you can get
14058 two versions: one which emulates a spooler (the more expensive version),
14059 or one which just lets you send data to it as if you were using a serial
14060 or parallel port (the cheaper version). This section tells how to use the
14061 cheaper version. For the more expensive one, see the previous section
14062 Printers Installed on Remote Hosts.
14064 The format of the /etc/printcap file lets you specify what serial or
14065 parallel interface to use, and (if you are using a serial interface), what
14066 baud rate, whether to use flow control, delays for tabs, conversion of
14067 newlines, and more. But there is no way to specify a connection to a
14068 printer that is listening on a TCP/IP or other network port.
14070 To send data to a networked printer, you need to develop a communications
14071 program that can be called by the text and conversion filters. Here is one
14072 such example: the script netprint takes all data on standard input and
14073 sends it to a network-attached printer. We specify the hostname of the
14074 printer as the first argument and the port number to which to connect as
14075 the second argument to netprint. Note that this supports one-way
14076 communication only (DragonFly to printer); many network printers support
14077 two-way communication, and you might want to take advantage of that (to
14078 get printer status, perform accounting, etc.).
14082 # netprint - Text filter for printer attached to network
14083 # Installed in /usr/local/libexec/netprint
14085 $#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>";
14087 $printer_host = $ARGV[0];
14088 $printer_port = $ARGV[1];
14090 require 'sys/socket.ph';
14092 ($ignore, $ignore, $protocol) = getprotobyname('tcp');
14093 ($ignore, $ignore, $ignore, $ignore, $address)
14094 = gethostbyname($printer_host);
14096 $sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);
14098 socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
14099 || die "Can't create TCP/IP stream socket: $!";
14100 connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
14101 while (<STDIN>) { print PRINTER; }
14104 We can then use this script in various filters. Suppose we had a Diablo
14105 750-N line printer connected to the network. The printer accepts data to
14106 print on port number 5100. The host name of the printer is scrivener. Here
14107 is the text filter for the printer:
14111 # diablo-if-net - Text filter for Diablo printer `scrivener' listening
14112 # on port 5100. Installed in /usr/local/libexec/diablo-if-net
14114 exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100
14116 ----------------------------------------------------------------------
14118 11.4.4 Restricting Printer Usage
14120 This section gives information on restricting printer usage. The LPD
14121 system lets you control who can access a printer, both locally or
14122 remotely, whether they can print multiple copies, how large their jobs can
14123 be, and how large the printer queues can get.
14125 ----------------------------------------------------------------------
14127 11.4.4.1 Restricting Multiple Copies
14129 The LPD system makes it easy for users to print multiple copies of a file.
14130 Users can print jobs with lpr -#5 (for example) and get five copies of
14131 each file in the job. Whether this is a good thing is up to you.
14133 If you feel multiple copies cause unnecessary wear and tear on your
14134 printers, you can disable the -# option to lpr(1) by adding the sc
14135 capability to the /etc/printcap file. When users submit jobs with the -#
14136 option, they will see:
14138 lpr: multiple copies are not allowed
14140 Note that if you have set up access to a printer remotely (see section
14141 Printers Installed on Remote Hosts), you need the sc capability on the
14142 remote /etc/printcap files as well, or else users will still be able to
14143 submit multiple-copy jobs by using another host.
14145 Here is an example. This is the /etc/printcap file for the host rose. The
14146 printer rattan is quite hearty, so we will allow multiple copies, but the
14147 laser printer bamboo is a bit more delicate, so we will disable multiple
14148 copies by adding the sc capability:
14151 # /etc/printcap for host rose - restrict multiple copies on bamboo
14153 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14154 :sh:sd=/var/spool/lpd/rattan:\
14156 :if=/usr/local/libexec/if-simple:
14158 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14159 :sh:sd=/var/spool/lpd/bamboo:sc:\
14160 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14161 :if=/usr/local/libexec/psif:\
14162 :df=/usr/local/libexec/psdf:
14164 Now, we also need to add the sc capability on the host orchid's
14165 /etc/printcap (and while we are at it, let us disable multiple copies for
14169 # /etc/printcap for host orchid - no multiple copies for local
14170 # printer teak or remote printer bamboo
14171 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
14172 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\
14173 :if=/usr/local/libexec/ifhp:\
14174 :vf=/usr/local/libexec/vfhp:\
14175 :of=/usr/local/libexec/ofhp:
14177 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14178 :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
14180 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14181 :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:
14183 By using the sc capability, we prevent the use of lpr -#, but that still
14184 does not prevent users from running lpr(1) multiple times, or from
14185 submitting the same file multiple times in one job like this:
14187 % lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign
14189 There are many ways to prevent this abuse (including ignoring it) which
14190 you are free to explore.
14192 ----------------------------------------------------------------------
14194 11.4.4.2 Restricting Access to Printers
14196 You can control who can print to what printers by using the UNIX group
14197 mechanism and the rg capability in /etc/printcap. Just place the users you
14198 want to have access to a printer in a certain group, and then name that
14199 group in the rg capability.
14201 Users outside the group (including root) will be greeted with ``lpr: Not a
14202 member of the restricted group'' if they try to print to the controlled
14205 As with the sc (suppress multiple copies) capability, you need to specify
14206 rg on remote hosts that also have access to your printers, if you feel it
14207 is appropriate (see section Printers Installed on Remote Hosts).
14209 For example, we will let anyone access the printer rattan, but only those
14210 in group artists can use bamboo. Here is the familiar /etc/printcap for
14214 # /etc/printcap for host rose - restricted group for bamboo
14216 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14217 :sh:sd=/var/spool/lpd/rattan:\
14219 :if=/usr/local/libexec/if-simple:
14221 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14222 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\
14223 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14224 :if=/usr/local/libexec/psif:\
14225 :df=/usr/local/libexec/psdf:
14227 Let us leave the other example /etc/printcap file (for the host orchid)
14228 alone. Of course, anyone on orchid can print to bamboo. It might be the
14229 case that we only allow certain logins on orchid anyway, and want them to
14230 have access to the printer. Or not.
14232 Note: There can be only one restricted group per printer.
14234 ----------------------------------------------------------------------
14236 11.4.4.3 Controlling Sizes of Jobs Submitted
14238 If you have many users accessing the printers, you probably need to put an
14239 upper limit on the sizes of the files users can submit to print. After
14240 all, there is only so much free space on the filesystem that houses the
14241 spooling directories, and you also need to make sure there is room for the
14242 jobs of other users.
14244 LPD enables you to limit the maximum byte size a file in a job can be with
14245 the mx capability. The units are in BUFSIZ blocks, which are 1024 bytes.
14246 If you put a zero for this capability, there will be no limit on file
14247 size; however, if no mx capability is specified, then a default limit of
14248 1000 blocks will be used.
14250 Note: The limit applies to files in a job, and not the total job size.
14252 LPD will not refuse a file that is larger than the limit you place on a
14253 printer. Instead, it will queue as much of the file up to the limit, which
14254 will then get printed. The rest will be discarded. Whether this is correct
14255 behavior is up for debate.
14257 Let us add limits to our example printers rattan and bamboo. Since those
14258 artists' PostScript files tend to be large, we will limit them to five
14259 megabytes. We will put no limit on the plain text line printer:
14262 # /etc/printcap for host rose
14266 # No limit on job size:
14268 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14269 :sh:mx#0:sd=/var/spool/lpd/rattan:\
14271 :if=/usr/local/libexec/if-simple:
14274 # Limit of five megabytes:
14276 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14277 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
14278 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14279 :if=/usr/local/libexec/psif:\
14280 :df=/usr/local/libexec/psdf:
14282 Again, the limits apply to the local users only. If you have set up access
14283 to your printers remotely, remote users will not get those limits. You
14284 will need to specify the mx capability in the remote /etc/printcap files
14285 as well. See section Printers Installed on Remote Hosts for more
14286 information on remote printing.
14288 There is another specialized way to limit job sizes from remote printers;
14289 see section Restricting Jobs from Remote Printers.
14291 ----------------------------------------------------------------------
14293 11.4.4.4 Restricting Jobs from Remote Printers
14295 The LPD spooling system provides several ways to restrict print jobs
14296 submitted from remote hosts:
14300 You can control from which remote hosts a local LPD accepts
14301 requests with the files /etc/hosts.equiv and /etc/hosts.lpd. LPD
14302 checks to see if an incoming request is from a host listed in
14303 either one of these files. If not, LPD refuses the request.
14305 The format of these files is simple: one host name per line. Note
14306 that the file /etc/hosts.equiv is also used by the ruserok(3)
14307 protocol, and affects programs like rsh(1) and rcp(1), so be
14310 For example, here is the /etc/hosts.lpd file on the host rose:
14314 madrigal.fishbaum.de
14316 This means rose will accept requests from the hosts orchid,
14317 violet, and madrigal.fishbaum.de. If any other host tries to
14318 access rose's LPD, the job will be refused.
14322 You can control how much free space there needs to remain on the
14323 filesystem where a spooling directory resides. Make a file called
14324 minfree in the spooling directory for the local printer. Insert in
14325 that file a number representing how many disk blocks (512 bytes)
14326 of free space there has to be for a remote job to be accepted.
14328 This lets you insure that remote users will not fill your
14329 filesystem. You can also use it to give a certain priority to
14330 local users: they will be able to queue jobs long after the free
14331 disk space has fallen below the amount specified in the minfree
14334 For example, let us add a minfree file for the printer bamboo. We
14335 examine /etc/printcap to find the spooling directory for this
14336 printer; here is bamboo's entry:
14338 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14339 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
14340 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\
14341 :if=/usr/local/libexec/psif:\
14342 :df=/usr/local/libexec/psdf:
14344 The spooling directory is given in the sd capability. We will make
14345 three megabytes (which is 6144 disk blocks) the amount of free
14346 disk space that must exist on the filesystem for LPD to accept
14349 # echo 6144 > /var/spool/lpd/bamboo/minfree
14354 You can control which remote users can print to local printers by
14355 specifying the rs capability in /etc/printcap. When rs appears in
14356 the entry for a locally-attached printer, LPD will accept jobs
14357 from remote hosts if the user submitting the job also has an
14358 account of the same login name on the local host. Otherwise, LPD
14361 This capability is particularly useful in an environment where
14362 there are (for example) different departments sharing a network,
14363 and some users transcend departmental boundaries. By giving them
14364 accounts on your systems, they can use your printers from their
14365 own departmental systems. If you would rather allow them to use
14366 only your printers and not your computer resources, you can give
14367 them ``token'' accounts, with no home directory and a useless
14368 shell like /usr/bin/false.
14370 ----------------------------------------------------------------------
14372 11.4.5 Accounting for Printer Usage
14374 So, you need to charge for printouts. And why not? Paper and ink cost
14375 money. And then there are maintenance costs--printers are loaded with
14376 moving parts and tend to break down. You have examined your printers,
14377 usage patterns, and maintenance fees and have come up with a per-page (or
14378 per-foot, per-meter, or per-whatever) cost. Now, how do you actually start
14379 accounting for printouts?
14381 Well, the bad news is the LPD spooling system does not provide much help
14382 in this department. Accounting is highly dependent on the kind of printer
14383 in use, the formats being printed, and your requirements in charging for
14386 To implement accounting, you have to modify a printer's text filter (to
14387 charge for plain text jobs) and the conversion filters (to charge for
14388 other file formats), to count pages or query the printer for pages
14389 printed. You cannot get away with using the simple output filter, since it
14390 cannot do accounting. See section Filters.
14392 Generally, there are two ways to do accounting:
14394 * Periodic accounting is the more common way, possibly because it is
14395 easier. Whenever someone prints a job, the filter logs the user, host,
14396 and number of pages to an accounting file. Every month, semester,
14397 year, or whatever time period you prefer, you collect the accounting
14398 files for the various printers, tally up the pages printed by users,
14399 and charge for usage. Then you truncate all the logging files,
14400 starting with a clean slate for the next period.
14402 * Timely accounting is less common, probably because it is more
14403 difficult. This method has the filters charge users for printouts as
14404 soon as they use the printers. Like disk quotas, the accounting is
14405 immediate. You can prevent users from printing when their account goes
14406 in the red, and might provide a way for users to check and adjust
14407 their ``print quotas.'' But this method requires some database code to
14408 track users and their quotas.
14410 The LPD spooling system supports both methods easily: since you have to
14411 provide the filters (well, most of the time), you also have to provide the
14412 accounting code. But there is a bright side: you have enormous flexibility
14413 in your accounting methods. For example, you choose whether to use
14414 periodic or timely accounting. You choose what information to log: user
14415 names, host names, job types, pages printed, square footage of paper used,
14416 how long the job took to print, and so forth. And you do so by modifying
14417 the filters to save this information.
14419 ----------------------------------------------------------------------
14421 11.4.5.1 Quick and Dirty Printer Accounting
14423 DragonFly comes with two programs that can get you set up with simple
14424 periodic accounting right away. They are the text filter lpf, described in
14425 section lpf: a Text Filter, and pac(8), a program to gather and total
14426 entries from printer accounting files.
14428 As mentioned in the section on filters (Filters), LPD starts the text and
14429 the conversion filters with the name of the accounting file to use on the
14430 filter command line. The filters can use this argument to know where to
14431 write an accounting file entry. The name of this file comes from the af
14432 capability in /etc/printcap, and if not specified as an absolute path, is
14433 relative to the spooling directory.
14435 LPD starts lpf with page width and length arguments (from the pw and pl
14436 capabilities). lpf uses these arguments to determine how much paper will
14437 be used. After sending the file to the printer, it then writes an
14438 accounting entry in the accounting file. The entries look like this:
14446 You should use a separate accounting file for each printer, as lpf has no
14447 file locking logic built into it, and two lpfs might corrupt each other's
14448 entries if they were to write to the same file at the same time. An easy
14449 way to insure a separate accounting file for each printer is to use
14450 af=acct in /etc/printcap. Then, each accounting file will be in the
14451 spooling directory for a printer, in a file named acct.
14453 When you are ready to charge users for printouts, run the pac(8) program.
14454 Just change to the spooling directory for the printer you want to collect
14455 on and type pac. You will get a dollar-centric summary like the following:
14457 Login pages/feet runs price
14458 orchid:kelly 5.00 1 $ 0.10
14459 orchid:mary 31.00 3 $ 0.62
14460 orchid:zhang 9.00 1 $ 0.18
14461 rose:andy 2.00 1 $ 0.04
14462 rose:kelly 177.00 104 $ 3.54
14463 rose:mary 87.00 32 $ 1.74
14464 rose:root 26.00 12 $ 0.52
14466 total 337.00 154 $ 6.74
14468 These are the arguments pac(8) expects:
14472 Which printer to summarize. This option works only if there is an
14473 absolute path in the af capability in /etc/printcap.
14477 Sort the output by cost instead of alphabetically by user name.
14481 Ignore host name in the accounting files. With this option, user
14482 smith on host alpha is the same user smith on host gamma. Without,
14483 they are different users.
14487 Compute charges with price dollars per page or per foot instead of
14488 the price from the pc capability in /etc/printcap, or two cents
14489 (the default). You can specify price as a floating point number.
14493 Reverse the sort order.
14497 Make an accounting summary file and truncate the accounting file.
14501 Print accounting information for the given user names only.
14503 In the default summary that pac(8) produces, you see the number of pages
14504 printed by each user from various hosts. If, at your site, host does not
14505 matter (because users can use any host), run pac -m, to produce the
14508 Login pages/feet runs price
14510 kelly 182.00 105 $ 3.64
14511 mary 118.00 35 $ 2.36
14512 root 26.00 12 $ 0.52
14513 zhang 9.00 1 $ 0.18
14515 total 337.00 154 $ 6.74
14517 To compute the dollar amount due, pac(8) uses the pc capability in the
14518 /etc/printcap file (default of 200, or 2 cents per page). Specify, in
14519 hundredths of cents, the price per page or per foot you want to charge for
14520 printouts in this capability. You can override this value when you run
14521 pac(8) with the -p option. The units for the -p option are in dollars,
14522 though, not hundredths of cents. For example,
14526 makes each page cost one dollar and fifty cents. You can really rake in
14527 the profits by using this option.
14529 Finally, running pac -s will save the summary information in a summary
14530 accounting file, which is named the same as the printer's accounting file,
14531 but with _sum appended to the name. It then truncates the accounting file.
14532 When you run pac(8) again, it rereads the summary file to get starting
14533 totals, then adds information from the regular accounting file.
14535 ----------------------------------------------------------------------
14537 11.4.5.2 How Can You Count Pages Printed?
14539 In order to perform even remotely accurate accounting, you need to be able
14540 to determine how much paper a job uses. This is the essential problem of
14541 printer accounting.
14543 For plain text jobs, the problem is not that hard to solve: you count how
14544 many lines are in a job and compare it to how many lines per page your
14545 printer supports. Do not forget to take into account backspaces in the
14546 file which overprint lines, or long logical lines that wrap onto one or
14547 more additional physical lines.
14549 The text filter lpf (introduced in lpf: a Text Filter) takes into account
14550 these things when it does accounting. If you are writing a text filter
14551 which needs to do accounting, you might want to examine lpf's source code.
14553 How do you handle other file formats, though?
14555 Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you can have
14556 your filter parse the diagnostic output of dvilj or dvips and look to see
14557 how many pages were converted. You might be able to do similar things with
14558 other file formats and conversion programs.
14560 But these methods suffer from the fact that the printer may not actually
14561 print all those pages. For example, it could jam, run out of toner, or
14562 explode--and the user would still get charged.
14564 So, what can you do?
14566 There is only one sure way to do accurate accounting. Get a printer that
14567 can tell you how much paper it uses, and attach it via a serial line or a
14568 network connection. Nearly all PostScript printers support this notion.
14569 Other makes and models do as well (networked Imagen laser printers, for
14570 example). Modify the filters for these printers to get the page usage
14571 after they print each job and have them log accounting information based
14572 on that value only. There is no line counting nor error-prone file
14573 examination required.
14575 Of course, you can always be generous and make all printouts free.
14577 ----------------------------------------------------------------------
14579 11.5 Using Printers
14581 This section tells you how to use printers you have set up with DragonFly.
14582 Here is an overview of the user-level commands:
14590 Check printer queues
14594 Remove jobs from a printer's queue
14596 There is also an administrative command, lpc(8), described in the section
14597 Administering the LPD Spooler, used to control printers and their queues.
14599 All three of the commands lpr(1), lprm(1), and lpq(1) accept an option -P
14600 printer-name to specify on which printer/queue to operate, as listed in
14601 the /etc/printcap file. This enables you to submit, remove, and check on
14602 jobs for various printers. If you do not use the -P option, then these
14603 commands use the printer specified in the PRINTER environment variable.
14604 Finally, if you do not have a PRINTER environment variable, these commands
14605 default to the printer named lp.
14607 Hereafter, the terminology default printer means the printer named in the
14608 PRINTER environment variable, or the printer named lp when there is no
14609 PRINTER environment variable.
14611 ----------------------------------------------------------------------
14613 11.5.1 Printing Jobs
14615 To print files, type:
14619 This prints each of the listed files to the default printer. If you list
14620 no files, lpr(1) reads data to print from standard input. For example,
14621 this command prints some important system files:
14623 % lpr /etc/host.conf /etc/hosts.equiv
14625 To select a specific printer, type:
14627 % lpr -P printer-name filename ...
14629 This example prints a long listing of the current directory to the printer
14632 % ls -l | lpr -P rattan
14634 Because no files were listed for the lpr(1) command, lpr read the data to
14635 print from standard input, which was the output of the ls -l command.
14637 The lpr(1) command can also accept a wide variety of options to control
14638 formatting, apply file conversions, generate multiple copies, and so
14639 forth. For more information, see the section Printing Options.
14641 ----------------------------------------------------------------------
14643 11.5.2 Checking Jobs
14645 When you print with lpr(1), the data you wish to print is put together in
14646 a package called a ``print job'', which is sent to the LPD spooling
14647 system. Each printer has a queue of jobs, and your job waits in that queue
14648 along with other jobs from yourself and from other users. The printer
14649 prints those jobs in a first-come, first-served order.
14651 To display the queue for the default printer, type lpq(1). For a specific
14652 printer, use the -P option. For example, the command
14656 shows the queue for the printer named bamboo. Here is an example of the
14657 output of the lpq command:
14659 bamboo is ready and printing
14660 Rank Owner Job Files Total Size
14661 active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes
14662 2nd kelly 10 (standard input) 1635 bytes
14663 3rd mary 11 ... 78519 bytes
14665 This shows three jobs in the queue for bamboo. The first job, submitted by
14666 user kelly, got assigned ``job number'' 9. Every job for a printer gets a
14667 unique job number. Most of the time you can ignore the job number, but you
14668 will need it if you want to cancel the job; see section Removing Jobs for
14671 Job number nine consists of two files; multiple files given on the lpr(1)
14672 command line are treated as part of a single job. It is the currently
14673 active job (note the word active under the ``Rank'' column), which means
14674 the printer should be currently printing that job. The second job consists
14675 of data passed as the standard input to the lpr(1) command. The third job
14676 came from user mary; it is a much larger job. The pathname of the file she
14677 is trying to print is too long to fit, so the lpq(1) command just shows
14680 The very first line of the output from lpq(1) is also useful: it tells
14681 what the printer is currently doing (or at least what LPD thinks the
14684 The lpq(1) command also support a -l option to generate a detailed long
14685 listing. Here is an example of lpq -l:
14687 waiting for bamboo to become ready (offline ?)
14688 kelly: 1st [job 009rose]
14689 /etc/host.conf 73 bytes
14690 /etc/hosts.equiv 15 bytes
14692 kelly: 2nd [job 010rose]
14693 (standard input) 1635 bytes
14695 mary: 3rd [job 011rose]
14696 /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes
14698 ----------------------------------------------------------------------
14700 11.5.3 Removing Jobs
14702 If you change your mind about printing a job, you can remove the job from
14703 the queue with the lprm(1) command. Often, you can even use lprm(1) to
14704 remove an active job, but some or all of the job might still get printed.
14706 To remove a job from the default printer, first use lpq(1) to find the job
14711 To remove the job from a specific printer, add the -P option. The
14712 following command removes job number 10 from the queue for the printer
14715 % lprm -P bamboo 10
14717 The lprm(1) command has a few shortcuts:
14721 Removes all jobs (for the default printer) belonging to you.
14725 Removes all jobs (for the default printer) belonging to user. The
14726 superuser can remove other users' jobs; you can remove only your
14731 With no job number, user name, or - appearing on the command line,
14732 lprm(1) removes the currently active job on the default printer,
14733 if it belongs to you. The superuser can remove any active job.
14735 Just use the -P option with the above shortcuts to operate on a specific
14736 printer instead of the default. For example, the following command removes
14737 all jobs for the current user in the queue for the printer named rattan:
14741 Note: If you are working in a networked environment, lprm(1) will let
14742 you remove jobs only from the host from which the jobs were submitted,
14743 even if the same printer is available from other hosts. The following
14744 command sequence demonstrates this:
14746 % lpr -P rattan myfile
14749 Rank Owner Job Files Total Size
14750 active seeyan 12 ... 49123 bytes
14751 2nd kelly 13 myfile 12 bytes
14752 % lprm -P rattan 13
14753 rose: Permission denied
14755 % lprm -P rattan 13
14756 dfA013rose dequeued
14757 cfA013rose dequeued
14760 ----------------------------------------------------------------------
14762 11.5.4 Beyond Plain Text: Printing Options
14764 The lpr(1) command supports a number of options that control formatting
14765 text, converting graphic and other file formats, producing multiple
14766 copies, handling of the job, and more. This section describes the options.
14768 ----------------------------------------------------------------------
14770 11.5.4.1 Formatting and Conversion Options
14772 The following lpr(1) options control formatting of the files in the job.
14773 Use these options if the job does not contain plain text or if you want
14774 plain text formatted through the pr(1) utility.
14776 For example, the following command prints a DVI file (from the TeX
14777 typesetting system) named fish-report.dvi to the printer named bamboo:
14779 % lpr -P bamboo -d fish-report.dvi
14781 These options apply to every file in the job, so you cannot mix (say) DVI
14782 and ditroff files together in a job. Instead, submit the files as separate
14783 jobs, using a different conversion option for each job.
14785 Note: All of these options except -p and -T require conversion filters
14786 installed for the destination printer. For example, the -d option
14787 requires the DVI conversion filter. Section Conversion Filters gives
14792 Print cifplot files.
14800 Print FORTRAN text files.
14808 Indent the output by number columns; if you omit number, indent by
14809 8 columns. This option works only with certain conversion filters.
14811 Note: Do not put any space between the -i and the number.
14815 Print literal text data, including control characters.
14819 Print ditroff (device independent troff) data.
14823 Format plain text with pr(1) before printing. See pr(1) for more
14828 Use title on the pr(1) header instead of the file name. This
14829 option has effect only when used with the -p option.
14839 Here is an example: this command prints a nicely formatted version of the
14840 ls(1) manual page on the default printer:
14842 % zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t
14844 The zcat(1) command uncompresses the source of the ls(1) manual page and
14845 passes it to the troff(1) command, which formats that source and makes GNU
14846 troff output and passes it to lpr(1), which submits the job to the LPD
14847 spooler. Because we used the -t option to lpr(1), the spooler will convert
14848 the GNU troff output into a format the default printer can understand when
14851 ----------------------------------------------------------------------
14853 11.5.4.2 Job Handling Options
14855 The following options to lpr(1) tell LPD to handle the job specially:
14859 Produce a number of copies of each file in the job instead of just
14860 one copy. An administrator may disable this option to reduce
14861 printer wear-and-tear and encourage photocopier usage. See section
14862 Restricting Multiple Copies.
14864 This example prints three copies of parser.c followed by three
14865 copies of parser.h to the default printer:
14867 % lpr -#3 parser.c parser.h
14871 Send mail after completing the print job. With this option, the
14872 LPD system will send mail to your account when it finishes
14873 handling your job. In its message, it will tell you if the job
14874 completed successfully or if there was an error, and (often) what
14879 Do not copy the files to the spooling directory, but make symbolic
14880 links to them instead.
14882 If you are printing a large job, you probably want to use this
14883 option. It saves space in the spooling directory (your job might
14884 overflow the free space on the filesystem where the spooling
14885 directory resides). It saves time as well since LPD will not have
14886 to copy each and every byte of your job to the spooling directory.
14888 There is a drawback, though: since LPD will refer to the original
14889 files directly, you cannot modify or remove them until they have
14892 Note: If you are printing to a remote printer, LPD will
14893 eventually have to copy files from the local host to the remote
14894 host, so the -s option will save space only on the local
14895 spooling directory, not the remote. It is still useful, though.
14899 Remove the files in the job after copying them to the spooling
14900 directory, or after printing them with the -s option. Be careful
14903 ----------------------------------------------------------------------
14905 11.5.4.3 Header Page Options
14907 These options to lpr(1) adjust the text that normally appears on a job's
14908 header page. If header pages are suppressed for the destination printer,
14909 these options have no effect. See section Header Pages for information
14910 about setting up header pages.
14914 Replace the hostname on the header page with text. The hostname is
14915 normally the name of the host from which the job was submitted.
14919 Replace the job name on the header page with text. The job name is
14920 normally the name of the first file of the job, or stdin if you
14921 are printing standard input.
14925 Do not print any header page.
14927 Note: At some sites, this option may have no effect due to the
14928 way header pages are generated. See Header Pages for details.
14930 ----------------------------------------------------------------------
14932 11.5.5 Administering Printers
14934 As an administrator for your printers, you have had to install, set up,
14935 and test them. Using the lpc(8) command, you can interact with your
14936 printers in yet more ways. With lpc(8), you can
14938 * Start and stop the printers
14940 * Enable and disable their queues
14942 * Rearrange the order of the jobs in each queue.
14944 First, a note about terminology: if a printer is stopped, it will not
14945 print anything in its queue. Users can still submit jobs, which will wait
14946 in the queue until the printer is started or the queue is cleared.
14948 If a queue is disabled, no user (except root) can submit jobs for the
14949 printer. An enabled queue allows jobs to be submitted. A printer can be
14950 started for a disabled queue, in which case it will continue to print jobs
14951 in the queue until the queue is empty.
14953 In general, you have to have root privileges to use the lpc(8) command.
14954 Ordinary users can use the lpc(8) command to get printer status and to
14955 restart a hung printer only.
14957 Here is a summary of the lpc(8) commands. Most of the commands take a
14958 printer-name argument to tell on which printer to operate. You can use all
14959 for the printer-name to mean all printers listed in /etc/printcap.
14963 Cancel the current job and stop the printer. Users can still
14964 submit jobs if the queue is enabled.
14968 Remove old files from the printer's spooling directory.
14969 Occasionally, the files that make up a job are not properly
14970 removed by LPD, particularly if there have been errors during
14971 printing or a lot of administrative activity. This command finds
14972 files that do not belong in the spooling directory and removes
14975 disable printer-name
14977 Disable queuing of new jobs. If the printer is running, it will
14978 continue to print any jobs remaining in the queue. The superuser
14979 (root) can always submit jobs, even to a disabled queue.
14981 This command is useful while you are testing a new printer or
14982 filter installation: disable the queue and submit jobs as root.
14983 Other users will not be able to submit jobs until you complete
14984 your testing and re-enable the queue with the enable command.
14986 down printer-name message
14988 Take a printer down. Equivalent to disable followed by stop. The
14989 message appears as the printer's status whenever a user checks the
14990 printer's queue with lpq(1) or status with lpc status.
14992 enable printer-name
14994 Enable the queue for a printer. Users can submit jobs but the
14995 printer will not print anything until it is started.
14999 Print help on the command command-name. With no command-name,
15000 print a summary of the commands available.
15002 restart printer-name
15004 Start the printer. Ordinary users can use this command if some
15005 extraordinary circumstance hangs LPD, but they cannot start a
15006 printer stopped with either the stop or down commands. The restart
15007 command is equivalent to abort followed by start.
15011 Start the printer. The printer will print jobs in its queue.
15015 Stop the printer. The printer will finish the current job and will
15016 not print anything else in its queue. Even though the printer is
15017 stopped, users can still submit jobs to an enabled queue.
15019 topq printer-name job-or-username
15021 Rearrange the queue for printer-name by placing the jobs with the
15022 listed job numbers or the jobs belonging to username at the top of
15023 the queue. For this command, you cannot use all as the
15028 Bring a printer up; the opposite of the down command. Equivalent
15029 to start followed by enable.
15031 lpc(8) accepts the above commands on the command line. If you do not enter
15032 any commands, lpc(8) enters an interactive mode, where you can enter
15033 commands until you type exit, quit, or end-of-file.
15035 ----------------------------------------------------------------------
15037 11.6 Alternatives to the Standard Spooler
15039 If you have been reading straight through this manual, by now you have
15040 learned just about everything there is to know about the LPD spooling
15041 system that comes with DragonFly. You can probably appreciate many of its
15042 shortcomings, which naturally leads to the question: ``What other spooling
15043 systems are out there (and work with DragonFly)?''
15047 LPRng, which purportedly means ``LPR: the Next Generation'' is a
15048 complete rewrite of PLP. Patrick Powell and Justin Mason (the
15049 principal maintainer of PLP) collaborated to make LPRng. The main
15050 site for LPRng is http://www.lprng.org/.
15054 CUPS, the Common UNIX Printing System, provides a portable
15055 printing layer for UNIX-based operating systems. It has been
15056 developed by Easy Software Products to promote a standard printing
15057 solution for all UNIX vendors and users.
15059 CUPS uses the Internet Printing Protocol (IPP) as the basis for
15060 managing print jobs and queues. The Line Printer Daemon (LPD)
15061 Server Message Block (SMB), and AppSocket (a.k.a. JetDirect)
15062 protocols are also supported with reduced functionality. CUPS adds
15063 network printer browsing and PostScript Printer Description (PPD)
15064 based printing options to support real-world printing under UNIX.
15066 The main site for CUPS is http://www.cups.org/.
15068 ----------------------------------------------------------------------
15070 11.7 Troubleshooting
15072 After performing the simple test with lptest(1), you might have gotten one
15073 of the following results instead of the correct printout:
15075 It worked, after awhile; or, it did not eject a full sheet.
15077 The printer printed the above, but it sat for awhile and did
15078 nothing. In fact, you might have needed to press a PRINT REMAINING
15079 or FORM FEED button on the printer to get any results to appear.
15081 If this is the case, the printer was probably waiting to see if
15082 there was any more data for your job before it printed anything.
15083 To fix this problem, you can have the text filter send a FORM FEED
15084 character (or whatever is necessary) to the printer. This is
15085 usually sufficient to have the printer immediately print any text
15086 remaining in its internal buffer. It is also useful to make sure
15087 each print job ends on a full sheet, so the next job does not
15088 start somewhere on the middle of the last page of the previous
15091 The following replacement for the shell script
15092 /usr/local/libexec/if-simple prints a form feed after it sends the
15093 job to the printer:
15097 # if-simple - Simple text input filter for lpd
15098 # Installed in /usr/local/libexec/if-simple
15100 # Simply copies stdin to stdout. Ignores all filter arguments.
15101 # Writes a form feed character (\f) after printing job.
15103 /bin/cat && printf "\f" && exit 0
15106 It produced the ``staircase effect.''
15108 You got the following on paper:
15110 !"#$%&'()*+,-./01234
15111 "#$%&'()*+,-./012345
15112 #$%&'()*+,-./0123456
15114 You have become another victim of the staircase effect, caused by
15115 conflicting interpretations of what characters should indicate a
15116 new line. UNIX style operating systems use a single character:
15117 ASCII code 10, the line feed (LF). MS-DOS, OS/2(R), and others
15118 uses a pair of characters, ASCII code 10 and ASCII code 13 (the
15119 carriage return or CR). Many printers use the MS-DOS convention
15120 for representing new-lines.
15122 When you print with DragonFly, your text used just the line feed
15123 character. The printer, upon seeing a line feed character,
15124 advanced the paper one line, but maintained the same horizontal
15125 position on the page for the next character to print. That is what
15126 the carriage return is for: to move the location of the next
15127 character to print to the left edge of the paper.
15129 Here is what DragonFly wants your printer to do:
15131 Printer received CR Printer prints CR
15132 Printer received LF Printer prints CR + LF
15134 Here are some ways to achieve this:
15136 * Use the printer's configuration switches or control panel to
15137 alter its interpretation of these characters. Check your
15138 printer's manual to find out how to do this.
15140 Note: If you boot your system into other operating systems
15141 besides DragonFly, you may have to reconfigure the printer
15142 to use a an interpretation for CR and LF characters that
15143 those other operating systems use. You might prefer one of
15144 the other solutions, below.
15146 * Have DragonFly's serial line driver automatically convert LF
15147 to CR+LF. Of course, this works with printers on serial ports
15148 only. To enable this feature, use the ms# capability and set
15149 the onlcr mode in the /etc/printcap file for the printer.
15151 * Send an escape code to the printer to have it temporarily
15152 treat LF characters differently. Consult your printer's
15153 manual for escape codes that your printer might support. When
15154 you find the proper escape code, modify the text filter to
15155 send the code first, then send the print job.
15157 Here is an example text filter for printers that understand
15158 the Hewlett-Packard PCL escape codes. This filter makes the
15159 printer treat LF characters as a LF and CR; then it sends the
15160 job; then it sends a form feed to eject the last page of the
15161 job. It should work with nearly all Hewlett Packard printers.
15165 # hpif - Simple text input filter for lpd for HP-PCL based printers
15166 # Installed in /usr/local/libexec/hpif
15168 # Simply copies stdin to stdout. Ignores all filter arguments.
15169 # Tells printer to treat LF as CR+LF. Ejects the page when done.
15171 printf "\033&k2G" && cat && printf "\033&l0H" && exit 0
15174 Here is an example /etc/printcap from a host called orchid.
15175 It has a single printer attached to its first parallel port,
15176 a Hewlett Packard LaserJet 3Si named teak. It is using the
15177 above script as its text filter:
15180 # /etc/printcap for host orchid
15182 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
15183 :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
15184 :if=/usr/local/libexec/hpif:
15186 It overprinted each line.
15188 The printer never advanced a line. All of the lines of text were
15189 printed on top of each other on one line.
15191 This problem is the ``opposite'' of the staircase effect,
15192 described above, and is much rarer. Somewhere, the LF characters
15193 that DragonFly uses to end a line are being treated as CR
15194 characters to return the print location to the left edge of the
15195 paper, but not also down a line.
15197 Use the printer's configuration switches or control panel to
15198 enforce the following interpretation of LF and CR characters:
15200 Printer receives Printer prints
15204 The printer lost characters.
15206 While printing, the printer did not print a few characters in each
15207 line. The problem might have gotten worse as the printer ran,
15208 losing more and more characters.
15210 The problem is that the printer cannot keep up with the speed at
15211 which the computer sends data over a serial line (this problem
15212 should not occur with printers on parallel ports). There are two
15213 ways to overcome the problem:
15215 * If the printer supports XON/XOFF flow control, have DragonFly
15216 use it by specifying the ixon mode in the ms# capability.
15218 * If the printer supports carrier flow control, specify the
15219 crtscts mode in the ms# capability. Make sure the cable
15220 connecting the printer to the computer is correctly wired for
15221 carrier flow control.
15223 It printed garbage.
15225 The printer printed what appeared to be random garbage, but not
15228 This is usually another symptom of incorrect communications
15229 parameters with a serial printer. Double-check the bps rate in the
15230 br capability, and the parity setting in the ms# capability; make
15231 sure the printer is using the same settings as specified in the
15232 /etc/printcap file.
15236 If nothing happened, the problem is probably within DragonFly and
15237 not the hardware. Add the log file (lf) capability to the entry
15238 for the printer you are debugging in the /etc/printcap file. For
15239 example, here is the entry for rattan, with the lf capability:
15241 rattan|line|diablo|lp|Diablo 630 Line Printer:\
15242 :sh:sd=/var/spool/lpd/rattan:\
15244 :if=/usr/local/libexec/if-simple:\
15245 :lf=/var/log/rattan.log
15247 Then, try printing again. Check the log file (in our example,
15248 /var/log/rattan.log) to see any error messages that might appear.
15249 Based on the messages you see, try to correct the problem.
15251 If you do not specify a lf capability, LPD uses /dev/console as a
15254 ----------------------------------------------------------------------
15260 This chapter covers the use of disks in DragonFly. This includes
15261 memory-backed disks, network-attached disks, and standard SCSI/IDE storage
15264 After reading this chapter, you will know:
15266 * The terminology DragonFly uses to describe the organization of data on
15267 a physical disk (partitions and slices).
15269 * How to add additional hard disks to your system.
15271 * How to set up virtual file systems, such as memory disks.
15273 * How to use quotas to limit disk space usage.
15275 * How to encrypt disks to secure them against attackers.
15277 * How to create and burn CDs and DVDs on DragonFly.
15279 * The various storage media options for backups.
15281 * How to use backup programs available under DragonFly.
15283 * How to backup to floppy disks.
15285 * What snapshots are and how to use them efficiently.
15287 ----------------------------------------------------------------------
15291 The following is a list of physical storage devices supported in
15292 DragonFly, and the device names associated with them.
15294 Table 12-1. Physical Disk Naming Conventions
15296 +------------------------------------------------------------------------+
15297 | Drive type | Drive device name |
15298 |-----------------------------+------------------------------------------|
15299 | IDE hard drives | ad |
15300 |-----------------------------+------------------------------------------|
15301 | IDE CDROM drives | acd |
15302 |-----------------------------+------------------------------------------|
15303 | SCSI hard drives and USB | da |
15304 | Mass storage devices | |
15305 |-----------------------------+------------------------------------------|
15306 | SCSI CDROM drives | cd |
15307 |-----------------------------+------------------------------------------|
15308 | Assorted non-standard CDROM | mcd for Mitsumi CD-ROM, scd for Sony |
15309 | drives | CD-ROM, |
15310 |-----------------------------+------------------------------------------|
15311 | Floppy drives | fd |
15312 |-----------------------------+------------------------------------------|
15313 | SCSI tape drives | sa |
15314 |-----------------------------+------------------------------------------|
15315 | IDE tape drives | ast |
15316 |-----------------------------+------------------------------------------|
15317 | Flash drives | fla for DiskOnChip(R) Flash device |
15318 |-----------------------------+------------------------------------------|
15319 | | aacd for Adaptec(R) AdvancedRAID, mlxd |
15320 | RAID drives | and mlyd for Mylex(R), amrd for AMI |
15321 | | MegaRAID(R), idad for Compaq Smart RAID, |
15322 | | twed for 3ware(R) RAID. |
15323 +------------------------------------------------------------------------+
15325 ----------------------------------------------------------------------
15329 Originally contributed by David O'Brien.
15331 Lets say we want to add a new SCSI disk to a machine that currently only
15332 has a single drive. First turn off the computer and install the drive in
15333 the computer following the instructions of the computer, controller, and
15334 drive manufacturer. Due to the wide variations of procedures to do this,
15335 the details are beyond the scope of this document.
15337 Login as user root. After you have installed the drive, inspect
15338 /var/run/dmesg.boot to ensure the new disk was found. Continuing with our
15339 example, the newly added drive will be da1 and we want to mount it on /1
15340 (if you are adding an IDE drive, the device name will be ad1).
15342 Because DragonFly runs on IBM-PC compatible computers, it must take into
15343 account the PC BIOS partitions. These are different from the traditional
15344 BSD partitions. A PC disk has up to four BIOS partition entries. If the
15345 disk is going to be truly dedicated to DragonFly, you can use the
15346 dedicated mode. Otherwise, DragonFly will have to live within one of the
15347 PC BIOS partitions. DragonFly calls the PC BIOS partitions slices so as
15348 not to confuse them with traditional BSD partitions. You may also use
15349 slices on a disk that is dedicated to DragonFly, but used in a computer
15350 that also has another operating system installed. This is to not confuse
15351 the fdisk utility of the other operating system.
15353 In the slice case the drive will be added as /dev/da1s1e. This is read as:
15354 SCSI disk, unit number 1 (second SCSI disk), slice 1 (PC BIOS partition
15355 1), and e BSD partition. In the dedicated case, the drive will be added
15356 simply as /dev/da1e.
15358 ----------------------------------------------------------------------
15360 12.3.1 Using Command Line Utilities
15362 12.3.1.1 Using Slices
15364 This setup will allow your disk to work correctly with other operating
15365 systems that might be installed on your computer and will not confuse
15366 other operating systems' fdisk utilities. It is recommended to use this
15367 method for new disk installs. Only use dedicated mode if you have a good
15370 # dd if=/dev/zero of=/dev/da1 bs=1k count=1
15371 # fdisk -BI da1 #Initialize your new disk
15372 # disklabel -B -w -r da1s1 auto #Label it.
15373 # disklabel -e da1s1 # Edit the disklabel just created and add any partitions.
15375 # newfs /dev/da1s1e # Repeat this for every partition you created.
15376 # mount /dev/da1s1e /1 # Mount the partition(s)
15377 # vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab.
15379 If you have an IDE disk, substitute ad for da.
15381 ----------------------------------------------------------------------
15385 If you will not be sharing the new drive with another operating system,
15386 you may use the dedicated mode. Remember this mode can confuse Microsoft
15387 operating systems; however, no damage will be done by them. IBM's OS/2
15388 however, will ``appropriate'' any partition it finds which it does not
15391 # dd if=/dev/zero of=/dev/da1 bs=1k count=1
15392 # disklabel -Brw da1 auto
15393 # disklabel -e da1 # create the `e' partition
15394 # newfs -d0 /dev/da1e
15396 # vi /etc/fstab # add an entry for /dev/da1e
15399 An alternate method is:
15401 # dd if=/dev/zero of=/dev/da1 count=2
15402 # disklabel /dev/da1 | disklabel -BrR da1 /dev/stdin
15405 # vi /etc/fstab # add an entry for /dev/da1e
15408 ----------------------------------------------------------------------
15412 12.4.1 Software RAID
15414 12.4.1.1 Concatenated Disk Driver (CCD) Configuration
15416 Original work by Christopher Shumway. Revised by Jim Brown.
15418 When choosing a mass storage solution the most important factors to
15419 consider are speed, reliability, and cost. It is rare to have all three in
15420 balance; normally a fast, reliable mass storage device is expensive, and
15421 to cut back on cost either speed or reliability must be sacrificed.
15423 In designing the system described below, cost was chosen as the most
15424 important factor, followed by speed, then reliability. Data transfer speed
15425 for this system is ultimately constrained by the network. And while
15426 reliability is very important, the CCD drive described below serves online
15427 data that is already fully backed up on CD-R's and can easily be replaced.
15429 Defining your own requirements is the first step in choosing a mass
15430 storage solution. If your requirements prefer speed or reliability over
15431 cost, your solution will differ from the system described in this section.
15433 ----------------------------------------------------------------------
15435 12.4.1.1.1 Installing the Hardware
15437 In addition to the IDE system disk, three Western Digital 30GB, 5400 RPM
15438 IDE disks form the core of the CCD disk described below providing
15439 approximately 90GB of online storage. Ideally, each IDE disk would have
15440 its own IDE controller and cable, but to minimize cost, additional IDE
15441 controllers were not used. Instead the disks were configured with jumpers
15442 so that each IDE controller has one master, and one slave.
15444 Upon reboot, the system BIOS was configured to automatically detect the
15445 disks attached. More importantly, DragonFly detected them on reboot:
15447 ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33
15448 ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33
15449 ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33
15450 ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33
15452 Note: If DragonFly does not detect all the disks, ensure that you have
15453 jumpered them correctly. Most IDE drives also have a ``Cable Select''
15454 jumper. This is not the jumper for the master/slave relationship.
15455 Consult the drive documentation for help in identifying the correct
15458 Next, consider how to attach them as part of the file system. You should
15459 research both vinum(8) (Chapter 13) and ccd(4). In this particular
15460 configuration, ccd(4) was chosen.
15462 ----------------------------------------------------------------------
15464 12.4.1.1.2 Setting Up the CCD
15466 The driver ccd(4) allows you to take several identical disks and
15467 concatenate them into one logical file system. In order to use ccd(4), you
15468 need a kernel with ccd(4) support built in. Add this line to your kernel
15469 configuration file, rebuild, and reinstall the kernel:
15471 pseudo-device ccd 4
15473 The ccd(4) support can also be loaded as a kernel loadable module.
15475 To set up ccd(4), you must first use disklabel(8) to label the disks:
15477 disklabel -r -w ad1 auto
15478 disklabel -r -w ad2 auto
15479 disklabel -r -w ad3 auto
15481 This creates a disklabel for ad1c, ad2c and ad3c that spans the entire
15484 The next step is to change the disk label type. You can use disklabel(8)
15491 This opens up the current disk label on each disk with the editor
15492 specified by the EDITOR environment variable, typically vi(1).
15494 An unmodified disk label will look something like this:
15497 # size offset fstype [fsize bsize bps/cpg]
15498 c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
15500 Add a new e partition for ccd(4) to use. This can usually be copied from
15501 the c partition, but the fstype must be 4.2BSD. The disk label should now
15502 look something like this:
15505 # size offset fstype [fsize bsize bps/cpg]
15506 c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
15507 e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)
15509 ----------------------------------------------------------------------
15511 12.4.1.1.3 Building the File System
15513 The device node for ccd0c may not exist yet, so to create it, perform the
15514 following commands:
15519 Now that you have all of the disks labeled, you must build the ccd(4). To
15520 do that, use ccdconfig(8), with options similar to the following:
15522 ccdconfig ccd0(1) 32(2) 0(3) /dev/ad1e(4) /dev/ad2e /dev/ad3e
15524 The use and meaning of each option is shown below:
15527 The first argument is the device to configure, in this case,
15528 /dev/ccd0c. The /dev/ portion is optional.
15530 The interleave for the file system. The interleave defines the
15531 size of a stripe in disk blocks, each normally 512 bytes. So, an
15532 interleave of 32 would be 16,384 bytes.
15534 Flags for ccdconfig(8). If you want to enable drive mirroring, you
15535 can specify a flag here. This configuration does not provide
15536 mirroring for ccd(4), so it is set at 0 (zero).
15538 The final arguments to ccdconfig(8) are the devices to place into
15539 the array. Use the complete pathname for each device.
15541 After running ccdconfig(8) the ccd(4) is configured. A file system can be
15542 installed. Refer to newfs(8) for options, or simply run:
15546 ----------------------------------------------------------------------
15548 12.4.1.1.4 Making it All Automatic
15550 Generally, you will want to mount the ccd(4) upon each reboot. To do this,
15551 you must configure it first. Write out your current configuration to
15552 /etc/ccd.conf using the following command:
15554 ccdconfig -g > /etc/ccd.conf
15556 During reboot, the script /etc/rc runs ccdconfig -C if /etc/ccd.conf
15557 exists. This automatically configures the ccd(4) so it can be mounted.
15559 Note: If you are booting into single user mode, before you can mount(8)
15560 the ccd(4), you need to issue the following command to configure the
15565 To automatically mount the ccd(4), place an entry for the ccd(4) in
15566 /etc/fstab so it will be mounted at boot time:
15568 /dev/ccd0c /media ufs rw 2 2
15570 ----------------------------------------------------------------------
15572 12.4.1.2 The Vinum Volume Manager
15574 The Vinum Volume Manager is a block device driver which implements virtual
15575 disk drives. It isolates disk hardware from the block device interface and
15576 maps data in ways which result in an increase in flexibility, performance
15577 and reliability compared to the traditional slice view of disk storage.
15578 vinum(8) implements the RAID-0, RAID-1 and RAID-5 models, both
15579 individually and in combination.
15581 See Chapter 13 for more information about vinum(8).
15583 ----------------------------------------------------------------------
15585 12.4.2 Hardware RAID
15587 DragonFly also supports a variety of hardware RAID controllers. These
15588 devices control a RAID subsystem without the need for DragonFly specific
15589 software to manage the array.
15591 Using an on-card BIOS, the card controls most of the disk operations
15592 itself. The following is a brief setup description using a Promise IDE
15593 RAID controller. When this card is installed and the system is started up,
15594 it displays a prompt requesting information. Follow the instructions to
15595 enter the card's setup screen. From here, you have the ability to combine
15596 all the attached drives. After doing so, the disk(s) will look like a
15597 single drive to DragonFly. Other RAID levels can be set up accordingly.
15599 ----------------------------------------------------------------------
15601 12.4.3 Rebuilding ATA RAID1 Arrays
15603 DragonFly allows you to hot-replace a failed disk in an array. This
15604 requires that you catch it before you reboot.
15606 You will probably see something like the following in /var/log/messages or
15607 in the dmesg(8) output:
15609 ad6 on monster1 suffered a hard error.
15610 ad6: READ command timeout tag=0 serv=0 - resetting
15611 ad6: trying fallback to PIO mode
15612 ata3: resetting devices .. done
15613 ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11) status=59 error=40
15614 ar0: WARNING - mirror lost
15616 Using atacontrol(8), check for further information:
15620 Master: no device present
15621 Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0
15624 Master: no device present
15625 Slave: no device present
15628 Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15629 Slave: no device present
15632 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15633 Slave: no device present
15635 # atacontrol status ar0
15636 ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED
15638 1. You will first need to detach the disk from the array so that you can
15641 # atacontrol detach 3
15643 2. Replace the disk.
15645 3. Reattach the disk as a spare:
15647 # atacontrol attach 3
15648 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15649 Slave: no device present
15651 4. Rebuild the array:
15653 # atacontrol rebuild ar0
15655 5. The rebuild command hangs until complete. However, it is possible to
15656 open another terminal (using Alt+Fn) and check on the progress by
15657 issuing the following command:
15661 ad6: removed from configuration
15662 ad6: deleted from ar0 disk1
15663 ad6: inserted into ar0 disk1 as spare
15665 # atacontrol status ar0
15666 ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed
15668 6. Wait until this operation completes.
15670 ----------------------------------------------------------------------
15672 12.5 Creating and Using Optical Media (CDs)
15674 Contributed by Mike Meyer.
15676 ----------------------------------------------------------------------
15678 12.5.1 Introduction
15680 CDs have a number of features that differentiate them from conventional
15681 disks. Initially, they were not writable by the user. They are designed so
15682 that they can be read continuously without delays to move the head between
15683 tracks. They are also much easier to transport between systems than
15684 similarly sized media were at the time.
15686 CDs do have tracks, but this refers to a section of data to be read
15687 continuously and not a physical property of the disk. To produce a CD on
15688 DragonFly, you prepare the data files that are going to make up the tracks
15689 on the CD, then write the tracks to the CD.
15691 The ISO 9660 file system was designed to deal with these differences. It
15692 unfortunately codifies file system limits that were common then.
15693 Fortunately, it provides an extension mechanism that allows properly
15694 written CDs to exceed those limits while still working with systems that
15695 do not support those extensions.
15697 The sysutils/mkisofs program is used to produce a data file containing an
15698 ISO 9660 file system. It has options that support various extensions, and
15699 is described below. It is installed by default.
15701 Which tool to use to burn the CD depends on whether your CD burner is
15702 ATAPI or something else. ATAPI CD burners use the burncd program that is
15703 part of the base system. SCSI and USB CD burners should use cdrecord from
15704 the sysutils/cdrtools port.
15706 burncd has a limited number of supported drives. To find out if a drive is
15707 supported, see the CD-R/RW supported drives list.
15709 Note: It ispossible to use cdrecord and other tools for SCSI drives on
15710 an ATAPI hardware with the ATAPI/CAM module.
15712 ----------------------------------------------------------------------
15716 sysutils/mkisofs produces an ISO 9660 file system that is an image of a
15717 directory tree in the UNIX file system name space. The simplest usage is:
15719 # mkisofs -o imagefile.iso /path/to/tree
15721 This command will create an imagefile.iso containing an ISO 9660 file
15722 system that is a copy of the tree at /path/to/tree. In the process, it
15723 will map the file names to names that fit the limitations of the standard
15724 ISO 9660 file system, and will exclude files that have names
15725 uncharacteristic of ISO file systems.
15727 A number of options are available to overcome those restrictions. In
15728 particular, -R enables the Rock Ridge extensions common to UNIX systems,
15729 -J enables Joliet extensions used by Microsoft systems, and -hfs can be
15730 used to create HFS file systems used by Mac OS.
15732 For CDs that are going to be used only on DragonFly systems, -U can be
15733 used to disable all filename restrictions. When used with -R, it produces
15734 a file system image that is identical to the DragonFly tree you started
15735 from, though it may violate the ISO 9660 standard in a number of ways.
15737 The last option of general use is -b. This is used to specify the location
15738 of the boot image for use in producing an ``El Torito'' bootable CD. This
15739 option takes an argument which is the path to a boot image from the top of
15740 the tree being written to the CD. So, given that /tmp/myboot holds a
15741 bootable DragonFly system with the boot image in /tmp/myboot/boot/cdboot,
15742 you could produce the image of an ISO 9660 file system in
15743 /tmp/bootable.iso like so:
15745 # mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot
15747 Having done that, if you have vn configured in your kernel, you can mount
15748 the file system with:
15750 # vnconfig -e vn0c /tmp/bootable.iso
15751 # mount -t cd9660 /dev/vn0c /mnt
15753 At which point you can verify that /mnt and /tmp/myboot are identical.
15755 There are many other options you can use with sysutils/mkisofs to
15756 fine-tune its behavior. In particular: modifications to an ISO 9660 layout
15757 and the creation of Joliet and HFS discs. See the mkisofs(8) manual page
15760 ----------------------------------------------------------------------
15764 If you have an ATAPI CD burner, you can use the burncd command to burn an
15765 ISO image onto a CD. burncd is part of the base system, installed as
15766 /usr/sbin/burncd. Usage is very simple, as it has few options:
15768 # burncd -f cddevice data imagefile.iso fixate
15770 Will burn a copy of imagefile.iso on cddevice. The default device is
15771 /dev/acd0c. See burncd(8) for options to set the write speed, eject the CD
15772 after burning, and write audio data.
15774 ----------------------------------------------------------------------
15778 If you do not have an ATAPI CD burner, you will have to use cdrecord to
15779 burn your CDs. cdrecord is not part of the base system; you must install
15780 it from either the port at sysutils/cdrtools or the appropriate package.
15781 Changes to the base system can cause binary versions of this program to
15782 fail, possibly resulting in a ``coaster''. You should therefore either
15783 upgrade the port when you upgrade your system.
15785 While cdrecord has many options, basic usage is even simpler than burncd.
15786 Burning an ISO 9660 image is done with:
15788 # cdrecord dev=device imagefile.iso
15790 The tricky part of using cdrecord is finding the dev to use. To find the
15791 proper setting, use the -scanbus flag of cdrecord, which might produce
15794 # cdrecord -scanbus
15795 Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jo:rg Schilling
15796 Using libscg version 'schily-0.1'
15798 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk
15799 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk
15801 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk
15802 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
15812 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM
15813 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner
15816 This lists the appropriate dev value for the devices on the list. Locate
15817 your CD burner, and use the three numbers separated by commas as the value
15818 for dev. In this case, the CRW device is 1,5,0, so the appropriate input
15819 would be dev=1,5,0. There are easier ways to specify this value; see
15820 cdrecord(1) for details. That is also the place to look for information on
15821 writing audio tracks, controlling the speed, and other things.
15823 ----------------------------------------------------------------------
15825 12.5.5 Duplicating Audio CDs
15827 You can duplicate an audio CD by extracting the audio data from the CD to
15828 a series of files, and then writing these files to a blank CD. The process
15829 is slightly different for ATAPI and SCSI drives.
15833 1. Use cdda2wav to extract the audio.
15835 % cdda2wav -v255 -D2,0 -B -Owav
15837 2. Use cdrecord to write the .wav files.
15839 % cdrecord -v dev=2,0 -dao -useinfo *.wav
15841 Make sure that 2.0 is set appropriately, as described in Section
15846 1. The ATAPI CD driver makes each track available as /dev/acddtnn, where
15847 d is the drive number, and nn is the track number written with two
15848 decimal digits, prefixed with zero as needed. So the first track on
15849 the first disk is /dev/acd0t01, the second is /dev/acd0t02, the third
15850 is /dev/acd0t03, and so on.
15852 Make sure the appropriate files exist in /dev.
15855 # sh MAKEDEV acd0t99
15857 2. Extract each track using dd(1). You must also use a specific block
15858 size when extracting the files.
15860 # dd if=/dev/acd0t01 of=track1.cdr bs=2352
15861 # dd if=/dev/acd0t02 of=track2.cdr bs=2352
15864 3. Burn the extracted files to disk using burncd. You must specify that
15865 these are audio files, and that burncd should fixate the disk when
15868 # burncd -f /dev/acd0c audio track1.cdr track2.cdr ... fixate
15870 ----------------------------------------------------------------------
15872 12.5.6 Duplicating Data CDs
15874 You can copy a data CD to a image file that is functionally equivalent to
15875 the image file created with sysutils/mkisofs, and you can use it to
15876 duplicate any data CD. The example given here assumes that your CDROM
15877 device is acd0c. Substitute your correct CDROM device. A c must be
15878 appended to the end of the device name to indicate the entire partition
15879 or, in the case of CDROMs, the entire disc.
15881 # dd if=/dev/acd0c of=file.iso bs=2048
15883 Now that you have an image, you can burn it to CD as described above.
15885 ----------------------------------------------------------------------
15887 12.5.7 Using Data CDs
15889 Now that you have created a standard data CDROM, you probably want to
15890 mount it and read the data on it. By default, mount(8) assumes that a file
15891 system is of type ufs. If you try something like:
15893 # mount /dev/cd0 /mnt
15895 you will get a complaint about ``Incorrect super block'', and no mount.
15896 The CDROM is not a UFS file system, so attempts to mount it as such will
15897 fail. You just need to tell mount(8) that the file system is of type
15898 ISO9660, and everything will work. You do this by specifying the -t cd9660
15899 option mount(8). For example, if you want to mount the CDROM device,
15900 /dev/cd0, under /mnt, you would execute:
15902 # mount -t cd9660 /dev/cd0 /mnt
15904 Note that your device name (/dev/cd0 in this example) could be different,
15905 depending on the interface your CDROM uses. Also, the -t cd9660 option
15906 just executes mount_cd9660(8). The above example could be shortened to:
15908 # mount_cd9660 /dev/cd0 /mnt
15910 You can generally use data CDROMs from any vendor in this way. Disks with
15911 certain ISO 9660 extensions might behave oddly, however. For example,
15912 Joliet disks store all filenames in two-byte Unicode characters. The
15913 DragonFly kernel does not speak Unicode (yet!), so non-English characters
15914 show up as question marks. (The CD9660 driver includes hooks to load an
15915 appropriate Unicode conversion table on the fly. Modules for some of the
15916 common encodings are available via the sysutils/cd9660_unicode port.)
15918 Occasionally, you might get ``Device not configured'' when trying to mount
15919 a CDROM. This usually means that the CDROM drive thinks that there is no
15920 disk in the tray, or that the drive is not visible on the bus. It can take
15921 a couple of seconds for a CDROM drive to realize that it has been fed, so
15924 Sometimes, a SCSI CDROM may be missed because it did not have enough time
15925 to answer the bus reset. If you have a SCSI CDROM please add the following
15926 option to your kernel configuration and rebuild your kernel.
15928 options SCSI_DELAY=15000
15930 This tells your SCSI bus to pause 15 seconds during boot, to give your
15931 CDROM drive every possible chance to answer the bus reset.
15933 ----------------------------------------------------------------------
15935 12.5.8 Burning Raw Data CDs
15937 You can choose to burn a file directly to CD, without creating an ISO 9660
15938 file system. Some people do this for backup purposes. This runs more
15939 quickly than burning a standard CD:
15941 # burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate
15943 In order to retrieve the data burned to such a CD, you must read data from
15944 the raw device node:
15946 # tar xzvf /dev/acd1
15948 You cannot mount this disk as you would a normal CDROM. Such a CDROM
15949 cannot be read under any operating system except DragonFly. If you want to
15950 be able to mount the CD, or share data with another operating system, you
15951 must use sysutils/mkisofs as described above.
15953 ----------------------------------------------------------------------
15955 12.5.9 Using the ATAPI/CAM Driver
15957 Contributed by Marc Fonvieille.
15959 This driver allows ATAPI devices (CD-ROM, CD-RW, DVD drives etc...) to be
15960 accessed through the SCSI subsystem, and so allows the use of applications
15961 like sysutils/cdrdao or cdrecord(1).
15963 To use this driver, you will need to add the following lines to your
15964 kernel configuration file:
15971 You also need the following line in your kernel configuration file:
15975 which should already be present.
15977 Then rebuild, install your new kernel, and reboot your machine. During the
15978 boot process, your burner should show up, like so:
15980 acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4
15981 cd0 at ata1 bus 0 target 0 lun 0
15982 cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device
15983 cd0: 16.000MB/s transfers
15984 cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed
15986 The drive could now be accessed via the /dev/cd0 device name, for example
15987 to mount a CD-ROM on /mnt, just type the following:
15989 # mount -t cd9660 /dev/cd0 /mnt
15991 As root, you can run the following command to get the SCSI address of the
15994 # camcontrol devlist
15995 <MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0)
15997 So 1,0,0 will be the SCSI address to use with cdrecord(1) and other SCSI
16000 For more information about ATAPI/CAM and SCSI system, refer to the
16001 atapicam(4) and cam(4) manual pages.
16003 ----------------------------------------------------------------------
16005 12.6 Creating and Using Optical Media (DVDs)
16007 Contributed by Marc Fonvieille. With inputs from Andy Polyakov.
16009 ----------------------------------------------------------------------
16011 12.6.1 Introduction
16013 Compared to the CD, the DVD is the next generation of optical media
16014 storage technology. The DVD can hold more data than any CD and is nowadays
16015 the standard for video publishing.
16017 Five physical recordable formats can be defined for what we will call a
16020 * DVD-R: This was the first DVD recordable format available. The DVD-R
16021 standard is defined by the DVD Forum. This format is write once.
16023 * DVD-RW: This is the rewriteable version of the DVD-R standard. A
16024 DVD-RW can be rewritten about 1000 times.
16026 * DVD-RAM: This is also a rewriteable format supported by the DVD Forum.
16027 A DVD-RAM can be seen as a removable hard drive. However, this media
16028 is not compatible with most DVD-ROM drives and DVD-Video players; only
16029 a few DVD writers support the DVD-RAM format.
16031 * DVD+RW: This is a rewriteable format defined by the DVD+RW Alliance. A
16032 DVD+RW can be rewritten about 1000 times.
16034 * DVD+R: This format is the write once variation of the DVD+RW format.
16036 A single layer recordable DVD can hold up to 4,700,000,000 bytes which is
16037 actually 4.38 GB or 4485 MB (1 kilobyte is 1024 bytes).
16039 Note: A distinction must be made between the physical media and the
16040 application. For example, a DVD-Video is a specific file layout that can
16041 be written on any recordable DVD physical media: DVD-R, DVD+R, DVD-RW
16042 etc. Before choosing the type of media, you must be sure that both the
16043 burner and the DVD-Video player (a standalone player or a DVD-ROM drive
16044 on a computer) are compatible with the media under consideration.
16046 ----------------------------------------------------------------------
16048 12.6.2 Configuration
16050 The program growisofs(1) will be used to perform DVD recording. This
16051 command is part of the dvd+rw-tools utilities (sysutils/dvd+rw-tools). The
16052 dvd+rw-tools support all DVD media types.
16054 These tools use the SCSI subsystem to access to the devices, therefore the
16055 ATAPI/CAM support must be added to your kernel.
16057 You also have to enable DMA access for ATAPI devices, this can be done in
16058 adding the following line to the /boot/loader.conf file:
16060 hw.ata.atapi_dma="1"
16062 Before attempting to use the dvd+rw-tools you should consult the
16063 dvd+rw-tools' hardware compatibility notes for any information related to
16066 ----------------------------------------------------------------------
16068 12.6.3 Burning Data DVDs
16070 The growisofs(1) command is a frontend to mkisofs, it will invoke
16071 mkisofs(8) to create the file system layout and will perform the write on
16072 the DVD. This means you do not need to create an image of the data before
16073 the burning process.
16075 To burn onto a DVD+R or a DVD-R the data from the /path/to/data directory,
16076 use the following command:
16078 # growisofs -dvd-compat -Z /dev/cd0 -J -R /path/to/data
16080 The options -J -R are passed to mkisofs(8) for the file system creation
16081 (in this case: an ISO 9660 file system with Joliet and Rock Ridge
16082 extensions), consult the mkisofs(8) manual page for more details.
16084 The option -Z is used for the initial session recording in any case:
16085 multiple sessions or not. The DVD device, /dev/cd0, must be changed
16086 according to your configuration. The -dvd-compat parameter will close the
16087 disk, the recording will be unappendable. In return this should provide
16088 better media compatibility with DVD-ROM drives.
16090 It is also possible to burn a pre-mastered image, for example to burn the
16091 image imagefile.iso, we will run:
16093 # growisofs -dvd-compat -Z /dev/cd0=imagefile.iso
16095 The write speed should be detected and automatically set according to the
16096 media and the drive being used. If you want to force the write speed, use
16097 the -speed= parameter. For more information, read the growisofs(1) manual
16100 ----------------------------------------------------------------------
16102 12.6.4 Burning a DVD-Video
16104 A DVD-Video is a specific file layout based on ISO 9660 and the micro-UDF
16105 (M-UDF) specifications. The DVD-Video also presents a specific data
16106 structure hierarchy, it is the reason why you need a particular program
16107 such as multimedia/dvdauthor to author the DVD.
16109 If you already have an image of the DVD-Video file system, just burn it in
16110 the same way as for any image, see the previous section for an example. If
16111 you have made the DVD authoring and the result is in, for example, the
16112 directory /path/to/video, the following command should be used to burn the
16115 # growisofs -Z /dev/cd0 -dvd-video /path/to/video
16117 The -dvd-video option will be passed down to mkisofs(8) and will instruct
16118 it to create a DVD-Video file system layout. Beside this, the -dvd-video
16119 option implies -dvd-compat growisofs(1) option.
16121 ----------------------------------------------------------------------
16123 12.6.5 Using a DVD+RW
16125 Unlike CD-RW, a virgin DVD+RW needs to be formatted before first use. The
16126 growisofs(1) program will take care of it automatically whenever
16127 appropriate, which is the recommended way. However you can use the
16128 dvd+rw-format command to format the DVD+RW:
16130 # dvd+rw-format /dev/cd0
16132 You need to perform this operation just once, keep in mind that only
16133 virgin DVD+RW medias need to be formatted. Then you can burn the DVD+RW in
16134 the way seen in previous sections.
16136 If you want to burn new data (burn a totally new file system not append
16137 some data) onto a DVD+RW, you do not need to blank it, you just have to
16138 write over the previous recording (in performing a new initial session),
16141 # growisofs -Z /dev/cd0 -J -R /path/to/newdata
16143 DVD+RW format offers the possibility to easily append data to a previous
16144 recording. The operation consists in merging a new session to the existing
16145 one, it is not multisession writing, growisofs(1) will grow the ISO 9660
16146 file system present on the media.
16148 For example, if we want to append data to our previous DVD+RW, we have to
16151 # growisofs -M /dev/cd0 -J -R /path/to/nextdata
16153 The same mkisofs(8) options we used to burn the initial session should be
16154 used during next writes.
16156 Note: You may want to use the -dvd-compat option if you want better
16157 media compatibility with DVD-ROM drives. In the DVD+RW case, this will
16158 not prevent you from adding data.
16160 If for any reason you really want to blank the media, do the following:
16162 # growisofs -Z /dev/cd0=/dev/zero
16164 ----------------------------------------------------------------------
16166 12.6.6 Using a DVD-RW
16168 A DVD-RW accepts two disc formats: the incremental sequential one and the
16169 restricted overwrite. By default DVD-RW discs are in sequential format.
16171 A virgin DVD-RW can be directly written without the need of a formatting
16172 operation, however a non-virgin DVD-RW in sequential format needs to be
16173 blanked before to be able to write a new initial session.
16175 To blank a DVD-RW in sequential mode, run:
16177 # dvd+rw-format -blank=full /dev/cd0
16179 Note: A full blanking (-blank=full) will take about one hour on a 1x
16180 media. A fast blanking can be performed using the -blank option if the
16181 DVD-RW will be recorded in Disk-At-Once (DAO) mode. To burn the DVD-RW
16182 in DAO mode, use the command:
16184 # growisofs -use-the-force-luke=dao -Z /dev/cd0=imagefile.iso
16186 The -use-the-force-luke=dao option should not be required since
16187 growisofs(1) attempts to detect minimally (fast blanked) media and
16190 In fact one should use restricted overwrite mode with any DVD-RW, this
16191 format is more flexible than the default incremental sequential one.
16193 To write data on a sequential DVD-RW, use the same instructions as for the
16196 # growisofs -Z /dev/cd0 -J -R /path/to/data
16198 If you want to append some data to your previous recording, you will have
16199 to use the growisofs(1) -M option. However, if you perform data addition
16200 on a DVD-RW in incremental sequential mode, a new session will be created
16201 on the disc and the result will be a multi-session disc.
16203 A DVD-RW in restricted overwrite format does not need to be blanked before
16204 a new initial session, you just have to overwrite the disc with the -Z
16205 option, this is similar to the DVD+RW case. It is also possible to grow an
16206 existing ISO 9660 file system written on the disc in a same way as for a
16207 DVD+RW with the -M option. The result will be a one-session DVD.
16209 To put a DVD-RW in the restricted overwrite format, the following command
16212 # dvd+rw-format /dev/cd0
16214 To change back to the sequential format use:
16216 # dvd+rw-format -blank=full /dev/cd0
16218 ----------------------------------------------------------------------
16220 12.6.7 Multisession
16222 Very few DVD-ROM and DVD-Video players support multisession DVDs, they
16223 will most of time, hopefully, only read the first session. DVD+R, DVD-R
16224 and DVD-RW in sequential format can accept multiple sessions, the notion
16225 of multiple sessions does not exist for the DVD+RW and the DVD-RW
16226 restricted overwrite formats.
16228 Using the following command after an initial (non-closed) session on a
16229 DVD+R, DVD-R, or DVD-RW in sequential format, will add a new session to
16232 # growisofs -M /dev/cd0 -J -R /path/to/nextdata
16234 Using this command line with a DVD+RW or a DVD-RW in restricted overwrite
16235 mode, will append data in merging the new session to the existing one. The
16236 result will be a single-session disc. This is the way used to add data
16237 after an initial write on these medias.
16239 Note: Some space on the media is used between each session for end and
16240 start of sessions. Therefore, one should add sessions with large amount
16241 of data to optimize media space. The number of sessions is limited to
16242 154 for a DVD+R and about 2000 for a DVD-R.
16244 ----------------------------------------------------------------------
16246 12.6.8 For More Information
16248 To obtain more information about a DVD, the dvd+rw-mediainfo /dev/cd0
16249 command can be ran with the disc in the drive.
16251 More information about the dvd+rw-tools can be found in the growisofs(1)
16252 manual page, on the dvd+rw-tools web site and in the cdwrite mailing list
16255 Note: The dvd+rw-mediainfo output of the resulting recording or the
16256 media with issues is mandatory for any problem report. Without this
16257 output, it will be quite impossible to help you.
16259 ----------------------------------------------------------------------
16261 12.7 Creating and Using Floppy Disks
16263 Original work by Julio Merino. Rewritten by Martin Karlsson.
16265 Storing data on floppy disks is sometimes useful, for example when one
16266 does not have any other removable storage media or when one needs to
16267 transfer small amounts of data to another computer.
16269 This section will explain how to use floppy disks in DragonFly. It will
16270 primarily cover formatting and usage of 3.5inch DOS floppies, but the
16271 concepts are similar for other floppy disk formats.
16273 ----------------------------------------------------------------------
16275 12.7.1 Formatting Floppies
16277 12.7.1.1 The Device
16279 Floppy disks are accessed through entries in /dev, just like other
16280 devices. To access the raw floppy disk, one uses /dev/fdN, where N stands
16281 for the drive number, usually 0, or /dev/fdNX, where X stands for a
16284 There are also /dev/fdN.size devices, where size is a floppy disk size in
16285 kilobytes. These entries are used at low-level format time to determine
16286 the disk size. 1440kB is the size that will be used in the following
16289 Sometimes the entries under /dev will have to be (re)created. To do that,
16292 # cd /dev && ./MAKEDEV "fd*"
16294 ----------------------------------------------------------------------
16296 12.7.1.2 Formatting
16298 A floppy disk needs to be low-level formated before it can be used. This
16299 is usually done by the vendor, but formatting is a good way to check media
16300 integrity. Although it is possible to force larger (or smaller) disk
16301 sizes, 1440kB is what most floppy disks are designed for.
16303 To low-level format the floppy disk you need to use fdformat(1). This
16304 utility expects the device name as an argument.
16306 Make note of any error messages, as these can help determine if the disk
16309 Use the /dev/fdN.size devices to format the floppy. Insert a new 3.5inch
16310 floppy disk in your drive and issue:
16312 # /usr/sbin/fdformat /dev/fd0.1440
16314 ----------------------------------------------------------------------
16316 12.7.2 The Disk Label
16318 After low-level formatting the disk, you will need to place a disk label
16319 on it. This disk label will be destroyed later, but it is needed by the
16320 system to determine the size of the disk and its geometry later.
16322 The new disk label will take over the whole disk, and will contain all the
16323 proper information about the geometry of the floppy. The geometry values
16324 for the disk label are listed in /etc/disktab.
16326 You can run now disklabel(8) like so:
16328 # /sbin/disklabel -B -r -w /dev/fd0 fd1440
16330 ----------------------------------------------------------------------
16332 12.7.3 The File System
16334 Now the floppy is ready to be high-level formated. This will place a new
16335 file system on it, which will let DragonFly read and write to the disk.
16336 After creating the new file system, the disk label is destroyed, so if you
16337 want to reformat the disk, you will have to recreate the disk label.
16339 The floppy's file system can be either UFS or FAT. FAT is generally a
16340 better choice for floppies.
16342 To put a new file system on the floppy, issue:
16344 # /sbin/newfs_msdos /dev/fd0
16346 The disk is now ready for use.
16348 ----------------------------------------------------------------------
16350 12.7.4 Using the Floppy
16352 To use the floppy, mount it with mount_msdos(8). One can also use
16353 sysutils/mtools from pkgsrc.
16355 ----------------------------------------------------------------------
16357 12.8 Creating and Using Data Tapes
16359 The major tape media are the 4mm, 8mm, QIC, mini-cartridge and DLT.
16361 ----------------------------------------------------------------------
16363 12.8.1 4mm (DDS: Digital Data Storage)
16365 4mm tapes are replacing QIC as the workstation backup media of choice.
16366 This trend accelerated greatly when Conner purchased Archive, a leading
16367 manufacturer of QIC drives, and then stopped production of QIC drives. 4mm
16368 drives are small and quiet but do not have the reputation for reliability
16369 that is enjoyed by 8mm drives. The cartridges are less expensive and
16370 smaller (3 x 2 x 0.5 inches, 76 x 51 x 12 mm) than 8mm cartridges. 4mm,
16371 like 8mm, has comparatively short head life for the same reason, both use
16374 Data throughput on these drives starts ~150 kB/s, peaking at ~500 kB/s.
16375 Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware compression,
16376 available with most of these drives, approximately doubles the capacity.
16377 Multi-drive tape library units can have 6 drives in a single cabinet with
16378 automatic tape changing. Library capacities reach 240 GB.
16380 The DDS-3 standard now supports tape capacities up to 12 GB (or 24 GB
16383 4mm drives, like 8mm drives, use helical-scan. All the benefits and
16384 drawbacks of helical-scan apply to both 4mm and 8mm drives.
16386 Tapes should be retired from use after 2,000 passes or 100 full backups.
16388 ----------------------------------------------------------------------
16390 12.8.2 8mm (Exabyte)
16392 8mm tapes are the most common SCSI tape drives; they are the best choice
16393 of exchanging tapes. Nearly every site has an Exabyte 2 GB 8mm tape drive.
16394 8mm drives are reliable, convenient and quiet. Cartridges are inexpensive
16395 and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). One downside of 8mm
16396 tape is relatively short head and tape life due to the high rate of
16397 relative motion of the tape across the heads.
16399 Data throughput ranges from ~250 kB/s to ~500 kB/s. Data sizes start at
16400 300 MB and go up to 7 GB. Hardware compression, available with most of
16401 these drives, approximately doubles the capacity. These drives are
16402 available as single units or multi-drive tape libraries with 6 drives and
16403 120 tapes in a single cabinet. Tapes are changed automatically by the
16404 unit. Library capacities reach 840+ GB.
16406 The Exabyte ``Mammoth'' model supports 12 GB on one tape (24 GB with
16407 compression) and costs approximately twice as much as conventional tape
16410 Data is recorded onto the tape using helical-scan, the heads are
16411 positioned at an angle to the media (approximately 6 degrees). The tape
16412 wraps around 270 degrees of the spool that holds the heads. The spool
16413 spins while the tape slides over the spool. The result is a high density
16414 of data and closely packed tracks that angle across the tape from one edge
16417 ----------------------------------------------------------------------
16421 QIC-150 tapes and drives are, perhaps, the most common tape drive and
16422 media around. QIC tape drives are the least expensive ``serious'' backup
16423 drives. The downside is the cost of media. QIC tapes are expensive
16424 compared to 8mm or 4mm tapes, up to 5 times the price per GB data storage.
16425 But, if your needs can be satisfied with a half-dozen tapes, QIC may be
16426 the correct choice. QIC is the most common tape drive. Every site has a
16427 QIC drive of some density or another. Therein lies the rub, QIC has a
16428 large number of densities on physically similar (sometimes identical)
16429 tapes. QIC drives are not quiet. These drives audibly seek before they
16430 begin to record data and are clearly audible whenever reading, writing or
16431 seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7 mm).
16432 Mini-cartridges, which also use 1/4" wide tape are discussed separately.
16433 Tape libraries and changers are not available.
16435 Data throughput ranges from ~150 kB/s to ~500 kB/s. Data capacity ranges
16436 from 40 MB to 15 GB. Hardware compression is available on many of the
16437 newer QIC drives. QIC drives are less frequently installed; they are being
16438 supplanted by DAT drives.
16440 Data is recorded onto the tape in tracks. The tracks run along the long
16441 axis of the tape media from one end to the other. The number of tracks,
16442 and therefore the width of a track, varies with the tape's capacity. Most
16443 if not all newer drives provide backward-compatibility at least for
16444 reading (but often also for writing). QIC has a good reputation regarding
16445 the safety of the data (the mechanics are simpler and more robust than for
16446 helical scan drives).
16448 Tapes should be retired from use after 5,000 backups.
16450 ----------------------------------------------------------------------
16452 12.8.4 XXX* Mini-Cartridge
16454 ----------------------------------------------------------------------
16458 DLT has the fastest data transfer rate of all the drive types listed here.
16459 The 1/2" (12.5mm) tape is contained in a single spool cartridge (4 x 4 x 1
16460 inches; 100 x 100 x 25 mm). The cartridge has a swinging gate along one
16461 entire side of the cartridge. The drive mechanism opens this gate to
16462 extract the tape leader. The tape leader has an oval hole in it which the
16463 drive uses to ``hook'' the tape. The take-up spool is located inside the
16464 tape drive. All the other tape cartridges listed here (9 track tapes are
16465 the only exception) have both the supply and take-up spools located inside
16466 the tape cartridge itself.
16468 Data throughput is approximately 1.5 MB/s, three times the throughput of
16469 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 GB
16470 for a single drive. Drives are available in both multi-tape changers and
16471 multi-tape, multi-drive tape libraries containing from 5 to 900 tapes over
16472 1 to 20 drives, providing from 50 GB to 9 TB of storage.
16474 With compression, DLT Type IV format supports up to 70 GB capacity.
16476 Data is recorded onto the tape in tracks parallel to the direction of
16477 travel (just like QIC tapes). Two tracks are written at once. Read/write
16478 head lifetimes are relatively long; once the tape stops moving, there is
16479 no relative motion between the heads and the tape.
16481 ----------------------------------------------------------------------
16485 AIT is a new format from Sony, and can hold up to 50 GB (with compression)
16486 per tape. The tapes contain memory chips which retain an index of the
16487 tape's contents. This index can be rapidly read by the tape drive to
16488 determine the position of files on the tape, instead of the several
16489 minutes that would be required for other tapes. Software such as
16490 SAMS:Alexandria can operate forty or more AIT tape libraries,
16491 communicating directly with the tape's memory chip to display the contents
16492 on screen, determine what files were backed up to which tape, locate the
16493 correct tape, load it, and restore the data from the tape.
16495 Libraries like this cost in the region of $20,000, pricing them a little
16496 out of the hobbyist market.
16498 ----------------------------------------------------------------------
16500 12.8.7 Using a New Tape for the First Time
16502 The first time that you try to read or write a new, completely blank tape,
16503 the operation will fail. The console messages should be similar to:
16505 sa0(ncr1:4:0): NOT READY asc:4,1
16506 sa0(ncr1:4:0): Logical unit is in process of becoming ready
16508 The tape does not contain an Identifier Block (block number 0). All QIC
16509 tape drives since the adoption of QIC-525 standard write an Identifier
16510 Block to the tape. There are two solutions:
16512 * mt fsf 1 causes the tape drive to write an Identifier Block to the
16515 * Use the front panel button to eject the tape.
16517 Re-insert the tape and dump data to the tape.
16519 dump will report ``DUMP: End of tape detected'' and the console will
16520 show: ``HARDWARE FAILURE info:280 asc:80,96''.
16522 rewind the tape using: mt rewind.
16524 Subsequent tape operations are successful.
16526 ----------------------------------------------------------------------
16528 12.9 Backups to Floppies
16530 12.9.1 Can I Use Floppies for Backing Up My Data?
16532 Floppy disks are not really a suitable media for making backups as:
16534 * The media is unreliable, especially over long periods of time.
16536 * Backing up and restoring is very slow.
16538 * They have a very limited capacity (the days of backing up an entire
16539 hard disk onto a dozen or so floppies has long since passed).
16541 However, if you have no other method of backing up your data then floppy
16542 disks are better than no backup at all.
16544 If you do have to use floppy disks then ensure that you use good quality
16545 ones. Floppies that have been lying around the office for a couple of
16546 years are a bad choice. Ideally use new ones from a reputable
16549 ----------------------------------------------------------------------
16551 12.9.2 So How Do I Backup My Data to Floppies?
16553 The best way to backup to floppy disk is to use tar(1) with the -M (multi
16554 volume) option, which allows backups to span multiple floppies.
16556 To backup all the files in the current directory and sub-directory use
16559 # tar Mcvf /dev/fd0 *
16561 When the first floppy is full tar(1) will prompt you to insert the next
16562 volume (because tar(1) is media independent it refers to volumes; in this
16563 context it means floppy disk).
16565 Prepare volume #2 for /dev/fd0 and hit return:
16567 This is repeated (with the volume number incrementing) until all the
16568 specified files have been archived.
16570 ----------------------------------------------------------------------
16572 12.9.3 Can I Compress My Backups?
16574 Unfortunately, tar(1) will not allow the -z option to be used for
16575 multi-volume archives. You could, of course, gzip(1) all the files, tar(1)
16576 them to the floppies, then gunzip(1) the files again!
16578 ----------------------------------------------------------------------
16580 12.9.4 How Do I Restore My Backups?
16582 To restore the entire archive use:
16584 # tar Mxvf /dev/fd0
16586 There are two ways that you can use to restore only specific files. First,
16587 you can start with the first floppy and use:
16589 # tar Mxvf /dev/fd0 filename
16591 The utility tar(1) will prompt you to insert subsequent floppies until it
16592 finds the required file.
16594 Alternatively, if you know which floppy the file is on then you can simply
16595 insert that floppy and use the same command as above. Note that if the
16596 first file on the floppy is a continuation from the previous one then
16597 tar(1) will warn you that it cannot restore it, even if you have not asked
16600 ----------------------------------------------------------------------
16602 12.10 Backup Basics
16604 The three major backup programs are dump(8), tar(1), and cpio(1).
16606 ----------------------------------------------------------------------
16608 12.10.1 Dump and Restore
16610 The traditional UNIX backup programs are dump and restore. They operate on
16611 the drive as a collection of disk blocks, below the abstractions of files,
16612 links and directories that are created by the file systems. dump backs up
16613 an entire file system on a device. It is unable to backup only part of a
16614 file system or a directory tree that spans more than one file system. dump
16615 does not write files and directories to tape, but rather writes the raw
16616 data blocks that comprise files and directories.
16618 Note: If you use dump on your root directory, you would not back up
16619 /home, /usr or many other directories since these are typically mount
16620 points for other file systems or symbolic links into those file systems.
16622 dump has quirks that remain from its early days in Version 6 of AT&T UNIX
16623 (circa 1975). The default parameters are suitable for 9-track tapes (6250
16624 bpi), not the high-density media available today (up to 62,182 ftpi).
16625 These defaults must be overridden on the command line to utilize the
16626 capacity of current tape drives.
16628 It is also possible to backup data across the network to a tape drive
16629 attached to another computer with rdump and rrestore. Both programs rely
16630 upon rcmd and ruserok to access the remote tape drive. Therefore, the user
16631 performing the backup must be listed in the .rhosts file on the remote
16632 computer. The arguments to rdump and rrestore must be suitable to use on
16633 the remote computer. When rdumping from a DragonFly computer to an Exabyte
16634 tape drive connected to a Sun called komodo, use:
16636 # /sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1
16638 Beware: there are security implications to allowing .rhosts
16639 authentication. Evaluate your situation carefully.
16641 It is also possible to use dump and restore in a more secure fashion over
16644 Example 12-1. Using dump over ssh
16646 # /sbin/dump -0uan -f - /usr | gzip -2 | ssh1 -c blowfish \
16647 targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz
16649 Or using dump's built-in method, setting the enviroment variable RSH:
16651 Example 12-2. Using dump over ssh with RSH set
16653 # RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0
16655 ----------------------------------------------------------------------
16659 tar(1) also dates back to Version 6 of AT&T UNIX (circa 1975). tar
16660 operates in cooperation with the file system; tar writes files and
16661 directories to tape. tar does not support the full range of options that
16662 are available from cpio(1), but tar does not require the unusual command
16663 pipeline that cpio uses.
16665 Most versions of tar do not support backups across the network. The GNU
16666 version of tar, which DragonFly utilizes, supports remote devices using
16667 the same syntax as rdump. To tar to an Exabyte tape drive connected to a
16668 Sun called komodo, use:
16670 # /usr/bin/tar cf komodo:/dev/nsa8 . 2>&1
16672 For versions without remote device support, you can use a pipeline and rsh
16673 to send the data to a remote tape drive.
16675 # tar cf - . | rsh hostname dd of=tape-device obs=20b
16677 If you are worried about the security of backing up over a network you
16678 should use the ssh command instead of rsh.
16680 ----------------------------------------------------------------------
16684 cpio(1) is the original UNIX file interchange tape program for magnetic
16685 media. cpio has options (among many others) to perform byte-swapping,
16686 write a number of different archive formats, and pipe the data to other
16687 programs. This last feature makes cpio an excellent choice for
16688 installation media. cpio does not know how to walk the directory tree and
16689 a list of files must be provided through stdin.
16691 cpio does not support backups across the network. You can use a pipeline
16692 and rsh to send the data to a remote tape drive.
16694 # for f in directory_list; do
16695 find $f >> backup.list
16697 # cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device"
16699 Where directory_list is the list of directories you want to back up,
16700 user@host is the user/hostname combination that will be performing the
16701 backups, and backup_device is where the backups should be written to
16704 ----------------------------------------------------------------------
16708 pax(1) is IEEE/POSIX's answer to tar and cpio. Over the years the various
16709 versions of tar and cpio have gotten slightly incompatible. So rather than
16710 fight it out to fully standardize them, POSIX created a new archive
16711 utility. pax attempts to read and write many of the various cpio and tar
16712 formats, plus new formats of its own. Its command set more resembles cpio
16715 ----------------------------------------------------------------------
16719 Amanda (Advanced Maryland Network Disk Archiver) is a client/server backup
16720 system, rather than a single program. An Amanda server will backup to a
16721 single tape drive any number of computers that have Amanda clients and a
16722 network connection to the Amanda server. A common problem at sites with a
16723 number of large disks is that the length of time required to backup to
16724 data directly to tape exceeds the amount of time available for the task.
16725 Amanda solves this problem. Amanda can use a ``holding disk'' to backup
16726 several file systems at the same time. Amanda creates ``archive sets'': a
16727 group of tapes used over a period of time to create full backups of all
16728 the file systems listed in Amanda's configuration file. The ``archive
16729 set'' also contains nightly incremental (or differential) backups of all
16730 the file systems. Restoring a damaged file system requires the most recent
16731 full backup and the incremental backups.
16733 The configuration file provides fine control of backups and the network
16734 traffic that Amanda generates. Amanda will use any of the above backup
16735 programs to write the data to tape. Amanda is available as either a port
16736 or a package, it is not installed by default.
16738 ----------------------------------------------------------------------
16742 ``Do nothing'' is not a computer program, but it is the most widely used
16743 backup strategy. There are no initial costs. There is no backup schedule
16744 to follow. Just say no. If something happens to your data, grin and bear
16747 If your time and your data is worth little to nothing, then ``Do nothing''
16748 is the most suitable backup program for your computer. But beware, UNIX is
16749 a useful tool, you may find that within six months you have a collection
16750 of files that are valuable to you.
16752 ``Do nothing'' is the correct backup method for /usr/obj and other
16753 directory trees that can be exactly recreated by your computer. An example
16754 is the files that comprise the HTML or PostScript version of this
16755 Handbook. These document formats have been created from SGML input files.
16756 Creating backups of the HTML or PostScript files is not necessary. The
16757 SGML files are backed up regularly.
16759 ----------------------------------------------------------------------
16761 12.10.7 Which Backup Program Is Best?
16763 dump(8) Period. Elizabeth D. Zwicky torture tested all the backup programs
16764 discussed here. The clear choice for preserving all your data and all the
16765 peculiarities of UNIX file systems is dump. Elizabeth created file systems
16766 containing a large variety of unusual conditions (and some not so unusual
16767 ones) and tested each program by doing a backup and restore of those file
16768 systems. The peculiarities included: files with holes, files with holes
16769 and a block of nulls, files with funny characters in their names,
16770 unreadable and unwritable files, devices, files that change size during
16771 the backup, files that are created/deleted during the backup and more. She
16772 presented the results at LISA V in Oct. 1991. Read the ``Torture-testing
16773 Backup and Archive Programs'' study for more information.
16775 ----------------------------------------------------------------------
16777 12.10.8 Emergency Restore Procedure
16779 12.10.8.1 Before the Disaster
16781 There are only four steps that you need to perform in preparation for any
16782 disaster that may occur.
16784 First, print the disklabel from each of your disks (e.g. disklabel da0 |
16785 lpr), your file system table (/etc/fstab) and all boot messages, two
16788 Second, determine that the boot and fix-it floppies (boot.flp and
16789 fixit.flp) have all your devices. The easiest way to check is to reboot
16790 your machine with the boot floppy in the floppy drive and check the boot
16791 messages. If all your devices are listed and functional, skip on to step
16794 Otherwise, you have to create two custom bootable floppies which have a
16795 kernel that can mount all of your disks and access your tape drive. These
16796 floppies must contain: fdisk, disklabel, newfs, mount, and whichever
16797 backup program you use. These programs must be statically linked. If you
16798 use dump, the floppy must contain restore.
16800 Third, create backup tapes regularly. Any changes that you make after your
16801 last backup may be irretrievably lost. Write-protect the backup tapes.
16803 Fourth, test the floppies (either boot.flp and fixit.flp or the two custom
16804 bootable floppies you made in step two.) and backup tapes. Make notes of
16805 the procedure. Store these notes with the bootable floppy, the printouts
16806 and the backup tapes. You will be so distraught when restoring that the
16807 notes may prevent you from destroying your backup tapes (How? In place of
16808 tar xvf /dev/sa0, you might accidentally type tar cvf /dev/sa0 and
16809 over-write your backup tape).
16811 For an added measure of security, make bootable floppies and two backup
16812 tapes each time. Store one of each at a remote location. A remote location
16813 is NOT the basement of the same office building. A number of firms in the
16814 World Trade Center learned this lesson the hard way. A remote location
16815 should be physically separated from your computers and disk drives by a
16816 significant distance.
16818 Example 12-3. A Script for Creating a Bootable Floppy
16822 # create a restore floppy
16824 # format the floppy
16826 PATH=/bin:/sbin:/usr/sbin:/usr/bin
16831 echo "Bad floppy, please use a new one"
16835 # place boot blocks on the floppy
16837 disklabel -w -B /dev/fd0c fd1440
16840 # newfs the one and only partition
16842 newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/fd0a
16845 # mount the new floppy
16847 mount /dev/fd0a /mnt
16850 # create required directories
16857 mkdir /mnt/mnt # for the root partition
16862 # populate the directories
16864 if [ ! -x /sys/compile/MINI/kernel ]
16867 The MINI kernel does not exist, please create one.
16868 Here is an example config file:
16870 # MINI -- A kernel to get &os; onto a disk.
16877 options INET # needed for _tcp _icmpstat _ipstat
16878 # _udpstat _tcpstat _udb
16879 options FFS #Berkeley Fast File System
16880 options FAT_CURSOR #block cursor in syscons or pccons
16881 options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device
16882 options NCONS=2 #1 virtual consoles
16883 options USERCONFIG #Allow user configuration with -c XXX
16885 config kernel root on da0 swap on da0 and da1 dumps on da0
16890 device fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr
16891 device fd0 at fdc0 drive 0
16897 device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr
16898 device npx0 at isa? port "IO_NPX" irq 13 vector npxintr
16906 pseudo-device loop # required by INET
16907 pseudo-device gzip # Exec gzipped a.out's
16912 cp -f /sys/compile/MINI/kernel /mnt
16914 gzip -c -best /sbin/init > /mnt/sbin/init
16915 gzip -c -best /sbin/fsck > /mnt/sbin/fsck
16916 gzip -c -best /sbin/mount > /mnt/sbin/mount
16917 gzip -c -best /sbin/halt > /mnt/sbin/halt
16918 gzip -c -best /sbin/restore > /mnt/sbin/restore
16920 gzip -c -best /bin/sh > /mnt/bin/sh
16921 gzip -c -best /bin/sync > /mnt/bin/sync
16923 cp /root/.profile /mnt/root
16925 cp -f /dev/MAKEDEV /mnt/dev
16926 chmod 755 /mnt/dev/MAKEDEV
16928 chmod 500 /mnt/sbin/init
16929 chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt
16930 chmod 555 /mnt/bin/sh /mnt/bin/sync
16931 chmod 6555 /mnt/sbin/restore
16934 # create the devices nodes
16946 # create minimum file system table
16948 cat > /mnt/etc/fstab <<EOM
16949 /dev/fd0a / ufs rw 1 1
16953 # create minimum passwd file
16955 cat > /mnt/etc/passwd <<EOM
16956 root:*:0:0:Charlie &:/root:/bin/sh
16959 cat > /mnt/etc/master.passwd <<EOM
16960 root::0:0::0:0:Charlie &:/root:/bin/sh
16963 chmod 600 /mnt/etc/master.passwd
16964 chmod 644 /mnt/etc/passwd
16965 /usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd
16968 # umount the floppy and inform the user
16971 echo "The floppy has been unmounted and is now ready."
16973 ----------------------------------------------------------------------
16975 12.10.8.2 After the Disaster
16977 The key question is: did your hardware survive? You have been doing
16978 regular backups so there is no need to worry about the software.
16980 If the hardware has been damaged, the parts should be replaced before
16981 attempting to use the computer.
16983 If your hardware is okay, check your floppies. If you are using a custom
16984 boot floppy, boot single-user (type -s at the boot: prompt). Skip the
16985 following paragraph.
16987 If you are using the boot.flp and fixit.flp floppies, keep reading. Insert
16988 the boot.flp floppy in the first floppy drive and boot the computer. The
16989 original install menu will be displayed on the screen. Select the
16990 Fixit--Repair mode with CDROM or floppy. option. Insert the fixit.flp when
16991 prompted. restore and the other programs that you need are located in
16994 Recover each file system separately.
16996 Try to mount (e.g. mount /dev/da0a /mnt) the root partition of your first
16997 disk. If the disklabel was damaged, use disklabel to re-partition and
16998 label the disk to match the label that you printed and saved. Use newfs to
16999 re-create the file systems. Re-mount the root partition of the floppy
17000 read-write (mount -u -o rw /mnt). Use your backup program and backup tapes
17001 to recover the data for this file system (e.g. restore vrf /dev/sa0).
17002 Unmount the file system (e.g. umount /mnt). Repeat for each file system
17005 Once your system is running, backup your data onto new tapes. Whatever
17006 caused the crash or data loss may strike again. Another hour spent now may
17007 save you from further distress later.
17009 ----------------------------------------------------------------------
17011 12.11 Network, Memory, and File-Backed File Systems
17013 Reorganized and enhanced by Marc Fonvieille.
17015 Aside from the disks you physically insert into your computer: floppies,
17016 CDs, hard drives, and so forth; other forms of disks are understood by
17017 DragonFly - the virtual disks.
17019 These include network file systems such as the Network File System and
17020 Coda, memory-based file systems and file-backed file systems.
17022 ----------------------------------------------------------------------
17024 12.11.1 File-Backed File System
17026 The utility vnconfig(8) configures and enables vnode pseudo-disk devices.
17027 A vnode is a representation of a file, and is the focus of file activity.
17028 This means that vnconfig(8) uses files to create and operate a file
17029 system. One possible use is the mounting of floppy or CD images kept in
17032 To use vnconfig(8), you need vn(4) support in your kernel configuration
17037 To mount an existing file system image:
17039 Example 12-4. Using vnconfig to Mount an Existing File System Image
17041 # vnconfig vn0 diskimage
17042 # mount /dev/vn0c /mnt
17044 To create a new file system image with vnconfig(8):
17046 Example 12-5. Creating a New File-Backed Disk with vnconfig
17048 # dd if=/dev/zero of=newimage bs=1k count=5k
17051 # vnconfig -s labels -c vn0 newimage
17052 # disklabel -r -w vn0 auto
17054 Warning: 2048 sector(s) in last cylinder unallocated
17055 /dev/vn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors
17056 5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g)
17057 super-block backups (for fsck -b #) at:
17059 # mount /dev/vn0c /mnt
17061 Filesystem 1K-blocks Used Avail Capacity Mounted on
17062 /dev/vn0c 4927 1 4532 0% /mnt
17064 ----------------------------------------------------------------------
17066 12.11.2 Memory-Based File System
17068 The md(4) driver is a simple, efficient means to create memory file
17069 systems. malloc(9) is used to allocate the memory.
17071 Simply take a file system you have prepared with, for example,
17074 Example 12-6. md Memory Disk
17076 # dd if=newimage of=/dev/md0
17079 # mount /dev/md0c /mnt
17081 Filesystem 1K-blocks Used Avail Capacity Mounted on
17082 /dev/md0c 4927 1 4532 0% /mnt
17084 For more details, please refer to md(4) manual page.
17086 ----------------------------------------------------------------------
17088 12.11.3 Detaching a Memory Disk from the System
17090 When a memory-based or file-based file system is not used, you should
17091 release all resources to the system. The first thing to do is to unmount
17092 the file system, then use mdconfig(8) to detach the disk from the system
17093 and release the resources.
17095 For example to detach and free all resources used by /dev/md4:
17099 It is possible to list information about configured md(4) devices in using
17100 the command mdconfig -l.
17102 vnconfig(8) is used to detach the device. For example to detach and free
17103 all resources used by /dev/vn4:
17107 ----------------------------------------------------------------------
17109 12.12 File System Quotas
17111 Quotas are an optional feature of the operating system that allow you to
17112 limit the amount of disk space and/or the number of files a user or
17113 members of a group may allocate on a per-file system basis. This is used
17114 most often on timesharing systems where it is desirable to limit the
17115 amount of resources any one user or group of users may allocate. This will
17116 prevent one user or group of users from consuming all of the available
17119 ----------------------------------------------------------------------
17121 12.12.1 Configuring Your System to Enable Disk Quotas
17123 Before attempting to use disk quotas, it is necessary to make sure that
17124 quotas are configured in your kernel. This is done by adding the following
17125 line to your kernel configuration file:
17129 The stock GENERIC kernel does not have this enabled by default, so you
17130 will have to configure, build and install a custom kernel in order to use
17131 disk quotas. Please refer to Chapter 9 for more information on kernel
17134 Next you will need to enable disk quotas in /etc/rc.conf. This is done by
17137 enable_quotas="YES"
17139 For finer control over your quota startup, there is an additional
17140 configuration variable available. Normally on bootup, the quota integrity
17141 of each file system is checked by the quotacheck(8) program. The
17142 quotacheck(8) facility insures that the data in the quota database
17143 properly reflects the data on the file system. This is a very time
17144 consuming process that will significantly affect the time your system
17145 takes to boot. If you would like to skip this step, a variable in
17146 /etc/rc.conf is made available for the purpose:
17150 Finally you will need to edit /etc/fstab to enable disk quotas on a
17151 per-file system basis. This is where you can either enable user or group
17152 quotas or both for all of your file systems.
17154 To enable per-user quotas on a file system, add the userquota option to
17155 the options field in the /etc/fstab entry for the file system you want to
17156 enable quotas on. For example:
17158 /dev/da1s2g /home ufs rw,userquota 1 2
17160 Similarly, to enable group quotas, use the groupquota option instead of
17161 userquota. To enable both user and group quotas, change the entry as
17164 /dev/da1s2g /home ufs rw,userquota,groupquota 1 2
17166 By default, the quota files are stored in the root directory of the file
17167 system with the names quota.user and quota.group for user and group quotas
17168 respectively. See fstab(5) for more information. Even though the fstab(5)
17169 manual page says that you can specify an alternate location for the quota
17170 files, this is not recommended because the various quota utilities do not
17171 seem to handle this properly.
17173 At this point you should reboot your system with your new kernel. /etc/rc
17174 will automatically run the appropriate commands to create the initial
17175 quota files for all of the quotas you enabled in /etc/fstab, so there is
17176 no need to manually create any zero length quota files.
17178 In the normal course of operations you should not be required to run the
17179 quotacheck(8), quotaon(8), or quotaoff(8) commands manually. However, you
17180 may want to read their manual pages just to be familiar with their
17183 ----------------------------------------------------------------------
17185 12.12.2 Setting Quota Limits
17187 Once you have configured your system to enable quotas, verify that they
17188 really are enabled. An easy way to do this is to run:
17192 You should see a one line summary of disk usage and current quota limits
17193 for each file system that quotas are enabled on.
17195 You are now ready to start assigning quota limits with the edquota(8)
17198 You have several options on how to enforce limits on the amount of disk
17199 space a user or group may allocate, and how many files they may create.
17200 You may limit allocations based on disk space (block quotas) or number of
17201 files (inode quotas) or a combination of both. Each of these limits are
17202 further broken down into two categories: hard and soft limits.
17204 A hard limit may not be exceeded. Once a user reaches his hard limit he
17205 may not make any further allocations on the file system in question. For
17206 example, if the user has a hard limit of 500 blocks on a file system and
17207 is currently using 490 blocks, the user can only allocate an additional 10
17208 blocks. Attempting to allocate an additional 11 blocks will fail.
17210 Soft limits, on the other hand, can be exceeded for a limited amount of
17211 time. This period of time is known as the grace period, which is one week
17212 by default. If a user stays over his or her soft limit longer than the
17213 grace period, the soft limit will turn into a hard limit and no further
17214 allocations will be allowed. When the user drops back below the soft
17215 limit, the grace period will be reset.
17217 The following is an example of what you might see when you run the
17218 edquota(8) command. When the edquota(8) command is invoked, you are placed
17219 into the editor specified by the EDITOR environment variable, or in the vi
17220 editor if the EDITOR variable is not set, to allow you to edit the quota
17225 Quotas for user test:
17226 /usr: blocks in use: 65, limits (soft = 50, hard = 75)
17227 inodes in use: 7, limits (soft = 50, hard = 60)
17228 /usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
17229 inodes in use: 0, limits (soft = 50, hard = 60)
17231 You will normally see two lines for each file system that has quotas
17232 enabled. One line for the block limits, and one line for inode limits.
17233 Simply change the value you want updated to modify the quota limit. For
17234 example, to raise this user's block limit from a soft limit of 50 and a
17235 hard limit of 75 to a soft limit of 500 and a hard limit of 600, change:
17237 /usr: blocks in use: 65, limits (soft = 50, hard = 75)
17241 /usr: blocks in use: 65, limits (soft = 500, hard = 600)
17243 The new quota limits will be in place when you exit the editor.
17245 Sometimes it is desirable to set quota limits on a range of UIDs. This can
17246 be done by use of the -p option on the edquota(8) command. First, assign
17247 the desired quota limit to a user, and then run edquota -p protouser
17248 startuid-enduid. For example, if user test has the desired quota limits,
17249 the following command can be used to duplicate those quota limits for UIDs
17250 10,000 through 19,999:
17252 # edquota -p test 10000-19999
17254 For more information see edquota(8) manual page.
17256 ----------------------------------------------------------------------
17258 12.12.3 Checking Quota Limits and Disk Usage
17260 You can use either the quota(1) or the repquota(8) commands to check quota
17261 limits and disk usage. The quota(1) command can be used to check
17262 individual user or group quotas and disk usage. A user may only examine
17263 his own quota, and the quota of a group he is a member of. Only the
17264 super-user may view all user and group quotas. The repquota(8) command can
17265 be used to get a summary of all quotas and disk usage for file systems
17266 with quotas enabled.
17268 The following is some sample output from the quota -v command for a user
17269 that has quota limits on two file systems.
17271 Disk quotas for user test (uid 1002):
17272 Filesystem blocks quota limit grace files quota limit grace
17273 /usr 65* 50 75 5days 7 50 60
17274 /usr/var 0 50 75 0 50 60
17276 On the /usr file system in the above example, this user is currently 15
17277 blocks over the soft limit of 50 blocks and has 5 days of the grace period
17278 left. Note the asterisk * which indicates that the user is currently over
17281 Normally file systems that the user is not using any disk space on will
17282 not show up in the output from the quota(1) command, even if he has a
17283 quota limit assigned for that file system. The -v option will display
17284 those file systems, such as the /usr/var file system in the above example.
17286 ----------------------------------------------------------------------
17288 12.12.4 Quotas over NFS
17290 Quotas are enforced by the quota subsystem on the NFS server. The
17291 rpc.rquotad(8) daemon makes quota information available to the quota(1)
17292 command on NFS clients, allowing users on those machines to see their
17295 Enable rpc.rquotad in /etc/inetd.conf like so:
17297 rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad
17301 # kill -HUP `cat /var/run/inetd.pid`
17303 ----------------------------------------------------------------------
17305 Chapter 13 The Vinum Volume Manager
17307 Contributed by Greg Lehey.
17311 No matter what disks you have, there will always be limitations:
17313 * They can be too small.
17315 * They can be too slow.
17317 * They can be too unreliable.
17319 ----------------------------------------------------------------------
17321 13.2 Disks Are Too Small
17323 Originally written by Greg Lehey.
17325 Vinum is a so-called Volume Manager, a virtual disk driver that addresses
17326 these three problems. Let us look at them in more detail. Various
17327 solutions to these problems have been proposed and implemented:
17329 Disks are getting bigger, but so are data storage requirements. Often you
17330 will find you want a file system that is bigger than the disks you have
17331 available. Admittedly, this problem is not as acute as it was ten years
17332 ago, but it still exists. Some systems have solved this by creating an
17333 abstract device which stores its data on a number of disks.
17335 ----------------------------------------------------------------------
17337 13.3 Access Bottlenecks
17339 Modern systems frequently need to access data in a highly concurrent
17340 manner. For example, large FTP or HTTP servers can maintain thousands of
17341 concurrent sessions and have multiple 100 Mbit/s connections to the
17342 outside world, well beyond the sustained transfer rate of most disks.
17344 Current disk drives can transfer data sequentially at up to 70 MB/s, but
17345 this value is of little importance in an environment where many
17346 independent processes access a drive, where they may achieve only a
17347 fraction of these values. In such cases it is more interesting to view the
17348 problem from the viewpoint of the disk subsystem: the important parameter
17349 is the load that a transfer places on the subsystem, in other words the
17350 time for which a transfer occupies the drives involved in the transfer.
17352 In any disk transfer, the drive must first position the heads, wait for
17353 the first sector to pass under the read head, and then perform the
17354 transfer. These actions can be considered to be atomic: it does not make
17355 any sense to interrupt them.
17357 Consider a typical transfer of about 10 kB: the current generation of
17358 high-performance disks can position the heads in an average of 3.5 ms. The
17359 fastest drives spin at 15,000 rpm, so the average rotational latency (half
17360 a revolution) is 2 ms. At 70 MB/s, the transfer itself takes about 150 ms,
17361 almost nothing compared to the positioning time. In such a case, the
17362 effective transfer rate drops to a little over 1 MB/s and is clearly
17363 highly dependent on the transfer size.
17365 The traditional and obvious solution to this bottleneck is ``more
17366 spindles'': rather than using one large disk, it uses several smaller
17367 disks with the same aggregate storage space. Each disk is capable of
17368 positioning and transferring independently, so the effective throughput
17369 increases by a factor close to the number of disks used.
17371 The exact throughput improvement is, of course, smaller than the number of
17372 disks involved: although each drive is capable of transferring in
17373 parallel, there is no way to ensure that the requests are evenly
17374 distributed across the drives. Inevitably the load on one drive will be
17375 higher than on another.
17377 The evenness of the load on the disks is strongly dependent on the way the
17378 data is shared across the drives. In the following discussion, it is
17379 convenient to think of the disk storage as a large number of data sectors
17380 which are addressable by number, rather like the pages in a book. The most
17381 obvious method is to divide the virtual disk into groups of consecutive
17382 sectors the size of the individual physical disks and store them in this
17383 manner, rather like taking a large book and tearing it into smaller
17384 sections. This method is called concatenation and has the advantage that
17385 the disks are not required to have any specific size relationships. It
17386 works well when the access to the virtual disk is spread evenly about its
17387 address space. When access is concentrated on a smaller area, the
17388 improvement is less marked. Figure 13-1 illustrates the sequence in which
17389 storage units are allocated in a concatenated organization.
17391 Figure 13-1. Concatenated Organization
17393 An alternative mapping is to divide the address space into smaller,
17394 equal-sized components and store them sequentially on different devices.
17395 For example, the first 256 sectors may be stored on the first disk, the
17396 next 256 sectors on the next disk and so on. After filling the last disk,
17397 the process repeats until the disks are full. This mapping is called
17398 striping or RAID-0 [11]. Striping requires somewhat more effort to locate
17399 the data, and it can cause additional I/O load where a transfer is spread
17400 over multiple disks, but it can also provide a more constant load across
17401 the disks. Figure 13-2 illustrates the sequence in which storage units are
17402 allocated in a striped organization.
17404 Figure 13-2. Striped Organization
17406 ----------------------------------------------------------------------
17408 13.4 Data Integrity
17410 The final problem with current disks is that they are unreliable. Although
17411 disk drive reliability has increased tremendously over the last few years,
17412 they are still the most likely core component of a server to fail. When
17413 they do, the results can be catastrophic: replacing a failed disk drive
17414 and restoring data to it can take days.
17416 The traditional way to approach this problem has been mirroring, keeping
17417 two copies of the data on different physical hardware. Since the advent of
17418 the RAID levels, this technique has also been called RAID level 1 or
17419 RAID-1. Any write to the volume writes to both locations; a read can be
17420 satisfied from either, so if one drive fails, the data is still available
17421 on the other drive.
17423 Mirroring has two problems:
17425 * The price. It requires twice as much disk storage as a non-redundant
17428 * The performance impact. Writes must be performed to both drives, so
17429 they take up twice the bandwidth of a non-mirrored volume. Reads do
17430 not suffer from a performance penalty: it even looks as if they are
17433 An alternative solution is parity, implemented in the RAID levels 2, 3, 4
17434 and 5. Of these, RAID-5 is the most interesting. As implemented in Vinum,
17435 it is a variant on a striped organization which dedicates one block of
17436 each stripe to parity of the other blocks. As implemented by Vinum, a
17437 RAID-5 plex is similar to a striped plex, except that it implements RAID-5
17438 by including a parity block in each stripe. As required by RAID-5, the
17439 location of this parity block changes from one stripe to the next. The
17440 numbers in the data blocks indicate the relative block numbers.
17442 Figure 13-3. RAID-5 Organization
17444 Compared to mirroring, RAID-5 has the advantage of requiring significantly
17445 less storage space. Read access is similar to that of striped
17446 organizations, but write access is significantly slower, approximately 25%
17447 of the read performance. If one drive fails, the array can continue to
17448 operate in degraded mode: a read from one of the remaining accessible
17449 drives continues normally, but a read from the failed drive is
17450 recalculated from the corresponding block from all the remaining drives.
17452 ----------------------------------------------------------------------
17456 In order to address these problems, Vinum implements a four-level
17457 hierarchy of objects:
17459 * The most visible object is the virtual disk, called a volume. Volumes
17460 have essentially the same properties as a UNIX disk drive, though
17461 there are some minor differences. They have no size limitations.
17463 * Volumes are composed of plexes, each of which represent the total
17464 address space of a volume. This level in the hierarchy thus provides
17465 redundancy. Think of plexes as individual disks in a mirrored array,
17466 each containing the same data.
17468 * Since Vinum exists within the UNIX disk storage framework, it would be
17469 possible to use UNIX partitions as the building block for multi-disk
17470 plexes, but in fact this turns out to be too inflexible: UNIX disks
17471 can have only a limited number of partitions. Instead, Vinum
17472 subdivides a single UNIX partition (the drive) into contiguous areas
17473 called subdisks, which it uses as building blocks for plexes.
17475 * Subdisks reside on Vinum drives, currently UNIX partitions. Vinum
17476 drives can contain any number of subdisks. With the exception of a
17477 small area at the beginning of the drive, which is used for storing
17478 configuration and state information, the entire drive is available for
17481 The following sections describe the way these objects provide the
17482 functionality required of Vinum.
17484 ----------------------------------------------------------------------
17486 13.5.1 Volume Size Considerations
17488 Plexes can include multiple subdisks spread over all drives in the Vinum
17489 configuration. As a result, the size of an individual drive does not limit
17490 the size of a plex, and thus of a volume.
17492 ----------------------------------------------------------------------
17494 13.5.2 Redundant Data Storage
17496 Vinum implements mirroring by attaching multiple plexes to a volume. Each
17497 plex is a representation of the data in a volume. A volume may contain
17498 between one and eight plexes.
17500 Although a plex represents the complete data of a volume, it is possible
17501 for parts of the representation to be physically missing, either by design
17502 (by not defining a subdisk for parts of the plex) or by accident (as a
17503 result of the failure of a drive). As long as at least one plex can
17504 provide the data for the complete address range of the volume, the volume
17505 is fully functional.
17507 ----------------------------------------------------------------------
17509 13.5.3 Performance Issues
17511 Vinum implements both concatenation and striping at the plex level:
17513 * A concatenated plex uses the address space of each subdisk in turn.
17515 * A striped plex stripes the data across each subdisk. The subdisks must
17516 all have the same size, and there must be at least two subdisks in
17517 order to distinguish it from a concatenated plex.
17519 ----------------------------------------------------------------------
17521 13.5.4 Which Plex Organization?
17523 Vinum implements two kinds of plex:
17525 * Concatenated plexes are the most flexible: they can contain any number
17526 of subdisks, and the subdisks may be of different length. The plex may
17527 be extended by adding additional subdisks. They require less CPU time
17528 than striped plexes, though the difference in CPU overhead is not
17529 measurable. On the other hand, they are most susceptible to hot spots,
17530 where one disk is very active and others are idle.
17532 * The greatest advantage of striped (RAID-0) plexes is that they reduce
17533 hot spots: by choosing an optimum sized stripe (about 256 kB), you can
17534 even out the load on the component drives. The disadvantages of this
17535 approach are (fractionally) more complex code and restrictions on
17536 subdisks: they must be all the same size, and extending a plex by
17537 adding new subdisks is so complicated that Vinum currently does not
17538 implement it. Vinum imposes an additional, trivial restriction: a
17539 striped plex must have at least two subdisks, since otherwise it is
17540 indistinguishable from a concatenated plex.
17542 Table 13-1 summarizes the advantages and disadvantages of each plex
17545 Table 13-1. Vinum Plex Organizations
17547 +------------------------------------------------------------------------+
17548 | | Minimum | Can add | Must be | |
17549 | Plex type | subdisks | subdisks | equal | Application |
17551 |--------------+----------+----------+---------+-------------------------|
17552 | | | | | Large data storage with |
17553 | concatenated | 1 | yes | no | maximum placement |
17554 | | | | | flexibility and |
17555 | | | | | moderate performance |
17556 |--------------+----------+----------+---------+-------------------------|
17557 | | | | | High performance in |
17558 | striped | 2 | no | yes | combination with highly |
17559 | | | | | concurrent access |
17560 +------------------------------------------------------------------------+
17562 ----------------------------------------------------------------------
17566 Vinum maintains a configuration database which describes the objects known
17567 to an individual system. Initially, the user creates the configuration
17568 database from one or more configuration files with the aid of the vinum(8)
17569 utility program. Vinum stores a copy of its configuration database on each
17570 disk slice (which Vinum calls a device) under its control. This database
17571 is updated on each state change, so that a restart accurately restores the
17572 state of each Vinum object.
17574 ----------------------------------------------------------------------
17576 13.6.1 The Configuration File
17578 The configuration file describes individual Vinum objects. The definition
17579 of a simple volume might be:
17581 drive a device /dev/da3h
17584 sd length 512m drive a
17586 This file describes four Vinum objects:
17588 * The drive line describes a disk partition (drive) and its location
17589 relative to the underlying hardware. It is given the symbolic name a.
17590 This separation of the symbolic names from the device names allows
17591 disks to be moved from one location to another without confusion.
17593 * The volume line describes a volume. The only required attribute is the
17594 name, in this case myvol.
17596 * The plex line defines a plex. The only required parameter is the
17597 organization, in this case concat. No name is necessary: the system
17598 automatically generates a name from the volume name by adding the
17599 suffix .px, where x is the number of the plex in the volume. Thus this
17600 plex will be called myvol.p0.
17602 * The sd line describes a subdisk. The minimum specifications are the
17603 name of a drive on which to store it, and the length of the subdisk.
17604 As with plexes, no name is necessary: the system automatically assigns
17605 names derived from the plex name by adding the suffix .sx, where x is
17606 the number of the subdisk in the plex. Thus Vinum gives this subdisk
17607 the name myvol.p0.s0.
17609 After processing this file, vinum(8) produces the following output:
17611 # vinum -> create config1
17612 Configuration summary
17613 Drives: 1 (4 configured)
17614 Volumes: 1 (4 configured)
17615 Plexes: 1 (8 configured)
17616 Subdisks: 1 (16 configured)
17618 D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)
17620 V myvol State: up Plexes: 1 Size: 512 MB
17622 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17624 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17626 This output shows the brief listing format of vinum(8). It is represented
17627 graphically in Figure 13-4.
17629 Figure 13-4. A Simple Vinum Volume
17631 This figure, and the ones which follow, represent a volume, which contains
17632 the plexes, which in turn contain the subdisks. In this trivial example,
17633 the volume contains one plex, and the plex contains one subdisk.
17635 This particular volume has no specific advantage over a conventional disk
17636 partition. It contains a single plex, so it is not redundant. The plex
17637 contains a single subdisk, so there is no difference in storage allocation
17638 from a conventional disk partition. The following sections illustrate
17639 various more interesting configuration methods.
17641 ----------------------------------------------------------------------
17643 13.6.2 Increased Resilience: Mirroring
17645 The resilience of a volume can be increased by mirroring. When laying out
17646 a mirrored volume, it is important to ensure that the subdisks of each
17647 plex are on different drives, so that a drive failure will not take down
17648 both plexes. The following configuration mirrors a volume:
17650 drive b device /dev/da4h
17653 sd length 512m drive a
17655 sd length 512m drive b
17657 In this example, it was not necessary to specify a definition of drive a
17658 again, since Vinum keeps track of all objects in its configuration
17659 database. After processing this definition, the configuration looks like:
17661 Drives: 2 (4 configured)
17662 Volumes: 2 (4 configured)
17663 Plexes: 3 (8 configured)
17664 Subdisks: 3 (16 configured)
17666 D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)
17667 D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)
17669 V myvol State: up Plexes: 1 Size: 512 MB
17670 V mirror State: up Plexes: 2 Size: 512 MB
17672 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17673 P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
17674 P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
17676 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17677 S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
17678 S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
17680 Figure 13-5 shows the structure graphically.
17682 Figure 13-5. A Mirrored Vinum Volume
17684 In this example, each plex contains the full 512 MB of address space. As
17685 in the previous example, each plex contains only a single subdisk.
17687 ----------------------------------------------------------------------
17689 13.6.3 Optimizing Performance
17691 The mirrored volume in the previous example is more resistant to failure
17692 than an unmirrored volume, but its performance is less: each write to the
17693 volume requires a write to both drives, using up a greater proportion of
17694 the total disk bandwidth. Performance considerations demand a different
17695 approach: instead of mirroring, the data is striped across as many disk
17696 drives as possible. The following configuration shows a volume with a plex
17697 striped across four disk drives:
17699 drive c device /dev/da5h
17700 drive d device /dev/da6h
17702 plex org striped 512k
17703 sd length 128m drive a
17704 sd length 128m drive b
17705 sd length 128m drive c
17706 sd length 128m drive d
17708 As before, it is not necessary to define the drives which are already
17709 known to Vinum. After processing this definition, the configuration looks
17712 Drives: 4 (4 configured)
17713 Volumes: 3 (4 configured)
17714 Plexes: 4 (8 configured)
17715 Subdisks: 7 (16 configured)
17717 D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%)
17718 D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%)
17719 D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%)
17720 D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%)
17722 V myvol State: up Plexes: 1 Size: 512 MB
17723 V mirror State: up Plexes: 2 Size: 512 MB
17724 V striped State: up Plexes: 1 Size: 512 MB
17726 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17727 P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
17728 P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
17729 P striped.p1 State: up Subdisks: 1 Size: 512 MB
17731 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17732 S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
17733 S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
17734 S striped.p0.s0 State: up PO: 0 B Size: 128 MB
17735 S striped.p0.s1 State: up PO: 512 kB Size: 128 MB
17736 S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB
17737 S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB
17739 Figure 13-6. A Striped Vinum Volume
17741 This volume is represented in Figure 13-6. The darkness of the stripes
17742 indicates the position within the plex address space: the lightest stripes
17743 come first, the darkest last.
17745 ----------------------------------------------------------------------
17747 13.6.4 Resilience and Performance
17749 With sufficient hardware, it is possible to build volumes which show both
17750 increased resilience and increased performance compared to standard UNIX
17751 partitions. A typical configuration file might be:
17754 plex org striped 512k
17755 sd length 102480k drive a
17756 sd length 102480k drive b
17757 sd length 102480k drive c
17758 sd length 102480k drive d
17759 sd length 102480k drive e
17760 plex org striped 512k
17761 sd length 102480k drive c
17762 sd length 102480k drive d
17763 sd length 102480k drive e
17764 sd length 102480k drive a
17765 sd length 102480k drive b
17767 The subdisks of the second plex are offset by two drives from those of the
17768 first plex: this helps ensure that writes do not go to the same subdisks
17769 even if a transfer goes over two drives.
17771 Figure 13-7 represents the structure of this volume.
17773 Figure 13-7. A Mirrored, Striped Vinum Volume
17775 ----------------------------------------------------------------------
17779 As described above, Vinum assigns default names to plexes and subdisks,
17780 although they may be overridden. Overriding the default names is not
17781 recommended: experience with the VERITAS volume manager, which allows
17782 arbitrary naming of objects, has shown that this flexibility does not
17783 bring a significant advantage, and it can cause confusion.
17785 Names may contain any non-blank character, but it is recommended to
17786 restrict them to letters, digits and the underscore characters. The names
17787 of volumes, plexes and subdisks may be up to 64 characters long, and the
17788 names of drives may be up to 32 characters long.
17790 Vinum objects are assigned device nodes in the hierarchy /dev/vinum. The
17791 configuration shown above would cause Vinum to create the following device
17794 * The control devices /dev/vinum/control and /dev/vinum/controld, which
17795 are used by vinum(8) and the Vinum daemon respectively.
17797 * Block and character device entries for each volume. These are the main
17798 devices used by Vinum. The block device names are the name of the
17799 volume, while the character device names follow the BSD tradition of
17800 prepending the letter r to the name. Thus the configuration above
17801 would include the block devices /dev/vinum/myvol, /dev/vinum/mirror,
17802 /dev/vinum/striped, /dev/vinum/raid5 and /dev/vinum/raid10, and the
17803 character devices /dev/vinum/rmyvol, /dev/vinum/rmirror,
17804 /dev/vinum/rstriped, /dev/vinum/rraid5 and /dev/vinum/rraid10. There
17805 is obviously a problem here: it is possible to have two volumes called
17806 r and rr, but there will be a conflict creating the device node
17807 /dev/vinum/rr: is it a character device for volume r or a block device
17808 for volume rr? Currently Vinum does not address this conflict: the
17809 first-defined volume will get the name.
17811 * A directory /dev/vinum/drive with entries for each drive. These
17812 entries are in fact symbolic links to the corresponding disk nodes.
17814 * A directory /dev/vinum/volume with entries for each volume. It
17815 contains subdirectories for each plex, which in turn contain
17816 subdirectories for their component subdisks.
17818 * The directories /dev/vinum/plex, /dev/vinum/sd, and /dev/vinum/rsd,
17819 which contain block device nodes for each plex and block and character
17820 device nodes respectively for each subdisk.
17822 For example, consider the following configuration file:
17824 drive drive1 device /dev/sd1h
17825 drive drive2 device /dev/sd2h
17826 drive drive3 device /dev/sd3h
17827 drive drive4 device /dev/sd4h
17828 volume s64 setupstate
17829 plex org striped 64k
17830 sd length 100m drive drive1
17831 sd length 100m drive drive2
17832 sd length 100m drive drive3
17833 sd length 100m drive drive4
17835 After processing this file, vinum(8) creates the following structure in
17838 brwx------ 1 root wheel 25, 0x40000001 Apr 13 16:46 Control
17839 brwx------ 1 root wheel 25, 0x40000002 Apr 13 16:46 control
17840 brwx------ 1 root wheel 25, 0x40000000 Apr 13 16:46 controld
17841 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 drive
17842 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex
17843 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 rs64
17844 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rsd
17845 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rvol
17846 brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
17847 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd
17848 drwxr-xr-x 3 root wheel 512 Apr 13 16:46 vol
17852 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive1 -> /dev/sd1h
17853 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive2 -> /dev/sd2h
17854 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive3 -> /dev/sd3h
17855 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive4 -> /dev/sd4h
17859 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
17863 crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0
17864 crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1
17865 crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2
17866 crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3
17870 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
17874 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
17875 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
17876 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
17877 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3
17881 brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
17882 drwxr-xr-x 3 root wheel 512 Apr 13 16:46 s64.plex
17884 /dev/vinum/vol/s64.plex:
17886 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
17887 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 s64.p0.sd
17889 /dev/vinum/vol/s64.plex/s64.p0.sd:
17891 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
17892 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
17893 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
17894 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3
17896 Although it is recommended that plexes and subdisks should not be
17897 allocated specific names, Vinum drives must be named. This makes it
17898 possible to move a drive to a different location and still recognize it
17899 automatically. Drive names may be up to 32 characters long.
17901 ----------------------------------------------------------------------
17903 13.7.1 Creating File Systems
17905 Volumes appear to the system to be identical to disks, with one exception.
17906 Unlike UNIX drives, Vinum does not partition volumes, which thus do not
17907 contain a partition table. This has required modification to some disk
17908 utilities, notably newfs(8), which previously tried to interpret the last
17909 letter of a Vinum volume name as a partition identifier. For example, a
17910 disk drive may have a name like /dev/ad0a or /dev/da2h. These names
17911 represent the first partition (a) on the first (0) IDE disk (ad) and the
17912 eighth partition (h) on the third (2) SCSI disk (da) respectively. By
17913 contrast, a Vinum volume might be called /dev/vinum/concat, a name which
17914 has no relationship with a partition name.
17916 Normally, newfs(8) interprets the name of the disk and complains if it
17917 cannot understand it. For example:
17919 # newfs /dev/vinum/concat
17920 newfs: /dev/vinum/concat: can't figure out file system partition
17922 ----------------------------------------------------------------------
17924 13.8 Configuring Vinum
17926 The GENERIC kernel does not contain Vinum. It is possible to build a
17927 special kernel which includes Vinum, but this is not recommended. The
17928 standard way to start Vinum is as a kernel module (kld). You do not even
17929 need to use kldload(8) for Vinum: when you start vinum(8), it checks
17930 whether the module has been loaded, and if it is not, it loads it
17933 ----------------------------------------------------------------------
17937 Vinum stores configuration information on the disk slices in essentially
17938 the same form as in the configuration files. When reading from the
17939 configuration database, Vinum recognizes a number of keywords which are
17940 not allowed in the configuration files. For example, a disk configuration
17941 might contain the following text:
17943 volume myvol state up
17944 volume bigraid state down
17945 plex name myvol.p0 state up org concat vol myvol
17946 plex name myvol.p1 state up org concat vol myvol
17947 plex name myvol.p2 state init org striped 512b vol myvol
17948 plex name bigraid.p0 state initializing org raid5 512b vol bigraid
17949 sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b
17950 sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b
17951 sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b
17952 sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b
17953 sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b
17954 sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b
17955 sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b
17956 sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b
17957 sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b
17958 sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b
17959 sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b
17960 sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b
17961 sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b
17963 The obvious differences here are the presence of explicit location
17964 information and naming (both of which are also allowed, but discouraged,
17965 for use by the user) and the information on the states (which are not
17966 available to the user). Vinum does not store information about drives in
17967 the configuration information: it finds the drives by scanning the
17968 configured disk drives for partitions with a Vinum label. This enables
17969 Vinum to identify drives correctly even if they have been assigned
17970 different UNIX drive IDs.
17972 ----------------------------------------------------------------------
17974 13.8.1.1 Automatic Startup
17976 In order to start Vinum automatically when you boot the system, ensure
17977 that you have the following line in your /etc/rc.conf:
17979 start_vinum="YES" # set to YES to start vinum
17981 If you do not have a file /etc/rc.conf, create one with this content. This
17982 will cause the system to load the Vinum kld at startup, and to start any
17983 objects mentioned in the configuration. This is done before mounting file
17984 systems, so it is possible to automatically fsck(8) and mount file systems
17987 When you start Vinum with the vinum start command, Vinum reads the
17988 configuration database from one of the Vinum drives. Under normal
17989 circumstances, each drive contains an identical copy of the configuration
17990 database, so it does not matter which drive is read. After a crash,
17991 however, Vinum must determine which drive was updated most recently and
17992 read the configuration from this drive. It then updates the configuration
17993 if necessary from progressively older drives.
17995 ----------------------------------------------------------------------
17997 13.9 Using Vinum for the Root Filesystem
17999 For a machine that has fully-mirrored filesystems using Vinum, it is
18000 desirable to also mirror the root filesystem. Setting up such a
18001 configuration is less trivial than mirroring an arbitrary filesystem
18004 * The root filesystem must be available very early during the boot
18005 process, so the Vinum infrastructure must already be available at this
18008 * The volume containing the root filesystem also contains the system
18009 bootstrap and the kernel, which must be read using the host system's
18010 native utilities (e. g. the BIOS on PC-class machines) which often
18011 cannot be taught about the details of Vinum.
18013 In the following sections, the term ``root volume'' is generally used to
18014 describe the Vinum volume that contains the root filesystem. It is
18015 probably a good idea to use the name "root" for this volume, but this is
18016 not technically required in any way. All command examples in the following
18017 sections assume this name though.
18019 ----------------------------------------------------------------------
18021 13.9.1 Starting up Vinum Early Enough for the Root Filesystem
18023 There are several measures to take for this to happen:
18025 * Vinum must be available in the kernel at boot-time. Thus, the method
18026 to start Vinum automatically described in Section 13.8.1.1 is not
18027 applicable to accomplish this task, and the start_vinum parameter must
18028 actually not be set when the following setup is being arranged. The
18029 first option would be to compile Vinum statically into the kernel, so
18030 it is available all the time, but this is usually not desirable. There
18031 is another option as well, to have /boot/loader (Section 7.3.3) load
18032 the vinum kernel module early, before starting the kernel. This can be
18033 accomplished by putting the line
18037 into the file /boot/loader.conf.
18039 * Vinum must be initialized early since it needs to supply the volume
18040 for the root filesystem. By default, the Vinum kernel part is not
18041 looking for drives that might contain Vinum volume information until
18042 the administrator (or one of the startup scripts) issues a vinum start
18045 Vinum must explicitly be told which disks to scan, using a line like
18046 the following one in /boot/loader.conf:
18048 vinum.drives="/dev/da0 /dev/da1"
18050 It is important that all drives are mentioned that could possibly
18051 contain Vinum data. It does not harm if more drives are listed, nor is
18052 it necessary to add each slice and/or partition explicitly, since
18053 Vinum will scan all slices and partitions of the named drives for
18054 valid Vinum headers.
18056 Since the routines used to parse the name of the root filesystem, and
18057 derive the device ID (major/minor number) are only prepared to handle
18058 ``classical'' device names like /dev/ad0s1a, they cannot make any
18059 sense out of a root volume name like /dev/vinum/root. For that reason,
18060 Vinum itself needs to pre-setup the internal kernel parameter that
18061 holds the ID of the root device during its own initialization. This is
18062 requested by passing the name of the root volume in the loader
18063 variable vinum.root. The entry in /boot/loader.conf to accomplish this
18068 Now, when the kernel initialization tries to find out the root device
18069 to mount, it sees whether some kernel module has already
18070 pre-initialized the kernel parameter for it. If that is the case, and
18071 the device claiming the root device matches the major number of the
18072 driver as figured out from the name of the root device string being
18073 passed (that is, "vinum" in our case), it will use the pre-allocated
18074 device ID, instead of trying to figure out one itself. That way,
18075 during the usual automatic startup, it can continue to mount the Vinum
18076 root volume for the root filesystem.
18078 However, when boot -a has been requesting to ask for entering the name
18079 of the root device manually, it must be noted that this routine still
18080 cannot actually parse a name entered there that refers to a Vinum
18081 volume. If any device name is entered that does not refer to a Vinum
18082 device, the mismatch between the major numbers of the pre-allocated
18083 root parameter and the driver as figured out from the given name will
18084 make this routine enter its normal parser, so entering a string like
18085 ufs:da0d will work as expected. Note that if this fails, it is however
18086 no longer possible to re-enter a string like ufs:vinum/root again,
18087 since it cannot be parsed. The only way out is to reboot again, and
18088 start over then. (At the ``askroot'' prompt, the initial /dev/ can
18089 always be omitted.)
18091 By placing the line:
18093 vinum.drives="/dev/da0 /dev/da1"
18095 vinum.autostart="YES"
18097 into /boot/loader.conf, Vinum is instructed to automatically scan all
18098 drives for Vinum information as part of the kernel startup.
18100 It is important that all drives are mentioned that could possibly
18101 contain Vinum data. It does not harm if more drives are listed, nor is
18102 it necessary to add each slice and/or partition explicitly, since
18103 Vinum will scan all slices and partitions of the named drives for
18104 valid Vinum headers.
18106 Vinum itself needs to pre-setup the internal kernel parameter that
18107 holds the ID of the root device during its own initialization. This is
18108 requested by passing the name of the root volume in the loader
18109 variable vinum.root. The entry in /boot/loader.conf to accomplish this
18114 Now, when the kernel initialization tries to find out the root device
18115 to mount, it sees whether some kernel module has already
18116 pre-initialized the kernel parameter for it. If that is the case, and
18117 the device claiming the root device matches the major number of the
18118 driver as figured out from the name of the root device string being
18119 passed (that is, "vinum" in our case), it will use the pre-allocated
18120 device ID, instead of trying to figure out one itself. That way,
18121 during the usual automatic startup, it can continue to mount the Vinum
18122 root volume for the root filesystem.
18124 However, when boot -a has been requesting to ask for entering the name
18125 of the root device manually, it must be noted that this routine still
18126 cannot actually parse a name entered there that refers to a Vinum
18127 volume. If any device name is entered that does not refer to a Vinum
18128 device, the mismatch between the major numbers of the pre-allocated
18129 root parameter and the driver as figured out from the given name will
18130 make this routine enter its normal parser, so entering a string like
18131 ufs:da0d will work as expected. Note that if this fails, it is however
18132 no longer possible to re-enter a string like ufs:vinum/root again,
18133 since it cannot be parsed. The only way out is to reboot again, and
18134 start over then. (At the ``askroot'' prompt, the initial /dev/ can
18135 always be omitted.)
18137 ----------------------------------------------------------------------
18139 13.9.2 Making a Vinum-based Root Volume Accessible to the Bootstrap
18141 Since the current DragonFly bootstrap is very small, and already has the
18142 burden of reading files (like /boot/loader) from the UFS filesystem, it is
18143 sheer impossible to also teach it about internal Vinum structures so it
18144 could parse the Vinum configuration data, and figure out about the
18145 elements of a boot volume itself. Thus, some tricks are necessary to
18146 provide the bootstrap code with the illusion of a standard "a" partition
18147 that contains the root filesystem.
18149 For this to be possible at all, the following requirements must be met for
18152 * The root volume must not be striped or RAID-5.
18154 * The root volume must not contain more than one concatenated subdisk
18157 Note that it is desirable and possible that there are multiple plexes,
18158 each containing one replica of the root filesystem. The bootstrap process
18159 will, however, only use one of these replica for finding the bootstrap and
18160 all the files, until the kernel will eventually mount the root filesystem
18161 itself. Each single subdisk within these plexes will then need its own "a"
18162 partition illusion, for the respective device to become bootable. It is
18163 not strictly needed that each of these faked "a" partitions is located at
18164 the same offset within its device, compared with other devices containing
18165 plexes of the root volume. However, it is probably a good idea to create
18166 the Vinum volumes that way so the resulting mirrored devices are
18167 symmetric, to avoid confusion.
18169 In order to set up these "a" partitions, for each device containing part
18170 of the root volume, the following needs to be done:
18172 1. The location (offset from the beginning of the device) and size of
18173 this device's subdisk that is part of the root volume need to be
18174 examined, using the command
18178 Note that Vinum offsets and sizes are measured in bytes. They must be
18179 divided by 512 in order to obtain the block numbers that are to be
18180 used in the disklabel command.
18184 disklabel -e devname
18186 for each device that participates in the root volume. devname must be
18187 either the name of the disk (like da0) for disks without a slice (aka.
18188 fdisk) table, or the name of the slice (like ad0s1).
18190 If there is already an "a" partition on the device (presumably,
18191 containing a pre-Vinum root filesystem), it should be renamed to
18192 something else, so it remains accessible (just in case), but will no
18193 longer be used by default to bootstrap the system. Note that active
18194 partitions (like a root filesystem currently mounted) cannot be
18195 renamed, so this must be executed either when being booted from a
18196 ``Fixit'' medium, or in a two-step process, where (in a mirrored
18197 situation) the disk that has not been currently booted is being
18200 Then, the offset the Vinum partition on this device (if any) must be
18201 added to the offset of the respective root volume subdisk on this
18202 device. The resulting value will become the "offset" value for the new
18203 "a" partition. The "size" value for this partition can be taken
18204 verbatim from the calculation above. The "fstype" should be 4.2BSD.
18205 The "fsize", "bsize", and "cpg" values should best be chosen to match
18206 the actual filesystem, though they are fairly unimportant within this
18209 That way, a new "a" partition will be established that overlaps the
18210 Vinum partition on this device. Note that the disklabel will only
18211 allow for this overlap if the Vinum partition has properly been marked
18212 using the "vinum" fstype.
18214 3. That's all! A faked "a" partition does exist now on each device that
18215 has one replica of the root volume. It is highly recommendable to
18216 verify the result again, using a command like
18218 fsck -n /dev/devnamea
18220 It should be remembered that all files containing control information must
18221 be relative to the root filesystem in the Vinum volume which, when setting
18222 up a new Vinum root volume, might not match the root filesystem that is
18223 currently active. So in particular, the files /etc/fstab and
18224 /boot/loader.conf need to be taken care of.
18226 At next reboot, the bootstrap should figure out the appropriate control
18227 information from the new Vinum-based root filesystem, and act accordingly.
18228 At the end of the kernel initialization process, after all devices have
18229 been announced, the prominent notice that shows the success of this setup
18232 Mounting root from ufs:/dev/vinum/root
18234 ----------------------------------------------------------------------
18236 13.9.3 Example of a Vinum-based Root Setup
18238 After the Vinum root volume has been set up, the output of vinum l -rv
18239 root could look like:
18242 Subdisk root.p0.s0:
18243 Size: 125829120 bytes (120 MB)
18245 Plex root.p0 at offset 0 (0 B)
18246 Drive disk0 (/dev/da0h) at offset 135680 (132 kB)
18248 Subdisk root.p1.s0:
18249 Size: 125829120 bytes (120 MB)
18251 Plex root.p1 at offset 0 (0 B)
18252 Drive disk1 (/dev/da1h) at offset 135680 (132 kB)
18255 The values to note are 135680 for the offset (relative to partition
18256 /dev/da0h). This translates to 265 512-byte disk blocks in disklabel's
18257 terms. Likewise, the size of this root volume is 245760 512-byte blocks.
18258 /dev/da1h, containing the second replica of this root volume, has a
18261 The disklabel for these devices might look like:
18265 # size offset fstype [fsize bsize bps/cpg]
18266 a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*)
18267 c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*)
18268 h: 71771672 16 vinum # (Cyl. 0*- 4467*)
18271 It can be observed that the "size" parameter for the faked "a" partition
18272 matches the value outlined above, while the "offset" parameter is the sum
18273 of the offset within the Vinum partition "h", and the offset of this
18274 partition within the device (or slice). This is a typical setup that is
18275 necessary to avoid the problem described in Section 13.9.4.3. It can also
18276 be seen that the entire "a" partition is completely within the "h"
18277 partition containing all the Vinum data for this device.
18279 Note that in the above example, the entire device is dedicated to Vinum,
18280 and there is no leftover pre-Vinum root partition, since this has been a
18281 newly set-up disk that was only meant to be part of a Vinum configuration,
18284 ----------------------------------------------------------------------
18286 13.9.4 Troubleshooting
18288 If something goes wrong, a way is needed to recover from the situation.
18289 The following list contains few known pitfalls and solutions.
18291 ----------------------------------------------------------------------
18293 13.9.4.1 System Bootstrap Loads, but System Does Not Boot
18295 If for any reason the system does not continue to boot, the bootstrap can
18296 be interrupted with by pressing the space key at the 10-seconds warning.
18297 The loader variables (like vinum.autostart) can be examined using the
18298 show, and manipulated using set or unset commands.
18300 If the only problem was that the Vinum kernel module was not yet in the
18301 list of modules to load automatically, a simple load vinum will help.
18303 When ready, the boot process can be continued with a boot -as. The options
18304 -as will request the kernel to ask for the root filesystem to mount (-a),
18305 and make the boot process stop in single-user mode (-s), where the root
18306 filesystem is mounted read-only. That way, even if only one plex of a
18307 multi-plex volume has been mounted, no data inconsistency between plexes
18310 At the prompt asking for a root filesystem to mount, any device that
18311 contains a valid root filesystem can be entered. If /etc/fstab had been
18312 set up correctly, the default should be something like
18313 ufs:/dev/vinum/root. A typical alternate choice would be something like
18314 ufs:da0d which could be a hypothetical partition that contains the
18315 pre-Vinum root filesystem. Care should be taken if one of the alias "a"
18316 partitions are entered here that are actually reference to the subdisks of
18317 the Vinum root device, because in a mirrored setup, this would only mount
18318 one piece of a mirrored root device. If this filesystem is to be mounted
18319 read-write later on, it is necessary to remove the other plex(es) of the
18320 Vinum root volume since these plexes would otherwise carry inconsistent
18323 ----------------------------------------------------------------------
18325 13.9.4.2 Only Primary Bootstrap Loads
18327 If /boot/loader fails to load, but the primary bootstrap still loads
18328 (visible by a single dash in the left column of the screen right after the
18329 boot process starts), an attempt can be made to interrupt the primary
18330 bootstrap at this point, using the space key. This will make the bootstrap
18331 stop in stage two, see Section 7.3.2. An attempt can be made here to boot
18332 off an alternate partition, like the partition containing the previous
18333 root filesystem that has been moved away from "a" above.
18335 ----------------------------------------------------------------------
18337 13.9.4.3 Nothing Boots, the Bootstrap Panics
18339 This situation will happen if the bootstrap had been destroyed by the
18340 Vinum installation. Unfortunately, Vinum accidentally currently leaves
18341 only 4 KB at the beginning of its partition free before starting to write
18342 its Vinum header information. However, the stage one and two bootstraps
18343 plus the disklabel embedded between them currently require 8 KB. So if a
18344 Vinum partition was started at offset 0 within a slice or disk that was
18345 meant to be bootable, the Vinum setup will trash the bootstrap.
18347 Similarly, if the above situation has been recovered, for example by
18348 booting from a ``Fixit'' medium, and the bootstrap has been re-installed
18349 using disklabel -B as described in Section 7.3.2, the bootstrap will trash
18350 the Vinum header, and Vinum will no longer find its disk(s). Though no
18351 actual Vinum configuration data or data in Vinum volumes will be trashed
18352 by this, and it would be possible to recover all the data by entering
18353 exact the same Vinum configuration data again, the situation is hard to
18354 fix at all. It would be necessary to move the entire Vinum partition by at
18355 least 4 KB off, in order to have the Vinum header and the system bootstrap
18358 ----------------------------------------------------------------------
18360 Chapter 14 Localization - I18N/L10N Usage and Setup
18362 Contributed by Andrey A. Chernov. Rewritten by Michael C. Wu.
18366 DragonFly is a very distributed project with users and contributors
18367 located all over the world. This chapter discusses the
18368 internationalization and localization features of DragonFly that allow
18369 non-English speaking users to get real work done. There are many aspects
18370 of the i18n implementation in both the system and application levels, so
18371 where applicable we refer the reader to more specific sources of
18374 After reading this chapter, you will know:
18376 * How different languages and locales are encoded on modern operating
18379 * How to set the locale for your login shell.
18381 * How to configure your console for non-English languages.
18383 * How to use X Window System effectively with different languages.
18385 * Where to find more information about writing i18n-compliant
18388 Before reading this chapter, you should:
18390 * Know how to install additional third-party applications (Chapter 4).
18392 ----------------------------------------------------------------------
18396 14.2.1 What Is I18N/L10N?
18398 Developers shortened internationalization into the term I18N, counting the
18399 number of letters between the first and the last letters of
18400 internationalization. L10N uses the same naming scheme, coming from
18401 ``localization''. Combined together, I18N/L10N methods, protocols, and
18402 applications allow users to use languages of their choice.
18404 I18N applications are programmed using I18N kits under libraries. It
18405 allows for developers to write a simple file and translate displayed menus
18406 and texts to each language. We strongly encourage programmers to follow
18409 ----------------------------------------------------------------------
18411 14.2.2 Why Should I Use I18N/L10N?
18413 I18N/L10N is used whenever you wish to either view, input, or process data
18414 in non-English languages.
18416 ----------------------------------------------------------------------
18418 14.2.3 What Languages Are Supported in the I18N Effort?
18420 I18N and L10N are not DragonFly specific. Currently, one can choose from
18421 most of the major languages of the World, including but not limited to:
18422 Chinese, German, Japanese, Korean, French, Russian, Vietnamese and others.
18424 ----------------------------------------------------------------------
18426 14.3 Using Localization
18428 In all its splendor, I18N is not DragonFly-specific and is a convention.
18429 We encourage you to help DragonFly in following this convention.
18431 Localization settings are based on three main terms: Language Code,
18432 Country Code, and Encoding. Locale names are constructed from these parts
18435 LanguageCode_CountryCode.Encoding
18437 ----------------------------------------------------------------------
18439 14.3.1 Language and Country Codes
18441 In order to localize a DragonFly system to a specific language (or any
18442 other I18N-supporting UNIX like systems), the user needs to find out the
18443 codes for the specify country and language (country codes tell
18444 applications what variation of given language to use). In addition, web
18445 browsers, SMTP/POP servers, web servers, etc. make decisions based on
18446 them. The following are examples of language/country codes:
18448 Language/Country Code Description
18449 en_US English - United States
18450 ru_RU Russian for Russia
18451 zh_TW Traditional Chinese for Taiwan
18453 ----------------------------------------------------------------------
18457 Some languages use non-ASCII encodings that are 8-bit, wide or multibyte
18458 characters, see multibyte(3) for more details. Older applications do not
18459 recognize them and mistake them for control characters. Newer applications
18460 usually do recognize 8-bit characters. Depending on the implementation,
18461 users may be required to compile an application with wide or multibyte
18462 characters support, or configure it correctly. To be able to input and
18463 process wide or multibyte characters, the FreeBSD Ports collection has
18464 provided each language with different programs. Refer to the I18N
18465 documentation in the respective FreeBSD Port.
18467 Specifically, the user needs to look at the application documentation to
18468 decide on how to configure it correctly or to pass correct values into the
18469 configure/Makefile/compiler.
18471 Some things to keep in mind are:
18473 * Language specific single C chars character sets (see multibyte(3)),
18474 e.g. ISO-8859-1, ISO-8859-15, KOI8-R, CP437.
18476 * Wide or multibyte encodings, e.g. EUC, Big5.
18478 You can check the active list of character sets at the IANA Registry.
18480 Note: DragonFly uses X11-compatible locale encodings instead.
18482 ----------------------------------------------------------------------
18484 14.3.3 I18N Applications
18486 In the FreeBSD Ports and Package system, I18N applications have been named
18487 with I18N in their names for easy identification. However, they do not
18488 always support the language needed.
18490 ----------------------------------------------------------------------
18492 14.3.4 Setting Locale
18494 Usually it is sufficient to export the value of the locale name as LANG in
18495 the login shell. This could be done in the user's ~/.login_conf file or in
18496 the startup file of the user's shell (~/.profile, ~/.bashrc, ~/.cshrc).
18497 There is no need to set the locale subsets such as LC_CTYPE, LC_CTIME.
18498 Please refer to language-specific DragonFly documentation for more
18501 You should set the following two environment variables in your
18502 configuration files:
18504 * LANG for POSIX setlocale(3) family functions
18506 * MM_CHARSET for applications' MIME character set
18508 This includes the user shell configuration, the specific application
18509 configuration, and the X11 configuration.
18511 ----------------------------------------------------------------------
18513 14.3.4.1 Setting Locale Methods
18515 There are two methods for setting locale, and both are described below.
18516 The first (recommended one) is by assigning the environment variables in
18517 login class, and the second is by adding the environment variable
18518 assignments to the system's shell startup file.
18520 ----------------------------------------------------------------------
18522 14.3.4.1.1 Login Classes Method
18524 This method allows environment variables needed for locale name and MIME
18525 character sets to be assigned once for every possible shell instead of
18526 adding specific shell assignments to each shell's startup file. User Level
18527 Setup can be done by an user himself and Administrator Level Setup require
18528 superuser privileges.
18530 ----------------------------------------------------------------------
18532 14.3.4.1.1.1 User Level Setup
18534 Here is a minimal example of a .login_conf file in user's home directory
18535 which has both variables set for Latin-1 encoding:
18538 :charset=ISO-8859-1:\
18539 :lang=de_DE.ISO8859-1:
18541 Here is an example of a .login_conf that sets the variables for
18542 Traditional Chinese in BIG-5 encoding. Notice the many more variables set
18543 because some software does not respect locale variables correctly for
18544 Chinese, Japanese, and Korean.
18546 #Users who do not wish to use monetary units or time formats
18547 #of Taiwan can manually change each variable
18550 :lc_all=zh_TW.Big:\
18551 :lc_collate=zh_TW.Big5:\
18552 :lc_ctype=zh_TW.Big5:\
18553 :lc_messages=zh_TW.Big5:\
18554 :lc_monetary=zh_TW.Big5:\
18555 :lc_numeric=zh_TW.Big5:\
18556 :lc_time=zh_TW.Big5:\
18558 :xmodifiers="@im=xcin": #Setting the XIM Input Server
18560 See Administrator Level Setup and login.conf(5) for more details.
18562 ----------------------------------------------------------------------
18564 14.3.4.1.1.2 Administrator Level Setup
18566 Verify that the user's login class in /etc/login.conf sets the correct
18567 language. Make sure these settings appear in /etc/login.conf:
18569 language_name:accounts_title:\
18570 :charset=MIME_charset:\
18571 :lang=locale_name:\
18574 So sticking with our previous example using Latin-1, it would look like
18577 german:German Users Accounts:\
18578 :charset=ISO-8859-1:\
18579 :lang=de_DE.ISO8859-1:\
18582 Changing Login Classes with vipw(8)
18584 Use vipw to add new users, and make the entry look like this:
18586 user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh
18588 Changing Login Classes with adduser(8)
18590 Use adduser to add new users, and do the following:
18592 * Set defaultclass = language in /etc/adduser.conf. Keep in mind you
18593 must enter a default class for all users of other languages in this
18596 * An alternative variant is answering the specified language each time
18599 Enter login class: default []:
18601 appears from adduser(8).
18603 * Another alternative is to use the following for each user of a
18604 different language that you wish to add:
18606 # adduser -class language
18608 Changing Login Classes with pw(8)
18610 If you use pw(8) for adding new users, call it in this form:
18612 # pw useradd user_name -L language
18614 ----------------------------------------------------------------------
18616 14.3.4.1.2 Shell Startup File Method
18618 Note: This method is not recommended because it requires a different
18619 setup for each possible shell program chosen. Use the Login Class Method
18622 To add the locale name and MIME character set, just set the two
18623 environment variables shown below in the /etc/profile and/or
18624 /etc/csh.login shell startup files. We will use the German language as an
18629 LANG=de_DE.ISO8859-1; export LANG
18630 MM_CHARSET=ISO-8859-1; export MM_CHARSET
18632 Or in /etc/csh.login:
18634 setenv LANG de_DE.ISO8859-1
18635 setenv MM_CHARSET ISO-8859-1
18637 Alternatively, you can add the above instructions to
18638 /usr/share/skel/dot.profile (similar to what was used in /etc/profile
18639 above), or /usr/share/skel/dot.login (similar to what was used in
18640 /etc/csh.login above).
18646 LANG=de_DE.ISO8859-1; export LANG
18650 setenv LANG de_DE.ISO8859-1
18652 Depending on your shell (see above).
18654 ----------------------------------------------------------------------
18656 14.3.5 Console Setup
18658 For all single C chars character sets, set the correct console fonts in
18659 /etc/rc.conf for the language in question with:
18665 The font_name here is taken from the /usr/share/syscons/fonts directory,
18666 without the .fnt suffix.
18668 Also be sure to set the correct keymap and screenmap for your single C
18669 chars character set. You can add the following to /etc/rc.conf:
18671 scrnmap=screenmap_name
18673 keychange="fkey_number sequence"
18675 The screenmap_name here is taken from the /usr/share/syscons/scrnmaps
18676 directory, without the .scm suffix. A screenmap with a corresponding
18677 mapped font is usually needed as a workaround for expanding bit 8 to bit 9
18678 on a VGA adapter's font character matrix in pseudographics area, i.e., to
18679 move letters out of that area if screen font uses a bit 8 column.
18681 If you have the moused daemon enabled by setting the following in your
18684 moused_enable="YES"
18686 then examine the mouse cursor information in the next paragraph.
18688 By default the mouse cursor of the syscons(4) driver occupies the
18689 0xd0-0xd3 range in the character set. If your language uses this range,
18690 you need to move the cursor's range outside of it. To enable this
18691 workaround, insert the following line into your kernel configuration:
18693 options SC_MOUSE_CHAR=0x03
18695 Insert the following line into /etc/rc.conf:
18699 The keymap_name here is taken from the /usr/share/syscons/keymaps
18700 directory, without the .kbd suffix. If you're uncertain which keymap to
18701 use, you use can kbdmap(1) to test keymaps without rebooting.
18703 The keychange is usually needed to program function keys to match the
18704 selected terminal type because function key sequences cannot be defined in
18707 Also be sure to set the correct console terminal type in /etc/ttys for all
18708 ttyv* entries. Current pre-defined correspondences are:
18710 Character Set Terminal Type
18711 ISO-8859-1 or ISO-8859-15 cons25l1
18712 ISO-8859-2 cons25l2
18713 ISO-8859-7 cons25l7
18716 CP437 (VGA default) cons25
18719 For wide or multibyte characters languages, use the correct FreeBSD port
18720 in your /usr/ports/language directory. Some ports appear as console while
18721 the system sees it as serial vtty's, hence you must reserve enough vtty's
18722 for both X11 and the pseudo-serial console. Here is a partial list of
18723 applications for using other languages in console:
18726 Traditional Chinese (BIG-5) chinese/big5con
18727 Japanese japanese/ja-kon2-* or japanese/Mule_Wnn
18728 Korean korean/ko-han
18730 ----------------------------------------------------------------------
18734 Although X11 is not part of DragonFly, we have included some information
18735 here for DragonFly users. For more details, refer to the XFree86 web site
18736 or whichever X11 Server you use.
18738 In ~/.Xresources, you can additionally tune application specific I18N
18739 settings (e.g., fonts, menus, etc.).
18741 ----------------------------------------------------------------------
18743 14.3.6.1 Displaying Fonts
18745 Install the X11 TrueType Common server (x11-servers/XttXF86srv-common) and
18746 install the language TrueType fonts. Setting the correct locale should
18747 allow you to view your selected language in menus and such.
18749 ----------------------------------------------------------------------
18751 14.3.6.2 Inputting Non-English Characters
18753 The X11 Input Method (XIM) Protocol is a new standard for all X11 clients.
18754 All X11 applications should be written as XIM clients that take input from
18755 XIM Input servers. There are several XIM servers available for different
18758 ----------------------------------------------------------------------
18760 14.3.7 Printer Setup
18762 Some single C chars character sets are usually hardware coded into
18763 printers. Wide or multibyte character sets require special setup and we
18764 recommend using apsfilter. You may also convert the document to PostScript
18765 or PDF formats using language specific converters.
18767 ----------------------------------------------------------------------
18769 14.3.8 Kernel and File Systems
18771 The DragonFly fast filesystem (FFS) is 8-bit clean, so it can be used with
18772 any single C chars character set (see multibyte(3)), but there is no
18773 character set name stored in the filesystem; i.e., it is raw 8-bit and
18774 does not know anything about encoding order. Officially, FFS does not
18775 support any form of wide or multibyte character sets yet. However, some
18776 wide or multibyte character sets have independent patches for FFS enabling
18777 such support. They are only temporary unportable solutions or hacks and we
18778 have decided to not include them in the source tree. Refer to respective
18779 languages' web sites for more informations and the patch files.
18781 The DragonFly MS-DOS filesystem has the configurable ability to convert
18782 between MS-DOS, Unicode character sets and chosen DragonFly filesystem
18783 character sets. See mount_msdos(8) for details.
18785 ----------------------------------------------------------------------
18787 14.4 Compiling I18N Programs
18789 Many FreeBSD Ports have been ported with I18N support. Some of them are
18790 marked with -I18N in the port name. These and many other programs have
18791 built in support for I18N and need no special consideration.
18793 However, some applications such as MySQL need to be have the Makefile
18794 configured with the specific charset. This is usually done in the Makefile
18795 or done by passing a value to configure in the source.
18797 ----------------------------------------------------------------------
18799 14.5 Localizing DragonFly to Specific Languages
18801 14.5.1 Russian Language (KOI8-R Encoding)
18803 Originally contributed by Andrey A. Chernov.
18805 For more information about KOI8-R encoding, see the KOI8-R References
18806 (Russian Net Character Set).
18808 ----------------------------------------------------------------------
18810 14.5.1.1 Locale Setup
18812 Put the following lines into your ~/.login_conf file:
18816 :lang=ru_RU.KOI8-R:
18818 See earlier in this chapter for examples of setting up the locale.
18820 ----------------------------------------------------------------------
18822 14.5.1.2 Console Setup
18824 * Add the following line to your kernel configuration file:
18826 options SC_MOUSE_CHAR=0x03
18828 Insert the following line into /etc/rc.conf:
18832 * Use following settings in /etc/rc.conf:
18835 scrnmap="koi8-r2cp866"
18836 font8x16="cp866b-8x16"
18837 font8x14="cp866-8x14"
18838 font8x8="cp866-8x8"
18840 * For each ttyv* entry in /etc/ttys, use cons25r as the terminal type.
18842 See earlier in this chapter for examples of setting up the console.
18844 ----------------------------------------------------------------------
18846 14.5.1.3 Printer Setup
18848 Since most printers with Russian characters come with hardware code page
18849 CP866, a special output filter is needed to convert from KOI8-R to CP866.
18850 Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A
18851 Russian printer /etc/printcap entry should look like:
18853 lp|Russian local line printer:\
18854 :sh:of=/usr/libexec/lpr/ru/koi2alt:\
18855 :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
18857 See printcap(5) for a detailed description.
18859 ----------------------------------------------------------------------
18861 14.5.1.4 MS-DOS(R) FS and Russian Filenames
18863 The following example fstab(5) entry enables support for Russian filenames
18864 in mounted MS-DOS filesystems:
18866 /dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0
18868 The option -L selects the locale name used, and -W sets the character
18869 conversion table. To use the -W option, be sure to mount /usr before the
18870 MS-DOS partition because the conversion tables are located in
18871 /usr/libdata/msdosfs. For more informations, see the mount_msdos(8) manual
18874 ----------------------------------------------------------------------
18878 1. Do non-X locale setup first as described.
18880 Note: The Russian KOI8-R locale may not work with old XFree86
18881 releases (lower than 3.3). XFree86 4.X is now the default version of
18882 the X Window System on DragonFly. This should not be an issue unless
18883 you explicitly install an older version of XFree86.
18885 2. Go to the russian/X.language directory and issue the following
18890 The above port installs the latest version of the KOI8-R fonts.
18891 XFree86 3.3 already has some KOI8-R fonts, but these are scaled
18894 Check the "Files" section in your /etc/XF86Config file. The following
18895 lines must be added before any other FontPath entries:
18897 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
18898 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
18899 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"
18901 If you use a high resolution video mode, swap the 75 dpi and 100 dpi
18904 3. To activate a Russian keyboard, add the following to the "Keyboard"
18905 section of your XF86Config file.
18910 XkbOptions "grp:caps_toggle"
18914 Option "XkbLayout" "ru"
18915 Option "XkbOptions" "grp:caps_toggle"
18917 Also make sure that XkbDisable is turned off (commented out) there.
18919 The RUS/LAT switch will be CapsLock. The old CapsLock function is
18920 still available via Shift+CapsLock (in LAT mode only).
18922 If you have ``Windows'' keys on your keyboard, and notice that some
18923 non-alphabetical keys are mapped incorrectly in RUS mode, add the
18924 following line in your XF86Config file.
18928 XkbVariant "winkeys"
18932 Option "XkbVariant" "winkeys"
18934 Note: The Russian XKB keyboard may not work with old XFree86
18935 versions, see the above note for more information. The Russian XKB
18936 keyboard may also not work with non-localized applications as well.
18937 Minimally localized applications should call a XtSetLanguageProc
18938 (NULL, NULL, NULL); function early in the program. See KOI8-R for X
18939 Window for more instructions on localizing X11 applications.
18941 ----------------------------------------------------------------------
18943 14.5.2 Traditional Chinese Localization for Taiwan
18945 The FreeBSD-Taiwan Project has an I18N/L10N tutorial for FreeBSD at
18946 http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/ using many Chinese ports.
18947 Much of that project can apply to DragonFly. The editor for the
18948 zh-L10N-tut is Clive Lin <Clive@CirX.org>. You can also cvsup the
18949 following collections at freebsd.sinica.edu.tw:
18951 Collection Description
18952 outta-port tag=. Beta-quality ports collection for Chinese
18953 zh-L10N-tut tag=. Localizing FreeBSD Tutorial in BIG-5 Traditional Chinese
18954 zh-doc tag=. FreeBSD Documentation Translation to BIG-5 Traditional
18957 Chuan-Hsing Shen <s874070@mail.yzu.edu.tw> has created the Chinese FreeBSD
18958 Collection (CFC) using FreeBSD-Taiwan's zh-L10N-tut. The packages and the
18959 script files are available at
18960 ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/.
18962 ----------------------------------------------------------------------
18964 14.5.3 German Language Localization (for All ISO 8859-1 Languages)
18966 Slaven Rezic <eserte@cs.tu-berlin.de> wrote a tutorial how to use umlauts
18967 on a FreeBSD machine. The tutorial is written in German and available at
18968 http://www.de.FreeBSD.org/de/umlaute/.
18970 ----------------------------------------------------------------------
18972 14.5.4 Japanese and Korean Language Localization
18974 For Japanese, refer to http://www.jp.FreeBSD.org/, and for Korean, refer
18975 to http://www.kr.FreeBSD.org/.
18977 ----------------------------------------------------------------------
18979 14.5.5 Non-English DragonFly Documentation
18981 Non-English documentation will be made available as it is created, at the
18982 main site or in /usr/share/doc.
18984 ----------------------------------------------------------------------
18986 Chapter 15 Desktop Applications
18988 Contributed by Christophe Juniet.
18992 DragonFly can run a wide variety of desktop applications, such as browsers
18993 and word processors. Most of these are available as packages or can be
18994 automatically built from the ports collection. Many new users expect to
18995 find these kinds of applications on their desktop. This chapter will show
18996 you how to install some popular desktop applications effortlessly, either
18997 from their packages or from the ports collection.
18999 Warning: This chapter contains a number of outdated references to the
19000 FreeBSD ports collection. Most instructions still apply to pkgsrc, but
19001 proceed with caution until this chapter is updated.
19003 Note that when installing programs from the ports, they are compiled from
19004 source. This can take a very long time, depending on what you are
19005 compiling and the processing power of your machine(s). If building from
19006 source takes a prohibitively long amount of time for you, you can install
19007 most of the programs of the ports collection from pre-built packages.
19009 As DragonFly features Linux binary compatibility, many applications
19010 originally developed for Linux are available for your desktop. It is
19011 strongly recommended that you read Chapter 22 before installing any of the
19012 Linux applications. Many of the ports using the Linux binary compatibility
19013 start with ``linux-''. Remember this when you search for a particular
19014 port, for instance with whereis(1). In the following text, it is assumed
19015 that you have enabled Linux binary compatibility before installing any of
19016 the Linux applications.
19018 Here are the categories covered by this chapter:
19020 * Browsers (such as Mozilla, Netscape, Opera)
19022 * Productivity (such as KOffice, AbiWord, The GIMP, OpenOffice.org)
19024 * Document Viewers (such as Acrobat Reader(R), gv, Xpdf, GQview)
19026 * Finance (such as GnuCash, Gnumeric, Abacus)
19028 Before reading this chapter, you should:
19030 * Know how to install additional third-party software (Chapter 4).
19032 * Know how to install additional Linux software (Chapter 22).
19034 For information on how to get a multimedia environment, read Chapter 16.
19035 If you want to set up and use electronic mail, please refer to Chapter 20.
19037 ----------------------------------------------------------------------
19041 DragonFly does not come with a particular browser pre-installed. Instead,
19042 the www directory of the ports collection contains a lot of browsers ready
19043 to be installed. If you do not have time to compile everything (this can
19044 take a very long time in some cases) many of them are available as
19047 KDE and GNOME already provide HTML browsers. Please refer to Section 5.7
19048 for more information on how to set up these complete desktops.
19050 If you are looking for light-weight browsers, you should investigate the
19051 ports collection for www/dillo, www/links, or www/w3m.
19053 This section covers these applications:
19055 +------------------------------------------------------------------------+
19056 | Application | Resources | Installation | Major Dependencies |
19057 | Name | Needed | from Ports | |
19058 |-------------+-----------+--------------+-------------------------------|
19059 | Mozilla | heavy | heavy | Gtk+ |
19060 |-------------+-----------+--------------+-------------------------------|
19061 | Netscape | heavy | light | Linux Binary Compatibility |
19062 |-------------+-----------+--------------+-------------------------------|
19063 | | | | FreeBSD version (should work |
19064 | | | | on DragonFly): None. Linux |
19065 | Opera | light | light | version: Linux Binary |
19066 | | | | Compatibility and |
19067 | | | | linux-openmotif |
19068 +------------------------------------------------------------------------+
19070 ----------------------------------------------------------------------
19074 Mozilla is perhaps the most suitable browser for your DragonFly Desktop.
19075 It is modern and stable. It features a very standards-compliant HTML
19076 display engine. It provides a mail and news reader. It even has a HTML
19077 composer if you plan to write some web pages yourself. Users of Netscape
19078 will recognize the similarities with Communicator suite, as both browsers
19079 shared the same basis.
19081 On slow machines, with a CPU speed less than 233MHz or with less than 64MB
19082 of RAM, Mozilla can be too resource-consuming to be fully usable. You may
19083 want to look at the Opera browser instead, described a little later in
19086 The Mozilla package from the network by:
19090 If the package is not available, and you have enough time and disk space,
19091 you can get the source for Mozilla, compile it and install it on your
19092 system. This is accomplished by:
19094 # cd /usr/ports/www/mozilla
19095 # make install clean
19097 The Mozilla port ensures a correct initialization by running the chrome
19098 registry setup with root privileges. However, if you want to fetch some
19099 add-ons like mouse gestures, you must run Mozilla as root to get them
19100 properly installed.
19102 Once you have completed the installation of Mozilla, you do not need to be
19103 root any longer. You can start Mozilla as a browser by typing:
19107 You can start it directly as a mail and news reader as shown below:
19111 ----------------------------------------------------------------------
19113 15.2.2 Mozilla, Java(TM), and Macromedia(R) Flash(TM)
19115 Contributed by Tom Rhodes.
19117 Installing Mozilla is simple, but unfortunately installing Mozilla with
19118 support for add-ons like Java(TM) and Macromedia(R) Flash(TM) consumes
19119 both time and disk space.
19121 The first thing is to download the files which will be used with Mozilla.
19122 Take your current web browser up to
19123 http://www.sun.com/software/java2/download.html and create an account on
19124 their website. Remember to save the username and password from here as it
19125 may be needed in the future. Download a copy of the file
19126 j2sdk-1_3_1-src.tar.gz and place this in /usr/ports/distfiles/ as the port
19127 will not fetch it automatically. This is due to license restrictions.
19128 While we are here, download the ``java environment'' from
19129 http://java.sun.com/webapps/download/Display?BundleId=7905. The filename
19130 is j2sdk-1_3_1_08-linux-i586.bin and is large (about 25 megabytes!). Like
19131 before, this file must be placed into /usr/ports/distfiles/. Finally
19132 download a copy of the ``java patchkit'' from
19133 http://www.eyesbeyond.com/freebsddom/java/ and place it into
19134 /usr/ports/distfiles/.
19136 Install the java/jdk13 port with the standard make install clean and then
19137 install the www/flashpluginwrapper port. This port requires
19138 emulators/linux_base which is a large port. True that other Flash plugins
19139 exist, however they have not worked for me.
19141 Install the www/mozilla port, if Mozilla is not already installed.
19143 Now copy the Flash plug-in files with:
19145 # cp /usr/local/lib/flash/libflashplayer.so \
19146 /usr/X11R6/lib/browser_plugins/libflashplayer_linux.so
19148 # cp /usr/local/lib/flash/ShockwaveFlash.class \
19149 /usr/X11R6/lib/browser_plugins/
19151 Now add the following lines to the top of (but right under #!/bin/sh)
19152 Mozilla startup script: /usr/X11R6/bin/mozilla.
19154 LD_PRELOAD=/usr/local/lib/libflashplayer.so.1
19157 This will enable the Flash plug-in.
19159 Now just start Mozilla with:
19163 And access the About Plug-ins option from the Help menu. A list should
19164 appear with all the currently available plugins. Java and Shockwave(R)
19165 Flash should both be listed.
19167 ----------------------------------------------------------------------
19171 The ports collection contains several versions of the Netscape browser.
19172 Since the native FreeBSD ones contain a serious security bug, installing
19173 them is strongly discouraged. Instead, use a more recent Linux or DIGITAL
19176 The latest stable release of the Netscape browser is Netscape 7. It can be
19177 installed from the ports collection:
19179 # cd /usr/ports/www/netscape7
19180 # make install clean
19182 There are localized versions in the French, German, and Japanese
19185 Caution: Netscape 4.x versions are not recommended because they are not
19186 compliant with today's standards. However, Netscape 7.x and newer
19187 versions are only available for the i386 platform.
19189 ----------------------------------------------------------------------
19193 Opera is a very fast, full-featured, and standards-compliant browser. It
19194 comes in a version that runs under Linux emulation. There is a no-cost
19195 version of the browser that displays advertising and an ad-free version
19196 that can be purchased on the Opera web site.
19198 To browse the Web with Opera, install the package:
19202 Some FTP sites do not have all the packages, but the same result can be
19203 obtained with the ports collection by typing:
19205 # cd /usr/ports/www/opera
19206 # make install clean
19208 ----------------------------------------------------------------------
19212 When it comes to productivity, new users often look for a good office
19213 suite or a friendly word processor. While some desktop environments like
19214 KDE already provide an office suite, there is no default application.
19215 DragonFly provides all that is needed, regardless of your desktop
19218 This section covers these applications:
19220 +------------------------------------------------------------------------+
19221 | Application Name | Resources | Installation | Major Dependencies |
19222 | | Needed | from Ports | |
19223 |------------------+-----------+--------------+--------------------------|
19224 | KOffice | light | heavy | KDE |
19225 |------------------+-----------+--------------+--------------------------|
19226 | AbiWord | light | light | Gtk+ or GNOME |
19227 |------------------+-----------+--------------+--------------------------|
19228 | The Gimp | light | heavy | Gtk+ |
19229 |------------------+-----------+--------------+--------------------------|
19230 | OpenOffice.org | heavy | huge | GCC 3.1, JDK(TM) 1.3, |
19232 +------------------------------------------------------------------------+
19234 ----------------------------------------------------------------------
19238 The KDE community has provided its desktop environment with an office
19239 suite which can be used outside KDE. It includes the four standard
19240 components that can be found in other office suites. KWord is the word
19241 processor, KSpread is the spreadsheet program, KPresenter manages slide
19242 presentations, and Kontour lets you draw graphical documents.
19244 Before installing the latest KOffice, make sure you have an up-to-date
19247 To install KOffice as a package, issue the following command:
19251 If the package is not available, you can use the ports collection. For
19252 instance, to install KOffice for KDE3, do:
19254 # cd /usr/ports/editors/koffice-kde3
19255 # make install clean
19257 ----------------------------------------------------------------------
19261 AbiWord is a free word processing program similar in look and feel to
19262 Microsoft Word. It is suitable for typing papers, letters, reports, memos,
19263 and so forth. It is very fast, contains many features, and is very
19266 AbiWord can import or export many file formats, including some proprietary
19267 ones like Microsoft .doc.
19269 AbiWord is available as a package. You can install it by:
19273 If the package is not available, it can be compiled from the ports
19274 collection. The ports collection should be more up to date. It can be done
19277 # cd /usr/ports/editors/AbiWord
19278 # make install clean
19280 ----------------------------------------------------------------------
19284 For image authoring or picture retouching, The GIMP is a very
19285 sophisticated image manipulation program. It can be used as a simple paint
19286 program or as a quality photo retouching suite. It supports a large number
19287 of plug-ins and features a scripting interface. The GIMP can read and
19288 write a wide range of file formats. It supports interfaces with scanners
19291 You can install the package by issuing this command:
19295 If your FTP site does not have this package, you can use the ports
19296 collection. The graphics directory of the ports collection also contains
19297 The Gimp Manual. Here is how to get them installed:
19299 # cd /usr/ports/graphics/gimp1
19300 # make install clean
19301 # cd /usr/ports/graphics/gimp-manual-pdf
19302 # make install clean
19304 Note: The graphics directory of the ports collection holds the
19305 development version of The GIMP in graphics/gimp-devel. HTML and
19306 PostScript versions of The Gimp Manual are in graphics/gimp-manual-html
19307 and graphics/gimp-manual-ps.
19309 ----------------------------------------------------------------------
19311 15.3.4 OpenOffice.org
19313 OpenOffice.org includes all of the mandatory applications in a complete
19314 office productivity suite: a word processor, a spreadsheet, a presentation
19315 manager, and a drawing program. Its user interface is very similar to
19316 other office suites, and it can import and export in various popular file
19317 formats. It is available in a number of different languages including
19318 interfaces, spell checkers, and dictionaries.
19320 The word processor of OpenOffice.org uses a native XML file format for
19321 increased portability and flexibility. The spreadsheet program features a
19322 macro language and it can be interfaced with external databases.
19323 OpenOffice.org is already stable and runs natively on Windows,
19324 Solaris(TM), Linux, FreeBSD, and Mac OS X. More information about
19325 OpenOffice.org can be found on the OpenOffice web site. For FreeBSD
19326 specific information, and to directly download packages use the FreeBSD
19327 OpenOffice Porting Team's web site. These packages should work on
19330 To install OpenOffice.org, do:
19332 # pkg_add openoffice
19334 Once the package is installed, you must run the setup program and choose a
19335 standard workstation installation. Run this command as the user who will
19336 use OpenOffice.org:
19340 If the OpenOffice.org packages are not available, you still have the
19341 option to compile the port. However, you must bear in mind that it
19342 requires a lot of disk space and a fairly long time to compile.
19344 # cd /usr/ports/editors/openoffice
19345 # make install clean
19347 Once this is done, run the setup as the user who will use OpenOffice.org
19348 and choose a standard workstation installation by:
19350 % cd /usr/ports/editors/openoffice
19351 % make install-user
19353 If you want to use a localized version, here are the available ports:
19355 +------------------------------------+
19356 | Language | Port |
19357 |------------+-----------------------|
19358 | Arabic | editors/openoffice-ar |
19359 |------------+-----------------------|
19360 | Danish | editors/openoffice-dk |
19361 |------------+-----------------------|
19362 | Spanish | editors/openoffice-es |
19363 |------------+-----------------------|
19364 | Greek | editors/openoffice-gr |
19365 |------------+-----------------------|
19366 | Italian | editors/openoffice-it |
19367 |------------+-----------------------|
19368 | Dutch | editors/openoffice-nl |
19369 |------------+-----------------------|
19370 | Swedish | editors/openoffice-se |
19371 |------------+-----------------------|
19372 | Turkish | editors/openoffice-tr |
19373 |------------+-----------------------|
19374 | French | french/openoffice |
19375 |------------+-----------------------|
19376 | German | german/openoffice |
19377 |------------+-----------------------|
19378 | Japanese | japanese/openoffice |
19379 |------------+-----------------------|
19380 | Korean | korean/openoffice |
19381 |------------+-----------------------|
19382 | Polish | polish/openoffice |
19383 |------------+-----------------------|
19384 | Portuguese | portuguese/openoffice |
19385 |------------+-----------------------|
19386 | Russian | russian/openoffice |
19387 +------------------------------------+
19389 ----------------------------------------------------------------------
19391 15.4 Document Viewers
19393 Some new document formats have recently gained popularity. The standard
19394 viewers they require may not be available in the base system. We will see
19395 how to install them in this section.
19397 This section covers these applications:
19399 +------------------------------------------------------------------------+
19400 | Application Name | Resources | Installation | Major Dependencies |
19401 | | Needed | from Ports | |
19402 |------------------+-----------+--------------+--------------------------|
19403 | Acrobat Reader | light | light | Linux Binary |
19404 | | | | Compatibility |
19405 |------------------+-----------+--------------+--------------------------|
19406 | gv | light | light | Xaw3d |
19407 |------------------+-----------+--------------+--------------------------|
19408 | Xpdf | light | light | FreeType |
19409 |------------------+-----------+--------------+--------------------------|
19410 | GQview | light | light | Gtk+ or GNOME |
19411 +------------------------------------------------------------------------+
19413 ----------------------------------------------------------------------
19415 15.4.1 Acrobat Reader(R)
19417 Many documents are now distributed as PDF files, which stands for
19418 ``Portable Document Format''. One of the recommended viewers for these
19419 types of files is Acrobat Reader, released by Adobe for Linux. As
19420 DragonFly can run Linux binaries, it is also available for DragonFly.
19422 To install the Acrobat Reader 5 package, do:
19424 # pkg_add acroread5
19426 As usual, if the package is not available or you want the latest version,
19427 you can use the ports collection as well:
19429 # cd /usr/ports/print/acroread5
19430 # make install clean
19432 Note: Acrobat Reader is available in several different versions. At this
19433 time of writing, there are: print/acroread (version 3.0.2),
19434 print/acroread4 (version 4.0.5), and print/acroread5 (version 5.0.6).
19435 They may not all have been packaged for your version of DragonFly. The
19436 ports collection will always contain the latest versions.
19438 ----------------------------------------------------------------------
19442 gv is a PostScript and PDF viewer. It is originally based on ghostview but
19443 it has a nicer look thanks to the Xaw3d library. It is fast and its
19444 interface is clean. gv has many features like orientation, paper size,
19445 scale, or antialias. Almost any operation can be done either from the
19446 keyboard or the mouse.
19448 To install gv as a package, do:
19452 If you cannot get the package, you can use the ports collection:
19454 # cd /usr/ports/print/gv
19455 # make install clean
19457 ----------------------------------------------------------------------
19461 If you want a small DragonFly PDF viewer, Xpdf is a light-weight and
19462 efficient viewer. It requires very few resources and is very stable. It
19463 uses the standard X fonts and does not require Motif or any other X
19466 To install the Xpdf package, issue this command:
19470 If the package is not available or you prefer to use the ports collection,
19473 # cd /usr/ports/graphics/xpdf
19474 # make install clean
19476 Once the installation is complete, you can launch Xpdf and use the right
19477 mouse button to activate the menu.
19479 ----------------------------------------------------------------------
19483 GQview is an image manager. You can view a file with a single click,
19484 launch an external editor, get thumbnail previews, and much more. It also
19485 features a slideshow mode and some basic file operations. You can manage
19486 image collections and easily find duplicates. GQview can do full screen
19487 viewing and supports internationalization.
19489 If you want to install the GQview package, do:
19493 If the package is not available or you prefer to use the ports collection,
19496 # cd /usr/ports/graphics/gqview
19497 # make install clean
19499 ----------------------------------------------------------------------
19503 If, for any reason, you would like to manage your personal finances on
19504 your DragonFly Desktop, there are some powerful and easy to use
19505 applications ready to be installed. Some of them are compatible with
19506 widespread file formats like those of Quicken(R) or Excel documents.
19508 This section covers these applications:
19510 +------------------------------------------------------------------------+
19511 | Application | Resources | Installation from | Major |
19512 | Name | Needed | Ports | Dependencies |
19513 |-----------------+---------------+-------------------+------------------|
19514 | GnuCash | light | heavy | GNOME |
19515 |-----------------+---------------+-------------------+------------------|
19516 | Gnumeric | light | heavy | GNOME |
19517 |-----------------+---------------+-------------------+------------------|
19518 | Abacus | light | light | Tcl/Tk |
19519 +------------------------------------------------------------------------+
19521 ----------------------------------------------------------------------
19525 GnuCash is part of the GNOME effort to provide user-friendly yet powerful
19526 applications to end-users. With GnuCash, you can keep track of your income
19527 and expenses, your bank accounts, or your stocks. It features an intuitive
19528 interface while remaining very professional.
19530 GnuCash provides a smart register, a hierarchical system of accounts, many
19531 keyboard accelerators and auto-completion methods. It can split a single
19532 transaction into several more detailed pieces. GnuCash can import and
19533 merge Quicken QIF files. It also handles most international date and
19536 To install GnuCash on your system, do:
19540 If the package is not available, you can use the ports collection:
19542 # cd /usr/ports/finance/gnucash
19543 # make install clean
19545 ----------------------------------------------------------------------
19549 Gnumeric is a spreadsheet, part of the GNOME desktop environment. It
19550 features convenient automatic ``guessing'' of user input according to the
19551 cell format and an autofill system for many sequences. It can import files
19552 in a number of popular formats like those of Excel, Lotus 1-2-3, or
19553 Quattro Pro. Gnumeric supports graphs through the math/guppi graphing
19554 program. It has a large number of built-in functions and allows all of the
19555 usual cell formats such as number, currency, date, time, and much more.
19557 To install Gnumeric as a package, type in:
19561 If the package is not available, you can use the ports collection by
19564 # cd /usr/ports/math/gnumeric
19565 # make install clean
19567 ----------------------------------------------------------------------
19571 Abacus is a small and easy to use spreadsheet. It includes many built-in
19572 functions useful in several domains such as statistics, finances, and
19573 mathematics. It can import and export the Excel file format. Abacus can
19574 produce PostScript output.
19576 To install Abacus from its package, do:
19580 If the package is not available, you can use the ports collection by
19583 # cd /usr/ports/deskutils/abacus
19584 # make install clean
19586 ----------------------------------------------------------------------
19590 DragonFly is quite ready for day-to-day use as a desktop. With several
19591 thousand applications available as packages or ports, you can build a
19592 perfect desktop that suits all your needs.
19594 Once you have achieved the installation of your desktop, you may want to
19595 go one step further with misc/instant-workstation. This ``meta-port''
19596 allows you to build a typical set of ports for a workstation. You can
19597 customize it by editing /usr/ports/misc/instant-workstation/Makefile.
19598 Follow the syntax used for the default set to add or remove ports, and
19599 build it with the usual procedure. Eventually, you will be able to create
19600 a big package that corresponds to your very own desktop and install it to
19601 your other workstations!
19603 Here is a quick review of all the desktop applications covered in this
19606 +-----------------------------------------------------------+
19607 | Application Name | Package Name | Ports Name |
19608 |------------------+-----------------+----------------------|
19609 | Mozilla | mozilla | www/mozilla |
19610 |------------------+-----------------+----------------------|
19611 | Netscape | linux-netscape7 | www/netscape7 |
19612 |------------------+-----------------+----------------------|
19613 | Opera | linux-opera | www/linux-opera |
19614 |------------------+-----------------+----------------------|
19615 | KOffice | koffice-kde3 | editors/koffice-kde3 |
19616 |------------------+-----------------+----------------------|
19617 | AbiWord | AbiWord | editors/AbiWord |
19618 |------------------+-----------------+----------------------|
19619 | The GIMP | gimp | graphics/gimp1 |
19620 |------------------+-----------------+----------------------|
19621 | OpenOffice.org | openoffice | editors/openoffice |
19622 |------------------+-----------------+----------------------|
19623 | Acrobat Reader | acroread5 | print/acroread5 |
19624 |------------------+-----------------+----------------------|
19625 | gv | gv | print/gv |
19626 |------------------+-----------------+----------------------|
19627 | Xpdf | xpdf | graphics/xpdf |
19628 |------------------+-----------------+----------------------|
19629 | GQview | gqview | graphics/gqview |
19630 |------------------+-----------------+----------------------|
19631 | GnuCash | gnucash | finance/gnucash |
19632 |------------------+-----------------+----------------------|
19633 | Gnumeric | gnumeric | math/gnumeric |
19634 |------------------+-----------------+----------------------|
19635 | Abacus | abacus | deskutils/abacus |
19636 +-----------------------------------------------------------+
19638 ----------------------------------------------------------------------
19640 Chapter 16 Multimedia
19642 Edited by Ross Lippert.
19646 DragonFly supports a wide variety of sound cards, allowing you to enjoy
19647 high fidelity output from your computer. This includes the ability to
19648 record and playback audio in the MPEG Audio Layer 3 (MP3), WAV, and Ogg
19649 Vorbis formats as well as many other formats. The pkgsrc collection also
19650 contain applications allowing you to edit your recorded audio, add sound
19651 effects, and control attached MIDI devices.
19653 With some willingness to experiment, DragonFly can support playback of
19654 video files and DVD's. The number of applications to encode, convert, and
19655 playback various video media is more limited than the number of sound
19656 applications. For example as of this writing, there is no good re-encoding
19657 application in the FreeBSD Ports Collection, which could be use to convert
19658 between formats, as there is with audio/sox. However, the software
19659 landscape in this area is changing rapidly.
19661 This chapter will describe the necessary steps to configure your sound
19662 card. The configuration and installation of X11 (Chapter 5) has already
19663 taken care of the hardware issues for your video card, though there may be
19664 some tweaks to apply for better playback.
19666 After reading this chapter, you will know:
19668 * How to configure your system so that your sound card is recognized.
19670 * Methods to test that your card is working using sample applications.
19672 * How to troubleshoot your sound setup.
19674 * How to playback and encode MP3s and other audio.
19676 * How video is supported by the X server.
19678 * Some video player/encoder ports which give good results.
19680 * How to playback DVD's, .mpg and .avi files.
19682 * How to rip CD and DVD information into files.
19684 * How to configure a TV card.
19686 Before reading this chapter, you should:
19688 * Know how to configure and install a new kernel (Chapter 9).
19690 Warning: Trying to mount audio CDs with the mount(8) command will result
19691 in an error, at least, and a kernel panic, at worst. These media have
19692 specialized encodings which differ from the usual ISO-filesystem.
19694 ----------------------------------------------------------------------
19696 16.2 Setting Up the Sound Card
19698 Contributed by Moses Moore.
19700 16.2.1 Locating the Correct Device
19702 Before you begin, you should know the model of the card you have, the chip
19703 it uses, and whether it is a PCI or ISA card. DragonFly supports a wide
19704 variety of both PCI and ISA cards. If you do not see your card in the
19705 following list, check the pcm(4) manual page. This is not a complete list;
19706 however, it does list some of the most common cards.
19708 * Crystal 4237, 4236, 4232, 4231
19714 * Ensoniq AudioPCI 1370/1371
19718 * NeoMagic 256AV/ZX
19720 * SoundBlaster(R) Pro, 16, 32, AWE64, AWE128, Live
19724 * Advanced Asound 100, 110, and Logic ALS120
19726 * ES 1868, 1869, 1879, 1888
19728 * Gravis UltraSound
19730 * Aureal Vortex 1 or 2
19732 To use your sound device, you will need to load the proper device driver.
19733 This may be accomplished in one of two ways. The easiest way is to simply
19734 load a kernel module for your sound card with kldload(8) which can either
19735 be done from the command line:
19737 # kldload snd_emu10k1.ko
19739 or by adding the appropriate line to the file /boot/loader.conf like this:
19741 snd_emu10k1_load="YES"
19743 These examples are for a Creative SoundBlaster Live! sound card. Other
19744 available loadable sound modules are listed in /boot/defaults/loader.conf.
19746 Alternatively, you may statically compile in support for your sound card
19747 in your kernel. The sections below provide the information you need to add
19748 support for your hardware in this manner. For more information about
19749 recompiling your kernel, please see Chapter 9.
19751 ----------------------------------------------------------------------
19753 16.2.1.1 Creative, Advance, and ESS Sound Cards
19755 If you have one of the above cards, you will need to add:
19759 to your kernel configuration file. If you have a PnP ISA card, you will
19764 For a non-PnP ISA card, add:
19767 device sbc0 at isa? port 0x220 irq 5 drq 1 flags 0x15
19769 to your kernel configuration file. The settings shown above are the
19770 defaults. You may need to change the IRQ or the other settings to match
19771 your card. See the sbc(4) manual page for more information.
19773 ----------------------------------------------------------------------
19775 16.2.1.2 Gravis UltraSound Cards
19777 For a PnP ISA card, you will need to add:
19782 to your kernel configuration file. If you have a non-PnP ISA card, you
19786 device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13
19788 to your kernel configuration file. You may need to change the IRQ or the
19789 other settings to match your card. See the gusc(4) manual page for more
19792 ----------------------------------------------------------------------
19794 16.2.1.3 Crystal Sound Cards
19796 For Crystal cards, you will need to add:
19801 to your kernel configuration file.
19803 ----------------------------------------------------------------------
19805 16.2.1.4 Generic Support
19807 For PnP ISA or PCI cards, you will need to add:
19811 to your kernel configuration file. If you have a non-PnP ISA sound card
19812 that does not have a bridge driver, you will need to add:
19814 device pcm0 at isa? irq 10 drq 1 flags 0x0
19816 to your kernel configuration file. You may need to change the IRQ or the
19817 other settings to match your card.
19819 ----------------------------------------------------------------------
19821 16.2.1.5 Onboard Sound
19823 Some systems with built-in motherboard sound devices may require the
19824 following device in your kernel configuration:
19828 ----------------------------------------------------------------------
19830 16.2.2 Creating and Testing the Device Nodes
19832 After you reboot, log in and check for the device in the
19833 /var/run/dmesg.boot file, as shown below:
19835 # grep pcm /var/run/dmesg.boot
19836 pcm0: <SB16 DSP 4.11> on sbc0
19838 The output from your system may look different. If no pcm devices show up,
19839 something went wrong earlier. If that happens, go through your kernel
19840 configuration file again and make sure you chose the correct device.
19841 Common problems are listed in Section 16.2.2.1.
19843 If the previous command returned pcm0, you will have to run the following
19849 If the command returned pcm1, follow the same steps as shown above,
19850 replacing snd0 with snd1.
19852 Note: The above commands will not create a /dev/snd device!
19854 MAKEDEV will create a group of device nodes, including:
19857 /dev/audio Sparc(R) compatible audio device
19858 /dev/dsp Digitized voice device
19859 /dev/dspW Like /dev/dsp, but 16 bits per sample
19860 /dev/midi Raw midi access device
19861 /dev/mixer Control port mixer device
19862 /dev/music Level 2 sequencer interface
19863 /dev/sequencer Sequencer device
19864 /dev/pss Programmable device interface
19866 If all goes well, you should now have a functioning sound card. If your
19867 CD-ROM or DVD-ROM drive is properly coupled to your sound card, you can
19868 put a CD in the drive and play it with cdcontrol(1):
19870 % cdcontrol -f /dev/acd0c play 1
19872 Various applications, such as audio/workman offer a better interface. You
19873 may want to install an application such as audio/mpg123 to listen to MP3
19876 ----------------------------------------------------------------------
19878 16.2.2.1 Common Problems
19880 +------------------------------------------------------------------------+
19881 | Error | Solution |
19882 |------------------------------+-----------------------------------------|
19883 | | One or more of the device nodes was not |
19884 | ``unsupported subdevice XX'' | created correctly. Repeat the steps |
19886 |------------------------------+-----------------------------------------|
19887 | ``sb_dspwr(XX) timed out'' | The I/O port is not set correctly. |
19888 |------------------------------+-----------------------------------------|
19889 | | The IRQ is set incorrectly. Make sure |
19890 | ``bad irq XX'' | that the set IRQ and the sound IRQ are |
19892 |------------------------------+-----------------------------------------|
19893 | ``xxx: gus pcm not attached, | There is not enough available memory to |
19894 | out of memory'' | use the device. |
19895 |------------------------------+-----------------------------------------|
19896 | | Check with fstat | grep dsp if another |
19897 | ``xxx: can't open | application is holding the device open. |
19898 | /dev/dsp!'' | Noteworthy troublemakers are esound and |
19899 | | KDE's sound support. |
19900 +------------------------------------------------------------------------+
19902 ----------------------------------------------------------------------
19904 16.2.3 Utilizing Multiple Sound Sources
19906 Contributed by Munish Chopra.
19908 It is often desirable to have multiple sources of sound that are able to
19909 play simultaneously, such as when esound or artsd do not support sharing
19910 of the sound device with a certain application.
19912 DragonFly lets you do this through Virtual Sound Channels, which can be
19913 set with the sysctl(8) facility. Virtual channels allow you to multiplex
19914 your sound card's playback channels by mixing sound in the kernel.
19916 To set the number of virtual channels, there are two sysctl knobs which,
19917 if you are the root user, can be set like this:
19919 # sysctl hw.snd.pcm0.vchans=4
19920 # sysctl hw.snd.maxautovchans=4
19922 The above example allocates four virtual channels, which is a practical
19923 number for everyday use. hw.snd.pcm0.vchans is the number of virtual
19924 channels pcm0 has, and is configurable once a device has been attached.
19925 hw.snd.maxautovchans is the number of virtual channels a new audio device
19926 is given when it is attached using kldload(8). Since the pcm module can be
19927 loaded independently of the hardware drivers, hw.snd.maxautovchans can
19928 store how many virtual channels any devices which are attached later will
19931 If you are not using devfs(5), you will have to point your applications at
19932 /dev/dsp0.x, where x is 0 to 3 if hw.snd.pcm.0.vchans is set to 4 as in
19933 the above example. On a system using devfs(5), the above will
19934 automatically be allocated transparently to the user.
19936 ----------------------------------------------------------------------
19940 Contributed by Chern Lee.
19942 MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound, leaving no
19943 reason to let your DragonFly workstation fall short of its offerings.
19945 ----------------------------------------------------------------------
19949 A popular X11 MP3 player is XMMS (X Multimedia System). Winamp skins can
19950 be used with XMMS since the GUI is almost identical to that of Nullsoft's
19951 Winamp. XMMS also has native plug-in support.
19953 XMMS can be installed from the multimedia/xmms port or package.
19955 XMMS' interface is intuitive, with a playlist, graphic equalizer, and
19956 more. Those familiar with Winamp will find XMMS simple to use.
19958 The audio/mpg123 port is an alternative, command-line MP3 player.
19960 mpg123 can be run by specifying the sound device and the MP3 file on the
19961 command line, as shown below:
19963 # mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3
19964 High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
19965 Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
19966 Uses code from various people. See 'README' for more!
19967 THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!
19973 Playing MPEG stream from Foobar-GreatestHits.mp3 ...
19974 MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
19976 /dev/dsp1.0 should be replaced with the dsp device entry on your system.
19978 ----------------------------------------------------------------------
19980 16.3.2 Ripping CD Audio Tracks
19982 Before encoding a CD or CD track to MP3, the audio data on the CD must be
19983 ripped onto the hard drive. This is done by copying the raw CDDA (CD
19984 Digital Audio) data to WAV files.
19986 The cdda2wav tool, which is a part of the sysutils/cdrtools suite, is used
19987 for ripping audio information from CDs and the information associated with
19990 With the audio CD in the drive, the following command can be issued (as
19991 root) to rip an entire CD into individual (per track) WAV files:
19993 # cdda2wav -D 0,1,0 -B
19995 cdda2wav will support ATAPI (IDE) CDROM drives. To rip from an IDE drive,
19996 specify the device name in place of the SCSI unit numbers. For example, to
19997 rip track 7 from an IDE drive:
19999 # cdda2wav -D /dev/acd0a -t 7
20001 The -D 0,1,0 indicates the SCSI device 0,1,0, which corresponds to the
20002 output of cdrecord -scanbus.
20004 To rip individual tracks, make use of the -t option as shown:
20006 # cdda2wav -D 0,1,0 -t 7
20008 This example rips track seven of the audio CDROM. To rip a range of
20009 tracks, for example, track one to seven, specify a range:
20011 # cdda2wav -D 0,1,0 -t 1+7
20013 The utility dd(1) can also be used to extract audio tracks on ATAPI
20014 drives, read Section 12.5.5 for more information on that possibility.
20016 ----------------------------------------------------------------------
20018 16.3.3 Encoding MP3s
20020 Nowadays, the mp3 encoder of choice is lame. Lame can be found at
20021 audio/lame in the pkgsrc and ports trees.
20023 Using the ripped WAV files, the following command will convert audio01.wav
20027 --tt "Foo Song Title" \
20028 --ta "FooBar Artist" \
20029 --tl "FooBar Album" \
20031 --tc "Ripped and encoded by Foo" \
20033 audio01.wav audio01.mp3
20035 128 kbits seems to be the standard MP3 bitrate in use. Many enjoy the
20036 higher quality 160, or 192. The higher the bitrate, the more disk space
20037 the resulting MP3 will consume--but the quality will be higher. The -h
20038 option turns on the ``higher quality but a little slower'' mode. The
20039 options beginning with --t indicate ID3 tags, which usually contain song
20040 information, to be embedded within the MP3 file. Additional encoding
20041 options can be found by consulting the lame man page.
20043 ----------------------------------------------------------------------
20045 16.3.4 Decoding MP3s
20047 In order to burn an audio CD from MP3s, they must be converted to a
20048 non-compressed WAV format. Both XMMS and mpg123 support the output of MP3
20049 to an uncompressed file format.
20051 Writing to Disk in XMMS:
20055 2. Right-click on the window to bring up the XMMS menu.
20057 3. Select Preference under Options.
20059 4. Change the Output Plugin to ``Disk Writer Plugin''.
20061 5. Press Configure.
20063 6. Enter (or choose browse) a directory to write the uncompressed files
20066 7. Load the MP3 file into XMMS as usual, with volume at 100% and EQ
20067 settings turned off.
20069 8. Press Play -- XMMS will appear as if it is playing the MP3, but no
20070 music will be heard. It is actually playing the MP3 to a file.
20072 9. Be sure to set the default Output Plugin back to what it was before in
20073 order to listen to MP3s again.
20075 Writing to stdout in mpg123:
20077 1. Run mpg123 -s audio01.mp3 > audio01.pcm
20079 XMMS writes a file in the WAV format, while mpg123 converts the MP3 into
20080 raw PCM audio data. Both of these formats can be used with cdrecord to
20081 create audio CDs. You have to use raw PCM with burncd(8). If you use WAV
20082 files, you will notice a small tick sound at the beginning of each track,
20083 this sound is the header of the WAV file. You can simply remove the header
20084 of a WAV file with the utility SoX (it can be installed from the audio/sox
20087 % sox -t wav -r 44100 -s -w -c 2 track.wav track.raw
20089 Read Section 12.5 for more information on using a CD burner in DragonFly.
20091 ----------------------------------------------------------------------
20093 16.4 Video Playback
20095 Contributed by Ross Lippert.
20097 Video playback is a very new and rapidly developing application area. Be
20098 patient. Not everything is going to work as smoothly as it did with sound.
20100 Before you begin, you should know the model of the video card you have and
20101 the chip it uses. While XFree86 and X.org support a wide variety of video
20102 cards, fewer give good playback performance. To obtain a list of
20103 extensions supported by the X server using your card use the command
20104 xdpyinfo(1) while X11 is running.
20106 It is a good idea to have a short MPEG file which can be treated as a test
20107 file for evaluating various players and options. Since some DVD players
20108 will look for DVD media in /dev/dvd by default, or have this device name
20109 hardcoded in them, you might find it useful to make symbolic links to the
20112 # ln -sf /dev/acd0c /dev/dvd
20113 # ln -sf /dev/racd0c /dev/rdvd
20115 Additionally, DVD decryption, which requires invoking special DVD-ROM
20116 functions, requires write permission on the DVD devices.
20118 Some of the packages discussed rely on the following kernel options to
20119 build correctly. Before attempting to build, add these options to the
20120 kernel configuration file, build a new kernel, and reboot:
20122 option CPU_ENABLE_SSE
20125 To enhance the shared memory X11 interface, it is recommended that the
20126 values of some sysctl(8) variables should be increased:
20128 kern.ipc.shmmax=67108864
20129 kern.ipc.shmall=32768
20131 ----------------------------------------------------------------------
20133 16.4.1 Determining Video Capabilities
20135 There are several possible ways to display video under X11. What will
20136 really work is largely hardware dependent. Each method described below
20137 will have varying quality across different hardware. Secondly, the
20138 rendering of video in X11 is a topic receiving a lot of attention lately,
20139 and with each version of X.org or XFree86 there may be significant
20142 A list of common video interfaces:
20144 1. X11: normal X11 output using shared memory.
20146 2. XVideo: an extension to the X11 interface which supports video in any
20149 3. SDL: the Simple Directmedia Layer.
20151 4. DGA: the Direct Graphics Access.
20153 5. SVGAlib: low level console graphics layer.
20155 ----------------------------------------------------------------------
20159 Both XFree86 4.X and X.org have an extension called XVideo (aka Xvideo,
20160 aka Xv, aka xv) which allows video to be directly displayed in drawable
20161 objects through a special acceleration. This extension provides very good
20162 quality playback even on low-end machines (for example my PIII 400 Mhz
20163 laptop). Unfortunately, the list of cards in which this feature is
20164 supported ``out of the box'' is currently:
20168 2. Intel i810 and i815
20170 3. some S3 chips (such as Savage/IX and Savage/MX)
20172 If your card is not one of these, do not be disappointed yet. XFree86 4.X
20173 adds new xv capabilities with each release [12]. To check whether the
20174 extension is running, use xvinfo:
20178 XVideo is supported for your card if the result looks like:
20180 X-Video Extension version 2.2
20182 Adaptor #0: "Savage Streams Engine"
20185 operations supported: PutImage
20187 depth 16, visualID 0x22
20188 depth 16, visualID 0x23
20189 number of attributes: 5
20190 "XV_COLORKEY" (range 0 to 16777215)
20191 client settable attribute
20192 client gettable attribute (current value is 2110)
20193 "XV_BRIGHTNESS" (range -128 to 127)
20194 client settable attribute
20195 client gettable attribute (current value is 0)
20196 "XV_CONTRAST" (range 0 to 255)
20197 client settable attribute
20198 client gettable attribute (current value is 128)
20199 "XV_SATURATION" (range 0 to 255)
20200 client settable attribute
20201 client gettable attribute (current value is 128)
20202 "XV_HUE" (range -180 to 180)
20203 client settable attribute
20204 client gettable attribute (current value is 0)
20205 maximum XvImage size: 1024 x 1024
20206 Number of image formats: 7
20207 id: 0x32595559 (YUY2)
20208 guid: 59555932-0000-0010-8000-00aa00389b71
20210 number of planes: 1
20212 id: 0x32315659 (YV12)
20213 guid: 59563132-0000-0010-8000-00aa00389b71
20215 number of planes: 3
20217 id: 0x30323449 (I420)
20218 guid: 49343230-0000-0010-8000-00aa00389b71
20220 number of planes: 3
20222 id: 0x36315652 (RV16)
20223 guid: 52563135-0000-0000-0000-000000000000
20225 number of planes: 1
20228 red, green, blue masks: 0x1f, 0x3e0, 0x7c00
20229 id: 0x35315652 (RV15)
20230 guid: 52563136-0000-0000-0000-000000000000
20232 number of planes: 1
20235 red, green, blue masks: 0x1f, 0x7e0, 0xf800
20236 id: 0x31313259 (Y211)
20237 guid: 59323131-0000-0010-8000-00aa00389b71
20239 number of planes: 3
20242 guid: 00000000-0000-0000-0000-000000000000
20244 number of planes: 0
20247 red, green, blue masks: 0x0, 0x0, 0x0
20249 Also note that the formats listed (YUV2, YUV12, etc) are not present with
20250 every implementation of XVideo and their absence may hinder some players.
20252 If the result looks like:
20254 X-Video Extension version 2.2
20256 no adaptors present
20258 Then XVideo is probably not supported for your card.
20260 If XVideo is not supported for your card, this only means that it will be
20261 more difficult for your display to meet the computational demands of
20262 rendering video. Depending on your video card and processor, though, you
20263 might still be able to have a satisfying experience. You should probably
20264 read about ways of improving performance in the advanced reading Section
20267 ----------------------------------------------------------------------
20269 16.4.1.2 Simple Directmedia Layer
20271 The Simple Directmedia Layer, SDL, was intended to be a porting layer
20272 between Microsoft Windows, BeOS, and UNIX, allowing cross-platform
20273 applications to be developed which made efficient use of sound and
20274 graphics. The SDL layer provides a low-level abstraction to the hardware
20275 which can sometimes be more efficient than the X11 interface.
20277 The SDL can be found at devel/sdl12 (or pkgsrc/devel/SDL2).
20279 ----------------------------------------------------------------------
20281 16.4.1.3 Direct Graphics Access
20283 Direct Graphics Access is an X11 extension which allows a program to
20284 bypass the X server and directly alter the framebuffer. Because it relies
20285 on a low level memory mapping to effect this sharing, programs using it
20286 must be run as root.
20288 The DGA extension can be tested and benchmarked by dga(1). When dga is
20289 running, it changes the colors of the display whenever a key is pressed.
20292 ----------------------------------------------------------------------
20294 16.4.2 Ports and Packages Dealing with Video
20296 This section discusses the software available from the pkgsrc collection
20297 which can be used for video playback. Video playback is a very active area
20298 of software development, and the capabilities of various applications are
20299 bound to diverge somewhat from the descriptions given here.
20301 Firstly, it is important to know that many of the video applications which
20302 run on DragonFly were developed as Linux applications. Many of these
20303 applications are still beta-quality. Some of the problems that you may
20304 encounter with video packages on DragonFly include:
20306 1. An application cannot playback a file which another application
20309 2. An application cannot playback a file which the application itself
20312 3. The same application on two different machines, rebuilt on each
20313 machine for that machine, plays back the same file differently.
20315 4. A seemingly trivial filter like rescaling of the image size results in
20316 very bad artifacts from a buggy rescaling routine.
20318 5. An application frequently dumps core.
20320 6. Documentation is not installed with the port and can be found either
20321 on the web or under the port's work directory.
20323 Many of these applications may also exhibit ``Linux-isms''. That is, there
20324 may be issues resulting from the way some standard libraries are
20325 implemented in the Linux distributions, or some features of the Linux
20326 kernel which have been assumed by the authors of the applications. These
20327 issues are not always noticed and worked around by the port maintainers,
20328 which can lead to problems like these:
20330 1. The use of /proc/cpuinfo to detect processor characteristics.
20332 2. A misuse of threads which causes a program to hang upon completion
20333 instead of truly terminating.
20335 3. Software not yet in the pkgsrc collection which is commonly used in
20336 conjunction with the application.
20338 So far, these application developers have been cooperative with port
20339 maintainers to minimize the work-arounds needed for port-ing.
20341 ----------------------------------------------------------------------
20345 MPlayer is a recently developed and rapidly developing video player. The
20346 goals of the MPlayer team are speed and flexibility on Linux and other
20347 Unices. The project was started when the team founder got fed up with bad
20348 playback performance on then available players. Some would say that the
20349 graphical interface has been sacrificed for a streamlined design. However,
20350 once you get used to the command line options and the key-stroke controls,
20351 it works very well.
20353 ----------------------------------------------------------------------
20355 16.4.2.1.1 Building MPlayer
20357 MPlayer resides in multimedia/mplayer. MPlayer performs a variety of
20358 hardware checks during the build process, resulting in a binary which will
20359 not be portable from one system to another. Therefore, it is important to
20360 build it from ports and not to use a binary package. Additionally, a
20361 number of options can be specified in the make command line, as described
20362 at the start of the build.
20364 # cd /usr/ports/multimedia/mplayer
20366 You can enable additional compilation optimizations
20367 by defining WITH_OPTIMIZED_CFLAGS
20368 You can enable GTK GUI by defining WITH_GUI.
20369 You can enable DVD support by defining WITH_DVD.
20370 You can enable SVGALIB support by defining WITH_SVGALIB.
20371 You can enable VORBIS sound support by defining WITH_VORBIS.
20372 You can enable XAnim DLL support by defining WITH_XANIM.
20374 If you have x11-toolkits/gtk12 installed, then you might as well enable
20375 the GUI. Otherwise, it is not worth the effort. If you intend to play
20376 (possibly CSS encoded) DVD's with MPlayer you must enable the DVD support
20377 option here [13]. Some reasonable options are:
20379 # make WITH_DVD=yes WITH_SVGALIB=yes
20381 As of this writing, the MPlayer port will build its HTML documentation and
20382 one executable, mplayer. It can also be made to build an encoder,
20383 mencoder, which is a tool for re-encoding video. A modification to the
20384 Makefile can enable it. It may be enabled by default in subsequent
20385 versions of the port.
20387 The HTML documentation for MPlayer is very informative. If the reader
20388 finds the information on video hardware and interfaces in this chapter
20389 lacking, the MPlayer documentation is a very thorough supplement. You
20390 should definitely take the time to read the MPlayer documentation if you
20391 are looking for information about video support in UNIX.
20393 ----------------------------------------------------------------------
20395 16.4.2.1.2 Using MPlayer
20397 Any user of MPlayer must set up a .mplayer subdirectory of her home
20398 directory. To create this necessary subdirectory, you can type the
20401 % cd /usr/ports/multimedia/mplayer
20402 % make install-user
20404 The command options for mplayer are listed in the manual page. For even
20405 more detail there is HTML documentation. In this section, we will describe
20406 only a few common uses.
20408 To play a file, such as testfile.avi, through one of the various video
20409 interfaces set the -vo option:
20411 % mplayer -vo xv testfile.avi
20413 % mplayer -vo sdl testfile.avi
20415 % mplayer -vo x11 testfile.avi
20417 # mplayer -vo dga testfile.avi
20419 # mplayer -vo 'sdl:dga' testfile.avi
20421 It is worth trying all of these options, as their relative performance
20422 depends on many factors and will vary significantly with hardware.
20424 To play from a DVD, replace the testfile.avi with -dvd N DEVICE where N is
20425 the title number to play and DEVICE is the device node for the DVD-ROM.
20426 For example, to play title 3 from /dev/dvd:
20428 # mplayer -vo dga -dvd 3 /dev/dvd
20430 To stop, pause, advance and so on, consult the keybindings, which are
20431 output by running mplayer -h or read the manual page.
20433 Additional important options for playback are: -fs -zoom which engages the
20434 fullscreen mode and -framedrop which helps performance.
20436 In order for the mplayer command line to not become too large, the user
20437 can create a file .mplayer/config and set default options there:
20443 Finally, mplayer can be used to rip a DVD title into a .vob file. To dump
20444 out the second title from a DVD, type this:
20446 # mplayer -dumpstream -dumpfile out.vob -dvd 2 /dev/dvd
20448 The output file, out.vob, will be MPEG and can be manipulated by the other
20449 packages described in this section.
20451 ----------------------------------------------------------------------
20453 16.4.2.1.3 mencoder
20455 If you opt to install mencoder when you build MPlayer, be forewarned that
20456 it is still an experimental component. Before using mencoder it is a good
20457 idea to familiarize yourself with the options from the HTML documentation.
20458 There is a manual page, but it is not very useful without the HTML
20459 documentation. There are innumerable ways to improve quality, lower
20460 bitrate, and change formats, and some of these tricks may make the
20461 difference between good or bad performance. Here are a couple of examples
20462 to get you going. First a simple copy:
20464 % mencoder input.avi -oac copy -ovc copy -o output.avi
20466 Improper combinations of command line options can yield output files that
20467 are unplayable even by mplayer. Thus, if you just want to rip to a file,
20468 stick to the -dumpfile in mplayer.
20470 To convert input.avi to the MPEG4 codec with MPEG3 audio encoding
20471 (audio/lame is required):
20473 % mencoder input.avi -oac mp3lame -lameopts br=192 \
20474 -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi
20476 This has produced output playable by mplayer and xine.
20478 input.avi can be replaced with -dvd 1 /dev/dvd and run as root to
20479 re-encode a DVD title directly. Since you are likely to be dissatisfied
20480 with your results the first time around, it is recommended you dump the
20481 title to a file and work on the file.
20483 ----------------------------------------------------------------------
20485 16.4.2.2 The xine Video Player
20487 The xine video player is a project of wide scope aiming not only at being
20488 an all in one video solution, but also in producing a reusable base
20489 library and a modular executable which can be extended with plugins. It
20490 comes both as a package and as a port, multimedia/xine.
20492 The xine player is still very rough around the edges, but it is clearly
20493 off to a good start. In practice, xine requires either a fast CPU with a
20494 fast video card, or support for the XVideo extension. The GUI is usable,
20497 As of this writing, there is no input module shipped with xine which will
20498 play CSS encoded DVD's. There are third party builds which do have modules
20499 for this built in them, but none of these are in the FreeBSD Ports
20502 Compared to MPlayer, xine does more for the user, but at the same time,
20503 takes some of the more fine-grained control away from the user. The xine
20504 video player performs best on XVideo interfaces.
20506 By default, xine player will start up in a graphical user interface. The
20507 menus can then be used to open a specific file:
20511 Alternatively, it may be invoked to play a file immediately without the
20512 GUI with the command:
20514 % xine -g -p mymovie.avi
20516 ----------------------------------------------------------------------
20518 16.4.2.3 The transcode Utilities
20520 The software transcode is not a player, but a suite of tools for
20521 re-encoding .avi and .mpg files. With transcode, one has the ability to
20522 merge video files, repair broken files, using command line tools with
20523 stdin/stdout stream interfaces.
20525 Like MPlayer, transcode is very experimental software which must be build
20526 from ports or pkgsrc at multimedia/transcode. Using a great many options
20527 to the make command. I recommend:
20529 # make WITH_LIBMPEG2=yes
20531 If you plan to install multimedia/avifile, then add the WITH_AVIFILE
20532 option to your make command line, as shown here:
20534 # make WITH_AVIFILE=yes WITH_LIBMPEG2=yes
20536 Here are two examples of using transcode for video conversion which
20537 produce rescaled output. The first encodes the output to an openDIVX AVI
20538 file, while the second encodes to the much more portable MPEG format.
20540 % transcode -i input.vob -x vob -V -Z 320x240 \
20541 -y opendivx -N 0x55 -o output.avi
20543 % transcode -i input.vob -x vob -V -Z 320x240 \
20544 -y mpeg -N 0x55 -o output.tmp
20545 % tcmplex -o output.mpg -i output.tmp.m1v -p output.tmp.mpa -m 1
20547 There is a manual page for transcode, but there is little documentation
20548 for the various tc* utilities (such as tcmplex) which are also installed.
20549 However, the -h command line option can always be given to get curt usage
20550 instructions for a command.
20552 In comparison, transcode runs significantly slower than mencoder, but it
20553 has a better chance of producing a more widely playable file. MPEGs
20554 created by transcode have been known to play on Windows Media(R) Player
20555 and Apple's Quicktime(R), for example.
20557 ----------------------------------------------------------------------
20559 16.4.3 Further Reading
20561 The various video software packages for DragonFly are developing rapidly.
20562 It is quite possible that in the near future many of the problems
20563 discussed here will have been resolved. In the mean time, those who want
20564 to get the very most out of DragonFly's A/V capabilities will have to
20565 cobble together knowledge from several FAQs and tutorials and use a few
20566 different applications. This section exists to give the reader pointers to
20567 such additional information.
20569 The MPlayer documentation is very technically informative. These documents
20570 should probably be consulted by anyone wishing to obtain a high level of
20571 expertise with UNIX video. The MPlayer mailing list is hostile to anyone
20572 who has not bothered to read the documentation, so if you plan on making
20573 bug reports to them, RTFM.
20575 The xine HOWTO contains a chapter on performance improvement which is
20576 general to all players.
20578 Finally, there are some other promising applications which the reader may
20581 * Avifile which is also a port multimedia/avifile.
20583 * Ogle which is also a port multimedia/ogle.
20587 * multimedia/dvdauthor, an open source package for authoring DVD
20590 ----------------------------------------------------------------------
20592 16.5 Setting Up TV Cards
20594 Original contribution by Josef El-Rayes. Enhanced and adapted by Marc
20597 ----------------------------------------------------------------------
20599 16.5.1 Introduction
20601 TV cards allow you to watch broadcast or cable TV on your computer. Most
20602 of them accept composite video via an RCA or S-video input and some of
20603 these cards come with a FM radio tuner.
20605 DragonFly provides support for PCI-based TV cards using a Brooktree
20606 Bt848/849/878/879 or a Conexant CN-878/Fusion 878a Video Capture Chip with
20607 the bktr(4) driver. You must also ensure the board comes with a supported
20608 tuner, consult the bktr(4) manual page for a list of supported tuners.
20610 ----------------------------------------------------------------------
20612 16.5.2 Adding the Driver
20614 To use your card, you will need to load the bktr(4) driver, this can be
20615 done by adding the following line to the /boot/loader.conf file like this:
20619 Alternatively, you may statically compile the support for the TV card in
20620 your kernel, in that case add the following lines to your kernel
20628 These additional device drivers are necessary because of the card
20629 components being interconnected via an I2C bus. Then build and install a
20632 Once the support was added to your system, you have to reboot your
20633 machine. During the boot process, your TV card should show up, like this:
20635 bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
20636 iicbb0: <I2C bit-banging driver> on bti2c0
20637 iicbus0: <Philips I2C bus> on iicbb0 master-only
20638 iicbus1: <Philips I2C bus> on iicbb0 master-only
20639 smbus0: <System Management Bus> on bti2c0
20640 bktr0: Pinnacle/Miro TV, Philips SECAM tuner.
20642 Of course these messages can differ according to your hardware. However
20643 you should check if the tuner is correctly detected; it is still possible
20644 to override some of the detected parameters with sysctl(8) MIBs and kernel
20645 configuration file options. For example, if you want to force the tuner to
20646 a Philips SECAM tuner, you should add the following line to your kernel
20647 configuration file:
20649 options OVERRIDE_TUNER=6
20651 or you can directly use sysctl(8):
20653 # sysctl hw.bt848.tuner=6
20655 See the bktr(4) manual page and the /usr/src/sys/i386/conf/LINT file for
20656 more details on the available options.
20658 ----------------------------------------------------------------------
20660 16.5.3 Useful Applications
20662 To use your TV card you need to install one of the following applications:
20664 * multimedia/fxtv provides TV-in-a-window and image/audio/video capture
20667 * multimedia/xawtv is also a TV application, with the same features as
20670 * misc/alevt (or pkgsrc/multimedia/alevt) decodes and displays
20671 Videotext/Teletext.
20673 * audio/xmradio, an application to use the FM radio tuner coming with
20676 * audio/wmtune, a handy desktop application for radio tuners.
20678 More applications are available in the pkgsrc and FreeBSD Ports
20681 ----------------------------------------------------------------------
20683 16.5.4 Troubleshooting
20685 If you encounter any problem with your TV card, you should check at first
20686 if the video capture chip and the tuner are really supported by the
20687 bktr(4) driver and if you used the right configuration options. For more
20688 support and various questions about your TV card you may want to contact
20689 and use the archives of the freebsd-multimedia mailing list.
20691 ----------------------------------------------------------------------
20693 Chapter 17 Serial Communications
20697 UNIX has always had support for serial communications. In fact, the very
20698 first UNIX machines relied on serial lines for user input and output.
20699 Things have changed a lot from the days when the average ``terminal''
20700 consisted of a 10-character-per-second serial printer and a keyboard. This
20701 chapter will cover some of the ways in which DragonFly uses serial
20704 After reading this chapter, you will know:
20706 * How to connect terminals to your DragonFly system.
20708 * How to use a modem to dial out to remote hosts.
20710 * How to allow remote users to login to your system with a modem.
20712 * How to boot your system from a serial console.
20714 Before reading this chapter, you should:
20716 * Know how to configure and install a new kernel (Chapter 9).
20718 * Understand UNIX permissions and processes (Chapter 3).
20720 * Have access to the technical manual for the serial hardware (modem or
20721 multi-port card) that you would like to use with DragonFly.
20723 ----------------------------------------------------------------------
20731 Bits per Second -- the rate at which data is transmitted
20735 Data Terminal Equipment -- for example, your computer
20739 Data Communications Equipment -- your modem
20743 EIA standard for hardware serial communications
20745 When talking about communications data rates, this section does not use
20746 the term ``baud''. Baud refers to the number of electrical state
20747 transitions that may be made in a period of time, while ``bps'' (bits per
20748 second) is the correct term to use (at least it does not seem to bother
20749 the curmudgeons quite as much).
20751 ----------------------------------------------------------------------
20753 17.2.2 Cables and Ports
20755 To connect a modem or terminal to your DragonFly system, you will need a
20756 serial port on your computer and the proper cable to connect to your
20757 serial device. If you are already familiar with your hardware and the
20758 cable it requires, you can safely skip this section.
20760 ----------------------------------------------------------------------
20764 There are several different kinds of serial cables. The two most common
20765 types for our purposes are null-modem cables and standard (``straight'')
20766 RS-232 cables. The documentation for your hardware should describe the
20767 type of cable required.
20769 ----------------------------------------------------------------------
20771 17.2.2.1.1 Null-modem Cables
20773 A null-modem cable passes some signals, such as ``signal ground'',
20774 straight through, but switches other signals. For example, the ``send
20775 data'' pin on one end goes to the ``receive data'' pin on the other end.
20777 If you like making your own cables, you can construct a null-modem cable
20778 for use with terminals. This table shows the RS-232C signal names and the
20779 pin numbers on a DB-25 connector.
20781 Signal Pin # Pin # Signal
20782 SG 7 connects to 7 SG
20783 TxD 2 connects to 3 RxD
20784 RxD 3 connects to 2 TxD
20785 RTS 4 connects to 5 CTS
20786 CTS 5 connects to 4 RTS
20787 DTR 20 connects to 6 DSR
20789 DSR 6 connects to 20 DTR
20791 Note: Connect ``Data Set Ready'' (DSR) and ``Data Carrier Detect'' (DCD)
20792 internally in the connector hood, and then to ``Data Terminal Ready''
20793 (DTR) in the remote hood.
20795 ----------------------------------------------------------------------
20797 17.2.2.1.2 Standard RS-232C Cables
20799 A standard serial cable passes all the RS-232C signals straight-through.
20800 That is, the ``send data'' pin on one end of the cable goes to the ``send
20801 data'' pin on the other end. This is the type of cable to use to connect a
20802 modem to your DragonFly system, and is also appropriate for some
20805 ----------------------------------------------------------------------
20809 Serial ports are the devices through which data is transferred between the
20810 DragonFly host computer and the terminal. This section describes the kinds
20811 of ports that exist and how they are addressed in DragonFly.
20813 ----------------------------------------------------------------------
20815 17.2.2.2.1 Kinds of Ports
20817 Several kinds of serial ports exist. Before you purchase or construct a
20818 cable, you need to make sure it will fit the ports on your terminal and on
20819 the DragonFly system.
20821 Most terminals will have DB25 ports. Personal computers, including PCs
20822 running DragonFly, will have DB25 or DB9 ports. If you have a multiport
20823 serial card for your PC, you may have RJ-12 or RJ-45 ports.
20825 See the documentation that accompanied the hardware for specifications on
20826 the kind of port in use. A visual inspection of the port often works too.
20828 ----------------------------------------------------------------------
20830 17.2.2.2.2 Port Names
20832 In DragonFly, you access each serial port through an entry in the /dev
20833 directory. There are two different kinds of entries:
20835 * Call-in ports are named /dev/ttydN where N is the port number,
20836 starting from zero. Generally, you use the call-in port for terminals.
20837 Call-in ports require that the serial line assert the data carrier
20838 detect (DCD) signal to work correctly.
20840 * Call-out ports are named /dev/cuaaN. You usually do not use the
20841 call-out port for terminals, just for modems. You may use the call-out
20842 port if the serial cable or the terminal does not support the carrier
20845 If you have connected a terminal to the first serial port (COM1 in
20846 MS-DOS), then you will use /dev/ttyd0 to refer to the terminal. If the
20847 terminal is on the second serial port (also known as COM2), use
20848 /dev/ttyd1, and so forth.
20850 ----------------------------------------------------------------------
20852 17.2.3 Kernel Configuration
20854 DragonFly supports four serial ports by default. In the MS-DOS world,
20855 these are known as COM1, COM2, COM3, and COM4. DragonFly currently
20856 supports ``dumb'' multiport serial interface cards, such as the BocaBoard
20857 1008 and 2016, as well as more intelligent multi-port cards such as those
20858 made by Digiboard and Stallion Technologies. However, the default kernel
20859 only looks for the standard COM ports.
20861 To see if your kernel recognizes any of your serial ports, watch for
20862 messages while the kernel is booting, or use the /sbin/dmesg command to
20863 replay the kernel's boot messages. In particular, look for messages that
20864 start with the characters sio.
20866 Tip: To view just the messages that have the word sio, use the command:
20868 # /sbin/dmesg | grep 'sio'
20870 For example, on a system with four serial ports, these are the serial-port
20871 specific kernel boot messages:
20873 sio0 at 0x3f8-0x3ff irq 4 on isa
20875 sio1 at 0x2f8-0x2ff irq 3 on isa
20877 sio2 at 0x3e8-0x3ef irq 5 on isa
20879 sio3 at 0x2e8-0x2ef irq 9 on isa
20882 If your kernel does not recognize all of your serial ports, you will
20883 probably need to configure a custom DragonFly kernel for your system. For
20884 detailed information on configuring your kernel, please see Chapter 9.
20886 The relevant device lines for your kernel configuration file would look
20889 device sio0 at isa? port IO_COM1 irq 4
20890 device sio1 at isa? port IO_COM2 irq 3
20891 device sio2 at isa? port IO_COM3 irq 5
20892 device sio3 at isa? port IO_COM4 irq 9
20894 You can comment-out or completely remove lines for devices you do not
20895 have. Please refer to the sio(4) manual page for more information on
20896 serial ports and multiport boards configuration.
20898 Note: port IO_COM1 is a substitution for port 0x3f8, IO_COM2 is 0x2f8,
20899 IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8, which are fairly common port
20900 addresses for their respective serial ports; interrupts 4, 3, 5, and 9
20901 are fairly common interrupt request lines. Also note that regular serial
20902 ports cannot share interrupts on ISA-bus PCs (multiport boards have
20903 on-board electronics that allow all the 16550A's on the board to share
20904 one or two interrupt request lines).
20906 ----------------------------------------------------------------------
20908 17.2.4 Device Special Files
20910 Most devices in the kernel are accessed through ``device special files'',
20911 which are located in the /dev directory. The sio devices are accessed
20912 through the /dev/ttydN (dial-in) and /dev/cuaaN (call-out) devices.
20913 DragonFly also provides initialization devices (/dev/ttyidN and
20914 /dev/cuaiaN) and locking devices (/dev/ttyldN and /dev/cualaN). The
20915 initialization devices are used to initialize communications port
20916 parameters each time a port is opened, such as crtscts for modems which
20917 use RTS/CTS signaling for flow control. The locking devices are used to
20918 lock flags on ports to prevent users or programs changing certain
20919 parameters; see the manual pages termios(4), sio(4), and stty(1) for
20920 information on the terminal settings, locking and initializing devices,
20921 and setting terminal options, respectively.
20923 ----------------------------------------------------------------------
20925 17.2.4.1 Making Device Special Files
20927 A shell script called MAKEDEV in the /dev directory manages the device
20928 special files. To use MAKEDEV to make dial-up device special files for
20929 COM1 (port 0), cd to /dev and issue the command MAKEDEV ttyd0. Likewise,
20930 to make dial-up device special files for COM2 (port 1), use MAKEDEV ttyd1.
20932 MAKEDEV not only creates the /dev/ttydN device special files, but also the
20933 /dev/cuaaN, /dev/cuaiaN, /dev/cualaN, /dev/ttyldN, and /dev/ttyidN nodes.
20935 After making new device special files, be sure to check the permissions on
20936 the files (especially the /dev/cua* files) to make sure that only users
20937 who should have access to those device special files can read and write on
20938 them -- you probably do not want to allow your average user to use your
20939 modems to dial-out. The default permissions on the /dev/cua* files should
20942 crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cuaa1
20943 crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuaia1
20944 crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cuala1
20946 These permissions allow the user uucp and users in the group dialer to use
20947 the call-out devices.
20949 ----------------------------------------------------------------------
20951 17.2.5 Serial Port Configuration
20953 The ttydN (or cuaaN) device is the regular device you will want to open
20954 for your applications. When a process opens the device, it will have a
20955 default set of terminal I/O settings. You can see these settings with the
20958 # stty -a -f /dev/ttyd1
20960 When you change the settings to this device, the settings are in effect
20961 until the device is closed. When it is reopened, it goes back to the
20962 default set. To make changes to the default set, you can open and adjust
20963 the settings of the ``initial state'' device. For example, to turn on
20964 CLOCAL mode, 8 bit communication, and XON/XOFF flow control by default for
20967 # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
20969 System-wide initialization of the serial devices is controlled in
20970 /etc/rc.serial. This file affects the default settings of serial devices.
20972 To prevent certain settings from being changed by an application, make
20973 adjustments to the ``lock state'' device. For example, to lock the speed
20974 of ttyd5 to 57600 bps, type:
20976 # stty -f /dev/ttyld5 57600
20978 Now, an application that opens ttyd5 and tries to change the speed of the
20979 port will be stuck with 57600 bps.
20981 Naturally, you should make the initial state and lock state devices
20982 writable only by the root account.
20984 ----------------------------------------------------------------------
20988 Contributed by Sean Kelly.
20990 Terminals provide a convenient and low-cost way to access your DragonFly
20991 system when you are not at the computer's console or on a connected
20992 network. This section describes how to use terminals with DragonFly.
20994 ----------------------------------------------------------------------
20996 17.3.1 Uses and Types of Terminals
20998 The original UNIX systems did not have consoles. Instead, people logged in
20999 and ran programs through terminals that were connected to the computer's
21000 serial ports. It is quite similar to using a modem and terminal software
21001 to dial into a remote system to do text-only work.
21003 Today's PCs have consoles capable of high quality graphics, but the
21004 ability to establish a login session on a serial port still exists in
21005 nearly every UNIX style operating system today; DragonFly is no exception.
21006 By using a terminal attached to an unused serial port, you can log in and
21007 run any text program that you would normally run on the console or in an
21008 xterm window in the X Window System.
21010 For the business user, you can attach many terminals to a DragonFly system
21011 and place them on your employees' desktops. For a home user, a spare
21012 computer such as an older IBM PC or a Macintosh can be a terminal wired
21013 into a more powerful computer running DragonFly. You can turn what might
21014 otherwise be a single-user computer into a powerful multiple user system.
21016 For DragonFly, there are three kinds of terminals:
21020 * PCs acting as terminals
21024 The remaining subsections describe each kind.
21026 ----------------------------------------------------------------------
21028 17.3.1.1 Dumb Terminals
21030 Dumb terminals are specialized pieces of hardware that let you connect to
21031 computers over serial lines. They are called ``dumb'' because they have
21032 only enough computational power to display, send, and receive text. You
21033 cannot run any programs on them. It is the computer to which you connect
21034 them that has all the power to run text editors, compilers, email, games,
21037 There are hundreds of kinds of dumb terminals made by many manufacturers,
21038 including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just
21039 about any kind will work with DragonFly. Some high-end terminals can even
21040 display graphics, but only certain software packages can take advantage of
21041 these advanced features.
21043 Dumb terminals are popular in work environments where workers do not need
21044 access to graphical applications such as those provided by the X Window
21047 ----------------------------------------------------------------------
21049 17.3.1.2 PCs Acting as Terminals
21051 If a dumb terminal has just enough ability to display, send, and receive
21052 text, then certainly any spare personal computer can be a dumb terminal.
21053 All you need is the proper cable and some terminal emulation software to
21054 run on the computer.
21056 Such a configuration is popular in homes. For example, if your spouse is
21057 busy working on your DragonFly system's console, you can do some text-only
21058 work at the same time from a less powerful personal computer hooked up as
21059 a terminal to the DragonFly system.
21061 ----------------------------------------------------------------------
21063 17.3.1.3 X Terminals
21065 X terminals are the most sophisticated kind of terminal available. Instead
21066 of connecting to a serial port, they usually connect to a network like
21067 Ethernet. Instead of being relegated to text-only applications, they can
21068 display any X application.
21070 We introduce X terminals just for the sake of completeness. However, this
21071 chapter does not cover setup, configuration, or use of X terminals.
21073 ----------------------------------------------------------------------
21075 17.3.2 Configuration
21077 This section describes what you need to configure on your DragonFly system
21078 to enable a login session on a terminal. It assumes you have already
21079 configured your kernel to support the serial port to which the terminal is
21080 connected--and that you have connected it.
21082 Recall from Chapter 7 that the init process is responsible for all process
21083 control and initialization at system startup. One of the tasks performed
21084 by init is to read the /etc/ttys file and start a getty process on the
21085 available terminals. The getty process is responsible for reading a login
21086 name and starting the login program.
21088 Thus, to configure terminals for your DragonFly system the following steps
21089 should be taken as root:
21091 1. Add a line to /etc/ttys for the entry in the /dev directory for the
21092 serial port if it is not already there.
21094 2. Specify that /usr/libexec/getty be run on the port, and specify the
21095 appropriate getty type from the /etc/gettytab file.
21097 3. Specify the default terminal type.
21099 4. Set the port to ``on.''
21101 5. Specify whether the port should be ``secure.''
21103 6. Force init to reread the /etc/ttys file.
21105 As an optional step, you may wish to create a custom getty type for use in
21106 step 2 by making an entry in /etc/gettytab. This chapter does not explain
21107 how to do so; you are encouraged to see the gettytab(5) and the getty(8)
21108 manual pages for more information.
21110 ----------------------------------------------------------------------
21112 17.3.2.1 Adding an Entry to /etc/ttys
21114 The /etc/ttys file lists all of the ports on your DragonFly system where
21115 you want to allow logins. For example, the first virtual console ttyv0 has
21116 an entry in this file. You can log in on the console using this entry.
21117 This file also contains entries for the other virtual consoles, serial
21118 ports, and pseudo-ttys. For a hardwired terminal, just list the serial
21119 port's /dev entry without the /dev part (for example, /dev/ttyv0 would be
21122 A default DragonFly install includes an /etc/ttys file with support for
21123 the first four serial ports: ttyd0 through ttyd3. If you are attaching a
21124 terminal to one of those ports, you do not need to add another entry.
21126 Example 17-1. Adding Terminal Entries to /etc/ttys
21128 Suppose we would like to connect two terminals to the system: a Wyse-50
21129 and an old 286 IBM PC running Procomm terminal software emulating a VT-100
21130 terminal. We connect the Wyse to the second serial port and the 286 to the
21131 sixth serial port (a port on a multiport serial card). The corresponding
21132 entries in the /etc/ttys file would look like this:
21134 ttyd1(1) "/usr/libexec/getty std.38400"(2) wy50(3) on(4) insecure(5)
21135 ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure
21139 The first field normally specifies the name of the terminal
21140 special file as it is found in /dev.
21142 The second field is the command to execute for this line, which is
21143 usually getty(8). getty initializes and opens the line, sets the
21144 speed, prompts for a user name and then executes the login(1)
21147 The getty program accepts one (optional) parameter on its command
21148 line, the getty type. A getty type configures characteristics on
21149 the terminal line, like bps rate and parity. The getty program
21150 reads these characteristics from the file /etc/gettytab.
21152 The file /etc/gettytab contains lots of entries for terminal lines
21153 both old and new. In almost all cases, the entries that start with
21154 the text std will work for hardwired terminals. These entries
21155 ignore parity. There is a std entry for each bps rate from 110 to
21156 115200. Of course, you can add your own entries to this file. The
21157 gettytab(5) manual page provides more information.
21159 When setting the getty type in the /etc/ttys file, make sure that
21160 the communications settings on the terminal match.
21162 For our example, the Wyse-50 uses no parity and connects at
21163 38400 bps. The 286 PC uses no parity and connects at 19200 bps.
21166 The third field is the type of terminal usually connected to that
21167 tty line. For dial-up ports, unknown or dialup is typically used
21168 in this field since users may dial up with practically any type of
21169 terminal or software. For hardwired terminals, the terminal type
21170 does not change, so you can put a real terminal type from the
21171 termcap(5) database file in this field.
21173 For our example, the Wyse-50 uses the real terminal type while the
21174 286 PC running Procomm will be set to emulate at VT-100.
21177 The fourth field specifies if the port should be enabled. Putting
21178 on here will have the init process start the program in the second
21179 field, getty. If you put off in this field, there will be no
21180 getty, and hence no logins on the port.
21182 The final field is used to specify whether the port is secure.
21183 Marking a port as secure means that you trust it enough to allow
21184 the root account (or any account with a user ID of 0) to login
21185 from that port. Insecure ports do not allow root logins. On an
21186 insecure port, users must login from unprivileged accounts and
21187 then use su(1) or a similar mechanism to gain superuser
21190 It is highly recommended that you use ``insecure'' even for
21191 terminals that are behind locked doors. It is quite easy to login
21192 and use su if you need superuser privileges.
21194 ----------------------------------------------------------------------
21196 17.3.2.2 Force init to Reread /etc/ttys
21198 After making the necessary changes to the /etc/ttys file you should send a
21199 SIGHUP (hangup) signal to the init process to force it to re-read its
21200 configuration file. For example:
21204 Note: init is always the first process run on a system, therefore it
21205 will always have PID 1.
21207 If everything is set up correctly, all cables are in place, and the
21208 terminals are powered up, then a getty process should be running on each
21209 terminal and you should see login prompts on your terminals at this point.
21211 ----------------------------------------------------------------------
21213 17.3.3 Troubleshooting Your Connection
21215 Even with the most meticulous attention to detail, something could still
21216 go wrong while setting up a terminal. Here is a list of symptoms and some
21219 ----------------------------------------------------------------------
21221 17.3.3.1 No Login Prompt Appears
21223 Make sure the terminal is plugged in and powered up. If it is a personal
21224 computer acting as a terminal, make sure it is running terminal emulation
21225 software on the correct serial port.
21227 Make sure the cable is connected firmly to both the terminal and the
21228 DragonFly computer. Make sure it is the right kind of cable.
21230 Make sure the terminal and DragonFly agree on the bps rate and parity
21231 settings. If you have a video display terminal, make sure the contrast and
21232 brightness controls are turned up. If it is a printing terminal, make sure
21233 paper and ink are in good supply.
21235 Make sure that a getty process is running and serving the terminal. For
21236 example, to get a list of running getty processes with ps, type:
21238 # ps -axww|grep getty
21240 You should see an entry for the terminal. For example, the following
21241 display shows that a getty is running on the second serial port ttyd1 and
21242 is using the std.38400 entry in /etc/gettytab:
21244 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1
21246 If no getty process is running, make sure you have enabled the port in
21247 /etc/ttys. Also remember to run kill -HUP 1 after modifying the ttys file.
21249 If the getty process is running but the terminal still does not display a
21250 login prompt, or if it displays a prompt but will not allow you to type,
21251 your terminal or cable may not support hardware handshaking. Try changing
21252 the entry in /etc/ttys from std.38400 to 3wire.38400 remember to run kill
21253 -HUP 1 after modifying /etc/ttys). The 3wire entry is similar to std, but
21254 ignores hardware handshaking. You may need to reduce the baud rate or
21255 enable software flow control when using 3wire to prevent buffer overflows.
21257 ----------------------------------------------------------------------
21259 17.3.3.2 If Garbage Appears Instead of a Login Prompt
21261 Make sure the terminal and DragonFly agree on the bps rate and parity
21262 settings. Check the getty processes to make sure the correct getty type is
21263 in use. If not, edit /etc/ttys and run kill -HUP 1.
21265 ----------------------------------------------------------------------
21267 17.3.3.3 Characters Appear Doubled; the Password Appears When Typed
21269 Switch the terminal (or the terminal emulation software) from ``half
21270 duplex'' or ``local echo'' to ``full duplex.''
21272 ----------------------------------------------------------------------
21274 17.4 Dial-in Service
21276 Contributed by Guy Helmer. Additions by Sean Kelly.
21278 Configuring your DragonFly system for dial-in service is very similar to
21279 connecting terminals except that you are dealing with modems instead of
21282 ----------------------------------------------------------------------
21284 17.4.1 External vs. Internal Modems
21286 External modems seem to be more convenient for dial-up, because external
21287 modems often can be semi-permanently configured via parameters stored in
21288 non-volatile RAM and they usually provide lighted indicators that display
21289 the state of important RS-232 signals. Blinking lights impress visitors,
21290 but lights are also very useful to see whether a modem is operating
21293 Internal modems usually lack non-volatile RAM, so their configuration may
21294 be limited only to setting DIP switches. If your internal modem has any
21295 signal indicator lights, it is probably difficult to view the lights when
21296 the system's cover is in place.
21298 ----------------------------------------------------------------------
21300 17.4.1.1 Modems and Cables
21302 If you are using an external modem, then you will of course need the
21303 proper cable. A standard RS-232C serial cable should suffice as long as
21304 all of the normal signals are wired:
21306 * Transmitted Data (SD)
21308 * Received Data (RD)
21310 * Request to Send (RTS)
21312 * Clear to Send (CTS)
21314 * Data Set Ready (DSR)
21316 * Data Terminal Ready (DTR)
21318 * Carrier Detect (CD)
21320 * Signal Ground (SG)
21322 DragonFly needs the RTS and CTS signals for flow-control at speeds above
21323 2400 bps, the CD signal to detect when a call has been answered or the
21324 line has been hung up, and the DTR signal to reset the modem after a
21325 session is complete. Some cables are wired without all of the needed
21326 signals, so if you have problems, such as a login session not going away
21327 when the line hangs up, you may have a problem with your cable.
21329 Like other UNIX like operating systems, DragonFly uses the hardware
21330 signals to find out when a call has been answered or a line has been hung
21331 up and to hangup and reset the modem after a call. DragonFly avoids
21332 sending commands to the modem or watching for status reports from the
21333 modem. If you are familiar with connecting modems to PC-based bulletin
21334 board systems, this may seem awkward.
21336 ----------------------------------------------------------------------
21338 17.4.2 Serial Interface Considerations
21340 DragonFly supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA
21341 RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices
21342 have single-character buffers. The 16550 device provides a 16-character
21343 buffer, which allows for better system performance. (Bugs in plain 16550's
21344 prevent the use of the 16-character buffer, so use 16550A's if possible).
21345 Because single-character-buffer devices require more work by the operating
21346 system than the 16-character-buffer devices, 16550A-based serial interface
21347 cards are much preferred. If the system has many active serial ports or
21348 will have a heavy load, 16550A-based cards are better for low-error-rate
21351 ----------------------------------------------------------------------
21353 17.4.3 Quick Overview
21355 As with terminals, init spawns a getty process for each configured serial
21356 port for dial-in connections. For example, if a modem is attached to
21357 /dev/ttyd0, the command ps ax might show this:
21359 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
21361 When a user dials the modem's line and the modems connect, the CD (Carrier
21362 Detect) line is reported by the modem. The kernel notices that carrier has
21363 been detected and completes getty's open of the port. getty sends a login:
21364 prompt at the specified initial line speed. getty watches to see if
21365 legitimate characters are received, and, in a typical configuration, if it
21366 finds junk (probably due to the modem's connection speed being different
21367 than getty's speed), getty tries adjusting the line speeds until it
21368 receives reasonable characters.
21370 After the user enters his/her login name, getty executes /usr/bin/login,
21371 which completes the login by asking for the user's password and then
21372 starting the user's shell.
21374 ----------------------------------------------------------------------
21376 17.4.4 Configuration Files
21378 There are three system configuration files in the /etc directory that you
21379 will probably need to edit to allow dial-up access to your DragonFly
21380 system. The first, /etc/gettytab, contains configuration information for
21381 the /usr/libexec/getty daemon. Second, /etc/ttys holds information that
21382 tells /sbin/init what tty devices should have getty processes running on
21383 them. Lastly, you can place port initialization commands in the
21384 /etc/rc.serial script.
21386 There are two schools of thought regarding dial-up modems on UNIX. One
21387 group likes to configure their modems and systems so that no matter at
21388 what speed a remote user dials in, the local computer-to-modem RS-232
21389 interface runs at a locked speed. The benefit of this configuration is
21390 that the remote user always sees a system login prompt immediately. The
21391 downside is that the system does not know what a user's true data rate is,
21392 so full-screen programs like Emacs will not adjust their screen-painting
21393 methods to make their response better for slower connections.
21395 The other school configures their modems' RS-232 interface to vary its
21396 speed based on the remote user's connection speed. For example, V.32bis
21397 (14.4 Kbps) connections to the modem might make the modem run its RS-232
21398 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232
21399 interface run at 2400 bps. Because getty does not understand any
21400 particular modem's connection speed reporting, getty gives a login:
21401 message at an initial speed and watches the characters that come back in
21402 response. If the user sees junk, it is assumed that they know they should
21403 press the Enter key until they see a recognizable prompt. If the data
21404 rates do not match, getty sees anything the user types as ``junk'', tries
21405 going to the next speed and gives the login: prompt again. This procedure
21406 can continue ad nauseam, but normally only takes a keystroke or two before
21407 the user sees a good prompt. Obviously, this login sequence does not look
21408 as clean as the former ``locked-speed'' method, but a user on a low-speed
21409 connection should receive better interactive response from full-screen
21412 This section will try to give balanced configuration information, but is
21413 biased towards having the modem's data rate follow the connection rate.
21415 ----------------------------------------------------------------------
21417 17.4.4.1 /etc/gettytab
21419 /etc/gettytab is a termcap(5)-style file of configuration information for
21420 getty(8). Please see the gettytab(5) manual page for complete information
21421 on the format of the file and the list of capabilities.
21423 ----------------------------------------------------------------------
21425 17.4.4.1.1 Locked-speed Config
21427 If you are locking your modem's data communications rate at a particular
21428 speed, you probably will not need to make any changes to /etc/gettytab.
21430 ----------------------------------------------------------------------
21432 17.4.4.1.2 Matching-speed Config
21434 You will need to set up an entry in /etc/gettytab to give getty
21435 information about the speeds you wish to use for your modem. If you have a
21436 2400 bps modem, you can probably use the existing D2400 entry.
21439 # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
21441 D2400|d2400|Fast-Dial-2400:\
21442 :nx=D1200:tc=2400-baud:
21443 3|D1200|Fast-Dial-1200:\
21444 :nx=D300:tc=1200-baud:
21445 5|D300|Fast-Dial-300:\
21446 :nx=D2400:tc=300-baud:
21448 If you have a higher speed modem, you will probably need to add an entry
21449 in /etc/gettytab; here is an entry you could use for a 14.4 Kbps modem
21450 with a top interface speed of 19.2 Kbps:
21453 # Additions for a V.32bis Modem
21455 um|V300|High Speed Modem at 300,8-bit:\
21456 :nx=V19200:tc=std.300:
21457 un|V1200|High Speed Modem at 1200,8-bit:\
21458 :nx=V300:tc=std.1200:
21459 uo|V2400|High Speed Modem at 2400,8-bit:\
21460 :nx=V1200:tc=std.2400:
21461 up|V9600|High Speed Modem at 9600,8-bit:\
21462 :nx=V2400:tc=std.9600:
21463 uq|V19200|High Speed Modem at 19200,8-bit:\
21464 :nx=V9600:tc=std.19200:
21466 This will result in 8-bit, no parity connections.
21468 The example above starts the communications rate at 19.2 Kbps (for a
21469 V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps,
21470 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is
21471 implemented with the nx= (``next table'') capability. Each of the lines
21472 uses a tc= (``table continuation'') entry to pick up the rest of the
21473 ``standard'' settings for a particular data rate.
21475 If you have a 28.8 Kbps modem and/or you want to take advantage of
21476 compression on a 14.4 Kbps modem, you need to use a higher communications
21477 rate than 19.2 Kbps. Here is an example of a gettytab entry starting a
21481 # Additions for a V.32bis or V.34 Modem
21482 # Starting at 57.6 Kbps
21484 vm|VH300|Very High Speed Modem at 300,8-bit:\
21485 :nx=VH57600:tc=std.300:
21486 vn|VH1200|Very High Speed Modem at 1200,8-bit:\
21487 :nx=VH300:tc=std.1200:
21488 vo|VH2400|Very High Speed Modem at 2400,8-bit:\
21489 :nx=VH1200:tc=std.2400:
21490 vp|VH9600|Very High Speed Modem at 9600,8-bit:\
21491 :nx=VH2400:tc=std.9600:
21492 vq|VH57600|Very High Speed Modem at 57600,8-bit:\
21493 :nx=VH9600:tc=std.57600:
21495 If you have a slow CPU or a heavily loaded system and do not have
21496 16550A-based serial ports, you may receive ``sio'' ``silo'' errors at
21499 ----------------------------------------------------------------------
21503 Configuration of the /etc/ttys file was covered in Example 17-1.
21504 Configuration for modems is similar but we must pass a different argument
21505 to getty and specify a different terminal type. The general format for
21506 both locked-speed and matching-speed configurations is:
21508 ttyd0 "/usr/libexec/getty xxx" dialup on
21510 The first item in the above line is the device special file for this entry
21511 -- ttyd0 means /dev/ttyd0 is the file that this getty will be watching.
21512 The second item, "/usr/libexec/getty xxx" (xxx will be replaced by the
21513 initial gettytab capability) is the process init will run on the device.
21514 The third item, dialup, is the default terminal type. The fourth
21515 parameter, on, indicates to init that the line is operational. There can
21516 be a fifth parameter, secure, but it should only be used for terminals
21517 which are physically secure (such as the system console).
21519 The default terminal type (dialup in the example above) may depend on
21520 local preferences. dialup is the traditional default terminal type on
21521 dial-up lines so that users may customize their login scripts to notice
21522 when the terminal is dialup and automatically adjust their terminal type.
21523 However, the author finds it easier at his site to specify vt102 as the
21524 default terminal type, since the users just use VT102 emulation on their
21527 After you have made changes to /etc/ttys, you may send the init process a
21528 HUP signal to re-read the file. You can use the command
21532 to send the signal. If this is your first time setting up the system, you
21533 may want to wait until your modem(s) are properly configured and connected
21534 before signaling init.
21536 ----------------------------------------------------------------------
21538 17.4.4.2.1 Locked-speed Config
21540 For a locked-speed configuration, your ttys entry needs to have a
21541 fixed-speed entry provided to getty. For a modem whose port speed is
21542 locked at 19.2 Kbps, the ttys entry might look like this:
21544 ttyd0 "/usr/libexec/getty std.19200" dialup on
21546 If your modem is locked at a different data rate, substitute the
21547 appropriate value for std.speed instead of std.19200. Make sure that you
21548 use a valid type listed in /etc/gettytab.
21550 ----------------------------------------------------------------------
21552 17.4.4.2.2 Matching-speed Config
21554 In a matching-speed configuration, your ttys entry needs to reference the
21555 appropriate beginning ``auto-baud'' (sic) entry in /etc/gettytab. For
21556 example, if you added the above suggested entry for a matching-speed modem
21557 that starts at 19.2 Kbps (the gettytab entry containing the V19200
21558 starting point), your ttys entry might look like this:
21560 ttyd0 "/usr/libexec/getty V19200" dialup on
21562 ----------------------------------------------------------------------
21564 17.4.4.3 /etc/rc.serial
21566 High-speed modems, like V.32, V.32bis, and V.34 modems, need to use
21567 hardware (RTS/CTS) flow control. You can add stty commands to
21568 /etc/rc.serial to set the hardware flow control flag in the DragonFly
21569 kernel for the modem ports.
21571 For example to set the termios flag crtscts on serial port #1's (COM2)
21572 dial-in and dial-out initialization devices, the following lines could be
21573 added to /etc/rc.serial:
21575 # Serial port initial configuration
21576 stty -f /dev/ttyid1 crtscts
21577 stty -f /dev/cuaia1 crtscts
21579 ----------------------------------------------------------------------
21581 17.4.5 Modem Settings
21583 If you have a modem whose parameters may be permanently set in
21584 non-volatile RAM, you will need to use a terminal program (such as Telix
21585 under MS-DOS or tip under DragonFly) to set the parameters. Connect to the
21586 modem using the same communications speed as the initial speed getty will
21587 use and configure the modem's non-volatile RAM to match these
21590 * CD asserted when connected
21592 * DTR asserted for operation; dropping DTR hangs up line and resets
21595 * CTS transmitted data flow control
21597 * Disable XON/XOFF flow control
21599 * RTS received data flow control
21601 * Quiet mode (no result codes)
21605 Please read the documentation for your modem to find out what commands
21606 and/or DIP switch settings you need to give it.
21608 For example, to set the above parameters on a U.S. Robotics(R)
21609 Sportster(R) 14,400 external modem, one could give these commands to the
21613 AT&C1&D2&H1&I0&R2&W
21615 You might also want to take this opportunity to adjust other settings in
21616 the modem, such as whether it will use V.42bis and/or MNP5 compression.
21618 The U.S. Robotics Sportster 14,400 external modem also has some DIP
21619 switches that need to be set; for other modems, perhaps you can use these
21620 settings as an example:
21622 * Switch 1: UP -- DTR Normal
21624 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
21626 * Switch 3: UP -- Suppress Result Codes
21628 * Switch 4: DOWN -- No echo, offline commands
21630 * Switch 5: UP -- Auto Answer
21632 * Switch 6: UP -- Carrier Detect Normal
21634 * Switch 7: UP -- Load NVRAM Defaults
21636 * Switch 8: N/A (Smart Mode/Dumb Mode)
21638 Result codes should be disabled/suppressed for dial-up modems to avoid
21639 problems that can occur if getty mistakenly gives a login: prompt to a
21640 modem that is in command mode and the modem echoes the command or returns
21641 a result code. This sequence can result in a extended, silly conversation
21642 between getty and the modem.
21644 ----------------------------------------------------------------------
21646 17.4.5.1 Locked-speed Config
21648 For a locked-speed configuration, you will need to configure the modem to
21649 maintain a constant modem-to-computer data rate independent of the
21650 communications rate. On a U.S. Robotics Sportster 14,400 external modem,
21651 these commands will lock the modem-to-computer data rate at the speed used
21652 to issue the commands:
21657 ----------------------------------------------------------------------
21659 17.4.5.2 Matching-speed Config
21661 For a variable-speed configuration, you will need to configure your modem
21662 to adjust its serial port data rate to match the incoming call rate. On a
21663 U.S. Robotics Sportster 14,400 external modem, these commands will lock
21664 the modem's error-corrected data rate to the speed used to issue the
21665 commands, but allow the serial port rate to vary for non-error-corrected
21671 ----------------------------------------------------------------------
21673 17.4.5.3 Checking the Modem's Configuration
21675 Most high-speed modems provide commands to view the modem's current
21676 operating parameters in a somewhat human-readable fashion. On the U.S.
21677 Robotics Sportster 14,400 external modems, the command ATI5 displays the
21678 settings that are stored in the non-volatile RAM. To see the true
21679 operating parameters of the modem (as influenced by the modem's DIP switch
21680 settings), use the commands ATZ and then ATI4.
21682 If you have a different brand of modem, check your modem's manual to see
21683 how to double-check your modem's configuration parameters.
21685 ----------------------------------------------------------------------
21687 17.4.6 Troubleshooting
21689 Here are a few steps you can follow to check out the dial-up modem on your
21692 ----------------------------------------------------------------------
21694 17.4.6.1 Checking Out the DragonFly System
21696 Hook up your modem to your DragonFly system, boot the system, and, if your
21697 modem has status indication lights, watch to see whether the modem's DTR
21698 indicator lights when the login: prompt appears on the system's console --
21699 if it lights up, that should mean that DragonFly has started a getty
21700 process on the appropriate communications port and is waiting for the
21701 modem to accept a call.
21703 If the DTR indicator does not light, login to the DragonFly system through
21704 the console and issue a ps ax to see if DragonFly is trying to run a getty
21705 process on the correct port. You should see lines like these among the
21706 processes displayed:
21708 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
21709 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
21711 If you see something different, like this:
21713 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
21715 and the modem has not accepted a call yet, this means that getty has
21716 completed its open on the communications port. This could indicate a
21717 problem with the cabling or a mis-configured modem, because getty should
21718 not be able to open the communications port until CD (carrier detect) has
21719 been asserted by the modem.
21721 If you do not see any getty processes waiting to open the desired ttydN
21722 port, double-check your entries in /etc/ttys to see if there are any
21723 mistakes there. Also, check the log file /var/log/messages to see if there
21724 are any log messages from init or getty regarding any problems. If there
21725 are any messages, triple-check the configuration files /etc/ttys and
21726 /etc/gettytab, as well as the appropriate device special files /dev/ttydN,
21727 for any mistakes, missing entries, or missing device special files.
21729 ----------------------------------------------------------------------
21731 17.4.6.2 Try Dialing In
21733 Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop
21734 bit on the remote system. If you do not get a prompt right away, or get
21735 garbage, try pressing Enter about once per second. If you still do not see
21736 a login: prompt after a while, try sending a BREAK. If you are using a
21737 high-speed modem to do the dialing, try dialing again after locking the
21738 dialing modem's interface speed (via AT&B1 on a U.S. Robotics Sportster
21739 modem, for example).
21741 If you still cannot get a login: prompt, check /etc/gettytab again and
21744 * The initial capability name specified in /etc/ttys for the line
21745 matches a name of a capability in /etc/gettytab
21747 * Each nx= entry matches another gettytab capability name
21749 * Each tc= entry matches another gettytab capability name
21751 If you dial but the modem on the DragonFly system will not answer, make
21752 sure that the modem is configured to answer the phone when DTR is
21753 asserted. If the modem seems to be configured correctly, verify that the
21754 DTR line is asserted by checking the modem's indicator lights (if it has
21757 If you have gone over everything several times and it still does not work,
21758 take a break and come back to it later. If it still does not work, perhaps
21759 you can send an electronic mail message to the DragonFly User related
21760 mailing list describing your modem and your problem, and the good folks on
21761 the list will try to help.
21763 ----------------------------------------------------------------------
21765 17.5 Dial-out Service
21767 The following are tips for getting your host to be able to connect over
21768 the modem to another computer. This is appropriate for establishing a
21769 terminal session with a remote host.
21771 This is useful to log onto a BBS.
21773 This kind of connection can be extremely helpful to get a file on the
21774 Internet if you have problems with PPP. If you need to FTP something and
21775 PPP is broken, use the terminal session to FTP it. Then use zmodem to
21776 transfer it to your machine.
21778 ----------------------------------------------------------------------
21780 17.5.1 My Stock Hayes Modem Is Not Supported, What Can I Do?
21782 Actually, the manual page for tip is out of date. There is a generic Hayes
21783 dialer already built in. Just use at=hayes in your /etc/remote file.
21785 The Hayes driver is not smart enough to recognize some of the advanced
21786 features of newer modems--messages like BUSY, NO DIALTONE, or CONNECT
21787 115200 will just confuse it. You should turn those messages off when you
21788 use tip (using ATX0&W).
21790 Also, the dial timeout for tip is 60 seconds. Your modem should use
21791 something less, or else tip will think there is a communication problem.
21794 Note: As shipped, tip does not yet support Hayes modems fully. The
21795 solution is to edit the file tipconf.h in the directory
21796 /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to
21799 Edit the line #define HAYES 0 to #define HAYES 1. Then make and make
21800 install. Everything works nicely after that.
21802 ----------------------------------------------------------------------
21804 17.5.2 How Am I Expected to Enter These AT Commands?
21806 Make what is called a ``direct'' entry in your /etc/remote file. For
21807 example, if your modem is hooked up to the first serial port, /dev/cuaa0,
21808 then put in the following line:
21810 cuaa0:dv=/dev/cuaa0:br#19200:pa=none
21812 Use the highest bps rate your modem supports in the br capability. Then,
21813 type tip cuaa0 and you will be connected to your modem.
21815 If there is no /dev/cuaa0 on your system, do this:
21820 Or use cu as root with the following command:
21822 # cu -lline -sspeed
21824 line is the serial port (e.g./dev/cuaa0) and speed is the speed
21825 (e.g.57600). When you are done entering the AT commands hit ~. to exit.
21827 ----------------------------------------------------------------------
21829 17.5.3 The @ Sign for the pn Capability Does Not Work!
21831 The @ sign in the phone number capability tells tip to look in /etc/phones
21832 for a phone number. But the @ sign is also a special character in
21833 capability files like /etc/remote. Escape it with a backslash:
21837 ----------------------------------------------------------------------
21839 17.5.4 How Can I Dial a Phone Number on the Command Line?
21841 Put what is called a ``generic'' entry in your /etc/remote file. For
21844 tip115200|Dial any phone number at 115200 bps:\
21845 :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
21846 tip57600|Dial any phone number at 57600 bps:\
21847 :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:
21849 Then you can do things like:
21851 # tip -115200 5551234
21853 If you prefer cu over tip, use a generic cu entry:
21855 cu115200|Use cu to dial any number at 115200bps:\
21856 :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:
21860 # cu 5551234 -s 115200
21862 ----------------------------------------------------------------------
21864 17.5.5 Do I Have to Type in the bps Rate Every Time I Do That?
21866 Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps
21867 rate is appropriate with the br capability. tip thinks a good default is
21868 1200 bps which is why it looks for a tip1200 entry. You do not have to use
21871 ----------------------------------------------------------------------
21873 17.5.6 I Access a Number of Hosts Through a Terminal Server
21875 Rather than waiting until you are connected and typing CONNECT <host> each
21876 time, use tip's cm capability. For example, these entries in /etc/remote:
21878 pain|pain.deep13.com|Forrester's machine:\
21879 :cm=CONNECT pain\n:tc=deep13:
21880 muffin|muffin.deep13.com|Frank's machine:\
21881 :cm=CONNECT muffin\n:tc=deep13:
21882 deep13:Gizmonics Institute terminal server:\
21883 :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:
21885 will let you type tip pain or tip muffin to connect to the hosts pain or
21886 muffin, and tip deep13 to get to the terminal server.
21888 ----------------------------------------------------------------------
21890 17.5.7 Can Tip Try More Than One Line for Each Site?
21892 This is often a problem where a university has several modem lines and
21893 several thousand students trying to use them.
21895 Make an entry for your university in /etc/remote and use @ for the pn
21901 :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:
21903 Then, list the phone numbers for the university in /etc/phones:
21905 big-university 5551111
21906 big-university 5551112
21907 big-university 5551113
21908 big-university 5551114
21910 tip will try each one in the listed order, then give up. If you want to
21911 keep retrying, run tip in a while loop.
21913 ----------------------------------------------------------------------
21915 17.5.8 Why Do I Have to Hit Ctrl+P Twice to Send Ctrl+P Once?
21917 Ctrl+P is the default ``force'' character, used to tell tip that the next
21918 character is literal data. You can set the force character to any other
21919 character with the ~s escape, which means ``set a variable.''
21921 Type ~sforce=single-char followed by a newline. single-char is any single
21922 character. If you leave out single-char, then the force character is the
21923 nul character, which you can get by typing Ctrl+2 or Ctrl+Space. A pretty
21924 good value for single-char is Shift+Ctrl+6, which is only used on some
21927 You can have the force character be whatever you want by specifying the
21928 following in your $HOME/.tiprc file:
21930 force=<single-char>
21932 ----------------------------------------------------------------------
21934 17.5.9 Suddenly Everything I Type Is in Upper Case??
21936 You must have pressed Ctrl+A, tip's ``raise character,'' specially
21937 designed for people with broken caps-lock keys. Use ~s as above and set
21938 the variable raisechar to something reasonable. In fact, you can set it to
21939 the same as the force character, if you never expect to use either of
21942 Here is a sample .tiprc file perfect for Emacs users who need to type
21943 Ctrl+2 and Ctrl+A a lot:
21948 The ^^ is Shift+Ctrl+6.
21950 ----------------------------------------------------------------------
21952 17.5.10 How Can I Do File Transfers with tip?
21954 If you are talking to another UNIX system, you can send and receive files
21955 with ~p (put) and ~t (take). These commands run cat and echo on the remote
21956 system to accept and send files. The syntax is:
21958 ~p local-file [remote-file]
21960 ~t remote-file [local-file]
21962 There is no error checking, so you probably should use another protocol,
21965 ----------------------------------------------------------------------
21967 17.5.11 How Can I Run zmodem with tip?
21969 To receive files, start the sending program on the remote end. Then, type
21970 ~C rz to begin receiving them locally.
21972 To send files, start the receiving program on the remote end. Then, type
21973 ~C sz files to send them to the remote system.
21975 ----------------------------------------------------------------------
21977 17.6 Setting Up the Serial Console
21979 Contributed by Kazutaka YOKOTA. Based on a document by Bill Paul.
21981 ----------------------------------------------------------------------
21983 17.6.1 Introduction
21985 DragonFly has the ability to boot on a system with only a dumb terminal on
21986 a serial port as a console. Such a configuration should be useful for two
21987 classes of people: system administrators who wish to install DragonFly on
21988 machines that have no keyboard or monitor attached, and developers who
21989 want to debug the kernel or device drivers.
21991 As described in Chapter 7, DragonFly employs a three stage bootstrap. The
21992 first two stages are in the boot block code which is stored at the
21993 beginning of the DragonFly slice on the boot disk. The boot block will
21994 then load and run the boot loader (/boot/loader) as the third stage code.
21996 In order to set up the serial console you must configure the boot block
21997 code, the boot loader code and the kernel.
21999 ----------------------------------------------------------------------
22001 17.6.2 Serial Console Configuration, Terse Version
22003 This section assumes that you are using the default setup, know how to
22004 connect serial ports and just want a fast overview of a serial console. If
22005 you encounter difficulty with these steps, please see the more extensive
22006 explaination of all the options and advanced settings in Section 17.6.3.
22008 1. Connect the serial port. The serial console will be on COM1.
22010 2. echo -h > /boot.config to enable the serial console for the boot
22013 3. Edit /etc/ttys and change off to on for the ttyd0 entry. This enables
22014 a login prompt on the serial console, which mirrors how video consoles
22015 are typically setup.
22017 4. shutdown -r now will reboot the system with the serial console.
22019 ----------------------------------------------------------------------
22021 17.6.3 Serial Console Configuration
22023 1. Prepare a serial cable.
22025 You will need either a null-modem cable or a standard serial cable and
22026 a null-modem adapter. See Section 17.2.2 for a discussion on serial
22029 2. Unplug your keyboard.
22031 Most PC systems probe for the keyboard during the Power-On Self-Test
22032 (POST) and will generate an error if the keyboard is not detected.
22033 Some machines complain loudly about the lack of a keyboard and will
22034 not continue to boot until it is plugged in.
22036 If your computer complains about the error, but boots anyway, then you
22037 do not have to do anything special. (Some machines with Phoenix BIOS
22038 installed merely say ``Keyboard failed'' and continue to boot
22041 If your computer refuses to boot without a keyboard attached then you
22042 will have to configure the BIOS so that it ignores this error (if it
22043 can). Consult your motherboard's manual for details on how to do this.
22045 Tip: Setting the keyboard to ``Not installed'' in the BIOS setup
22046 does not mean that you will not be able to use your keyboard. All
22047 this does is tell the BIOS not to probe for a keyboard at power-on,
22048 so it will not complain if the keyboard is not plugged in. You can
22049 leave the keyboard plugged in even with this flag set to ``Not
22050 installed'' and the keyboard will still work.
22052 Note: If your system has a PS/2(R) mouse, chances are very good that
22053 you may have to unplug your mouse as well as your keyboard. This is
22054 because PS/2 mice share some hardware with the keyboard and leaving
22055 the mouse plugged in can fool the keyboard probe into thinking the
22056 keyboard is still there. In general, this is not a problem since the
22057 mouse is not much good without the keyboard anyway.
22059 3. Plug a dumb terminal into COM1 (sio0).
22061 If you do not have a dumb terminal, you can use an old PC/XT with a
22062 modem program, or the serial port on another UNIX box. If you do not
22063 have a COM1 (sio0), get one. At this time, there is no way to select a
22064 port other than COM1 for the boot blocks without recompiling the boot
22065 blocks. If you are already using COM1 for another device, you will
22066 have to temporarily remove that device and install a new boot block
22067 and kernel once you get DragonFly up and running. (It is assumed that
22068 COM1 will be available on a file/compute/terminal server anyway; if
22069 you really need COM1 for something else (and you cannot switch that
22070 something else to COM2 (sio1)), then you probably should not even be
22071 bothering with all this in the first place.)
22073 4. Make sure the configuration file of your kernel has appropriate flags
22074 set for COM1 (sio0).
22076 Relevant flags are:
22080 Enables console support for this unit. The other console
22081 flags are ignored unless this is set. Currently, at most
22082 one unit can have console support; the first one (in
22083 config file order) with this flag set is preferred. This
22084 option alone will not make the serial port the console.
22085 Set the following flag or use the -h option described
22086 below, together with this flag.
22090 Forces this unit to be the console (unless there is
22091 another higher priority console), regardless of the -h
22092 option discussed below. This flag replaces the COMCONSOLE
22093 option in DragonFly versions 2.X. The flag 0x20 must be
22094 used together with the 0x10 flag.
22098 Reserves this unit (in conjunction with 0x10) and makes
22099 the unit unavailable for normal access. You should not
22100 set this flag to the serial port unit which you want to
22101 use as the serial console. This reserves this port for
22102 "low-level IO", i.e. kernel debugging.
22106 This port will be used for remote kernel debugging.
22110 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
22112 See the sio(4) manual page for more details.
22114 If the flags were not set, you need to run UserConfig (on a different
22115 console) or recompile the kernel.
22117 5. Create boot.config in the root directory of the a partition on the
22120 This file will instruct the boot block code how you would like to boot
22121 the system. In order to activate the serial console, you need one or
22122 more of the following options--if you want multiple options, include
22123 them all on the same line:
22127 Toggles internal and serial consoles. You can use this to
22128 switch console devices. For instance, if you boot from
22129 the internal (video) console, you can use -h to direct
22130 the boot loader and the kernel to use the serial port as
22131 its console device. Alternatively, if you boot from the
22132 serial port, you can use the -h to tell the boot loader
22133 and the kernel to use the video display as the console
22138 Toggles single and dual console configurations. In the
22139 single configuration the console will be either the
22140 internal console (video display) or the serial port,
22141 depending on the state of the -h option above. In the
22142 dual console configuration, both the video display and
22143 the serial port will become the console at the same time,
22144 regardless of the state of the -h option. However, note
22145 that the dual console configuration takes effect only
22146 during the boot block is running. Once the boot loader
22147 gets control, the console specified by the -h option
22148 becomes the only console.
22152 Makes the boot block probe the keyboard. If no keyboard
22153 is found, the -D and -h options are automatically set.
22155 Note: Due to space constraints in the current version
22156 of the boot blocks, the -P option is capable of
22157 detecting extended keyboards only. Keyboards with less
22158 than 101 keys (and without F11 and F12 keys) may not be
22159 detected. Keyboards on some laptop computers may not be
22160 properly found because of this limitation. If this is
22161 the case with your system, you have to abandon using
22162 the -P option. Unfortunately there is no workaround for
22165 Use either the -P option to select the console automatically, or the
22166 -h option to activate the serial console.
22168 You may include other options described in boot(8) as well.
22170 The options, except for -P, will be passed to the boot loader
22171 (/boot/loader). The boot loader will determine which of the internal
22172 video or the serial port should become the console by examining the
22173 state of the -h option alone. This means that if you specify the -D
22174 option but not the -h option in /boot.config, you can use the serial
22175 port as the console only during the boot block; the boot loader will
22176 use the internal video display as the console.
22178 6. Boot the machine.
22180 When you start your DragonFly box, the boot blocks will echo the
22181 contents of /boot.config to the console. For example:
22186 The second line appears only if you put -P in /boot.config and
22187 indicates presence/absence of the keyboard. These messages go to
22188 either serial or internal console, or both, depending on the option in
22191 Options Message goes to
22192 none internal console
22194 -D serial and internal consoles
22195 -Dh serial and internal consoles
22196 -P, keyboard present internal console
22197 -P, keyboard absent serial console
22199 After the above messages, there will be a small pause before the boot
22200 blocks continue loading the boot loader and before any further
22201 messages printed to the console. Under normal circumstances, you do
22202 not need to interrupt the boot blocks, but you may want to do so in
22203 order to make sure things are set up correctly.
22205 Hit any key, other than Enter, at the console to interrupt the boot
22206 process. The boot blocks will then prompt you for further action. You
22207 should now see something like:
22209 >> DragonFly/i386 BOOT
22210 Default: 0:ad(0,a)/boot/loader
22213 Verify the above message appears on either the serial or internal
22214 console or both, according to the options you put in /boot.config. If
22215 the message appears in the correct console, hit Enter to continue the
22218 If you want the serial console but you do not see the prompt on the
22219 serial terminal, something is wrong with your settings. In the
22220 meantime, you enter -h and hit Enter/Return (if possible) to tell the
22221 boot block (and then the boot loader and the kernel) to choose the
22222 serial port for the console. Once the system is up, go back and check
22225 After the boot loader is loaded and you are in the third stage of the boot
22226 process you can still switch between the internal console and the serial
22227 console by setting appropriate environment variables in the boot loader.
22228 See Section 17.6.6.
22230 ----------------------------------------------------------------------
22234 Here is the summary of various settings discussed in this section and the
22235 console eventually selected.
22237 ----------------------------------------------------------------------
22239 17.6.4.1 Case 1: You Set the Flags to 0x10 for sio0
22241 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
22243 Options in Console during Console during Console in
22244 /boot.config boot blocks boot loader kernel
22245 nothing internal internal internal
22246 -h serial serial serial
22247 -D serial and internal internal
22249 -Dh serial and serial serial
22251 -P, keyboard present internal internal internal
22252 -P, keyboard absent serial and serial serial
22255 ----------------------------------------------------------------------
22257 17.6.4.2 Case 2: You Set the Flags to 0x30 for sio0
22259 device sio0 at isa? port IO_COM1 flags 0x30 irq 4
22261 Options in Console during Console during Console in
22262 /boot.config boot blocks boot loader kernel
22263 nothing internal internal serial
22264 -h serial serial serial
22265 -D serial and internal serial
22267 -Dh serial and serial serial
22269 -P, keyboard present internal internal serial
22270 -P, keyboard absent serial and serial serial
22273 ----------------------------------------------------------------------
22275 17.6.5 Tips for the Serial Console
22277 17.6.5.1 Setting a Faster Serial Port Speed
22279 By default, the serial port settings are: 9600 baud, 8 bits, no parity,
22280 and 1 stop bit. If you wish to change the speed, you need to recompile at
22281 least the boot blocks. Add the following line to /etc/make.conf and
22282 compile new boot blocks:
22284 BOOT_COMCONSOLE_SPEED=19200
22286 If the serial console is configured in some other way than by booting with
22287 -h, or if the serial console used by the kernel is different from the one
22288 used by the boot blocks, then you must also add the following option to
22289 the kernel configuration file and compile a new kernel:
22291 options CONSPEED=19200
22293 ----------------------------------------------------------------------
22295 17.6.5.2 Using Serial Port Other Than sio0 for the Console
22297 Using a port other than sio0 as the console requires some recompiling. If
22298 you want to use another serial port for whatever reasons, recompile the
22299 boot blocks, the boot loader and the kernel as follows.
22301 1. Get the kernel source. (See Section 21.1)
22303 2. Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the
22304 port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only sio0 through
22305 sio3 (COM1 through COM4) can be used; multiport serial cards will not
22306 work. No interrupt setting is needed.
22308 3. Create a custom kernel configuration file and add appropriate flags
22309 for the serial port you want to use. For example, if you want to make
22310 sio1 (COM2) the console:
22312 device sio1 at isa? port IO_COM2 flags 0x10 irq 3
22316 device sio1 at isa? port IO_COM2 flags 0x30 irq 3
22318 The console flags for the other serial ports should not be set.
22320 4. Recompile and install the boot blocks and the boot loader:
22326 5. Rebuild and install the kernel.
22328 6. Write the boot blocks to the boot disk with disklabel(8) and boot from
22331 ----------------------------------------------------------------------
22333 17.6.5.3 Entering the DDB Debugger from the Serial Line
22335 If you wish to drop into the kernel debugger from the serial console
22336 (useful for remote diagnostics, but also dangerous if you generate a
22337 spurious BREAK on the serial port!) then you should compile your kernel
22338 with the following options:
22340 options BREAK_TO_DEBUGGER
22343 ----------------------------------------------------------------------
22345 17.6.5.4 Getting a Login Prompt on the Serial Console
22347 While this is not required, you may wish to get a login prompt over the
22348 serial line, now that you can see boot messages and can enter the kernel
22349 debugging session through the serial console. Here is how to do it.
22351 Open the file /etc/ttys with an editor and locate the lines:
22353 ttyd0 "/usr/libexec/getty std.9600" unknown off secure
22354 ttyd1 "/usr/libexec/getty std.9600" unknown off secure
22355 ttyd2 "/usr/libexec/getty std.9600" unknown off secure
22356 ttyd3 "/usr/libexec/getty std.9600" unknown off secure
22358 ttyd0 through ttyd3 corresponds to COM1 through COM4. Change off to on for
22359 the desired port. If you have changed the speed of the serial port, you
22360 need to change std.9600 to match the current setting, e.g. std.19200.
22362 You may also want to change the terminal type from unknown to the actual
22363 type of your serial terminal.
22365 After editing the file, you must kill -HUP 1 to make this change take
22368 ----------------------------------------------------------------------
22370 17.6.6 Changing Console from the Boot Loader
22372 Previous sections described how to set up the serial console by tweaking
22373 the boot block. This section shows that you can specify the console by
22374 entering some commands and environment variables in the boot loader. As
22375 the boot loader is invoked at the third stage of the boot process, after
22376 the boot block, the settings in the boot loader will override the settings
22379 ----------------------------------------------------------------------
22381 17.6.6.1 Setting Up the Serial Console
22383 You can easily specify the boot loader and the kernel to use the serial
22384 console by writing just one line in /boot/loader.rc:
22386 set console=comconsole
22388 This will take effect regardless of the settings in the boot block
22389 discussed in the previous section.
22391 You had better put the above line as the first line of /boot/loader.rc so
22392 as to see boot messages on the serial console as early as possible.
22394 Likewise, you can specify the internal console as:
22396 set console=vidconsole
22398 If you do not set the boot loader environment variable console, the boot
22399 loader, and subsequently the kernel, will use whichever console indicated
22400 by the -h option in the boot block.
22402 In versions 3.2 or later, you may specify the console in
22403 /boot/loader.conf.local or /boot/loader.conf, rather than in
22404 /boot/loader.rc. In this method your /boot/loader.rc should look like:
22406 include /boot/loader.4th
22409 Then, create /boot/loader.conf.local and put the following line there.
22417 See loader.conf(5) for more information.
22419 Note: At the moment, the boot loader has no option equivalent to the -P
22420 option in the boot block, and there is no provision to automatically
22421 select the internal console and the serial console based on the presence
22424 ----------------------------------------------------------------------
22426 17.6.6.2 Using a Serial Port Other Than sio0 for the Console
22428 You need to recompile the boot loader to use a serial port other than sio0
22429 for the serial console. Follow the procedure described in Section
22432 ----------------------------------------------------------------------
22436 The idea here is to allow people to set up dedicated servers that require
22437 no graphics hardware or attached keyboards. Unfortunately, while most
22438 systems will let you boot without a keyboard, there are quite a few that
22439 will not let you boot without a graphics adapter. Machines with AMI BIOSes
22440 can be configured to boot with no graphics adapter installed simply by
22441 changing the ``graphics adapter'' setting in the CMOS configuration to
22444 However, many machines do not support this option and will refuse to boot
22445 if you have no display hardware in the system. With these machines, you
22446 will have to leave some kind of graphics card plugged in, (even if it is
22447 just a junky mono board) although you will not have to attach a monitor.
22448 You might also try installing an AMI BIOS.
22450 ----------------------------------------------------------------------
22452 Chapter 18 PPP and SLIP
22454 Restructured, reorganized, and updated by Jim Mock.
22458 DragonFly has a number of ways to link one computer to another. To
22459 establish a network or Internet connection through a dial-up modem, or to
22460 allow others to do so through you, requires the use of PPP or SLIP. This
22461 chapter describes setting up these modem-based communication services in
22464 After reading this chapter, you will know:
22466 * How to set up user PPP.
22468 * How to set up kernel PPP.
22470 * How to set up PPPoE (PPP over Ethernet).
22472 * How to set up PPPoA (PPP over ATM).
22474 * How to configure and set up a SLIP client and server.
22476 Before reading this chapter, you should:
22478 * Be familiar with basic network terminology.
22480 * Understand the basics and purpose of a dialup connection and PPP
22483 You may be wondering what the main difference is between user PPP and
22484 kernel PPP. The answer is simple: user PPP processes the inbound and
22485 outbound data in userland rather than in the kernel. This is expensive in
22486 terms of copying the data between the kernel and userland, but allows a
22487 far more feature-rich PPP implementation. User PPP uses the tun device to
22488 communicate with the outside world whereas kernel PPP uses the ppp device.
22490 Note: Throughout in this chapter, user PPP will simply be referred to as
22491 ppp unless a distinction needs to be made between it and any other PPP
22492 software such as pppd. Unless otherwise stated, all of the commands
22493 explained in this chapter should be executed as root.
22495 ----------------------------------------------------------------------
22497 18.2 Using User PPP
22499 Updated and enhanced by Tom Rhodes. Originally contributed by Brian
22500 Somers. With input from Nik Clayton, Dirk Fro:mberg, and Peter Childs.
22504 18.2.1.1 Assumptions
22506 This document assumes you have the following:
22508 * An account with an Internet Service Provider (ISP) which you connect
22511 * You have a modem or other device connected to your system and
22512 configured correctly which allows you to connect to your ISP.
22514 * The dial-up number(s) of your ISP.
22516 * Your login name and password. (Either a regular UNIX style login and
22517 password pair, or a PAP or CHAP login and password pair.)
22519 * The IP address of one or more name servers. Normally, you will be
22520 given two IP addresses by your ISP to use for this. If they have not
22521 given you at least one, then you can use the enable dns command in
22522 ppp.conf and ppp will set the name servers for you. This feature
22523 depends on your ISPs PPP implementation supporting DNS negotiation.
22525 The following information may be supplied by your ISP, but is not
22526 completely necessary:
22528 * The IP address of your ISP's gateway. The gateway is the machine to
22529 which you will connect and will be set up as your default route. If
22530 you do not have this information, we can make one up and your ISP's
22531 PPP server will tell us the correct value when we connect.
22533 This IP number is referred to as HISADDR by ppp.
22535 * The netmask you should use. If your ISP has not provided you with one,
22536 you can safely use 255.255.255.255.
22538 * If your ISP provides you with a static IP address and hostname, you
22539 can enter it. Otherwise, we simply let the peer assign whatever IP
22540 address it sees fit.
22542 If you do not have any of the required information, contact your ISP.
22544 Note: Throughout this section, many of the examples showing the contents
22545 of configuration files are numbered by line. These numbers serve to aid
22546 in the presentation and discussion only and are not meant to be placed
22547 in the actual file. Proper indentation with tab and space characters is
22550 ----------------------------------------------------------------------
22552 18.2.1.2 Creating PPP Device Nodes
22554 Under normal circumstances, most users will only need one tun device
22555 (/dev/tun0). References to tun0 below may be changed to tunN where N is
22556 any unit number corresponding to your system.
22558 The easiest way to make sure that the tun0 device is configured correctly
22559 is to remake the device. To remake the device, do the following:
22564 If you need 16 tunnel devices in your kernel, you will need to create
22565 them. This can be done by executing the following commands:
22570 ----------------------------------------------------------------------
22572 18.2.1.3 Automatic PPP Configuration
22574 Both ppp and pppd (the kernel level implementation of PPP) use the
22575 configuration files located in the /etc/ppp directory. Examples for user
22576 ppp can be found in /usr/share/examples/ppp/.
22578 Configuring ppp requires that you edit a number of files, depending on
22579 your requirements. What you put in them depends to some extent on whether
22580 your ISP allocates IP addresses statically (i.e., you get given one IP
22581 address, and always use that one) or dynamically (i.e., your IP address
22582 changes each time you connect to your ISP).
22584 ----------------------------------------------------------------------
22586 18.2.1.3.1 PPP and Static IP Addresses
22588 You will need to edit the /etc/ppp/ppp.conf configuration file. It should
22589 look similar to the example below.
22591 Note: Lines that end in a : start in the first column (beginning of the
22592 line)-- all other lines should be indented as shown using spaces or
22596 2 set log Phase Chat LCP IPCP CCP tun command
22597 3 ident user-ppp VERSION (built COMPILATIONDATE)
22598 4 set device /dev/cuaa0
22600 6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
22601 7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
22606 12 set phone "(123) 456 7890"
22607 13 set authname foo
22609 15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
22611 17 set ifaddr x.x.x.x y.y.y.y 255.255.255.255 0.0.0.0
22612 18 add default HISADDR
22616 Identifies the default entry. Commands in this entry are executed
22617 automatically when ppp is run.
22621 Enables logging parameters. When the configuration is working
22622 satisfactorily, this line should be reduced to saying
22626 in order to avoid excessive log file sizes.
22630 Tells PPP how to identify itself to the peer. PPP identifies
22631 itself to the peer if it has any trouble negotiating and setting
22632 up the link, providing information that the peers administrator
22633 may find useful when investigating such problems.
22637 Identifies the device to which the modem is connected. COM1 is
22638 /dev/cuaa0 and COM2 is /dev/cuaa1.
22642 Sets the speed you want to connect at. If 115200 does not work (it
22643 should with any reasonably new modem), try 38400 instead.
22647 The dial string. User PPP uses an expect-send syntax similar to
22648 the chat(8) program. Refer to the manual page for information on
22649 the features of this language.
22651 Note that this command continues onto the next line for
22652 readability. Any command in ppp.conf may do this if the last
22653 character on the line is a ``\'' character.
22657 Sets the idle timeout for the link. 180 seconds is the default, so
22658 this line is purely cosmetic.
22662 Tells PPP to ask the peer to confirm the local resolver settings.
22663 If you run a local name server, this line should be commented out
22668 A blank line for readability. Blank lines are ignored by PPP.
22672 Identifies an entry for a provider called ``provider''. This could
22673 be changed to the name of your ISP so that later you can use the
22674 load ISP to start the connection.
22678 Sets the phone number for this provider. Multiple phone numbers
22679 may be specified using the colon (:) or pipe character (|)as a
22680 separator. The difference between the two separators is described
22681 in ppp(8). To summarize, if you want to rotate through the
22682 numbers, use a colon. If you want to always attempt to dial the
22683 first number first and only use the other numbers if the first
22684 number fails, use the pipe character. Always quote the entire set
22685 of phone numbers as shown.
22687 You must enclose the phone number in quotation marks (") if there
22688 is any intention on using spaces in the phone number. This can
22689 cause a simple, yet subtle error.
22693 Identifies the user name and password. When connecting using a
22694 UNIX style login prompt, these values are referred to by the set
22695 login command using the \U and \P variables. When connecting using
22696 PAP or CHAP, these values are used at authentication time.
22700 If you are using PAP or CHAP, there will be no login at this
22701 point, and this line should be commented out or removed. See PAP
22702 and CHAP authentication for further details.
22704 The login string is of the same chat-like syntax as the dial
22705 string. In this example, the string works for a service whose
22706 login session looks like this:
22713 You will need to alter this script to suit your own needs. When
22714 you write this script for the first time, you should ensure that
22715 you have enabled ``chat'' logging so you can determine if the
22716 conversation is going as expected.
22720 Sets the default idle timeout (in seconds) for the connection.
22721 Here, the connection will be closed automatically after 300
22722 seconds of inactivity. If you never want to timeout, set this
22723 value to zero or use the -ddial command line switch.
22727 Sets the interface addresses. The string x.x.x.x should be
22728 replaced by the IP address that your provider has allocated to
22729 you. The string y.y.y.y should be replaced by the IP address that
22730 your ISP indicated for their gateway (the machine to which you
22731 connect). If your ISP has not given you a gateway address, use
22732 10.0.0.2/0. If you need to use a ``guessed'' address, make sure
22733 that you create an entry in /etc/ppp/ppp.linkup as per the
22734 instructions for PPP and Dynamic IP addresses. If this line is
22735 omitted, ppp cannot run in -auto mode.
22739 Adds a default route to your ISP's gateway. The special word
22740 HISADDR is replaced with the gateway address specified on line 17.
22741 It is important that this line appears after line 17, otherwise
22742 HISADDR will not yet be initialized.
22744 If you do not wish to run ppp in -auto, this line should be moved
22745 to the ppp.linkup file.
22747 It is not necessary to add an entry to ppp.linkup when you have a static
22748 IP address and are running ppp in -auto mode as your routing table entries
22749 are already correct before you connect. You may however wish to create an
22750 entry to invoke programs after connection. This is explained later with
22751 the sendmail example.
22753 Example configuration files can be found in the /usr/share/examples/ppp/
22756 ----------------------------------------------------------------------
22758 18.2.1.3.2 PPP and Dynamic IP Addresses
22760 If your service provider does not assign static IP addresses, ppp can be
22761 configured to negotiate the local and remote addresses. This is done by
22762 ``guessing'' an IP address and allowing ppp to set it up correctly using
22763 the IP Configuration Protocol (IPCP) after connecting. The ppp.conf
22764 configuration is the same as PPP and Static IP Addresses, with the
22767 17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255
22769 Again, do not include the line number, it is just for reference.
22770 Indentation of at least one space is required.
22774 The number after the / character is the number of bits of the
22775 address that ppp will insist on. You may wish to use IP numbers
22776 more appropriate to your circumstances, but the above example will
22779 The last argument (0.0.0.0) tells PPP to start negotiations using
22780 address 0.0.0.0 rather than 10.0.0.1 and is necessary for some
22781 ISPs. Do not use 0.0.0.0 as the first argument to set ifaddr as it
22782 prevents PPP from setting up an initial route in -auto mode.
22784 If you are not running in -auto mode, you will need to create an entry in
22785 /etc/ppp/ppp.linkup. ppp.linkup is used after a connection has been
22786 established. At this point, ppp will have assigned the interface addresses
22787 and it will now be possible to add the routing table entries:
22790 2 add default HISADDR
22794 On establishing a connection, ppp will look for an entry in
22795 ppp.linkup according to the following rules: First, try to match
22796 the same label as we used in ppp.conf. If that fails, look for an
22797 entry for the IP address of our gateway. This entry is a
22798 four-octet IP style label. If we still have not found an entry,
22799 look for the MYADDR entry.
22803 This line tells ppp to add a default route that points to HISADDR.
22804 HISADDR will be replaced with the IP number of the gateway as
22805 negotiated by the IPCP.
22807 See the pmdemand entry in the files
22808 /usr/share/examples/ppp/ppp.conf.sample and
22809 /usr/share/examples/ppp/ppp.linkup.sample for a detailed example.
22811 ----------------------------------------------------------------------
22813 18.2.1.3.3 Receiving Incoming Calls
22815 When you configure ppp to receive incoming calls on a machine connected to
22816 a LAN, you must decide if you wish to forward packets to the LAN. If you
22817 do, you should allocate the peer an IP number from your LAN's subnet, and
22818 use the command enable proxy in your /etc/ppp/ppp.conf file. You should
22819 also confirm that the /etc/rc.conf file contains the following:
22821 gateway_enable="YES"
22823 ----------------------------------------------------------------------
22825 18.2.1.3.4 Which getty?
22827 Configuring DragonFly for Dial-up Services provides a good description on
22828 enabling dial-up services using getty(8).
22830 An alternative to getty is mgetty, a smarter version of getty designed
22831 with dial-up lines in mind.
22833 The advantages of using mgetty is that it actively talks to modems,
22834 meaning if port is turned off in /etc/ttys then your modem will not answer
22837 Later versions of mgetty (from 0.99beta onwards) also support the
22838 automatic detection of PPP streams, allowing your clients script-less
22839 access to your server.
22841 Refer to Mgetty and AutoPPP for more information on mgetty.
22843 ----------------------------------------------------------------------
22845 18.2.1.3.5 PPP Permissions
22847 The ppp command must normally be run as the root user. If however, you
22848 wish to allow ppp to run in server mode as a normal user by executing ppp
22849 as described below, that user must be given permission to run ppp by
22850 adding them to the network group in /etc/group.
22852 You will also need to give them access to one or more sections of the
22853 configuration file using the allow command:
22855 allow users fred mary
22857 If this command is used in the default section, it gives the specified
22858 users access to everything.
22860 ----------------------------------------------------------------------
22862 18.2.1.3.6 PPP Shells for Dynamic-IP Users
22864 Create a file called /etc/ppp/ppp-shell containing the following:
22867 IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
22871 if [ x$IDENT = xdialup ]; then
22872 IDENT=`basename $TTY`
22875 echo "PPP for $CALLEDAS on $TTY"
22876 echo "Starting PPP for $IDENT"
22878 exec /usr/sbin/ppp -direct $IDENT
22880 This script should be executable. Now make a symbolic link called
22881 ppp-dialup to this script using the following commands:
22883 # ln -s ppp-shell /etc/ppp/ppp-dialup
22885 You should use this script as the shell for all of your dialup users. This
22886 is an example from /etc/password for a dialup PPP user with username
22887 pchilds (remember do not directly edit the password file, use vipw).
22889 pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup
22891 Create a /home/ppp directory that is world readable containing the
22892 following 0 byte files:
22894 -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
22895 -r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts
22897 which prevents /etc/motd from being displayed.
22899 ----------------------------------------------------------------------
22901 18.2.1.3.7 PPP Shells for Static-IP Users
22903 Create the ppp-shell file as above, and for each account with statically
22904 assigned IPs create a symbolic link to ppp-shell.
22906 For example, if you have three dialup customers, fred, sam, and mary, that
22907 you route class C networks for, you would type the following:
22909 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
22910 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
22911 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary
22913 Each of these users dialup accounts should have their shell set to the
22914 symbolic link created above (for example, mary's shell should be
22915 /etc/ppp/ppp-mary).
22917 ----------------------------------------------------------------------
22919 18.2.1.3.8 Setting Up ppp.conf for Dynamic-IP Users
22921 The /etc/ppp/ppp.conf file should contain something along the lines of:
22924 set debug phase lcp chat
22928 set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
22932 set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
22935 Note: The indenting is important.
22937 The default: section is loaded for each session. For each dialup line
22938 enabled in /etc/ttys create an entry similar to the one for ttyd0: above.
22939 Each line should get a unique IP address from your pool of IP addresses
22942 ----------------------------------------------------------------------
22944 18.2.1.3.9 Setting Up ppp.conf for Static-IP Users
22946 Along with the contents of the sample /usr/share/examples/ppp/ppp.conf
22947 above you should add a section for each of the statically assigned dialup
22948 users. We will continue with our fred, sam, and mary example.
22951 set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
22954 set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
22957 set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255
22959 The file /etc/ppp/ppp.linkup should also contain routing information for
22960 each static IP user if required. The line below would add a route for the
22961 203.14.101.0 class C via the client's ppp link.
22964 add 203.14.101.0 netmask 255.255.255.0 HISADDR
22967 add 203.14.102.0 netmask 255.255.255.0 HISADDR
22970 add 203.14.103.0 netmask 255.255.255.0 HISADDR
22972 ----------------------------------------------------------------------
22974 18.2.1.3.10 mgetty and AutoPPP
22976 Configuring and compiling mgetty with the AUTO_PPP option enabled allows
22977 mgetty to detect the LCP phase of PPP connections and automatically spawn
22978 off a ppp shell. However, since the default login/password sequence does
22979 not occur it is necessary to authenticate users using either PAP or CHAP.
22981 This section assumes the user has successfully configured, compiled, and
22982 installed a version of mgetty with the AUTO_PPP option (v0.99beta or
22985 Make sure your /usr/local/etc/mgetty+sendfax/login.config file has the
22988 /AutoPPP/ - - /etc/ppp/ppp-pap-dialup
22990 This will tell mgetty to run the ppp-pap-dialup script for detected PPP
22993 Create a file called /etc/ppp/ppp-pap-dialup containing the following (the
22994 file should be executable):
22997 exec /usr/sbin/ppp -direct pap$IDENT
22999 For each dialup line enabled in /etc/ttys, create a corresponding entry in
23000 /etc/ppp/ppp.conf. This will happily co-exist with the definitions we
23005 set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
23008 Each user logging in with this method will need to have a
23009 username/password in /etc/ppp/ppp.secret file, or alternatively add the
23010 following option to authenticate users via PAP from /etc/password file.
23014 If you wish to assign some users a static IP number, you can specify the
23015 number as the third argument in /etc/ppp/ppp.secret. See
23016 /usr/share/examples/ppp/ppp.secret.sample for examples.
23018 ----------------------------------------------------------------------
23020 18.2.1.3.11 MS Extensions
23022 It is possible to configure PPP to supply DNS and NetBIOS nameserver
23023 addresses on demand.
23025 To enable these extensions with PPP version 1.x, the following lines might
23026 be added to the relevant section of /etc/ppp/ppp.conf.
23029 set ns 203.14.100.1 203.14.100.2
23030 set nbns 203.14.100.5
23032 And for PPP version 2 and above:
23035 set dns 203.14.100.1 203.14.100.2
23036 set nbns 203.14.100.5
23038 This will tell the clients the primary and secondary name server
23039 addresses, and a NetBIOS nameserver host.
23041 In version 2 and above, if the set dns line is omitted, PPP will use the
23042 values found in /etc/resolv.conf.
23044 ----------------------------------------------------------------------
23046 18.2.1.3.12 PAP and CHAP Authentication
23048 Some ISPs set their system up so that the authentication part of your
23049 connection is done using either of the PAP or CHAP authentication
23050 mechanisms. If this is the case, your ISP will not give a login: prompt
23051 when you connect, but will start talking PPP immediately.
23053 PAP is less secure than CHAP, but security is not normally an issue here
23054 as passwords, although being sent as plain text with PAP, are being
23055 transmitted down a serial line only. There is not much room for crackers
23058 Referring back to the PPP and Static IP addresses or PPP and Dynamic IP
23059 addresses sections, the following alterations must be made:
23061 13 set authname MyUserName
23062 14 set authkey MyPassword
23067 This line specifies your PAP/CHAP user name. You will need to
23068 insert the correct value for MyUserName.
23072 This line specifies your PAP/CHAP password. You will need to
23073 insert the correct value for MyPassword. You may want to add an
23074 additional line, such as:
23082 to make it obvious that this is the intention, but PAP and CHAP
23083 are both accepted by default.
23087 Your ISP will not normally require that you log into the server if
23088 you are using PAP or CHAP. You must therefore disable your ``set
23091 ----------------------------------------------------------------------
23093 18.2.1.3.13 Changing Your ppp Configuration on the Fly
23095 It is possible to talk to the ppp program while it is running in the
23096 background, but only if a suitable diagnostic port has been set up. To do
23097 this, add the following line to your configuration:
23099 set server /var/run/ppp-tun%d DiagnosticPassword 0177
23101 This will tell PPP to listen to the specified UNIX domain socket, asking
23102 clients for the specified password before allowing access. The %d in the
23103 name is replaced with the tun device number that is in use.
23105 Once a socket has been set up, the pppctl(8) program may be used in
23106 scripts that wish to manipulate the running program.
23108 ----------------------------------------------------------------------
23110 18.2.1.4 Using PPP Network Address Translation Capability
23112 PPP has ability to use internal NAT without kernel diverting capabilities.
23113 This functionality may be enabled by the following line in
23118 Alternatively, PPP NAT may be enabled by command-line option -nat. There
23119 is also /etc/rc.conf knob named ppp_nat, which is enabled by default.
23121 If you use this feature, you may also find useful the following
23122 /etc/ppp/ppp.conf options to enable incoming connections forwarding:
23124 nat port tcp 10.0.0.2:ftp ftp
23125 nat port tcp 10.0.0.2:http http
23127 or do not trust the outside at all
23129 nat deny_incoming yes
23131 ----------------------------------------------------------------------
23133 18.2.1.5 Final System Configuration
23135 You now have ppp configured, but there are a few more things to do before
23136 it is ready to work. They all involve editing the /etc/rc.conf file.
23138 Working from the top down in this file, make sure the hostname= line is
23141 hostname="foo.example.com"
23143 If your ISP has supplied you with a static IP address and name, it is
23144 probably best that you use this name as your host name.
23146 Look for the network_interfaces variable. If you want to configure your
23147 system to dial your ISP on demand, make sure the tun0 device is added to
23148 the list, otherwise remove it.
23150 network_interfaces="lo0 tun0"
23153 Note: The ifconfig_tun0 variable should be empty, and a file called
23154 /etc/start_if.tun0 should be created. This file should contain the line:
23158 This script is executed at network configuration time, starting your ppp
23159 daemon in automatic mode. If you have a LAN for which this machine is a
23160 gateway, you may also wish to use the -alias switch. Refer to the manual
23161 page for further details.
23163 Make sure the router program set to NO with following line in your
23168 It is important that the routed daemon is not started (it is by default),
23169 as routed tends to delete the default routing table entries created by
23172 It is probably worth your while ensuring that the sendmail_flags line does
23173 not include the -q option, otherwise sendmail will attempt to do a network
23174 lookup every now and then, possibly causing your machine to dial out. You
23177 sendmail_flags="-bd"
23179 The downside of this is that you must force sendmail to re-examine the
23180 mail queue whenever the ppp link is up by typing:
23182 # /usr/sbin/sendmail -q
23184 You may wish to use the !bg command in ppp.linkup to do this
23190 4 !bg sendmail -bd -q30m
23192 If you do not like this, it is possible to set up a ``dfilter'' to block
23193 SMTP traffic. Refer to the sample files for further details.
23195 All that is left is to reboot the machine. After rebooting, you can now
23200 and then dial provider to start the PPP session, or, if you want ppp to
23201 establish sessions automatically when there is outbound traffic (and you
23202 have not created the start_if.tun0 script), type:
23204 # ppp -auto provider
23206 ----------------------------------------------------------------------
23210 To recap, the following steps are necessary when setting up ppp for the
23215 1. Ensure that the tun device is built into your kernel.
23217 2. Ensure that the tunN device file is available in the /dev directory.
23219 3. Create an entry in /etc/ppp/ppp.conf. The pmdemand example should
23220 suffice for most ISPs.
23222 4. If you have a dynamic IP address, create an entry in
23223 /etc/ppp/ppp.linkup.
23225 5. Update your /etc/rc.conf file.
23227 6. Create a start_if.tun0 script if you require demand dialing.
23231 1. Ensure that the tun device is built into your kernel.
23233 2. Ensure that the tunN device file is available in the /dev directory.
23235 3. Create an entry in /etc/passwd (using the vipw(8) program).
23237 4. Create a profile in this users home directory that runs ppp -direct
23238 direct-server or similar.
23240 5. Create an entry in /etc/ppp/ppp.conf. The direct-server example should
23243 6. Create an entry in /etc/ppp/ppp.linkup.
23245 7. Update your /etc/rc.conf file.
23247 ----------------------------------------------------------------------
23249 18.3 Using Kernel PPP
23251 Parts originally contributed by Gennady B. Sorokopud and Robert Huff.
23253 18.3.1 Setting Up Kernel PPP
23255 Before you start setting up PPP on your machine, make sure that pppd is
23256 located in /usr/sbin and the directory /etc/ppp exists.
23258 pppd can work in two modes:
23260 1. As a ``client'' -- you want to connect your machine to the outside
23261 world via a PPP serial connection or modem line.
23263 2. As a ``server'' -- your machine is located on the network, and is used
23264 to connect other computers using PPP.
23266 In both cases you will need to set up an options file (/etc/ppp/options or
23267 ~/.ppprc if you have more than one user on your machine that uses PPP).
23269 You will also need some modem/serial software (preferably comms/kermit),
23270 so you can dial and establish a connection with the remote host.
23272 ----------------------------------------------------------------------
23274 18.3.2 Using pppd as a Client
23276 Based on information provided by Trev Roydhouse.
23278 The following /etc/ppp/options might be used to connect to a Cisco
23279 terminal server PPP line.
23281 crtscts # enable hardware flow control
23282 modem # modem control line
23283 noipdefault # remote PPP server must supply your IP address
23284 # if the remote host does not send your IP during IPCP
23285 # negotiation, remove this option
23286 passive # wait for LCP packets
23287 domain ppp.foo.com # put your domain name here
23289 :<remote_ip> # put the IP of remote PPP host here
23290 # it will be used to route packets via PPP link
23291 # if you didn't specified the noipdefault option
23292 # change this line to <local_ip>:<remote_ip>
23294 defaultroute # put this if you want that PPP server will be your
23299 1. Dial to the remote host using kermit (or some other modem program),
23300 and enter your user name and password (or whatever is needed to enable
23301 PPP on the remote host).
23303 2. Exit kermit (without hanging up the line).
23305 3. Enter the following:
23307 # /usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200
23309 Be sure to use the appropriate speed and device name.
23311 Now your computer is connected with PPP. If the connection fails, you can
23312 add the debug option to the /etc/ppp/options file, and check console
23313 messages to track the problem.
23315 Following /etc/ppp/pppup script will make all 3 stages automatic:
23318 ps ax |grep pppd |grep -v grep
23319 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23320 if [ "X${pid}" != "X" ] ; then
23321 echo 'killing pppd, PID=' ${pid}
23324 ps ax |grep kermit |grep -v grep
23325 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23326 if [ "X${pid}" != "X" ] ; then
23327 echo 'killing kermit, PID=' ${pid}
23332 ifconfig ppp0 delete
23334 kermit -y /etc/ppp/kermit.dial
23335 pppd /dev/tty01 19200
23337 /etc/ppp/kermit.dial is a kermit script that dials and makes all necessary
23338 authorization on the remote host (an example of such a script is attached
23339 to the end of this document).
23341 Use the following /etc/ppp/pppdown script to disconnect the PPP line:
23344 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23345 if [ X${pid} != "X" ] ; then
23346 echo 'killing pppd, PID=' ${pid}
23350 ps ax |grep kermit |grep -v grep
23351 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23352 if [ "X${pid}" != "X" ] ; then
23353 echo 'killing kermit, PID=' ${pid}
23357 /sbin/ifconfig ppp0 down
23358 /sbin/ifconfig ppp0 delete
23359 kermit -y /etc/ppp/kermit.hup
23362 Check to see if pppd is still running by executing /usr/etc/ppp/ppptest,
23363 which should look like this:
23366 pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
23367 if [ X${pid} != "X" ] ; then
23368 echo 'pppd running: PID=' ${pid-NONE}
23370 echo 'No pppd running.'
23376 To hang up the modem, execute /etc/ppp/kermit.hup, which should contain:
23378 set line /dev/tty01 ; put your modem device here
23380 set file type binary
23381 set file names literal
23386 set term bytesize 8
23387 set command bytesize 8
23397 Here is an alternate method using chat instead of kermit:
23399 The following two files are sufficient to accomplish a pppd connection.
23405 crtscts # enable hardware flow control
23406 modem # modem control line
23407 connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
23408 noipdefault # remote PPP serve must supply your IP address
23409 # if the remote host doesn't send your IP during
23410 # IPCP negotiation, remove this option
23411 passive # wait for LCP packets
23412 domain <your.domain> # put your domain name here
23414 : # put the IP of remote PPP host here
23415 # it will be used to route packets via PPP link
23416 # if you didn't specified the noipdefault option
23417 # change this line to <local_ip>:<remote_ip>
23419 defaultroute # put this if you want that PPP server will be
23420 # your default router
23422 /etc/ppp/login.chat.script:
23424 Note: The following should go on a single line.
23426 ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number>
23427 CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id>
23428 TIMEOUT 5 sword: <password>
23430 Once these are installed and modified correctly, all you need to do is run
23435 ----------------------------------------------------------------------
23437 18.3.3 Using pppd as a Server
23439 /etc/ppp/options should contain something similar to the following:
23441 crtscts # Hardware flow control
23442 netmask 255.255.255.0 # netmask (not required)
23443 192.114.208.20:192.114.208.165 # IP's of local and remote hosts
23444 # local ip must be different from one
23445 # you assigned to the ethernet (or other)
23446 # interface on your machine.
23447 # remote IP is IP address that will be
23448 # assigned to the remote machine
23449 domain ppp.foo.com # your domain
23450 passive # wait for LCP
23453 The following /etc/ppp/pppserv script will tell pppd to behave as a
23457 ps ax |grep pppd |grep -v grep
23458 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23459 if [ "X${pid}" != "X" ] ; then
23460 echo 'killing pppd, PID=' ${pid}
23463 ps ax |grep kermit |grep -v grep
23464 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23465 if [ "X${pid}" != "X" ] ; then
23466 echo 'killing kermit, PID=' ${pid}
23470 # reset ppp interface
23472 ifconfig ppp0 delete
23474 # enable autoanswer mode
23475 kermit -y /etc/ppp/kermit.ans
23478 pppd /dev/tty01 19200
23480 Use this /etc/ppp/pppservdown script to stop the server:
23483 ps ax |grep pppd |grep -v grep
23484 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23485 if [ "X${pid}" != "X" ] ; then
23486 echo 'killing pppd, PID=' ${pid}
23489 ps ax |grep kermit |grep -v grep
23490 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23491 if [ "X${pid}" != "X" ] ; then
23492 echo 'killing kermit, PID=' ${pid}
23496 ifconfig ppp0 delete
23498 kermit -y /etc/ppp/kermit.noans
23500 The following kermit script (/etc/ppp/kermit.ans) will enable/disable
23501 autoanswer mode on your modem. It should look like this:
23503 set line /dev/tty01
23505 set file type binary
23506 set file names literal
23511 set term bytesize 8
23512 set command bytesize 8
23521 out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable
23527 A script named /etc/ppp/kermit.dial is used for dialing and authenticating
23528 on the remote host. You will need to customize it for your needs. Put your
23529 login and password in this script; you will also need to change the input
23530 statement depending on responses from your modem and remote host.
23533 ; put the com line attached to the modem here:
23535 set line /dev/tty01
23537 ; put the modem speed here:
23540 set file type binary ; full 8 bit file xfer
23541 set file names literal
23546 set term bytesize 8
23547 set command bytesize 8
23550 set dial hangup off
23551 set carrier auto ; Then SET CARRIER if necessary,
23552 set dial display on ; Then SET DIAL if necessary,
23554 set input timeout proceed
23555 set input case ignore
23556 def \%x 0 ; login prompt counter
23559 :slcmd ; put the modem in command mode
23560 echo Put the modem in command mode.
23561 clear ; Clear unread characters from input buffer
23563 output +++ ; hayes escape sequence
23564 input 1 OK\13\10 ; wait for OK
23565 if success goto slhup
23570 if fail goto slcmd ; if modem doesn't answer OK, try again
23572 :slhup ; hang up the phone
23573 clear ; Clear unread characters from input buffer
23575 echo Hanging up the phone.
23576 output ath0\13 ; hayes command for on hook
23578 if fail goto slcmd ; if no OK answer, put modem in command mode
23580 :sldial ; dial the number
23583 output atdt9,550311\13\10 ; put phone number here
23584 assign \%x 0 ; zero the time counter
23587 clear ; Clear unread characters from input buffer
23588 increment \%x ; Count the seconds
23590 if success goto sllogin
23591 reinput 1 {NO CARRIER\13\10}
23592 if success goto sldial
23593 reinput 1 {NO DIALTONE\13\10}
23594 if success goto slnodial
23596 if success goto slhup
23598 if success goto slhup
23599 if < \%x 60 goto look
23603 assign \%x 0 ; zero the time counter
23605 echo Looking for login prompt.
23608 increment \%x ; Count the seconds
23609 clear ; Clear unread characters from input buffer
23612 ; put your expected login prompt here:
23614 input 1 {Username: }
23615 if success goto sluid
23617 if success goto slhup
23619 if success goto slhup
23620 if < \%x 10 goto slloop ; try 10 times to get a login prompt
23621 else goto slhup ; hang up and start again if 10 failures
23625 ; put your userid here:
23627 output ppp-login\13
23628 input 1 {Password: }
23630 ; put your password here:
23632 output ppp-password\13
23633 input 1 {Entering SLIP mode.}
23638 echo \7No dialtone. Check the telephone line!\7
23643 ; comment-start: "; "
23644 ; comment-start-skip: "; "
23647 ----------------------------------------------------------------------
23649 18.4 Troubleshooting PPP Connections
23651 Contributed by Tom Rhodes.
23653 This section covers a few issues which may arise when using PPP over a
23654 modem connection. For instance, perhaps you need to know exactly what
23655 prompts the system you are dialing into will present. Some ISPs present
23656 the ssword prompt, and others will present password; if the ppp script is
23657 not written accordingly, the login attempt will fail. The most common way
23658 to debug ppp connections is by connecting manually. The following
23659 information will walk you through a manual connection step by step.
23661 ----------------------------------------------------------------------
23663 18.4.1 Check the Device Nodes
23665 If you reconfigured your kernel then you recall the sio device. If you did
23666 not configure your kernel, there is no reason to worry. Just check the
23667 dmesg output for the modem device with:
23671 You should get some pertinent output about the sio devices. These are the
23672 COM ports we need. If your modem acts like a standard serial port then you
23673 should see it listed on sio1, or COM2. If so, you are not required to
23674 rebuild the kernel, you just need to make the serial device. You can do
23675 this by changing your directory to /dev and running the MAKEDEV script
23676 like above. Now make the serial devices with:
23678 # sh MAKEDEV cuaa0 cuaa1 cuaa2 cuaa3
23680 which will create the serial devices for your system. When matching up sio
23681 modem is on sio1 or COM2 if you are in DOS, then your modem device would
23684 ----------------------------------------------------------------------
23686 18.4.2 Connecting Manually
23688 Connecting to the Internet by manually controlling ppp is quick, easy, and
23689 a great way to debug a connection or just get information on how your ISP
23690 treats ppp client connections. Lets start PPP from the command line. Note
23691 that in all of our examples we will use example as the hostname of the
23692 machine running PPP. You start ppp by just typing ppp:
23696 We have now started ppp.
23698 ppp ON example> set device /dev/cuaa1
23700 We set our modem device, in this case it is cuaa1.
23702 ppp ON example> set speed 115200
23704 Set the connection speed, in this case we are using 115,200 kbps.
23706 ppp ON example> enable dns
23708 Tell ppp to configure our resolver and add the nameserver lines to
23709 /etc/resolv.conf. If ppp cannot determine our hostname, we can set one
23712 ppp ON example> term
23714 Switch to ``terminal'' mode so that we can manually control the modem.
23716 deflink: Entering terminal mode on /dev/cuaa1
23723 Use at to initialize the modem, then use atdt and the number for your ISP
23724 to begin the dial in process.
23728 Confirmation of the connection, if we are going to have any connection
23729 problems, unrelated to hardware, here is where we will attempt to resolve
23732 ISP Login:myusername
23734 Here you are prompted for a username, return the prompt with the username
23735 that was provided by the ISP.
23737 ISP Pass:mypassword
23739 This time we are prompted for a password, just reply with the password
23740 that was provided by the ISP. Just like logging into DragonFly, the
23741 password will not echo.
23745 Depending on your ISP this prompt may never appear. Here we are being
23746 asked if we wish to use a shell on the provider, or to start ppp. In this
23747 example, we have chosen to use ppp as we want an Internet connection.
23751 Notice that in this example the first p has been capitalized. This shows
23752 that we have successfully connected to the ISP.
23756 We have successfully authenticated with our ISP and are waiting for the
23757 assigned IP address.
23761 We have made an agreement on an IP address and successfully completed our
23764 PPP ON example>add default HISADDR
23766 Here we add our default route, we need to do this before we can talk to
23767 the outside world as currently the only established connection is with the
23768 peer. If this fails due to existing routes you can put a bang character !
23769 in front of the add. Alternatively, you can set this before making the
23770 actual connection and it will negotiate a new route accordingly.
23772 If everything went good we should now have an active connection to the
23773 Internet, which could be thrown into the background using CTRL+z If you
23774 notice the PPP return to ppp then we have lost our connection. This is
23775 good to know because it shows our connection status. Capital P's show that
23776 we have a connection to the ISP and lowercase p's show that the connection
23777 has been lost for whatever reason. ppp only has these 2 states.
23779 ----------------------------------------------------------------------
23783 If you have a direct line and cannot seem to make a connection, then turn
23784 hardware flow CTS/RTS to off with the set ctsrts off. This is mainly the
23785 case if you are connected to some PPP capable terminal servers, where PPP
23786 hangs when it tries to write data to your communication link, so it would
23787 be waiting for a CTS, or Clear To Send signal which may never come. If you
23788 use this option however, you should also use the set accmap option, which
23789 may be required to defeat hardware dependent on passing certain characters
23790 from end to end, most of the time XON/XOFF. See the ppp(8) manual page for
23791 more information on this option, and how it is used.
23793 If you have an older modem, you may need to use the set parity even.
23794 Parity is set at none be default, but is used for error checking (with a
23795 large increase in traffic) on older modems and some ISPs. You may need
23796 this option for the Compuserve ISP.
23798 PPP may not return to the command mode, which is usually a negotiation
23799 error where the ISP is waiting for your side to start negotiating. At this
23800 point, using the ~p command will force ppp to start sending the
23801 configuration information.
23803 If you never obtain a login prompt, then most likely you need to use PAP
23804 or CHAP authentication instead of the UNIX style in the example above. To
23805 use PAP or CHAP just add the following options to PPP before going into
23808 ppp ON example> set authname myusername
23810 Where myusername should be replaced with the username that was assigned by
23813 ppp ON example> set authkey mypassword
23815 Where mypassword should be replaced with the password that was assigned by
23818 If you connect fine, but cannot seem to find any domain name, try to use
23819 ping(8) with an IP address and see if you can get any return information.
23820 If you experience 100 percent (100%) packet loss, then it is most likely
23821 that you were not assigned a default route. Double check that the option
23822 add default HISADDR was set during the connection. If you can connect to a
23823 remote IP address then it is possible that a resolver address has not been
23824 added to the /etc/resolv.conf. This file should look like:
23830 Where x.x.x.x and y.y.y.y should be replaced with the IP address of your
23831 ISP's DNS servers. This information may or may not have been provided when
23832 you signed up, but a quick call to your ISP should remedy that.
23834 You could also have syslog(3) provide a logging function for your PPP
23835 connection. Just add:
23838 *.* /var/log/ppp.log
23840 to /etc/syslog.conf. In most cases, this functionality already exists.
23842 ----------------------------------------------------------------------
23844 18.5 Using PPP over Ethernet (PPPoE)
23847 http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by Jim Mock.
23849 This section describes how to set up PPP over Ethernet (PPPoE).
23851 ----------------------------------------------------------------------
23853 18.5.1 Configuring the Kernel
23855 No kernel configuration is necessary for PPPoE any longer. If the
23856 necessary netgraph support is not built into the kernel, it will be
23857 dynamically loaded by ppp.
23859 ----------------------------------------------------------------------
23861 18.5.2 Setting Up ppp.conf
23863 Here is an example of a working ppp.conf:
23866 set log Phase tun command # you can add more detailed logging if you wish
23867 set ifaddr 10.0.0.1/0 10.0.0.2/0
23869 name_of_service_provider:
23870 set device PPPoE:xl1 # replace xl1 with your ethernet device
23871 set authname YOURLOGINNAME
23872 set authkey YOURPASSWORD
23875 add default HISADDR
23877 ----------------------------------------------------------------------
23881 As root, you can run:
23883 # ppp -ddial name_of_service_provider
23885 ----------------------------------------------------------------------
23887 18.5.4 Starting ppp at Boot
23889 Add the following to your /etc/rc.conf file:
23893 ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO
23894 ppp_profile="name_of_service_provider"
23896 ----------------------------------------------------------------------
23898 18.5.5 Using a PPPoE Service Tag
23900 Sometimes it will be necessary to use a service tag to establish your
23901 connection. Service tags are used to distinguish between different PPPoE
23902 servers attached to a given network.
23904 You should have been given any required service tag information in the
23905 documentation provided by your ISP. If you cannot locate it there, ask
23906 your ISP's tech support personnel.
23908 As a last resort, you could try the method suggested by the Roaring
23909 Penguin PPPoE program which can be found in the pkgsrc collection. Bear in
23910 mind however, this may de-program your modem and render it useless, so
23911 think twice before doing it. Simply install the program shipped with the
23912 modem by your provider. Then, access the System menu from the program. The
23913 name of your profile should be listed there. It is usually ISP.
23915 The profile name (service tag) will be used in the PPPoE configuration
23916 entry in ppp.conf as the provider part of the set device command (see the
23917 ppp(8) manual page for full details). It should look like this:
23919 set device PPPoE:xl1:ISP
23921 Do not forget to change xl1 to the proper device for your Ethernet card.
23923 Do not forget to change ISP to the profile you have just found above.
23925 For additional information, see:
23927 * Cheaper Broadband with FreeBSD on DSL by Renaud Waldura.
23929 * Nutzung von T-DSL und T-Online mit FreeBSD by Udo Erdelhoff (in
23932 ----------------------------------------------------------------------
23934 18.5.6 PPPoE with a 3Com(R) HomeConnect(R) ADSL Modem Dual Link
23936 This modem does not follow RFC 2516 (A Method for transmitting PPP over
23937 Ethernet (PPPoE), written by L. Mamakos, K. Lidl, J. Evarts, D. Carrel, D.
23938 Simone, and R. Wheeler). Instead, different packet type codes have been
23939 used for the Ethernet frames. Please complain to 3Com if you think it
23940 should comply with the PPPoE specification.
23942 In order to make DragonFly capable of communicating with this device, a
23943 sysctl must be set. This can be done automatically at boot time by
23944 updating /etc/sysctl.conf:
23946 net.graph.nonstandard_pppoe=1
23948 or can be done for immediate effect with the command sysctl
23949 net.graph.nonstandard_pppoe=1.
23951 Unfortunately, because this is a system-wide setting, it is not possible
23952 to talk to a normal PPPoE client or server and a 3Com(R) HomeConnect(R)
23953 ADSL Modem at the same time.
23955 ----------------------------------------------------------------------
23959 Originally contributed by Satoshi Asami. With input from Guy Helmer and
23962 ----------------------------------------------------------------------
23964 18.6.1 Setting Up a SLIP Client
23966 The following is one way to set up a DragonFly machine for SLIP on a
23967 static host network. For dynamic hostname assignments (your address
23968 changes each time you dial up), you probably need to have a more complex
23971 First, determine which serial port your modem is connected to. Many people
23972 set up a symbolic link, such as /dev/modem, to point to the real device
23973 name, /dev/cuaaN. This allows you to abstract the actual device name
23974 should you ever need to move the modem to a different port. It can become
23975 quite cumbersome when you need to fix a bunch of files in /etc and .kermrc
23976 files all over the system!
23978 Note: /dev/cuaa0 is COM1, cuaa1 is COM2, etc.
23980 Make sure you have the following in your kernel configuration file:
23984 It is included in the GENERIC kernel, so this should not be a problem
23985 unless you have deleted it.
23987 ----------------------------------------------------------------------
23989 18.6.1.1 Things You Have to Do Only Once
23991 1. Add your home machine, the gateway and nameservers to your /etc/hosts
23992 file. Mine looks like this:
23994 127.0.0.1 localhost loghost
23995 136.152.64.181 water.CS.Example.EDU water.CS water
23996 136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway
23997 128.32.136.9 ns1.Example.EDU ns1
23998 128.32.136.12 ns2.Example.EDU ns2
24000 2. Make sure you have hosts before bind in your /etc/host.conf.
24002 3. Edit the /etc/rc.conf file.
24004 1. Set your hostname by editing the line that says:
24006 hostname="myname.my.domain"
24008 Your machine's full Internet hostname should be placed here.
24010 2. Add sl0 to the list of network interfaces by changing the line
24013 network_interfaces="lo0"
24017 network_interfaces="lo0 sl0"
24019 3. Set the startup flags of sl0 by adding a line:
24021 ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"
24023 4. Designate the default router by changing the line:
24029 defaultrouter="slip-gateway"
24031 4. Make a file /etc/resolv.conf which contains:
24033 domain CS.Example.EDU
24034 nameserver 128.32.136.9
24035 nameserver 128.32.136.12
24037 As you can see, these set up the nameserver hosts. Of course, the
24038 actual domain names and addresses depend on your environment.
24040 5. Set the password for root and toor (and any other accounts that do not
24043 6. Reboot your machine and make sure it comes up with the correct
24046 ----------------------------------------------------------------------
24048 18.6.1.2 Making a SLIP Connection
24050 1. Dial up, type slip at the prompt, enter your machine name and
24051 password. What is required to be entered depends on your environment.
24052 If you use kermit, you can try a script like this:
24056 set line /dev/modem
24060 set terminal bytesize 8
24061 set file type binary
24062 # The next macro will dial up and login
24063 define slip dial 643-9600, input 10 =>, if failure stop, -
24064 output slip\x0d, input 10 Username:, if failure stop, -
24065 output silvia\x0d, input 10 Password:, if failure stop, -
24066 output ***\x0d, echo \x0aCONNECTED\x0a
24068 Of course, you have to change the hostname and password to fit yours.
24069 After doing so, you can just type slip from the kermit prompt to
24072 Note: Leaving your password in plain text anywhere in the filesystem
24073 is generally a bad idea. Do it at your own risk.
24075 2. Leave the kermit there (you can suspend it by Ctrl-z) and as root,
24078 # slattach -h -c -s 115200 /dev/modem
24080 If you are able to ping hosts on the other side of the router, you are
24081 connected! If it does not work, you might want to try -a instead of -c
24082 as an argument to slattach.
24084 ----------------------------------------------------------------------
24086 18.6.1.3 How to Shutdown the Connection
24090 # kill -INT `cat /var/run/slattach.modem.pid`
24092 to kill slattach. Keep in mind you must be root to do the above. Then go
24093 back to kermit (by running fg if you suspended it) and exit from it (q).
24095 The slattach manual page says you have to use ifconfig sl0 down to mark
24096 the interface down, but this does not seem to make any difference for me.
24097 (ifconfig sl0 reports the same thing.)
24099 Some times, your modem might refuse to drop the carrier (mine often does).
24100 In that case, simply start kermit and quit it again. It usually goes out
24103 ----------------------------------------------------------------------
24105 18.6.1.4 Troubleshooting
24107 If it does not work, feel free to ask me. The things that people tripped
24110 * Not using -c or -a in slattach (This should not be fatal, but some
24111 users have reported that this solves their problems.)
24113 * Using s10 instead of sl0 (might be hard to see the difference on some
24116 * Try ifconfig sl0 to see your interface status. For example, you might
24120 sl0: flags=10<POINTOPOINT>
24121 inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00
24123 * If you get ``no route to host'' messages from ping, there may be a
24124 problem with your routing table. You can use the netstat -r command to
24125 display the current routes :
24129 Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks:
24134 Route Tree for Protocol Family inet:
24136 default inr-3.Example.EDU UG 8 224515 sl0 - -
24137 localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438
24138 inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - -
24139 water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438
24142 The preceding examples are from a relatively busy system. The numbers
24143 on your system will vary depending on network activity.
24145 ----------------------------------------------------------------------
24147 18.6.2 Setting Up a SLIP Server
24149 This document provides suggestions for setting up SLIP Server services on
24150 a DragonFly system, which typically means configuring your system to
24151 automatically startup connections upon login for remote SLIP clients.
24153 ----------------------------------------------------------------------
24155 18.6.2.1 Prerequisites
24157 This section is very technical in nature, so background knowledge is
24158 required. It is assumed that you are familiar with the TCP/IP network
24159 protocol, and in particular, network and node addressing, network address
24160 masks, subnetting, routing, and routing protocols, such as RIP.
24161 Configuring SLIP services on a dial-up server requires a knowledge of
24162 these concepts, and if you are not familiar with them, please read a copy
24163 of either Craig Hunt's TCP/IP Network Administration published by O'Reilly
24164 & Associates, Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books
24165 on the TCP/IP protocol.
24167 It is further assumed that you have already set up your modem(s) and
24168 configured the appropriate system files to allow logins through your
24169 modems. If you have not prepared your system for this yet, please see the
24170 tutorial for configuring dialup services. You may also want to check the
24171 manual pages for sio(4) for information on the serial port device driver
24172 and ttys(5), gettytab(5), getty(8), & init(8) for information relevant to
24173 configuring the system to accept logins on modems, and perhaps stty(1) for
24174 information on setting serial port parameters (such as clocal for
24175 directly-connected serial interfaces).
24177 ----------------------------------------------------------------------
24179 18.6.2.2 Quick Overview
24181 In its typical configuration, using DragonFly as a SLIP server works as
24182 follows: a SLIP user dials up your DragonFly SLIP Server system and logs
24183 in with a special SLIP login ID that uses /usr/sbin/sliplogin as the
24184 special user's shell. The sliplogin program browses the file
24185 /etc/sliphome/slip.hosts to find a matching line for the special user, and
24186 if it finds a match, connects the serial line to an available SLIP
24187 interface and then runs the shell script /etc/sliphome/slip.login to
24188 configure the SLIP interface.
24190 ----------------------------------------------------------------------
24192 18.6.2.2.1 An Example of a SLIP Server Login
24194 For example, if a SLIP user ID were Shelmerg, Shelmerg's entry in
24195 /etc/master.passwd would look something like this:
24197 Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin
24199 When Shelmerg logs in, sliplogin will search /etc/sliphome/slip.hosts for
24200 a line that had a matching user ID; for example, there may be a line in
24201 /etc/sliphome/slip.hosts that reads:
24203 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
24205 sliplogin will find that matching line, hook the serial line into the next
24206 available SLIP interface, and then execute /etc/sliphome/slip.login like
24209 /etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
24211 If all goes well, /etc/sliphome/slip.login will issue an ifconfig for the
24212 SLIP interface to which sliplogin attached itself (slip interface 0, in
24213 the above example, which was the first parameter in the list given to
24214 slip.login) to set the local IP address (dc-slip), remote IP address
24215 (sl-helmer), network mask for the SLIP interface (0xfffffc00), and any
24216 additional flags (autocomp). If something goes wrong, sliplogin usually
24217 logs good informational messages via the daemon syslog facility, which
24218 usually logs to /var/log/messages (see the manual pages for syslogd(8) and
24219 syslog.conf(5) and perhaps check /etc/syslog.conf to see to what syslogd
24220 is logging and where it is logging to).
24222 OK, enough of the examples -- let us dive into setting up the system.
24224 ----------------------------------------------------------------------
24226 18.6.2.3 Kernel Configuration
24228 DragonFly's default kernels usually come with two SLIP interfaces defined
24229 (sl0 and sl1); you can use netstat -i to see whether these interfaces are
24230 defined in your kernel.
24232 Sample output from netstat -i:
24234 Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll
24235 ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133
24236 ed0 1500 138.247.224 ivory 291311 0 174209 0 133
24237 lo0 65535 <Link> 79 0 79 0 0
24238 lo0 65535 loop localhost 79 0 79 0 0
24239 sl0* 296 <Link> 0 0 0 0 0
24240 sl1* 296 <Link> 0 0 0 0 0
24242 The sl0 and sl1 interfaces shown from netstat -i indicate that there are
24243 two SLIP interfaces built into the kernel. (The asterisks after the sl0
24244 and sl1 indicate that the interfaces are ``down''.)
24246 However, DragonFly's default kernel does not come configured to forward
24247 packets (by default, your DragonFly machine will not act as a router) due
24248 to Internet RFC requirements for Internet hosts (see RFCs 1009
24249 [Requirements for Internet Gateways], 1122 [Requirements for Internet
24250 Hosts -- Communication Layers], and perhaps 1127 [A Perspective on the
24251 Host Requirements RFCs]). If you want your DragonFly SLIP Server to act as
24252 a router, you will have to edit the /etc/rc.conf file and change the
24253 setting of the gateway_enable variable to YES.
24255 You will then need to reboot for the new settings to take effect.
24257 You will notice that near the end of the default kernel configuration file
24258 (/sys/i386/conf/GENERIC) is a line that reads:
24262 This is the line that defines the number of SLIP devices available in the
24263 kernel; the number at the end of the line is the maximum number of SLIP
24264 connections that may be operating simultaneously.
24266 Please refer to Chapter 9 on Configuring the DragonFly Kernel for help in
24267 reconfiguring your kernel.
24269 ----------------------------------------------------------------------
24271 18.6.2.4 Sliplogin Configuration
24273 As mentioned earlier, there are three files in the /etc/sliphome directory
24274 that are part of the configuration for /usr/sbin/sliplogin (see
24275 sliplogin(8) for the actual manual page for sliplogin): slip.hosts, which
24276 defines the SLIP users and their associated IP addresses; slip.login,
24277 which usually just configures the SLIP interface; and (optionally)
24278 slip.logout, which undoes slip.login's effects when the serial connection
24281 ----------------------------------------------------------------------
24283 18.6.2.4.1 slip.hosts Configuration
24285 /etc/sliphome/slip.hosts contains lines which have at least four items
24286 separated by whitespace:
24288 * SLIP user's login ID
24290 * Local address (local to the SLIP server) of the SLIP link
24292 * Remote address of the SLIP link
24296 The local and remote addresses may be host names (resolved to IP addresses
24297 by /etc/hosts or by the domain name service, depending on your
24298 specifications in /etc/host.conf), and the network mask may be a name that
24299 can be resolved by a lookup into /etc/networks. On a sample system,
24300 /etc/sliphome/slip.hosts looks like this:
24303 # login local-addr remote-addr mask opt1 opt2
24304 # (normal,compress,noicmp)
24306 Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp
24308 At the end of the line is one or more of the options.
24310 * normal -- no header compression
24312 * compress -- compress headers
24314 * autocomp -- compress headers if the remote end allows it
24316 * noicmp -- disable ICMP packets (so any ``ping'' packets will be
24317 dropped instead of using up your bandwidth)
24319 Your choice of local and remote addresses for your SLIP links depends on
24320 whether you are going to dedicate a TCP/IP subnet or if you are going to
24321 use ``proxy ARP'' on your SLIP server (it is not ``true'' proxy ARP, but
24322 that is the terminology used in this section to describe it). If you are
24323 not sure which method to select or how to assign IP addresses, please
24324 refer to the TCP/IP books referenced in the SLIP Prerequisites (Section
24325 18.6.2.1) and/or consult your IP network manager.
24327 If you are going to use a separate subnet for your SLIP clients, you will
24328 need to allocate the subnet number out of your assigned IP network number
24329 and assign each of your SLIP client's IP numbers out of that subnet. Then,
24330 you will probably need to configure a static route to the SLIP subnet via
24331 your SLIP server on your nearest IP router.
24333 Otherwise, if you will use the ``proxy ARP'' method, you will need to
24334 assign your SLIP client's IP addresses out of your SLIP server's Ethernet
24335 subnet, and you will also need to adjust your /etc/sliphome/slip.login and
24336 /etc/sliphome/slip.logout scripts to use arp(8) to manage the proxy-ARP
24337 entries in the SLIP server's ARP table.
24339 ----------------------------------------------------------------------
24341 18.6.2.4.2 slip.login Configuration
24343 The typical /etc/sliphome/slip.login file looks like this:
24347 # @(#)slip.login 5.1 (Berkeley) 7/1/90
24350 # generic login file for a slip line. sliplogin invokes this with
24353 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24355 /sbin/ifconfig sl$1 inet $4 $5 netmask $6
24357 This slip.login file merely runs ifconfig for the appropriate SLIP
24358 interface with the local and remote addresses and network mask of the SLIP
24361 If you have decided to use the ``proxy ARP'' method (instead of using a
24362 separate subnet for your SLIP clients), your /etc/sliphome/slip.login file
24363 will need to look something like this:
24367 # @(#)slip.login 5.1 (Berkeley) 7/1/90
24370 # generic login file for a slip line. sliplogin invokes this with
24373 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24375 /sbin/ifconfig sl$1 inet $4 $5 netmask $6
24376 # Answer ARP requests for the SLIP client with our Ethernet addr
24377 /usr/sbin/arp -s $5 00:11:22:33:44:55 pub
24379 The additional line in this slip.login, arp -s $5 00:11:22:33:44:55 pub,
24380 creates an ARP entry in the SLIP server's ARP table. This ARP entry causes
24381 the SLIP server to respond with the SLIP server's Ethernet MAC address
24382 whenever another IP node on the Ethernet asks to speak to the SLIP
24383 client's IP address.
24385 When using the example above, be sure to replace the Ethernet MAC address
24386 (00:11:22:33:44:55) with the MAC address of your system's Ethernet card,
24387 or your ``proxy ARP'' will definitely not work! You can discover your SLIP
24388 server's Ethernet MAC address by looking at the results of running netstat
24389 -i; the second line of the output should look something like:
24391 ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116
24393 This indicates that this particular system's Ethernet MAC address is
24394 00:02:c1:28:5f:4a -- the periods in the Ethernet MAC address given by
24395 netstat -i must be changed to colons and leading zeros should be added to
24396 each single-digit hexadecimal number to convert the address into the form
24397 that arp(8) desires; see the manual page on arp(8) for complete
24398 information on usage.
24400 Note: When you create /etc/sliphome/slip.login and
24401 /etc/sliphome/slip.logout, the ``execute'' bit (chmod 755
24402 /etc/sliphome/slip.login /etc/sliphome/slip.logout) must be set, or
24403 sliplogin will be unable to execute it.
24405 ----------------------------------------------------------------------
24407 18.6.2.4.3 slip.logout Configuration
24409 /etc/sliphome/slip.logout is not strictly needed (unless you are
24410 implementing ``proxy ARP''), but if you decide to create it, this is an
24411 example of a basic slip.logout script:
24418 # logout file for a slip line. sliplogin invokes this with
24421 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24423 /sbin/ifconfig sl$1 down
24425 If you are using ``proxy ARP'', you will want to have
24426 /etc/sliphome/slip.logout remove the ARP entry for the SLIP client:
24433 # logout file for a slip line. sliplogin invokes this with
24436 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24438 /sbin/ifconfig sl$1 down
24439 # Quit answering ARP requests for the SLIP client
24440 /usr/sbin/arp -d $5
24442 The arp -d $5 removes the ARP entry that the ``proxy ARP'' slip.login
24443 added when the SLIP client logged in.
24445 It bears repeating: make sure /etc/sliphome/slip.logout has the execute
24446 bit set after you create it (ie, chmod 755 /etc/sliphome/slip.logout).
24448 ----------------------------------------------------------------------
24450 18.6.2.5 Routing Considerations
24452 If you are not using the ``proxy ARP'' method for routing packets between
24453 your SLIP clients and the rest of your network (and perhaps the Internet),
24454 you will probably have to add static routes to your closest default
24455 router(s) to route your SLIP client subnet via your SLIP server.
24457 ----------------------------------------------------------------------
24459 18.6.2.5.1 Static Routes
24461 Adding static routes to your nearest default routers can be troublesome
24462 (or impossible if you do not have authority to do so...). If you have a
24463 multiple-router network in your organization, some routers, such as those
24464 made by Cisco and Proteon, may not only need to be configured with the
24465 static route to the SLIP subnet, but also need to be told which static
24466 routes to tell other routers about, so some expertise and
24467 troubleshooting/tweaking may be necessary to get static-route-based
24470 ----------------------------------------------------------------------
24472 18.6.2.5.2 Running GateD(R)
24474 Note: GateD(R) is proprietary software now and will not be available as
24475 source code to the public anymore (more info on the GateD website). This
24476 section only exists to ensure backwards compatibility for those that are
24477 still using an older version.
24479 An alternative to the headaches of static routes is to install GateD on
24480 your DragonFly SLIP server and configure it to use the appropriate routing
24481 protocols (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP subnet.
24482 You'll need to write a /etc/gated.conf file to configure your gated; here
24483 is a sample, similar to what the author used on a FreeBSD SLIP server:
24486 # gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
24487 # Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
24492 traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;
24495 interface sl noripout noripin ;
24496 interface ed ripin ripout version 1 ;
24497 traceoptions route ;
24501 # Turn on a bunch of tracing info for the interface to the kernel:
24503 traceoptions remnants request routes info interface ;
24507 # Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
24510 export proto rip interface ed {
24512 xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections
24517 # Accept routes from RIP via ed Ethernet interfaces
24519 import proto rip interface ed {
24523 The above sample gated.conf file broadcasts routing information regarding
24524 the SLIP subnet xxx.xxx.yy via RIP onto the Ethernet; if you are using a
24525 different Ethernet driver than the ed driver, you will need to change the
24526 references to the ed interface appropriately. This sample file also sets
24527 up tracing to /var/tmp/gated.output for debugging GateD's activity; you
24528 can certainly turn off the tracing options if GateD works OK for you. You
24529 will need to change the xxx.xxx.yy's into the network address of your own
24530 SLIP subnet (be sure to change the net mask in the proto direct clause as
24533 Once you have installed and configured GateD on your system, you will need
24534 to tell the DragonFly startup scripts to run GateD in place of routed. The
24535 easiest way to accomplish this is to set the router and router_flags
24536 variables in /etc/rc.conf. Please see the manual page for GateD for
24537 information on command-line parameters.
24539 ----------------------------------------------------------------------
24541 Chapter 19 Advanced Networking
24545 This chapter will cover some of the more frequently used network services
24546 on UNIX systems. We will cover how to define, set up, test and maintain
24547 all of the network services that DragonFly utilizes. In addition, there
24548 have been example configuration files included throughout this chapter for
24549 you to benefit from.
24551 After reading this chapter, you will know:
24553 * The basics of gateways and routes.
24555 * How to set up IEEE 802.11 and Bluetooth(R) devices.
24557 * How to make DragonFly act as a bridge.
24559 * How to set up a network filesystem.
24561 * How to set up network booting on a diskless machine.
24563 * How to set up a network information server for sharing user accounts.
24565 * How to set up automatic network settings using DHCP.
24567 * How to set up a domain name server.
24569 * How to synchronize the time and date, and set up a time server, with
24572 * How to set up network address translation.
24574 * How to manage the inetd daemon.
24576 * How to connect two computers via PLIP.
24578 * How to set up IPv6 on a DragonFly machine.
24580 Before reading this chapter, you should:
24582 * Understand the basics of the /etc/rc scripts.
24584 * Be familiar with basic network terminology.
24586 ----------------------------------------------------------------------
24588 19.2 Gateways and Routes
24590 Contributed by Coranth Gryphon.
24592 For one machine to be able to find another over a network, there must be a
24593 mechanism in place to describe how to get from one to the other. This is
24594 called routing. A ``route'' is a defined pair of addresses: a
24595 ``destination'' and a ``gateway''. The pair indicates that if you are
24596 trying to get to this destination, communicate through this gateway. There
24597 are three types of destinations: individual hosts, subnets, and
24598 ``default''. The ``default route'' is used if none of the other routes
24599 apply. We will talk a little bit more about default routes later on. There
24600 are also three types of gateways: individual hosts, interfaces (also
24601 called ``links''), and Ethernet hardware addresses (MAC addresses).
24603 ----------------------------------------------------------------------
24607 To illustrate different aspects of routing, we will use the following
24608 example from netstat:
24613 Destination Gateway Flags Refs Use Netif Expire
24615 default outside-gw UGSc 37 418 ppp0
24616 localhost localhost UH 0 181 lo0
24617 test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
24618 10.20.30.255 link#1 UHLW 1 2421
24619 example.com link#1 UC 0 0
24620 host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
24621 host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
24622 host2.example.com link#1 UC 0 0
24625 The first two lines specify the default route (which we will cover in the
24626 next section) and the localhost route.
24628 The interface (Netif column) that this routing table specifies to use for
24629 localhost is lo0, also known as the loopback device. This says to keep all
24630 traffic for this destination internal, rather than sending it out over the
24631 LAN, since it will only end up back where it started.
24633 The next thing that stands out are the addresses beginning with 0:e0:.
24634 These are Ethernet hardware addresses, which are also known as MAC
24635 addresses. DragonFly will automatically identify any hosts (test0 in the
24636 example) on the local Ethernet and add a route for that host, directly to
24637 it over the Ethernet interface, ed0. There is also a timeout (Expire
24638 column) associated with this type of route, which is used if we fail to
24639 hear from the host in a specific amount of time. When this happens, the
24640 route to this host will be automatically deleted. These hosts are
24641 identified using a mechanism known as RIP (Routing Information Protocol),
24642 which figures out routes to local hosts based upon a shortest path
24645 DragonFly will also add subnet routes for the local subnet (10.20.30.255
24646 is the broadcast address for the subnet 10.20.30, and example.com is the
24647 domain name associated with that subnet). The designation link#1 refers to
24648 the first Ethernet card in the machine. You will notice no additional
24649 interface is specified for those.
24651 Both of these groups (local network hosts and local subnets) have their
24652 routes automatically configured by a daemon called routed. If this is not
24653 run, then only routes which are statically defined (i.e. entered
24654 explicitly) will exist.
24656 The host1 line refers to our host, which it knows by Ethernet address.
24657 Since we are the sending host, DragonFly knows to use the loopback
24658 interface (lo0) rather than sending it out over the Ethernet interface.
24660 The two host2 lines are an example of what happens when we use an
24661 ifconfig(8) alias (see the section on Ethernet for reasons why we would do
24662 this). The => symbol after the lo0 interface says that not only are we
24663 using the loopback (since this address also refers to the local host), but
24664 specifically it is an alias. Such routes only show up on the host that
24665 supports the alias; all other hosts on the local network will simply have
24666 a link#1 line for such routes.
24668 The final line (destination subnet 224) deals with multicasting, which
24669 will be covered in another section.
24671 Finally, various attributes of each route can be seen in the Flags column.
24672 Below is a short table of some of these flags and their meanings:
24674 U Up: The route is active.
24675 H Host: The route destination is a single host.
24676 G Gateway: Send anything for this destination on to this remote system,
24677 which will figure out from there where to send it.
24678 S Static: This route was configured manually, not automatically generated
24680 C Clone: Generates a new route based upon this route for machines we
24681 connect to. This type of route is normally used for local networks.
24682 W WasCloned: Indicated a route that was auto-configured based upon a local
24683 area network (Clone) route.
24684 L Link: Route involves references to Ethernet hardware.
24686 ----------------------------------------------------------------------
24688 19.2.2 Default Routes
24690 When the local system needs to make a connection to a remote host, it
24691 checks the routing table to determine if a known path exists. If the
24692 remote host falls into a subnet that we know how to reach (Cloned routes),
24693 then the system checks to see if it can connect along that interface.
24695 If all known paths fail, the system has one last option: the ``default''
24696 route. This route is a special type of gateway route (usually the only one
24697 present in the system), and is always marked with a c in the flags field.
24698 For hosts on a local area network, this gateway is set to whatever machine
24699 has a direct connection to the outside world (whether via PPP link, DSL,
24700 cable modem, T1, or another network interface).
24702 If you are configuring the default route for a machine which itself is
24703 functioning as the gateway to the outside world, then the default route
24704 will be the gateway machine at your Internet Service Provider's (ISP)
24707 Let us look at an example of default routes. This is a common
24710 [Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
24713 The hosts Local1 and Local2 are at your site. Local1 is connected to an
24714 ISP via a dial up PPP connection. This PPP server computer is connected
24715 through a local area network to another gateway computer through an
24716 external interface to the ISPs Internet feed.
24718 The default routes for each of your machines will be:
24720 Host Default Gateway Interface
24721 Local2 Local1 Ethernet
24724 A common question is ``Why (or how) would we set the T1-GW to be the
24725 default gateway for Local1, rather than the ISP server it is connected
24728 Remember, since the PPP interface is using an address on the ISP's local
24729 network for your side of the connection, routes for any other machines on
24730 the ISP's local network will be automatically generated. Hence, you will
24731 already know how to reach the T1-GW machine, so there is no need for the
24732 intermediate step of sending traffic to the ISP server.
24734 It is common to use the address X.X.X.1 as the gateway address for your
24735 local network. So (using the same example), if your local class-C address
24736 space was 10.20.30 and your ISP was using 10.9.9 then the default routes
24740 Local2 (10.20.30.2) Local1 (10.20.30.1)
24741 Local1 (10.20.30.1, 10.9.9.30) T1-GW (10.9.9.1)
24743 You can easily define the default route via the /etc/rc.conf file. In our
24744 example, on the Local2 machine, we added the following line in
24747 defaultrouter="10.20.30.1"
24749 It is also possible to do it directly from the command line with the
24752 # route add default 10.20.30.1
24754 For more informations on manual manipulation of network routing tables,
24755 consult route(8) manual page.
24757 ----------------------------------------------------------------------
24759 19.2.3 Dual Homed Hosts
24761 There is one other type of configuration that we should cover, and that is
24762 a host that sits on two different networks. Technically, any machine
24763 functioning as a gateway (in the example above, using a PPP connection)
24764 counts as a dual-homed host. But the term is really only used to refer to
24765 a machine that sits on two local-area networks.
24767 In one case, the machine has two Ethernet cards, each having an address on
24768 the separate subnets. Alternately, the machine may only have one Ethernet
24769 card, and be using ifconfig(8) aliasing. The former is used if two
24770 physically separate Ethernet networks are in use, the latter if there is
24771 one physical network segment, but two logically separate subnets.
24773 Either way, routing tables are set up so that each subnet knows that this
24774 machine is the defined gateway (inbound route) to the other subnet. This
24775 configuration, with the machine acting as a router between the two
24776 subnets, is often used when we need to implement packet filtering or
24777 firewall security in either or both directions.
24779 If you want this machine to actually forward packets between the two
24780 interfaces, you need to tell DragonFly to enable this ability. See the
24781 next section for more details on how to do this.
24783 ----------------------------------------------------------------------
24785 19.2.4 Building a Router
24787 A network router is simply a system that forwards packets from one
24788 interface to another. This is not enabled by default in DragonFly. You can
24789 enable this feature by changing the following variable to YES in
24792 gateway_enable=YES # Set to YES if this host will be a gateway
24794 This option will set the sysctl(8) variable net.inet.ip.forwarding to 1.
24795 If you should need to stop routing temporarily, you can reset this to 0
24798 Your new router will need routes to know where to send the traffic. If
24799 your network is simple enough you can use static routes. DragonFly also
24800 comes with the standard BSD routing daemon routed(8), which speaks RIP
24801 (both version 1 and version 2) and IRDP. Support for BGP v4, OSPF v2, and
24802 other sophisticated routing protocols is available with the net/zebra
24803 package. Commercial products such as GateD are also available for more
24804 complex network routing solutions.
24806 Even when DragonFly is configured in this way, it does not completely
24807 comply with the Internet standard requirements for routers. It comes close
24808 enough for ordinary use, however.
24810 ----------------------------------------------------------------------
24812 19.2.5 Setting Up Static Routes
24814 Contributed by Al Hoang.
24816 19.2.5.1 Manual Configuration
24818 Let us assume we have a network as follows:
24821 | (10.0.0.1/24) Default Router to Internet
24827 | | (DragonFly gateway)
24832 +--------------------------------+
24833 Internal Net 1 | 192.168.1.2/24
24844 In this scenario, RouterA is our DragonFly machine that is acting as a
24845 router to the rest of the Internet. It has a default route set to 10.0.0.1
24846 which allows it to connect with the outside world. We will assume that
24847 RouterB is already configured properly and knows how to get wherever it
24848 needs to go. (This is simple in this picture. Just add a default route on
24849 RouterB using 192.168.1.1 as the gateway.)
24851 If we look at the routing table for RouterA we would see something like
24858 Destination Gateway Flags Refs Use Netif Expire
24859 default 10.0.0.1 UGS 0 49378 xl0
24860 127.0.0.1 127.0.0.1 UH 0 6 lo0
24861 10.0.0/24 link#1 UC 0 0 xl0
24862 192.168.1/24 link#2 UC 0 0 xl1
24864 With the current routing table RouterA will not be able to reach our
24865 Internal Net 2. It does not have a route for 192.168.2.0/24. One way to
24866 alleviate this is to manually add the route. The following command would
24867 add the Internal Net 2 network to RouterA's routing table using
24868 192.168.1.2 as the next hop:
24870 # route add -net 192.168.2.0/24 192.168.1.2
24872 Now RouterA can reach any hosts on the 192.168.2.0/24 network.
24874 ----------------------------------------------------------------------
24876 19.2.5.2 Persistent Configuration
24878 The above example is perfect for configuring a static route on a running
24879 system. However, one problem is that the routing information will not
24880 persist if you reboot your DragonFly machine. The way to handle the
24881 addition of a static route is to put it in your /etc/rc.conf file:
24883 # Add Internal Net 2 as a static route
24884 static_routes="internalnet2"
24885 route_internalnet2="-net 192.168.2.0/24 192.168.1.2"
24887 The static_routes configuration variable is a list of strings seperated by
24888 a space. Each string references to a route name. In our above example we
24889 only have one string in static_routes. This string is internalnet2. We
24890 then add a configuration variable called route_internalnet2 where we put
24891 all of the configuration parameters we would give to the route(8) command.
24892 For our example above we would have used the command:
24894 # route add -net 192.168.2.0/24 192.168.1.2
24896 so we need "-net 192.168.2.0/24 192.168.1.2".
24898 As said above, we can have more than one string in static_routes. This
24899 allows us to create multiple static routes. The following lines shows an
24900 example of adding static routes for the 192.168.0.0/24 and 192.168.1.0/24
24901 networks on an imaginary router:
24903 static_routes="net1 net2"
24904 route_net1="-net 192.168.0.0/24 192.168.0.1"
24905 route_net2="-net 192.168.1.0/24 192.168.1.1"
24907 ----------------------------------------------------------------------
24909 19.2.6 Routing Propagation
24911 We have already talked about how we define our routes to the outside
24912 world, but not about how the outside world finds us.
24914 We already know that routing tables can be set up so that all traffic for
24915 a particular address space (in our examples, a class-C subnet) can be sent
24916 to a particular host on that network, which will forward the packets
24919 When you get an address space assigned to your site, your service provider
24920 will set up their routing tables so that all traffic for your subnet will
24921 be sent down your PPP link to your site. But how do sites across the
24922 country know to send to your ISP?
24924 There is a system (much like the distributed DNS information) that keeps
24925 track of all assigned address-spaces, and defines their point of
24926 connection to the Internet Backbone. The ``Backbone'' are the main trunk
24927 lines that carry Internet traffic across the country, and around the
24928 world. Each backbone machine has a copy of a master set of tables, which
24929 direct traffic for a particular network to a specific backbone carrier,
24930 and from there down the chain of service providers until it reaches your
24933 It is the task of your service provider to advertise to the backbone sites
24934 that they are the point of connection (and thus the path inward) for your
24935 site. This is known as route propagation.
24937 ----------------------------------------------------------------------
24939 19.2.7 Troubleshooting
24941 Sometimes, there is a problem with routing propagation, and some sites are
24942 unable to connect to you. Perhaps the most useful command for trying to
24943 figure out where routing is breaking down is the traceroute(8) command. It
24944 is equally useful if you cannot seem to make a connection to a remote
24945 machine (i.e. ping(8) fails).
24947 The traceroute(8) command is run with the name of the remote host you are
24948 trying to connect to. It will show the gateway hosts along the path of the
24949 attempt, eventually either reaching the target host, or terminating
24950 because of a lack of connection.
24952 For more information, see the manual page for traceroute(8).
24954 ----------------------------------------------------------------------
24956 19.2.8 Multicast Routing
24958 DragonFly supports both multicast applications and multicast routing
24959 natively. Multicast applications do not require any special configuration
24960 of DragonFly; applications will generally run out of the box. Multicast
24961 routing requires that support be compiled into the kernel:
24965 In addition, the multicast routing daemon, mrouted(8) must be configured
24966 to set up tunnels and DVMRP via /etc/mrouted.conf. More details on
24967 multicast configuration may be found in the manual page for mrouted(8).
24969 ----------------------------------------------------------------------
24971 19.3 Wireless Networking
24973 Written by Eric Anderson.
24975 ----------------------------------------------------------------------
24977 19.3.1 Introduction
24979 It can be very useful to be able to use a computer without the annoyance
24980 of having a network cable attached at all times. DragonFly can be used as
24981 a wireless client, and even as a wireless ``access point''.
24983 ----------------------------------------------------------------------
24985 19.3.2 Wireless Modes of Operation
24987 There are two different ways to configure 802.11 wireless devices: BSS and
24990 ----------------------------------------------------------------------
24994 BSS mode is the mode that typically is used. BSS mode is also called
24995 infrastructure mode. In this mode, a number of wireless access points are
24996 connected to a wired network. Each wireless network has its own name. This
24997 name is called the SSID of the network.
24999 Wireless clients connect to these wireless access points. The IEEE 802.11
25000 standard defines the protocol that wireless networks use to connect. A
25001 wireless client can be tied to a specific network, when a SSID is set. A
25002 wireless client can also attach to any network by not explicitly setting a
25005 ----------------------------------------------------------------------
25009 IBSS mode, also called ad-hoc mode, is designed for point to point
25010 connections. There are actually two types of ad-hoc mode. One is IBSS
25011 mode, also called ad-hoc or IEEE ad-hoc mode. This mode is defined by the
25012 IEEE 802.11 standards. The second is called demo ad-hoc mode or Lucent
25013 ad-hoc mode (and sometimes, confusingly, ad-hoc mode). This is the old,
25014 pre-802.11 ad-hoc mode and should only be used for legacy installations.
25015 We will not cover either of the ad-hoc modes further.
25017 ----------------------------------------------------------------------
25019 19.3.3 Infrastructure Mode
25021 19.3.3.1 Access Points
25023 Access points are wireless networking devices that allow one or more
25024 wireless clients to use the device as a central hub. When using an access
25025 point, all clients communicate through the access point. Multiple access
25026 points are often used to cover a complete area such as a house, business,
25027 or park with a wireless network.
25029 Access points typically have multiple network connections: the wireless
25030 card, and one or more wired Ethernet adapters for connection to the rest
25033 Access points can either be purchased prebuilt, or you can build your own
25034 with DragonFly and a supported wireless card. Several vendors make
25035 wireless access points and wireless cards with various features.
25037 ----------------------------------------------------------------------
25039 19.3.3.2 Building a DragonFly Access Point
25041 ----------------------------------------------------------------------
25043 19.3.3.2.1 Requirements
25045 In order to set up a wireless access point with DragonFly, you need to
25046 have a compatible wireless card. Currently, only cards with the Prism
25047 chipset are supported. You will also need a wired network card that is
25048 supported by DragonFly (this should not be difficult to find, DragonFly
25049 supports a lot of different devices). For this guide, we will assume you
25050 want to bridge(4) all traffic between the wireless device and the network
25051 attached to the wired network card.
25053 The hostap functionality that DragonFly uses to implement the access point
25054 works best with certain versions of firmware. Prism 2 cards should use
25055 firmware version 1.3.4 or newer. Prism 2.5 and Prism 3 cards should use
25056 firmware 1.4.9. Older versions of the firmware way or may not function
25057 correctly. At this time, the only way to update cards is with Windows
25058 firmware update utilities available from your card's manufacturer.
25060 ----------------------------------------------------------------------
25062 19.3.3.2.2 Setting It Up
25064 First, make sure your system can see the wireless card:
25067 wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
25068 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
25069 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
25070 ether 00:09:2d:2d:c9:50
25071 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
25074 stationname "DragonFly Wireless node"
25075 channel 10 authmode OPEN powersavemode OFF powersavesleep 100
25076 wepmode OFF weptxkey 1
25078 Do not worry about the details now, just make sure it shows you something
25079 to indicate you have a wireless card installed. If you have trouble seeing
25080 the wireless interface, and you are using a PC Card, you may want to check
25081 out pccardc(8) and pccardd(8) manual pages for more information.
25083 Next, you will need to load a module in order to get the bridging part of
25084 DragonFly ready for the access point. To load the bridge(4) module, simply
25085 run the following command:
25089 It should not have produced any errors when loading the module. If it did,
25090 you may need to compile the bridge(4) code into your kernel. The Bridging
25091 section of this handbook should be able to help you accomplish that task.
25093 Now that you have the bridging stuff done, we need to tell the DragonFly
25094 kernel which interfaces to bridge together. We do that by using sysctl(8):
25096 # sysctl net.link.ether.bridge=1
25097 # sysctl net.link.ether.bridge_cfg="wi0,xl0"
25098 # sysctl net.inet.ip.forwarding=1
25100 Now it is time for the wireless card setup. The following command will set
25101 the card into an access point:
25103 # ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "DragonFly AP"
25106 The ifconfig(8) line brings the wi0 interface up, sets its SSID to my_net,
25107 and sets the station name to DragonFly AP. The media DS/11Mbps sets the
25108 card into 11Mbps mode and is needed for any mediaopt to take effect. The
25109 mediaopt hostap option places the interface into access point mode. The
25110 channel 11 option sets the 802.11b channel to use. The wicontrol(8) manual
25111 page has valid channel options for your regulatory domain.
25113 Now you should have a complete functioning access point up and running.
25114 You are encouraged to read wicontrol(8), ifconfig(8), and wi(4) for
25115 further information.
25117 It is also suggested that you read the section on encryption that follows.
25119 ----------------------------------------------------------------------
25121 19.3.3.2.3 Status Information
25123 Once the access point is configured and operational, operators will want
25124 to see the clients that are associated with the access point. At any time,
25125 the operator may type:
25129 00:09:b7:7b:9d:16 asid=04c0, flags=3<ASSOC,AUTH>, caps=1<ESS>, rates=f<1M,2M,5.5M,11M>, sig=38/15
25131 This shows that there is one station associated, along with its
25132 parameters. The signal indicated should be used as a relative indication
25133 of strength only. Its translation to dBm or other units varies between
25134 different firmware revisions.
25136 ----------------------------------------------------------------------
25140 A wireless client is a system that accesses an access point or another
25143 Typically, wireless clients only have one network device, the wireless
25146 There are a few different ways to configure a wireless client. These are
25147 based on the different wireless modes, generally BSS (infrastructure mode,
25148 which requires an access point), and IBSS (ad-hoc, or peer-to-peer mode).
25149 In our example, we will use the most popular of the two, BSS mode, to talk
25150 to an access point.
25152 ----------------------------------------------------------------------
25154 19.3.3.3.1 Requirements
25156 There is only one real requirement for setting up DragonFly as a wireless
25157 client. You will need a wireless card that is supported by DragonFly.
25159 ----------------------------------------------------------------------
25161 19.3.3.3.2 Setting Up a Wireless DragonFly Client
25163 You will need to know a few things about the wireless network you are
25164 joining before you start. In this example, we are joining a network that
25165 has a name of my_net, and encryption turned off.
25167 Note: In this example, we are not using encryption, which is a dangerous
25168 situation. In the next section, you will learn how to turn on
25169 encryption, why it is important to do so, and why some encryption
25170 technologies still do not completely protect you.
25172 Make sure your card is recognized by DragonFly:
25175 wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
25176 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
25177 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
25178 ether 00:09:2d:2d:c9:50
25179 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
25182 stationname "DragonFly Wireless node"
25183 channel 10 authmode OPEN powersavemode OFF powersavesleep 100
25184 wepmode OFF weptxkey 1
25186 Now, we can set the card to the correct settings for our network:
25188 # ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net
25190 Replace 192.168.0.20 and 255.255.255.0 with a valid IP address and netmask
25191 on your wired network. Remember, our access point is bridging the data
25192 between the wireless network, and the wired network, so it will appear to
25193 the other devices on your network that you are on the wired network just
25196 Once you have done that, you should be able to ping hosts on the wired
25197 network just as if you were connected using a standard wired connection.
25199 If you are experiencing problems with your wireless connection, check to
25200 make sure that your are associated (connected) to the access point:
25204 should return some information, and you should see:
25208 If it does not show associated, then you may be out of range of the access
25209 point, have encryption on, or possibly have a configuration problem.
25211 ----------------------------------------------------------------------
25213 19.3.3.4 Encryption
25215 Encryption on a wireless network is important because you no longer have
25216 the ability to keep the network contained in a well protected area. Your
25217 wireless data will be broadcast across your entire neighborhood, so anyone
25218 who cares to read it can. This is where encryption comes in. By encrypting
25219 the data that is sent over the airwaves, you make it much more difficult
25220 for any interested party to grab your data right out of the air.
25222 The two most common ways to encrypt the data between your client and the
25223 access point are WEP, and ipsec(4).
25225 ----------------------------------------------------------------------
25229 WEP is an abbreviation for Wired Equivalency Protocol. WEP is an attempt
25230 to make wireless networks as safe and secure as a wired network.
25231 Unfortunately, it has been cracked, and is fairly trivial to break. This
25232 also means it is not something to rely on when it comes to encrypting
25235 It is better than nothing, so use the following to turn on WEP on your new
25236 DragonFly access point:
25238 # ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap
25240 And you can turn on WEP on a client with this command:
25242 # ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890
25244 Note that you should replace the 0x1234567890 with a more unique key.
25246 ----------------------------------------------------------------------
25250 ipsec(4) is a much more robust and powerful tool for encrypting data
25251 across a network. This is definitely the preferred way to encrypt data
25252 over a wireless network. You can read more about ipsec(4) security and how
25253 to implement it in the IPsec section of this handbook.
25255 ----------------------------------------------------------------------
25259 There are a small number of tools available for use in debugging and
25260 setting up your wireless network, and here we will attempt to describe
25261 some of them and what they do.
25263 ----------------------------------------------------------------------
25265 19.3.3.5.1 The wicontrol, ancontrol and raycontrol Utilities
25267 These are the tools you can use to control how your wireless card behaves
25268 on the wireless network. In the examples above, we have chosen to use
25269 wicontrol(8), since our wireless card is a wi0 interface. If you had a
25270 Cisco wireless device, it would come up as an0, and therefore you would
25273 ----------------------------------------------------------------------
25275 19.3.3.5.2 The ifconfig Command
25277 The ifconfig(8) command can be used to do many of the same options as
25278 wicontrol(8), however it does lack a few options. Check ifconfig(8) for
25279 command line parameters and options.
25281 ----------------------------------------------------------------------
25283 19.3.3.6 Supported Cards
25285 19.3.3.6.1 Access Points
25287 The only cards that are currently supported for BSS (as an access point)
25288 mode are devices based on the Prism 2, 2.5, or 3 chipsets. For a complete
25289 list, look at wi(4).
25291 ----------------------------------------------------------------------
25295 Almost all 802.11b wireless cards are currently supported under DragonFly.
25296 Most cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will
25297 work as a wireless network card in IBSS (ad-hoc, peer-to-peer, and BSS)
25300 ----------------------------------------------------------------------
25304 Written by Pav Lucistnik.
25306 ----------------------------------------------------------------------
25308 19.4.1 Introduction
25310 Bluetooth is a wireless technology for creating personal networks
25311 operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
25312 Networks are usually formed ad-hoc from portable devices such as cellular
25313 phones, handhelds and laptops. Unlike the other popular wireless
25314 technology, Wi-Fi, Bluetooth offers higher level service profiles, e.g.
25315 FTP-like file servers, file pushing, voice transport, serial line
25316 emulation, and more.
25318 The Bluetooth stack in DragonFly is implemented using the Netgraph
25319 framework (see netgraph(4)). A broad variety of Bluetooth USB dongles is
25320 supported by the ng_ubt(4) driver. The Broadcom BCM2033 chip based
25321 Bluetooth devices are supported via the ubtbcmfw(4) and ng_ubt(4) drivers.
25322 The 3Com Bluetooth PC Card 3CRWB60-A is supported by the ng_bt3c(4)
25323 driver. Serial and UART based Bluetooth devices are supported via sio(4),
25324 ng_h4(4) and hcseriald(8). This chapter describes the use of the USB
25325 Bluetooth dongle. Bluetooth support is available in DragonFly 5.0 and
25328 ----------------------------------------------------------------------
25330 19.4.2 Plugging in the Device
25332 By default Bluetooth device drivers are available as kernel modules.
25333 Before attaching a device, you will need to load the driver into the
25338 If the Bluetooth device is present in the system during system startup,
25339 load the module from /boot/loader.conf.
25343 Plug in your USB dongle. The output similar to the following will appear
25344 on the console (or in syslog).
25346 ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
25347 ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
25348 ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
25349 wMaxPacketSize=49, nframes=6, buffer size=294
25351 Copy /usr/share/examples/netgraph/bluetooth/rc.bluetooth into some
25352 convenient place, like /etc/rc.bluetooth. This script is used to start and
25353 stop the Bluetooth stack. It is a good idea to stop the stack before
25354 unplugging the device, but it is not (usually) fatal. When starting the
25355 stack, you will receive output similar to the following:
25357 # /etc/rc.bluetooth start ubt0
25358 BD_ADDR: 00:02:72:00:d4:1a
25359 Features: 0xff 0xff 0xf 00 00 00 00 00
25360 <3-Slot> <5-Slot> <Encryption> <Slot offset>
25361 <Timing accuracy> <Switch> <Hold mode> <Sniff mode>
25362 <Park mode> <RSSI> <Channel quality> <SCO link>
25363 <HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
25364 <Paging scheme> <Power control> <Transparent SCO data>
25365 Max. ACL packet size: 192 bytes
25366 Number of ACL packets: 8
25367 Max. SCO packet size: 64 bytes
25368 Number of SCO packets: 8
25370 ----------------------------------------------------------------------
25372 19.4.3 Host Controller Interface (HCI)
25374 Host Controller Interface (HCI) provides a command interface to the
25375 baseband controller and link manager, and access to hardware status and
25376 control registers. This interface provides a uniform method of accessing
25377 the Bluetooth baseband capabilities. HCI layer on the Host exchanges data
25378 and commands with the HCI firmware on the Bluetooth hardware. The Host
25379 Controller Transport Layer (i.e. physical bus) driver provides both HCI
25380 layers with the ability to exchange information with each other.
25382 A single Netgraph node of type hci is created for a single Bluetooth
25383 device. The HCI node is normally connected to the Bluetooth device driver
25384 node (downstream) and the L2CAP node (upstream). All HCI operations must
25385 be performed on the HCI node and not on the device driver node. Default
25386 name for the HCI node is ``devicehci''. For more details refer to the
25387 ng_hci(4) man page.
25389 One of the most common tasks is discovery of Bluetooth devices in RF
25390 proximity. This operation is called inquiry. Inquiry and other HCI
25391 realated operations are done with the hccontrol(8) utility. The example
25392 below shows how to find out which Bluetooth devices are in range. You
25393 should receive the list of devices in a few seconds. Note that a remote
25394 device will only answer the inquiry if it put into discoverable mode.
25396 % hccontrol -n ubt0hci inquiry
25397 Inquiry result, num_responses=1
25399 BD_ADDR: 00:80:37:29:19:a4
25400 Page Scan Rep. Mode: 0x1
25401 Page Scan Period Mode: 00
25404 Clock offset: 0x78ef
25405 Inquiry complete. Status: No error [00]
25407 BD_ADDR is unique address of a Bluetooth device, similar to MAC addresses
25408 of a network card. This address is needed for further communication with a
25409 device. It is possible to assign human readable name to a BD_ADDR. The
25410 /etc/bluetooth/hosts file contains information regarding the known
25411 Bluetooth hosts. The following example shows how to obtain human readable
25412 name that was assigned to the remote device.
25414 % hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4
25415 BD_ADDR: 00:80:37:29:19:a4
25418 If you perform an inquiry on a remote Bluetooth device, it will find your
25419 computer as ``your.host.name (ubt0)''. The name assigned to the local
25420 device can be changed at any time.
25422 The Bluetooth system provides a point-to-point connection (only two
25423 Bluetooth units involved), or a point-to-multipoint connection. In the
25424 point-to-multipoint connection the connection is shared among several
25425 Bluetooth devices. The following example shows how to obtain the list of
25426 active baseband connections for the local device.
25428 % hccontrol -n ubt0hci read_connection_list
25429 Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
25430 00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN
25432 A connection handle is useful when termination of the baseband connection
25433 is required. Note, that it is normally not required to do it by hand. The
25434 stack will automatically terminate inactive baseband connections.
25436 # hccontrol -n ubt0hci disconnect 41
25437 Connection handle: 41
25438 Reason: Connection terminated by local host [0x16]
25440 Refer to hccontrol help for a complete listing of available HCI commands.
25441 Most of the HCI commands do not require superuser privileges.
25443 ----------------------------------------------------------------------
25445 19.4.4 Logical Link Control and Adaptation Protocol (L2CAP)
25447 Logical Link Control and Adaptation Protocol (L2CAP) provides
25448 connection-oriented and connectionless data services to upper layer
25449 protocols with protocol multiplexing capability and segmentation and
25450 reassembly operation. L2CAP permits higher level protocols and
25451 applications to transmit and receive L2CAP data packets up to 64 kilobytes
25454 L2CAP is based around the concept of channels. Channel is a logical
25455 connection on top of baseband connection. Each channel is bound to a
25456 single protocol in a many-to-one fashion. Multiple channels can be bound
25457 to the same protocol, but a channel cannot be bound to multiple protocols.
25458 Each L2CAP packet received on a channel is directed to the appropriate
25459 higher level protocol. Multiple channels can share the same baseband
25462 A single Netgraph node of type l2cap is created for a single Bluetooth
25463 device. The L2CAP node is normally connected to the Bluetooth HCI node
25464 (downstream) and Bluetooth sockets nodes (upstream). Default name for the
25465 L2CAP node is ``devicel2cap''. For more details refer to the ng_l2cap(4)
25468 A useful command is l2ping(8), which can be used to ping other devices.
25469 Some Bluetooth implementations might not return all of the data sent to
25470 them, so 0 bytes in the following example is normal.
25472 # l2ping -a 00:80:37:29:19:a4
25473 0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
25474 0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
25475 0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
25476 0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0
25478 The l2control(8) utility is used to perform various operations on L2CAP
25479 nodes. This example shows how to obtain the list of logical connections
25480 (channels) and the list of baseband connections for the local device.
25482 % l2control -a 00:02:72:00:d4:1a read_channel_list
25484 Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State
25485 00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN
25486 % l2control -a 00:02:72:00:d4:1a read_connection_list
25488 Remote BD_ADDR Handle Flags Pending State
25489 00:07:e0:00:0b:ca 41 O 0 OPEN
25491 Another diagnostic tool is btsockstat(1). It does a job similar to as
25492 netstat(1) does, but for Bluetooth network-related data structures. The
25493 example below shows the same logical connection as l2control(8) above.
25496 Active L2CAP sockets
25497 PCB Recv-Q Send-Q Local address/PSM Foreign address CID State
25498 c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN
25499 Active RFCOMM sessions
25500 L2PCB PCB Flag MTU Out-Q DLCs State
25501 c2afe900 c2b53380 1 127 0 Yes OPEN
25502 Active RFCOMM sockets
25503 PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State
25504 c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN
25506 ----------------------------------------------------------------------
25508 19.4.5 RFCOMM Protocol
25510 The RFCOMM protocol provides emulation of serial ports over the L2CAP
25511 protocol. The protocol is based on the ETSI standard TS 07.10. RFCOMM is a
25512 simple transport protocol, with additional provisions for emulating the 9
25513 circuits of RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol
25514 supports up to 60 simultaneous connections (RFCOMM channels) between two
25517 For the purposes of RFCOMM, a complete communication path involves two
25518 applications running on different devices (the communication endpoints)
25519 with a communication segment between them. RFCOMM is intended to cover
25520 applications that make use of the serial ports of the devices in which
25521 they reside. The communication segment is a Bluetooth link from one device
25522 to another (direct connect).
25524 RFCOMM is only concerned with the connection between the devices in the
25525 direct connect case, or between the device and a modem in the network
25526 case. RFCOMM can support other configurations, such as modules that
25527 communicate via Bluetooth wireless technology on one side and provide a
25528 wired interface on the other side.
25530 In DragonFly the RFCOMM protocol is implemented at the Bluetooth sockets
25533 ----------------------------------------------------------------------
25535 19.4.6 Pairing of Devices
25537 By default, Bluetooth communication is not authenticated, and any device
25538 can talk to any other device. A Bluetooth device (for example, cellular
25539 phone) may choose to require authentication to provide a particular
25540 service (for example, Dial-Up service). Bluetooth authentication is
25541 normally done with PIN codes. A PIN code is an ASCII string up to 16
25542 characters in length. User is required to enter the same PIN code on both
25543 devices. Once user has entered the PIN code, both devices will generate a
25544 link key. After that the link key can be stored either in the devices
25545 themselves or in a persistent storage. Next time both devices will use
25546 previously generated link key. The described above procedure is called
25547 pairing. Note that if the link key is lost by any device then pairing must
25550 The hcsecd(8) daemon is responsible for handling of all Bluetooth
25551 authentication requests. The default configuration file is
25552 /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with
25553 the PIN code arbitrarily set to ``1234'' is shown below.
25556 bdaddr 00:80:37:29:19:a4;
25562 There is no limitation on PIN codes (except length). Some devices (for
25563 example Bluetooth headsets) may have a fixed PIN code built in. The -d
25564 switch forces the hcsecd(8) daemon to stay in the foreground, so it is
25565 easy to see what is happening. Set the remote device to receive pairing
25566 and initiate the Bluetooth connection to the remote device. The remote
25567 device should say that pairing was accepted, and request the PIN code.
25568 Enter the same PIN code as you have in hcsecd.conf. Now your PC and the
25569 remote device are paired. Alternatively, you can initiate pairing on the
25570 remote device. Below in the sample hcsecd output.
25572 hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
25573 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
25574 hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
25575 hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
25576 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
25577 hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
25579 ----------------------------------------------------------------------
25581 19.4.7 Service Discovery Protocol (SDP)
25583 The Service Discovery Protocol (SDP) provides the means for client
25584 applications to discover the existence of services provided by server
25585 applications as well as the attributes of those services. The attributes
25586 of a service include the type or class of service offered and the
25587 mechanism or protocol information needed to utilize the service.
25589 SDP involves communication between a SDP server and a SDP client. The
25590 server maintains a list of service records that describe the
25591 characteristics of services associated with the server. Each service
25592 record contains information about a single service. A client may retrieve
25593 information from a service record maintained by the SDP server by issuing
25594 a SDP request. If the client, or an application associated with the
25595 client, decides to use a service, it must open a separate connection to
25596 the service provider in order to utilize the service. SDP provides a
25597 mechanism for discovering services and their attributes, but it does not
25598 provide a mechanism for utilizing those services.
25600 Normally, a SDP client searches for services based on some desired
25601 characteristics of the services. However, there are times when it is
25602 desirable to discover which types of services are described by an SDP
25603 server's service records without any a priori information about the
25604 services. This process of looking for any offered services is called
25607 The Bluetooth SDP server sdpd(8) and command line client sdpcontrol(8) are
25608 included in the standard DragonFly installation. The following example
25609 shows how to perform a SDP browse query.
25611 % sdpcontrol -a 00:01:03:fc:6e:ec browse
25612 Record Handle: 00000000
25613 Service Class ID List:
25614 Service Discovery Server (0x1000)
25615 Protocol Descriptor List:
25617 Protocol specific parameter #1: u/int/uuid16 1
25618 Protocol specific parameter #2: u/int/uuid16 1
25620 Record Handle: 0x00000001
25621 Service Class ID List:
25622 Browse Group Descriptor (0x1001)
25624 Record Handle: 0x00000002
25625 Service Class ID List:
25626 LAN Access Using PPP (0x1102)
25627 Protocol Descriptor List:
25630 Protocol specific parameter #1: u/int8/bool 1
25631 Bluetooth Profile Descriptor List:
25632 LAN Access Using PPP (0x1102) ver. 1.0
25634 ... and so on. Note that each service has a list of attributes (RFCOMM
25635 channel for example). Depending on the service you might need to make a
25636 note of some of the attributes. Some Bluetooth implementations do not
25637 support service browsing and may return an empty list. In this case it is
25638 possible to search for the specific service. The example below shows how
25639 to search for the OBEX Object Push (OPUSH) service.
25641 % sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH
25643 Offering services on DragonFly to Bluetooth clients is done with the
25648 The local server application that wants to provide Bluetooth service to
25649 the remote clients will register service with the local SDP daemon. The
25650 example of such application is rfcomm_pppd(8). Once started it will
25651 register Bluetooth LAN service with the local SDP daemon.
25653 The list of services registered with the local SDP server can be obtained
25654 by issuing SDP browse query via local control channel.
25656 # sdpcontrol -l browse
25658 ----------------------------------------------------------------------
25660 19.4.8 Dial-Up Networking (DUN) and Network Access with PPP (LAN) Profiles
25662 The Dial-Up Networking (DUN) profile is mostly used with modems and
25663 cellular phones. The scenarios covered by this profile are the following:
25665 * use of a cellular phone or modem by a computer as a wireless modem for
25666 connecting to a dial-up internet access server, or using other dial-up
25669 * use of a cellular phone or modem by a computer to receive data calls.
25671 Network Access with PPP (LAN) profile can be used in the following
25674 * LAN access for a single Bluetooth device;
25676 * LAN access for multiple Bluetooth devices;
25678 * PC to PC (using PPP networking over serial cable emulation).
25680 In DragonFly both profiles are implemented with ppp(8) and rfcomm_pppd(8)
25681 - a wrapper that converts RFCOMM Bluetooth connection into something PPP
25682 can operate with. Before any profile can be used, a new PPP label in the
25683 /etc/ppp/ppp.conf must be created. Consult rfcomm_pppd(8) manual page for
25686 In the following example rfcomm_pppd(8) will be used to open RFCOMM
25687 connection to remote device with BD_ADDR 00:80:37:29:19:a4 on DUN RFCOMM
25688 channel. The actual RFCOMM channel number will be obtained from the remote
25689 device via SDP. It is possible to specify RFCOMM channel by hand, and in
25690 this case rfcomm_pppd(8) will not perform SDP query. Use sdpcontrol(8) to
25691 find out RFCOMM channel on the remote device.
25693 # rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup
25695 In order to provide Network Access with PPP (LAN) service the sdpd(8)
25696 server must be running. A new entry for LAN clients must be created in the
25697 /etc/ppp/ppp.conf file. Consult rfcomm_pppd(8) manual page for examples.
25698 Finally, start RFCOMM PPP server on valid RFCOMM channel number. The
25699 RFCOMM PPP server will automatically register Bluetooth LAN service with
25700 the local SDP daemon. The example below shows how to start RFCOMM PPP
25703 # rfcomm_pppd -s -C 7 -l rfcomm-server
25705 ----------------------------------------------------------------------
25707 19.4.9 OBEX Object Push (OPUSH) Profile
25709 OBEX is a widely used protocol for simple file transfers between mobile
25710 devices. Its main use is in infrared communication, where it is used for
25711 generic file transfers between notebooks or Palm handhelds, and for
25712 sending business cards or calendar entries between cellular phones and
25713 other devices with PIM applications.
25715 The OBEX server and client are implemented as a third-party package
25716 obexapp, which is available as comms/obexapp port.
25718 OBEX client is used to push and/or pull objects from the OBEX server. An
25719 object can, for example, be a business card or an appointment. The OBEX
25720 client can obtain RFCOMM channel number from the remote device via SDP.
25721 This can be done by specifying service name instead of RFCOMM channel
25722 number. Supported service names are: IrMC, FTRN and OPUSH. It is possible
25723 to specify RFCOMM channel as a number. Below is an example of an OBEX
25724 session, where device information object is pulled from the cellular
25725 phone, and a new object (business card) is pushed into the phone's
25728 % obexapp -a 00:80:37:29:19:a4 -C IrMC
25730 get: remote file> telecom/devinfo.txt
25731 get: local file> devinfo-t39.txt
25732 Success, response: OK, Success (0x20)
25734 put: local file> new.vcf
25735 put: remote file> new.vcf
25736 Success, response: OK, Success (0x20)
25738 Success, response: OK, Success (0x20)
25740 In order to provide OBEX Object Push service, sdpd(8) server must be
25741 running. A root folder, where all incoming objects will be stored, must be
25742 created. The default path to the root folder is /var/spool/obex. Finally,
25743 start OBEX server on valid RFCOMM channel number. The OBEX server will
25744 automatically register OBEX Object Push service with the local SDP daemon.
25745 The example below shows how to start OBEX server.
25749 ----------------------------------------------------------------------
25751 19.4.10 Serial Port (SP) Profile
25753 The Serial Port (SP) profile allows Bluetooth device to perform RS232 (or
25754 similar) serial cable emulation. The scenario covered by this profile
25755 deals with legacy applications using Bluetooth as a cable replacement,
25756 through a virtual serial port abstraction.
25758 The rfcomm_sppd(1) utility implements the Serial Port profile. Pseudo tty
25759 is used as a virtual serial port abstraction. The example below shows how
25760 to connect to a remote device Serial Port service. Note that you do not
25761 have to specify RFCOMM channel - rfcomm_sppd(1) can obtain it from the
25762 remote device via SDP. If you would like to override this, specify RFCOMM
25763 channel in the command line.
25765 # rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6
25766 rfcomm_sppd[94692]: Starting on /dev/ttyp6...
25768 Once connected pseudo tty can be used as serial port.
25772 ----------------------------------------------------------------------
25774 19.4.11 Troubleshooting
25776 19.4.11.1 A remote device cannot connect
25778 Some older Bluetooth devices do not support role switching. By default,
25779 when DragonFly is accepting a new connection, it tries to perform role
25780 switch and become a master. Devices, which do not support this will not be
25781 able to connect. Note the role switching is performed when a new
25782 connection is being established, so it is not possible to ask the remote
25783 device if it does support role switching. There is a HCI option to disable
25784 role switching on the local side.
25786 # hccontrol -n ubt0hci write_node_role_switch 0
25788 ----------------------------------------------------------------------
25790 19.4.11.2 Something is going wrong, can I see what exactly is happening?
25792 Yes, you can. Use the hcidump-1.5 third-party package that can be
25793 downloaded from here. The hcidump utility is similar to tcpdump(1). It can
25794 be used to display the content of the Bluetooth packets on the terminal
25795 and to dump the Bluetooth packets to a file.
25797 ----------------------------------------------------------------------
25801 Written by Steve Peterson.
25803 19.5.1 Introduction
25805 It is sometimes useful to divide one physical network (such as an Ethernet
25806 segment) into two separate network segments without having to create IP
25807 subnets and use a router to connect the segments together. A device that
25808 connects two networks together in this fashion is called a ``bridge''. A
25809 DragonFly system with two network interface cards can act as a bridge.
25811 The bridge works by learning the MAC layer addresses (Ethernet addresses)
25812 of the devices on each of its network interfaces. It forwards traffic
25813 between two networks only when its source and destination are on different
25816 In many respects, a bridge is like an Ethernet switch with very few ports.
25818 ----------------------------------------------------------------------
25820 19.5.2 Situations Where Bridging Is Appropriate
25822 There are two common situations in which a bridge is used today.
25824 ----------------------------------------------------------------------
25826 19.5.2.1 High Traffic on a Segment
25828 Situation one is where your physical network segment is overloaded with
25829 traffic, but you do not want for whatever reason to subnet the network and
25830 interconnect the subnets with a router.
25832 Let us consider an example of a newspaper where the Editorial and
25833 Production departments are on the same subnetwork. The Editorial users all
25834 use server A for file service, and the Production users are on server B.
25835 An Ethernet network is used to connect all users together, and high loads
25836 on the network are slowing things down.
25838 If the Editorial users could be segregated on one network segment and the
25839 Production users on another, the two network segments could be connected
25840 with a bridge. Only the network traffic destined for interfaces on the
25841 ``other'' side of the bridge would be sent to the other network, reducing
25842 congestion on each network segment.
25844 ----------------------------------------------------------------------
25846 19.5.2.2 Filtering/Traffic Shaping Firewall
25848 The second common situation is where firewall functionality is needed
25849 without network address translation (NAT).
25851 An example is a small company that is connected via DSL or ISDN to their
25852 ISP. They have a 13 globally-accessible IP addresses from their ISP and
25853 have 10 PCs on their network. In this situation, using a router-based
25854 firewall is difficult because of subnetting issues.
25856 A bridge-based firewall can be configured and dropped into the path just
25857 downstream of their DSL/ISDN router without any IP numbering issues.
25859 ----------------------------------------------------------------------
25861 19.5.3 Configuring a Bridge
25863 19.5.3.1 Network Interface Card Selection
25865 A bridge requires at least two network cards to function. Unfortunately,
25866 not all network interface cards support bridging. Read bridge(4) for
25867 details on the cards that are supported.
25869 Install and test the two network cards before continuing.
25871 ----------------------------------------------------------------------
25873 19.5.3.2 Kernel Configuration Changes
25875 To enable kernel support for bridging, add the:
25879 statement to your kernel configuration file, and rebuild your kernel.
25881 ----------------------------------------------------------------------
25883 19.5.3.3 Firewall Support
25885 If you are planning to use the bridge as a firewall, you will need to add
25886 the IPFIREWALL option as well. Read Section 10.7 for general information
25887 on configuring the bridge as a firewall.
25889 If you need to allow non-IP packets (such as ARP) to flow through the
25890 bridge, there is a firewall option that must be set. This option is
25891 IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this changes the default rule for
25892 the firewall to accept any packet. Make sure you know how this changes the
25893 meaning of your ruleset before you set it.
25895 ----------------------------------------------------------------------
25897 19.5.3.4 Traffic Shaping Support
25899 If you want to use the bridge as a traffic shaper, you will need to add
25900 the DUMMYNET option to your kernel configuration. Read dummynet(4) for
25901 further information.
25903 ----------------------------------------------------------------------
25905 19.5.4 Enabling the Bridge
25909 net.link.ether.bridge=1
25911 to /etc/sysctl.conf to enable the bridge at runtime, and the line:
25913 net.link.ether.bridge_cfg=if1,if2
25915 to enable bridging on the specified interfaces (replace if1 and if2 with
25916 the names of your two network interfaces). If you want the bridged packets
25917 to be filtered by ipfw(8), you should add:
25919 net.link.ether.bridge_ipfw=1
25923 ----------------------------------------------------------------------
25925 19.5.5 Other Information
25927 If you want to be able to telnet(1) into the bridge from the network, it
25928 is correct to assign one of the network cards an IP address. The consensus
25929 is that assigning both cards an address is a bad idea.
25931 If you have multiple bridges on your network, there cannot be more than
25932 one path between any two workstations. Technically, this means that there
25933 is no support for spanning tree link management.
25935 A bridge can add latency to your ping(8) times, especially for traffic
25936 from one segment to another.
25938 ----------------------------------------------------------------------
25942 Reorganized and enhanced by Tom Rhodes. Written by Bill Swingle.
25944 Among the many different filesystems that DragonFly supports is the
25945 Network File System, also known as NFS. NFS allows a system to share
25946 directories and files with others over a network. By using NFS, users and
25947 programs can access files on remote systems almost as if they were local
25950 Some of the most notable benefits that NFS can provide are:
25952 * Local workstations use less disk space because commonly used data can
25953 be stored on a single machine and still remain accessible to others
25956 * There is no need for users to have separate home directories on every
25957 network machine. Home directories could be set up on the NFS server
25958 and made available throughout the network.
25960 * Storage devices such as floppy disks, CDROM drives, and ZIP drives can
25961 be used by other machines on the network. This may reduce the number
25962 of removable media drives throughout the network.
25964 ----------------------------------------------------------------------
25966 19.6.1 How NFS Works
25968 NFS consists of at least two main parts: a server and one or more clients.
25969 The client remotely accesses the data that is stored on the server
25970 machine. In order for this to function properly a few processes have to be
25971 configured and running:
25973 The server has to be running the following daemons:
25976 nfsd The NFS daemon which services requests from the NFS clients.
25977 mountd The NFS mount daemon which carries out the requests that nfsd(8)
25979 portmap The portmapper daemon allows NFS clients to discover which port
25980 the NFS server is using.
25982 The client can also run a daemon, known as nfsiod. The nfsiod daemon
25983 services the requests from the NFS server. This is optional, and improves
25984 performance, but is not required for normal and correct operation. See the
25985 nfsiod(8) manual page for more information.
25987 ----------------------------------------------------------------------
25989 19.6.2 Configuring NFS
25991 NFS configuration is a relatively straightforward process. The processes
25992 that need to be running can all start at boot time with a few
25993 modifications to your /etc/rc.conf file.
25995 On the NFS server, make sure that the following options are configured in
25996 the /etc/rc.conf file:
25998 portmap_enable="YES"
25999 nfs_server_enable="YES"
26002 mountd runs automatically whenever the NFS server is enabled.
26004 On the client, make sure this option is present in /etc/rc.conf:
26006 nfs_client_enable="YES"
26008 The /etc/exports file specifies which filesystems NFS should export
26009 (sometimes referred to as ``share''). Each line in /etc/exports specifies
26010 a filesystem to be exported and which machines have access to that
26011 filesystem. Along with what machines have access to that filesystem,
26012 access options may also be specified. There are many such options that can
26013 be used in this file but only a few will be mentioned here. You can easily
26014 discover other options by reading over the exports(5) manual page.
26016 Here are a few example /etc/exports entries:
26018 The following examples give an idea of how to export filesystems, although
26019 the settings may be different depending on your environment and network
26020 configuration. For instance, to export the /cdrom directory to three
26021 example machines that have the same domain name as the server (hence the
26022 lack of a domain name for each) or have entries in your /etc/hosts file.
26023 The -ro flag makes the exported filesystem read-only. With this flag, the
26024 remote system will not be able to write any changes to the exported
26027 /cdrom -ro host1 host2 host3
26029 The following line exports /home to three hosts by IP address. This is a
26030 useful setup if you have a private network without a DNS server
26031 configured. Optionally the /etc/hosts file could be configured for
26032 internal hostnames; please review hosts(5) for more information. The
26033 -alldirs flag allows the subdirectories to be mount points. In other
26034 words, it will not mount the subdirectories but permit the client to mount
26035 only the directories that are required or needed.
26037 /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4
26039 The following line exports /a so that two clients from different domains
26040 may access the filesystem. The -maproot=root flag allows the root user on
26041 the remote system to write data on the exported filesystem as root. If the
26042 -maproot=root flag is not specified, then even if a user has root access
26043 on the remote system, they will not be able to modify files on the
26044 exported filesystem.
26046 /a -maproot=root host.example.com box.example.org
26048 In order for a client to access an exported filesystem, the client must
26049 have permission to do so. Make sure the client is listed in your
26052 In /etc/exports, each line represents the export information for one
26053 filesystem to one host. A remote host can only be specified once per
26054 filesystem, and may only have one default entry. For example, assume that
26055 /usr is a single filesystem. The following /etc/exports would be invalid:
26060 One filesystem, /usr, has two lines specifying exports to the same host,
26061 client. The correct format for this situation is:
26063 /usr/src /usr/ports client
26065 The properties of one filesystem exported to a given host must all occur
26066 on one line. Lines without a client specified are treated as a single
26067 host. This limits how you can export filesystems, but for most people this
26070 The following is an example of a valid export list, where /usr and
26071 /exports are local filesystems:
26073 # Export src and ports to client01 and client02, but only
26074 # client01 has root privileges on it
26075 /usr/src /usr/ports -maproot=root client01
26076 /usr/src /usr/ports client02
26077 # The client machines have root and can mount anywhere
26078 # on /exports. Anyone in the world can mount /exports/obj read-only
26079 /exports -alldirs -maproot=root client01 client02
26082 You must restart mountd whenever you modify /etc/exports so the changes
26083 can take effect. This can be accomplished by sending the HUP signal to the
26086 # kill -HUP `cat /var/run/mountd.pid`
26088 Alternatively, a reboot will make DragonFly set everything up properly. A
26089 reboot is not necessary though. Executing the following commands as root
26090 should start everything up.
26102 Now everything should be ready to actually mount a remote file system. In
26103 these examples the server's name will be server and the client's name will
26104 be client. If you only want to temporarily mount a remote filesystem or
26105 would rather test the configuration, just execute a command like this as
26106 root on the client:
26108 # mount server:/home /mnt
26110 This will mount the /home directory on the server at /mnt on the client.
26111 If everything is set up correctly you should be able to enter /mnt on the
26112 client and see all the files that are on the server.
26114 If you want to automatically mount a remote filesystem each time the
26115 computer boots, add the filesystem to the /etc/fstab file. Here is an
26118 server:/home /mnt nfs rw 0 0
26120 The fstab(5) manual page lists all the available options.
26122 ----------------------------------------------------------------------
26124 19.6.3 Practical Uses
26126 NFS has many practical uses. Some of the more common ones are listed
26129 * Set several machines to share a CDROM or other media among them. This
26130 is cheaper and often a more convenient method to install software on
26133 * On large networks, it might be more convenient to configure a central
26134 NFS server in which to store all the user home directories. These home
26135 directories can then be exported to the network so that users would
26136 always have the same home directory, regardless of which workstation
26139 * Several machines could have a common /usr/ports/distfiles directory.
26140 That way, when you need to install a port on several machines, you can
26141 quickly access the source without downloading it on each machine.
26143 ----------------------------------------------------------------------
26145 19.6.4 Automatic Mounts with amd
26147 Contributed by Wylie Stilwell. Rewritten by Chern Lee.
26149 amd(8) (the automatic mounter daemon) automatically mounts a remote
26150 filesystem whenever a file or directory within that filesystem is
26151 accessed. Filesystems that are inactive for a period of time will also be
26152 automatically unmounted by amd. Using amd provides a simple alternative to
26153 permanent mounts, as permanent mounts are usually listed in /etc/fstab.
26155 amd operates by attaching itself as an NFS server to the /host and /net
26156 directories. When a file is accessed within one of these directories, amd
26157 looks up the corresponding remote mount and automatically mounts it. /net
26158 is used to mount an exported filesystem from an IP address, while /host is
26159 used to mount an export from a remote hostname.
26161 An access to a file within /host/foobar/usr would tell amd to attempt to
26162 mount the /usr export on the host foobar.
26164 Example 19-1. Mounting an Export with amd
26166 You can view the available mounts of a remote host with the showmount
26167 command. For example, to view the mounts of a host named foobar, you can
26170 % showmount -e foobar
26171 Exports list on foobar:
26174 % cd /host/foobar/usr
26176 As seen in the example, the showmount shows /usr as an export. When
26177 changing directories to /host/foobar/usr, amd attempts to resolve the
26178 hostname foobar and automatically mount the desired export.
26180 amd can be started by the startup scripts by placing the following lines
26185 Additionally, custom flags can be passed to amd from the amd_flags option.
26186 By default, amd_flags is set to:
26188 amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"
26190 The /etc/amd.map file defines the default options that exports are mounted
26191 with. The /etc/amd.conf file defines some of the more advanced features of
26194 Consult the amd(8) and amd.conf(5) manual pages for more information.
26196 ----------------------------------------------------------------------
26198 19.6.5 Problems Integrating with Other Systems
26200 Contributed by John Lind.
26202 Certain Ethernet adapters for ISA PC systems have limitations which can
26203 lead to serious network problems, particularly with NFS. This difficulty
26204 is not specific to DragonFly, but DragonFly systems are affected by it.
26206 The problem nearly always occurs when (DragonFly) PC systems are networked
26207 with high-performance workstations, such as those made by Silicon
26208 Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will work fine,
26209 and some operations may succeed, but suddenly the server will seem to
26210 become unresponsive to the client, even though requests to and from other
26211 systems continue to be processed. This happens to the client system,
26212 whether the client is the DragonFly system or the workstation. On many
26213 systems, there is no way to shut down the client gracefully once this
26214 problem has manifested itself. The only solution is often to reset the
26215 client, because the NFS situation cannot be resolved.
26217 Though the ``correct'' solution is to get a higher performance and
26218 capacity Ethernet adapter for the DragonFly system, there is a simple
26219 workaround that will allow satisfactory operation. If the DragonFly system
26220 is the server, include the option -w=1024 on the mount from the client. If
26221 the DragonFly system is the client, then mount the NFS filesystem with the
26222 option -r=1024. These options may be specified using the fourth field of
26223 the fstab entry on the client for automatic mounts, or by using the -o
26224 parameter of the mount(8) command for manual mounts.
26226 It should be noted that there is a different problem, sometimes mistaken
26227 for this one, when the NFS servers and clients are on different networks.
26228 If that is the case, make certain that your routers are routing the
26229 necessary UDP information, or you will not get anywhere, no matter what
26230 else you are doing.
26232 In the following examples, fastws is the host (interface) name of a
26233 high-performance workstation, and freebox is the host (interface) name of
26234 a DragonFly system with a lower-performance Ethernet adapter. Also,
26235 /sharedfs will be the exported NFS filesystem (see exports(5)), and
26236 /project will be the mount point on the client for the exported
26237 filesystem. In all cases, note that additional options, such as hard or
26238 soft and bg may be desirable in your application.
26240 Examples for the DragonFly system (freebox) as the client in /etc/fstab on
26243 fastws:/sharedfs /project nfs rw,-r=1024 0 0
26245 As a manual mount command on freebox:
26247 # mount -t nfs -o -r=1024 fastws:/sharedfs /project
26249 Examples for the DragonFly system as the server in /etc/fstab on fastws:
26251 freebox:/sharedfs /project nfs rw,-w=1024 0 0
26253 As a manual mount command on fastws:
26255 # mount -t nfs -o -w=1024 freebox:/sharedfs /project
26257 Nearly any 16-bit Ethernet adapter will allow operation without the above
26258 restrictions on the read or write size.
26260 For anyone who cares, here is what happens when the failure occurs, which
26261 also explains why it is unrecoverable. NFS typically works with a
26262 ``block'' size of 8 k (though it may do fragments of smaller sizes). Since
26263 the maximum Ethernet packet is around 1500 bytes, the NFS ``block'' gets
26264 split into multiple Ethernet packets, even though it is still a single
26265 unit to the upper-level code, and must be received, assembled, and
26266 acknowledged as a unit. The high-performance workstations can pump out the
26267 packets which comprise the NFS unit one right after the other, just as
26268 close together as the standard allows. On the smaller, lower capacity
26269 cards, the later packets overrun the earlier packets of the same unit
26270 before they can be transferred to the host and the unit as a whole cannot
26271 be reconstructed or acknowledged. As a result, the workstation will time
26272 out and try again, but it will try again with the entire 8 K unit, and the
26273 process will be repeated, ad infinitum.
26275 By keeping the unit size below the Ethernet packet size limitation, we
26276 ensure that any complete Ethernet packet received can be acknowledged
26277 individually, avoiding the deadlock situation.
26279 Overruns may still occur when a high-performance workstations is slamming
26280 data out to a PC system, but with the better cards, such overruns are not
26281 guaranteed on NFS ``units''. When an overrun occurs, the units affected
26282 will be retransmitted, and there will be a fair chance that they will be
26283 received, assembled, and acknowledged.
26285 ----------------------------------------------------------------------
26287 19.7 Diskless Operation
26289 Updated by Jean-Franc,ois Dockes. Reorganized and enhanced by Alex Dupre.
26291 A DragonFly machine can boot over the network and operate without a local
26292 disk, using filesystems mounted from an NFS server. No system modification
26293 is necessary, beyond standard configuration files. Such a system is
26294 relatively easy to set up because all the necessary elements are readily
26297 * There are at least two possible methods to load the kernel over the
26300 * PXE: The Intel Preboot Execution Environment system is a form of
26301 smart boot ROM built into some networking cards or motherboards.
26302 See pxeboot(8) for more details.
26304 * The etherboot port (net/etherboot) produces ROM-able code to boot
26305 kernels over the network. The code can be either burnt into a
26306 boot PROM on a network card, or loaded from a local floppy (or
26307 hard) disk drive, or from a running MS-DOS system. Many network
26308 cards are supported.
26310 * A sample script (/usr/share/examples/diskless/clone_root) eases the
26311 creation and maintenance of the workstation's root filesystem on the
26312 server. The script will probably require a little customization but it
26313 will get you started very quickly.
26315 * Standard system startup files exist in /etc to detect and support a
26316 diskless system startup.
26318 * Swapping, if needed, can be done either to an NFS file or to a local
26321 There are many ways to set up diskless workstations. Many elements are
26322 involved, and most can be customized to suit local taste. The following
26323 will describe variations on the setup of a complete system, emphasizing
26324 simplicity and compatibility with the standard DragonFly startup scripts.
26325 The system described has the following characteristics:
26327 * The diskless workstations use a shared read-only root filesystem, and
26328 a shared read-only /usr.
26330 The root filesystem is a copy of a standard DragonFly root (typically
26331 the server's), with some configuration files overridden by ones
26332 specific to diskless operation or, possibly, to the workstation they
26335 The parts of the root which have to be writable are overlaid with
26336 mfs(8) filesystems. Any changes will be lost when the system reboots.
26338 * The kernel is transferred and loaded either with etherboot or PXE as
26339 some situations may mandate the use of either method.
26341 Caution: As described, this system is insecure. It should live in a
26342 protected area of a network, and be untrusted by other hosts.
26344 ----------------------------------------------------------------------
26346 19.7.1 Background Information
26348 Setting up diskless workstations is both relatively straightforward and
26349 prone to errors. These are sometimes difficult to diagnose for a number of
26350 reasons. For example:
26352 * Compile time options may determine different behaviours at runtime.
26354 * Error messages are often cryptic or totally absent.
26356 In this context, having some knowledge of the background mechanisms
26357 involved is very useful to solve the problems that may arise.
26359 Several operations need to be performed for a successful bootstrap:
26361 * The machine needs to obtain initial parameters such as its IP address,
26362 executable filename, server name, root path. This is done using the
26363 DHCP or BOOTP protocols. DHCP is a compatible extension of BOOTP, and
26364 uses the same port numbers and basic packet format.
26366 It is possible to configure a system to use only BOOTP. The bootpd(8)
26367 server program is included in the base DragonFly system.
26369 However, DHCP has a number of advantages over BOOTP (nicer
26370 configuration files, possibility of using PXE, plus many others not
26371 directly related to diskless operation), and we will describe mainly a
26372 DHCP configuration, with equivalent exemples using bootpd(8) when
26373 possible. The sample configuration will use the ISC DHCP software
26374 package (release 3.0.1.r12 was installed on the test server).
26376 * The machine needs to transfer one or several programs to local memory.
26377 Either TFTP or NFS are used. The choice between TFTP and NFS is a
26378 compile time option in several places. A common source of error is to
26379 specify filenames for the wrong protocol: TFTP typically transfers all
26380 files from a single directory on the server, and would expect
26381 filenames relative to this directory. NFS needs absolute file paths.
26383 * The possible intermediate bootstrap programs and the kernel need to be
26384 initialized and executed. There are several important variations in
26387 * PXE will load pxeboot(8), which is a modified version of the
26388 DragonFly third stage loader. The loader(8) will obtain most
26389 parameters necessary to system startup, and leave them in the
26390 kernel environment before transferring control. It is possible to
26391 use a GENERIC kernel in this case.
26393 * etherboot, will directly load the kernel, with less preparation.
26394 You will need to build a kernel with specific options.
26396 * Finally, the machine needs to access its filesystems. NFS is used in
26399 See also diskless(8) manual page.
26401 ----------------------------------------------------------------------
26403 19.7.2 Setup Instructions
26405 19.7.2.1 Configuration Using ISC DHCP
26407 The ISC DHCP server can answer both BOOTP and DHCP requests.
26409 ISC DHCP needs a configuration file to run, (normally named
26410 /usr/local/etc/dhcpd.conf). Here follows a commented example, where host
26411 margaux uses etherboot and host corbieres uses PXE:
26413 default-lease-time 600;
26414 max-lease-time 7200;
26417 option domain-name "example.com";
26418 option domain-name-servers 192.168.4.1;
26419 option routers 192.168.4.1;
26421 subnet 192.168.4.0 netmask 255.255.255.0 {
26422 use-host-decl-names on; (1)
26423 option subnet-mask 255.255.255.0;
26424 option broadcast-address 192.168.4.255;
26427 hardware ethernet 01:23:45:67:89:ab;
26428 fixed-address margaux.example.com;
26429 next-server 192.168.4.4; (2)
26430 filename "/data/misc/kernel.diskless"; (3)
26431 option root-path "192.168.4.4:/data/misc/diskless"; (4)
26434 hardware ethernet 00:02:b3:27:62:df;
26435 fixed-address corbieres.example.com;
26436 next-server 192.168.4.4;
26437 filename "pxeboot";
26438 option root-path "192.168.4.4:/data/misc/diskless";
26444 This option tells dhcpd to send the value in the host declarations
26445 as the hostname for the diskless host. An alternate way would be
26446 to add an option host-name margaux inside the host declarations.
26448 The next-server directive designates the TFTP or NFS server to use
26449 for loading loader or kernel file (the default is to use the same
26450 host as the DHCP server).
26452 The filename directive defines the file that etherboot or PXE will
26453 load for the next execution step. It must be specified according
26454 to the transfer method used. etherboot can be compiled to use NFS
26455 or TFTP. The DragonFly port configures NFS by default. PXE uses
26456 TFTP, which is why a relative filename is used here (this may
26457 depend on the TFTP server configuration, but would be fairly
26458 typical). Also, PXE loads pxeboot, not the kernel. There are other
26459 interesting possibilities, like loading pxeboot from a DragonFly
26460 CD-ROM /boot directory (as pxeboot(8) can load a GENERIC kernel,
26461 this makes it possible to use PXE to boot from a remote CD-ROM).
26463 The root-path option defines the path to the root filesystem, in
26464 usual NFS notation. When using PXE, it is possible to leave off
26465 the host's IP as long as you do not enable the kernel option
26466 BOOTP. The NFS server will then be the same as the TFTP one.
26468 ----------------------------------------------------------------------
26470 19.7.2.2 Configuration Using BOOTP
26472 Here follows an equivalent bootpd configuration (reduced to one client).
26473 This would be found in /etc/bootptab.
26475 Please note that etherboot must be compiled with the non-default option
26476 NO_DHCP_SUPPORT in order to use BOOTP, and that PXE needs DHCP. The only
26477 obvious advantage of bootpd is that it exists in the base system.
26480 :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
26481 :sm=255.255.255.0:\
26485 :bf="/kernel.diskless":\
26486 :rp="192.168.4.4:/data/misc/diskless":
26488 margaux:ha=0123456789ab:tc=.def100
26491 ----------------------------------------------------------------------
26493 19.7.2.3 Booting with PXE
26495 By default, the pxeboot(8) loader loads the kernel via NFS. It can be
26496 compiled to use TFTP instead by specifying the LOADER_TFTP_SUPPORT option
26497 in /etc/make.conf. See the comments in /etc/defaults/make.conf (or
26498 /usr/share/examples/etc/make.conf for 5.X systems) for instructions.
26500 There are two other undocumented make.conf options which may be useful for
26501 setting up a serial console diskless machine: BOOT_PXELDR_PROBE_KEYBOARD,
26502 and BOOT_PXELDR_ALWAYS_SERIAL.
26504 To use PXE when the machine starts, you will usually need to select the
26505 Boot from network option in your BIOS setup, or type a function key during
26506 the PC initialization.
26508 ----------------------------------------------------------------------
26510 19.7.2.4 Configuring the TFTP and NFS Servers
26512 If you are using PXE or etherboot configured to use TFTP, you need to
26513 enable tftpd on the file server:
26515 1. Create a directory from which tftpd will serve the files, e.g.
26518 2. Add this line to your /etc/inetd.conf:
26520 tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot
26522 Note: It appears that at least some PXE versions want the TCP
26523 version of TFTP. In this case, add a second line, replacing dgram
26524 udp with stream tcp.
26526 3. Tell inetd to reread its configuration file:
26528 # kill -HUP `cat /var/run/inetd.pid`
26530 You can place the tftpboot directory anywhere on the server. Make sure
26531 that the location is set in both inetd.conf and dhcpd.conf.
26533 In all cases, you also need to enable NFS and export the appropriate
26534 filesystem on the NFS server.
26536 1. Add this to /etc/rc.conf:
26538 nfs_server_enable="YES"
26540 2. Export the filesystem where the diskless root directory is located by
26541 adding the following to /etc/exports (adjust the volume mount point
26542 and replace margaux corbieres with the names of the diskless
26545 /data/misc -alldirs -ro margaux corbieres
26547 3. Tell mountd to reread its configuration file. If you actually needed
26548 to enable NFS in /etc/rc.conf at the first step, you probably want to
26551 # kill -HUP `cat /var/run/mountd.pid`
26553 ----------------------------------------------------------------------
26555 19.7.2.5 Building a Diskless Kernel
26557 If using etherboot, you need to create a kernel configuration file for the
26558 diskless client with the following options (in addition to the usual
26561 options BOOTP # Use BOOTP to obtain IP address/hostname
26562 options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
26565 You may also want to use BOOTP_NFSV3, BOOT_COMPAT and BOOTP_WIRED_TO
26568 These option names are historical and slightly misleading as they actually
26569 enable indifferent use of DHCP and BOOTP inside the kernel (it is also
26570 possible to force strict BOOTP or DHCP use).
26572 Build the kernel (see Chapter 9), and copy it to the place specified in
26575 Note: When using PXE, building a kernel with the above options is not
26576 strictly necessary (though suggested). Enabling them will cause more
26577 DHCP requests to be issued during kernel startup, with a small risk of
26578 inconsistency between the new values and those retrieved by pxeboot(8)
26579 in some special cases. The advantage of using them is that the host name
26580 will be set as a side effect. Otherwise you will need to set the host
26581 name by another method, for example in a client-specific rc.conf file.
26583 ----------------------------------------------------------------------
26585 19.7.2.6 Preparing the Root Filesystem
26587 You need to create a root filesystem for the diskless workstations, in the
26588 location listed as root-path in dhcpd.conf. The following sections
26589 describe two ways to do it.
26591 ----------------------------------------------------------------------
26593 19.7.2.6.1 Using the clone_root Script
26595 This is the quickest way to create a root filesystem. but This shell
26596 script is located at /usr/share/examples/diskless/clone_root and needs
26597 customization, at least to adjust the place where the filesystem will be
26598 created (the DEST variable).
26600 Refer to the comments at the top of the script for instructions. They
26601 explain how the base filesystem is built, and how files may be selectively
26602 overridden by versions specific to diskless operation, to a subnetwork, or
26603 to an individual workstation. They also give examples for the diskless
26604 /etc/fstab and /etc/rc.conf files.
26606 The README files in /usr/share/examples/diskless contain a lot of
26607 interesting background information, but, together with the other examples
26608 in the diskless directory, they actually document a configuration method
26609 which is distinct from the one used by clone_root and the system startup
26610 scripts in /etc, which is a little confusing. Use them for reference only,
26611 except if you prefer the method that they describe, in which case you will
26612 need customized rc scripts.
26614 ----------------------------------------------------------------------
26616 19.7.2.6.2 Using the Standard make world Procedure
26618 This method will install a complete virgin system (not only the root
26619 filesystem) into DESTDIR. All you have to do is simply execute the
26623 export DESTDIR=/data/misc/diskless
26624 mkdir -p ${DESTDIR}
26625 cd /usr/src; make world && make kernel
26626 cd /usr/src/etc; make distribution
26628 Once done, you may need to customize your /etc/rc.conf and /etc/fstab
26629 placed into DESTDIR according to your needs.
26631 ----------------------------------------------------------------------
26633 19.7.2.7 Configuring Swap
26635 If needed, a swap file located on the server can be accessed via NFS.
26637 ----------------------------------------------------------------------
26639 19.7.2.7.1 NFS Swap with DragonFly
26641 The swap file location and size can be specified with BOOTP/DHCP
26642 DragonFly-specific options 128 and 129. Examples of configuration files
26643 for ISC DHCP 3.0 or bootpd follow:
26645 1. Add the following lines to dhcpd.conf:
26648 option swap-path code 128 = string;
26649 option swap-size code 129 = integer 32;
26652 ... # Standard lines, see above
26653 option swap-path "192.168.4.4:/netswapvolume/netswap";
26654 option swap-size 64000;
26658 swap-path is the path to a directory where swap files will be located.
26659 Each file will be named swap.client-ip.
26661 Older versions of dhcpd used a syntax of option option-128 "..., which
26662 is no longer supported.
26664 /etc/bootptab would use the following syntax instead:
26666 T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00
26668 Note: In /etc/bootptab, the swap size must be expressed in
26669 hexadecimal format.
26671 2. On the NFS swap file server, create the swap file(s)
26673 # mkdir /netswapvolume/netswap
26674 # cd /netswapvolume/netswap
26675 # dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6
26676 # chmod 0600 swap.192.168.4.6
26679 192.168.4.6 is the IP address for the diskless client.
26681 3. On the NFS swap file server, add the following line to /etc/exports:
26683 /netswapvolume -maproot=0:10 -alldirs margaux corbieres
26686 Then tell mountd to reread the exports file, as above.
26688 ----------------------------------------------------------------------
26690 19.7.2.8 Miscellaneous Issues
26692 19.7.2.8.1 Running with a Read-only /usr
26694 If the diskless workstation is configured to run X, you will have to
26695 adjust the xdm configuration file, which puts the error log on /usr by
26698 ----------------------------------------------------------------------
26700 19.7.2.8.2 Using a Non-DragonFly Server
26702 When the server for the root filesystem is not running DragonFly, you will
26703 have to create the root filesystem on a DragonFly machine, then copy it to
26704 its destination, using tar or cpio.
26706 In this situation, there are sometimes problems with the special files in
26707 /dev, due to differing major/minor integer sizes. A solution to this
26708 problem is to export a directory from the non-DragonFly server, mount this
26709 directory onto a DragonFly machine, and run MAKEDEV on the DragonFly
26710 machine to create the correct device entries.
26712 ----------------------------------------------------------------------
26716 A good resource for information on ISDN technology and hardware is Dan
26719 A quick simple road map to ISDN follows:
26721 * If you live in Europe you might want to investigate the ISDN card
26724 * If you are planning to use ISDN primarily to connect to the Internet
26725 with an Internet Provider on a dial-up non-dedicated basis, you might
26726 look into Terminal Adapters. This will give you the most flexibility,
26727 with the fewest problems, if you change providers.
26729 * If you are connecting two LANs together, or connecting to the Internet
26730 with a dedicated ISDN connection, you might consider the stand alone
26731 router/bridge option.
26733 Cost is a significant factor in determining what solution you will choose.
26734 The following options are listed from least expensive to most expensive.
26736 ----------------------------------------------------------------------
26740 Contributed by Hellmuth Michaelis.
26742 DragonFly's ISDN implementation supports only the DSS1/Q.931 (or
26743 Euro-ISDN) standard using passive cards. Some active cards are supported
26744 where the firmware also supports other signaling protocols; this also
26745 includes the first supported Primary Rate (PRI) ISDN card.
26747 The isdn4bsd software allows you to connect to other ISDN routers using
26748 either IP over raw HDLC or by using synchronous PPP: either by using
26749 kernel PPP with isppp, a modified sppp(4) driver, or by using userland
26750 ppp(8). By using userland ppp(8), channel bonding of two or more ISDN
26751 B-channels is possible. A telephone answering machine application is also
26752 available as well as many utilities such as a software 300 Baud modem.
26754 Some growing number of PC ISDN cards are supported under DragonFly and the
26755 reports show that it is successfully used all over Europe and in many
26756 other parts of the world.
26758 The passive ISDN cards supported are mostly the ones with the Infineon
26759 (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, but also ISDN cards with
26760 chips from Cologne Chip (ISA bus only), PCI cards with Winbond W6692
26761 chips, some cards with the Tiger300/320/ISAC chipset combinations and some
26762 vendor specific chipset based cards such as the AVM Fritz!Card PCI V.1.0
26763 and the AVM Fritz!Card PnP.
26765 Currently the active supported ISDN cards are the AVM B1 (ISA and PCI) BRI
26766 cards and the AVM T1 PCI PRI cards.
26768 For documentation on isdn4bsd, have a look at /usr/share/examples/isdn/
26769 directory on your DragonFly system or at the homepage of isdn4bsd which
26770 also has pointers to hints, erratas and much more documentation such as
26771 the isdn4bsd handbook.
26773 For questions regarding the installation, configuration and
26774 troubleshooting isdn4bsd, a freebsd-isdn mailing list is available.
26776 ----------------------------------------------------------------------
26778 19.8.2 ISDN Terminal Adapters
26780 Terminal adapters (TA), are to ISDN what modems are to regular phone
26783 Most TA's use the standard Hayes modem AT command set, and can be used as
26784 a drop in replacement for a modem.
26786 A TA will operate basically the same as a modem except connection and
26787 throughput speeds will be much faster than your old modem. You will need
26788 to configure PPP exactly the same as for a modem setup. Make sure you set
26789 your serial speed as high as possible.
26791 The main advantage of using a TA to connect to an Internet Provider is
26792 that you can do Dynamic PPP. As IP address space becomes more and more
26793 scarce, most providers are not willing to provide you with a static IP
26794 anymore. Most stand-alone routers are not able to accommodate dynamic IP
26797 TA's completely rely on the PPP daemon that you are running for their
26798 features and stability of connection. This allows you to upgrade easily
26799 from using a modem to ISDN on a DragonFly machine, if you already have PPP
26800 set up. However, at the same time any problems you experienced with the
26801 PPP program and are going to persist.
26803 If you want maximum stability, use the kernel PPP option, not the userland
26806 The following TA's are known to work with DragonFly:
26808 * Motorola BitSurfer and Bitsurfer Pro
26812 Most other TA's will probably work as well, TA vendors try to make sure
26813 their product can accept most of the standard modem AT command set.
26815 The real problem with external TA's is that, like modems, you need a good
26816 serial card in your computer.
26818 You should read the DragonFly Serial Hardware tutorial for a detailed
26819 understanding of serial devices, and the differences between asynchronous
26820 and synchronous serial ports.
26822 A TA running off a standard PC serial port (asynchronous) limits you to
26823 115.2 Kbs, even though you have a 128 Kbs connection. To fully utilize the
26824 128 Kbs that ISDN is capable of, you must move the TA to a synchronous
26827 Do not be fooled into buying an internal TA and thinking you have avoided
26828 the synchronous/asynchronous issue. Internal TA's simply have a standard
26829 PC serial port chip built into them. All this will do is save you having
26830 to buy another serial cable and find another empty electrical socket.
26832 A synchronous card with a TA is at least as fast as a stand-alone router,
26833 and with a simple 386 DragonFly box driving it, probably more flexible.
26835 The choice of synchronous card/TA v.s. stand-alone router is largely a
26836 religious issue. There has been some discussion of this in the mailing
26837 lists. We suggest you search the archives for the complete discussion.
26839 ----------------------------------------------------------------------
26841 19.8.3 Stand-alone ISDN Bridges/Routers
26843 ISDN bridges or routers are not at all specific to DragonFly or any other
26844 operating system. For a more complete description of routing and bridging
26845 technology, please refer to a networking reference book.
26847 In the context of this section, the terms router and bridge will be used
26850 As the cost of low end ISDN routers/bridges comes down, it will likely
26851 become a more and more popular choice. An ISDN router is a small box that
26852 plugs directly into your local Ethernet network, and manages its own
26853 connection to the other bridge/router. It has built in software to
26854 communicate via PPP and other popular protocols.
26856 A router will allow you much faster throughput than a standard TA, since
26857 it will be using a full synchronous ISDN connection.
26859 The main problem with ISDN routers and bridges is that interoperability
26860 between manufacturers can still be a problem. If you are planning to
26861 connect to an Internet provider, you should discuss your needs with them.
26863 If you are planning to connect two LAN segments together, such as your
26864 home LAN to the office LAN, this is the simplest lowest maintenance
26865 solution. Since you are buying the equipment for both sides of the
26866 connection you can be assured that the link will work.
26868 For example to connect a home computer or branch office network to a head
26869 office network the following setup could be used:
26871 Example 19-2. Branch Office or Home Network
26873 Network uses a bus based topology with 10 base 2 Ethernet (``thinnet'').
26874 Connect router to network cable with AUI/10BT transceiver, if necessary.
26886 If your home/branch office is only one computer you can use a twisted pair
26887 crossover cable to connect to the stand-alone router directly.
26889 Example 19-3. Head Office or Other LAN
26891 Network uses a star topology with 10 base T Ethernet (``Twisted Pair'').
26893 -------Novell Server
26901 |___---Stand-alone router
26905 One large advantage of most routers/bridges is that they allow you to have
26906 two separate independent PPP connections to two separate sites at the same
26907 time. This is not supported on most TA's, except for specific (usually
26908 expensive) models that have two serial ports. Do not confuse this with
26909 channel bonding, MPP, etc.
26911 This can be a very useful feature if, for example, you have an dedicated
26912 ISDN connection at your office and would like to tap into it, but do not
26913 want to get another ISDN line at work. A router at the office location can
26914 manage a dedicated B channel connection (64 Kbps) to the Internet and use
26915 the other B channel for a separate data connection. The second B channel
26916 can be used for dial-in, dial-out or dynamically bonding (MPP, etc.) with
26917 the first B channel for more bandwidth.
26919 An Ethernet bridge will also allow you to transmit more than just IP
26920 traffic. You can also send IPX/SPX or whatever other protocols you use.
26922 ----------------------------------------------------------------------
26926 Written by Bill Swingle. Enhanced by Eric Ogren and Udo Erdelhoff.
26930 NIS, which stands for Network Information Services, was developed by Sun
26931 Microsystems to centralize administration of UNIX (originally SunOS)
26932 systems. It has now essentially become an industry standard; all major
26933 UNIX like systems (Solaris, HP-UX, AIX(R), Linux, NetBSD, OpenBSD,
26934 FreeBSD, DragonFly, etc.) support NIS.
26936 NIS was formerly known as Yellow Pages, but because of trademark issues,
26937 Sun changed the name. The old term (and yp) is still often seen and used.
26939 It is a RPC-based client/server system that allows a group of machines
26940 within an NIS domain to share a common set of configuration files. This
26941 permits a system administrator to set up NIS client systems with only
26942 minimal configuration data and add, remove or modify configuration data
26943 from a single location.
26945 It is similar to the Windows NT(R) domain system; although the internal
26946 implementation of the two are not at all similar, the basic functionality
26949 ----------------------------------------------------------------------
26951 19.9.2 Terms/Processes You Should Know
26953 There are several terms and several important user processes that you will
26954 come across when attempting to implement NIS on DragonFly, whether you are
26955 trying to create an NIS server or act as an NIS client:
26957 +------------------------------------------------------------------------+
26958 | Term | Description |
26959 |----------------+-------------------------------------------------------|
26960 | | An NIS master server and all of its clients |
26961 | NIS domainname | (including its slave servers) have a NIS domainname. |
26962 | | Similar to an Windows NT domain name, the NIS |
26963 | | domainname does not have anything to do with DNS. |
26964 |----------------+-------------------------------------------------------|
26965 | | Must be running in order to enable RPC (Remote |
26966 | portmap | Procedure Call, a network protocol used by NIS). If |
26967 | | portmap is not running, it will be impossible to run |
26968 | | an NIS server, or to act as an NIS client. |
26969 |----------------+-------------------------------------------------------|
26970 | | ``Binds'' an NIS client to its NIS server. It will |
26971 | | take the NIS domainname from the system, and using |
26972 | ypbind | RPC, connect to the server. ypbind is the core of |
26973 | | client-server communication in an NIS environment; if |
26974 | | ypbind dies on a client machine, it will not be able |
26975 | | to access the NIS server. |
26976 |----------------+-------------------------------------------------------|
26977 | | Should only be running on NIS servers; this is the |
26978 | | NIS server process itself. If ypserv(8) dies, then |
26979 | | the server will no longer be able to respond to NIS |
26980 | | requests (hopefully, there is a slave server to take |
26981 | ypserv | over for it). There are some implementations of NIS |
26982 | | (but not the DragonFly one), that do not try to |
26983 | | reconnect to another server if the server it used |
26984 | | before dies. Often, the only thing that helps in this |
26985 | | case is to restart the server process (or even the |
26986 | | whole server) or the ypbind process on the client. |
26987 |----------------+-------------------------------------------------------|
26988 | | Another process that should only be running on NIS |
26989 | | master servers; this is a daemon that will allow NIS |
26990 | rpc.yppasswdd | clients to change their NIS passwords. If this daemon |
26991 | | is not running, users will have to login to the NIS |
26992 | | master server and change their passwords there. |
26993 +------------------------------------------------------------------------+
26995 ----------------------------------------------------------------------
26997 19.9.3 How Does It Work?
26999 There are three types of hosts in an NIS environment: master servers,
27000 slave servers, and clients. Servers act as a central repository for host
27001 configuration information. Master servers hold the authoritative copy of
27002 this information, while slave servers mirror this information for
27003 redundancy. Clients rely on the servers to provide this information to
27006 Information in many files can be shared in this manner. The master.passwd,
27007 group, and hosts files are commonly shared via NIS. Whenever a process on
27008 a client needs information that would normally be found in these files
27009 locally, it makes a query to the NIS server that it is bound to instead.
27011 ----------------------------------------------------------------------
27013 19.9.3.1 Machine Types
27015 * A NIS master server. This server, analogous to a Windows NT primary
27016 domain controller, maintains the files used by all of the NIS clients.
27017 The passwd, group, and other various files used by the NIS clients
27018 live on the master server.
27020 Note: It is possible for one machine to be an NIS master server for
27021 more than one NIS domain. However, this will not be covered in this
27022 introduction, which assumes a relatively small-scale NIS
27025 * NIS slave servers. Similar to the Windows NT backup domain
27026 controllers, NIS slave servers maintain copies of the NIS master's
27027 data files. NIS slave servers provide the redundancy, which is needed
27028 in important environments. They also help to balance the load of the
27029 master server: NIS Clients always attach to the NIS server whose
27030 response they get first, and this includes slave-server-replies.
27032 * NIS clients. NIS clients, like most Windows NT workstations,
27033 authenticate against the NIS server (or the Windows NT domain
27034 controller in the Windows NT Workstation case) to log on.
27036 ----------------------------------------------------------------------
27038 19.9.4 Using NIS/YP
27040 This section will deal with setting up a sample NIS environment.
27042 ----------------------------------------------------------------------
27046 Let us assume that you are the administrator of a small university lab.
27047 This lab, which consists of 15 DragonFly machines, currently has no
27048 centralized point of administration; each machine has its own /etc/passwd
27049 and /etc/master.passwd. These files are kept in sync with each other only
27050 through manual intervention; currently, when you add a user to the lab,
27051 you must run adduser on all 15 machines. Clearly, this has to change, so
27052 you have decided to convert the lab to use NIS, using two of the machines
27055 Therefore, the configuration of the lab now looks something like:
27057 +------------------------------------------------------+
27058 | Machine name | IP address | Machine role |
27059 |--------------+---------------+-----------------------|
27060 | ellington | 10.0.0.2 | NIS master |
27061 |--------------+---------------+-----------------------|
27062 | coltrane | 10.0.0.3 | NIS slave |
27063 |--------------+---------------+-----------------------|
27064 | basie | 10.0.0.4 | Faculty workstation |
27065 |--------------+---------------+-----------------------|
27066 | bird | 10.0.0.5 | Client machine |
27067 |--------------+---------------+-----------------------|
27068 | cli[1-11] | 10.0.0.[6-17] | Other client machines |
27069 +------------------------------------------------------+
27071 If you are setting up a NIS scheme for the first time, it is a good idea
27072 to think through how you want to go about it. No matter what the size of
27073 your network, there are a few decisions that need to be made.
27075 ----------------------------------------------------------------------
27077 19.9.4.1.1 Choosing a NIS Domain Name
27079 This might not be the ``domainname'' that you are used to. It is more
27080 accurately called the ``NIS domainname''. When a client broadcasts its
27081 requests for info, it includes the name of the NIS domain that it is part
27082 of. This is how multiple servers on one network can tell which server
27083 should answer which request. Think of the NIS domainname as the name for a
27084 group of hosts that are related in some way.
27086 Some organizations choose to use their Internet domainname for their NIS
27087 domainname. This is not recommended as it can cause confusion when trying
27088 to debug network problems. The NIS domainname should be unique within your
27089 network and it is helpful if it describes the group of machines it
27090 represents. For example, the Art department at Acme Inc. might be in the
27091 ``acme-art'' NIS domain. For this example, assume you have chosen the name
27094 However, some operating systems (notably SunOS) use their NIS domain name
27095 as their Internet domain name. If one or more machines on your network
27096 have this restriction, you must use the Internet domain name as your NIS
27099 ----------------------------------------------------------------------
27101 19.9.4.1.2 Physical Server Requirements
27103 There are several things to keep in mind when choosing a machine to use as
27104 a NIS server. One of the unfortunate things about NIS is the level of
27105 dependency the clients have on the server. If a client cannot contact the
27106 server for its NIS domain, very often the machine becomes unusable. The
27107 lack of user and group information causes most systems to temporarily
27108 freeze up. With this in mind you should make sure to choose a machine that
27109 will not be prone to being rebooted regularly, or one that might be used
27110 for development. The NIS server should ideally be a stand alone machine
27111 whose sole purpose in life is to be an NIS server. If you have a network
27112 that is not very heavily used, it is acceptable to put the NIS server on a
27113 machine running other services, just keep in mind that if the NIS server
27114 becomes unavailable, it will affect all of your NIS clients adversely.
27116 ----------------------------------------------------------------------
27118 19.9.4.2 NIS Servers
27120 The canonical copies of all NIS information are stored on a single machine
27121 called the NIS master server. The databases used to store the information
27122 are called NIS maps. In DragonFly, these maps are stored in
27123 /var/yp/[domainname] where [domainname] is the name of the NIS domain
27124 being served. A single NIS server can support several domains at once,
27125 therefore it is possible to have several such directories, one for each
27126 supported domain. Each domain will have its own independent set of maps.
27128 NIS master and slave servers handle all NIS requests with the ypserv
27129 daemon. ypserv is responsible for receiving incoming requests from NIS
27130 clients, translating the requested domain and map name to a path to the
27131 corresponding database file and transmitting data from the database back
27134 ----------------------------------------------------------------------
27136 19.9.4.2.1 Setting Up a NIS Master Server
27138 Setting up a master NIS server can be relatively straight forward,
27139 depending on your needs. DragonFly comes with support for NIS
27140 out-of-the-box. All you need is to add the following lines to
27141 /etc/rc.conf, and DragonFly will do the rest for you.
27143 1. nisdomainname="test-domain"
27145 This line will set the NIS domainname to test-domain upon network
27146 setup (e.g. after reboot).
27148 2. nis_server_enable="YES"
27150 This will tell DragonFly to start up the NIS server processes when the
27151 networking is next brought up.
27153 3. nis_yppasswdd_enable="YES"
27155 This will enable the rpc.yppasswdd daemon which, as mentioned above,
27156 will allow users to change their NIS password from a client machine.
27158 Note: Depending on your NIS setup, you may need to add further entries.
27159 See the section about NIS servers that are also NIS clients, below, for
27162 Now, all you have to do is to run the command /etc/netstart as superuser.
27163 It will set up everything for you, using the values you defined in
27166 ----------------------------------------------------------------------
27168 19.9.4.2.2 Initializing the NIS Maps
27170 The NIS maps are database files, that are kept in the /var/yp directory.
27171 They are generated from configuration files in the /etc directory of the
27172 NIS master, with one exception: the /etc/master.passwd file. This is for a
27173 good reason; you do not want to propagate passwords to your root and other
27174 administrative accounts to all the servers in the NIS domain. Therefore,
27175 before we initialize the NIS maps, you should:
27177 # cp /etc/master.passwd /var/yp/master.passwd
27181 You should remove all entries regarding system accounts (bin, tty, kmem,
27182 games, etc), as well as any accounts that you do not want to be propagated
27183 to the NIS clients (for example root and any other UID 0 (superuser)
27186 Note: Make sure the /var/yp/master.passwd is neither group nor world
27187 readable (mode 600)! Use the chmod command, if appropriate.
27189 When you have finished, it is time to initialize the NIS maps! DragonFly
27190 includes a script named ypinit to do this for you (see its manual page for
27191 more information). Note that this script is available on most UNIX
27192 Operating Systems, but not on all. On Digital UNIX/Compaq Tru64 UNIX it is
27193 called ypsetup. Because we are generating maps for an NIS master, we are
27194 going to pass the -m option to ypinit. To generate the NIS maps, assuming
27195 you already performed the steps above, run:
27197 ellington# ypinit -m test-domain
27198 Server Type: MASTER Domain: test-domain
27199 Creating an YP server will require that you answer a few questions.
27200 Questions will all be asked at the beginning of the procedure.
27201 Do you want this procedure to quit on non-fatal errors? [y/n: n] n
27202 Ok, please remember to go back and redo manually whatever fails.
27203 If you don't, something might not work.
27204 At this point, we have to construct a list of this domains YP servers.
27205 rod.darktech.org is already known as master server.
27206 Please continue to add any slave servers, one per line. When you are
27207 done with the list, type a <control D>.
27208 master server : ellington
27209 next host to add: coltrane
27210 next host to add: ^D
27211 The current list of NIS servers looks like this:
27214 Is this correct? [y/n: y] y
27216 [..output from map generation..]
27218 NIS Map update completed.
27219 ellington has been setup as an YP master server without any errors.
27221 ypinit should have created /var/yp/Makefile from /var/yp/Makefile.dist.
27222 When created, this file assumes that you are operating in a single server
27223 NIS environment with only DragonFly machines. Since test-domain has a
27224 slave server as well, you must edit /var/yp/Makefile:
27226 ellington# vi /var/yp/Makefile
27228 You should comment out the line that says
27232 (if it is not commented out already).
27234 ----------------------------------------------------------------------
27236 19.9.4.2.3 Setting up a NIS Slave Server
27238 Setting up an NIS slave server is even more simple than setting up the
27239 master. Log on to the slave server and edit the file /etc/rc.conf as you
27240 did before. The only difference is that we now must use the -s option when
27241 running ypinit. The -s option requires the name of the NIS master be
27242 passed to it as well, so our command line looks like:
27244 coltrane# ypinit -s ellington test-domain
27246 Server Type: SLAVE Domain: test-domain Master: ellington
27248 Creating an YP server will require that you answer a few questions.
27249 Questions will all be asked at the beginning of the procedure.
27251 Do you want this procedure to quit on non-fatal errors? [y/n: n] n
27253 Ok, please remember to go back and redo manually whatever fails.
27254 If you don't, something might not work.
27255 There will be no further questions. The remainder of the procedure
27256 should take a few minutes, to copy the databases from ellington.
27257 Transferring netgroup...
27258 ypxfr: Exiting: Map successfully transferred
27259 Transferring netgroup.byuser...
27260 ypxfr: Exiting: Map successfully transferred
27261 Transferring netgroup.byhost...
27262 ypxfr: Exiting: Map successfully transferred
27263 Transferring master.passwd.byuid...
27264 ypxfr: Exiting: Map successfully transferred
27265 Transferring passwd.byuid...
27266 ypxfr: Exiting: Map successfully transferred
27267 Transferring passwd.byname...
27268 ypxfr: Exiting: Map successfully transferred
27269 Transferring group.bygid...
27270 ypxfr: Exiting: Map successfully transferred
27271 Transferring group.byname...
27272 ypxfr: Exiting: Map successfully transferred
27273 Transferring services.byname...
27274 ypxfr: Exiting: Map successfully transferred
27275 Transferring rpc.bynumber...
27276 ypxfr: Exiting: Map successfully transferred
27277 Transferring rpc.byname...
27278 ypxfr: Exiting: Map successfully transferred
27279 Transferring protocols.byname...
27280 ypxfr: Exiting: Map successfully transferred
27281 Transferring master.passwd.byname...
27282 ypxfr: Exiting: Map successfully transferred
27283 Transferring networks.byname...
27284 ypxfr: Exiting: Map successfully transferred
27285 Transferring networks.byaddr...
27286 ypxfr: Exiting: Map successfully transferred
27287 Transferring netid.byname...
27288 ypxfr: Exiting: Map successfully transferred
27289 Transferring hosts.byaddr...
27290 ypxfr: Exiting: Map successfully transferred
27291 Transferring protocols.bynumber...
27292 ypxfr: Exiting: Map successfully transferred
27293 Transferring ypservers...
27294 ypxfr: Exiting: Map successfully transferred
27295 Transferring hosts.byname...
27296 ypxfr: Exiting: Map successfully transferred
27298 coltrane has been setup as an YP slave server without any errors.
27299 Don't forget to update map ypservers on ellington.
27301 You should now have a directory called /var/yp/test-domain. Copies of the
27302 NIS master server's maps should be in this directory. You will need to
27303 make sure that these stay updated. The following /etc/crontab entries on
27304 your slave servers should do the job:
27306 20 * * * * root /usr/libexec/ypxfr passwd.byname
27307 21 * * * * root /usr/libexec/ypxfr passwd.byuid
27309 These two lines force the slave to sync its maps with the maps on the
27310 master server. Although these entries are not mandatory, since the master
27311 server attempts to ensure any changes to its NIS maps are communicated to
27312 its slaves and because password information is vital to systems depending
27313 on the server, it is a good idea to force the updates. This is more
27314 important on busy networks where map updates might not always complete.
27316 Now, run the command /etc/netstart on the slave server as well, which
27317 again starts the NIS server.
27319 ----------------------------------------------------------------------
27321 19.9.4.3 NIS Clients
27323 An NIS client establishes what is called a binding to a particular NIS
27324 server using the ypbind daemon. ypbind checks the system's default domain
27325 (as set by the domainname command), and begins broadcasting RPC requests
27326 on the local network. These requests specify the name of the domain for
27327 which ypbind is attempting to establish a binding. If a server that has
27328 been configured to serve the requested domain receives one of the
27329 broadcasts, it will respond to ypbind, which will record the server's
27330 address. If there are several servers available (a master and several
27331 slaves, for example), ypbind will use the address of the first one to
27332 respond. From that point on, the client system will direct all of its NIS
27333 requests to that server. ypbind will occasionally ``ping'' the server to
27334 make sure it is still up and running. If it fails to receive a reply to
27335 one of its pings within a reasonable amount of time, ypbind will mark the
27336 domain as unbound and begin broadcasting again in the hopes of locating
27339 ----------------------------------------------------------------------
27341 19.9.4.3.1 Setting Up a NIS Client
27343 Setting up a DragonFly machine to be a NIS client is fairly
27346 1. Edit the file /etc/rc.conf and add the following lines in order to set
27347 the NIS domainname and start ypbind upon network startup:
27349 nisdomainname="test-domain"
27350 nis_client_enable="YES"
27352 2. To import all possible password entries from the NIS server, remove
27353 all user accounts from your /etc/master.passwd file and use vipw to
27354 add the following line to the end of the file:
27358 Note: This line will afford anyone with a valid account in the NIS
27359 server's password maps an account. There are many ways to configure
27360 your NIS client by changing this line. See the netgroups section
27361 below for more information. For more detailed reading see O'Reilly's
27362 book on Managing NFS and NIS.
27364 Note: You should keep at least one local account (i.e. not imported
27365 via NIS) in your /etc/master.passwd and this account should also be
27366 a member of the group wheel. If there is something wrong with NIS,
27367 this account can be used to log in remotely, become root, and fix
27370 3. To import all possible group entries from the NIS server, add this
27371 line to your /etc/group file:
27375 After completing these steps, you should be able to run ypcat passwd and
27376 see the NIS server's passwd map.
27378 ----------------------------------------------------------------------
27380 19.9.5 NIS Security
27382 In general, any remote user can issue an RPC to ypserv(8) and retrieve the
27383 contents of your NIS maps, provided the remote user knows your domainname.
27384 To prevent such unauthorized transactions, ypserv(8) supports a feature
27385 called securenets which can be used to restrict access to a given set of
27386 hosts. At startup, ypserv(8) will attempt to load the securenets
27387 information from a file called /var/yp/securenets.
27389 Note: This path varies depending on the path specified with the -p
27390 option. This file contains entries that consist of a network
27391 specification and a network mask separated by white space. Lines
27392 starting with ``#'' are considered to be comments. A sample securenets
27393 file might look like this:
27395 # allow connections from local host -- mandatory
27396 127.0.0.1 255.255.255.255
27397 # allow connections from any host
27398 # on the 192.168.128.0 network
27399 192.168.128.0 255.255.255.0
27400 # allow connections from any host
27401 # between 10.0.0.0 to 10.0.15.255
27402 # this includes the machines in the testlab
27403 10.0.0.0 255.255.240.0
27405 If ypserv(8) receives a request from an address that matches one of these
27406 rules, it will process the request normally. If the address fails to match
27407 a rule, the request will be ignored and a warning message will be logged.
27408 If the /var/yp/securenets file does not exist, ypserv will allow
27409 connections from any host.
27411 The ypserv program also has support for Wietse Venema's tcpwrapper
27412 package. This allows the administrator to use the tcpwrapper configuration
27413 files for access control instead of /var/yp/securenets.
27415 Note: While both of these access control mechanisms provide some
27416 security, they, like the privileged port test, are vulnerable to ``IP
27417 spoofing'' attacks. All NIS-related traffic should be blocked at your
27420 Servers using /var/yp/securenets may fail to serve legitimate NIS
27421 clients with archaic TCP/IP implementations. Some of these
27422 implementations set all host bits to zero when doing broadcasts and/or
27423 fail to observe the subnet mask when calculating the broadcast address.
27424 While some of these problems can be fixed by changing the client
27425 configuration, other problems may force the retirement of the client
27426 systems in question or the abandonment of /var/yp/securenets.
27428 Using /var/yp/securenets on a server with such an archaic implementation
27429 of TCP/IP is a really bad idea and will lead to loss of NIS
27430 functionality for large parts of your network.
27432 The use of the tcpwrapper package increases the latency of your NIS
27433 server. The additional delay may be long enough to cause timeouts in
27434 client programs, especially in busy networks or with slow NIS servers.
27435 If one or more of your client systems suffers from these symptoms, you
27436 should convert the client systems in question into NIS slave servers and
27437 force them to bind to themselves.
27439 ----------------------------------------------------------------------
27441 19.9.6 Barring Some Users from Logging On
27443 In our lab, there is a machine basie that is supposed to be a faculty only
27444 workstation. We do not want to take this machine out of the NIS domain,
27445 yet the passwd file on the master NIS server contains accounts for both
27446 faculty and students. What can we do?
27448 There is a way to bar specific users from logging on to a machine, even if
27449 they are present in the NIS database. To do this, all you must do is add
27450 -username to the end of the /etc/master.passwd file on the client machine,
27451 where username is the username of the user you wish to bar from logging
27452 in. This should preferably be done using vipw, since vipw will sanity
27453 check your changes to /etc/master.passwd, as well as automatically rebuild
27454 the password database when you finish editing. For example, if we wanted
27455 to bar user bill from logging on to basie we would:
27458 [add -bill to the end, exit]
27459 vipw: rebuilding the database...
27462 basie# cat /etc/master.passwd
27464 root:[password]:0:0::0:0:The super-user:/root:/bin/csh
27465 toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
27466 daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
27467 operator:*:2:5::0:0:System &:/:/sbin/nologin
27468 bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
27469 tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
27470 kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
27471 games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
27472 news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
27473 man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
27474 bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
27475 uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
27476 xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
27477 pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
27478 nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
27484 ----------------------------------------------------------------------
27486 19.9.7 Using Netgroups
27488 Contributed by Udo Erdelhoff.
27490 The method shown in the previous section works reasonably well if you need
27491 special rules for a very small number of users and/or machines. On larger
27492 networks, you will forget to bar some users from logging onto sensitive
27493 machines, or you may even have to modify each machine separately, thus
27494 losing the main benefit of NIS, centralized administration.
27496 The NIS developers' solution for this problem is called netgroups. Their
27497 purpose and semantics can be compared to the normal groups used by UNIX
27498 file systems. The main differences are the lack of a numeric id and the
27499 ability to define a netgroup by including both user accounts and other
27502 Netgroups were developed to handle large, complex networks with hundreds
27503 of users and machines. On one hand, this is a Good Thing if you are forced
27504 to deal with such a situation. On the other hand, this complexity makes it
27505 almost impossible to explain netgroups with really simple examples. The
27506 example used in the remainder of this section demonstrates this problem.
27508 Let us assume that your successful introduction of NIS in your laboratory
27509 caught your superiors' interest. Your next job is to extend your NIS
27510 domain to cover some of the other machines on campus. The two tables
27511 contain the names of the new users and new machines as well as brief
27512 descriptions of them.
27514 +----------------------------------------------------------------------+
27515 | User Name(s) | Description |
27516 |---------------------------+------------------------------------------|
27517 | alpha, beta | Normal employees of the IT department |
27518 |---------------------------+------------------------------------------|
27519 | charlie, delta | The new apprentices of the IT department |
27520 |---------------------------+------------------------------------------|
27521 | echo, foxtrott, golf, ... | Ordinary employees |
27522 |---------------------------+------------------------------------------|
27523 | able, baker, ... | The current interns |
27524 +----------------------------------------------------------------------+
27526 +------------------------------------------------------------------------+
27527 | Machine Name(s) | Description |
27528 |----------------------------+-------------------------------------------|
27529 | war, death, famine, | Your most important servers. Only the IT |
27530 | pollution | employees are allowed to log onto these |
27532 |----------------------------+-------------------------------------------|
27533 | pride, greed, envy, wrath, | Less important servers. All members of |
27534 | lust, sloth | the IT department are allowed to login |
27535 | | onto these machines. |
27536 |----------------------------+-------------------------------------------|
27537 | | Ordinary workstations. Only the real |
27538 | one, two, three, four, ... | employees are allowed to use these |
27540 |----------------------------+-------------------------------------------|
27541 | | A very old machine without any critical |
27542 | trashcan | data. Even the intern is allowed to use |
27544 +------------------------------------------------------------------------+
27546 If you tried to implement these restrictions by separately blocking each
27547 user, you would have to add one -user line to each system's passwd for
27548 each user who is not allowed to login onto that system. If you forget just
27549 one entry, you could be in trouble. It may be feasible to do this
27550 correctly during the initial setup, however you will eventually forget to
27551 add the lines for new users during day-to-day operations. After all,
27552 Murphy was an optimist.
27554 Handling this situation with netgroups offers several advantages. Each
27555 user need not be handled separately; you assign a user to one or more
27556 netgroups and allow or forbid logins for all members of the netgroup. If
27557 you add a new machine, you will only have to define login restrictions for
27558 netgroups. If a new user is added, you will only have to add the user to
27559 one or more netgroups. Those changes are independent of each other; no
27560 more ``for each combination of user and machine do...'' If your NIS setup
27561 is planned carefully, you will only have to modify exactly one central
27562 configuration file to grant or deny access to machines.
27564 The first step is the initialization of the NIS map netgroup. DragonFly's
27565 ypinit(8) does not create this map by default, but its NIS implementation
27566 will support it once it has been created. To create an empty map, simply
27569 ellington# vi /var/yp/netgroup
27571 and start adding content. For our example, we need at least four
27572 netgroups: IT employees, IT apprentices, normal employees and interns.
27574 IT_EMP (,alpha,test-domain) (,beta,test-domain)
27575 IT_APP (,charlie,test-domain) (,delta,test-domain)
27576 USERS (,echo,test-domain) (,foxtrott,test-domain) \
27577 (,golf,test-domain)
27578 INTERNS (,able,test-domain) (,baker,test-domain)
27580 IT_EMP, IT_APP etc. are the names of the netgroups. Each bracketed group
27581 adds one or more user accounts to it. The three fields inside a group are:
27583 1. The name of the host(s) where the following items are valid. If you do
27584 not specify a hostname, the entry is valid on all hosts. If you do
27585 specify a hostname, you will enter a realm of darkness, horror and
27588 2. The name of the account that belongs to this netgroup.
27590 3. The NIS domain for the account. You can import accounts from other NIS
27591 domains into your netgroup if you are one of the unlucky fellows with
27592 more than one NIS domain.
27594 Each of these fields can contain wildcards. See netgroup(5) for details.
27596 Note: Netgroup names longer than 8 characters should not be used,
27597 especially if you have machines running other operating systems within
27598 your NIS domain. The names are case sensitive; using capital letters for
27599 your netgroup names is an easy way to distinguish between user, machine
27600 and netgroup names.
27602 Some NIS clients (other than DragonFly) cannot handle netgroups with a
27603 large number of entries. For example, some older versions of SunOS start
27604 to cause trouble if a netgroup contains more than 15 entries. You can
27605 circumvent this limit by creating several sub-netgroups with 15 users or
27606 less and a real netgroup that consists of the sub-netgroups:
27608 BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...]
27609 BIGGRP2 (,joe16,domain) (,joe17,domain) [...]
27610 BIGGRP3 (,joe31,domain) (,joe32,domain)
27611 BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3
27613 You can repeat this process if you need more than 225 users within a
27616 Activating and distributing your new NIS map is easy:
27618 ellington# cd /var/yp
27621 This will generate the three NIS maps netgroup, netgroup.byhost and
27622 netgroup.byuser. Use ypcat(1) to check if your new NIS maps are available:
27624 ellington% ypcat -k netgroup
27625 ellington% ypcat -k netgroup.byhost
27626 ellington% ypcat -k netgroup.byuser
27628 The output of the first command should resemble the contents of
27629 /var/yp/netgroup. The second command will not produce output if you have
27630 not specified host-specific netgroups. The third command can be used to
27631 get the list of netgroups for a user.
27633 The client setup is quite simple. To configure the server war, you only
27634 have to start vipw(8) and replace the line
27642 Now, only the data for the users defined in the netgroup IT_EMP is
27643 imported into war's password database and only these users are allowed to
27646 Unfortunately, this limitation also applies to the ~ function of the shell
27647 and all routines converting between user names and numerical user IDs. In
27648 other words, cd ~user will not work, ls -l will show the numerical id
27649 instead of the username and find . -user joe -print will fail with ``No
27650 such user''. To fix this, you will have to import all user entries without
27651 allowing them to login onto your servers.
27653 This can be achieved by adding another line to /etc/master.passwd. This
27654 line should contain:
27656 +:::::::::/sbin/nologin, meaning ``Import all entries but replace the
27657 shell with /sbin/nologin in the imported entries''. You can replace any
27658 field in the passwd entry by placing a default value in your
27659 /etc/master.passwd.
27661 Warning: Make sure that the line +:::::::::/sbin/nologin is placed after
27662 +@IT_EMP:::::::::. Otherwise, all user accounts imported from NIS will
27663 have /sbin/nologin as their login shell.
27665 After this change, you will only have to change one NIS map if a new
27666 employee joins the IT department. You could use a similar approach for the
27667 less important servers by replacing the old +::::::::: in their local
27668 version of /etc/master.passwd with something like this:
27672 +:::::::::/sbin/nologin
27674 The corresponding lines for the normal workstations could be:
27678 +:::::::::/sbin/nologin
27680 And everything would be fine until there is a policy change a few weeks
27681 later: The IT department starts hiring interns. The IT interns are allowed
27682 to use the normal workstations and the less important servers; and the IT
27683 apprentices are allowed to login onto the main servers. You add a new
27684 netgroup IT_INTERN, add the new IT interns to this netgroup and start to
27685 change the config on each and every machine... As the old saying goes:
27686 ``Errors in centralized planning lead to global mess''.
27688 NIS' ability to create netgroups from other netgroups can be used to
27689 prevent situations like these. One possibility is the creation of
27690 role-based netgroups. For example, you could create a netgroup called
27691 BIGSRV to define the login restrictions for the important servers, another
27692 netgroup called SMALLSRV for the less important servers and a third
27693 netgroup called USERBOX for the normal workstations. Each of these
27694 netgroups contains the netgroups that are allowed to login onto these
27695 machines. The new entries for your NIS map netgroup should look like this:
27697 BIGSRV IT_EMP IT_APP
27698 SMALLSRV IT_EMP IT_APP ITINTERN
27699 USERBOX IT_EMP ITINTERN USERS
27701 This method of defining login restrictions works reasonably well if you
27702 can define groups of machines with identical restrictions. Unfortunately,
27703 this is the exception and not the rule. Most of the time, you will need
27704 the ability to define login restrictions on a per-machine basis.
27706 Machine-specific netgroup definitions are the other possibility to deal
27707 with the policy change outlined above. In this scenario, the
27708 /etc/master.passwd of each box contains two lines starting with ``+''. The
27709 first of them adds a netgroup with the accounts allowed to login onto this
27710 machine, the second one adds all other accounts with /sbin/nologin as
27711 shell. It is a good idea to use the ALL-CAPS version of the machine name
27712 as the name of the netgroup. In other words, the lines should look like
27716 +:::::::::/sbin/nologin
27718 Once you have completed this task for all your machines, you will not have
27719 to modify the local versions of /etc/master.passwd ever again. All further
27720 changes can be handled by modifying the NIS map. Here is an example of a
27721 possible netgroup map for this scenario with some additional goodies.
27723 # Define groups of users first
27724 IT_EMP (,alpha,test-domain) (,beta,test-domain)
27725 IT_APP (,charlie,test-domain) (,delta,test-domain)
27726 DEPT1 (,echo,test-domain) (,foxtrott,test-domain)
27727 DEPT2 (,golf,test-domain) (,hotel,test-domain)
27728 DEPT3 (,india,test-domain) (,juliet,test-domain)
27729 ITINTERN (,kilo,test-domain) (,lima,test-domain)
27730 D_INTERNS (,able,test-domain) (,baker,test-domain)
27732 # Now, define some groups based on roles
27733 USERS DEPT1 DEPT2 DEPT3
27734 BIGSRV IT_EMP IT_APP
27735 SMALLSRV IT_EMP IT_APP ITINTERN
27736 USERBOX IT_EMP ITINTERN USERS
27738 # And a groups for a special tasks
27739 # Allow echo and golf to access our anti-virus-machine
27740 SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain)
27742 # machine-based netgroups
27746 # User india needs access to this server
27747 POLLUTION BIGSRV (,india,test-domain)
27749 # This one is really important and needs more access restrictions
27752 # The anti-virus-machine mentioned above
27755 # Restrict a machine to a single user
27756 TWO (,hotel,test-domain)
27757 # [...more groups to follow]
27759 If you are using some kind of database to manage your user accounts, you
27760 should be able to create the first part of the map with your database's
27761 report tools. This way, new users will automatically have access to the
27764 One last word of caution: It may not always be advisable to use
27765 machine-based netgroups. If you are deploying a couple of dozen or even
27766 hundreds of identical machines for student labs, you should use role-based
27767 netgroups instead of machine-based netgroups to keep the size of the NIS
27768 map within reasonable limits.
27770 ----------------------------------------------------------------------
27772 19.9.8 Important Things to Remember
27774 There are still a couple of things that you will need to do differently
27775 now that you are in an NIS environment.
27777 * Every time you wish to add a user to the lab, you must add it to the
27778 master NIS server only, and you must remember to rebuild the NIS maps.
27779 If you forget to do this, the new user will not be able to login
27780 anywhere except on the NIS master. For example, if we needed to add a
27781 new user ``jsmith'' to the lab, we would:
27783 # pw useradd jsmith
27787 You could also run adduser jsmith instead of pw useradd jsmith.
27789 * Keep the administration accounts out of the NIS maps. You do not want
27790 to be propagating administrative accounts and passwords to machines
27791 that will have users that should not have access to those accounts.
27793 * Keep the NIS master and slave secure, and minimize their downtime. If
27794 somebody either hacks or simply turns off these machines, they have
27795 effectively rendered many people without the ability to login to the
27798 This is the chief weakness of any centralized administration system.
27799 If you do not protect your NIS servers, you will have a lot of angry
27802 ----------------------------------------------------------------------
27804 19.9.9 NIS v1 Compatibility
27806 DragonFly's ypserv has some support for serving NIS v1 clients.
27807 DragonFly's NIS implementation only uses the NIS v2 protocol, however
27808 other implementations include support for the v1 protocol for backwards
27809 compatibility with older systems. The ypbind daemons supplied with these
27810 systems will try to establish a binding to an NIS v1 server even though
27811 they may never actually need it (and they may persist in broadcasting in
27812 search of one even after they receive a response from a v2 server). Note
27813 that while support for normal client calls is provided, this version of
27814 ypserv does not handle v1 map transfer requests; consequently, it cannot
27815 be used as a master or slave in conjunction with older NIS servers that
27816 only support the v1 protocol. Fortunately, there probably are not any such
27817 servers still in use today.
27819 ----------------------------------------------------------------------
27821 19.9.10 NIS Servers That Are Also NIS Clients
27823 Care must be taken when running ypserv in a multi-server domain where the
27824 server machines are also NIS clients. It is generally a good idea to force
27825 the servers to bind to themselves rather than allowing them to broadcast
27826 bind requests and possibly become bound to each other. Strange failure
27827 modes can result if one server goes down and others are dependent upon it.
27828 Eventually all the clients will time out and attempt to bind to other
27829 servers, but the delay involved can be considerable and the failure mode
27830 is still present since the servers might bind to each other all over
27833 You can force a host to bind to a particular server by running ypbind with
27834 the -S flag. If you do not want to do this manually each time you reboot
27835 your NIS server, you can add the following lines to your /etc/rc.conf:
27837 nis_client_enable="YES" # run client stuff as well
27838 nis_client_flags="-S NIS domain,server"
27840 See ypbind(8) for further information.
27842 ----------------------------------------------------------------------
27844 19.9.11 Password Formats
27846 One of the most common issues that people run into when trying to
27847 implement NIS is password format compatibility. If your NIS server is
27848 using DES encrypted passwords, it will only support clients that are also
27849 using DES. For example, if you have Solaris NIS clients in your network,
27850 then you will almost certainly need to use DES encrypted passwords.
27852 To check which format your servers and clients are using, look at
27853 /etc/login.conf. If the host is configured to use DES encrypted passwords,
27854 then the default class will contain an entry like this:
27857 :passwd_format=des:\
27858 :copyright=/etc/COPYRIGHT:\
27859 [Further entries elided]
27861 Other possible values for the passwd_format capability include blf and md5
27862 (for Blowfish and MD5 encrypted passwords, respectively).
27864 If you have made changes to /etc/login.conf, you will also need to rebuild
27865 the login capability database, which is achieved by running the following
27868 # cap_mkdb /etc/login.conf
27870 Note: The format of passwords already in /etc/master.passwd will not be
27871 updated until a user changes their password for the first time after the
27872 login capability database is rebuilt.
27874 Next, in order to ensure that passwords are encrypted with the format that
27875 you have chosen, you should also check that the crypt_default in
27876 /etc/auth.conf gives precedence to your chosen password format. To do
27877 this, place the format that you have chosen first in the list. For
27878 example, when using DES encrypted passwords, the entry would be:
27880 crypt_default = des blf md5
27882 Having followed the above steps on each of the DragonFly based NIS servers
27883 and clients, you can be sure that they all agree on which password format
27884 is used within your network. If you have trouble authenticating on an NIS
27885 client, this is a pretty good place to start looking for possible
27886 problems. Remember: if you want to deploy an NIS server for a heterogenous
27887 network, you will probably have to use DES on all systems because it is
27888 the lowest common standard.
27890 ----------------------------------------------------------------------
27894 Written by Greg Sutter.
27896 19.10.1 What Is DHCP?
27898 DHCP, the Dynamic Host Configuration Protocol, describes the means by
27899 which a system can connect to a network and obtain the necessary
27900 information for communication upon that network. DragonFly uses the ISC
27901 (Internet Software Consortium) DHCP implementation, so all
27902 implementation-specific information here is for use with the ISC
27905 ----------------------------------------------------------------------
27907 19.10.2 What This Section Covers
27909 This section describes both the client-side and server-side components of
27910 the ISC DHCP system. The client-side program, dhclient, and the server,
27911 come integrated within DragonFly. The dhclient(8), dhcp-options(5), and
27912 dhclient.conf(5) manual pages, in addition to the references below, are
27915 ----------------------------------------------------------------------
27917 19.10.3 How It Works
27919 When dhclient, the DHCP client, is executed on the client machine, it
27920 begins broadcasting requests for configuration information. By default,
27921 these requests are on UDP port 68. The server replies on UDP 67, giving
27922 the client an IP address and other relevant network information such as
27923 netmask, router, and DNS servers. All of this information comes in the
27924 form of a DHCP ``lease'' and is only valid for a certain time (configured
27925 by the DHCP server maintainer). In this manner, stale IP addresses for
27926 clients no longer connected to the network can be automatically reclaimed.
27928 DHCP clients can obtain a great deal of information from the server. An
27929 exhaustive list may be found in dhcp-options(5).
27931 ----------------------------------------------------------------------
27933 19.10.4 DragonFly Integration
27935 DragonFly fully integrates the ISC DHCP client, dhclient. DHCP client
27936 support is provided within both the installer and the base system,
27937 obviating the need for detailed knowledge of network configurations on any
27938 network that runs a DHCP server.
27940 There are two things you must do to have your system use DHCP upon
27943 * Make sure that the bpf device is compiled into your kernel. To do
27944 this, add pseudo-device bpf to your kernel configuration file, and
27945 rebuild the kernel. For more information about building kernels, see
27948 The bpf device is already part of the GENERIC kernel that is supplied
27949 with DragonFly, so if you do not have a custom kernel, you should not
27950 need to create one in order to get DHCP working.
27952 Note: For those who are particularly security conscious, you should
27953 be warned that bpf is also the device that allows packet sniffers to
27954 work correctly (although they still have to be run as root). bpf is
27955 required to use DHCP, but if you are very sensitive about security,
27956 you probably should not add bpf to your kernel in the expectation
27957 that at some point in the future you will be using DHCP.
27959 * Edit your /etc/rc.conf to include the following:
27961 ifconfig_fxp0="DHCP"
27963 Note: Be sure to replace fxp0 with the designation for the interface
27964 that you wish to dynamically configure, as described in Section 6.8.
27966 If you are using a different location for dhclient, or if you wish to
27967 pass additional flags to dhclient, also include the following (editing
27970 dhcp_program="/sbin/dhclient"
27973 The DHCP server, dhcpd, is included as part of the net/isc-dhcp3-server
27974 port in the ports collection. This port contains the ISC DHCP server and
27977 ----------------------------------------------------------------------
27981 * /etc/dhclient.conf
27983 dhclient requires a configuration file, /etc/dhclient.conf. Typically
27984 the file contains only comments, the defaults being reasonably sane.
27985 This configuration file is described by the dhclient.conf(5) manual
27990 dhclient is statically linked and resides in /sbin. The dhclient(8)
27991 manual page gives more information about dhclient.
27993 * /sbin/dhclient-script
27995 dhclient-script is the DragonFly-specific DHCP client configuration
27996 script. It is described in dhclient-script(8), but should not need any
27997 user modification to function properly.
27999 * /var/db/dhclient.leases
28001 The DHCP client keeps a database of valid leases in this file, which
28002 is written as a log. dhclient.leases(5) gives a slightly longer
28005 ----------------------------------------------------------------------
28007 19.10.6 Further Reading
28009 The DHCP protocol is fully described in RFC 2131. An informational
28010 resource has also been set up at dhcp.org.
28012 ----------------------------------------------------------------------
28014 19.10.7 Installing and Configuring a DHCP Server
28016 19.10.7.1 What This Section Covers
28018 This section provides information on how to configure a DragonFly system
28019 to act as a DHCP server using the ISC (Internet Software Consortium)
28020 implementation of the DHCP suite.
28022 ----------------------------------------------------------------------
28024 19.10.7.2 DHCP Server Installation
28026 In order to configure your DragonFly system as a DHCP server, you will
28027 need to ensure that the bpf(4) device is compiled into your kernel. To do
28028 this, add pseudo-device bpf to your kernel configuration file, and rebuild
28029 the kernel. For more information about building kernels, see Chapter 9.
28031 The bpf device is already part of the GENERIC kernel that is supplied with
28032 DragonFly, so you do not need to create a custom kernel in order to get
28035 Note: Those who are particularly security conscious should note that bpf
28036 is also the device that allows packet sniffers to work correctly
28037 (although such programs still need privileged access). bpf is required
28038 to use DHCP, but if you are very sensitive about security, you probably
28039 should not include bpf in your kernel purely because you expect to use
28040 DHCP at some point in the future.
28042 The next thing that you will need to do is edit the sample dhcpd.conf
28043 which was installed by the net/isc-dhcp3-server port. By default, this
28044 will be /usr/local/etc/dhcpd.conf.sample, and you should copy this to
28045 /usr/local/etc/dhcpd.conf before proceeding to make changes.
28047 ----------------------------------------------------------------------
28049 19.10.7.3 Configuring the DHCP Server
28051 dhcpd.conf is comprised of declarations regarding subnets and hosts, and
28052 is perhaps most easily explained using an example :
28054 option domain-name "example.com";(1)
28055 option domain-name-servers 192.168.4.100;(2)
28056 option subnet-mask 255.255.255.0;(3)
28058 default-lease-time 3600;(4)
28059 max-lease-time 86400;(5)
28060 ddns-update-style none;(6)
28062 subnet 192.168.4.0 netmask 255.255.255.0 {
28063 range 192.168.4.129 192.168.4.254;(7)
28064 option routers 192.168.4.1;(8)
28068 hardware ethernet 02:03:04:05:06:07;(9)
28069 fixed-address mailhost.example.com;(10)
28073 This option specifies the domain that will be provided to clients
28074 as the default search domain. See resolv.conf(5) for more
28075 information on what this means.
28077 This option specifies a comma separated list of DNS servers that
28078 the client should use.
28080 The netmask that will be provided to clients.
28082 A client may request a specific length of time that a lease will
28083 be valid. Otherwise the server will assign a lease with this
28084 expiry value (in seconds).
28086 This is the maximum length of time that the server will lease for.
28087 Should a client request a longer lease, a lease will be issued,
28088 although it will only be valid for max-lease-time seconds.
28090 This option specifies whether the DHCP server should attempt to
28091 update DNS when a lease is accepted or released. In the ISC
28092 implementation, this option is required.
28094 This denotes which IP addresses should be used in the pool
28095 reserved for allocating to clients. IP addresses between, and
28096 including, the ones stated are handed out to clients.
28098 Declares the default gateway that will be provided to clients.
28100 The hardware MAC address of a host (so that the DHCP server can
28101 recognize a host when it makes a request).
28103 Specifies that the host should always be given the same IP
28104 address. Note that using a hostname is correct here, since the
28105 DHCP server will resolve the hostname itself before returning the
28108 Once you have finished writing your dhcpd.conf, you can proceed to start
28109 the server by issuing the following command:
28111 # /usr/local/etc/rc.d/isc-dhcpd.sh start
28113 Should you need to make changes to the configuration of your server in the
28114 future, it is important to note that sending a SIGHUP signal to dhcpd does
28115 not result in the configuration being reloaded, as it does with most
28116 daemons. You will need to send a SIGTERM signal to stop the process, and
28117 then restart it using the command above.
28119 ----------------------------------------------------------------------
28125 dhcpd is statically linked and resides in /usr/local/sbin. The
28126 dhcpd(8) manual page installed with the port gives more information
28131 dhcpd requires a configuration file, /usr/local/etc/dhcpd.conf before
28132 it will start providing service to clients. This file needs to contain
28133 all the information that should be provided to clients that are being
28134 serviced, along with information regarding the operation of the
28135 server. This configuration file is described by the dhcpd.conf(5)
28136 manual page installed by the port.
28138 * /var/db/dhcpd.leases
28140 The DHCP server keeps a database of leases it has issued in this file,
28141 which is written as a log. The manual page dhcpd.leases(5), installed
28142 by the port gives a slightly longer description.
28144 * /usr/sbin/dhcrelay
28146 dhcrelay is used in advanced environments where one DHCP server
28147 forwards a request from a client to another DHCP server on a separate
28150 ----------------------------------------------------------------------
28154 Contributed by Chern Lee.
28158 DragonFly utilizes, by default, a version of BIND (Berkeley Internet Name
28159 Domain), which is the most common implementation of the DNS protocol. DNS
28160 is the protocol through which names are mapped to IP addresses, and vice
28161 versa. For example, a query for www.dragonflybsd.org will receive a reply
28162 with the IP address of The DragonFly Project's web server, whereas, a
28163 query for ftp.dragonflybsd.org will return the IP address of the
28164 corresponding FTP machine. Likewise, the opposite can happen. A query for
28165 an IP address can resolve its hostname. It is not necessary to run a name
28166 server to perform DNS lookups on a system.
28168 DNS is coordinated across the Internet through a somewhat complex system
28169 of authoritative root name servers, and other smaller-scale name servers
28170 who host and cache individual domain information.
28172 This document refers to BIND 9.x.
28174 RFC1034 and RFC1035 dictate the DNS protocol.
28176 Currently, BIND is maintained by the Internet Software Consortium
28179 ----------------------------------------------------------------------
28181 19.11.2 Terminology
28183 To understand this document, some terms related to DNS must be understood.
28186 Forward DNS Mapping of hostnames to IP addresses
28187 Origin Refers to the domain covered in a particular zone
28189 named, BIND, name server Common names for the BIND name server package
28191 Resolver A system process through which a machine queries
28192 a name server for zone information
28193 Reverse DNS The opposite of forward DNS; mapping of IP
28194 addresses to hostnames
28195 The beginning of the Internet zone hierarchy. All
28196 Root zone zones fall under the root zone, similar to how
28197 all files in a file system fall under the root
28199 Zone An individual domain, subdomain, or portion of
28200 the DNS administered by the same authority
28204 * . is the root zone
28206 * org. is a zone under the root zone
28208 * example.org is a zone under the org. zone
28210 * foo.example.org. is a subdomain, a zone under the example.org. zone
28212 * 1.2.3.in-addr.arpa is a zone referencing all IP addresses which fall
28213 under the 3.2.1.* IP space.
28215 As one can see, the more specific part of a hostname appears to its left.
28216 For example, example.org. is more specific than org., as org. is more
28217 specific than the root zone. The layout of each part of a hostname is much
28218 like a filesystem: the /dev directory falls within the root, and so on.
28220 ----------------------------------------------------------------------
28222 19.11.3 Reasons to Run a Name Server
28224 Name servers usually come in two forms: an authoritative name server, and
28225 a caching name server.
28227 An authoritative name server is needed when:
28229 * one wants to serve DNS information to the world, replying
28230 authoritatively to queries.
28232 * a domain, such as example.org, is registered and IP addresses need to
28233 be assigned to hostnames under it.
28235 * an IP address block requires reverse DNS entries (IP to hostname).
28237 * a backup name server, called a slave, must reply to queries when the
28238 primary is down or inaccessible.
28240 A caching name server is needed when:
28242 * a local DNS server may cache and respond more quickly than querying an
28243 outside name server.
28245 * a reduction in overall network traffic is desired (DNS traffic has
28246 been measured to account for 5% or more of total Internet traffic).
28248 When one queries for www.dragonflybsd.org, the resolver usually queries
28249 the uplink ISP's name server, and retrieves the reply. With a local,
28250 caching DNS server, the query only has to be made once to the outside
28251 world by the caching DNS server. Every additional query will not have to
28252 look to the outside of the local network, since the information is cached
28255 ----------------------------------------------------------------------
28257 19.11.4 How It Works
28259 In DragonFly, the BIND daemon is called named for obvious reasons.
28262 named the BIND daemon
28263 ndc name daemon control program
28264 /etc/namedb directory where BIND zone information resides
28265 /etc/namedb/named.conf daemon configuration file
28267 Zone files are usually contained within the /etc/namedb directory, and
28268 contain the DNS zone information served by the name server.
28270 ----------------------------------------------------------------------
28272 19.11.5 Starting BIND
28274 Since BIND is installed by default, configuring it all is relatively
28277 To ensure the named daemon is started at boot, put the following
28278 modifications in /etc/rc.conf:
28282 To start the daemon manually (after configuring it)
28286 ----------------------------------------------------------------------
28288 19.11.6 Configuration Files
28290 ----------------------------------------------------------------------
28292 19.11.6.1 Using make-localhost
28297 # sh make-localhost
28299 to properly create the local reverse DNS zone file in
28300 /etc/namedb/localhost.rev.
28302 ----------------------------------------------------------------------
28304 19.11.6.2 /etc/namedb/named.conf
28306 // Refer to the named(8) manual page for details. If you are ever going
28307 // to setup a primary server, make sure you've understood the hairy
28308 // details of how DNS is working. Even with simple mistakes, you can
28309 // break connectivity for affected parties, or cause huge amount of
28310 // useless Internet traffic.
28313 directory "/etc/namedb";
28315 // In addition to the "forwarders" clause, you can force your name
28316 // server to never initiate queries of its own, but always ask its
28317 // forwarders only, by enabling the following line:
28321 // If you've got a DNS server around at your upstream provider, enter
28322 // its IP address here, and enable the line below. This will make you
28323 // benefit from its cache, thus reduce overall DNS traffic in the
28331 Just as the comment says, to benefit from an uplink's cache, forwarders
28332 can be enabled here. Under normal circumstances, a name server will
28333 recursively query the Internet looking at certain name servers until it
28334 finds the answer it is looking for. Having this enabled will have it query
28335 the uplink's name server (or name server provided) first, taking advantage
28336 of its cache. If the uplink name server in question is a heavily
28337 trafficked, fast name server, enabling this may be worthwhile.
28339 Warning: 127.0.0.1 will not work here. Change this IP address to a name
28340 server at your uplink.
28343 * If there is a firewall between you and name servers you want
28344 * to talk to, you might need to uncomment the query-source
28345 * directive below. Previous versions of BIND always asked
28346 * questions using port 53, but BIND 8.1 uses an unprivileged
28349 // query-source address * port 53;
28352 * If running in a sandbox, you may have to specify a different
28353 * location for the dumpfile.
28355 // dump-file "s/named_dump.db";
28358 // Note: the following will be supported in a future release.
28367 // Setting up secondaries is way easier and the rough picture for this
28368 // is explained below.
28370 // If you enable a local name server, don't forget to enter 127.0.0.1
28371 // into your /etc/resolv.conf so this server will be queried first.
28372 // Also, make sure to enable it in /etc/rc.conf.
28379 zone "0.0.127.IN-ADDR.ARPA" {
28381 file "localhost.rev";
28385 "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
28387 file "localhost.rev";
28390 // NB: Do not use the IP addresses below, they are faked, and only
28391 // serve demonstration/documentation purposes!
28393 // Example secondary config entries. It can be convenient to become
28394 // a secondary at least for the zone where your own domain is in. Ask
28395 // your network administrator for the IP address of the responsible
28398 // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
28399 // (This is the first bytes of the respective IP address, in reverse
28400 // order, with ".IN-ADDR.ARPA" appended.)
28402 // Before starting to setup a primary zone, better make sure you fully
28403 // understand how DNS and BIND works, however. There are sometimes
28404 // unobvious pitfalls. Setting up a secondary is comparably simpler.
28406 // NB: Don't blindly enable the examples below. :-) Use actual names
28407 // and addresses instead.
28409 // NOTE!!! DragonFly runs bind in a sandbox (see named_flags in rc.conf).
28410 // The directory containing the secondary zones must be write accessible
28411 // to bind. The following sequence is suggested:
28413 // mkdir /etc/namedb/s
28414 // chown bind:bind /etc/namedb/s
28415 // chmod 750 /etc/namedb/s
28417 For more information on running BIND in a sandbox, see Running named in a
28421 zone "example.com" {
28423 file "s/example.com.bak";
28429 zone "0.168.192.in-addr.arpa" {
28431 file "s/0.168.192.in-addr.arpa.bak";
28438 In named.conf, these are examples of slave entries for a forward and
28441 For each new zone served, a new zone entry must be added to named.conf
28443 For example, the simplest zone entry for example.org can look like:
28445 zone "example.org" {
28447 file "example.org";
28450 The zone is a master, as indicated by the type statement, holding its zone
28451 information in /etc/namedb/example.org indicated by the file statement.
28453 zone "example.org" {
28455 file "example.org";
28458 In the slave case, the zone information is transferred from the master
28459 name server for the particular zone, and saved in the file specified. If
28460 and when the master server dies or is unreachable, the slave name server
28461 will have the transferred zone information and will be able to serve it.
28463 ----------------------------------------------------------------------
28465 19.11.6.3 Zone Files
28467 An example master zone file for example.org (existing within
28468 /etc/namedb/example.org) is as follows:
28472 example.org. IN SOA ns1.example.org. admin.example.org. (
28477 86400 ) ; Minimum TTL
28480 @ IN NS ns1.example.org.
28481 @ IN NS ns2.example.org.
28484 localhost IN A 127.0.0.1
28494 @ IN MX 10 mail.example.org.
28496 Note that every hostname ending in a ``.'' is an exact hostname, whereas
28497 everything without a trailing ``.'' is referenced to the origin. For
28498 example, www is translated into www + origin. In our fictitious zone file,
28499 our origin is example.org., so www would translate to www.example.org.
28501 The format of a zone file follows:
28503 recordname IN recordtype value
28505 The most commonly used DNS records:
28509 start of zone authority
28513 an authoritative name server
28521 the canonical name for an alias
28529 a domain name pointer (used in reverse DNS)
28531 example.org. IN SOA ns1.example.org. admin.example.org. (
28533 10800 ; Refresh after 3 hours
28534 3600 ; Retry after 1 hour
28535 604800 ; Expire after 1 week
28536 86400 ) ; Minimum TTL of 1 day
28540 the domain name, also the origin for this zone file.
28544 the primary/authoritative name server for this zone
28548 the responsible person for this zone, email address with @
28549 replaced. (<admin@example.org> becomes admin.example.org)
28553 the serial number of the file. this must be incremented each time
28554 the zone file is modified. Nowadays, many admins prefer a
28555 yyyymmddrr format for the serial number. 2001041002 would mean
28556 last modified 04/10/2001, the latter 02 being the second time the
28557 zone file has been modified this day. The serial number is
28558 important as it alerts slave name servers for a zone when it is
28561 @ IN NS ns1.example.org.
28563 This is an NS entry. Every name server that is going to reply
28564 authoritatively for the zone must have one of these entries. The @ as seen
28565 here could have been example.org. The @ translates to the origin.
28567 localhost IN A 127.0.0.1
28573 The A record indicates machine names. As seen above, ns1.example.org would
28574 resolve to 3.2.1.2. Again, the origin symbol, @, is used here, thus
28575 meaning example.org would resolve to 3.2.1.30.
28579 The canonical name record is usually used for giving aliases to a machine.
28580 In the example, www is aliased to the machine addressed to the origin, or
28581 example.org (3.2.1.30). CNAMEs can be used to provide alias hostnames, or
28582 round robin one hostname among multiple machines.
28584 @ IN MX 10 mail.example.org.
28586 The MX record indicates which mail servers are responsible for handling
28587 incoming mail for the zone. mail.example.org is the hostname of the mail
28588 server, and 10 being the priority of that mail server.
28590 One can have several mail servers, with priorities of 3, 2, 1. A mail
28591 server attempting to deliver to example.org would first try the highest
28592 priority MX, then the second highest, etc, until the mail can be properly
28595 For in-addr.arpa zone files (reverse DNS), the same format is used, except
28596 with PTR entries instead of A or CNAME.
28600 1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
28607 @ IN NS ns1.example.org.
28608 @ IN NS ns2.example.org.
28610 2 IN PTR ns1.example.org.
28611 3 IN PTR ns2.example.org.
28612 10 IN PTR mail.example.org.
28613 30 IN PTR example.org.
28615 This file gives the proper IP address to hostname mappings of our above
28618 ----------------------------------------------------------------------
28620 19.11.7 Caching Name Server
28622 A caching name server is a name server that is not authoritative for any
28623 zones. It simply asks queries of its own, and remembers them for later
28624 use. To set one up, just configure the name server as usual, omitting any
28625 inclusions of zones.
28627 ----------------------------------------------------------------------
28629 19.11.8 Running named in a Sandbox
28631 For added security you may want to run named(8) as an unprivileged user,
28632 and configure it to chroot(8) into a sandbox directory. This makes
28633 everything outside of the sandbox inaccessible to the named daemon. Should
28634 named be compromised, this will help to reduce the damage that can be
28635 caused. By default, DragonFly has a user and a group called bind, intended
28638 Note: Various people would recommend that instead of configuring named
28639 to chroot, you should run named inside a jail(8). This section does not
28640 attempt to cover this situation.
28642 Since named will not be able to access anything outside of the sandbox
28643 (such as shared libraries, log sockets, and so on), there are a number of
28644 steps that need to be followed in order to allow named to function
28645 correctly. In the following checklist, it is assumed that the path to the
28646 sandbox is /etc/namedb and that you have made no prior modifications to
28647 the contents of this directory. Perform the following steps as root.
28649 * Create all directories that named expects to see:
28652 # mkdir -p bin dev etc var/tmp var/run master slave
28653 # chown bind:bind slave var/*(1)
28656 named only needs write access to these directories, so
28657 that is all we give it.
28658 * Rearrange and create basic zone and configuration files:
28660 # cp /etc/localtime etc(1)
28661 # mv named.conf etc && ln -sf etc/named.conf
28662 # mv named.root master
28663 # sh make-localhost && mv localhost.rev localhost-v6.rev master
28664 # cat > master/named.localhost
28667 @ IN SOA localhost. postmaster.localhost. (
28671 604800 ; expiration
28678 This allows named to log the correct time to syslogd(8)
28679 * Use cp(1) to copy named-xfer in /usr/libexec into your sandbox.
28681 * Make a dev/null that named can see and write to:
28683 # cd /etc/namedb/dev && mknod null c 2 2
28686 * Symlink /var/run/ndc to /etc/namedb/var/run/ndc:
28688 # ln -sf /etc/namedb/var/run/ndc /var/run/ndc
28690 Note: This simply avoids having to specify the -c option to ndc(8)
28691 every time you run it. Since the contents of /var/run are deleted on
28692 boot, if this is something that you find useful you may wish to add
28693 this command to root's crontab, making use of the @reboot option.
28694 See crontab(5) for more information regarding this.
28696 * Configure syslogd(8) to create an extra log socket that named can
28697 write to. To do this, add -l /etc/namedb/dev/log to the syslogd_flags
28698 variable in /etc/rc.conf.
28700 * Arrange to have named start and chroot itself to the sandbox by adding
28701 the following to /etc/rc.conf:
28704 named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"
28706 Note: Note that the configuration file /etc/named.conf is denoted by
28707 a full pathname relative to the sandbox, i.e. in the line above, the
28708 file referred to is actually /etc/namedb/etc/named.conf.
28710 The next step is to edit /etc/namedb/etc/named.conf so that named knows
28711 which zones to load and where to find them on the disk. There follows a
28712 commented example (anything not specifically commented here is no
28713 different from the setup for a DNS server not running in a sandbox):
28717 named-xfer "/bin/named-xfer";(2)
28718 version ""; // Don't reveal BIND version
28719 query-source address * port 53;
28721 // ndc control socket
28723 unix "/var/run/ndc" perm 0600 owner 0 group 0;
28726 zone "localhost" IN {
28728 file "master/named.localhost";(3)
28729 allow-transfer { localhost; };
28732 zone "0.0.127.in-addr.arpa" IN {
28734 file "master/localhost.rev";
28735 allow-transfer { localhost; };
28738 zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.int" {
28740 file "master/localhost-v6.rev";
28741 allow-transfer { localhost; };
28746 file "master/named.root";
28748 zone "private.example.net" in {
28750 file "master/private.example.net.db";
28751 allow-transfer { 192.168.10.0/24; };
28753 zone "10.168.192.in-addr.arpa" in {
28755 masters { 192.168.10.2; };
28756 file "slave/192.168.10.db";(4)
28760 The directory statement is specified as /, since all files that
28761 named needs are within this directory (recall that this is
28762 equivalent to a ``normal'' user's /etc/namedb.
28764 Specifies the full path to the named-xfer binary (from named's
28765 frame of reference). This is necessary since named is compiled to
28766 look for named-xfer in /usr/libexec by default.
28768 Specifies the filename (relative to the directory statement above)
28769 where named can find the zonefile for this zone.
28771 Specifies the filename (relative to the directory statement above)
28772 where named should write a copy of the zonefile for this zone
28773 after successfully transferring it from the master server. This is
28774 why we needed to change the ownership of the directory slave to
28775 bind in the setup stages above.
28777 After completing the steps above, either reboot your server or restart
28778 syslogd(8) and start named(8), making sure to use the new options
28779 specified in syslogd_flags and named_flags. You should now be running a
28780 sandboxed copy of named!
28782 ----------------------------------------------------------------------
28786 Although BIND is the most common implementation of DNS, there is always
28787 the issue of security. Possible and exploitable security holes are
28790 It is a good idea to subscribe to CERT and freebsd-security-notifications
28791 to stay up to date with the current Internet and FreeBSD security issues.
28793 Tip: If a problem arises, keeping sources up to date and having a fresh
28794 build of named would not hurt.
28796 ----------------------------------------------------------------------
28798 19.11.10 Further Reading
28800 BIND/named manual pages: ndc(8) named(8) named.conf(5)
28802 * Official ISC Bind Page
28806 * O'Reilly DNS and BIND 4th Edition
28808 * RFC1034 - Domain Names - Concepts and Facilities
28810 * RFC1035 - Domain Names - Implementation and Specification
28812 ----------------------------------------------------------------------
28816 Contributed by Tom Hukins.
28818 ----------------------------------------------------------------------
28822 Over time, a computer's clock is prone to drift. As time passes, the
28823 computer's clock becomes less accurate. NTP (Network Time Protocol) is one
28824 way to ensure your clock is right.
28826 Many Internet services rely on, or greatly benefit from, computers' clocks
28827 being accurate. For example, a Web server may receive requests to send a
28828 file if it has modified since a certain time. Services such as cron(8) run
28829 commands at a given time. If the clock is inaccurate, these commands may
28830 not run when expected.
28832 DragonFly ships with the ntpd(8) NTP server which can be used to query
28833 other NTP servers to set the clock on your machine or provide time
28834 services to others.
28836 ----------------------------------------------------------------------
28838 19.12.2 Choosing Appropriate NTP Servers
28840 In order to synchronize your clock, you will need to find one or more NTP
28841 servers to use. Your network administrator or ISP may have set up an NTP
28842 server for this purpose--check their documentation to see if this is the
28843 case. There is a list of publicly accessible NTP servers which you can use
28844 to find an NTP server near to you. Make sure you are aware of the policy
28845 for any servers you choose, and ask for permission if required.
28847 Choosing several unconnected NTP servers is a good idea in case one of the
28848 servers you are using becomes unreachable or its clock is unreliable.
28849 ntpd(8) uses the responses it receives from other servers
28850 intelligently--it will favor unreliable servers less than reliable ones.
28852 ----------------------------------------------------------------------
28854 19.12.3 Configuring Your Machine
28856 ----------------------------------------------------------------------
28858 19.12.3.1 Basic Configuration
28860 If you only wish to synchronize your clock when the machine boots up, you
28861 can use ntpdate(8). This may be appropriate for some desktop machines
28862 which are frequently rebooted and only require infrequent synchronization,
28863 but most machines should run ntpd(8).
28865 Using ntpdate(8) at boot time is also a good idea for machines that run
28866 ntpd(8). The ntpd(8) program changes the clock gradually, whereas
28867 ntpdate(8) sets the clock, no matter how great the difference between a
28868 machine's current clock setting and the correct time.
28870 To enable ntpdate(8) at boot time, add ntpdate_enable="YES" to
28871 /etc/rc.conf. You will also need to specify all servers you wish to
28872 synchronize with and any flags to be passed to ntpdate(8) in
28875 ----------------------------------------------------------------------
28877 19.12.3.2 General Configuration
28879 NTP is configured by the /etc/ntp.conf file in the format described in
28880 ntp.conf(5). Here is a simple example:
28882 server ntplocal.example.com prefer
28883 server timeserver.example.org
28884 server ntp2a.example.net
28886 driftfile /var/db/ntp.drift
28888 The server option specifies which servers are to be used, with one server
28889 listed on each line. If a server is specified with the prefer argument, as
28890 with ntplocal.example.com, that server is preferred over other servers. A
28891 response from a preferred server will be discarded if it differs
28892 significantly from other servers' responses, otherwise it will be used
28893 without any consideration to other responses. The prefer argument is
28894 normally used for NTP servers that are known to be highly accurate, such
28895 as those with special time monitoring hardware.
28897 The driftfile option specifies which file is used to store the system
28898 clock's frequency offset. The ntpd(8) program uses this to automatically
28899 compensate for the clock's natural drift, allowing it to maintain a
28900 reasonably correct setting even if it is cut off from all external time
28901 sources for a period of time.
28903 The driftfile option specifies which file is used to store information
28904 about previous responses from the NTP servers you are using. This file
28905 contains internal information for NTP. It should not be modified by any
28908 ----------------------------------------------------------------------
28910 19.12.3.3 Controlling Access to Your Server
28912 By default, your NTP server will be accessible to all hosts on the
28913 Internet. The restrict option in /etc/ntp.conf allows you to control which
28914 machines can access your server.
28916 If you want to deny all machines from accessing your NTP server, add the
28917 following line to /etc/ntp.conf:
28919 restrict default ignore
28921 If you only want to allow machines within your own network to synchronize
28922 their clocks with your server, but ensure they are not allowed to
28923 configure the server or used as peers to synchronize against, add
28925 restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap
28927 instead, where 192.168.1.0 is an IP address on your network and
28928 255.255.255.0 is your network's netmask.
28930 /etc/ntp.conf can contain multiple restrict options. For more details, see
28931 the Access Control Support subsection of ntp.conf(5).
28933 ----------------------------------------------------------------------
28935 19.12.4 Running the NTP Server
28937 To ensure the NTP server is started at boot time, add the line
28938 xntpd_enable="YES" to /etc/rc.conf. If you wish to pass additional flags
28939 to ntpd(8), edit the xntpd_flags parameter in /etc/rc.conf.
28941 To start the server without rebooting your machine, run ntpd being sure to
28942 specify any additional parameters from xntpd_flags in /etc/rc.conf. For
28945 # ntpd -p /var/run/ntpd.pid
28947 ----------------------------------------------------------------------
28949 19.12.5 Using ntpd with a Temporary Internet Connection
28951 The ntpd(8) program does not need a permanent connection to the Internet
28952 to function properly. However, if you have a temporary connection that is
28953 configured to dial out on demand, it is a good idea to prevent NTP traffic
28954 from triggering a dial out or keeping the connection alive. If you are
28955 using user PPP, you can use filter directives in /etc/ppp/ppp.conf. For
28958 set filter dial 0 deny udp src eq 123
28959 # Prevent NTP traffic from initiating dial out
28960 set filter dial 1 permit 0 0
28961 set filter alive 0 deny udp src eq 123
28962 # Prevent incoming NTP traffic from keeping the connection open
28963 set filter alive 1 deny udp dst eq 123
28964 # Prevent outgoing NTP traffic from keeping the connection open
28965 set filter alive 2 permit 0/0 0/0
28967 For more details see the PACKET FILTERING section in ppp(8) and the
28968 examples in /usr/share/examples/ppp/.
28970 Note: Some Internet access providers block low-numbered ports,
28971 preventing NTP from functioning since replies never reach your machine.
28973 ----------------------------------------------------------------------
28975 19.12.6 Further Information
28977 Documentation for the NTP server can be found in /usr/share/doc/ntp/ in
28980 ----------------------------------------------------------------------
28982 19.13 Network Address Translation
28984 Contributed by Chern Lee.
28988 DragonFly's Network Address Translation daemon, commonly known as natd(8)
28989 is a daemon that accepts incoming raw IP packets, changes the source to
28990 the local machine and re-injects these packets back into the outgoing IP
28991 packet stream. natd(8) does this by changing the source IP address and
28992 port such that when data is received back, it is able to determine the
28993 original location of the data and forward it back to its original
28996 The most common use of NAT is to perform what is commonly known as
28997 Internet Connection Sharing.
28999 ----------------------------------------------------------------------
29003 Due to the diminishing IP space in IPv4, and the increased number of users
29004 on high-speed consumer lines such as cable or DSL, people are increasingly
29005 in need of an Internet Connection Sharing solution. The ability to connect
29006 several computers online through one connection and IP address makes
29007 natd(8) a reasonable choice.
29009 Most commonly, a user has a machine connected to a cable or DSL line with
29010 one IP address and wishes to use this one connected computer to provide
29011 Internet access to several more over a LAN.
29013 To do this, the DragonFly machine on the Internet must act as a gateway.
29014 This gateway machine must have two NICs--one for connecting to the
29015 Internet router, the other connecting to a LAN. All the machines on the
29016 LAN are connected through a hub or switch.
29018 _______ __________ ________
29020 | Hub |-----| Client B |-----| Router |----- Internet
29021 |_______| |__________| |________|
29028 A setup like this is commonly used to share an Internet connection. One of
29029 the LAN machines is connected to the Internet. The rest of the machines
29030 access the Internet through that ``gateway'' machine.
29032 ----------------------------------------------------------------------
29034 19.13.3 Configuration
29036 The following options must be in the kernel configuration file:
29041 Additionally, at choice, the following may also be suitable:
29043 options IPFIREWALL_DEFAULT_TO_ACCEPT
29044 options IPFIREWALL_VERBOSE
29046 The following must be in /etc/rc.conf:
29048 gateway_enable="YES"
29049 firewall_enable="YES"
29050 firewall_type="OPEN"
29052 natd_interface="fxp0"
29055 Sets up the machine to act as a gateway. Running
29056 gateway_enable="YES" sysctl net.inet.ip.forwarding=1 would have the same
29058 firewall_enable="YES" Enables the firewall rules in /etc/rc.firewall at
29060 This specifies a predefined firewall ruleset that
29061 firewall_type="OPEN" allows anything in. See /etc/rc.firewall for
29063 natd_interface="fxp0" Indicates which interface to forward packets through
29064 (the interface connected to the Internet).
29065 natd_flags="" Any additional configuration options passed to
29068 Having the previous options defined in /etc/rc.conf would run natd
29069 -interface fxp0 at boot. This can also be run manually.
29071 Note: It is also possible to use a configuration file for natd(8) when
29072 there are too many options to pass. In this case, the configuration file
29073 must be defined by adding the following line to /etc/rc.conf:
29075 natd_flags="-f /etc/natd.conf"
29077 The /etc/natd.conf file will contain a list of configuration options,
29078 one per line. For example the next section case would use the following
29081 redirect_port tcp 192.168.0.2:6667 6667
29082 redirect_port tcp 192.168.0.3:80 80
29084 For more information about the configuration file, consult the natd(8)
29085 manual page about the -f option.
29087 Each machine and interface behind the LAN should be assigned IP address
29088 numbers in the private network space as defined by RFC 1918 and have a
29089 default gateway of the natd machine's internal IP address.
29091 For example, client A and B behind the LAN have IP addresses of
29092 192.168.0.2 and 192.168.0.3, while the natd machine's LAN interface has an
29093 IP address of 192.168.0.1. Client A and B's default gateway must be set to
29094 that of the natd machine, 192.168.0.1. The natd machine's external, or
29095 Internet interface does not require any special modification for natd(8)
29098 ----------------------------------------------------------------------
29100 19.13.4 Port Redirection
29102 The drawback with natd(8) is that the LAN clients are not accessible from
29103 the Internet. Clients on the LAN can make outgoing connections to the
29104 world but cannot receive incoming ones. This presents a problem if trying
29105 to run Internet services on one of the LAN client machines. A simple way
29106 around this is to redirect selected Internet ports on the natd machine to
29109 For example, an IRC server runs on client A, and a web server runs on
29110 client B. For this to work properly, connections received on ports 6667
29111 (IRC) and 80 (web) must be redirected to the respective machines.
29113 The -redirect_port must be passed to natd(8) with the proper options. The
29114 syntax is as follows:
29116 -redirect_port proto targetIP:targetPORT[-targetPORT]
29117 [aliasIP:]aliasPORT[-aliasPORT]
29118 [remoteIP[:remotePORT[-remotePORT]]]
29120 In the above example, the argument should be:
29122 -redirect_port tcp 192.168.0.2:6667 6667
29123 -redirect_port tcp 192.168.0.3:80 80
29125 This will redirect the proper tcp ports to the LAN client machines.
29127 The -redirect_port argument can be used to indicate port ranges over
29128 individual ports. For example, tcp 192.168.0.2:2000-3000 2000-3000 would
29129 redirect all connections received on ports 2000 to 3000 to ports 2000 to
29132 These options can be used when directly running natd(8), placed within the
29133 natd_flags="" option in /etc/rc.conf, or passed via a configuration file.
29135 For further configuration options, consult natd(8)
29137 ----------------------------------------------------------------------
29139 19.13.5 Address Redirection
29141 Address redirection is useful if several IP addresses are available, yet
29142 they must be on one machine. With this, natd(8) can assign each LAN client
29143 its own external IP address. natd(8) then rewrites outgoing packets from
29144 the LAN clients with the proper external IP address and redirects all
29145 traffic incoming on that particular IP address back to the specific LAN
29146 client. This is also known as static NAT. For example, the IP addresses
29147 128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway machine.
29148 128.1.1.1 can be used as the natd gateway machine's external IP address,
29149 while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN clients A and B.
29151 The -redirect_address syntax is as follows:
29153 -redirect_address localIP publicIP
29155 localIP The internal IP address of the LAN client.
29156 publicIP The external IP address corresponding to the LAN client.
29158 In the example, this argument would read:
29160 -redirect_address 192.168.0.2 128.1.1.2
29161 -redirect_address 192.168.0.3 128.1.1.3
29163 Like -redirect_port, these arguments are also placed within the
29164 natd_flags="" option of /etc/rc.conf, or passed via a configuration file.
29165 With address redirection, there is no need for port redirection since all
29166 data received on a particular IP address is redirected.
29168 The external IP addresses on the natd machine must be active and aliased
29169 to the external interface. Look at rc.conf(5) to do so.
29171 ----------------------------------------------------------------------
29173 19.14 The inetd ``Super-Server''
29175 Contributed by Chern Lee.
29179 inetd(8) is referred to as the ``Internet Super-Server'' because it
29180 manages connections for several daemons. Programs that provide network
29181 service are commonly known as daemons. inetd serves as a managing server
29182 for other daemons. When a connection is received by inetd, it determines
29183 which daemon the connection is destined for, spawns the particular daemon
29184 and delegates the socket to it. Running one instance of inetd reduces the
29185 overall system load as compared to running each daemon individually in
29188 Primarily, inetd is used to spawn other daemons, but several trivial
29189 protocols are handled directly, such as chargen, auth, and daytime.
29191 This section will cover the basics in configuring inetd through its
29192 command-line options and its configuration file, /etc/inetd.conf.
29194 ----------------------------------------------------------------------
29198 inetd is initialized through the /etc/rc.conf system. The inetd_enable
29199 option is set to NO by default. Placing:
29207 into /etc/rc.conf can enable or disable inetd starting at boot time.
29209 Additionally, different command-line options can be passed to inetd via
29210 the inetd_flags option.
29212 ----------------------------------------------------------------------
29214 19.14.3 Command-Line Options
29218 inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
29219 [-p filename] [-R rate] [configuration file]
29227 Turn on logging of successful connections.
29231 Turn on TCP Wrapping for external services (on by default).
29235 Turn on TCP Wrapping for internal services which are built into
29236 inetd (on by default).
29240 Specify the default maximum number of simultaneous invocations of
29241 each service; the default is unlimited. May be overridden on a
29242 per-service basis with the max-child parameter.
29246 Specify the default maximum number of times a service can be
29247 invoked from a single IP address in one minute; the default is
29248 unlimited. May be overridden on a per-service basis with the
29249 max-connections-per-ip-per-minute parameter.
29253 Specify the maximum number of times a service can be invoked in
29254 one minute; the default is 256. A rate of 0 allows an unlimited
29255 number of invocations.
29259 Specify one specific IP address to bind to. Alternatively, a
29260 hostname can be specified, in which case the IPv4 or IPv6 address
29261 which corresponds to that hostname is used. Usually a hostname is
29262 specified when inetd is run inside a jail(8), in which case the
29263 hostname corresponds to the jail(8) environment.
29265 When hostname specification is used and both IPv4 and IPv6
29266 bindings are desired, one entry with the appropriate protocol type
29267 for each binding is required for each service in /etc/inetd.conf.
29268 For example, a TCP-based service would need two entries, one using
29269 tcp4 for the protocol and the other using tcp6.
29273 Specify an alternate file in which to store the process ID.
29275 These options can be passed to inetd using the inetd_flags option in
29276 /etc/rc.conf. By default, inetd_flags is set to -wW, which turns on TCP
29277 wrapping for inetd's internal and external services. For novice users,
29278 these parameters usually do not need to be modified or even entered in
29281 Note: An external service is a daemon outside of inetd, which is invoked
29282 when a connection is received for it. On the other hand, an internal
29283 service is one that inetd has the facility of offering within itself.
29285 ----------------------------------------------------------------------
29289 Configuration of inetd is controlled through the /etc/inetd.conf file.
29291 When a modification is made to /etc/inetd.conf, inetd can be forced to
29292 re-read its configuration file by sending a HangUP signal to the inetd
29295 Example 19-4. Sending inetd a HangUP Signal
29297 # kill -HUP `cat /var/run/inetd.pid`
29299 Each line of the configuration file specifies an individual daemon.
29300 Comments in the file are preceded by a ``#''. The format of
29301 /etc/inetd.conf is as follows:
29306 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
29307 user[:group][/login-class]
29309 server-program-arguments
29311 An example entry for the ftpd daemon using IPv4:
29313 ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
29317 This is the service name of the particular daemon. It must
29318 correspond to a service listed in /etc/services. This determines
29319 which port inetd must listen to. If a new service is being
29320 created, it must be placed in /etc/services first.
29324 Either stream, dgram, raw, or seqpacket. stream must be used for
29325 connection-based, TCP daemons, while dgram is used for daemons
29326 utilizing the UDP transport protocol.
29330 One of the following:
29332 +----------------------------------+
29333 | Protocol | Explanation |
29334 |-----------+----------------------|
29335 | tcp, tcp4 | TCP IPv4 |
29336 |-----------+----------------------|
29337 | udp, udp4 | UDP IPv4 |
29338 |-----------+----------------------|
29339 | tcp6 | TCP IPv6 |
29340 |-----------+----------------------|
29341 | udp6 | UDP IPv6 |
29342 |-----------+----------------------|
29343 | tcp46 | Both TCP IPv4 and v6 |
29344 |-----------+----------------------|
29345 | udp46 | Both UDP IPv4 and v6 |
29346 +----------------------------------+
29348 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
29350 wait|nowait indicates whether the daemon invoked from inetd is
29351 able to handle its own socket or not. dgram socket types must use
29352 the wait option, while stream socket daemons, which are usually
29353 multi-threaded, should use nowait. wait usually hands off multiple
29354 sockets to a single daemon, while nowait spawns a child daemon for
29357 The maximum number of child daemons inetd may spawn can be set
29358 using the max-child option. If a limit of ten instances of a
29359 particular daemon is needed, a /10 would be placed after nowait.
29361 In addition to max-child, another option limiting the maximum
29362 connections from a single place to a particular daemon can be
29363 enabled. max-connections-per-ip-per-minute does just this. A value
29364 of ten here would limit any particular IP address connecting to a
29365 particular service to ten attempts per minute. This is useful to
29366 prevent intentional or unintentional resource consumption and
29367 Denial of Service (DoS) attacks to a machine.
29369 In this field, wait or nowait is mandatory. max-child and
29370 max-connections-per-ip-per-minute are optional.
29372 A stream-type multi-threaded daemon without any max-child or
29373 max-connections-per-ip-per-minute limits would simply be: nowait.
29375 The same daemon with a maximum limit of ten daemons would read:
29378 Additionally, the same setup with a limit of twenty connections
29379 per IP address per minute and a maximum total limit of ten child
29380 daemons would read: nowait/10/20.
29382 These options are all utilized by the default settings of the
29383 fingerd daemon, as seen here:
29385 finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s
29389 This is the username that the particular daemon should run as.
29390 Most commonly, daemons run as the root user. For security
29391 purposes, it is common to find some servers running as the daemon
29392 user, or the least privileged nobody user.
29396 The full path of the daemon to be executed when a connection is
29397 received. If the daemon is a service provided by inetd internally,
29398 then internal should be used.
29400 server-program-arguments
29402 This works in conjunction with server-program by specifying the
29403 arguments, starting with argv[0], passed to the daemon on
29404 invocation. If mydaemon -d is the command line, mydaemon -d would
29405 be the value of server-program-arguments. Again, if the daemon is
29406 an internal service, use internal here.
29408 ----------------------------------------------------------------------
29412 Depending on the security profile chosen at install, many of inetd's
29413 daemons may be enabled by default. If there is no apparent need for a
29414 particular daemon, disable it! Place a ``#'' in front of the daemon in
29415 question, and send a hangup signal to inetd. Some daemons, such as
29416 fingerd, may not be desired at all because they provide an attacker with
29417 too much information.
29419 Some daemons are not security-conscious and have long, or non-existent
29420 timeouts for connection attempts. This allows an attacker to slowly send
29421 connections to a particular daemon, thus saturating available resources.
29422 It may be a good idea to place max-connections-per-ip-per-minute and
29423 max-child limitations on certain daemons.
29425 By default, TCP wrapping is turned on. Consult the hosts_access(5) manual
29426 page for more information on placing TCP restrictions on various inetd
29429 ----------------------------------------------------------------------
29431 19.14.6 Miscellaneous
29433 daytime, time, echo, discard, chargen, and auth are all internally
29434 provided services of inetd.
29436 The auth service provides identity (ident, identd) network services, and
29437 is configurable to a certain degree.
29439 Consult the inetd(8) manual page for more in-depth information.
29441 ----------------------------------------------------------------------
29443 19.15 Parallel Line IP (PLIP)
29445 PLIP lets us run TCP/IP between parallel ports. It is useful on machines
29446 without network cards, or to install on laptops. In this section, we will
29449 * Creating a parallel (laplink) cable.
29451 * Connecting two computers with PLIP.
29453 ----------------------------------------------------------------------
29455 19.15.1 Creating a Parallel Cable
29457 You can purchase a parallel cable at most computer supply stores. If you
29458 cannot do that, or you just want to know how it is done, the following
29459 table shows how to make one out of a normal parallel printer cable.
29461 Table 19-1. Wiring a Parallel Cable for Networking
29463 +--------------------------------------------+
29464 | A-name | A-End | B-End | Descr. | Post/Bit |
29465 |--------+-------+-------+--------+----------|
29466 | DATA0 | 2 | 15 | Data | 0/0x01 |
29467 | -ERROR | 15 | 2 | | 1/0x08 |
29468 |--------+-------+-------+--------+----------|
29469 | DATA1 | 3 | 13 | Data | 0/0x02 |
29470 | +SLCT | 13 | 3 | | 1/0x10 |
29471 |--------+-------+-------+--------+----------|
29472 | DATA2 | 4 | 12 | Data | 0/0x04 |
29473 | +PE | 12 | 4 | | 1/0x20 |
29474 |--------+-------+-------+--------+----------|
29475 | DATA3 | 5 | 10 | Strobe | 0/0x08 |
29476 | -ACK | 10 | 5 | | 1/0x40 |
29477 |--------+-------+-------+--------+----------|
29478 | DATA4 | 6 | 11 | Data | 0/0x10 |
29479 | BUSY | 11 | 6 | | 1/0x80 |
29480 |--------+-------+-------+--------+----------|
29481 | GND | 18-25 | 18-25 | GND | - |
29482 +--------------------------------------------+
29484 ----------------------------------------------------------------------
29486 19.15.2 Setting Up PLIP
29488 First, you have to get a laplink cable. Then, confirm that both computers
29489 have a kernel with lpt(4) driver support:
29491 # grep lp /var/run/dmesg.boot
29492 lpt0: <Printer> on ppbus0
29493 lpt0: Interrupt-driven port
29495 The parallel port must be an interrupt driven port. You should have a line
29496 similar to the following in your kernel configuration file:
29498 device ppc0 at isa? irq 7
29500 Then check if the kernel configuration file has a device plip line or if
29501 the plip.ko kernel module is loaded. In both cases the parallel networking
29502 interface should appear when you directly use the ifconfig(8) command.
29505 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
29507 Plug in the laplink cable into the parallel interface on both computers.
29509 Configure the network interface parameters on both sites as root. For
29510 example, if you want connect the host host1 with host2:
29512 host1 <-----> host2
29513 IP Address 10.0.0.1 10.0.0.2
29515 Configure the interface on host1 by doing:
29517 # ifconfig lp0 10.0.0.1 10.0.0.2
29519 Configure the interface on host2 by doing:
29521 # ifconfig lp0 10.0.0.2 10.0.0.1
29523 You now should have a working connection. Please read the manual pages
29524 lp(4) and lpt(4) for more details.
29526 You should also add both hosts to /etc/hosts:
29528 127.0.0.1 localhost.my.domain localhost
29529 10.0.0.1 host1.my.domain host1
29530 10.0.0.2 host2.my.domain
29532 To confirm the connection works, go to each host and ping the other. For
29536 lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500
29537 inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000
29542 Destination Gateway Flags Refs Use Netif Expire
29543 host2 host1 UH 0 0 lp0
29545 PING host2 (10.0.0.2): 56 data bytes
29546 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
29547 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
29548 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
29549 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
29551 --- host2 ping statistics ---
29552 4 packets transmitted, 4 packets received, 0% packet loss
29553 round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms
29555 ----------------------------------------------------------------------
29559 Originally Written by Aaron Kaplan. Restructured and Added by Tom Rhodes.
29561 IPv6 (also know as IPng ``IP next generation'') is the new version of the
29562 well known IP protocol (also know as IPv4). Like the other current *BSD
29563 systems, DragonFly includes the KAME IPv6 reference implementation. So
29564 your DragonFly system comes with all you will need to experiment with
29565 IPv6. This section focuses on getting IPv6 configured and running.
29567 In the early 1990s, people became aware of the rapidly diminishing address
29568 space of IPv4. Given the expansion rate of the Internet there were two
29571 * Running out of addresses. Today this is not so much of a concern
29572 anymore since private address spaces (10.0.0.0/8, 192.168.0.0/24,
29573 etc.) and Network Address Translation (NAT) are being employed.
29575 * Router table entries were getting too large. This is still a concern
29578 IPv6 deals with these and many other issues:
29580 * 128 bit address space. In other words theoretically there are
29581 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
29582 available. This means there are approximately 6.67 * 10^27 IPv6
29583 addresses per square meter on our planet.
29585 * Routers will only store network aggregation addresses in their routing
29586 tables thus reducing the average space of a routing table to 8192
29589 There are also lots of other useful features of IPv6 such as:
29591 * Address autoconfiguration (RFC2462)
29593 * Anycast addresses (``one-out-of many'')
29595 * Mandatory multicast addresses
29597 * IPsec (IP security)
29599 * Simplified header structure
29603 * IPv4-to-IPv6 transition mechanisms
29605 For more information see:
29607 * IPv6 overview at playground.sun.com
29613 ----------------------------------------------------------------------
29615 19.16.1 Background on IPv6 Addresses
29617 There are different types of IPv6 addresses: Unicast, Anycast and
29620 Unicast addresses are the well known addresses. A packet sent to a unicast
29621 address arrives exactly at the interface belonging to the address.
29623 Anycast addresses are syntactically indistinguishable from unicast
29624 addresses but they address a group of interfaces. The packet destined for
29625 an anycast address will arrive at the nearest (in router metric)
29626 interface. Anycast addresses may only be used by routers.
29628 Multicast addresses identify a group of interfaces. A packet destined for
29629 a multicast address will arrive at all interfaces belonging to the
29632 Note: The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
29633 by multicast addresses in IPv6.
29635 Table 19-2. Reserved IPv6 addresses
29637 +------------------------------------------------------------------------+
29638 | IPv6 address | Prefixlength | Description | Notes |
29640 |------------------+--------------+----------------+---------------------|
29641 | :: | 128 bits | unspecified | cf. 0.0.0.0 in IPv4 |
29642 |------------------+--------------+----------------+---------------------|
29643 | ::1 | 128 bits | loopback | cf. 127.0.0.1 in |
29644 | | | address | IPv4 |
29645 |------------------+--------------+----------------+---------------------|
29646 | | | | The lower 32 bits |
29647 | | | | are the IPv4 |
29648 | ::00:xx:xx:xx:xx | 96 bits | embedded IPv4 | address. Also |
29649 | | | | called ``IPv4 |
29650 | | | | compatible IPv6 |
29651 | | | | address'' |
29652 |------------------+--------------+----------------+---------------------|
29653 | | | | The lower 32 bits |
29654 | | | IPv4 mapped | are the IPv4 |
29655 | ::ff:xx:xx:xx:xx | 96 bits | IPv6 address | address. For hosts |
29656 | | | | which do not |
29657 | | | | support IPv6. |
29658 |------------------+--------------+----------------+---------------------|
29659 | fe80:: - feb:: | 10 bits | link-local | cf. loopback |
29660 | | | | address in IPv4 |
29661 |------------------+--------------+----------------+---------------------|
29662 | fec0:: - fef:: | 10 bits | site-local | |
29663 |------------------+--------------+----------------+---------------------|
29664 | ff:: | 8 bits | multicast | |
29665 |------------------+--------------+----------------+---------------------|
29666 | | | | All global unicast |
29667 | | | | addresses are |
29668 | 001 (base 2) | 3 bits | global unicast | assigned from this |
29669 | | | | pool. The first 3 |
29670 | | | | bits are ``001''. |
29671 +------------------------------------------------------------------------+
29673 ----------------------------------------------------------------------
29675 19.16.2 Reading IPv6 Addresses
29677 The canonical form is represented as: x:x:x:x:x:x:x:x, each ``x'' being a
29678 16 Bit hex value. For example FEBC:A574:382B:23C1:AA49:4592:4EFE:9982
29680 Often an address will have long substrings of all zeros therefore each
29681 such substring can be abbreviated by ``::''. For example fe80::1
29682 corresponds to the canonical form fe80:0000:0000:0000:0000:0000:0000:0001.
29684 A third form is to write the last 32 Bit part in the well known (decimal)
29685 IPv4 style with dots ``.'' as separators. For example 2002::10.0.0.1
29686 corresponds to the (hexadecimal) canonical representation
29687 2002:0000:0000:0000:0000:0000:0a00:0001 which in turn is equivalent to
29688 writing 2002::a00:1.
29690 By now the reader should be able to understand the following:
29694 rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
29695 inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
29696 inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
29697 ether 00:00:21:03:08:e1
29698 media: Ethernet autoselect (100baseTX )
29701 fe80::200:21ff:fe03:8e1%rl0 is an auto configured link-local address. It
29702 includes the scrambled Ethernet MAC as part of the auto configuration.
29704 For further information on the structure of IPv6 addresses see RFC3513.
29706 ----------------------------------------------------------------------
29708 19.16.3 Getting Connected
29710 Currently there are four ways to connect to other IPv6 hosts and networks:
29712 * Join the experimental 6bone
29714 * Getting an IPv6 network from your upstream provider. Talk to your
29715 Internet provider for instructions.
29717 * Tunnel via 6-to-4
29719 * Use the net/freenet6 port if you are on a dial-up connection.
29721 Here we will talk on how to connect to the 6bone since it currently seems
29722 to be the most popular way.
29724 First take a look at the 6bone site and find a 6bone connection nearest to
29725 you. Write to the responsible person and with a little bit of luck you
29726 will be given instructions on how to set up your connection. Usually this
29727 involves setting up a GRE (gif) tunnel.
29729 Here is a typical example on setting up a gif(4) tunnel:
29731 # ifconfig gif0 create
29733 gif0: flags=8010<POINTOPOINT,MULTICAST> mtu 1280
29734 # ifconfig gif0 tunnel MY_IPv4_ADDR HIS_IPv4_ADDR
29735 # ifconfig gif0 inet6 alias MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR
29737 Replace the capitalized words by the information you received from the
29738 upstream 6bone node.
29740 This establishes the tunnel. Check if the tunnel is working by ping6(8)
29741 'ing ff02::1%gif0. You should receive two ping replies.
29743 Note: In case you are intrigued by the address ff02:1%gif0, this is a
29744 multicast address. %gif0 states that the multicast address at network
29745 interface gif0 is to be used. Since we ping a multicast address the
29746 other endpoint of the tunnel should reply as well.
29748 By now setting up a route to your 6bone uplink should be rather
29751 # route add -inet6 default -interface gif0
29752 # ping6 -n MY_UPLINK
29754 # traceroute6 www.jp.FreeBSD.org
29755 (3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
29756 1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms
29757 2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms *
29758 3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms
29759 4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms
29760 5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms
29761 6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 ms
29763 This output will differ from machine to machine. By now you should be able
29764 to reach the IPv6 site www.kame.net and see the dancing tortoise -- that
29765 is if you have a IPv6 enabled browser such as www/mozilla.
29767 ----------------------------------------------------------------------
29769 19.16.4 DNS in the IPv6 World
29771 There are two new types of DNS records for IPv6:
29777 Using AAAA records is straightforward. Assign your hostname to the new
29778 IPv6 address you just got by adding:
29780 MYHOSTNAME AAAA MYIPv6ADDR
29782 To your primary zone DNS file. In case you do not serve your own DNS zones
29783 ask your DNS provider. Current versions of bind (version 8.3 and 9)
29784 support AAAA records.
29786 ----------------------------------------------------------------------
29788 Chapter 20 Electronic Mail
29790 Original work by Bill Lloyd. Rewritten by Jim Mock.
29794 ``Electronic Mail'', better known as email, is one of the most widely used
29795 forms of communication today. This chapter provides a basic introduction
29796 to running a mail server on DragonFly, as well as an introduction to
29797 sending and receiving email using DragonFly; however, it is not a complete
29798 reference and in fact many important considerations are omitted. For more
29799 complete coverage of the subject, the reader is referred to the many
29800 excellent books listed in Appendix B.
29802 After reading this chapter, you will know:
29804 * What software components are involved in sending and receiving
29807 * Where basic sendmail configuration files are located in DragonFly.
29809 * The difference between remote and local mailboxes.
29811 * How to block spammers from illegally using your mail server as a
29814 * How to install and configure an alternate Mail Transfer Agent on your
29815 system, replacing sendmail.
29817 * How to troubleshoot common mail server problems.
29819 * How to use SMTP with UUCP.
29821 * How to set up the system to send mail only.
29823 * How to use mail with a dialup connection.
29825 * How to configure SMTP Authentication for added security.
29827 * How to install and use a Mail User Agent, such as mutt to send and
29830 * How to download your mail from a remote POP or IMAP server.
29832 * How to automatically apply filters and rules to incoming email.
29834 Before reading this chapter, you should:
29836 * Properly set up your network connection (Chapter 19).
29838 * Properly set up the DNS information for your mail host (Chapter 19).
29840 * Know how to install additional third-party software (Chapter 4).
29842 ----------------------------------------------------------------------
29844 20.2 Using Electronic Mail
29846 There are five major parts involved in an email exchange. They are: the
29847 user program, the server daemon, DNS, a remote or local mailbox, and of
29848 course, the mailhost itself.
29850 ----------------------------------------------------------------------
29852 20.2.1 The User Program
29854 This includes command line programs such as mutt, pine, elm, and mail, and
29855 GUI programs such as balsa, xfmail to name a few, and something more
29856 ``sophisticated'' like a WWW browser. These programs simply pass off the
29857 email transactions to the local ``mailhost'', either by calling one of the
29858 server daemons available, or delivering it over TCP.
29860 ----------------------------------------------------------------------
29862 20.2.2 Mailhost Server Daemon
29864 DragonFly ships with sendmail by default, but also support numerous other
29865 mail server daemons, just some of which include:
29873 The server daemon usually has two functions--it is responsible for
29874 receiving incoming mail as well as delivering outgoing mail. It is not
29875 responsible for the collection of mail using protocols such as POP or IMAP
29876 to read your email, nor does it allow connecting to local mbox or Maildir
29877 mailboxes. You may require an additional daemon for that.
29879 Warning: Older versions of sendmail have some serious security issues
29880 which may result in an attacker gaining local and/or remote access to
29881 your machine. Make sure that you are running a current version to avoid
29882 these problems. Optionally, install an alternative MTA from the
29883 DragonFly Pkgsrc Collection.
29885 ----------------------------------------------------------------------
29887 20.2.3 Email and DNS
29889 The Domain Name System (DNS) and its daemon named play a large role in the
29890 delivery of email. In order to deliver mail from your site to another, the
29891 server daemon will look up the remote site in the DNS to determine the
29892 host that will receive mail for the destination. This process also occurs
29893 when mail is sent from a remote host to your mail server.
29895 DNS is responsible for mapping hostnames to IP addresses, as well as for
29896 storing information specific to mail delivery, known as MX records. The MX
29897 (Mail eXchanger) record specifies which host, or hosts, will receive mail
29898 for a particular domain. If you do not have an MX record for your hostname
29899 or domain, the mail will be delivered directly to your host provided you
29900 have an A record pointing your hostname to your IP address.
29902 You may view the MX records for any domain by using the host(1) command,
29903 as seen in the example below:
29905 % host -t mx DragonflyBSD.org
29906 DragonflyBSD.org mail is handled (pri=10) by crater.dragonflybsd.org
29908 ----------------------------------------------------------------------
29910 20.2.4 Receiving Mail
29912 Receiving mail for your domain is done by the mail host. It will collect
29913 all mail sent to your domain and store it either in mbox (the default
29914 method for storing mail) or Maildir format, depending on your
29915 configuration. Once mail has been stored, it may either be read locally
29916 using applications such as mail(1) or mutt, or remotely accessed and
29917 collected using protocols such as POP or IMAP. This means that should you
29918 only wish to read mail locally, you are not required to install a POP or
29921 ----------------------------------------------------------------------
29923 20.2.4.1 Accessing remote mailboxes using POP and IMAP
29925 In order to access mailboxes remotely, you are required to have access to
29926 a POP or IMAP server. These protocols allow users to connect to their
29927 mailboxes from remote locations with ease. Though both POP and IMAP allow
29928 users to remotely access mailboxes, IMAP offers many advantages, some of
29931 * IMAP can store messages on a remote server as well as fetch them.
29933 * IMAP supports concurrent updates.
29935 * IMAP can be extremely useful over low-speed links as it allows users
29936 to fetch the structure of messages without downloading them; it can
29937 also perform tasks such as searching on the server in order to
29938 minimize data transfer between clients and servers.
29940 In order to install a POP or IMAP server, the following steps should be
29943 1. Choose an IMAP or POP server that best suits your needs. The following
29944 POP and IMAP servers are well known and serve as some good examples:
29954 2. Install the POP or IMAP daemon of your choosing from the ports
29957 3. Where required, modify /etc/inetd.conf to load the POP or IMAP server.
29959 Warning: It should be noted that both POP and IMAP transmit information,
29960 including username and password credentials in clear-text. This means
29961 that if you wish to secure the transmission of information across these
29962 protocols, you should consider tunneling sessions over ssh(1). Tunneling
29963 sessions is described in Section 10.10.7.
29965 ----------------------------------------------------------------------
29967 20.2.4.2 Accessing local mailboxes
29969 Mailboxes may be accessed locally by directly utilizing MUAs on the server
29970 on which the mailbox resides. This can be done using applications such as
29973 ----------------------------------------------------------------------
29975 20.2.5 The Mail Host
29977 The mail host is the name given to a server that is responsible for
29978 delivering and receiving mail for your host, and possibly your network.
29980 ----------------------------------------------------------------------
29982 20.3 sendmail Configuration
29984 Contributed by Christopher Shumway.
29986 sendmail(8) is the default Mail Transfer Agent (MTA) in DragonFly.
29987 sendmail's job is to accept mail from Mail User Agents (MUA) and deliver
29988 it to the appropriate mailer as defined by its configuration file.
29989 sendmail can also accept network connections and deliver mail to local
29990 mailboxes or deliver it to another program.
29992 sendmail uses the following configuration files:
29994 +-----------------------------------------------------------------------+
29995 | Filename | Function |
29996 |----------------------------+------------------------------------------|
29997 | /etc/mail/access | sendmail access database file |
29998 |----------------------------+------------------------------------------|
29999 | /etc/mail/aliases | Mailbox aliases |
30000 |----------------------------+------------------------------------------|
30001 | /etc/mail/local-host-names | Lists of hosts sendmail accepts mail for |
30002 |----------------------------+------------------------------------------|
30003 | /etc/mail/mailer.conf | Mailer program configuration |
30004 |----------------------------+------------------------------------------|
30005 | /etc/mail/mailertable | Mailer delivery table |
30006 |----------------------------+------------------------------------------|
30007 | /etc/mail/sendmail.cf | sendmail master configuration file |
30008 |----------------------------+------------------------------------------|
30009 | /etc/mail/virtusertable | Virtual users and domain tables |
30010 +-----------------------------------------------------------------------+
30012 ----------------------------------------------------------------------
30014 20.3.1 /etc/mail/access
30016 The access database defines what host(s) or IP addresses have access to
30017 the local mail server and what kind of access they have. Hosts can be
30018 listed as OK, REJECT, RELAY or simply passed to sendmail's error handling
30019 routine with a given mailer error. Hosts that are listed as OK, which is
30020 the default, are allowed to send mail to this host as long as the mail's
30021 final destination is the local machine. Hosts that are listed as REJECT
30022 are rejected for all mail connections. Hosts that have the RELAY option
30023 for their hostname are allowed to send mail for any destination through
30026 Example 20-1. Configuring the sendmail Access Database
30028 cyberspammer.com 550 We don't accept mail from spammers
30029 FREE.STEALTH.MAILER@ 550 We don't accept mail from spammers
30030 another.source.of.spam REJECT
30031 okay.cyberspammer.com OK
30034 In this example we have five entries. Mail senders that match the left
30035 hand side of the table are affected by the action on the right side of the
30036 table. The first two examples give an error code to sendmail's error
30037 handling routine. The message is printed to the remote host when a mail
30038 matches the left hand side of the table. The next entry rejects mail from
30039 a specific host on the Internet, another.source.of.spam. The next entry
30040 accepts mail connections from a host okay.cyberspammer.com, which is more
30041 exact than the cyberspammer.com line above. More specific matches override
30042 less exact matches. The last entry allows relaying of electronic mail from
30043 hosts with an IP address that begins with 128.32. These hosts would be
30044 able to send mail through this mail server that are destined for other
30047 When this file is updated, you need to run make in /etc/mail/ to update
30050 ----------------------------------------------------------------------
30052 20.3.2 /etc/mail/aliases
30054 The aliases database contains a list of virtual mailboxes that are
30055 expanded to other user(s), files, programs or other aliases. Here are a
30056 few examples that can be used in /etc/mail/aliases:
30058 Example 20-2. Mail Aliases
30061 ftp-bugs: joe,eric,paul
30062 bit.bucket: /dev/null
30063 procmail: "|/usr/local/bin/procmail"
30065 The file format is simple; the mailbox name on the left side of the colon
30066 is expanded to the target(s) on the right. The first example simply
30067 expands the mailbox root to the mailbox localuser, which is then looked up
30068 again in the aliases database. If no match is found, then the message is
30069 delivered to the local user localuser. The next example shows a mail list.
30070 Mail to the mailbox ftp-bugs is expanded to the three local mailboxes joe,
30071 eric, and paul. Note that a remote mailbox could be specified as
30072 user@example.com. The next example shows writing mail to a file, in this
30073 case /dev/null. The last example shows sending mail to a program, in this
30074 case the mail message is written to the standard input of
30075 /usr/local/bin/procmail through a UNIX pipe.
30077 When this file is updated, you need to run make in /etc/mail/ to update
30080 ----------------------------------------------------------------------
30082 20.3.3 /etc/mail/local-host-names
30084 This is a list of hostnames sendmail(8) is to accept as the local host
30085 name. Place any domains or hosts that sendmail is to be receiving mail
30086 for. For example, if this mail server was to accept mail for the domain
30087 example.com and the host mail.example.com, its local-host-names might look
30088 something like this:
30093 When this file is updated, sendmail(8) needs to be restarted to read the
30096 ----------------------------------------------------------------------
30098 20.3.4 /etc/mail/sendmail.cf
30100 sendmail's master configuration file, sendmail.cf controls the overall
30101 behavior of sendmail, including everything from rewriting e-mail addresses
30102 to printing rejection messages to remote mail servers. Naturally, with
30103 such a diverse role, this configuration file is quite complex and its
30104 details are a bit out of the scope of this section. Fortunately, this file
30105 rarely needs to be changed for standard mail servers.
30107 The master sendmail configuration file can be built from m4(1) macros that
30108 define the features and behavior of sendmail. Please see
30109 /usr/src/contrib/sendmail/cf/README for some of the details.
30111 When changes to this file are made, sendmail needs to be restarted for the
30112 changes to take effect.
30114 ----------------------------------------------------------------------
30116 20.3.5 /etc/mail/virtusertable
30118 The virtusertable maps mail addresses for virtual domains and mailboxes to
30119 real mailboxes. These mailboxes can be local, remote, aliases defined in
30120 /etc/mail/aliases or files.
30122 Example 20-3. Example Virtual Domain Mail Map
30124 root@example.com root
30125 postmaster@example.com postmaster@noc.example.net
30128 In the above example, we have a mapping for a domain example.com. This
30129 file is processed in a first match order down the file. The first item
30130 maps root@example.com to the local mailbox root. The next entry maps
30131 postmaster@example.com to the mailbox postmaster on the host
30132 noc.example.net. Finally, if nothing from example.com has matched so far,
30133 it will match the last mapping, which matches every other mail message
30134 addressed to someone at example.com. This will be mapped to the local
30137 ----------------------------------------------------------------------
30139 20.4 Changing Your Mail Transfer Agent
30141 Written by Andrew Boothman. Information taken from e-mails written by
30142 Gregory Neil Shapiro.
30144 As already mentioned, DragonFly comes with sendmail already installed as
30145 your MTA (Mail Transfer Agent). Therefore by default it is in charge of
30146 your outgoing and incoming mail.
30148 However, for a variety of reasons, some system administrators want to
30149 change their system's MTA. These reasons range from simply wanting to try
30150 out another MTA to needing a specific feature or package which relies on
30151 another mailer. Fortunately, whatever the reason, DragonFly makes it easy
30152 to make the change.
30154 ----------------------------------------------------------------------
30156 20.4.1 Install a New MTA
30158 You have a wide choice of MTAs available. A good starting point is the
30159 pkgsrc collectionor where you will be able to find many. Of course you are
30160 free to use any MTA you want from any location, as long as you can make it
30161 run under DragonFly.
30163 Start by installing your new MTA. Once it is installed it gives you a
30164 chance to decide if it really fulfills your needs, and also gives you the
30165 opportunity to configure your new software before getting it to take over
30166 from sendmail. When doing this, you should be sure that installing the new
30167 software will not attempt to overwrite system binaries such as
30168 /usr/bin/sendmail. Otherwise, your new mail software has essentially been
30169 put into service before you have configured it.
30171 Please refer to your chosen MTA's documentation for information on how to
30172 configure the software you have chosen.
30174 ----------------------------------------------------------------------
30176 20.4.2 Disable sendmail
30178 In order to completely disable sendmail you must use
30180 sendmail_enable="NONE"
30184 Warning: If you disable sendmail's outgoing mail service in this way, it
30185 is important that you replace it with a fully working alternative mail
30186 delivery system. If you choose not to, system functions such as
30187 periodic(8) will be unable to deliver their results by e-mail as they
30188 would normally expect to. Many parts of your system may expect to have a
30189 functional sendmail-compatible system. If applications continue to use
30190 sendmail's binaries to try to send e-mail after you have disabled them,
30191 mail could go into an inactive sendmail queue, and never be delivered.
30193 If you only want to disable sendmail's incoming mail service, you should
30196 sendmail_enable="NO"
30198 in /etc/rc.conf. More information on sendmail's startup options is
30199 available from the rc.sendmail(8) manual page.
30201 ----------------------------------------------------------------------
30203 20.4.3 Running Your New MTA on Boot
30205 You may have a choice of two methods for running your new MTA on boot,
30206 again depending on what version of DragonFly you are running.
30208 With later versions of DragonFly, you can use the above method or you can
30211 mta_start_script="filename"
30213 in /etc/rc.conf, where filename is the name of some script that you want
30214 executed at boot to start your MTA.
30216 ----------------------------------------------------------------------
30218 20.4.4 Replacing sendmail as the System's Default Mailer
30220 The program sendmail is so ubiquitous as standard software on UNIX systems
30221 that some software just assumes it is already installed and configured.
30222 For this reason, many alternative MTA's provide their own compatible
30223 implementations of the sendmail command-line interface; this facilitates
30224 using them as ``drop-in'' replacements for sendmail.
30226 Therefore, if you are using an alternative mailer, you will need to make
30227 sure that software trying to execute standard sendmail binaries such as
30228 /usr/bin/sendmail actually executes your chosen mailer instead.
30229 Fortunately, DragonFly provides a system called mailwrapper(8) that does
30232 When sendmail is operating as installed, you will find something like the
30233 following in /etc/mail/mailer.conf:
30235 sendmail /usr/libexec/sendmail/sendmail
30236 send-mail /usr/libexec/sendmail/sendmail
30237 mailq /usr/libexec/sendmail/sendmail
30238 newaliases /usr/libexec/sendmail/sendmail
30239 hoststat /usr/libexec/sendmail/sendmail
30240 purgestat /usr/libexec/sendmail/sendmail
30242 This means that when any of these common commands (such as sendmail
30243 itself) are run, the system actually invokes a copy of mailwrapper named
30244 sendmail, which checks mailer.conf and executes
30245 /usr/libexec/sendmail/sendmail instead. This system makes it easy to
30246 change what binaries are actually executed when these default sendmail
30247 functions are invoked.
30249 Therefore if you wanted /usr/local/supermailer/bin/sendmail-compat to be
30250 run instead of sendmail, you could change /etc/mail/mailer.conf to read:
30252 sendmail /usr/local/supermailer/bin/sendmail-compat
30253 send-mail /usr/local/supermailer/bin/sendmail-compat
30254 mailq /usr/local/supermailer/bin/mailq-compat
30255 newaliases /usr/local/supermailer/bin/newaliases-compat
30256 hoststat /usr/local/supermailer/bin/hoststat-compat
30257 purgestat /usr/local/supermailer/bin/purgestat-compat
30259 ----------------------------------------------------------------------
30263 Once you have everything configured the way you want it, you should either
30264 kill the sendmail processes that you no longer need and start the
30265 processes belonging to your new software, or simply reboot. Rebooting will
30266 also give you the opportunity to ensure that you have correctly configured
30267 your system to start your new MTA automatically on boot.
30269 ----------------------------------------------------------------------
30271 20.5 Troubleshooting
30273 20.5.1. Why do I have to use the FQDN for hosts on my site?
30275 20.5.2. sendmail says ``mail loops back to myself''
30277 20.5.3. How can I run a mail server on a dial-up PPP host?
30279 20.5.4. Why do I keep getting ``Relaying Denied'' errors when sending mail
30282 20.5.1. Why do I have to use the FQDN for hosts on my site?
30284 You will probably find that the host is actually in a different domain;
30285 for example, if you are in foo.bar.edu and you wish to reach a host called
30286 mumble in the bar.edu domain, you will have to refer to it by the
30287 fully-qualified domain name, mumble.bar.edu, instead of just mumble.
30289 Traditionally, this was allowed by BSD BIND resolvers. However the current
30290 version of BIND that ships with DragonFly no longer provides default
30291 abbreviations for non-fully qualified domain names other than the domain
30292 you are in. So an unqualified host mumble must either be found as
30293 mumble.foo.bar.edu, or it will be searched for in the root domain.
30295 This is different from the previous behavior, where the search continued
30296 across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535 for why
30297 this was considered bad practice, or even a security hole.
30299 As a good workaround, you can place the line:
30301 search foo.bar.edu bar.edu
30303 instead of the previous:
30307 into your /etc/resolv.conf. However, make sure that the search order does
30308 not go beyond the ``boundary between local and public administration'', as
30311 20.5.2. sendmail says ``mail loops back to myself''
30313 This is answered in the sendmail FAQ as follows:
30315 I'm getting these error messages:
30317 553 MX list for domain.net points back to relay.domain.net
30318 554 <user@domain.net>... Local configuration error
30320 How can I solve this problem?
30322 You have asked mail to the domain (e.g., domain.net) to be
30323 forwarded to a specific host (in this case, relay.domain.net)
30324 by using an MX record, but the relay machine does not recognize
30325 itself as domain.net. Add domain.net to /etc/mail/local-host-names
30326 [known as /etc/sendmail.cw prior to version 8.10]
30327 (if you are using FEATURE(use_cw_file)) or add ``Cw domain.net''
30328 to /etc/mail/sendmail.cf.
30330 The sendmail FAQ can be found at http://www.sendmail.org/faq/ and is
30331 recommended reading if you want to do any ``tweaking'' of your mail setup.
30333 20.5.3. How can I run a mail server on a dial-up PPP host?
30335 You want to connect a DragonFly box on a LAN to the Internet. The
30336 DragonFly box will be a mail gateway for the LAN. The PPP connection is
30339 There are at least two ways to do this. One way is to use UUCP.
30341 Another way is to get a full-time Internet server to provide secondary MX
30342 services for your domain. For example, if your company's domain is
30343 example.com and your Internet service provider has set example.net up to
30344 provide secondary MX services to your domain:
30346 example.com. MX 10 example.com.
30349 Only one host should be specified as the final recipient (add Cw
30350 example.com in /etc/mail/sendmail.cf on example.com).
30352 When the sending sendmail is trying to deliver the mail it will try to
30353 connect to you (example.com) over the modem link. It will most likely time
30354 out because you are not online. The program sendmail will automatically
30355 deliver it to the secondary MX site, i.e. your Internet provider
30356 (example.net). The secondary MX site will then periodically try to connect
30357 to your host and deliver the mail to the primary MX host (example.com).
30359 You might want to use something like this as a login script:
30362 # Put me in /usr/local/bin/pppmyisp
30363 ( sleep 60 ; /usr/sbin/sendmail -q ) &
30364 /usr/sbin/ppp -direct pppmyisp
30366 If you are going to create a separate login script for a user you could
30367 use sendmail -qRexample.com instead in the script above. This will force
30368 all mail in your queue for example.com to be processed immediately.
30370 A further refinement of the situation is as follows:
30372 Message stolen from the FreeBSD Internet service provider's mailing list.
30374 > we provide the secondary MX for a customer. The customer connects to
30375 > our services several times a day automatically to get the mails to
30376 > his primary MX (We do not call his site when a mail for his domains
30377 > arrived). Our sendmail sends the mailqueue every 30 minutes. At the
30378 > moment he has to stay 30 minutes online to be sure that all mail is
30379 > gone to the primary MX.
30381 > Is there a command that would initiate sendmail to send all the mails
30382 > now? The user has not root-privileges on our machine of course.
30384 In the ``privacy flags'' section of sendmail.cf, there is a
30385 definition Opgoaway,restrictqrun
30387 Remove restrictqrun to allow non-root users to start the queue processing.
30388 You might also like to rearrange the MXs. We are the 1st MX for our
30389 customers like this, and we have defined:
30391 # If we are the best MX for a host, try directly instead of generating
30392 # local config error.
30395 That way a remote site will deliver straight to you, without trying
30396 the customer connection. You then send to your customer. Only works for
30397 ``hosts'', so you need to get your customer to name their mail
30398 machine ``customer.com'' as well as
30399 ``hostname.customer.com'' in the DNS. Just put an A record in
30400 the DNS for ``customer.com''.
30402 20.5.4. Why do I keep getting ``Relaying Denied'' errors when sending mail
30405 In default DragonFly installations, sendmail is configured to only send
30406 mail from the host it is running on. For example, if a POP server is
30407 available, then users will be able to check mail from school, work, or
30408 other remote locations but they still will not be able to send outgoing
30409 emails from outside locations. Typically, a few moments after the attempt,
30410 an email will be sent from MAILER-DAEMON with a ``5.7 Relaying Denied''
30413 There are several ways to get around this. The most straightforward
30414 solution is to put your ISP's address in a relay-domains file at
30415 /etc/mail/relay-domains. A quick way to do this would be:
30417 # echo "your.isp.example.com" > /etc/mail/relay-domains
30419 After creating or editing this file you must restart sendmail. This works
30420 great if you are a server administrator and do not wish to send mail
30421 locally, or would like to use a point and click client/system on another
30422 machine or even another ISP. It is also very useful if you only have one
30423 or two email accounts set up. If there is a large number of addresses to
30424 add, you can simply open this file in your favorite text editor and then
30425 add the domains, one per line:
30427 your.isp.example.com
30428 other.isp.example.net
30429 users-isp.example.org
30432 Now any mail sent through your system, by any host in this list (provided
30433 the user has an account on your system), will succeed. This is a very nice
30434 way to allow users to send mail from your system remotely without allowing
30435 people to send SPAM through your system.
30437 ----------------------------------------------------------------------
30439 20.6 Advanced Topics
30441 The following section covers more involved topics such as mail
30442 configuration and setting up mail for your entire domain.
30444 ----------------------------------------------------------------------
30446 20.6.1 Basic Configuration
30448 Out of the box, you should be able to send email to external hosts as long
30449 as you have set up /etc/resolv.conf or are running your own name server.
30450 If you would like to have mail for your host delivered to the MTA (e.g.,
30451 sendmail) on your own DragonFly host, there are two methods:
30453 * Run your own name server and have your own domain. For example,
30456 * Get mail delivered directly to your host. This is done by delivering
30457 mail directly to the current DNS name for your machine. For example,
30458 example.dragonflybsd.org.
30460 Regardless of which of the above you choose, in order to have mail
30461 delivered directly to your host, it must have a permanent static IP
30462 address (not a dynamic address, as with most PPP dial-up configurations).
30463 If you are behind a firewall, it must pass SMTP traffic on to you. If you
30464 want to receive mail directly at your host, you need to be sure of either
30467 * Make sure that the (lowest-numbered) MX record in your DNS points to
30468 your host's IP address.
30470 * Make sure there is no MX entry in your DNS for your host.
30472 Either of the above will allow you to receive mail directly at your host.
30477 example.dragonflybsd.org
30478 # host example.dragonflybsd.org
30479 example.dragonflybsd.org has address 204.216.27.XX
30481 If that is what you see, mail directly to
30482 <yourlogin@example.dragonflybsd.org> should work without problems
30483 (assuming sendmail is running correctly on example.dragonflybsd.org).
30485 If instead you see something like this:
30487 # host example.dragonflybsd.org
30488 example.dragonflybsd.org has address 204.216.27.XX
30489 example.dragonflybsd.org mail is handled (pri=10) by hub.dragonflybsd.org
30491 All mail sent to your host (example.dragonflybsd.org) will end up being
30492 collected on hub under the same username instead of being sent directly to
30495 The above information is handled by your DNS server. The DNS record that
30496 carries mail routing information is the Mail eXchange entry. If no MX
30497 record exists, mail will be delivered directly to the host by way of its
30500 The MX entry for freefall.FreeBSD.org at one time looked like this:
30502 freefall MX 30 mail.crl.net
30503 freefall MX 40 agora.rdrop.com
30504 freefall MX 10 freefall.FreeBSD.org
30505 freefall MX 20 who.cdrom.com
30507 As you can see, freefall had many MX entries. The lowest MX number is the
30508 host that receives mail directly if available; if it is not accessible for
30509 some reason, the others (sometimes called ``backup MXes'') accept messages
30510 temporarily, and pass it along when a lower-numbered host becomes
30511 available, eventually to the lowest-numbered host.
30513 Alternate MX sites should have separate Internet connections from your own
30514 in order to be most useful. Your ISP or another friendly site should have
30515 no problem providing this service for you.
30517 ----------------------------------------------------------------------
30519 20.6.2 Mail for Your Domain
30521 In order to set up a ``mailhost'' (a.k.a. mail server) you need to have
30522 any mail sent to various workstations directed to it. Basically, you want
30523 to ``claim'' any mail for any hostname in your domain (in this case
30524 *.dragonflybsd.org) and divert it to your mail server so your users can
30525 receive their mail on the master mail server.
30527 To make life easiest, a user account with the same username should exist
30528 on both machines. Use adduser(8) to do this.
30530 The mailhost you will be using must be the designated mail exchanger for
30531 each workstation on the network. This is done in your DNS configuration
30534 example.dragonflybsd.org A 204.216.27.XX ; Workstation
30535 MX 10 hub.dragonflybsd.org ; Mailhost
30537 This will redirect mail for the workstation to the mailhost no matter
30538 where the A record points. The mail is sent to the MX host.
30540 You cannot do this yourself unless you are running a DNS server. If you
30541 are not, or cannot run your own DNS server, talk to your ISP or whoever
30544 If you are doing virtual email hosting, the following information will
30545 come in handy. For this example, we will assume you have a customer with
30546 his own domain, in this case customer1.org, and you want all the mail for
30547 customer1.org sent to your mailhost, mail.myhost.com. The entry in your
30548 DNS should look like this:
30550 customer1.org MX 10 mail.myhost.com
30552 You do not need an A record for customer1.org if you only want to handle
30553 email for that domain.
30555 Note: Be aware that pinging customer1.org will not work unless an A
30556 record exists for it.
30558 The last thing that you must do is tell sendmail on your mailhost what
30559 domains and/or hostnames it should be accepting mail for. There are a few
30560 different ways this can be done. Either of the following will work:
30562 * Add the hosts to your /etc/mail/local-host-names file if you are using
30563 the FEATURE(use_cw_file).
30565 * Add a Cwyour.host.com line to your /etc/mail/sendmail.cf.
30567 ----------------------------------------------------------------------
30569 20.7 SMTP with UUCP
30571 The sendmail configuration that ships with DragonFly is designed for sites
30572 that connect directly to the Internet. Sites that wish to exchange their
30573 mail via UUCP must install another sendmail configuration file.
30575 Tweaking /etc/mail/sendmail.cf manually is an advanced topic. sendmail
30576 version 8 generates config files via m4(1) preprocessing, where the actual
30577 configuration occurs on a higher abstraction level. The m4(1)
30578 configuration files can be found under /usr/src/usr.sbin/sendmail/cf.
30580 If you did not install your system with full sources, the sendmail
30581 configuration set has been broken out into a separate source distribution
30582 tarball. Assuming you have your DragonFly source code CDROM mounted, do:
30585 # cat scontrib.?? | tar xzf - -C /usr/src/contrib/sendmail
30587 This extracts to only a few hundred kilobytes. The file README in the cf
30588 directory can serve as a basic introduction to m4(1) configuration.
30590 The best way to support UUCP delivery is to use the mailertable feature.
30591 This creates a database that sendmail can use to make routing decisions.
30593 First, you have to create your .mc file. The directory
30594 /usr/src/usr.sbin/sendmail/cf/cf contains a few examples. Assuming you
30595 have named your file foo.mc, all you need to do in order to convert it
30596 into a valid sendmail.cf is:
30598 # cd /usr/src/usr.sbin/sendmail/cf/cf
30600 # cp foo.cf /etc/mail/sendmail.cf
30602 A typical .mc file might look like:
30604 VERSIONID(`Your version number') OSTYPE(bsd4.4)
30606 FEATURE(accept_unresolvable_domains)
30607 FEATURE(nocanonify)
30608 FEATURE(mailertable, `hash -o /etc/mail/mailertable')
30610 define(`UUCP_RELAY', your.uucp.relay)
30611 define(`UUCP_MAX_SIZE', 200000)
30612 define(`confDONT_PROBE_INTERFACES')
30618 Cw your.alias.host.name
30619 Cw youruucpnodename.UUCP
30621 The lines containing accept_unresolvable_domains, nocanonify, and
30622 confDONT_PROBE_INTERFACES features will prevent any usage of the DNS
30623 during mail delivery. The UUCP_RELAY clause is needed to support UUCP
30624 delivery. Simply put an Internet hostname there that is able to handle
30625 .UUCP pseudo-domain addresses; most likely, you will enter the mail relay
30628 Once you have this, you need an /etc/mail/mailertable file. If you have
30629 only one link to the outside that is used for all your mails, the
30630 following file will suffice:
30633 # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable
30634 . uucp-dom:your.uucp.relay
30636 A more complex example might look like this:
30639 # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable
30641 horus.interface-business.de uucp-dom:horus
30642 .interface-business.de uucp-dom:if-bus
30643 interface-business.de uucp-dom:if-bus
30644 .heep.sax.de smtp8:%1
30645 horus.UUCP uucp-dom:horus
30646 if-bus.UUCP uucp-dom:if-bus
30649 The first three lines handle special cases where domain-addressed mail
30650 should not be sent out to the default route, but instead to some UUCP
30651 neighbor in order to ``shortcut'' the delivery path. The next line handles
30652 mail to the local Ethernet domain that can be delivered using SMTP.
30653 Finally, the UUCP neighbors are mentioned in the .UUCP pseudo-domain
30654 notation, to allow for a uucp-neighbor !recipient override of the default
30655 rules. The last line is always a single dot, matching everything else,
30656 with UUCP delivery to a UUCP neighbor that serves as your universal mail
30657 gateway to the world. All of the node names behind the uucp-dom: keyword
30658 must be valid UUCP neighbors, as you can verify using the command uuname.
30660 As a reminder that this file needs to be converted into a DBM database
30661 file before use. The command line to accomplish this is best placed as a
30662 comment at the top of the mailertable file. You always have to execute
30663 this command each time you change your mailertable file.
30665 Final hint: if you are uncertain whether some particular mail routing
30666 would work, remember the -bt option to sendmail. It starts sendmail in
30667 address test mode; simply enter 3,0, followed by the address you wish to
30668 test for the mail routing. The last line tells you the used internal mail
30669 agent, the destination host this agent will be called with, and the
30670 (possibly translated) address. Leave this mode by typing Ctrl+D.
30673 ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
30674 Enter <ruleset> <address>
30675 > 3,0 foo@example.com
30676 canonify input: foo @ example . com
30678 parse returns: $# uucp-dom $@ your.uucp.relay $: foo < @ example . com . >
30681 ----------------------------------------------------------------------
30683 20.8 Setting up to send only
30685 Contributed by Bill Moran.
30687 There are many instances where you may only want to send mail through a
30688 relay. Some examples are:
30690 * Your computer is a desktop machine, but you want to use programs from
30691 the command line that send mail. To do so, you should use your ISP's
30694 * The computer is a server that does not handle mail locally, but needs
30695 to pass off all mail to a relay for processing.
30697 Just about any MTA is capable of filling this particular niche.
30698 Unfortunately, it can be very difficult to properly configure a
30699 full-featured MTA just to handle offloading mail. Programs such as
30700 sendmail and postfix are largely overkill for this use.
30702 Additionally, if you are using a typical Internet access service, your
30703 agreement may forbid you from running a ``mail server''.
30705 The easiest way to fulfill those needs is to install the mail/ssmtp port.
30706 Execute the following commands as root:
30708 # cd /usr/ports/mail/ssmtp
30709 # make install replace clean
30711 Once installed, mail/ssmtp can be configured with a four-line file located
30712 at /usr/local/etc/ssmtp/ssmtp.conf:
30714 root=yourrealemail@example.com
30715 mailhub=mail.example.com
30716 rewriteDomain=example.com
30717 hostname=_HOSTNAME_
30719 Make sure you use your real email address for root. Enter your ISP's
30720 outgoing mail relay in place of mail.example.com (some ISPs call this the
30721 ``outgoing mail server'' or ``SMTP server'').
30723 Make sure you disable sendmail by setting sendmail_enable="NONE" in
30726 mail/ssmtp has some other options available. See the example configuration
30727 file in /usr/local/etc/ssmtp or the manual page of ssmtp for some examples
30728 and more information.
30730 Setting up ssmtp in this manner will allow any software on your computer
30731 that needs to send mail to function properly, while not violating your
30732 ISP's usage policy or allowing your computer to be hijacked for spamming.
30734 ----------------------------------------------------------------------
30736 20.9 Using Mail with a Dialup Connection
30738 If you have a static IP address, you should not need to adjust anything
30739 from the defaults. Set your host name to your assigned Internet name and
30740 sendmail will do the rest.
30742 If you have a dynamically assigned IP number and use a dialup PPP
30743 connection to the Internet, you will probably have a mailbox on your ISPs
30744 mail server. Let's assume your ISP's domain is example.net, and that your
30745 user name is user, you have called your machine bsd.home, and your ISP has
30746 told you that you may use relay.example.net as a mail relay.
30748 In order to retrieve mail from your mailbox, you must install a retrieval
30749 agent. The fetchmail utility is a good choice as it supports many
30750 different protocols. This program is available as a package or from the
30751 ports collection (mail/fetchmail). Usually, your ISP will provide POP. If
30752 you are using user PPP, you can automatically fetch your mail when an
30753 Internet connection is established with the following entry in
30754 /etc/ppp/ppp.linkup:
30757 !bg su user -c fetchmail
30759 If you are using sendmail (as shown below) to deliver mail to non-local
30760 accounts, you probably want to have sendmail process your mailqueue as
30761 soon as your Internet connection is established. To do this, put this
30762 command after the fetchmail command in /etc/ppp/ppp.linkup:
30764 !bg su user -c "sendmail -q"
30766 Assume that you have an account for user on bsd.home. In the home
30767 directory of user on bsd.home, create a .fetchmailrc file:
30769 poll example.net protocol pop3 fetchall pass MySecret
30771 This file should not be readable by anyone except user as it contains the
30774 In order to send mail with the correct from: header, you must tell
30775 sendmail to use user@example.net rather than user@bsd.home. You may also
30776 wish to tell sendmail to send all mail via relay.example.net, allowing
30777 quicker mail transmission.
30779 The following .mc file should suffice:
30781 VERSIONID(`bsd.home.mc version 1.0')
30788 MASQUERADE_AS(`example.net')dnl
30789 FEATURE(allmasquerade)dnl
30790 FEATURE(masquerade_envelope)dnl
30791 FEATURE(nocanonify)dnl
30793 define(`SMART_HOST', `relay.example.net')
30795 define(`confDOMAIN_NAME',`bsd.home')dnl
30796 define(`confDELIVERY_MODE',`deferred')dnl
30798 Refer to the previous section for details of how to turn this .mc file
30799 into a sendmail.cf file. Also, do not forget to restart sendmail after
30800 updating sendmail.cf.
30802 ----------------------------------------------------------------------
30804 20.10 SMTP Authentication
30806 Written by James Gorham.
30808 Having SMTP Authentication in place on your mail server has a number of
30809 benefits. SMTP Authentication can add another layer of security to
30810 sendmail, and has the benefit of giving mobile users who switch hosts the
30811 ability to use the same mail server without the need to reconfigure their
30812 mail client settings each time.
30814 1. Install security/cyrus-sasl from the ports. You can find this port in
30815 security/cyrus-sasl. security/cyrus-sasl has a number of compile time
30816 options to choose from and, for the method we will be using here, make
30817 sure to select the pwcheck option.
30819 2. After installing security/cyrus-sasl, edit
30820 /usr/local/lib/sasl/Sendmail.conf (or create it if it does not exist)
30821 and add the following line:
30823 pwcheck_method: passwd
30825 This method will enable sendmail to authenticate against your
30826 DragonFly passwd database. This saves the trouble of creating a new
30827 set of usernames and passwords for each user that needs to use SMTP
30828 authentication, and keeps the login and mail password the same.
30830 3. Now edit /etc/make.conf and add the following lines:
30832 SENDMAIL_CFLAGS=-I/usr/local/include/sasl1 -DSASL
30833 SENDMAIL_LDFLAGS=-L/usr/local/lib
30834 SENDMAIL_LDADD=-lsasl
30836 These lines will give sendmail the proper configuration options for
30837 linking to cyrus-sasl at compile time. Make sure that cyrus-sasl has
30838 been installed before recompiling sendmail.
30840 4. Recompile sendmail by executing the following commands:
30842 # cd /usr/src/usr.sbin/sendmail
30848 The compile of sendmail should not have any problems if /usr/src has
30849 not been changed extensively and the shared libraries it needs are
30852 5. After sendmail has been compiled and reinstalled, edit your
30853 /etc/mail/freebsd.mc file (or whichever file you use as your .mc file.
30854 Many administrators choose to use the output from hostname(1) as the
30855 .mc file for uniqueness). Add these lines to it:
30857 dnl set SASL options
30858 TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
30859 define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
30860 define(`confDEF_AUTH_INFO', `/etc/mail/auth-info')dnl
30862 These options configure the different methods available to sendmail
30863 for authenticating users. If you would like to use a method other than
30864 pwcheck, please see the included documentation.
30866 6. Finally, run make(1) while in /etc/mail. That will run your new .mc
30867 file and create a .cf file named freebsd.cf (or whatever name you have
30868 used for your .mc file). Then use the command make install restart,
30869 which will copy the file to sendmail.cf, and will properly restart
30870 sendmail. For more information about this process, you should refer to
30871 /etc/mail/Makefile.
30873 If all has gone correctly, you should be able to enter your login
30874 information into the mail client and send a test message. For further
30875 investigation, set the LogLevel of sendmail to 13 and watch
30876 /var/log/maillog for any errors.
30878 You may wish to add the following lines to /etc/rc.conf so this service
30879 will be available after every system boot:
30881 sasl_pwcheck_enable="YES"
30882 sasl_pwcheck_program="/usr/local/sbin/pwcheck"
30884 This will ensure the initialization of SMTP_AUTH upon system boot.
30886 For more information, please see the sendmail page regarding SMTP
30889 ----------------------------------------------------------------------
30891 20.11 Mail User Agents
30893 Contributed by Marc Silver.
30895 A Mail User Agent (MUA) is an application that is used to send and receive
30896 email. Furthermore, as email ``evolves'' and becomes more complex, MUA's
30897 are becoming increasingly powerful in the way they interact with email;
30898 this gives users increased functionality and flexibility. DragonFly
30899 contains support for numerous mail user agents, all of which can be easily
30900 installed using the pkgsrc collection. Users may choose between graphical
30901 email clients such as evolution or balsa, console based clients such as
30902 mutt, pine or mail, or the web interfaces used by some large
30905 ----------------------------------------------------------------------
30909 mail(1) is the default Mail User Agent (MUA) in DragonFly. It is a console
30910 based MUA that offers all the basic functionality required to send and
30911 receive text-based email, though it is limited in interaction abilities
30912 with attachments and can only support local mailboxes.
30914 Although mail does not natively support interaction with POP or IMAP
30915 servers, these mailboxes may be downloaded to a local mbox file using an
30916 application such as fetchmail, which will be discussed later in this
30917 chapter (Section 20.12).
30919 In order to send and receive email, simply invoke the mail command as per
30920 the following example:
30924 The contents of the user mailbox in /var/mail are automatically read by
30925 the mail utility. Should the mailbox be empty, the utility exits with a
30926 message indicating that no mails could be found. Once the mailbox has been
30927 read, the application interface is started, and a list of messages will be
30928 displayed. Messages are automatically numbered, as can be seen in the
30931 Mail version 8.1 6/6/93. Type ? for help.
30932 "/var/mail/marcs": 3 messages 3 new
30933 >N 1 root@localhost Mon Mar 8 14:05 14/510 "test"
30934 N 2 root@localhost Mon Mar 8 14:05 14/509 "user account"
30935 N 3 root@localhost Mon Mar 8 14:05 14/509 "sample"
30937 Messages can now be read by using the t mail command, suffixed by the
30938 message number that should be displayed. In this example, we will read the
30943 From root@localhost Mon Mar 8 14:05:52 2004
30944 X-Original-To: marcs@localhost
30945 Delivered-To: marcs@localhost
30946 To: marcs@localhost
30948 Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST)
30949 From: root@localhost (Charlie Root)
30951 This is a test message, please reply if you receive it.
30953 As can be seen in the example above, the t key will cause the message to
30954 be displayed with full headers. To display the list of messages again, the
30955 h key should be used.
30957 If the email requires a response, you may use mail to reply, by using
30958 either the R or r mail keys. The R key instructs mail to reply only to the
30959 sender of the email, while r replies not only to the sender, but also to
30960 other recipients of the message. You may also suffix these commands with
30961 the mail number which you would like make a reply to. Once this has been
30962 done, the response should be entered, and the end of the message should be
30963 marked by a single . on a new line. An example can be seen below:
30969 Thank you, I did get your email.
30973 In order to send new email, the m key should be used, followed by the
30974 recipient email address. Multiple recipients may also be specified by
30975 separating each address with the , delimiter. The subject of the message
30976 may then be entered, followed by the message contents. The end of the
30977 message should be specified by putting a single . on a new line.
30979 & mail root@localhost
30980 Subject: I mastered mail
30982 Now I can send and receive email using mail ... :)
30986 While inside the mail utility, the ? command may be used to display help
30987 at any time, the mail(1) manual page should also be consulted for more
30990 Note: As previously mentioned, the mail(1) command was not originally
30991 designed to handle attachments, and thus deals with them very poorly.
30992 Newer MUAs such as mutt handle attachments in a much more intelligent
30993 way. But should you still wish to use the mail command, the
30994 converters/mpack port may be of considerable use.
30996 ----------------------------------------------------------------------
31000 mutt is a small yet very powerful Mail User Agent, with excellent
31001 features, just some of which include:
31003 * The ability to thread messages;
31005 * PGP support for digital signing and encryption of email;
31011 * Highly customizable.
31013 All of these features help to make mutt one of the most advanced mail user
31014 agents available. See http://www.mutt.org for more information on mutt.
31016 The stable version of mutt may be installed using the mail/mutt port,
31017 while the current development version may be installed via the
31018 mail/mutt-devel port. After the port has been installed, mutt can be
31019 started by issuing the following command:
31023 mutt will automatically read the contents of the user mailbox in /var/mail
31024 and display the contents if applicable. If no mails are found in the user
31025 mailbox, then mutt will wait for commands from the user. The example below
31026 shows mutt displaying a list of messages:
31028 In order to read an email, simply select it using the cursor keys, and
31029 press the Enter key. An example of mutt displaying email can be seen
31032 As with the mail(1) command, mutt allows users to reply only to the sender
31033 of the message as well as to all recipients. To reply only to the sender
31034 of the email, use the r keyboard shortcut. To send a group reply, which
31035 will be sent to the original sender as well as all the message recipients,
31036 use the g shortcut.
31038 Note: mutt makes use of the vi(1) command as an editor for creating and
31039 replying to emails. This may be customized by the user by creating or
31040 editing their own .muttrc file in their home directory and setting the
31043 In order to compose a new mail message, press m. After a valid subject has
31044 been given, mutt will start vi(1) and the mail can be written. Once the
31045 contents of the mail are complete, save and quit from vi and mutt will
31046 resume, displaying a summary screen of the mail that is to be delivered.
31047 In order to send the mail, press y. An example of the summary screen can
31050 mutt also contains extensive help, which can be accessed from most of the
31051 menus by pressing the ? key. The top line also displays the keyboard
31052 shortcuts where appropriate.
31054 ----------------------------------------------------------------------
31058 pine is aimed at a beginner user, but also includes some advanced
31061 Warning: The pine software has had several remote vulnerabilities
31062 discovered in the past, which allowed remote attackers to execute
31063 arbitrary code as users on the local system, by the action of sending a
31064 specially-prepared email. All such known problems have been fixed, but
31065 the pine code is written in a very insecure style and the DragonFly
31066 Security Officer believes there are likely to be other undiscovered
31067 vulnerabilities. You install pine at your own risk.
31069 The current version of pine may be installed using the mail/pine4 port.
31070 Once the port has installed, pine can be started by issuing the following
31075 The first time that pine is run it displays a greeting page with a brief
31076 introduction, as well as a request from the pine development team to send
31077 an anonymous email message allowing them to judge how many users are using
31078 their client. To send this anonymous message, press Enter, or
31079 alternatively press E to exit the greeting without sending an anonymous
31080 message. An example of the greeting page can be seen below:
31082 Users are then presented with the main menu, which can be easily navigated
31083 using the cursor keys. This main menu provides shortcuts for the composing
31084 new mails, browsing of mail directories, and even the administration of
31085 address book entries. Below the main menu, relevant keyboard shortcuts to
31086 perform functions specific to the task at hand are shown.
31088 The default directory opened by pine is the inbox. To view the message
31089 index, press I, or select the MESSAGE INDEX option as seen below:
31091 The message index shows messages in the current directory, and can be
31092 navigated by using the cursor keys. Highlighted messages can be read by
31093 pressing the Enter key.
31095 In the screenshot below, a sample message is displayed by pine. Keyboard
31096 shortcuts are displayed as a reference at the bottom of the screen. An
31097 example of one of these shortcuts is the r key, which tells the MUA to
31098 reply to the current message being displayed.
31100 Replying to an email in pine is done using the pico editor, which is
31101 installed by default with pine. The pico utility makes it easy to navigate
31102 around the message and is slightly more forgiving on novice users than
31103 vi(1) or mail(1). Once the reply is complete, the message can be sent by
31104 pressing Ctrl+X. The pine application will ask for confirmation.
31106 The pine application can be customized using the SETUP option from the
31107 main menu. Consult http://www.washington.edu/pine/ for more information.
31109 ----------------------------------------------------------------------
31111 20.12 Using fetchmail
31113 Contributed by Marc Silver.
31115 fetchmail is a full-featured IMAP and POP client which allows users to
31116 automatically download mail from remote IMAP and POP servers and save it
31117 into local mailboxes; there it can be accessed more easily. fetchmail can
31118 be installed using the mail/fetchmail port, and offers various features,
31119 some of which include:
31121 * Support of POP3, APOP, KPOP, IMAP, ETRN and ODMR protocols.
31123 * Ability to forward mail using SMTP, which allows filtering,
31124 forwarding, and aliasing to function normally.
31126 * May be run in daemon mode to check periodically for new messages.
31128 * Can retrieve multiple mailboxes and forward them based on
31129 configuration, to different local users.
31131 While it is outside the scope of this document to explain all of
31132 fetchmail's features, some basic features will be explained. The fetchmail
31133 utility requires a configuration file known as .fetchmailrc, in order to
31134 run correctly. This file includes server information as well as login
31135 credentials. Due to the sensitive nature of the contents of this file, it
31136 is advisable to make it readable only by the owner, with the following
31139 % chmod 600 .fetchmailrc
31141 The following .fetchmailrc serves as an example for downloading a single
31142 user mailbox using POP. It tells fetchmail to connect to example.com using
31143 a username of joesoap and a password of XXX. This example assumes that the
31144 user joesoap is also a user on the local system.
31146 poll example.com protocol pop3 username "joesoap" password "XXX"
31148 The next example connects to multiple POP and IMAP servers and redirects
31149 to different local usernames where applicable:
31151 poll example.com proto pop3:
31152 user "joesoap", with password "XXX", is "jsoap" here;
31153 user "andrea", with password "XXXX";
31154 poll example2.net proto imap:
31155 user "john", with password "XXXXX", is "myth" here;
31157 The fetchmail utility can be run in daemon mode by running it with the -d
31158 flag, followed by the interval (in seconds) that fetchmail should poll
31159 servers listed in the .fetchmailrc file. The following example would cause
31160 fetchmail to poll every 60 seconds:
31164 More information on fetchmail can be found at
31165 http://www.catb.org/~esr/fetchmail/.
31167 ----------------------------------------------------------------------
31169 20.13 Using procmail
31171 Contributed by Marc Silver.
31173 The procmail utility is an incredibly powerful application used to filter
31174 incoming mail. It allows users to define ``rules'' which can be matched to
31175 incoming mails to perform specific functions or to reroute mail to
31176 alternative mailboxes and/or email addresses. procmail can be installed
31177 using the mail/procmail port. Once installed, it can be directly
31178 integrated into most MTAs; consult your MTA documentation for more
31179 information. Alternatively, procmail can be integrated by adding the
31180 following line to a .forward in the home directory of the user utilizing
31183 "|exec /usr/local/bin/procmail || exit 75"
31185 The following section will display some basic procmail rules, as well as
31186 brief descriptions on what they do. These rules, and others must be
31187 inserted into a .procmailrc file, which must reside in the user's home
31192 The majority of these rules can also be found in the procmailex(5) manual
31195 Forward all mail from user@example.com to an external address of
31196 goodmail@example2.com:
31199 * ^From.*user@example.com
31200 ! goodmail@example2.com
31202 Forward all mails shorter than 1000 bytes to an external address of
31203 goodmail@example2.com:
31207 ! goodmail@example2.com
31209 Send all mail sent to alternate@example.com into a mailbox called
31213 * ^TOalternate@example.com
31216 Send all mail with a subject of ``Spam'' to /dev/null:
31222 A useful recipe that parses incoming dragonflybsd.org mailing lists and
31223 places each list in its own mailbox:
31226 * ^List-Post: <mailto:\/[^@]+
31230 * LISTNAME??^\/[^-]+
31234 ----------------------------------------------------------------------
31236 Chapter 21 Updating DragonFly
31238 Written by Justin Sherrill.
31242 Updates to the DragonFly source code is performed using cvsup. cvsup
31243 compares your local system source or ports files to a remote repository,
31244 and downloads any changes. Only the differences in the files are
31245 downloaded, saving on bandwidth and time.
31247 cvsup exists as a port (net/cvsup) and traditionally had to be installed
31248 separately on FreeBSD. With DragonFly, the binary is installed as part of
31251 ----------------------------------------------------------------------
31255 cvsup is guided by a configuration file that describes what files to
31256 update, and the source from which to update them.
31258 Here is a basic DragonFly cvsup configuration file:
31260 *default host=cvsup.dragonflybsd.org
31262 *default prefix=/usr
31263 *default release=cvs
31264 *default release=cvs tag=.
31265 *default delete use-rel-suffix
31271 Alternately, the file /usr/share/examples/cvsup/DragonFly-src-supfile can
31272 be used as-is to update system source.
31274 Run cvsup using /usr/share/examples/cvsup/DragonFly-src-supfile as an
31275 argument or with a separate file containing the above example text. Your
31276 system source files will be updated.
31278 ----------------------------------------------------------------------
31280 21.3 Preparing to Update
31282 If you want to create a custom kernel, see Chapter 9. This is not needed
31283 to update your system unless there is a specific feature that needs to be
31284 added to the kernel.
31286 Check recent mail traffic on DragonFly Kernel mailing list and the file
31287 /usr/src/UPDATING. Any recent problems or changes should be described
31288 there. /usr/src/UPDATING also contains abbreviated build instructions in
31289 case these directions are not available.
31291 ----------------------------------------------------------------------
31293 21.4 Updating the System
31295 Updating the system is a relatively simple process. As root, in /usr/src:
31298 % make buildkernel KERNCONF=GENERIC
31299 % make installkernel KERNCONF=GENERIC
31300 % make installworld
31304 An explanation of each step follows.
31306 * make buildworld : This command rebuilds all userland programs. This is
31307 the most time-consuming step.
31309 * make buildkernel KERNCONF=GENERIC : This builds the kernel using the
31310 config file specified by KERNCONF. If you've created a different
31311 kernel configuration file as detailed in Chapter 9, use that instead
31312 of GENERIC. If KERNCONF isn't specified, the GENERIC configuration
31313 file (installed by default) is used.
31315 * make installkernel KERNCONF=GENERIC : This installs the kernel using
31316 the config file specified by KERNCONF. The value of KERNCONF must
31317 match what was specified in the make buildkernel command, so that
31318 files that match this configuration can be installed correctly. As
31319 with make buildkernel, KERNCONF will be set to GENERIC if not
31320 otherwise specified.
31322 * make installworld : This copies all the files built in the buildworld
31323 step (i.e. everything that is not the kernel) to the proper places in
31326 * make upgrade : This cleans out any files made unnecessary by this
31329 * (reboot) : Reboot the computer to load the new kernel and use the new
31330 files installed as part of this process.
31332 If your computer fails to reboot, check the Section 9.6 section of the
31335 ----------------------------------------------------------------------
31337 Chapter 22 Linux Binary Compatibility
31339 Restructured and parts updated by Jim Mock. Originally contributed by
31340 Brian N. Handy and Rich Murphey.
31344 DragonFly provides binary compatibility with several other UNIX like
31345 operating systems, including Linux. At this point, you may be asking
31346 yourself why exactly, does DragonFly need to be able to run Linux
31347 binaries? The answer to that question is quite simple. Many companies and
31348 developers develop only for Linux, since it is the latest ``hot thing'' in
31349 the computing world. That leaves the rest of us DragonFly users bugging
31350 these same companies and developers to put out native DragonFly versions
31351 of their applications. The problem is, that most of these companies do not
31352 really realize how many people would use their product if there were
31353 DragonFly versions too, and most continue to only develop for Linux. So
31354 what is a DragonFly user to do? This is where the Linux binary
31355 compatibility of DragonFly comes into play.
31357 In a nutshell, the compatibility allows DragonFly users to run about 90%
31358 of all Linux applications without modification. This includes applications
31359 such as StarOffice, the Linux version of Netscape, Adobe(R) Acrobat(R),
31360 RealPlayer(R) 5 and 7, VMware(TM), Oracle, WordPerfect(R), Doom, Quake,
31361 and more. It is also reported that in some situations, Linux binaries
31362 perform better on DragonFly than they do under Linux.
31364 There are, however, some Linux-specific operating system features that are
31365 not supported under DragonFly. Linux binaries will not work on DragonFly
31366 if they overly use the Linux /proc file system (which is different from
31367 DragonFly's /proc file system), or i386 specific calls, such as enabling
31370 After reading this chapter, you will know:
31372 * How to enable Linux binary compatibility on your system.
31374 * How to install additional Linux shared libraries.
31376 * How to install Linux applications on your DragonFly system.
31378 * The implementation details of Linux compatibility in DragonFly.
31380 Before reading this chapter, you should:
31382 * Know how to install additional third-party software (Chapter 4).
31384 ----------------------------------------------------------------------
31388 Linux binary compatibility is not turned on by default. The easiest way to
31389 enable this functionality is to load the linux KLD object (``Kernel
31390 Loadable Device''). You can load this module by simply typing linux at the
31393 If you would like Linux compatibility to always be enabled, then you
31394 should add the following line to /etc/rc.conf:
31398 The kldstat(8) command can be used to verify that the KLD is loaded:
31401 Id Refs Address Size Name
31402 1 2 0xc0100000 16bdb8 kernel
31403 7 1 0xc24db000 d000 linux.ko
31405 If for some reason you do not want to or cannot load the KLD, then you may
31406 statically link Linux binary compatibility into the kernel by adding
31407 options COMPAT_LINUX to your kernel configuration file. Then install your
31408 new kernel as described in Chapter 9.
31410 ----------------------------------------------------------------------
31412 22.2.1 Installing Linux Runtime Libraries
31414 This can be done one of two ways, either by using the suse package, or by
31415 installing them manually.
31417 ----------------------------------------------------------------------
31419 22.2.1.1 Installing Using suse Package
31421 This is by far the easiest method to use when installing the runtime
31422 libraries. It is just like installing any other package from the pkgsrc
31423 collection. Simply do the following:
31425 # cd /usr/pkgsrc/meta-pkgs/suse9
31426 # make install distclean
31427 # ln -s /usr/pkg/emul /compat
31429 You should now have working Linux binary compatibility. Some programs may
31430 complain about incorrect minor versions of the system libraries. In
31431 general, however, this does not seem to be a problem.
31433 Note: There may be multiple versions of the meta-pkgs/suse package
31434 available, corresponding to different versions of various Linux
31435 distributions. You should install the package most closely resembling
31436 the requirements of the Linux applications you would like to install.
31438 ----------------------------------------------------------------------
31440 22.2.1.2 Installing Libraries Manually
31442 If you do not have the ``pkgsrc'' collection installed, you can install
31443 the libraries by hand instead. You will need the Linux shared libraries
31444 that the program depends on and the runtime linker. Also, you will need to
31445 create a ``shadow root'' directory, /compat/linux, for Linux libraries on
31446 your DragonFly system. Any shared libraries opened by Linux programs run
31447 under DragonFly will look in this tree first. So, if a Linux program
31448 loads, for example, /lib/libc.so, DragonFly will first try to open
31449 /compat/linux/lib/libc.so, and if that does not exist, it will then try
31450 /lib/libc.so. Shared libraries should be installed in the shadow tree
31451 /compat/linux/lib rather than the paths that the Linux ld.so reports.
31453 Generally, you will need to look for the shared libraries that Linux
31454 binaries depend on only the first few times that you install a Linux
31455 program on your DragonFly system. After a while, you will have a
31456 sufficient set of Linux shared libraries on your system to be able to run
31457 newly imported Linux binaries without any extra work.
31459 ----------------------------------------------------------------------
31461 22.2.1.3 How to Install Additional Shared Libraries
31463 What if you install the suse package and your application still complains
31464 about missing shared libraries? How do you know which shared libraries
31465 Linux binaries need, and where to get them? Basically, there are 2
31466 possibilities (when following these instructions you will need to be root
31467 on your DragonFly system).
31469 If you have access to a Linux system, see what shared libraries the
31470 application needs, and copy them to your DragonFly system. Look at the
31473 Let us assume you used FTP to get the Linux binary of Doom, and put it on
31474 a Linux system you have access to. You then can check which shared
31475 libraries it needs by running ldd linuxdoom, like so:
31478 libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
31479 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
31480 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
31482 You would need to get all the files from the last column, and put them
31483 under /compat/linux, with the names in the first column as symbolic links
31484 pointing to them. This means you eventually have these files on your
31487 /compat/linux/usr/X11/lib/libXt.so.3.1.0
31488 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
31489 /compat/linux/usr/X11/lib/libX11.so.3.1.0
31490 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
31491 /compat/linux/lib/libc.so.4.6.29
31492 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
31494 Note: Note that if you already have a Linux shared library with a
31495 matching major revision number to the first column of the ldd output,
31496 you will not need to copy the file named in the last column to your
31497 system, the one you already have should work. It is advisable to copy
31498 the shared library anyway if it is a newer version, though. You can
31499 remove the old one, as long as you make the symbolic link point to the
31500 new one. So, if you have these libraries on your system:
31502 /compat/linux/lib/libc.so.4.6.27
31503 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27
31505 and you find a new binary that claims to require a later version
31506 according to the output of ldd:
31508 libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29
31510 If it is only one or two versions out of date in the in the trailing
31511 digit then do not worry about copying /lib/libc.so.4.6.29 too, because
31512 the program should work fine with the slightly older version. However,
31513 if you like, you can decide to replace the libc.so anyway, and that
31514 should leave you with:
31516 /compat/linux/lib/libc.so.4.6.29
31517 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
31519 Note: The symbolic link mechanism is only needed for Linux binaries.
31520 The DragonFly runtime linker takes care of looking for matching major
31521 revision numbers itself and you do not need to worry about it.
31523 ----------------------------------------------------------------------
31525 22.2.2 Installing Linux ELF Binaries
31527 ELF binaries sometimes require an extra step of ``branding''. If you
31528 attempt to run an unbranded ELF binary, you will get an error message like
31531 % ./my-linux-elf-binary
31532 ELF binary type not known
31535 To help the DragonFly kernel distinguish between a DragonFly ELF binary
31536 from a Linux binary, use the brandelf(1) utility.
31538 % brandelf -t Linux my-linux-elf-binary
31540 The GNU toolchain now places the appropriate branding information into ELF
31541 binaries automatically, so this step should only be needed for older,
31544 ----------------------------------------------------------------------
31546 22.2.3 Configuring the Hostname Resolver
31548 If DNS does not work or you get this message:
31550 resolv+: "bind" is an invalid keyword resolv+:
31551 "hosts" is an invalid keyword
31553 You will need to configure a /compat/linux/etc/host.conf file containing:
31558 The order here specifies that /etc/hosts is searched first and DNS is
31559 searched second. When /compat/linux/etc/host.conf is not installed, Linux
31560 applications find DragonFly's /etc/host.conf and complain about the
31561 incompatible DragonFly syntax. You should remove bind if you have not
31562 configured a name server using the /etc/resolv.conf file.
31564 ----------------------------------------------------------------------
31566 22.3 Installing Mathematica(R)
31568 Updated for Mathematica 4.X by Murray Stokely. Merged with work by Bojan
31571 This document describes the process of installing the Linux version of
31572 Mathematica 4.X onto a DragonFly system.
31574 Warning: This description applies to FreeBSD, for which it was
31575 originally written. This may or may not apply to DragonFly at this
31576 point; while FreeBSD 4.x features usually translate over to DragonFly
31577 well, your mileage may vary.
31579 The Linux version of Mathematica runs perfectly under DragonFly however
31580 the binaries shipped by Wolfram need to be branded so that DragonFly knows
31581 to use the Linux ABI to execute them.
31583 The Linux version of Mathematica or Mathematica for Students can be
31584 ordered directly from Wolfram at http://www.wolfram.com/.
31586 ----------------------------------------------------------------------
31588 22.3.1 Branding the Linux Binaries
31590 The Linux binaries are located in the Unix directory of the Mathematica
31591 CDROM distributed by Wolfram. You need to copy this directory tree to your
31592 local hard drive so that you can brand the Linux binaries with brandelf(1)
31593 before running the installer:
31596 # cp -rp /cdrom/Unix/ /localdir/
31597 # brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*
31598 # brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*
31599 # brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*
31600 # brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*
31601 # brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*
31602 # brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm
31603 # cd /localdir/Installers/Linux/
31606 Alternatively, you can simply set the default ELF brand to Linux for all
31607 unbranded binaries with the command:
31609 # sysctl kern.fallback_elf_brand=3
31611 This will make DragonFly assume that unbranded ELF binaries use the Linux
31612 ABI and so you should be able to run the installer straight from the
31615 ----------------------------------------------------------------------
31617 22.3.2 Obtaining Your Mathematica Password
31619 Before you can run Mathematica you will have to obtain a password from
31620 Wolfram that corresponds to your ``machine ID''.
31622 Once you have installed the Linux compatibility runtime libraries and
31623 unpacked Mathematica you can obtain the ``machine ID'' by running the
31624 program mathinfo in the installation directory. This machine ID is based
31625 solely on the MAC address of your first Ethernet card.
31627 # cd /localdir/Files/SystemFiles/Installation/Binaries/Linux
31629 disco.example.com 7115-70839-20412
31631 When you register with Wolfram, either by email, phone or fax, you will
31632 give them the ``machine ID'' and they will respond with a corresponding
31633 password consisting of groups of numbers. You can then enter this
31634 information when you attempt to run Mathematica for the first time exactly
31635 as you would for any other Mathematica platform.
31637 ----------------------------------------------------------------------
31639 22.3.3 Running the Mathematica Frontend over a Network
31641 Mathematica uses some special fonts to display characters not present in
31642 any of the standard font sets (integrals, sums, Greek letters, etc.). The
31643 X protocol requires these fonts to be install locally. This means you will
31644 have to copy these fonts from the CDROM or from a host with Mathematica
31645 installed to your local machine. These fonts are normally stored in
31646 /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or
31647 /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual
31648 fonts are in the subdirectories Type1 and X. There are several ways to use
31649 them, as described below.
31651 The first way is to copy them into one of the existing font directories in
31652 /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file,
31653 adding the font names to it, and changing the number of fonts on the first
31654 line. Alternatively, you should also just be able to run mkfontdir(1) in
31655 the directory you have copied them to.
31657 The second way to do this is to copy the directories to
31658 /usr/X11R6/lib/X11/fonts:
31660 # cd /usr/X11R6/lib/X11/fonts
31663 # cd /cdrom/Unix/Files/SystemFiles/Fonts
31664 # cp X/* /usr/X11R6/lib/X11/fonts/X
31665 # cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1
31666 # cd /usr/X11R6/lib/X11/fonts/X
31671 Now add the new font directories to your font path:
31673 # xset fp+ /usr/X11R6/lib/X11/fonts/X
31674 # xset fp+ /usr/X11R6/lib/X11/fonts/MathType1
31677 If you are using the XFree86 server, you can have these font directories
31678 loaded automatically by adding them to your XF86Config file.
31680 If you do not already have a directory called
31681 /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1
31682 directory in the example above to Type1.
31684 ----------------------------------------------------------------------
31686 22.4 Installing Maple(TM)
31688 Contributed by Aaron Kaplan. Thanks to Robert Getschmann.
31690 Maple(TM) is a commercial mathematics program similar to Mathematica. You
31691 must purchase this software from http://www.maplesoft.com/ and then
31692 register there for a license file. To install this software on DragonFly,
31693 please follow these simple steps.
31695 Warning: This description applies to FreeBSD, for which it was
31696 originally written. This may or may not apply to DragonFly at this
31697 point; while FreeBSD 4.x features usually translate over to DragonFly
31698 well, your mileage may vary.
31700 1. Execute the INSTALL shell script from the product distribution. Choose
31701 the ``RedHat'' option when prompted by the installation program. A
31702 typical installation directory might be /usr/local/maple.
31704 2. If you have not done so, order a license for Maple from Maple Waterloo
31705 Software (http://register.maplesoft.com/) and copy it to
31706 /usr/local/maple/license/license.dat.
31708 3. Install the FLEXlm license manager by running the INSTALL_LIC install
31709 shell script that comes with Maple. Specify the primary hostname for
31710 your machine for the license server.
31712 4. Patch the /usr/local/maple/bin/maple.system.type file with the
31715 ----- snip ------------------
31716 *** maple.system.type.orig Sun Jul 8 16:35:33 2001
31717 --- maple.system.type Sun Jul 8 16:35:51 2001
31721 # the IBM RS/6000 AIX case
31722 MAPLE_BIN="bin.IBM_RISC_UNIX"
31726 # the Linux/x86 case
31727 # We have two Linux implementations, one for Red Hat and
31728 ----- snip end of patch -----
31730 Please note that after the "DragonFly"|\ no other whitespace should be
31733 This patch instructs Maple to recognize ``DragonFly'' as a type of
31734 Linux system. The bin/maple shell script calls the
31735 bin/maple.system.type shell script which in turn calls uname -a to
31736 find out the operating system name. Depending on the OS name it will
31737 find out which binaries to use.
31739 5. Start the license server.
31741 The following script, installed as /usr/local/etc/rc.d/lmgrd.sh is a
31742 convenient way to start up lmgrd:
31744 ----- snip ------------
31747 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
31748 PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
31751 LICENSE_FILE=/usr/local/maple/license/license.dat
31752 LOG=/var/log/lmgrd.log
31756 lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
31760 lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
31763 echo "Usage: `basename $0` {start|stop}" 1>&2
31769 ----- snip ------------
31771 6. Test-start Maple:
31773 % cd /usr/local/maple/bin
31776 You should be up and running. Make sure to write Maplesoft to let them
31777 know you would like a native DragonFly version!
31779 ----------------------------------------------------------------------
31781 22.4.1 Common Pitfalls
31783 * The FLEXlm license manager can be a difficult tool to work with.
31784 Additional documentation on the subject can be found at
31785 http://www.globetrotter.com/.
31787 * lmgrd is known to be very picky about the license file and to core
31788 dump if there are any problems. A correct license file should look
31791 # =======================================================
31792 # License File for UNIX Installations ("Pointer File")
31793 # =======================================================
31798 FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
31799 PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
31800 ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
31803 Note: Serial number and key 'X''ed out. chillig is a hostname.
31805 Editing the license file works as long as you do not touch the
31806 ``FEATURE'' line (which is protected by the license key).
31808 ----------------------------------------------------------------------
31810 22.5 Installing MATLAB(R)
31812 Contributed by Dan Pelleg.
31814 This document describes the process of installing the Linux version of
31815 MATLAB(R) version 6.5 onto a DragonFly system. It works quite well, with
31816 the exception of the Java Virtual Machine(TM) (see Section 22.5.3).
31818 The Linux version of MATLAB can be ordered directly from The MathWorks at
31819 http://www.mathworks.com. Make sure you also get the license file or
31820 instructions how to create it. While you are there, let them know you
31821 would like a native DragonFly version of their software.
31823 ----------------------------------------------------------------------
31825 22.5.1 Installing MATLAB
31827 To install MATLAB, do the following:
31829 1. Insert the installation CD and mount it. Become root, as recommended
31830 by the installation script. To start the installation script type:
31832 # /compat/linux/bin/sh /cdrom/install
31834 Tip: The installer is graphical. If you get errors about not being
31835 able to open a display, type setenv HOME ~USER, where USER is the
31836 user you did a su(1) as.
31838 2. When asked for the MATLAB root directory, type:
31839 /compat/linux/usr/local/matlab.
31841 Tip: For easier typing on the rest of the installation process, type
31842 this at your shell prompt: set MATLAB=/compat/linux/usr/local/matlab
31844 3. Edit the license file as instructed when obtaining the MATLAB license.
31846 Tip: You can prepare this file in advance using your favorite
31847 editor, and copy it to $MATLAB/license.dat before the installer asks
31850 4. Complete the installation process.
31852 At this point your MATLAB installation is complete. The following steps
31853 apply ``glue'' to connect it to your DragonFly system.
31855 ----------------------------------------------------------------------
31857 22.5.2 License Manager Startup
31859 1. Create symlinks for the license manager scripts:
31861 # ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW
31862 # ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW
31864 2. Create a startup file at /usr/local/etc/rc.d/flexlm.sh. The example
31865 below is a modified version of the distributed
31866 $MATLAB/etc/rc.lm.glnx86. The changes are file locations, and startup
31867 of the license manager under Linux emulation.
31872 if [ -f /usr/local/etc/lmboot_TMW ]; then
31873 /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd'
31877 if [ -f /usr/local/etc/lmdown_TMW ]; then
31878 /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1
31882 echo "Usage: $0 {start|stop}"
31889 Important: The file must be made executable:
31891 # chmod +x /usr/local/etc/rc.d/flexlm.sh
31893 You must also replace username above with the name of a valid user
31894 on your system (and not root).
31896 3. Start the license manager with the command:
31898 # /usr/local/etc/rc.d/flexlm.sh start
31900 ----------------------------------------------------------------------
31902 22.5.3 Linking the Java Runtime Environment
31904 Change the Java Runtime Environment (JRE) link to one working under
31907 # cd $MATLAB/sys/java/jre/glnx86/
31908 # unlink jre; ln -s ./jre1.1.8 ./jre
31910 ----------------------------------------------------------------------
31912 22.5.4 Creating a MATLAB Startup Script
31914 1. Place the following startup script in /usr/local/bin/matlab:
31917 /compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"
31919 2. Then type the command chmod +x /usr/local/bin/matlab.
31921 Tip: Depending on your version of emulators/linux_base, you may run into
31922 errors when running this script. To avoid that, edit the file
31923 /compat/linux/usr/local/matlab/bin/matlab, and change the line that
31926 if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then
31928 (in version 13.0.1 it is on line 410) to this line:
31930 if test -L $newbase; then
31932 ----------------------------------------------------------------------
31934 22.5.5 Creating a MATLAB Shutdown Script
31936 The following is needed to solve a problem with MATLAB not exiting
31939 1. Create a file $MATLAB/toolbox/local/finish.m, and in it put the single
31942 ! $MATLAB/bin/finish.sh
31944 Note: The $MATLAB is literal.
31946 Tip: In the same directory, you will find the files finishsav.m and
31947 finishdlg.m, which let you save your workspace before quitting. If
31948 you use either of them, insert the line above immediately after the
31951 2. Create a file $MATLAB/bin/finish.sh, which will contain the following:
31953 #!/usr/compat/linux/bin/sh
31954 (sleep 5; killall -1 matlab_helper) &
31957 3. Make the file executable:
31959 # chmod +x $MATLAB/bin/finish.sh
31961 ----------------------------------------------------------------------
31963 22.5.6 Using MATLAB
31965 At this point you are ready to type matlab and start using it.
31967 ----------------------------------------------------------------------
31969 22.6 Installing Oracle(R)
31971 Contributed by Marcel Moolenaar.
31973 ----------------------------------------------------------------------
31977 This document describes the process of installing Oracle 8.0.5 and Oracle
31978 8.0.5.1 Enterprise Edition for Linux onto a DragonFly machine.
31980 Warning: This description applies to FreeBSD, for which it was
31981 originally written. This may or may not apply to DragonFly at this
31982 point; while FreeBSD 4.x features usually translate over to DragonFly
31983 well, your mileage may vary.
31985 ----------------------------------------------------------------------
31987 22.6.2 Installing the Linux Environment
31989 Make sure you have both emulators/linux_base and devel/linux_devtools from
31990 the ports collection installed. If you run into difficulties with these
31991 ports, you may have to use the packages or older versions available in the
31994 If you want to run the intelligent agent, you will also need to install
31995 the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for
31996 installing packages with the official RPM port (archivers/rpm) is:
31998 # rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package
32000 Installation of the package should not generate any errors.
32002 ----------------------------------------------------------------------
32004 22.6.3 Creating the Oracle Environment
32006 Before you can install Oracle, you need to set up a proper environment.
32007 This document only describes what to do specially to run Oracle for Linux
32008 on DragonFly, not what has been described in the Oracle installation
32011 ----------------------------------------------------------------------
32013 22.6.3.1 Kernel Tuning
32015 As described in the Oracle installation guide, you need to set the maximum
32016 size of shared memory. Do not use SHMMAX under DragonFly. SHMMAX is merely
32017 calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All
32018 other options can be used as described in the guide. For example:
32020 options SHMMAXPGS=10000
32027 Set these options to suit your intended use of Oracle.
32029 Also, make sure you have the following options in your kernel
32030 configuration file:
32032 options SYSVSHM #SysV shared memory
32033 options SYSVSEM #SysV semaphores
32034 options SYSVMSG #SysV interprocess communication
32036 ----------------------------------------------------------------------
32038 22.6.3.2 Oracle Account
32040 Create an oracle account just as you would create any other account. The
32041 oracle account is special only that you need to give it a Linux shell. Add
32042 /compat/linux/bin/bash to /etc/shells and set the shell for the oracle
32043 account to /compat/linux/bin/bash.
32045 ----------------------------------------------------------------------
32047 22.6.3.3 Environment
32049 Besides the normal Oracle variables, such as ORACLE_HOME and ORACLE_SID
32050 you must set the following environment variables:
32053 LD_LIBRARY_PATH $ORACLE_HOME/lib
32054 CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip
32055 /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin
32056 PATH /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin
32057 /usr/local/bin $ORACLE_HOME/bin
32059 It is advised to set all the environment variables in .profile. A complete
32062 ORACLE_BASE=/oracle; export ORACLE_BASE
32063 ORACLE_HOME=/oracle; export ORACLE_HOME
32064 LD_LIBRARY_PATH=$ORACLE_HOME/lib
32065 export LD_LIBRARY_PATH
32066 ORACLE_SID=ORCL; export ORACLE_SID
32067 ORACLE_TERM=386x; export ORACLE_TERM
32068 CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
32070 PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
32071 PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
32072 PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
32075 ----------------------------------------------------------------------
32077 22.6.4 Installing Oracle
32079 Due to a slight inconsistency in the Linux emulator, you need to create a
32080 directory named .oracle in /var/tmp before you start the installer. Either
32081 make it world writable or let it be owned by the oracle user. You should
32082 be able to install Oracle without any problems. If you have problems,
32083 check your Oracle distribution and/or configuration first! After you have
32084 installed Oracle, apply the patches described in the next two subsections.
32086 A frequent problem is that the TCP protocol adapter is not installed
32087 right. As a consequence, you cannot start any TCP listeners. The following
32088 actions help solve this problem:
32090 # cd $ORACLE_HOME/network/lib
32091 # make -f ins_network.mk ntcontab.o
32092 # cd $ORACLE_HOME/lib
32093 # ar r libnetwork.a ntcontab.o
32094 # cd $ORACLE_HOME/network/lib
32095 # make -f ins_network.mk install
32097 Do not forget to run root.sh again!
32099 ----------------------------------------------------------------------
32101 22.6.4.1 Patching root.sh
32103 When installing Oracle, some actions, which need to be performed as root,
32104 are recorded in a shell script called root.sh. This script is written in
32105 the orainst directory. Apply the following patch to root.sh, to have it
32106 use to proper location of chown or alternatively run the script under a
32107 Linux native shell.
32109 *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
32110 --- orainst/root.sh Mon Dec 28 15:58:53 1998
32113 # This is the default value for CHOWN
32114 # It will redefined later in this script for those ports
32115 # which have it conditionally defined in ss_install.h
32118 # Define variables to be used in this script
32120 # This is the default value for CHOWN
32121 # It will redefined later in this script for those ports
32122 # which have it conditionally defined in ss_install.h
32123 ! CHOWN=/usr/sbin/chown
32125 # Define variables to be used in this script
32127 When you do not install Oracle from CD, you can patch the source for
32128 root.sh. It is called rthd.sh and is located in the orainst directory in
32131 ----------------------------------------------------------------------
32133 22.6.4.2 Patching genclntsh
32135 The script genclntsh is used to create a single shared client library. It
32136 is used when building the demos. Apply the following patch to comment out
32137 the definition of PATH:
32139 *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
32140 --- bin/genclntsh Tue Dec 22 15:36:49 1998
32144 # Explicit path to ensure that we're using the correct commands
32145 #PATH=/usr/bin:/usr/ccs/bin export PATH
32146 ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
32148 # each product MUST provide a $PRODUCT/admin/shrept.lst
32151 # Explicit path to ensure that we're using the correct commands
32152 #PATH=/usr/bin:/usr/ccs/bin export PATH
32153 ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
32155 # each product MUST provide a $PRODUCT/admin/shrept.lst
32157 ----------------------------------------------------------------------
32159 22.6.5 Running Oracle
32161 When you have followed the instructions, you should be able to run Oracle
32162 as if it was run on Linux itself.
32164 ----------------------------------------------------------------------
32166 22.7 Installing SAP(R) R/3(R)
32168 Contributed by Holger Kipp. Original version converted to SGML by
32169 Valentino Vaschetto.
32171 Installations of SAP Systems using DragonFly will not be supported by the
32172 SAP support team -- they only offer support for certified platforms.
32174 Warning: This description applies to FreeBSD, for which it was
32175 originally written. This may or may not apply to DragonFly at this
32176 point; while FreeBSD 4.x features usually translate over to DragonFly
32177 well, your mileage may vary.
32179 ----------------------------------------------------------------------
32183 This document describes a possible way of installing a SAP R/3 System with
32184 Oracle Database for Linux onto a DragonFly machine, including the
32185 installation of DragonFly and Oracle. Two different configurations will be
32188 * SAP R/3 4.6B (IDES) with Oracle 8.0.5 on FreeBSD 4.3-STABLE
32190 * SAP R/3 4.6C with Oracle 8.1.7 on FreeBSD 4.5-STABLE
32192 Even though this document tries to describe all important steps in a
32193 greater detail, it is not intended as a replacement for the Oracle and
32194 SAP R/3 installation guides.
32196 Please see the documentation that comes with the SAP R/3 Linux edition for
32197 SAP and Oracle specific questions, as well as resources from Oracle and
32200 ----------------------------------------------------------------------
32204 The following CD-ROMs have been used for SAP installations:
32206 ----------------------------------------------------------------------
32208 22.7.2.1 SAP R/3 4.6B, Oracle 8.0.5
32210 +------------------------------------------------------------------------+
32211 | Name | Number | Description |
32212 |---------+----------+---------------------------------------------------|
32213 | KERNEL | 51009113 | SAP Kernel Oracle / Installation / AIX, Linux, |
32215 |---------+----------+---------------------------------------------------|
32216 | RDBMS | 51007558 | Oracle / RDBMS 8.0.5.X / Linux |
32217 |---------+----------+---------------------------------------------------|
32218 | EXPORT1 | 51010208 | IDES / DB-Export / Disc 1 of 6 |
32219 |---------+----------+---------------------------------------------------|
32220 | EXPORT2 | 51010209 | IDES / DB-Export / Disc 2 of 6 |
32221 |---------+----------+---------------------------------------------------|
32222 | EXPORT3 | 51010210 | IDES / DB-Export / Disc 3 of 6 |
32223 |---------+----------+---------------------------------------------------|
32224 | EXPORT4 | 51010211 | IDES / DB-Export / Disc 4 of 6 |
32225 |---------+----------+---------------------------------------------------|
32226 | EXPORT5 | 51010212 | IDES / DB-Export / Disc 5 of 6 |
32227 |---------+----------+---------------------------------------------------|
32228 | EXPORT6 | 51010213 | IDES / DB-Export / Disc 6 of 6 |
32229 +------------------------------------------------------------------------+
32231 Additionally, we used the Oracle 8 Server (Pre-production version 8.0.5
32232 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and
32233 FreeBSD 4.3-STABLE (it was only a few days past 4.3 RELEASE).
32235 ----------------------------------------------------------------------
32237 22.7.2.2 SAP R/3 4.6C SR2, Oracle 8.1.7
32239 +------------------------------------------------------------------------+
32240 | Name | Number | Description |
32241 |---------+----------+---------------------------------------------------|
32242 | KERNEL | 51014004 | SAP Kernel Oracle / SAP Kernel Version 4.6D / |
32244 |---------+----------+---------------------------------------------------|
32245 | RDBMS | 51012930 | Oracle 8.1.7/ RDBMS / Linux |
32246 |---------+----------+---------------------------------------------------|
32247 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 1 of 4 |
32248 |---------+----------+---------------------------------------------------|
32249 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 2 of 4 |
32250 |---------+----------+---------------------------------------------------|
32251 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 3 of 4 |
32252 |---------+----------+---------------------------------------------------|
32253 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 4 of 4 |
32254 |---------+----------+---------------------------------------------------|
32255 | LANG1 | 51013954 | Release 4.6C SR2 / Language / DE, EN, FR / Disc 1 |
32257 +------------------------------------------------------------------------+
32259 Depending on the languages you would like to install, additional language
32260 CDs might be necessary. Here we are just using DE and EN, so the first
32261 language CD is the only one needed. As a little note, the numbers for all
32262 four EXPORT CDs are identical. All three language CDs also have the same
32263 number (this is different from the 4.6B IDES release CD numbering). At the
32264 time of writing this installation is running on FreeBSD 4.5-STABLE
32267 ----------------------------------------------------------------------
32271 The following notes should be read before installing SAP R/3 and proved to
32272 be useful during installation:
32274 ----------------------------------------------------------------------
32276 22.7.3.1 SAP R/3 4.6B, Oracle 8.0.5
32278 +-----------------------------------------------------------------+
32280 |---------+-------------------------------------------------------|
32281 | 0171356 | SAP Software on Linux: Essential Comments |
32282 |---------+-------------------------------------------------------|
32283 | 0201147 | INST: 4.6C R/3 Inst. on UNIX - Oracle |
32284 |---------+-------------------------------------------------------|
32285 | 0373203 | Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX |
32286 |---------+-------------------------------------------------------|
32287 | 0072984 | Release of Digital UNIX 4.0B for Oracle |
32288 |---------+-------------------------------------------------------|
32289 | 0130581 | R3SETUP step DIPGNTAB terminates |
32290 |---------+-------------------------------------------------------|
32291 | 0144978 | Your system has not been installed correctly |
32292 |---------+-------------------------------------------------------|
32293 | 0162266 | Questions and tips for R3SETUP on Windows NT / W2K |
32294 +-----------------------------------------------------------------+
32296 ----------------------------------------------------------------------
32298 22.7.3.2 SAP R/3 4.6C, Oracle 8.1.7
32300 +----------------------------------------------------------+
32302 |---------+------------------------------------------------|
32303 | 0015023 | Initializing table TCPDB (RSXP0004) (EBCDIC) |
32304 |---------+------------------------------------------------|
32305 | 0045619 | R/3 with several languages or typefaces |
32306 |---------+------------------------------------------------|
32307 | 0171356 | SAP Software on Linux: Essential Comments |
32308 |---------+------------------------------------------------|
32309 | 0195603 | RedHat 6.1 Enterprise version: Known problems |
32310 |---------+------------------------------------------------|
32311 | 0212876 | The new archiving tool SAPCAR |
32312 |---------+------------------------------------------------|
32313 | 0300900 | Linux: Released DELL Hardware |
32314 |---------+------------------------------------------------|
32315 | 0377187 | RedHat 6.2: important remarks |
32316 |---------+------------------------------------------------|
32317 | 0387074 | INST: R/3 4.6C SR2 Installation on UNIX |
32318 |---------+------------------------------------------------|
32319 | 0387077 | INST: R/3 4.6C SR2 Inst. on UNIX - Oracle |
32320 |---------+------------------------------------------------|
32321 | 0387078 | SAP Software on UNIX: OS Dependencies 4.6C SR2 |
32322 +----------------------------------------------------------+
32324 ----------------------------------------------------------------------
32326 22.7.4 Hardware Requirements
32328 The following equipment is sufficient for the installation of a SAP R/3
32329 System. For production use, a more exact sizing is of course needed:
32331 +-------------------------------------------------------------------+
32332 | Component | 4.6B | 4.6C |
32333 |-----------------+------------------------+------------------------|
32334 | Processor | 2 x 800MHz Pentium III | 2 x 800MHz Pentium III |
32335 |-----------------+------------------------+------------------------|
32336 | Memory | 1GB ECC | 2GB ECC |
32337 |-----------------+------------------------+------------------------|
32338 | Hard Disk Space | 50-60GB (IDES) | 50-60GB (IDES) |
32339 +-------------------------------------------------------------------+
32341 For use in production, Xeon Processors with large cache, high-speed disk
32342 access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended.
32343 The large amount of hard disk space is due to the preconfigured IDES
32344 System, which creates 27 GB of database files during installation. This
32345 space is also sufficient for initial production systems and application
32348 ----------------------------------------------------------------------
32350 22.7.4.1 SAP R/3 4.6B, Oracle 8.0.5
32352 The following off-the-shelf hardware was used: a dual processor board with
32353 two 800 MHz Pentium III processors, Adaptec 29160 Ultra160 SCSI adapter
32354 (for accessing a 40/80 GB DLT tape drive and CDROM), Mylex AcceleRAID(TM)
32355 (2 channels, firmware 6.00-1-00 with 32 MB RAM). To the Mylex RAID
32356 controller are attached two 17 GB hard disks (mirrored) and four 36 GB
32357 hard disks (RAID level 5).
32359 ----------------------------------------------------------------------
32361 22.7.4.2 SAP R/3 4.6C, Oracle 8.1.7
32363 For this installation a Dell(TM) PowerEdge(TM) 2500 was used: a dual
32364 processor board with two 1000 MHz Pentium III processors (256 kB Cache),
32365 2 GB PC133 ECC SDRAM, PERC/3 DC PCI RAID Controller with 128 MB, and an
32366 EIDE DVD-ROM drive. To the RAID controller are attached two 18 GB hard
32367 disks (mirrored) and four 36 GB hard disks (RAID level 5).
32369 ----------------------------------------------------------------------
32371 22.7.5 Installation of FreeBSD
32373 First you have to install FreeBSD.
32375 ----------------------------------------------------------------------
32377 22.7.5.1 Disk Layout
32379 To keep it simple, the same disk layout both for the SAP R/3 46B and
32380 SAP R/3 46C SR2 installation was used. Only the device names changed, as
32381 the installations were on different hardware (/dev/da and /dev/amr
32382 respectively, so if using an AMI MegaRAID, one will see /dev/amr0s1a
32383 instead of /dev/da0s1a):
32385 +--------------------------------------------------------------------+
32386 | File system | Size (1k-blocks) | Size (GB) | Mounted on |
32387 |-------------+------------------+-----------+-----------------------|
32388 | /dev/da0s1a | 1.016.303 | 1 | / |
32389 |-------------+------------------+-----------+-----------------------|
32390 | /dev/da0s1b | | 6 | swap |
32391 |-------------+------------------+-----------+-----------------------|
32392 | /dev/da0s1e | 2.032.623 | 2 | /var |
32393 |-------------+------------------+-----------+-----------------------|
32394 | /dev/da0s1f | 8.205.339 | 8 | /usr |
32395 |-------------+------------------+-----------+-----------------------|
32396 | /dev/da1s1e | 45.734.361 | 45 | /compat/linux/oracle |
32397 |-------------+------------------+-----------+-----------------------|
32398 | /dev/da1s1f | 2.032.623 | 2 | /compat/linux/sapmnt |
32399 |-------------+------------------+-----------+-----------------------|
32400 | /dev/da1s1g | 2.032.623 | 2 | /compat/linux/usr/sap |
32401 +--------------------------------------------------------------------+
32403 Configure and initialize the two logical drives with the Mylex or PERC/3
32404 RAID software beforehand. The software can be started during the BIOS boot
32407 Please note that this disk layout differs slightly from the SAP
32408 recommendations, as SAP suggests mounting the Oracle subdirectories (and
32409 some others) separately -- we decided to just create them as real
32410 subdirectories for simplicity.
32412 ----------------------------------------------------------------------
32414 22.7.5.2 make world and a New Kernel
32416 Download the latest -STABLE sources. Rebuild world and your custom kernel
32417 after configuring your kernel configuration file. Here you should also
32418 include the kernel parameters which are required for both SAP R/3 and
32421 ----------------------------------------------------------------------
32423 22.7.6 Installing the Linux Environment
32425 22.7.6.1 Installing the Linux Base System
32427 First the linux_base port needs to be installed (as root):
32429 # cd /usr/ports/emulators/linux_base
32430 # make install distclean
32432 ----------------------------------------------------------------------
32434 22.7.6.2 Installing Linux Development Environment
32436 The Linux development environment is needed, if you want to install Oracle
32437 on FreeBSD according to the Section 22.6:
32439 # cd /usr/ports/devel/linux_devtools
32440 # make install distclean
32442 The Linux development environment has only been installed for the SAP R/3
32443 46B IDES installation. It is not needed, if the Oracle DB is not relinked
32444 on the FreeBSD system. This is the case if you are using the Oracle
32445 tarball from a Linux system.
32447 ----------------------------------------------------------------------
32449 22.7.6.3 Installing the Necessary RPMs
32451 To start the R3SETUP program, PAM support is needed. During the first SAP
32452 Installation on FreeBSD 4.3-STABLE we tried to install PAM with all the
32453 required packages and finally forced the installation of the PAM package,
32454 which worked. For SAP R/3 4.6C SR2 we directly forced the installation of
32455 the PAM RPM, which also works, so it seems the dependent packages are not
32458 # rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \
32459 pam-0.68-7.i386.rpm
32461 For Oracle 8.0.5 to run the intelligent agent, we also had to install the
32462 RedHat Tcl package tcl-8.0.5-30.i386.rpm (otherwise the relinking during
32463 Oracle installation will not work). There are some other issues regarding
32464 relinking of Oracle, but that is a Oracle Linux issue, not DragonFly
32467 ----------------------------------------------------------------------
32469 22.7.6.4 Some Additional Hints
32471 It might also be a good idea to add linprocfs to /etc/fstab, for more
32472 informations, see the linprocfs(5) manual page. Another parameter to set
32473 is kern.fallback_elf_brand=3 which is done in the file /etc/sysctl.conf.
32475 ----------------------------------------------------------------------
32477 22.7.7 Creating the SAP R/3 Environment
32479 22.7.7.1 Creating the Necessary File Systems and Mountpoints
32481 For a simple installation, it is sufficient to create the following file
32484 +------------------------------------+
32485 | mount point | size in GB |
32486 |-----------------------+------------|
32487 | /compat/linux/oracle | 45 GB |
32488 |-----------------------+------------|
32489 | /compat/linux/sapmnt | 2 GB |
32490 |-----------------------+------------|
32491 | /compat/linux/usr/sap | 2 GB |
32492 +------------------------------------+
32494 It is also necessary to created some links. Otherwise the SAP Installer
32495 will complain, as it is checking the created links:
32497 # ln -s /compat/linux/oracle /oracle
32498 # ln -s /compat/linux/sapmnt /sapmnt
32499 # ln -s /compat/linux/usr/sap /usr/sap
32501 Possible error message during installation (here with System PRD and the
32502 SAP R/3 4.6C SR2 installation):
32504 INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200
32505 Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to
32506 /sapmnt/PRD/exe. Creating if it does not exist...
32508 WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400
32509 Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file
32510 /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The
32511 program cannot go on as long as this link exists at this
32512 location. Move the link to another location.
32514 ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0
32515 can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content
32518 ----------------------------------------------------------------------
32520 22.7.7.2 Creating Users and Directories
32522 SAP R/3 needs two users and three groups. The user names depend on the SAP
32523 system ID (SID) which consists of three letters. Some of these SIDs are
32524 reserved by SAP (for example SAP and NIX. For a complete list please see
32525 the SAP documentation). For the IDES installation we used IDS, for the
32526 4.6C SR2 installation PRD, as that system is intended for production use.
32527 We have therefore the following groups (group IDs might differ, these are
32528 just the values we used with our installation):
32530 +-------------------------------------------------+
32531 | group ID | group name | description |
32532 |----------+------------+-------------------------|
32533 | 100 | dba | Data Base Administrator |
32534 |----------+------------+-------------------------|
32535 | 101 | sapsys | SAP System |
32536 |----------+------------+-------------------------|
32537 | 102 | oper | Data Base Operator |
32538 +-------------------------------------------------+
32540 For a default Oracle installation, only group dba is used. As oper group,
32541 one also uses group dba (see Oracle and SAP documentation for further
32544 We also need the following users:
32546 +------------------------------------------------------------------------+
32547 | user | user name | generic | group | additional | description |
32548 | ID | | name | | groups | |
32549 |------+---------------+---------+--------+------------+-----------------|
32550 | 1000 | idsadm/prdadm | sidadm | sapsys | oper | SAP |
32551 | | | | | | Administrator |
32552 |------+---------------+---------+--------+------------+-----------------|
32553 | 1002 | oraids/oraprd | orasid | dba | oper | Oracle |
32554 | | | | | | Administrator |
32555 +------------------------------------------------------------------------+
32557 Adding the users with adduser(8) requires the following (please note shell
32558 and home directory) entries for ``SAP Administrator'':
32562 Fullname: SAP Administrator SID
32568 Shell: bash (/compat/linux/bin/bash)
32570 and for ``Oracle Administrator'':
32574 Fullname: Oracle Administrator SID
32580 Shell: bash (/compat/linux/bin/bash)
32582 This should also include group oper in case you are using both groups dba
32585 ----------------------------------------------------------------------
32587 22.7.7.3 Creating Directories
32589 These directories are usually created as separate file systems. This
32590 depends entirely on your requirements. We choose to create them as simple
32591 directories, as they are all located on the same RAID 5 anyway:
32593 First we will set owners and rights of some directories (as user root):
32595 # chmod 775 /oracle
32596 # chmod 777 /sapmnt
32597 # chown root:dba /oracle
32598 # chown sidadm:sapsys /compat/linux/usr/sap
32599 # chmod 775 /compat/linux/usr/sap
32601 Second we will create directories as user orasid. These will all be
32602 subdirectories of /oracle/SID:
32606 # mkdir mirrlogA mirrlogB origlogA origlogB
32607 # mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6
32608 # mkdir saparch sapreorg
32611 For the Oracle 8.1.7 installation some additional directories are needed:
32616 # mkdir client stage
32617 # mkdir client/80x_32
32618 # mkdir stage/817_32
32622 Note: The directory client/80x_32 is used with exactly this name. Do not
32623 replace the x with some number or anything.
32625 In the third step we create directories as user sidadm:
32633 ----------------------------------------------------------------------
32635 22.7.7.4 Entries in /etc/services
32637 SAP R/3 requires some entries in file /etc/services, which will not be set
32638 correctly during installation under FreeBSD. Please add the following
32639 entries (you need at least those entries corresponding to the instance
32640 number -- in this case, 00. It will do no harm adding all entries from 00
32641 to 99 for dp, gw, sp and ms). If you are going to use a SAProuter or need
32642 to access SAP OSS, you also need 99, as port 3299 is usually used for the
32643 SAProuter process on the target system:
32645 sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number
32646 sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number
32647 sapsp00 3400/tcp # 3400 + Instance-Number
32648 sapms00 3500/tcp # 3500 + Instance-Number
32649 sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number
32650 sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number
32652 ----------------------------------------------------------------------
32654 22.7.7.5 Necessary Locales
32656 SAP requires at least two locales that are not part of the default RedHat
32657 installation. SAP offers the required RPMs as download from their FTP
32658 server (which is only accessible if you are a customer with OSS access).
32659 See note 0171356 for a list of RPMs you need.
32661 It is also possible to just create appropriate links (for example from
32662 de_DE and en_US ), but we would not recommend this for a production system
32663 (so far it worked with the IDES system without any problems, though). The
32664 following locales are needed:
32669 Create the links like this:
32671 # cd /compat/linux/usr/share/locale
32672 # ln -s de_DE de_DE.ISO-8859-1
32673 # ln -s en_US en_US.ISO-8859-1
32675 If they are not present, there will be some problems during the
32676 installation. If these are then subsequently ignored (by setting the
32677 STATUS of the offending steps to OK in file CENTRDB.R3S), it will be
32678 impossible to log onto the SAP system without some additional effort.
32680 ----------------------------------------------------------------------
32682 22.7.7.6 Kernel Tuning
32684 SAP R/3 systems need a lot of resources. We therefore added the following
32685 parameters to the kernel configuration file:
32687 # Set these for memory pigs (SAP and Oracle):
32688 options MAXDSIZ="(1024*1024*1024)"
32689 options DFLDSIZ="(1024*1024*1024)"
32690 # System V options needed.
32691 options SYSVSHM #SYSV-style shared memory
32692 options SHMMAXPGS=262144 #max amount of shared mem. pages
32693 #options SHMMAXPGS=393216 #use this for the 46C inst.parameters
32694 options SHMMNI=256 #max number of shared memory ident if.
32695 options SHMSEG=100 #max shared mem.segs per process
32696 options SYSVMSG #SYSV-style message queues
32697 options MSGSEG=32767 #max num. of mes.segments in system
32698 options MSGSSZ=32 #size of msg-seg. MUST be power of 2
32699 options MSGMNB=65535 #max char. per message queue
32700 options MSGTQL=2046 #max amount of msgs in system
32701 options SYSVSEM #SYSV-style semaphores
32702 options SEMMNU=256 #number of semaphore UNDO structures
32703 options SEMMNS=1024 #number of semaphores in system
32704 options SEMMNI=520 #number of semaphore identifiers
32705 options SEMUME=100 #number of UNDO keys
32707 The minimum values are specified in the documentation that comes from SAP.
32708 As there is no description for Linux, see the HP-UX section (32-bit) for
32709 further information. As the system for the 4.6C SR2 installation has more
32710 main memory, the shared segments can be larger both for SAP and Oracle,
32711 therefore choose a larger number of shared memory pages.
32713 Note: With the default installation of FreeBSD 4.5 on i386, leave
32714 MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange errors like
32715 ``ORA-27102: out of memory'' and ``Linux Error: 12: Cannot allocate
32716 memory'' might happen.
32718 ----------------------------------------------------------------------
32720 22.7.8 Installing SAP R/3
32722 22.7.8.1 Preparing SAP CDROMs
32724 There are many CDROMs to mount and unmount during the installation.
32725 Assuming you have enough CDROM drives, you can just mount them all. We
32726 decided to copy the CDROMs contents to corresponding directories:
32728 /oracle/SID/sapreorg/cd-name
32730 where cd-name was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3,
32731 EXPORT4, EXPORT5 and EXPORT6 for the 4.6B/IDES installation, and KERNEL,
32732 RDBMS, DISK1, DISK2, DISK3, DISK4 and LANG for the 4.6C SR2 installation.
32733 All the filenames on the mounted CDs should be in capital letters,
32734 otherwise use the -g option for mounting. So use the following commands:
32736 # mount_cd9660 -g /dev/cd0a /mnt
32737 # cp -R /mnt/* /oracle/SID/sapreorg/cd-name
32740 ----------------------------------------------------------------------
32742 22.7.8.2 Running the Installation Script
32744 First you have to prepare an install directory:
32746 # cd /oracle/SID/sapreorg
32750 Then the installation script is started, which will copy nearly all the
32751 relevant files into the install directory:
32753 # /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH
32755 The IDES installation (4.6B) comes with a fully customized SAP R/3
32756 demonstration system, so there are six instead of just three EXPORT CDs.
32757 At this point the installation template CENTRDB.R3S is for installing a
32758 standard central instance (R/3 and database), not the IDES central
32759 instance, so one needs to copy the corresponding CENTRDB.R3S from the
32760 EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT CDs.
32762 The newer SAP 4.6C SR2 release comes with four EXPORT CDs. The parameter
32763 file that controls the installation steps is CENTRAL.R3S. Contrary to
32764 earlier releases there are no separate installation templates for a
32765 central instance with or without database. SAP is using a separate
32766 template for database installation. To restart the installation later it
32767 is however sufficient to restart with the original file.
32769 During and after installation, SAP requires hostname to return the
32770 computer name only, not the fully qualified domain name. So either set the
32771 hostname accordingly, or set an alias with alias hostname='hostname -s'
32772 for both orasid and sidadm (and for root at least during installation
32773 steps performed as root). It is also possible to adjust the installed
32774 .profile and .login files of both users that are installed during SAP
32777 ----------------------------------------------------------------------
32779 22.7.8.3 Start R3SETUP 4.6B
32781 Make sure LD_LIBRARY_PATH is set correctly:
32783 # export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib
32785 Start R3SETUP as root from installation directory:
32787 # cd /oracle/IDS/sapreorg/install
32788 # ./R3SETUP -f CENTRDB.R3S
32790 The script then asks some questions (defaults in brackets, followed by
32793 +------------------------------------------------------------------------+
32794 | Question | Default | Input |
32795 |------------+------------------------------+----------------------------|
32796 |Enter SAP |[C11] |IDSEnter |
32798 |------------+------------------------------+----------------------------|
32800 |Instance |[00] |Enter |
32802 |------------+------------------------------+----------------------------|
32804 |SAPMOUNT |[/sapmnt] |Enter |
32806 |------------+------------------------------+----------------------------|
32808 |of SAP |[troubadix.domain.de] |Enter |
32810 |------------+------------------------------+----------------------------|
32812 |of SAP db |[troubadix] |Enter |
32814 |------------+------------------------------+----------------------------|
32816 |character |[1] (WE8DEC) |Enter |
32818 |------------+------------------------------+----------------------------|
32823 |8.0.5, (2) | |1Enter |
32829 |------------+------------------------------+----------------------------|
32831 |Oracle |[1] (Yes, extract) |Enter |
32834 |------------+------------------------------+----------------------------|
32835 |Enter path |[/sapcd] |/oracle/IDS/sapreorg/KERNEL |
32837 |------------+------------------------------+----------------------------|
32838 |Enter path |[/sapcd] |/oracle/IDS/sapreorg/RDBMS |
32840 |------------+------------------------------+----------------------------|
32842 |to EXPORT1 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT1|
32844 |------------+------------------------------+----------------------------|
32846 |copy EXPORT1|[/oracle/IDS/sapreorg/CD4_DIR]|Enter |
32848 |------------+------------------------------+----------------------------|
32850 |to EXPORT2 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT2|
32852 |------------+------------------------------+----------------------------|
32854 |copy EXPORT2|[/oracle/IDS/sapreorg/CD5_DIR]|Enter |
32856 |------------+------------------------------+----------------------------|
32858 |to EXPORT3 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT3|
32860 |------------+------------------------------+----------------------------|
32862 |copy EXPORT3|[/oracle/IDS/sapreorg/CD6_DIR]|Enter |
32864 |------------+------------------------------+----------------------------|
32866 |to EXPORT4 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT4|
32868 |------------+------------------------------+----------------------------|
32870 |copy EXPORT4|[/oracle/IDS/sapreorg/CD7_DIR]|Enter |
32872 |------------+------------------------------+----------------------------|
32874 |to EXPORT5 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT5|
32876 |------------+------------------------------+----------------------------|
32878 |copy EXPORT5|[/oracle/IDS/sapreorg/CD8_DIR]|Enter |
32880 |------------+------------------------------+----------------------------|
32882 |to EXPORT6 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT6|
32884 |------------+------------------------------+----------------------------|
32886 |copy EXPORT6|[/oracle/IDS/sapreorg/CD9_DIR]|Enter |
32888 |------------+------------------------------+----------------------------|
32890 |of RAM for | |850Enter (in Megabytes) |
32892 |------------+------------------------------+----------------------------|
32894 |Entry |[3600] |Enter |
32897 |------------+------------------------------+----------------------------|
32899 |Group-ID of |[101] |Enter |
32901 |------------+------------------------------+----------------------------|
32903 |Group-ID of |[102] |Enter |
32905 |------------+------------------------------+----------------------------|
32907 |Group-ID of |[100] |Enter |
32909 |------------+------------------------------+----------------------------|
32911 |User-ID of |[1000] |Enter |
32913 |------------+------------------------------+----------------------------|
32915 |User-ID of |[1002] |Enter |
32917 |------------+------------------------------+----------------------------|
32919 |parallel |[2] |Enter |
32921 +------------------------------------------------------------------------+
32923 If you had not copied the CDs to the different locations, then the SAP
32924 installer cannot find the CD needed (identified by the LABEL.ASC file on
32925 the CD) and would then ask you to insert and mount the CD and confirm or
32926 enter the mount path.
32928 The CENTRDB.R3S might not be error free. In our case, it requested EXPORT4
32929 CD again but indicated the correct key (6_LOCATION, then 7_LOCATION etc.),
32930 so one can just continue with entering the correct values.
32932 Apart from some problems mentioned below, everything should go straight
32933 through up to the point where the Oracle database software needs to be
32936 ----------------------------------------------------------------------
32938 22.7.8.4 Start R3SETUP 4.6C SR2
32940 Make sure LD_LIBRARY_PATH is set correctly. This is a different value from
32941 the 4.6B installation with Oracle 8.0.5:
32943 # export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib
32945 Start R3SETUP as user root from installation directory:
32947 # cd /oracle/PRD/sapreorg/install
32948 # ./R3SETUP -f CENTRAL.R3S
32950 The script then asks some questions (defaults in brackets, followed by
32953 +------------------------------------------------------------------------+
32954 | Question | Default | Input |
32955 |-------------------------+----------------+-----------------------------|
32956 | Enter SAP System ID | [C11] | PRDEnter |
32957 |-------------------------+----------------+-----------------------------|
32958 | Enter SAP Instance | [00] | Enter |
32960 |-------------------------+----------------+-----------------------------|
32961 | Enter SAPMOUNT | [/sapmnt] | Enter |
32963 |-------------------------+----------------+-----------------------------|
32964 | Enter name of SAP | [majestix] | Enter |
32965 | central host | | |
32966 |-------------------------+----------------+-----------------------------|
32967 | Enter Database System | [PRD] | PRDEnter |
32969 |-------------------------+----------------+-----------------------------|
32970 | Enter name of SAP db | [majestix] | Enter |
32972 |-------------------------+----------------+-----------------------------|
32973 | Select character set | [1] (WE8DEC) | Enter |
32974 |-------------------------+----------------+-----------------------------|
32975 | Enter Oracle server | | |
32976 | version (2) Oracle | | 2Enter |
32978 |-------------------------+----------------+-----------------------------|
32979 | Extract Oracle Client | [1] (Yes, | Enter |
32980 | archive | extract) | |
32981 |-------------------------+----------------+-----------------------------|
32982 | Enter path to KERNEL CD | [/sapcd] | /oracle/PRD/sapreorg/KERNEL |
32983 |-------------------------+----------------+-----------------------------|
32984 | Enter amount of RAM for | 2044 | 1800Enter (in Megabytes) |
32986 |-------------------------+----------------+-----------------------------|
32987 | Service Entry Message | [3600] | Enter |
32989 |-------------------------+----------------+-----------------------------|
32990 | Enter Group-ID of | [100] | Enter |
32992 |-------------------------+----------------+-----------------------------|
32993 | Enter Group-ID of oper | [101] | Enter |
32994 |-------------------------+----------------+-----------------------------|
32995 | Enter Group-ID of dba | [102] | Enter |
32996 |-------------------------+----------------+-----------------------------|
32997 | Enter User-ID of oraprd | [1002] | Enter |
32998 |-------------------------+----------------+-----------------------------|
32999 | Enter User-ID of prdadm | [1000] | Enter |
33000 |-------------------------+----------------+-----------------------------|
33001 | LDAP support | | 3Enter (no support) |
33002 |-------------------------+----------------+-----------------------------|
33003 | Installation step | [1] (continue) | Enter |
33005 |-------------------------+----------------+-----------------------------|
33006 | Choose installation | [1] (DB | Enter |
33007 | service | inst,file) | |
33008 +------------------------------------------------------------------------+
33010 So far, creation of users gives an error during installation in phases
33011 OSUSERDBSID_IND_ORA (for creating user orasid) and OSUSERSIDADM_IND_ORA
33012 (creating user sidadm).
33014 Apart from some problems mentioned below, everything should go straight
33015 through up to the point where the Oracle database software needs to be
33018 ----------------------------------------------------------------------
33020 22.7.9 Installing Oracle 8.0.5
33022 Please see the corresponding SAP Notes and Oracle Readmes regarding Linux
33023 and Oracle DB for possible problems. Most if not all problems stem from
33024 incompatible libraries.
33026 For more information on installing Oracle, refer to the Installing Oracle
33029 ----------------------------------------------------------------------
33031 22.7.9.1 Installing the Oracle 8.0.5 with orainst
33033 If Oracle 8.0.5 is to be used, some additional libraries are needed for
33034 successfully relinking, as Oracle 8.0.5 was linked with an old glibc
33035 (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to
33036 install the following additional packages to ensure that linking will
33039 compat-libs-5.2-2.i386.rpm
33041 compat-glibc-5.2-2.0.7.2.i386.rpm
33043 compat-egcs-5.2-1.0.3a.1.i386.rpm
33045 compat-egcs-c++-5.2-1.0.3a.1.i386.rpm
33047 compat-binutils-5.2-2.9.1.0.23.1.i386.rpm
33049 See the corresponding SAP Notes or Oracle Readmes for further information.
33050 If this is no option (at the time of installation we did not have enough
33051 time to check this), one could use the original binaries, or use the
33052 relinked binaries from an original RedHat system.
33054 For compiling the intelligent agent, the RedHat Tcl package must be
33055 installed. If you cannot get tcl-8.0.3-20.i386.rpm, a newer one like
33056 tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do.
33058 Apart from relinking, the installation is straightforward:
33061 # export TERM=xterm
33062 # export ORACLE_TERM=xterm
33063 # export ORACLE_HOME=/oracle/IDS
33064 # cd /ORACLE_HOME/orainst_sap
33067 Confirm all screens with Enter until the software is installed, except
33068 that one has to deselect the Oracle On-Line Text Viewer, as this is not
33069 currently available for Linux. Oracle then wants to relink with
33070 i386-glibc20-linux-gcc instead of the available gcc, egcs or
33071 i386-redhat-linux-gcc .
33073 Due to time constrains we decided to use the binaries from an Oracle 8.0.5
33074 PreProduction release, after the first attempt at getting the version from
33075 the RDBMS CD working, failed, and finding and accessing the correct RPMs
33076 was a nightmare at that time.
33078 ----------------------------------------------------------------------
33080 22.7.9.2 Installing the Oracle 8.0.5 Pre-production Release for Linux
33083 This installation is quite easy. Mount the CD, start the installer. It
33084 will then ask for the location of the Oracle home directory, and copy all
33085 binaries there. We did not delete the remains of our previous RDBMS
33086 installation tries, though.
33088 Afterwards, Oracle Database could be started with no problems.
33090 ----------------------------------------------------------------------
33092 22.7.10 Installing the Oracle 8.1.7 Linux Tarball
33094 Take the tarball oracle81732.tgz you produced from the installation
33095 directory on a Linux system and untar it to /oracle/SID/817_32/.
33097 ----------------------------------------------------------------------
33099 22.7.11 Continue with SAP R/3 Installation
33101 First check the environment settings of users idsamd (sidadm) and oraids
33102 (orasid). They should now both have the files .profile, .login and .cshrc
33103 which are all using hostname. In case the system's hostname is the fully
33104 qualified name, you need to change hostname to hostname -s within all
33107 ----------------------------------------------------------------------
33109 22.7.11.1 Database Load
33111 Afterwards, R3SETUP can either be restarted or continued (depending on
33112 whether exit was chosen or not). R3SETUP then creates the tablespaces and
33113 loads the data (for 46B IDES, from EXPORT1 to EXPORT6, for 46C from DISK1
33114 to DISK4) with R3load into the database.
33116 When the database load is finished (might take a few hours), some
33117 passwords are requested. For test installations, one can use the well
33118 known default passwords (use different ones if security is an issue!):
33120 +------------------------------------------------------+
33121 | Question | Input |
33122 |-----------------------------+------------------------|
33123 | Enter Password for sapr3 | sapEnter |
33124 |-----------------------------+------------------------|
33125 | Confirum Password for sapr3 | sapEnter |
33126 |-----------------------------+------------------------|
33127 | Enter Password for sys | change_on_installEnter |
33128 |-----------------------------+------------------------|
33129 | Confirm Password for sys | change_on_installEnter |
33130 |-----------------------------+------------------------|
33131 | Enter Password for system | managerEnter |
33132 |-----------------------------+------------------------|
33133 | Confirm Password for system | managerEnter |
33134 +------------------------------------------------------+
33136 At this point We had a few problems with dipgntab during the 4.6B
33139 ----------------------------------------------------------------------
33143 Start the Oracle Listener as user orasid as follows:
33145 % umask 0; lsnrctl start
33147 Otherwise you might get the error ORA-12546 as the sockets will not have
33148 the correct permissions. See SAP Note 072984.
33150 ----------------------------------------------------------------------
33152 22.7.11.3 Updating MNLS Tables
33154 If you plan to import non-Latin-1 languages into the SAP system, you have
33155 to update the Multi National Language Support tables. This is described in
33156 the SAP OSS Notes 15023 and 45619. Otherwise, you can skip this question
33157 during SAP installation.
33159 Note: If you do not need MNLS, it is still necessary to check the table
33160 TCPDB and initializing it if this has not been done. See SAP note
33161 0015023 and 0045619 for further information.
33163 ----------------------------------------------------------------------
33165 22.7.12 Post-installation Steps
33167 22.7.12.1 Request SAP R/3 License Key
33169 You have to request your SAP R/3 License Key. This is needed, as the
33170 temporary license that was installed during installation is only valid for
33171 four weeks. First get the hardware key. Log on as user idsadm and call
33174 # /sapmnt/IDS/exe/saplicense -get
33176 Calling saplicense without parameters gives a list of options. Upon
33177 receiving the license key, it can be installed using:
33179 # /sapmnt/IDS/exe/saplicense -install
33181 You are then required to enter the following values:
33183 SAP SYSTEM ID = SID, 3 chars
33184 CUSTOMER KEY = hardware key, 11 chars
33185 INSTALLATION NO = installation, 10 digits
33186 EXPIRATION DATE = yyyymmdd, usually "99991231"
33187 LICENSE KEY = license key, 24 chars
33189 ----------------------------------------------------------------------
33191 22.7.12.2 Creating Users
33193 Create a user within client 000 (for some tasks required to be done within
33194 client 000, but with a user different from users sap* and ddic). As a user
33195 name, We usually choose wartung (or service in English). Profiles required
33196 are sap_new and sap_all. For additional safety the passwords of default
33197 users within all clients should be changed (this includes users sap* and
33200 ----------------------------------------------------------------------
33202 22.7.12.3 Configure Transport System, Profile, Operation Modes, Etc.
33204 Within client 000, user different from ddic and sap*, do at least the
33207 +------------------------------------------------------------------------+
33208 | Task | Transaction |
33209 |----------------------------------------------------------+-------------|
33210 | Configure Transport System, e.g. as Stand-Alone | STMS |
33211 | Transport Domain Entity | |
33212 |----------------------------------------------------------+-------------|
33213 | Create / Edit Profile for System | RZ10 |
33214 |----------------------------------------------------------+-------------|
33215 | Maintain Operation Modes and Instances | RZ04 |
33216 +------------------------------------------------------------------------+
33218 These and all the other post-installation steps are thoroughly described
33219 in SAP installation guides.
33221 ----------------------------------------------------------------------
33223 22.7.12.4 Edit initsid.sap (initIDS.sap)
33225 The file /oracle/IDS/dbs/initIDS.sap contains the SAP backup profile. Here
33226 the size of the tape to be used, type of compression and so on need to be
33227 defined. To get this running with sapdba / brbackup, we changed the
33230 compress = hardware
33231 archive_function = copy_delete_save
33232 cpio_flags = "-ov --format=newc --block-size=128 --quiet"
33233 cpio_in_flags = "-iuv --block-size=128 --quiet"
33235 tape_address = /dev/nsa0
33236 tape_address_rew = /dev/sa0
33240 compress: The tape we use is a HP DLT1 which does hardware compression.
33242 archive_function: This defines the default behavior for saving Oracle
33243 archive logs: new logfiles are saved to tape, already saved logfiles are
33244 saved again and are then deleted. This prevents lots of trouble if you
33245 need to recover the database, and one of the archive-tapes has gone bad.
33247 cpio_flags: Default is to use -B which sets block size to 5120 Bytes. For
33248 DLT Tapes, HP recommends at least 32 K block size, so we used
33249 --block-size=128 for 64 K. --format=newc is needed because we have inode
33250 numbers greater than 65535. The last option --quiet is needed as otherwise
33251 brbackup complains as soon as cpio outputs the numbers of blocks saved.
33253 cpio_in_flags: Flags needed for loading data back from tape. Format is
33254 recognized automatically.
33256 tape_size: This usually gives the raw storage capability of the tape. For
33257 security reason (we use hardware compression), the value is slightly lower
33258 than the actual value.
33260 tape_address: The non-rewindable device to be used with cpio.
33262 tape_address_rew: The rewindable device to be used with cpio.
33264 ----------------------------------------------------------------------
33266 22.7.12.5 Configuration Issues after Installation
33268 The following SAP parameters should be tuned after installation (examples
33269 for IDES 46B, 1 GB memory):
33272 ztta/roll_extension 250000000
33273 abap/heap_area_dia 300000000
33274 abap/heap_area_nondia 400000000
33275 em/initial_size_MB 256
33276 em/blocksize_kB 1024
33277 ipc/shm_psize_40 70000000
33282 ztta/dynpro_area 2500000
33287 rdisp/ROLL_MAXFS 16000
33288 rdisp/PG_MAXFS 30000
33290 Note: With the above parameters, on a system with 1 gigabyte of memory,
33291 one may find memory consumption similar to:
33293 Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free
33295 ----------------------------------------------------------------------
33297 22.7.13 Problems during Installation
33299 22.7.13.1 Restart R3SETUP after Fixing a Problem
33301 R3SETUP stops if it encounters an error. If you have looked at the
33302 corresponding logfiles and fixed the error, you have to start R3SETUP
33303 again, usually selecting REPEAT as option for the last step R3SETUP
33306 To restart R3SETUP, just start it with the corresponding R3S file:
33308 # ./R3SETUP -f CENTRDB.R3S
33312 # ./R3SETUP -f CENTRAL.R3S
33314 for 4.6C, no matter whether the error occurred with CENTRAL.R3S or
33317 Note: At some stages, R3SETUP assumes that both database and SAP
33318 processes are up and running (as those were steps it already completed).
33319 Should errors occur and for example the database could not be started,
33320 you have to start both database and SAP by hand after you fixed the
33321 errors and before starting R3SETUP again.
33323 Do not forget to also start the Oracle listener again (as orasid with
33324 umask 0; lsnrctl start) if it was also stopped (for example due to a
33325 necessary reboot of the system).
33327 ----------------------------------------------------------------------
33329 22.7.13.2 OSUSERSIDADM_IND_ORA during R3SETUP
33331 If R3SETUP complains at this stage, edit the template file R3SETUP used at
33332 that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S
33333 (4.6C)). Locate [OSUSERSIDADM_IND_ORA] or search for the only STATUS=ERROR
33334 entry and edit the following values:
33336 HOME=/home/sidadm (was empty)
33337 STATUS=OK (had status ERROR)
33340 Then you can restart R3SETUP again.
33342 ----------------------------------------------------------------------
33344 22.7.13.3 OSUSERDBSID_IND_ORA during R3SETUP
33346 Possibly R3SETUP also complains at this stage. The error here is similar
33347 to the one in phase OSUSERSIDADM_IND_ORA. Just edit the template file
33348 R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or
33349 DATABASE.R3S (4.6C)). Locate [OSUSERDBSID_IND_ORA] or search for the only
33350 STATUS=ERROR entry and edit the following value in that section:
33354 Then restart R3SETUP.
33356 ----------------------------------------------------------------------
33358 22.7.13.4 ``oraview.vrf FILE NOT FOUND'' during Oracle Installation
33360 You have not deselected Oracle On-Line Text Viewer before starting the
33361 installation. This is marked for installation even though this option is
33362 currently not available for Linux. Deselect this product inside the Oracle
33363 installation menu and restart installation.
33365 ----------------------------------------------------------------------
33367 22.7.13.5 ``TEXTENV_INVALID'' during R3SETUP, RFC or SAPgui Start
33369 If this error is encountered, the correct locale is missing. SAP Note
33370 0171356 lists the necessary RPMs that need be installed (e.g.
33371 saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored
33372 all the related errors and set the corresponding STATUS from ERROR to OK
33373 (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP,
33374 the SAP system will not be properly configured and you will then not be
33375 able to connect to the system with a SAPgui, even though the system can be
33376 started. Trying to connect with the old Linux SAPgui gave the following
33379 Sat May 5 14:23:14 2001
33380 *** ERROR => no valid userarea given [trgmsgo. 0401]
33381 Sat May 5 14:23:22 2001
33382 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
33383 *** ERROR => Error when generating text environment. [trgmsgi. 0435]
33384 *** ERROR => function failed [trgmsgi. 0447]
33385 *** ERROR => no socket operation allowed [trxio.c 3363]
33386 Speicherzugriffsfehler
33388 This behavior is due to SAP R/3 being unable to correctly assign a locale
33389 and also not being properly configured itself (missing entries in some
33390 database tables). To be able to connect to SAP, add the following entries
33391 to file DEFAULT.PFL (see Note 0043288):
33393 abap/set_etct_env_at_new_mode = 0
33394 install/collate/active = 0
33397 Restart the SAP system. Now you can connect to the system, even though
33398 country-specific language settings might not work as expected. After
33399 correcting country settings (and providing the correct locales), these
33400 entries can be removed from DEFAULT.PFL and the SAP system can be
33403 ----------------------------------------------------------------------
33405 22.7.13.6 ORA-00001
33407 This error only happened with Oracle 8.1.7 on FreeBSD 4.5. The reason was
33408 that the Oracle database could not initialize itself properly and crashed,
33409 leaving semaphores and shared memory on the system. The next try to start
33410 the database then returned ORA-00001.
33412 Find them with ipcs -a and remove them with ipcrm.
33414 ----------------------------------------------------------------------
33416 22.7.13.7 ORA-00445 (Background Process PMON Did Not Start)
33418 This error happened with Oracle 8.1.7. This error is reported if the
33419 database is started with the usual startsap script (for example
33420 startsap_majestix_00) as user prdadm.
33422 A possible workaround is to start the database as user oraprd instead with
33426 SVRMGR> connect internal;
33430 ----------------------------------------------------------------------
33432 22.7.13.8 ORA-12546 (Start Listener with Correct Permissions)
33434 Start the Oracle listener as user oraids with the following commands:
33436 # umask 0; lsnrctl start
33438 Otherwise you might get ORA-12546 as the sockets will not have the correct
33439 permissions. See SAP Note 0072984.
33441 ----------------------------------------------------------------------
33443 22.7.13.9 ORA-27102 (Out of Memory)
33445 This error happened whilst trying to use values for MAXDSIZ and DFLDSIZ
33446 greater than 1 GB (1024x1024x1024). Additionally, we got ``Linux Error 12:
33447 Cannot allocate memory''.
33449 ----------------------------------------------------------------------
33451 22.7.13.10 [DIPGNTAB_IND_IND] during R3SETUP
33453 In general, see SAP Note 0130581 (R3SETUP step DIPGNTAB terminates).
33454 During the IDES-specific installation, for some reasons the installation
33455 process was not using the proper SAP system name ``IDS'', but the empty
33456 string "" instead. This lead to some minor problems with accessing
33457 directories, as the paths are generated dynamically using SID (in this
33458 case IDS). So instead of accessing:
33460 /usr/sap/IDS/SYS/...
33461 /usr/sap/IDS/DVMGS00
33463 the following paths were used:
33468 To continue with the installation, we created a link and an additional
33472 /compat/linux/usr/sap
33475 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00
33476 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS
33477 lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS
33478 drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp
33479 drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans
33481 We also found SAP Notes (0029227 and 0008401) describing this behavior. We
33482 did not encounter any of these problems with the SAP 4.6C installation.
33484 ----------------------------------------------------------------------
33486 22.7.13.11 [RFCRSWBOINI_IND_IND] during R3SETUP
33488 During installation of SAP 4.6C, this error was just the result of another
33489 error happening earlier during installation. In this case, you have to
33490 look through the corresponding logfiles and correct the real problem.
33492 If after looking through the logfiles this error is indeed the correct one
33493 (check the SAP Notes), you can set STATUS of the offending step from ERROR
33494 to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have
33495 to execute the report RSWBOINS from transaction SE38. See SAP Note 0162266
33496 for additional information about phase RFCRSWBOINI and RFCRADDBDIF.
33498 ----------------------------------------------------------------------
33500 22.7.13.12 [RFCRADDBDIF_IND_IND] during R3SETUP
33502 Here the same restrictions apply: make sure by looking through the
33503 logfiles, that this error is not caused by some previous problems.
33505 If you can confirm that SAP Note 0162266 applies, just set STATUS of the
33506 offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP.
33507 After installation, you have to execute the report RADDBDIF from
33510 ----------------------------------------------------------------------
33512 22.7.13.13 sigaction sig31: File size limit exceeded
33514 This error occurred during start of SAP processes disp+work. If starting
33515 SAP with the startsap script, subprocesses are then started which detach
33516 and do the dirty work of starting all other SAP processes. As a result,
33517 the script itself will not notice if something goes wrong.
33519 To check whether the SAP processes did start properly, have a look at the
33520 process status with ps ax | grep SID, which will give you a list of all
33521 Oracle and SAP processes. If it looks like some processes are missing or
33522 if you cannot connect to the SAP system, look at the corresponding
33523 logfiles which can be found at /usr/sap/SID/DVEBMGSnr/work/. The files to
33524 look at are dev_ms and dev_disp.
33526 Signal 31 happens here if the amount of shared memory used by Oracle and
33527 SAP exceed the one defined within the kernel configuration file and could
33528 be resolved by using a larger value:
33530 # larger value for 46C production systems:
33531 options SHMMAXPGS=393216
33532 # smaller value sufficient for 46B:
33533 #options SHMMAXPGS=262144
33535 ----------------------------------------------------------------------
33537 22.7.13.14 Start of saposcol Failed
33539 There are some problems with the program saposcol (version 4.6D). The SAP
33540 system is using saposcol to collect data about the system performance.
33541 This program is not needed to use the SAP system, so this problem can be
33542 considered a minor one. The older versions (4.6B) does work, but does not
33543 collect all the data (many calls will just return 0, for example for CPU
33546 ----------------------------------------------------------------------
33548 22.8 Advanced Topics
33550 If you are curious as to how the Linux binary compatibility works, this is
33551 the section you want to read. Most of what follows is based heavily on an
33552 email written to FreeBSD chat mailing list by Terry Lambert
33553 <tlambert@primenet.com> (Message ID:
33554 <199906020108.SAA07001@usr09.primenet.com>).
33556 Warning: This description applies to FreeBSD, for which it was
33557 originally written. This may or may not apply to DragonFly at this
33558 point; while FreeBSD 4.x features usually translate over to DragonFly
33559 well, your mileage may vary.
33561 ----------------------------------------------------------------------
33563 22.8.1 How Does It Work?
33565 DragonFly has an abstraction called an ``execution class loader''. This is
33566 a wedge into the execve(2) system call.
33568 What happens is that DragonFly has a list of loaders, instead of a single
33569 loader with a fallback to the #! loader for running any shell interpreters
33572 Historically, the only loader on the UNIX platform examined the magic
33573 number (generally the first 4 or 8 bytes of the file) to see if it was a
33574 binary known to the system, and if so, invoked the binary loader.
33576 If it was not the binary type for the system, the execve(2) call returned
33577 a failure, and the shell attempted to start executing it as shell
33580 The assumption was a default of ``whatever the current shell is''.
33582 Later, a hack was made for sh(1) to examine the first two characters, and
33583 if they were :\n, then it invoked the csh(1) shell instead (we believe SCO
33584 first made this hack).
33586 What DragonFly does now is go through a list of loaders, with a generic #!
33587 loader that knows about interpreters as the characters which follow to the
33588 next whitespace next to last, followed by a fallback to /bin/sh.
33590 For the Linux ABI support, DragonFly sees the magic number as an ELF
33591 binary (it makes no distinction between FreeBSD, Solaris, Linux, or any
33592 other OS which has an ELF image type, at this point).
33594 The ELF loader looks for a specialized brand, which is a comment section
33595 in the ELF image, and which is not present on SVR4/Solaris ELF binaries.
33597 For Linux binaries to function, they must be branded as type Linux from
33600 # brandelf -t Linux file
33602 When this is done, the ELF loader will see the Linux brand on the file.
33604 When the ELF loader sees the Linux brand, the loader replaces a pointer in
33605 the proc structure. All system calls are indexed through this pointer (in
33606 a traditional UNIX system, this would be the sysent[] structure array,
33607 containing the system calls). In addition, the process is flagged for
33608 special handling of the trap vector for the signal trampoline code, and
33609 several other (minor) fix-ups that are handled by the Linux kernel module.
33611 The Linux system call vector contains, among other things, a list of
33612 sysent[] entries whose addresses reside in the kernel module.
33614 When a system call is called by the Linux binary, the trap code
33615 dereferences the system call function pointer off the proc structure, and
33616 gets the Linux, not the DragonFly, system call entry points.
33618 In addition, the Linux mode dynamically reroots lookups; this is, in
33619 effect, what the union option to file system mounts (not the unionfs file
33620 system type!) does. First, an attempt is made to lookup the file in the
33621 /compat/linux/original-path directory, then only if that fails, the lookup
33622 is done in the /original-path directory. This makes sure that binaries
33623 that require other binaries can run (e.g., the Linux toolchain can all run
33624 under Linux ABI support). It also means that the Linux binaries can load
33625 and execute DragonFly binaries, if there are no corresponding Linux
33626 binaries present, and that you could place a uname(1) command in the
33627 /compat/linux directory tree to ensure that the Linux binaries could not
33628 tell they were not running on Linux.
33630 In effect, there is a Linux kernel in the DragonFly kernel; the various
33631 underlying functions that implement all of the services provided by the
33632 kernel are identical to both the DragonFly system call table entries, and
33633 the Linux system call table entries: file system operations, virtual
33634 memory operations, signal delivery, System V IPC, etc... The only
33635 difference is that DragonFly binaries get the DragonFly glue functions,
33636 and Linux binaries get the Linux glue functions (most older OS's only had
33637 their own glue functions: addresses of functions in a static global
33638 sysent[] structure array, instead of addresses of functions dereferenced
33639 off a dynamically initialized pointer in the proc structure of the process
33642 Which one is the native DragonFly ABI? It does not matter. Basically the
33643 only difference is that (currently; this could easily be changed in a
33644 future release, and probably will be after this) the DragonFly glue
33645 functions are statically linked into the kernel, and the Linux glue
33646 functions can be statically linked, or they can be accessed via a kernel
33649 Yeah, but is this really emulation? No. It is an ABI implementation, not
33650 an emulation. There is no emulator (or simulator, to cut off the next
33651 question) involved.
33653 So why is it sometimes called ``Linux emulation''? To make it hard to sell
33654 DragonFly! Really, it is because the historical implementation was done at
33655 a time when there was really no word other than that to describe what was
33656 going on; saying that FreeBSD [14] ran Linux binaries was not true, if you
33657 did not compile the code in or load a module, and there needed to be a
33658 word to describe what was being loaded--hence ``the Linux emulator''.
33664 A. Obtaining DragonFly
33668 C. Resources on the Internet
33672 ----------------------------------------------------------------------
33674 Appendix A. Obtaining DragonFly
33676 A.1 CDROM and DVD Publishers
33678 A.1.1 Retail Products
33680 DragonFly is available as a purchasable CD:
33683 WWW: http://www.crescentanchor.com/
33686 ----------------------------------------------------------------------
33688 A.1.2 CD and DVD Sets
33690 DragonFly BSD CD and DVD sets are available from online retailers:
33693 560 South State Street, Suite A2
33696 Phone: +1 800 407-5170
33697 Fax: +1 1 801 765-0877
33698 Email: <sales@bsdmall.com>
33699 WWW: http://www.bsdmall.com/
33703 Email: <sales@bsd-systems.co.uk>
33704 WWW: http://www.bsd-systems.co.uk/
33707 ----------------------------------------------------------------------
33711 The official sources for DragonFly are available via anonymous FTP from a
33712 worldwide set of mirror sites. The site ftp://ftp.dragonflybsd.org/ is
33713 well connected and allows a large number of connections to it, but you are
33714 probably better off finding a ``closer'' mirror site (especially if you
33715 decide to set up some sort of mirror site).
33717 The DragonFly mirror sites list is the best, most up-to-date source.
33719 Additionally, DragonFly is available via anonymous FTP from the following
33720 mirror sites. If you choose to obtain DragonFly via anonymous FTP, please
33721 try to use a site near you. The mirror sites listed as ``Primary Mirror
33722 Sites'' typically have the entire DragonFly archive (all the currently
33723 available versions for each of the architectures) but you will probably
33724 have faster download times from a site that is in your country or region.
33725 The regional sites carry the most recent versions for the most popular
33726 architecture(s) but might not carry the entire DragonFly archive. All
33727 sites provide access via anonymous FTP but some sites also provide access
33728 via other methods. The access methods available for each site are provided
33729 in parentheses after the hostname.
33731 Central Servers, Primary Mirror Sites, Australia, USA.
33733 (as of 2005/06/27 23:37:47 UTC)
33737 * ftp://ftp.DragonFlyBSD.org/ (ftp)
33739 Primary Mirror Sites
33741 In case of problems, please contact <docs@DragonFlyBSD.org>.
33743 * ftp://chlamydia.fs.ei.tum.de/pub/DragonFly/ (ftp)
33745 * ftp://ftp.allbsd.org/pub/DragonFly/ (ftp)
33747 * ftp://ftp.esat.net/mirrors/chlamydia.fs.ei.tum.de/pub/DragonFly/
33750 * ftp://ftp.fortunaty.net/DragonFly/ (ftp)
33752 * ftp://ftp.univie.ac.at/systems/DragonFly/ (ftp)
33754 * ftp://cvsup.math.uic.edu/dragonflybsd/ (ftp)
33756 * ftp://ftp.starkast.net/pub/DragonFly/ (ftp)
33758 * ftp://mirror.bgp4.net/pub/DragonFly/ (ftp)
33760 * ftp://ftp.csie.chu.edu.tw/ (ftp)
33762 * ftp://dragonflybsd.cs.pu.edu.tw/DragonFLYBSD (ftp)
33764 * ftp://mirror.isp.net.au/pub/DragonFly/ (ftp)
33766 * ftp://ftp.theshell.com/pub/DragonFly/ (ftp)
33768 * ftp://mirror.macomnet.net/pub/DragonFlyBSD/ (ftp)
33770 * ftp://ftp.tu-clausthal.de/pub/DragonFly/ (ftp)
33774 In case of problems, please contact <docs@DragonFlyBSD.org>.
33776 * ftp://mirror.isp.net.au/pub/DragonFly/ (ftp / http / rsync)
33780 In case of problems, please contact <docs@DragonFlyBSD.org>.
33782 * ftp://ftp.theshell.com/pub/DragonFly/ (ftp / http / rsync)
33784 ----------------------------------------------------------------------
33790 CVSup is a software package for distributing and updating source trees
33791 from a master CVS repository on a remote server host. The DragonFly
33792 sources are maintained in a CVS repository on a central development
33793 machine in California. With CVSup, DragonFly users can easily keep their
33794 own source trees up to date.
33796 CVSup uses the so-called pull model of updating. Under the pull model,
33797 each client asks the server for updates, if and when they are wanted. The
33798 server waits passively for update requests from its clients. Thus all
33799 updates are instigated by the client. The server never sends unsolicited
33800 updates. Users must either run the CVSup client manually to get an update,
33801 or they must set up a cron job to run it automatically on a regular basis.
33803 The term CVSup, capitalized just so, refers to the entire software
33804 package. Its main components are the client cvsup which runs on each
33805 user's machine, and the server cvsupd which runs at each of the DragonFly
33806 mirror sites that use CVSup.
33808 ----------------------------------------------------------------------
33812 CVSup is installed by default on all DragonFly systems.
33814 ----------------------------------------------------------------------
33816 A.3.3 CVSup Configuration
33818 CVSup's operation is controlled by a configuration file called the
33819 supfile. There are some sample supfiles in the directory
33820 /usr/share/examples/cvsup/.
33822 The information in a supfile answers the following questions for CVSup:
33824 * Which files do you want to receive?
33826 * Which versions of them do you want?
33828 * Where do you want to get them from?
33830 * Where do you want to put them on your own machine?
33832 * Where do you want to put your status files?
33834 In the following sections, we will construct a typical supfile by
33835 answering each of these questions in turn. First, we describe the overall
33836 structure of a supfile.
33838 A supfile is a text file. Comments begin with # and extend to the end of
33839 the line. Lines that are blank and lines that contain only comments are
33842 Each remaining line describes a set of files that the user wishes to
33843 receive. The line begins with the name of a ``collection'', a logical
33844 grouping of files defined by the server. The name of the collection tells
33845 the server which files you want. After the collection name come zero or
33846 more fields, separated by white space. These fields answer the questions
33847 listed above. There are two types of fields: flag fields and value fields.
33848 A flag field consists of a keyword standing alone, e.g., delete or
33849 compress. A value field also begins with a keyword, but the keyword is
33850 followed without intervening white space by = and a second word. For
33851 example, release=cvs is a value field.
33853 A supfile typically specifies more than one collection to receive. One way
33854 to structure a supfile is to specify all of the relevant fields explicitly
33855 for each collection. However, that tends to make the supfile lines quite
33856 long, and it is inconvenient because most fields are the same for all of
33857 the collections in a supfile. CVSup provides a defaulting mechanism to
33858 avoid these problems. Lines beginning with the special pseudo-collection
33859 name *default can be used to set flags and values which will be used as
33860 defaults for the subsequent collections in the supfile. A default value
33861 can be overridden for an individual collection, by specifying a different
33862 value with the collection itself. Defaults can also be changed or
33863 augmented in mid-supfile by additional *default lines.
33865 With this background, we will now proceed to construct a supfile for
33866 receiving and updating the main source tree of DragonFly.
33868 * Which files do you want to receive?
33870 The files available via CVSup are organized into named groups called
33871 ``collections''. The collections that are available are described in
33872 the following section. In this example, we wish to receive the entire
33873 main source tree for the DragonFly system. There is a single large
33874 collection cvs-src which will give us all of that. As a first step
33875 toward constructing our supfile, we simply list the collections, one
33876 per line (in this case, only one line):
33880 * Which version(s) of them do you want?
33882 With CVSup, you can receive virtually any version of the sources that
33883 ever existed. That is possible because the cvsupd server works
33884 directly from the CVS repository, which contains all of the versions.
33885 You specify which one of them you want using the tag= and date= value
33888 Warning: Be very careful to specify any tag= fields correctly. Some
33889 tags are valid only for certain collections of files. If you specify
33890 an incorrect or misspelled tag, CVSup will delete files which you
33891 probably do not want deleted. In particular, use only tag=. for the
33892 ports-* collections.
33894 The tag= field names a symbolic tag in the repository. There are two
33895 kinds of tags, revision tags and branch tags. A revision tag refers to
33896 a specific revision. Its meaning stays the same from day to day. A
33897 branch tag, on the other hand, refers to the latest revision on a
33898 given line of development, at any given time. Because a branch tag
33899 does not refer to a specific revision, it may mean something different
33900 tomorrow than it means today.
33902 Section A.4 contains branch tags that users might be interested in.
33903 When specifying a tag in CVSup's configuration file, it must be
33904 preceded with tag= (RELENG_4 will become tag=RELENG_4). Keep in mind
33905 that only the tag=. is relevant for the ports collection.
33907 Warning: Be very careful to type the tag name exactly as shown.
33908 CVSup cannot distinguish between valid and invalid tags. If you
33909 misspell the tag, CVSup will behave as though you had specified a
33910 valid tag which happens to refer to no files at all. It will delete
33911 your existing sources in that case.
33913 When you specify a branch tag, you normally receive the latest
33914 versions of the files on that line of development. If you wish to
33915 receive some past version, you can do so by specifying a date with the
33916 date= value field. The cvsup(1) manual page explains how to do that.
33918 For our example, we wish to receive the current release of DragonFly.
33919 We add this line at the beginning of our supfile:
33923 There is an important special case that comes into play if you specify
33924 neither a tag= field nor a date= field. In that case, you receive the
33925 actual RCS files directly from the server's CVS repository, rather
33926 than receiving a particular version. Developers generally prefer this
33927 mode of operation. By maintaining a copy of the repository itself on
33928 their systems, they gain the ability to browse the revision histories
33929 and examine past versions of files. This gain is achieved at a large
33930 cost in terms of disk space, however.
33932 * Where do you want to get them from?
33934 We use the host= field to tell cvsup where to obtain its updates. Any
33935 of the CVSup mirror sites will do, though you should try to select one
33936 that is close to you in cyberspace. In this example we will use a
33937 fictional DragonFly distribution site, cvsup666.dragonflybsd.org:
33939 *default host=cvsup666.dragonflybsd.org
33941 You will need to change the host to one that actually exists before
33942 running CVSup. On any particular run of cvsup, you can override the
33943 host setting on the command line, with -h hostname.
33945 * Where do you want to put them on your own machine?
33947 The prefix= field tells cvsup where to put the files it receives. In
33948 this example, we will put the source files directly into our main
33949 source tree, /usr/src. The src directory is already implicit in the
33950 collections we have chosen to receive, so this is the correct
33953 *default prefix=/usr
33955 * Where should cvsup maintain its status files?
33957 The CVSup client maintains certain status files in what is called the
33958 ``base'' directory. These files help CVSup to work more efficiently,
33959 by keeping track of which updates you have already received. We will
33960 use the standard base directory, /usr/local/etc/cvsup:
33962 *default base=/usr/local/etc/cvsup
33964 This setting is used by default if it is not specified in the supfile,
33965 so we actually do not need the above line.
33967 If your base directory does not already exist, now would be a good
33968 time to create it. The cvsup client will refuse to run if the base
33969 directory does not exist.
33971 * Miscellaneous supfile settings:
33973 There is one more line of boiler plate that normally needs to be
33974 present in the supfile:
33976 *default release=cvs delete use-rel-suffix compress
33978 release=cvs indicates that the server should get its information out
33979 of the main DragonFly CVS repository. This is virtually always the
33980 case, but there are other possibilities which are beyond the scope of
33983 delete gives CVSup permission to delete files. You should always
33984 specify this, so that CVSup can keep your source tree fully
33985 up-to-date. CVSup is careful to delete only those files for which it
33986 is responsible. Any extra files you happen to have will be left
33989 use-rel-suffix is ... arcane. If you really want to know about it, see
33990 the cvsup(1) manual page. Otherwise, just specify it and do not worry
33993 compress enables the use of gzip-style compression on the
33994 communication channel. If your network link is T1 speed or faster, you
33995 probably should not use compression. Otherwise, it helps
33998 * Putting it all together:
34000 Here is the entire supfile for our example:
34003 *default host=cvsup666.dragonflybsd.org
34004 *default prefix=/usr
34005 *default base=/usr/local/etc/cvsup
34006 *default release=cvs delete use-rel-suffix compress
34010 ----------------------------------------------------------------------
34012 A.3.3.1 The refuse File
34014 As mentioned above, CVSup uses a pull method. Basically, this means that
34015 you connect to the CVSup server, and it says, ``Here is what you can
34016 download from me...'', and your client responds ``OK, I will take this,
34017 this, this, and this.'' In the default configuration, the CVSup client
34018 will take every file associated with the collection and tag you chose in
34019 the configuration file. However, this is not always what you want,
34020 especially if you are synching the doc, ports, or www trees -- most people
34021 cannot read four or five languages, and therefore they do not need to
34022 download the language-specific files. If you are CVSuping the ports
34023 collection, you can get around this by specifying each collection
34024 individually (e.g., ports-astrology, ports-biology, etc instead of simply
34025 saying ports-all). However, since the doc and www trees do not have
34026 language-specific collections, you must use one of CVSup's many nifty
34027 features: the refuse file.
34029 The refuse file essentially tells CVSup that it should not take every
34030 single file from a collection; in other words, it tells the client to
34031 refuse certain files from the server. The refuse file can be found (or, if
34032 you do not yet have one, should be placed) in base/sup/. base is defined
34033 in your supfile; by default, base is /usr/local/etc/cvsup, which means
34034 that by default the refuse file is /usr/local/etc/cvsup/sup/refuse.
34036 The refuse file has a very simple format; it simply contains the names of
34037 files or directories that you do not wish to download. For example, if you
34038 cannot speak any languages other than English and some German, and you do
34039 not feel the need to use the German applications (or applications for any
34040 other languages, except for English), you can put the following in your
34070 and so forth for the other languages (you can find the full list by
34071 browsing the FreeBSD CVS repository).
34073 With this very useful feature, those users who are on slow links or pay by
34074 the minute for their Internet connection will be able to save valuable
34075 time as they will no longer need to download files that they will never
34076 use. For more information on refuse files and other neat features of
34077 CVSup, please view its manual page.
34079 ----------------------------------------------------------------------
34081 A.3.4 Running CVSup
34083 You are now ready to try an update. The command line for doing this is
34088 where supfile is of course the name of the supfile you have just created.
34089 Assuming you are running under X11, cvsup will display a GUI window with
34090 some buttons to do the usual things. Press the go button, and watch it
34093 Since you are updating your actual /usr/src tree in this example, you will
34094 need to run the program as root so that cvsup has the permissions it needs
34095 to update your files. Having just created your configuration file, and
34096 having never used this program before, that might understandably make you
34097 nervous. There is an easy way to do a trial run without touching your
34098 precious files. Just create an empty directory somewhere convenient, and
34099 name it as an extra argument on the command line:
34101 # mkdir /var/tmp/dest
34102 # cvsup supfile /var/tmp/dest
34104 The directory you specify will be used as the destination directory for
34105 all file updates. CVSup will examine your usual files in /usr/src, but it
34106 will not modify or delete any of them. Any file updates will instead land
34107 in /var/tmp/dest/usr/src. CVSup will also leave its base directory status
34108 files untouched when run this way. The new versions of those files will be
34109 written into the specified directory. As long as you have read access to
34110 /usr/src, you do not even need to be root to perform this kind of trial
34113 If you are not running X11 or if you just do not like GUIs, you should add
34114 a couple of options to the command line when you run cvsup:
34116 # cvsup -g -L 2 supfile
34118 The -g tells CVSup not to use its GUI. This is automatic if you are not
34119 running X11, but otherwise you have to specify it.
34121 The -L 2 tells CVSup to print out the details of all the file updates it
34122 is doing. There are three levels of verbosity, from -L 0 to -L 2. The
34123 default is 0, which means total silence except for error messages.
34125 There are plenty of other options available. For a brief list of them,
34126 type cvsup -H. For more detailed descriptions, see the manual page.
34128 Once you are satisfied with the way updates are working, you can arrange
34129 for regular runs of CVSup using cron(8). Obviously, you should not let
34130 CVSup use its GUI when running it from cron(8).
34132 ----------------------------------------------------------------------
34134 A.3.5 CVSup File Collections
34136 The most commonly used collections are cvs-src, and cvs-dfports.
34140 The DragonFly source code.
34144 Documentation. This does not include the DragonFly website.
34148 Overrides for the FreeBSD Ports Collection.
34152 The DragonFly website code.
34156 Basic CVS data. This is only needed if you are pulling the RCS
34159 ----------------------------------------------------------------------
34161 A.3.6 For More Information
34163 For the CVSup FAQ and other information about CVSup, see The CVSup Home
34166 Questions and bug reports should be addressed to the author of the program
34167 at <cvsup-bugs@polstra.com>.
34169 ----------------------------------------------------------------------
34173 CVSup servers for DragonFly are running at the following sites:
34175 Primary Mirror Sites, Australia, USA.
34177 (as of 2005/06/27 23:37:47 UTC)
34179 Primary Mirror Sites
34181 * chlamydia.fs.ei.tum.de
34185 * grappa.unix-ag.uni-kl.de
34187 * mirror.isp.net.au
34191 * dragonflybsd.delphij.net
34193 * fred.acm.cs.rpi.edu
34197 * mirror.isp.net.au
34201 * fred.acm.cs.rpi.edu
34203 ----------------------------------------------------------------------
34207 When obtaining or updating sources from cvs and CVSup a revision tag
34208 (reference to a date in time) must be specified.
34210 A revision tag refers to either a particular line of DragonFly
34211 development, or a specific point in time. The first type are called
34212 ``branch tags'', the second type are called ``release tags''.
34214 ----------------------------------------------------------------------
34218 The DragonFly tree has no branch tags at the current time.
34220 ----------------------------------------------------------------------
34224 These tags correspond to the DragonFly src/ tree at a specific point in
34225 time, when a particular version was released.
34229 The latest bleeding-edge DragonFly code. Be warned that this is
34230 considered unstable and possibly may not build or compile at any
34235 A "preview" of the latest bleeding-edge DragonFly code. The main
34236 purpose of the Preview tag is to support those users who want a
34237 fairly recent snapshot at a "reasonably stable" point in
34238 development. Under normal conditions, one should consider syncing
34239 Preview at least once a month.
34241 DragonFly_RELEASE_1_2
34249 ----------------------------------------------------------------------
34251 Appendix B. Bibliography
34253 While the manual pages provide the definitive reference for individual
34254 pieces of the DragonFly operating system, they are notorious for not
34255 illustrating how to put the pieces together to make the whole operating
34256 system run smoothly. For this, there is no substitute for a good book on
34257 UNIX system administration and a good users' manual.
34259 ----------------------------------------------------------------------
34261 B.1 Books & Magazines Specific to BSD
34263 International books & Magazines:
34265 * Using FreeBSD (in Chinese).
34267 * FreeBSD for PC 98'ers (in Japanese), published by SHUWA System Co,
34268 LTD. ISBN 4-87966-468-5 C3055 P2900E.
34270 * FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 C3055
34273 * Complete Introduction to FreeBSD (in Japanese), published by Shoeisha
34274 Co., Ltd. ISBN 4-88135-473-6 P3600E.
34276 * Personal UNIX Starter Kit FreeBSD (in Japanese), published by ASCII.
34277 ISBN 4-7561-1733-3 P3000E.
34279 * FreeBSD Handbook (Japanese translation), published by ASCII. ISBN
34280 4-7561-1580-2 P3800E.
34282 * FreeBSD mit Methode (in German), published by Computer und Literatur
34283 Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.
34285 * FreeBSD 4 - Installieren, Konfigurieren, Administrieren (in German),
34286 published by Computer und Literatur Verlag, 2001. ISBN 3-932311-88-4.
34288 * FreeBSD 5 - Installieren, Konfigurieren, Administrieren (in German),
34289 published by Computer und Literatur Verlag, 2003. ISBN 3-936546-06-1.
34291 * FreeBSD de Luxe (in German), published by Verlag Modere Industrie,
34292 2003. ISBN 3-8266-1343-0.
34294 * FreeBSD Install and Utilization Manual (in Japanese), published by
34295 Mainichi Communications Inc..
34297 * Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil Widodo Building
34298 Internet Server with FreeBSD (in Indonesia Language), published by
34299 Elex Media Komputindo.
34301 English language books & Magazines:
34303 * Absolute BSD: The Ultimate Guide to FreeBSD, published by No Starch
34304 Press, 2002. ISBN: 1886411743
34306 * The Complete FreeBSD, published by O'Reilly, 2003. ISBN: 0596005164
34308 * The FreeBSD Corporate Networker's Guide, published by Addison-Wesley,
34309 2000. ISBN: 0201704811
34311 * FreeBSD: An Open-Source Operating System for Your Personal Computer,
34312 published by The Bit Tree Press, 2001. ISBN: 0971204500
34314 * Teach Yourself FreeBSD in 24 Hours, published by Sams, 2002. ISBN:
34317 * FreeBSD unleashed, published by Sams, 2002. ISBN: 0672324563
34319 * FreeBSD: The Complete Reference, published by McGrawHill, 2003. ISBN:
34322 ----------------------------------------------------------------------
34326 * Computer Systems Research Group, UC Berkeley. 4.4BSD User's Reference
34327 Manual. O'Reilly & Associates, Inc., 1994. ISBN 1-56592-075-9
34329 * Computer Systems Research Group, UC Berkeley. 4.4BSD User's
34330 Supplementary Documents. O'Reilly & Associates, Inc., 1994. ISBN
34333 * UNIX in a Nutshell. O'Reilly & Associates, Inc., 1990. ISBN 093717520X
34335 * Mui, Linda. What You Need To Know When You Can't Find Your UNIX System
34336 Administrator. O'Reilly & Associates, Inc., 1995. ISBN 1-56592-104-6
34338 * Ohio State University has written a UNIX Introductory Course which is
34339 available online in HTML and PostScript format.
34341 An Italian translation of this document is available as part of the
34342 FreeBSD Italian Documentation Project.
34344 * Jpman Project, Japan FreeBSD Users Group. FreeBSD User's Reference
34345 Manual (Japanese translation). Mainichi Communications Inc., 1998.
34346 ISBN4-8399-0088-4 P3800E.
34348 * Edinburgh University has written an Online Guide for newcomers to the
34351 ----------------------------------------------------------------------
34353 B.3 Administrators' Guides
34355 * Albitz, Paul and Liu, Cricket. DNS and BIND, 4th Ed. O'Reilly &
34356 Associates, Inc., 2001. ISBN 1-59600-158-4
34358 * Computer Systems Research Group, UC Berkeley. 4.4BSD System Manager's
34359 Manual. O'Reilly & Associates, Inc., 1994. ISBN 1-56592-080-5
34361 * Costales, Brian, et al. Sendmail, 2nd Ed. O'Reilly & Associates, Inc.,
34362 1997. ISBN 1-56592-222-0
34364 * Frisch, AEleen. Essential System Administration, 2nd Ed. O'Reilly &
34365 Associates, Inc., 1995. ISBN 1-56592-127-5
34367 * Hunt, Craig. TCP/IP Network Administration, 2nd Ed. O'Reilly &
34368 Associates, Inc., 1997. ISBN 1-56592-322-7
34370 * Nemeth, Evi. UNIX System Administration Handbook. 3rd Ed. Prentice
34371 Hall, 2000. ISBN 0-13-020601-6
34373 * Stern, Hal Managing NFS and NIS O'Reilly & Associates, Inc., 1991.
34376 * Jpman Project, Japan FreeBSD Users Group. FreeBSD System
34377 Administrator's Manual (Japanese translation). Mainichi Communications
34378 Inc., 1998. ISBN4-8399-0109-0 P3300E.
34380 * Dreyfus, Emmanuel. Cahiers de l'Admin: BSD (in French), Eyrolles,
34381 2003. ISBN 2-212-11244-0
34383 ----------------------------------------------------------------------
34385 B.4 Programmers' Guides
34387 * Asente, Paul, Converse, Diana, and Swick, Ralph. X Window System
34388 Toolkit. Digital Press, 1998. ISBN 1-55558-178-1
34390 * Computer Systems Research Group, UC Berkeley. 4.4BSD Programmer's
34391 Reference Manual. O'Reilly & Associates, Inc., 1994. ISBN
34394 * Computer Systems Research Group, UC Berkeley. 4.4BSD Programmer's
34395 Supplementary Documents. O'Reilly & Associates, Inc., 1994. ISBN
34398 * Harbison, Samuel P. and Steele, Guy L. Jr. C: A Reference Manual. 4rd
34399 ed. Prentice Hall, 1995. ISBN 0-13-326224-3
34401 * Kernighan, Brian and Dennis M. Ritchie. The C Programming Language..
34402 PTR Prentice Hall, 1988. ISBN 0-13-110362-9
34404 * Lehey, Greg. Porting UNIX Software. O'Reilly & Associates, Inc., 1995.
34407 * Plauger, P. J. The Standard C Library. Prentice Hall, 1992. ISBN
34410 * Spinellis, Diomidis. Code Reading: The Open Source Perspective.
34411 Addison-Wesley, 2003. ISBN 0-201-79940-5
34413 * Stevens, W. Richard. Advanced Programming in the UNIX Environment.
34414 Reading, Mass. : Addison-Wesley, 1992. ISBN 0-201-56317-7
34416 * Stevens, W. Richard. UNIX Network Programming. 2nd Ed, PTR Prentice
34417 Hall, 1998. ISBN 0-13-490012-X
34419 * Wells, Bill. ``Writing Serial Drivers for UNIX''. Dr. Dobb's Journal.
34420 19(15), December 1994. pp68-71, 97-99.
34422 ----------------------------------------------------------------------
34424 B.5 Operating System Internals
34426 * Andleigh, Prabhat K. UNIX System Architecture. Prentice-Hall, Inc.,
34427 1990. ISBN 0-13-949843-5
34429 * Jolitz, William. ``Porting UNIX to the 386''. Dr. Dobb's Journal.
34430 January 1991-July 1992.
34432 * Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and John
34433 Quarterman The Design and Implementation of the 4.3BSD UNIX Operating
34434 System. Reading, Mass. : Addison-Wesley, 1989. ISBN 0-201-06196-1
34436 * Leffler, Samuel J., Marshall Kirk McKusick, The Design and
34437 Implementation of the 4.3BSD UNIX Operating System: Answer Book.
34438 Reading, Mass. : Addison-Wesley, 1991. ISBN 0-201-54629-9
34440 * McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and John
34441 Quarterman. The Design and Implementation of the 4.4BSD Operating
34442 System. Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-54979-4
34444 (Chapter 2 of this book is available online as part of the FreeBSD
34445 Documentation Project, and chapter 9 here.)
34447 * Stevens, W. Richard. TCP/IP Illustrated, Volume 1: The Protocols.
34448 Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-63346-9
34450 * Schimmel, Curt. Unix Systems for Modern Architectures. Reading, Mass.
34451 : Addison-Wesley, 1994. ISBN 0-201-63338-8
34453 * Stevens, W. Richard. TCP/IP Illustrated, Volume 3: TCP for
34454 Transactions, HTTP, NNTP and the UNIX Domain Protocols. Reading, Mass.
34455 : Addison-Wesley, 1996. ISBN 0-201-63495-3
34457 * Vahalia, Uresh. UNIX Internals -- The New Frontiers. Prentice Hall,
34458 1996. ISBN 0-13-101908-2
34460 * Wright, Gary R. and W. Richard Stevens. TCP/IP Illustrated, Volume 2:
34461 The Implementation. Reading, Mass. : Addison-Wesley, 1995. ISBN
34464 ----------------------------------------------------------------------
34466 B.6 Security Reference
34468 * Cheswick, William R. and Steven M. Bellovin. Firewalls and Internet
34469 Security: Repelling the Wily Hacker. Reading, Mass. : Addison-Wesley,
34470 1995. ISBN 0-201-63357-4
34472 * Garfinkel, Simson and Gene Spafford. Practical UNIX & Internet
34473 Security. 2nd Ed. O'Reilly & Associates, Inc., 1996. ISBN
34476 * Garfinkel, Simson. PGP Pretty Good Privacy O'Reilly & Associates,
34477 Inc., 1995. ISBN 1-56592-098-8
34479 ----------------------------------------------------------------------
34481 B.7 Hardware Reference
34483 * Anderson, Don and Tom Shanley. Pentium Processor System Architecture.
34484 2nd Ed. Reading, Mass. : Addison-Wesley, 1995. ISBN 0-201-40992-5
34486 * Ferraro, Richard F. Programmer's Guide to the EGA, VGA, and Super VGA
34487 Cards. 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN
34490 * Intel Corporation publishes documentation on their CPUs, chipsets and
34491 standards on their developer web site, usually as PDF files.
34493 * Shanley, Tom. 80486 System Architecture. 3rd ed. Reading, Mass. :
34494 Addison-Wesley, 1995. ISBN 0-201-40994-1
34496 * Shanley, Tom. ISA System Architecture. 3rd ed. Reading, Mass. :
34497 Addison-Wesley, 1995. ISBN 0-201-40996-8
34499 * Shanley, Tom. PCI System Architecture. 4th ed. Reading, Mass. :
34500 Addison-Wesley, 1999. ISBN 0-201-30974-2
34502 * Van Gilluwe, Frank. The Undocumented PC, 2nd Ed. Reading, Mass:
34503 Addison-Wesley Pub. Co., 1996. ISBN 0-201-47950-8
34505 * Messmer, Hans-Peter. The Indispensable PC Hardware Book, 4th Ed.
34506 Reading, Mass: Addison-Wesley Pub. Co., 2002. ISBN 0-201-59616-4
34508 ----------------------------------------------------------------------
34512 * Lion, John Lion's Commentary on UNIX, 6th Ed. With Source Code. ITP
34513 Media Group, 1996. ISBN 1573980137
34515 * Raymond, Eric S. The New Hacker's Dictionary, 3rd edition. MIT Press,
34516 1996. ISBN 0-262-68092-0. Also known as the Jargon File
34518 * Salus, Peter H. A Quarter Century of UNIX. Addison-Wesley Publishing
34519 Company, Inc., 1994. ISBN 0-201-54777-5
34521 * Simon Garfinkel, Daniel Weise, Steven Strassmann. The UNIX-HATERS
34522 Handbook. IDG Books Worldwide, Inc., 1994. ISBN 1-56884-203-1
34524 * Don Libes, Sandy Ressler Life with UNIX -- special edition.
34525 Prentice-Hall, Inc., 1989. ISBN 0-13-536657-7
34527 * The BSD family tree.
34528 http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree
34529 or /usr/share/misc/bsd-family-tree on a modern FreeBSD machine.
34531 * The BSD Release Announcements collection. 1997.
34532 http://www.de.FreeBSD.org/de/ftp/releases/
34534 * Networked Computer Science Technical Reports Library.
34535 http://www.ncstrl.org/
34537 * Old BSD releases from the Computer Systems Research group (CSRG).
34538 http://www.mckusick.com/csrg/: The 4CD set covers all BSD versions
34539 from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately).
34540 As well, the last disk holds the final sources plus the SCCS files.
34542 ----------------------------------------------------------------------
34544 B.9 Magazines and Journals
34546 * The C/C++ Users Journal. R&D Publications Inc. ISSN 1075-2838
34548 * Sys Admin -- The Journal for UNIX System Administrators Miller
34549 Freeman, Inc., ISSN 1061-2688
34551 * freeX -- Das Magazin fu:r Linux - BSD - UNIX (in German) Computer- und
34552 Literaturverlag GmbH, ISSN 1436-7033
34554 ----------------------------------------------------------------------
34556 Appendix C. Resources on the Internet
34558 The rapid pace of DragonFly progress makes print media impractical as a
34559 means of following the latest developments. Electronic resources are the
34560 best, if not often the only, way stay informed of the latest advances.
34561 Since DragonFly is a volunteer effort, the user community itself also
34562 generally serves as a ``technical support department'' of sorts, with
34563 electronic mail and USENET news being the most effective way of reaching
34566 The most important points of contact with the DragonFly user community are
34567 outlined below. If you are aware of other resources not mentioned here,
34568 please send them to the DragonFly Documentation project mailing list so
34569 that they may also be included.
34571 ----------------------------------------------------------------------
34575 Though many of the DragonFly development members read USENET, we cannot
34576 always guarantee that we will get to your questions in a timely fashion
34577 (or at all) if you post them only to one of the comp.unix.bsd.* groups. By
34578 addressing your questions to the appropriate mailing list you will reach
34579 both us and a concentrated DragonFly audience, invariably assuring a
34580 better (or at least faster) response.
34582 The charters for the various lists are given at the bottom of this
34583 document. Please read the charter before joining or sending mail to any
34584 list. Most of our list subscribers now receive many hundreds of DragonFly
34585 related messages every day, and by setting down charters and rules for
34586 proper use we are striving to keep the signal-to-noise ratio of the lists
34587 high. To do less would see the mailing lists ultimately fail as an
34588 effective communications medium for the project.
34590 Archives are kept for all of the mailing lists and can be searched using
34591 the mail archives. The keyword searchable archive offers an excellent way
34592 of finding answers to frequently asked questions and should be consulted
34593 before posting a question.
34595 ----------------------------------------------------------------------
34599 General lists: The following are general lists which anyone is free (and
34600 encouraged) to join:
34604 commits Messages generated by code changes to DragonFly source,
34605 documentation, or the website.
34606 docs Discussion of DragonFly documentation
34607 kernel Ostensibly for discussion of kernel work, though this list also
34608 serves as a catch-all for any topic pertaining to DragonFly.
34609 submit Submission and discussion of new code or ideas for DragonFly.
34610 Test For testing your newsreader or mail software.
34611 users User related discussion about DragonFly.
34613 ----------------------------------------------------------------------
34615 C.1.2 How to Subscribe
34617 To subscribe to a list, click on the list name above or send an email to
34618 <listname-request@dragonflybsd.org> and put 'subscribe' in the body of the
34621 To actually post to a given list you simply send mail to
34622 <listname@dragonflybsd.org>. It will then be redistributed to mailing list
34623 members world-wide.
34625 To unsubscribe yourself from a list, email
34626 <listname-request@dragonflybsd.org> and put 'unsubscribe' in the body of
34629 ----------------------------------------------------------------------
34631 C.1.3 List Charters
34633 All DragonFly mailing lists have certain basic rules which must be adhered
34634 to by anyone using them. Failure to comply with these guidelines may
34635 result in from all DragonFly mailing lists and filtered from further
34636 posting to them. We regret that such rules and measures are necessary at
34637 all, but today's Internet is a pretty harsh environment, it would seem,
34638 and many fail to appreciate just how fragile some of its mechanisms are.
34642 * The topic of any posting should adhere to the basic charter of the
34643 list it is posted to, e.g. if the list is about technical issues then
34644 your posting should contain technical discussion. Ongoing irrelevant
34645 chatter or flaming only detracts from the value of the mailing list
34646 for everyone on it and will not be tolerated.
34648 * No posting should be made to more than two mailing lists, and only to
34649 two when a clear and obvious need to post to both lists exists. For
34650 most lists, there is already a great deal of subscriber overlap. If a
34651 message is sent to you in such a way that multiple mailing lists
34652 appear on the Cc line then the Cc line should also be trimmed before
34653 sending it out again. You are still responsible for your own
34654 cross-postings, no matter who the originator might have been.
34656 * Personal attacks and profanity (in the context of an argument) are not
34657 allowed, and that includes users and developers alike. Gross breaches
34658 of netiquette, like excerpting or reposting private mail when
34659 permission to do so was not and would not be forthcoming, are frowned
34660 upon but not specifically enforced. However, there are also very few
34661 cases where such content would fit within the charter of a list and it
34662 would therefore probably rate a warning (or ban) on that basis alone.
34664 * Advertising of non-DragonFly related products or services is strictly
34665 prohibited and will result in an immediate ban if it is clear that the
34666 offender is advertising by spam.
34668 ----------------------------------------------------------------------
34670 C.1.4 Filtering on the Mailing Lists
34672 The DragonFly mailing lists are filtered in multiple ways to avoid the
34673 distribution of spam, viruses, and other unwanted emails. The filtering
34674 actions described in this section do not include all those used to protect
34677 Only certain types of attachments are allowed on the mailing lists. All
34678 attachments with a MIME content type not found in the list below will be
34679 stripped before an email is distributed on the mailing lists.
34681 * application/octet-stream
34685 * application/pgp-signature
34687 * application/x-pkcs7-signature
34691 * multipart/alternative
34693 * multipart/related
34705 Note: Some of the mailing lists might allow attachments of other MIME
34706 content types, but the above list should be applicable for most of the
34709 If an email contains both an HTML and a plain text version, the HTML
34710 version will be removed. If an email contains only an HTML version, it
34711 will be converted to plain text.
34713 ----------------------------------------------------------------------
34715 C.2 Usenet Newsgroups
34717 All the DragonFly mailing lists are duplicated as newsgroups, served at
34718 nntp.dragonflybsd.org.
34720 In addition to these newsgroups, there are many others in which DragonFly
34721 is discussed or are otherwise relevant to DragonFly users. Keyword
34722 searchable archives are available for some of these newsgroups from
34723 courtesy of Warren Toomey <wkt@cs.adfa.edu.au>.
34725 ----------------------------------------------------------------------
34727 C.2.1 BSD Specific Newsgroups
34729 * comp.unix.bsd.freebsd.announce
34731 * de.comp.os.unix.bsd (German)
34733 * fr.comp.os.bsd (French)
34735 * it.comp.os.freebsd (Italian)
34737 ----------------------------------------------------------------------
34739 C.2.2 Other UNIX Newsgroups of Interest
34743 * comp.unix.questions
34747 * comp.unix.programmer
34751 * comp.unix.user-friendly
34753 * comp.security.unix
34755 * comp.sources.unix
34757 * comp.unix.advocacy
34763 * comp.bugs.4bsd.ucb-fixes
34767 ----------------------------------------------------------------------
34769 C.2.3 X Window System
34771 * comp.windows.x.i386unix
34775 * comp.windows.x.apps
34777 * comp.windows.x.announce
34779 * comp.windows.x.intrinsics
34781 * comp.windows.x.motif
34783 * comp.windows.x.pex
34785 * comp.emulators.ms-windows.wine
34787 ----------------------------------------------------------------------
34789 C.3 World Wide Web Servers
34793 (as of 2005/06/27 23:37:47 UTC)
34797 * http://www.DragonFlyBSD.org/
34799 ----------------------------------------------------------------------
34801 Appendix D. PGP Keys
34803 In case you need to verify a signature or send encrypted email to one of
34804 the developers, a number of keys are provided here for your convenience.
34806 ----------------------------------------------------------------------
34810 D.1.1 Hiten Pandya <hmp at dragonflybsd.org>
34812 pub 1024D/938CACA8 2004-02-13 Hiten Pandya (FreeBSD) <hmp@FreeBSD.org>
34813 Key fingerprint = 84EB C75E C75A 50ED 304E E446 D974 7842 938C ACA8
34814 uid Hiten Pandya <hmp@backplane.com>
34815 sub 2048g/783874B5 2004-02-13
34817 -----BEGIN PGP PUBLIC KEY BLOCK-----
34819 mQGiBEAscLQRBADERe+RX2eJpYLoaJ7d29B8YcTYzNlsfzghM1R1/Dx2RDy5poKa
34820 Jn9j+Iptq1qS9GkTHXFcQh8LT2K7wnE/MZTCxkZvg2ZkfQbJ4Z+0z3A1A6Kvg0tH
34821 X5aqmPUeLXvnps7nqZxkhl2ibcjhH/VYZK3mdRikd1wtJD1EhbbeqaR8BwCgkQAG
34822 vdJHN9gfjLLcM12EitkjoUcEALoo1bPoULWd4YhVH7W5L3Qp0dr1vf5pYC/V7FQ+
34823 8yPXZtGzMvIld8iX1sv/zsw4EoXXsaRzJo/ixdCS1WYBPowryu0G/LX5w0RTTGHc
34824 ihcHLm6ZmyNuIsTQ1ifLNASJoLkNBlQAuA0VG4evAujrmaWyEHbbIDSQKUJOjL9u
34825 jb2HA/9pycrr3+735Aa7B5jThN6p1XEC8GQg5MDx23QnTPj9QHXH4qs7s+hwxZq9
34826 3WkVFBcJtDBi8PeEVqfD/QPeU3ewbnNnfaF46miGV1iG1mzU4zMq4n5oBdijf5eL
34827 cRRdOJytYKTvlSCe8gf0MzfaB3RqD8+Cjcs3PtQOy1VT4aQiv7QgSGl0ZW4gUGFu
34828 ZHlhIDxobXBAYmFja3BsYW5lLmNvbT6IXgQTEQIAHgUCQCxw7AIbAwYLCQgHAwID
34829 FQIDAxYCAQIeAQIXgAAKCRDZdHhCk4ysqEPZAJ9ByMndfTtnnVIbsyHc2NjDp5F/
34830 vgCeP6o87Lw4aHuGo5guA9yeWwtwAla0KEhpdGVuIFBhbmR5YSAoRnJlZUJTRCkg
34831 PGhtcEBGcmVlQlNELm9yZz6IYQQTEQIAIQIbAwYLCQgHAwIDFQIDAxYCAQIeAQIX
34832 gAUCQCxxDgIZAQAKCRDZdHhCk4ysqLchAJ4+01/uQVdqdDeESGodcvgKsrieqACb
34833 BIW7HMvh85WqofTeAK5pJu7hCM25Ag0EQCxw2BAIAPXEkkg6lSxGRmVH1yzRnSKr
34834 /M48xyRXYDrRPaVVBFkC4Af3CR5MjncJtjbzm7xH82glC67cksRTfTZRs7kJsid+
34835 g62V53dAu1Uoj8ecSDhblb8yW3rTLKVqGcliGcTRFivcm+ZFm0kc0xCQE3rd1COX
34836 NLEomMV6xuZ9PVzDAbJwAoGdpCYsCl09eZrTErueQ7pEVsLx9/0zQSmC/uDFEVZ7
34837 23GsJg23+EUBT5KuTxQ4i0k++Ccr4HR/OiUy6KmyXSNsKsBsXwm3map3Debqqqx1
34838 ssrDXa+PHkKEUrONQBoYbZ17DpPZb+NKWibi0Vp1HKPP2vZl4NZQC0GBLXbEudMA
34839 AwYIAOYhwVTWKQSgeEZUNe4PwvHczx8/3VNjYZGY6/ZRjgmfO3+MagjonZqfxYha
34840 GpsEV17NXm4WIg6HWtI43JwIWfkUybsdxQVH4i5lWYuA26wD6UtNXw9laPHKXonR
34841 DvmKDC6K0iFbSxTqXRZVQ//wMxh58/Yw/fX+fYtmH6u6kPaL+CPRkhQLezTzZWHj
34842 2wF6v+frdglW1/LpwpCFndb1i5+36ogZ5ZudG/iz53QzlOF0IZSGHIb9tlQ+4gUn
34843 KfxpQloI+5vAyqpHDKIH9K26wTBzKsp5Mt4W6cLfgjXs7TNc8BVT8d4rmmbGpGnG
34844 pSjj7b1q6EhpIVBkAMLw7qanLlCISQQYEQIACQUCQCxw2AIbDAAKCRDZdHhCk4ys
34845 qAuZAJ0VNEtJSZOAGetxBJ/BMWahVD8xeQCfVKwTHdPh83Qcf28xx81icY5OKY0=
34847 -----END PGP PUBLIC KEY BLOCK-----
34849 ----------------------------------------------------------------------
34853 This book is the combined work of hundreds of contributors to ``The
34854 FreeBSD Documentation Project'' and the ``The DragonFly BSD Documentation
34855 Project''. The text is authored in SGML according to the DocBook DTD and
34856 is formatted from SGML into many different presentation formats using
34857 Jade, an open source DSSSL engine. Norm Walsh's DSSSL stylesheets were
34858 used with an additional customization layer to provide the presentation
34859 instructions for Jade. The printed version of this document would not be
34860 possible without Donald Knuth's TeX typesetting language, Leslie Lamport's
34861 LaTeX, or Sebastian Rahtz's JadeTeX macro package.
34865 [1] This is what i386 means. Note that even if you are not running
34866 DragonFly on an Intel 386 CPU, this is going to be i386. It is not
34867 the type of your processor, but the processor ``architecture'' that
34869 [2] Startup scripts are programs that are run automatically by DragonFly
34870 when booting. Their main function is to set things up for everything
34871 else to run, and start any services that you have configured to run
34872 in the background doing useful things.
34873 [3] A fairly technical and accurate description of all the details of the
34874 DragonFly console and keyboard drivers can be found in the manual
34875 pages of syscons(4), atkbd(4), vidcontrol(1) and kbdcontrol(1). We
34876 will not expand on the details here, but the interested reader can
34877 always consult the manual pages for a more detailed and thorough
34878 explanation of how things work.
34879 [4] Not quite true--there are a few things that can not be interrupted.
34880 For example, if the process is trying to read from a file that is on
34881 another computer on the network, and the other computer has gone away
34882 for some reason (been turned off, or the network has a fault), then
34883 the process is said to be ``uninterruptible''. Eventually the process
34884 will time out, typically after two minutes. As soon as this time out
34885 occurs the process will be killed.
34886 [5] Previously this was used to define *BSD dependent features.
34887 [6] Well, unless you hook up multiple terminals, but we will save that
34889 [7] It is possible to use UID/GIDs as large as 4294967295, but such IDs
34890 can cause serious problems with software that makes assumptions about
34892 [8] The -s makes adduser(8) default to quiet. We use -v later when we
34893 want to change defaults.
34894 [9] The auto-tuning algorithm sets maxuser equal to the amount of memory
34895 in the system, with a minimum of 32, and a maximum of 384.
34896 [10] Under DragonFly the standard login password may be up to 128
34897 characters in length.
34898 [11] RAID stands for Redundant Array of Inexpensive Disks and offers
34899 various forms of fault tolerance, though the latter term is somewhat
34900 misleading: it provides no redundancy.
34901 [12] A popular familiar graphics card with generally very good XFree86
34902 performance, nVidia, has yet to release the specifications on their
34903 XVideo support to the XFree86 team. It may be some time before
34904 XFree86 fully support XVideo for these cards.
34905 [13] Unauthorized DVD playback is a serious criminal act in some
34906 countries. Check local laws before enabling this option.
34907 [14] FreeBSD's original Linux compatibility code was committed in June
34908 1995. It fulfilled milestone number one: running DOOM.
34910 ----------------------------------------------------------------------
34912 Contact the Documentation mailing list for comments, suggestions and questions
34913 about this document.
projects / dragonfly.git / blob