1 $DragonFly: src/share/doc/handbook/Attic/handbook.txt,v 1.1 2006/07/14 21:42:07 swildner 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.
8277 The above option specifies the type of CPU you have in your system. You
8278 may have multiple instances of the CPU line (i.e., you are not sure
8279 whether you should use I586_CPU or I686_CPU), however, for a custom
8280 kernel, it is best to specify only the CPU you have. If you are unsure of
8281 your CPU type, you can check the /var/run/dmesg.boot file to view your
8286 This is the identification of the kernel. You should change this to
8287 whatever you named your kernel, i.e. MYKERNEL if you have followed the
8288 instructions of the previous examples. The value you put in the ident
8289 string will print when you boot up the kernel, so it is useful to give the
8290 new kernel a different name if you want to keep it separate from your
8291 usual kernel (i.e. you want to build an experimental kernel).
8295 The maxusers option sets the size of a number of important system tables.
8296 This number is supposed to be roughly equal to the number of simultaneous
8297 users you expect to have on your machine.
8299 (Recommended) The system will auto-tune this setting for you if you
8300 explicitly set it to 0[9]. If you want to manage it yourself you will want
8301 to set maxusers to at least 4, especially if you are using the X Window
8302 System or compiling software. The reason is that the most important table
8303 set by maxusers is the maximum number of processes, which is set to 20 +
8304 16 * maxusers, so if you set maxusers to 1, then you can only have 36
8305 simultaneous processes, including the 18 or so that the system starts up
8306 at boot time, and the 15 or so you will probably create when you start the
8307 X Window System. Even a simple task like reading a manual page will start
8308 up nine processes to filter, decompress, and view it. Setting maxusers to
8309 64 will allow you to have up to 1044 simultaneous processes, which should
8310 be enough for nearly all uses. If, however, you see the dreaded proc table
8311 full error when trying to start another program, or are running a server
8312 with a large number of simultaneous users, you can always increase the
8315 Note: maxusers does not limit the number of users which can log into
8316 your machine. It simply sets various table sizes to reasonable values
8317 considering the maximum number of users you will likely have on your
8318 system and how many processes each of them will be running. One keyword
8319 which does limit the number of simultaneous remote logins and X terminal
8320 windows is pseudo-device pty 16.
8322 # Floating point support - do not disable.
8323 device npx0 at nexus? port IO_NPX irq 13
8325 npx0 is the interface to the floating point math unit in DragonFly, which
8326 is either the hardware co-processor or the software math emulator. This is
8329 # Pseudo devices - the number indicates how many units to allocate.
8330 pseudo-device loop # Network loopback
8332 This is the generic loopback device for TCP/IP. If you telnet or FTP to
8333 localhost (a.k.a., 127.0.0.1) it will come back at you through this
8334 device. This is mandatory.
8336 Everything that follows is more or less optional. See the notes underneath
8337 or next to each option for more information.
8339 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
8341 The normal build process of the DragonFly does not include debugging
8342 information when building the kernel and strips most symbols after the
8343 resulting kernel is linked, to save some space at the install location. If
8344 you are going to do tests of kernels in the DEVELOPMENT branch or develop
8345 changes of your own for the DragonFly kernel, you might want to uncomment
8346 this line. It will enable the use of the -g option which enables debugging
8347 information when passed to gcc(1).
8349 options MATH_EMULATE #Support for x87 emulation
8351 This line allows the kernel to simulate a math co-processor if your
8352 computer does not have one (386 or 486SX). If you have a 486DX, or a 386
8353 or 486SX (with a separate 387 or 487 chip), or higher (Pentium,
8354 Pentium II, etc.), you can comment this line out.
8356 Note: The normal math co-processor emulation routines that come with
8357 DragonFly are not very accurate. If you do not have a math co-processor,
8358 and you need the best accuracy, it is recommended that you change this
8359 option to GPL_MATH_EMULATE to use the GNU math support, which is not
8360 included by default for licensing reasons.
8362 options INET #InterNETworking
8364 Networking support. Leave this in, even if you do not plan to be connected
8365 to a network. Most programs require at least loopback networking (i.e.,
8366 making network connections within your PC), so this is essentially
8369 options INET6 #IPv6 communications protocols
8371 This enables the IPv6 communication protocols.
8373 options FFS #Berkeley Fast Filesystem
8374 options FFS_ROOT #FFS usable as root device [keep this!]
8376 This is the basic hard drive Filesystem. Leave it in if you boot from the
8379 options UFS_DIRHASH #Improve performance on big directories
8381 This option includes functionality to speed up disk operations on large
8382 directories, at the expense of using additional memory. You would normally
8383 keep this for a large server, or interactive workstation, and remove it if
8384 you are using DragonFly on a smaller system where memory is at a premium
8385 and disk access speed is less important, such as a firewall.
8387 options SOFTUPDATES #Enable FFS Soft Updates support
8389 This option enables Soft Updates in the kernel, this will help speed up
8390 write access on the disks. Even when this functionality is provided by the
8391 kernel, it must be turned on for specific disks. Review the output from
8392 mount(8) to see if Soft Updates is enabled for your system disks. If you
8393 do not see the soft-updates option then you will need to activate it using
8394 the tunefs(8) (for existing filesystems) or newfs(8) (for new filesystems)
8397 options MFS #Memory Filesystem
8398 options MD_ROOT #MD is a potential root device
8400 This is the memory-mapped filesystem. This is basically a RAM disk for
8401 fast storage of temporary files, useful if you have a lot of swap space
8402 that you want to take advantage of. A perfect place to mount an MFS
8403 partition is on the /tmp directory, since many programs store temporary
8404 data here. To mount an MFS RAM disk on /tmp, add the following line to
8407 /dev/ad1s2b /tmp mfs rw 0 0
8409 Now you simply need to either reboot, or run the command mount /tmp.
8411 options NFS #Network Filesystem
8412 options NFS_ROOT #NFS usable as root device, NFS required
8414 The network Filesystem. Unless you plan to mount partitions from a UNIX
8415 file server over TCP/IP, you can comment these out.
8417 options MSDOSFS #MSDOS Filesystem
8419 The MS-DOS Filesystem. Unless you plan to mount a DOS formatted hard drive
8420 partition at boot time, you can safely comment this out. It will be
8421 automatically loaded the first time you mount a DOS partition, as
8422 described above. Also, the excellent mtools software (in pkgsrc) allows
8423 you to access DOS floppies without having to mount and unmount them (and
8424 does not require MSDOSFS at all).
8426 options CD9660 #ISO 9660 Filesystem
8427 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
8429 The ISO 9660 Filesystem for CDROMs. Comment it out if you do not have a
8430 CDROM drive or only mount data CDs occasionally (since it will be
8431 dynamically loaded the first time you mount a data CD). Audio CDs do not
8432 need this Filesystem.
8434 options PROCFS #Process filesystem
8436 The process filesystem. This is a ``pretend'' filesystem mounted on /proc
8437 which allows programs like ps(1) to give you more information on what
8438 processes are running.
8440 options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]
8442 Compatibility with 4.3BSD. Leave this in; some programs will act strangely
8443 if you comment this out.
8445 options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI
8447 This causes the kernel to pause for 15 seconds before probing each SCSI
8448 device in your system. If you only have IDE hard drives, you can ignore
8449 this, otherwise you will probably want to lower this number, perhaps to
8450 five seconds (5000 ms), to speed up booting. Of course, if you do this,
8451 and DragonFly has trouble recognizing your SCSI devices, you will have to
8454 options UCONSOLE #Allow users to grab the console
8456 Allow users to grab the console, which is useful for X users. For example,
8457 you can create a console xterm by typing xterm -C, which will display any
8458 write(1), talk(1), and any other messages you receive, as well as any
8459 console messages sent by the kernel.
8461 options USERCONFIG #boot -c editor
8463 This option allows you to boot the configuration editor from the boot
8466 options VISUAL_USERCONFIG #visual boot -c editor
8468 This option allows you to boot the visual configuration editor from the
8471 options KTRACE #ktrace(1) support
8473 This enables kernel process tracing, which is useful in debugging.
8475 options SYSVSHM #SYSV-style shared memory
8477 This option provides for System V shared memory. The most common use of
8478 this is the XSHM extension in X, which many graphics-intensive programs
8479 will automatically take advantage of for extra speed. If you use X, you
8480 will definitely want to include this.
8482 options SYSVSEM #SYSV-style semaphores
8484 Support for System V semaphores. Less commonly used but only adds a few
8485 hundred bytes to the kernel.
8487 options SYSVMSG #SYSV-style message queues
8489 Support for System V messages. Again, only adds a few hundred bytes to the
8492 Note: The ipcs(1) command will list any processes using each of these
8493 System V facilities.
8495 options P1003_1B #Posix P1003_1B real-time extensions
8496 options _KPOSIX_PRIORITY_SCHEDULING
8498 Real-time extensions added in the 1993 POSIX(R). Certain applications in
8499 the ports collection use these (such as StarOffice).
8501 options ICMP_BANDLIM #Rate limit bad replies
8503 This option enables ICMP error response bandwidth limiting. You typically
8504 want this option as it will help protect the machine from denial of
8505 service packet attacks.
8507 # To make an SMP kernel, the next two are needed
8508 #options SMP # Symmetric MultiProcessor Kernel
8509 #options APIC_IO # Symmetric (APIC) I/O
8511 The above are both required for SMP support.
8515 All PCs supported by DragonFly have one of these. Do not remove, even if
8516 you have no ISA slots. If you have an IBM PS/2 (Micro Channel
8517 Architecture), DragonFly provides some limited support at this time. For
8518 more information about the MCA support, see /usr/src/sys/i386/conf/LINT.
8522 Include this if you have an EISA motherboard. This enables auto-detection
8523 and configuration support for all devices on the EISA bus.
8527 Include this if you have a PCI motherboard. This enables auto-detection of
8528 PCI cards and gatewaying from the PCI to ISA bus.
8532 Include this if you have an AGP card in the system. This will enable
8533 support for AGP, and AGP GART for boards which have these features.
8536 device fdc0 at isa? port IO_FD1 irq 6 drq 2
8537 device fd0 at fdc0 drive 0
8538 device fd1 at fdc0 drive 1
8540 This is the floppy drive controller. fd0 is the A: floppy drive, and fd1
8545 This driver supports all ATA and ATAPI devices. You only need one device
8546 ata line for the kernel to detect all PCI ATA/ATAPI devices on modern
8549 device atadisk # ATA disk drives
8551 This is needed along with device ata for ATA disk drives.
8553 device atapicd # ATAPI CDROM drives
8555 This is needed along with device ata for ATAPI CDROM drives.
8557 device atapifd # ATAPI floppy drives
8559 This is needed along with device ata for ATAPI floppy drives.
8561 device atapist # ATAPI tape drives
8563 This is needed along with device ata for ATAPI tape drives.
8565 options ATA_STATIC_ID #Static device numbering
8567 This makes the controller number static (like the old driver) or else the
8568 device numbers are dynamically allocated.
8570 # ATA and ATAPI devices
8571 device ata0 at isa? port IO_WD1 irq 14
8572 device ata1 at isa? port IO_WD2 irq 15
8574 Use the above for older, non-PCI systems.
8577 device ahb # EISA AHA1742 family
8578 device ahc # AHA2940 and onboard AIC7xxx devices
8579 device amd # AMD 53C974 (Teckram DC-390(T))
8580 device dpt # DPT Smartcache - See LINT for options!
8581 device isp # Qlogic family
8582 device ncr # NCR/Symbios Logic
8583 device sym # NCR/Symbios Logic (newer chipsets)
8591 SCSI controllers. Comment out any you do not have in your system. If you
8592 have an IDE only system, you can remove these altogether.
8595 device scbus # SCSI bus (required)
8596 device da # Direct Access (disks)
8597 device sa # Sequential Access (tape etc)
8599 device pass # Passthrough device (direct SCSI
8602 SCSI peripherals. Again, comment out any you do not have, or if you have
8603 only IDE hardware, you can remove them completely.
8605 Note: The USB umass(4) driver (and a few other drivers) use the SCSI
8606 subsystem even though they are not real SCSI devices. Therefore make
8607 sure not to remove SCSI support, if any such drivers are included in the
8608 kernel configuration.
8611 device ida # Compaq Smart RAID
8612 device amr # AMI MegaRAID
8613 device mlx # Mylex DAC960 family
8615 Supported RAID controllers. If you do not have any of these, you can
8616 comment them out or remove them.
8618 # atkbdc0 controls both the keyboard and the PS/2 mouse
8619 device atkbdc0 at isa? port IO_KBD
8621 The keyboard controller (atkbdc) provides I/O services for the AT keyboard
8622 and PS/2 style pointing devices. This controller is required by the
8623 keyboard driver (atkbd) and the PS/2 pointing device driver (psm).
8625 device atkbd0 at atkbdc? irq 1
8627 The atkbd driver, together with atkbdc controller, provides access to the
8628 AT 84 keyboard or the AT enhanced keyboard which is connected to the AT
8629 keyboard controller.
8631 device psm0 at atkbdc? irq 12
8633 Use this device if your mouse plugs into the PS/2 mouse port.
8637 The video card driver.
8639 # splash screen/screen saver
8640 pseudo-device splash
8642 Splash screen at start up! Screen savers require this too.
8644 # syscons is the default console driver, resembling an SCO console
8647 sc0 is the default console driver, which resembles a SCO console. Since
8648 most full-screen programs access the console through a terminal database
8649 library like termcap, it should not matter whether you use this or vt0,
8650 the VT220 compatible console driver. When you log in, set your TERM
8651 variable to scoansi if full-screen programs have trouble running under
8654 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
8656 #options XSERVER # support for X server on a vt console
8657 #options FAT_CURSOR # start with block cursor
8658 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
8659 #options PCVT_SCANSET=2 # IBM keyboards are non-std
8661 This is a VT220-compatible console driver, backward compatible to
8662 VT100/102. It works well on some laptops which have hardware
8663 incompatibilities with sc0. Also set your TERM variable to vt100 or vt220
8664 when you log in. This driver might also prove useful when connecting to a
8665 large number of different machines over the network, where termcap or
8666 terminfo entries for the sc0 device are often not available -- vt100
8667 should be available on virtually any platform.
8669 # Power management support (see LINT for more options)
8670 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
8672 Advanced Power Management support. Useful for laptops.
8674 # PCCARD (PCMCIA) support
8676 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
8677 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
8679 PCMCIA support. You want this if you are using a laptop.
8681 # Serial (COM) ports
8682 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
8683 device sio1 at isa? port IO_COM2 irq 3
8684 device sio2 at isa? disable port IO_COM3 irq 5
8685 device sio3 at isa? disable port IO_COM4 irq 9
8687 These are the four serial ports referred to as COM1 through COM4 in the
8688 MS-DOS/Windows world.
8690 Note: If you have an internal modem on COM4 and a serial port at COM2,
8691 you will have to change the IRQ of the modem to 2 (for obscure technical
8692 reasons, IRQ2 = IRQ 9) in order to access it from DragonFly. If you have
8693 a multiport serial card, check the manual page for sio(4) for more
8694 information on the proper values for these lines. Some video cards
8695 (notably those based on S3 chips) use IO addresses in the form of
8696 0x*2e8, and since many cheap serial cards do not fully decode the 16-bit
8697 IO address space, they clash with these cards making the COM4 port
8698 practically unavailable.
8700 Each serial port is required to have a unique IRQ (unless you are using
8701 one of the multiport cards where shared interrupts are supported), so
8702 the default IRQs for COM3 and COM4 cannot be used.
8705 device ppc0 at isa? irq 7
8707 This is the ISA-bus parallel port interface.
8709 device ppbus # Parallel port bus (required)
8711 Provides support for the parallel port bus.
8713 device lpt # Printer
8715 Support for parallel port printers.
8717 Note: All three of the above are required to enable parallel printer
8720 device plip # TCP/IP over parallel
8722 This is the driver for the parallel network interface.
8724 device ppi # Parallel port interface device
8726 The general-purpose I/O (``geek port'') + IEEE1284 I/O.
8728 #device vpo # Requires scbus and da
8730 This is for an Iomega Zip drive. It requires scbus and da support. Best
8731 performance is achieved with ports in EPP 1.9 mode.
8733 # PCI Ethernet NICs.
8734 device de # DEC/Intel DC21x4x (``Tulip'')
8735 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
8736 device tx # SMC 9432TX (83c170 ``EPIC'')
8737 device vx # 3Com 3c590, 3c595 (``Vortex'')
8738 device wx # Intel Gigabit Ethernet Card (``Wiseman'')
8740 Various PCI network card drivers. Comment out or remove any of these not
8741 present in your system.
8743 # PCI Ethernet NICs that use the common MII bus controller code.
8744 device miibus # MII bus support
8746 MII bus support is required for some PCI 10/100 Ethernet NICs, namely
8747 those which use MII-compliant transceivers or implement transceiver
8748 control interfaces that operate like an MII. Adding device miibus to the
8749 kernel config pulls in support for the generic miibus API and all of the
8750 PHY drivers, including a generic one for PHYs that are not specifically
8751 handled by an individual driver.
8753 device dc # DEC/Intel 21143 and various workalikes
8754 device rl # RealTek 8129/8139
8755 device sf # Adaptec AIC-6915 (``Starfire'')
8756 device sis # Silicon Integrated Systems SiS 900/SiS 7016
8757 device ste # Sundance ST201 (D-Link DFE-550TX)
8758 device tl # Texas Instruments ThunderLAN
8759 device vr # VIA Rhine, Rhine II
8760 device wb # Winbond W89C840F
8761 device xl # 3Com 3c90x (``Boomerang'', ``Cyclone'')
8763 Drivers that use the MII bus controller code.
8765 # ISA Ethernet NICs.
8766 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
8769 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
8770 # exists only as a PCMCIA device, so there is no ISA attachment needed
8771 # and resources will always be dynamically assigned by the pccard code.
8773 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
8774 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
8775 # mode (the factory default). If you set the switches on your ISA
8776 # card for a manually chosen I/O address and IRQ, you must specify
8777 # those parameters here.
8779 # The probe order of these is presently determined by i386/isa/isa_compat.c.
8780 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
8781 device fe0 at isa? port 0x300
8782 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
8783 device lnc0 at isa? port 0x280 irq 10 drq 0
8784 device cs0 at isa? port 0x300
8785 device sn0 at isa? port 0x300 irq 10
8786 # requires PCCARD (PCMCIA) support to be activated
8789 ISA Ethernet drivers. See /usr/src/sys/i386/conf/LINT for which cards are
8790 supported by which driver.
8792 pseudo-device ether # Ethernet support
8794 ether is only needed if you have an Ethernet card. It includes generic
8795 Ethernet protocol code.
8797 pseudo-device sl 1 # Kernel SLIP
8799 sl is for SLIP support. This has been almost entirely supplanted by PPP,
8800 which is easier to set up, better suited for modem-to-modem connection,
8801 and more powerful. The number after sl specifies how many simultaneous
8802 SLIP sessions to support.
8804 pseudo-device ppp 1 # Kernel PPP
8806 This is for kernel PPP support for dial-up connections. There is also a
8807 version of PPP implemented as a userland application that uses tun and
8808 offers more flexibility and features such as demand dialing. The number
8809 after ppp specifies how many simultaneous PPP connections to support. .
8811 device tun # Packet tunnel.
8813 This is used by the userland PPP software. A number after tun specifies
8814 the number of simultaneous PPP sessions to support. See the PPP section of
8815 this book for more information.
8817 pseudo-device pty # Pseudo-ttys (telnet etc)
8819 This is a ``pseudo-terminal'' or simulated login port. It is used by
8820 incoming telnet and rlogin sessions, xterm, and some other applications
8821 such as Emacs. The number after pty indicates the number of ptys to
8822 create. If you need more than the default of 16 simultaneous xterm windows
8823 and/or remote logins, be sure to increase this number accordingly, up to a
8826 pseudo-device md # Memory ``disks''
8828 Memory disk pseudo-devices.
8830 pseudo-device gif # IPv6 and IPv4 tunneling
8832 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4
8833 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
8835 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
8837 This pseudo-device captures packets that are sent to it and diverts them
8838 to the IPv4/IPv6 translation daemon.
8840 # The `bpf' device enables the Berkeley Packet Filter.
8841 # Be aware of the administrative consequences of enabling this!
8842 pseudo-device bpf # Berkeley packet filter
8844 This is the Berkeley Packet Filter. This pseudo-device allows network
8845 interfaces to be placed in promiscuous mode, capturing every packet on a
8846 broadcast network (e.g., an Ethernet). These packets can be captured to
8847 disk and or examined with the tcpdump(1) program.
8849 Note: The bpf(4) device is also used by dhclient(8) to obtain the IP
8850 address of the default router (gateway) and so on. If you use DHCP,
8851 leave this uncommented.
8854 #device uhci # UHCI PCI->USB interface
8855 #device ohci # OHCI PCI->USB interface
8856 #device usb # USB Bus (required)
8857 #device ugen # Generic
8858 #device uhid # ``Human Interface Devices''
8859 #device ukbd # Keyboard
8860 #device ulpt # Printer
8861 #device umass # Disks/Mass storage - Requires scbus and da
8863 # USB Ethernet, requires mii
8864 #device aue # ADMtek USB ethernet
8865 #device cue # CATC USB ethernet
8866 #device kue # Kawasaki LSI USB ethernet
8868 Support for various USB devices.
8870 For more information and additional devices supported by DragonFly, see
8871 /usr/src/sys/i386/conf/LINT.
8873 ----------------------------------------------------------------------
8875 9.5 Making Device Nodes
8877 Almost every device in the kernel has a corresponding ``node'' entry in
8878 the /dev directory. These nodes look like regular files, but are actually
8879 special entries into the kernel which programs use to access the device.
8880 The shell script /dev/MAKEDEV, which is executed when you first install
8881 the operating system, creates nearly all of the device nodes supported.
8882 However, it does not create all of them, so when you add support for a new
8883 device, it pays to make sure that the appropriate entries are in this
8884 directory, and if not, add them. Here is a simple example:
8886 Suppose you add the IDE CD-ROM support to the kernel. The line to add is:
8890 This means that you should look for some entries that start with acd0 in
8891 the /dev directory, possibly followed by a letter, such as c, or preceded
8892 by the letter r, which means a ``raw'' device. It turns out that those
8893 files are not there, so you must change to the /dev directory and type:
8897 When this script finishes, you will find that there are now acd0c and
8898 racd0c entries in /dev so you know that it executed correctly.
8900 For sound cards, the following command creates the appropriate entries:
8904 Note: When creating device nodes for devices such as sound cards, if
8905 other people have access to your machine, it may be desirable to protect
8906 the devices from outside access by adding them to the /etc/fbtab file.
8907 See fbtab(5) for more information.
8909 Follow this simple procedure for any other non-GENERIC devices which do
8912 Note: All SCSI controllers use the same set of /dev entries, so you do
8913 not need to create these. Also, network cards and SLIP/PPP
8914 pseudo-devices do not have entries in /dev at all, so you do not have to
8915 worry about these either.
8917 ----------------------------------------------------------------------
8919 9.6 If Something Goes Wrong
8921 There are five categories of trouble that can occur when building a custom
8926 If the config(8) command fails when you give it your kernel
8927 description, you have probably made a simple error somewhere.
8928 Fortunately, config(8) will print the line number that it had
8929 trouble with, so you can quickly skip to it with vi. For example,
8932 config: line 17: syntax error
8934 You can skip to the problem in vi by typing 17G in command mode.
8935 Make sure the keyword is typed correctly, by comparing it to the
8936 GENERIC kernel or another reference.
8940 If the make command fails, it usually signals an error in your
8941 kernel description, but not severe enough for config(8) to catch
8942 it. Again, look over your configuration, and if you still cannot
8943 resolve the problem, send mail to the DragonFly Bugs mailing list
8944 with your kernel configuration, and it should be diagnosed very
8947 Installing the new kernel fails:
8949 If the kernel compiled fine, but failed to install (the make
8950 install or make installkernel command failed), the first thing to
8951 check is if your system is running at securelevel 1 or higher (see
8952 init(8)). The kernel installation tries to remove the immutable
8953 flag from your kernel and set the immutable flag on the new one.
8954 Since securelevel 1 or higher prevents unsetting the immutable
8955 flag for any files on the system, the kernel installation needs to
8956 be performed at securelevel 0 or lower.
8958 The kernel does not boot:
8960 If your new kernel does not boot, or fails to recognize your
8961 devices, do not panic! Fortunately, DragonFly has an excellent
8962 mechanism for recovering from incompatible kernels. Simply choose
8963 the kernel you want to boot from at the DragonFly boot loader. You
8964 can access this when the system counts down from 10. Hit any key
8965 except for the Enter key, type unload and then type boot
8966 kernel.old, or the filename of any other kernel that will boot
8967 properly. When reconfiguring a kernel, it is always a good idea to
8968 keep a kernel that is known to work on hand.
8970 After booting with a good kernel you can check over your
8971 configuration file and try to build it again. One helpful resource
8972 is the /var/log/messages file which records, among other things,
8973 all of the kernel messages from every successful boot. Also, the
8974 dmesg(8) command will print the kernel messages from the current
8977 Note: If you are having trouble building a kernel, make sure to
8978 keep a GENERIC, or some other kernel that is known to work on
8979 hand as a different name that will not get erased on the next
8980 build. You cannot rely on kernel.old because when installing a
8981 new kernel, kernel.old is overwritten with the last installed
8982 kernel which may be non-functional. Also, as soon as possible,
8983 move the working kernel to the proper kernel location or
8984 commands such as ps(1) will not work properly. The proper
8985 command to ``unlock'' the kernel file that make installs (in
8986 order to move another kernel back permanently) is:
8988 # chflags noschg /kernel
8990 If you find you cannot do this, you are probably running at a
8991 securelevel(8) greater than zero. Edit kern_securelevel in
8992 /etc/rc.conf and set it to -1, then reboot. You can change it
8993 back to its previous setting when you are happy with your new
8996 And, if you want to ``lock'' your new kernel into place, or any
8997 file for that matter, so that it cannot be moved or tampered
9000 # chflags schg /kernel
9002 The kernel works, but ps(1) does not work any more:
9004 If you have installed a different version of the kernel from the
9005 one that the system utilities have been built with, many
9006 system-status commands like ps(1) and vmstat(8) will not work any
9007 more. You must recompile the libkvm library as well as these
9008 utilities. This is one reason it is not normally a good idea to
9009 use a different version of the kernel from the rest of the
9012 ----------------------------------------------------------------------
9016 Much of this chapter has been taken from the security(7) manual page by
9019 ----------------------------------------------------------------------
9023 This chapter will provide a basic introduction to system security
9024 concepts, some general good rules of thumb, and some advanced topics under
9025 DragonFly. A lot of the topics covered here can be applied to system and
9026 Internet security in general as well. The Internet is no longer a
9027 ``friendly'' place in which everyone wants to be your kind neighbor.
9028 Securing your system is imperative to protect your data, intellectual
9029 property, time, and much more from the hands of hackers and the like.
9031 DragonFly provides an array of utilities and mechanisms to ensure the
9032 integrity and security of your system and network.
9034 After reading this chapter, you will know:
9036 * Basic system security concepts, in respect to DragonFly.
9038 * About the various crypt mechanisms available in DragonFly, such as DES
9041 * How to set up one-time password authentication.
9043 * How to set up KerberosIV.
9045 * How to set up Kerberos5.
9047 * How to create firewalls using IPFW.
9049 * How to configure IPsec and create a VPN between DragonFly/Windows
9052 * How to configure and use OpenSSH, DragonFly's SSH implementation.
9054 Before reading this chapter, you should:
9056 * Understand basic DragonFly and Internet concepts.
9058 ----------------------------------------------------------------------
9062 Security is a function that begins and ends with the system administrator.
9063 While all BSD UNIX multi-user systems have some inherent security, the job
9064 of building and maintaining additional security mechanisms to keep those
9065 users ``honest'' is probably one of the single largest undertakings of the
9066 sysadmin. Machines are only as secure as you make them, and security
9067 concerns are ever competing with the human necessity for convenience. UNIX
9068 systems, in general, are capable of running a huge number of simultaneous
9069 processes and many of these processes operate as servers -- meaning that
9070 external entities can connect and talk to them. As yesterday's
9071 mini-computers and mainframes become today's desktops, and as computers
9072 become networked and internetworked, security becomes an even bigger
9075 Security is best implemented through a layered ``onion'' approach. In a
9076 nutshell, what you want to do is to create as many layers of security as
9077 are convenient and then carefully monitor the system for intrusions. You
9078 do not want to overbuild your security or you will interfere with the
9079 detection side, and detection is one of the single most important aspects
9080 of any security mechanism. For example, it makes little sense to set the
9081 schg flags (see chflags(1)) on every system binary because while this may
9082 temporarily protect the binaries, it prevents an attacker who has broken
9083 in from making an easily detectable change that may result in your
9084 security mechanisms not detecting the attacker at all.
9086 System security also pertains to dealing with various forms of attack,
9087 including attacks that attempt to crash, or otherwise make a system
9088 unusable, but do not attempt to compromise the root account (``break
9089 root''). Security concerns can be split up into several categories:
9091 1. Denial of service attacks.
9093 2. User account compromises.
9095 3. Root compromise through accessible servers.
9097 4. Root compromise via user accounts.
9099 5. Backdoor creation.
9101 A denial of service attack is an action that deprives the machine of
9102 needed resources. Typically, DoS attacks are brute-force mechanisms that
9103 attempt to crash or otherwise make a machine unusable by overwhelming its
9104 servers or network stack. Some DoS attacks try to take advantage of bugs
9105 in the networking stack to crash a machine with a single packet. The
9106 latter can only be fixed by applying a bug fix to the kernel. Attacks on
9107 servers can often be fixed by properly specifying options to limit the
9108 load the servers incur on the system under adverse conditions. Brute-force
9109 network attacks are harder to deal with. A spoofed-packet attack, for
9110 example, is nearly impossible to stop, short of cutting your system off
9111 from the Internet. It may not be able to take your machine down, but it
9112 can saturate your Internet connection.
9114 A user account compromise is even more common than a DoS attack. Many
9115 sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on
9116 their machines. These servers, by default, do not operate over encrypted
9117 connections. The result is that if you have any moderate-sized user base,
9118 one or more of your users logging into your system from a remote location
9119 (which is the most common and convenient way to login to a system) will
9120 have his or her password sniffed. The attentive system admin will analyze
9121 his remote access logs looking for suspicious source addresses even for
9124 One must always assume that once an attacker has access to a user account,
9125 the attacker can break root. However, the reality is that in a well
9126 secured and maintained system, access to a user account does not
9127 necessarily give the attacker access to root. The distinction is important
9128 because without access to root the attacker cannot generally hide his
9129 tracks and may, at best, be able to do nothing more than mess with the
9130 user's files, or crash the machine. User account compromises are very
9131 common because users tend not to take the precautions that sysadmins take.
9133 System administrators must keep in mind that there are potentially many
9134 ways to break root on a machine. The attacker may know the root password,
9135 the attacker may find a bug in a root-run server and be able to break root
9136 over a network connection to that server, or the attacker may know of a
9137 bug in a suid-root program that allows the attacker to break root once he
9138 has broken into a user's account. If an attacker has found a way to break
9139 root on a machine, the attacker may not have a need to install a backdoor.
9140 Many of the root holes found and closed to date involve a considerable
9141 amount of work by the attacker to cleanup after himself, so most attackers
9142 install backdoors. A backdoor provides the attacker with a way to easily
9143 regain root access to the system, but it also gives the smart system
9144 administrator a convenient way to detect the intrusion. Making it
9145 impossible for an attacker to install a backdoor may actually be
9146 detrimental to your security, because it will not close off the hole the
9147 attacker found to break in the first place.
9149 Security remedies should always be implemented with a multi-layered
9150 ``onion peel'' approach and can be categorized as follows:
9152 1. Securing root and staff accounts.
9154 2. Securing root -- root-run servers and suid/sgid binaries.
9156 3. Securing user accounts.
9158 4. Securing the password file.
9160 5. Securing the kernel core, raw devices, and filesystems.
9162 6. Quick detection of inappropriate changes made to the system.
9166 The next section of this chapter will cover the above bullet items in
9169 ----------------------------------------------------------------------
9171 10.3 Securing DragonFly
9173 Command vs. Protocol: Throughout this document, we will use bold text to
9174 refer to a command or application. This is used for instances such as
9175 ssh, since it is a protocol as well as command.
9177 The sections that follow will cover the methods of securing your DragonFly
9178 system that were mentioned in the last section of this chapter.
9180 ----------------------------------------------------------------------
9182 10.3.1 Securing the root Account and Staff Accounts
9184 First off, do not bother securing staff accounts if you have not secured
9185 the root account. Most systems have a password assigned to the root
9186 account. The first thing you do is assume that the password is always
9187 compromised. This does not mean that you should remove the password. The
9188 password is almost always necessary for console access to the machine.
9189 What it does mean is that you should not make it possible to use the
9190 password outside of the console or possibly even with the su(1) command.
9191 For example, make sure that your pty's are specified as being insecure in
9192 the /etc/ttys file so that direct root logins via telnet or rlogin are
9193 disallowed. If using other login services such as sshd, make sure that
9194 direct root logins are disabled there as well. You can do this by editing
9195 your /etc/ssh/sshd_config file, and making sure that PermitRootLogin is
9196 set to NO. Consider every access method -- services such as FTP often fall
9197 through the cracks. Direct root logins should only be allowed via the
9200 Of course, as a sysadmin you have to be able to get to root, so we open up
9201 a few holes. But we make sure these holes require additional password
9202 verification to operate. One way to make root accessible is to add
9203 appropriate staff accounts to the wheel group (in /etc/group). The staff
9204 members placed in the wheel group are allowed to su to root. You should
9205 never give staff members native wheel access by putting them in the wheel
9206 group in their password entry. Staff accounts should be placed in a staff
9207 group, and then added to the wheel group via the /etc/group file. Only
9208 those staff members who actually need to have root access should be placed
9209 in the wheel group. It is also possible, when using an authentication
9210 method such as Kerberos, to use Kerberos' .k5login file in the root
9211 account to allow a ksu(1) to root without having to place anyone at all in
9212 the wheel group. This may be the better solution since the wheel mechanism
9213 still allows an intruder to break root if the intruder has gotten hold of
9214 your password file and can break into a staff account. While having the
9215 wheel mechanism is better than having nothing at all, it is not
9216 necessarily the safest option.
9218 An indirect way to secure staff accounts, and ultimately root access is to
9219 use an alternative login access method and do what is known as
9220 ``starring'' out the encrypted password for the staff accounts. Using the
9221 vipw(8) command, one can replace each instance of an encrypted password
9222 with a single ``*'' character. This command will update the
9223 /etc/master.passwd file and user/password database to disable
9224 password-authenticated logins.
9226 A staff account entry such as:
9228 foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
9230 Should be changed to this:
9232 foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
9234 This change will prevent normal logins from occurring, since the encrypted
9235 password will never match ``*''. With this done, staff members must use
9236 another mechanism to authenticate themselves such as kerberos(1) or ssh(1)
9237 using a public/private key pair. When using something like Kerberos, one
9238 generally must secure the machines which run the Kerberos servers and your
9239 desktop workstation. When using a public/private key pair with ssh, one
9240 must generally secure the machine used to login from (typically one's
9241 workstation). An additional layer of protection can be added to the key
9242 pair by password protecting the key pair when creating it with
9243 ssh-keygen(1). Being able to ``star'' out the passwords for staff accounts
9244 also guarantees that staff members can only login through secure access
9245 methods that you have set up. This forces all staff members to use secure,
9246 encrypted connections for all of their sessions, which closes an important
9247 hole used by many intruders: sniffing the network from an unrelated, less
9250 The more indirect security mechanisms also assume that you are logging in
9251 from a more restrictive server to a less restrictive server. For example,
9252 if your main box is running all sorts of servers, your workstation should
9253 not be running any. In order for your workstation to be reasonably secure
9254 you should run as few servers as possible, up to and including no servers
9255 at all, and you should run a password-protected screen blanker. Of course,
9256 given physical access to a workstation an attacker can break any sort of
9257 security you put on it. This is definitely a problem that you should
9258 consider, but you should also consider the fact that the vast majority of
9259 break-ins occur remotely, over a network, from people who do not have
9260 physical access to your workstation or servers.
9262 Using something like Kerberos also gives you the ability to disable or
9263 change the password for a staff account in one place, and have it
9264 immediately affect all the machines on which the staff member may have an
9265 account. If a staff member's account gets compromised, the ability to
9266 instantly change his password on all machines should not be underrated.
9267 With discrete passwords, changing a password on N machines can be a mess.
9268 You can also impose re-passwording restrictions with Kerberos: not only
9269 can a Kerberos ticket be made to timeout after a while, but the Kerberos
9270 system can require that the user choose a new password after a certain
9271 period of time (say, once a month).
9273 ----------------------------------------------------------------------
9275 10.3.2 Securing Root-run Servers and SUID/SGID Binaries
9277 The prudent sysadmin only runs the servers he needs to, no more, no less.
9278 Be aware that third party servers are often the most bug-prone. For
9279 example, running an old version of imapd or popper is like giving a
9280 universal root ticket out to the entire world. Never run a server that you
9281 have not checked out carefully. Many servers do not need to be run as
9282 root. For example, the ntalk, comsat, and finger daemons can be run in
9283 special user sandboxes. A sandbox is not perfect, unless you go through a
9284 large amount of trouble, but the onion approach to security still stands:
9285 If someone is able to break in through a server running in a sandbox, they
9286 still have to break out of the sandbox. The more layers the attacker must
9287 break through, the lower the likelihood of his success. Root holes have
9288 historically been found in virtually every server ever run as root,
9289 including basic system servers. If you are running a machine through which
9290 people only login via sshd and never login via telnetd or rshd or rlogind,
9291 then turn off those services!
9293 DragonFly now defaults to running ntalkd, comsat, and finger in a sandbox.
9294 Another program which may be a candidate for running in a sandbox is
9295 named(8). /etc/defaults/rc.conf includes the arguments necessary to run
9296 named in a sandbox in a commented-out form. Depending on whether you are
9297 installing a new system or upgrading an existing system, the special user
9298 accounts used by these sandboxes may not be installed. The prudent
9299 sysadmin would research and implement sandboxes for servers whenever
9302 There are a number of other servers that typically do not run in
9303 sandboxes: sendmail, popper, imapd, ftpd, and others. There are
9304 alternatives to some of these, but installing them may require more work
9305 than you are willing to perform (the convenience factor strikes again).
9306 You may have to run these servers as root and rely on other mechanisms to
9307 detect break-ins that might occur through them.
9309 The other big potential root holes in a system are the suid-root and sgid
9310 binaries installed on the system. Most of these binaries, such as rlogin,
9311 reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe,
9312 the system-default suid and sgid binaries can be considered reasonably
9313 safe. Still, root holes are occasionally found in these binaries. A root
9314 hole was found in Xlib in 1998 that made xterm (which is typically suid)
9315 vulnerable. It is better to be safe than sorry and the prudent sysadmin
9316 will restrict suid binaries, that only staff should run, to a special
9317 group that only staff can access, and get rid of (chmod 000) any suid
9318 binaries that nobody uses. A server with no display generally does not
9319 need an xterm binary. Sgid binaries can be almost as dangerous. If an
9320 intruder can break an sgid-kmem binary, the intruder might be able to read
9321 /dev/kmem and thus read the encrypted password file, potentially
9322 compromising any passworded account. Alternatively an intruder who breaks
9323 group kmem can monitor keystrokes sent through pty's, including pty's used
9324 by users who login through secure methods. An intruder that breaks the tty
9325 group can write to almost any user's tty. If a user is running a terminal
9326 program or emulator with a keyboard-simulation feature, the intruder can
9327 potentially generate a data stream that causes the user's terminal to echo
9328 a command, which is then run as that user.
9330 ----------------------------------------------------------------------
9332 10.3.3 Securing User Accounts
9334 User accounts are usually the most difficult to secure. While you can
9335 impose Draconian access restrictions on your staff and ``star'' out their
9336 passwords, you may not be able to do so with any general user accounts you
9337 might have. If you do have sufficient control, then you may win out and be
9338 able to secure the user accounts properly. If not, you simply have to be
9339 more vigilant in your monitoring of those accounts. Use of ssh and
9340 Kerberos for user accounts is more problematic, due to the extra
9341 administration and technical support required, but still a very good
9342 solution compared to a crypted password file.
9344 ----------------------------------------------------------------------
9346 10.3.4 Securing the Password File
9348 The only sure fire way is to * out as many passwords as you can and use
9349 ssh or Kerberos for access to those accounts. Even though the encrypted
9350 password file (/etc/spwd.db) can only be read by root, it may be possible
9351 for an intruder to obtain read access to that file even if the attacker
9352 cannot obtain root-write access.
9354 Your security scripts should always check for and report changes to the
9355 password file (see the Checking file integrity section below).
9357 ----------------------------------------------------------------------
9359 10.3.5 Securing the Kernel Core, Raw Devices, and Filesystems
9361 If an attacker breaks root he can do just about anything, but there are
9362 certain conveniences. For example, most modern kernels have a packet
9363 sniffing device driver built in. Under DragonFly it is called the bpf
9364 device. An intruder will commonly attempt to run a packet sniffer on a
9365 compromised machine. You do not need to give the intruder the capability
9366 and most systems do not have the need for the bpf device compiled in.
9368 But even if you turn off the bpf device, you still have /dev/mem and
9369 /dev/kmem to worry about. For that matter, the intruder can still write to
9370 raw disk devices. Also, there is another kernel feature called the module
9371 loader, kldload(8). An enterprising intruder can use a KLD module to
9372 install his own bpf device, or other sniffing device, on a running kernel.
9373 To avoid these problems you have to run the kernel at a higher secure
9374 level, at least securelevel 1. The securelevel can be set with a sysctl on
9375 the kern.securelevel variable. Once you have set the securelevel to 1,
9376 write access to raw devices will be denied and special chflags flags, such
9377 as schg, will be enforced. You must also ensure that the schg flag is set
9378 on critical startup binaries, directories, and script files -- everything
9379 that gets run up to the point where the securelevel is set. This might be
9380 overdoing it, and upgrading the system is much more difficult when you
9381 operate at a higher secure level. You may compromise and run the system at
9382 a higher secure level but not set the schg flag for every system file and
9383 directory under the sun. Another possibility is to simply mount / and /usr
9384 read-only. It should be noted that being too Draconian in what you attempt
9385 to protect may prevent the all-important detection of an intrusion.
9387 ----------------------------------------------------------------------
9389 10.3.6 Checking File Integrity: Binaries, Configuration Files, Etc.
9391 When it comes right down to it, you can only protect your core system
9392 configuration and control files so much before the convenience factor
9393 rears its ugly head. For example, using chflags to set the schg bit on
9394 most of the files in / and /usr is probably counterproductive, because
9395 while it may protect the files, it also closes a detection window. The
9396 last layer of your security onion is perhaps the most important --
9397 detection. The rest of your security is pretty much useless (or, worse,
9398 presents you with a false sense of safety) if you cannot detect potential
9399 incursions. Half the job of the onion is to slow down the attacker, rather
9400 than stop him, in order to give the detection side of the equation a
9401 chance to catch him in the act.
9403 The best way to detect an incursion is to look for modified, missing, or
9404 unexpected files. The best way to look for modified files is from another
9405 (often centralized) limited-access system. Writing your security scripts
9406 on the extra-secure limited-access system makes them mostly invisible to
9407 potential attackers, and this is important. In order to take maximum
9408 advantage you generally have to give the limited-access box significant
9409 access to the other machines in the business, usually either by doing a
9410 read-only NFS export of the other machines to the limited-access box, or
9411 by setting up ssh key-pairs to allow the limited-access box to ssh to the
9412 other machines. Except for its network traffic, NFS is the least visible
9413 method -- allowing you to monitor the filesystems on each client box
9414 virtually undetected. If your limited-access server is connected to the
9415 client boxes through a switch, the NFS method is often the better choice.
9416 If your limited-access server is connected to the client boxes through a
9417 hub, or through several layers of routing, the NFS method may be too
9418 insecure (network-wise) and using ssh may be the better choice even with
9419 the audit-trail tracks that ssh lays.
9421 Once you give a limited-access box, at least read access to the client
9422 systems it is supposed to monitor, you must write scripts to do the actual
9423 monitoring. Given an NFS mount, you can write scripts out of simple system
9424 utilities such as find(1) and md5(1). It is best to physically md5 the
9425 client-box files at least once a day, and to test control files such as
9426 those found in /etc and /usr/local/etc even more often. When mismatches
9427 are found, relative to the base md5 information the limited-access machine
9428 knows is valid, it should scream at a sysadmin to go check it out. A good
9429 security script will also check for inappropriate suid binaries and for
9430 new or deleted files on system partitions such as / and /usr.
9432 When using ssh rather than NFS, writing the security script is much more
9433 difficult. You essentially have to scp the scripts to the client box in
9434 order to run them, making them visible, and for safety you also need to
9435 scp the binaries (such as find) that those scripts use. The ssh client on
9436 the client box may already be compromised. All in all, using ssh may be
9437 necessary when running over insecure links, but it is also a lot harder to
9440 A good security script will also check for changes to user and staff
9441 members access configuration files: .rhosts, .shosts, .ssh/authorized_keys
9442 and so forth... files that might fall outside the purview of the MD5
9445 If you have a huge amount of user disk space, it may take too long to run
9446 through every file on those partitions. In this case, setting mount flags
9447 to disallow suid binaries and devices on those partitions is a good idea.
9448 The nodev and nosuid options (see mount(8)) are what you want to look
9449 into. You should probably scan them anyway, at least once a week, since
9450 the object of this layer is to detect a break-in whether or not the
9451 break-in is effective.
9453 Process accounting (see accton(8)) is a relatively low-overhead feature of
9454 the operating system which might help as a post-break-in evaluation
9455 mechanism. It is especially useful in tracking down how an intruder has
9456 actually broken into a system, assuming the file is still intact after the
9459 Finally, security scripts should process the log files, and the logs
9460 themselves should be generated in as secure a manner as possible -- remote
9461 syslog can be very useful. An intruder tries to cover his tracks, and log
9462 files are critical to the sysadmin trying to track down the time and
9463 method of the initial break-in. One way to keep a permanent record of the
9464 log files is to run the system console to a serial port and collect the
9465 information on a continuing basis through a secure machine monitoring the
9468 ----------------------------------------------------------------------
9472 A little paranoia never hurts. As a rule, a sysadmin can add any number of
9473 security features, as long as they do not affect convenience, and can add
9474 security features that do affect convenience with some added thought. Even
9475 more importantly, a security administrator should mix it up a bit -- if
9476 you use recommendations such as those given by this document verbatim, you
9477 give away your methodologies to the prospective attacker who also has
9478 access to this document.
9480 ----------------------------------------------------------------------
9482 10.3.8 Denial of Service Attacks
9484 This section covers Denial of Service attacks. A DoS attack is typically a
9485 packet attack. While there is not much you can do about modern spoofed
9486 packet attacks that saturate your network, you can generally limit the
9487 damage by ensuring that the attacks cannot take down your servers.
9489 1. Limiting server forks.
9491 2. Limiting springboard attacks (ICMP response attacks, ping broadcast,
9494 3. Kernel Route Cache.
9496 A common DoS attack is against a forking server that attempts to cause the
9497 server to eat processes, file descriptors, and memory, until the machine
9498 dies. inetd (see inetd(8)) has several options to limit this sort of
9499 attack. It should be noted that while it is possible to prevent a machine
9500 from going down, it is not generally possible to prevent a service from
9501 being disrupted by the attack. Read the inetd manual page carefully and
9502 pay specific attention to the -c, -C, and -R options. Note that spoofed-IP
9503 attacks will circumvent the -C option to inetd, so typically a combination
9504 of options must be used. Some standalone servers have self-fork-limitation
9507 Sendmail has its -OMaxDaemonChildren option, which tends to work much
9508 better than trying to use sendmail's load limiting options due to the load
9509 lag. You should specify a MaxDaemonChildren parameter, when you start
9510 sendmail, high enough to handle your expected load, but not so high that
9511 the computer cannot handle that number of sendmails without falling on its
9512 face. It is also prudent to run sendmail in queued mode
9513 (-ODeliveryMode=queued) and to run the daemon (sendmail -bd) separate from
9514 the queue-runs (sendmail -q15m). If you still want real-time delivery you
9515 can run the queue at a much lower interval, such as -q1m, but be sure to
9516 specify a reasonable MaxDaemonChildren option for that sendmail to prevent
9519 Syslogd can be attacked directly and it is strongly recommended that you
9520 use the -s option whenever possible, and the -a option otherwise.
9522 You should also be fairly careful with connect-back services such as
9523 tcpwrapper's reverse-identd, which can be attacked directly. You generally
9524 do not want to use the reverse-ident feature of tcpwrappers for this
9527 It is a very good idea to protect internal services from external access
9528 by firewalling them off at your border routers. The idea here is to
9529 prevent saturation attacks from outside your LAN, not so much to protect
9530 internal services from network-based root compromise. Always configure an
9531 exclusive firewall, i.e., ``firewall everything except ports A, B, C, D,
9532 and M-Z''. This way you can firewall off all of your low ports except for
9533 certain specific services such as named (if you are primary for a zone),
9534 ntalkd, sendmail, and other Internet-accessible services. If you try to
9535 configure the firewall the other way -- as an inclusive or permissive
9536 firewall, there is a good chance that you will forget to ``close'' a
9537 couple of services, or that you will add a new internal service and forget
9538 to update the firewall. You can still open up the high-numbered port range
9539 on the firewall, to allow permissive-like operation, without compromising
9540 your low ports. Also take note that DragonFly allows you to control the
9541 range of port numbers used for dynamic binding, via the various
9542 net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can
9543 also ease the complexity of your firewall's configuration. For example,
9544 you might use a normal first/last range of 4000 to 5000, and a hiport
9545 range of 49152 to 65535, then block off everything under 4000 in your
9546 firewall (except for certain specific Internet-accessible ports, of
9549 Another common DoS attack is called a springboard attack -- to attack a
9550 server in a manner that causes the server to generate responses which
9551 overloads the server, the local network, or some other machine. The most
9552 common attack of this nature is the ICMP ping broadcast attack. The
9553 attacker spoofs ping packets sent to your LAN's broadcast address with the
9554 source IP address set to the actual machine they wish to attack. If your
9555 border routers are not configured to stomp on ping's to broadcast
9556 addresses, your LAN winds up generating sufficient responses to the
9557 spoofed source address to saturate the victim, especially when the
9558 attacker uses the same trick on several dozen broadcast addresses over
9559 several dozen different networks at once. Broadcast attacks of over a
9560 hundred and twenty megabits have been measured. A second common
9561 springboard attack is against the ICMP error reporting system. By
9562 constructing packets that generate ICMP error responses, an attacker can
9563 saturate a server's incoming network and cause the server to saturate its
9564 outgoing network with ICMP responses. This type of attack can also crash
9565 the server by running it out of mbuf's, especially if the server cannot
9566 drain the ICMP responses it generates fast enough. The DragonFly kernel
9567 has a new kernel compile option called ICMP_BANDLIM which limits the
9568 effectiveness of these sorts of attacks. The last major class of
9569 springboard attacks is related to certain internal inetd services such as
9570 the udp echo service. An attacker simply spoofs a UDP packet with the
9571 source address being server A's echo port, and the destination address
9572 being server B's echo port, where server A and B are both on your LAN. The
9573 two servers then bounce this one packet back and forth between each other.
9574 The attacker can overload both servers and their LANs simply by injecting
9575 a few packets in this manner. Similar problems exist with the internal
9576 chargen port. A competent sysadmin will turn off all of these
9577 inetd-internal test services.
9579 Spoofed packet attacks may also be used to overload the kernel route
9580 cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache
9581 sysctl parameters. A spoofed packet attack that uses a random source IP
9582 will cause the kernel to generate a temporary cached route in the route
9583 table, viewable with netstat -rna | fgrep W3. These routes typically
9584 timeout in 1600 seconds or so. If the kernel detects that the cached route
9585 table has gotten too big it will dynamically reduce the rtexpire but will
9586 never decrease it to less than rtminexpire. There are two problems:
9588 1. The kernel does not react quickly enough when a lightly loaded server
9589 is suddenly attacked.
9591 2. The rtminexpire is not low enough for the kernel to survive a
9594 If your servers are connected to the Internet via a T3 or better, it may
9595 be prudent to manually override both rtexpire and rtminexpire via
9596 sysctl(8). Never set either parameter to zero (unless you want to crash
9597 the machine). Setting both parameters to two seconds should be sufficient
9598 to protect the route table from attack.
9600 ----------------------------------------------------------------------
9602 10.3.9 Access Issues with Kerberos and SSH
9604 There are a few issues with both Kerberos and ssh that need to be
9605 addressed if you intend to use them. Kerberos V is an excellent
9606 authentication protocol, but there are bugs in the kerberized telnet and
9607 rlogin applications that make them unsuitable for dealing with binary
9608 streams. Also, by default Kerberos does not encrypt a session unless you
9609 use the -x option. ssh encrypts everything by default.
9611 ssh works quite well in every respect except that it forwards encryption
9612 keys by default. What this means is that if you have a secure workstation
9613 holding keys that give you access to the rest of the system, and you ssh
9614 to an insecure machine, your keys are usable. The actual keys themselves
9615 are not exposed, but ssh installs a forwarding port for the duration of
9616 your login, and if an attacker has broken root on the insecure machine he
9617 can utilize that port to use your keys to gain access to any other machine
9618 that your keys unlock.
9620 We recommend that you use ssh in combination with Kerberos whenever
9621 possible for staff logins. ssh can be compiled with Kerberos support. This
9622 reduces your reliance on potentially exposable ssh keys while at the same
9623 time protecting passwords via Kerberos. ssh keys should only be used for
9624 automated tasks from secure machines (something that Kerberos is unsuited
9625 to do). We also recommend that you either turn off key-forwarding in the
9626 ssh configuration, or that you make use of the from=IP/DOMAIN option that
9627 ssh allows in its authorized_keys file to make the key only usable to
9628 entities logging in from specific machines.
9630 ----------------------------------------------------------------------
9632 10.4 DES, MD5, and Crypt
9634 Parts rewritten and updated by Bill Swingle.
9636 Every user on a UNIX system has a password associated with their account.
9637 It seems obvious that these passwords need to be known only to the user
9638 and the actual operating system. In order to keep these passwords secret,
9639 they are encrypted with what is known as a ``one-way hash'', that is, they
9640 can only be easily encrypted but not decrypted. In other words, what we
9641 told you a moment ago was obvious is not even true: the operating system
9642 itself does not really know the password. It only knows the encrypted form
9643 of the password. The only way to get the ``plain-text'' password is by a
9644 brute force search of the space of possible passwords.
9646 Unfortunately the only secure way to encrypt passwords when UNIX came into
9647 being was based on DES, the Data Encryption Standard. This was not such a
9648 problem for users resident in the US, but since the source code for DES
9649 could not be exported outside the US, DragonFly had to find a way to both
9650 comply with US law and retain compatibility with all the other UNIX
9651 variants that still used DES.
9653 The solution was to divide up the encryption libraries so that US users
9654 could install the DES libraries and use DES but international users still
9655 had an encryption method that could be exported abroad. This is how
9656 DragonFly came to use MD5 as its default encryption method. MD5 is
9657 believed to be more secure than DES, so installing DES is offered
9658 primarily for compatibility reasons.
9660 ----------------------------------------------------------------------
9662 10.4.1 Recognizing Your Crypt Mechanism
9664 libcrypt.a provides a configurable password authentication hash library.
9665 Currently the library supports DES, MD5 and Blowfish hash functions. By
9666 default DragonFly uses MD5 to encrypt passwords.
9668 It is pretty easy to identify which encryption method DragonFly is set up
9669 to use. Examining the encrypted passwords in the /etc/master.passwd file
9670 is one way. Passwords encrypted with the MD5 hash are longer than those
9671 encrypted with the DES hash and also begin with the characters $1$.
9672 Passwords starting with $2a$ are encrypted with the Blowfish hash
9673 function. DES password strings do not have any particular identifying
9674 characteristics, but they are shorter than MD5 passwords, and are coded in
9675 a 64-character alphabet which does not include the $ character, so a
9676 relatively short string which does not begin with a dollar sign is very
9677 likely a DES password.
9679 The password format used for new passwords is controlled by the
9680 passwd_format login capability in /etc/login.conf, which takes values of
9681 des, md5 or blf. See the login.conf(5) manual page for more information
9682 about login capabilities.
9684 ----------------------------------------------------------------------
9686 10.5 One-time Passwords
9688 S/Key is a one-time password scheme based on a one-way hash function.
9689 DragonFly uses the MD4 hash for compatibility but other systems have used
9690 MD5 and DES-MAC. S/Key ia part of the FreeBSD base system, and is also
9691 used on a growing number of other operating systems. S/Key is a registered
9692 trademark of Bell Communications Research, Inc.
9694 There are three different sorts of passwords which we will discuss below.
9695 The first is your usual UNIX style or Kerberos password; we will call this
9696 a ``UNIX password''. The second sort is the one-time password which is
9697 generated by the S/Key key program or the OPIE opiekey(1) program and
9698 accepted by the keyinit or opiepasswd(1) programs and the login prompt; we
9699 will call this a ``one-time password''. The final sort of password is the
9700 secret password which you give to the key/opiekey programs (and sometimes
9701 the keyinit/opiepasswd programs) which it uses to generate one-time
9702 passwords; we will call it a ``secret password'' or just unqualified
9705 The secret password does not have anything to do with your UNIX password;
9706 they can be the same but this is not recommended. S/Key and OPIE secret
9707 passwords are not limited to eight characters like old UNIX passwords[10],
9708 they can be as long as you like. Passwords of six or seven word long
9709 phrases are fairly common. For the most part, the S/Key or OPIE system
9710 operates completely independently of the UNIX password system.
9712 Besides the password, there are two other pieces of data that are
9713 important to S/Key and OPIE. One is what is known as the ``seed'' or
9714 ``key'', consisting of two letters and five digits. The other is what is
9715 called the ``iteration count'', a number between 1 and 100. S/Key creates
9716 the one-time password by concatenating the seed and the secret password,
9717 then applying the MD4/MD5 hash as many times as specified by the iteration
9718 count and turning the result into six short English words. These six
9719 English words are your one-time password. The authentication system
9720 (primarily PAM) keeps track of the last one-time password used, and the
9721 user is authenticated if the hash of the user-provided password is equal
9722 to the previous password. Because a one-way hash is used it is impossible
9723 to generate future one-time passwords if a successfully used password is
9724 captured; the iteration count is decremented after each successful login
9725 to keep the user and the login program in sync. When the iteration count
9726 gets down to 1, S/Key and OPIE must be reinitialized.
9728 There are three programs involved in each system which we will discuss
9729 below. The key and opiekey programs accept an iteration count, a seed, and
9730 a secret password, and generate a one-time password or a consecutive list
9731 of one-time passwords. The keyinit and opiepasswd programs are used to
9732 initialize S/Key and OPIE respectively, and to change passwords, iteration
9733 counts, or seeds; they take either a secret passphrase, or an iteration
9734 count, seed, and one-time password. The keyinfo and opieinfo programs
9735 examine the relevant credentials files (/etc/skeykeys or /etc/opiekeys)
9736 and print out the invoking user's current iteration count and seed.
9738 There are four different sorts of operations we will cover. The first is
9739 using keyinit or opiepasswd over a secure connection to set up
9740 one-time-passwords for the first time, or to change your password or seed.
9741 The second operation is using keyinit or opiepasswd over an insecure
9742 connection, in conjunction with key or opiekey over a secure connection,
9743 to do the same. The third is using key/opiekey to log in over an insecure
9744 connection. The fourth is using key or opiekey to generate a number of
9745 keys which can be written down or printed out to carry with you when going
9746 to some location without secure connections to anywhere.
9748 ----------------------------------------------------------------------
9750 10.5.1 Secure Connection Initialization
9752 To initialize S/Key for the first time, change your password, or change
9753 your seed while logged in over a secure connection (e.g., on the console
9754 of a machine or via ssh), use the keyinit command without any parameters
9755 while logged in as yourself:
9759 Reminder - Only use this method if you are directly connected.
9760 If you are using telnet or rlogin exit with no password and use keyinit -s.
9761 Enter secret password:
9762 Again secret password:
9764 ID unfurl s/key is 99 to17757
9765 DEFY CLUB PRO NASH LACE SOFT
9767 For OPIE, opiepasswd is used instead:
9770 [grimreaper] ~ $ opiepasswd -f -c
9772 Only use this method from the console; NEVER from remote. If you are using
9773 telnet, xterm, or a dial-in, type ^C now or exit with no password.
9774 Then run opiepasswd without the -c parameter.
9775 Using MD5 to compute responses.
9776 Enter new secret pass phrase:
9777 Again new secret pass phrase:
9778 ID unfurl OTP key is 499 to4268
9779 MOS MALL GOAT ARM AVID COED
9781 At the Enter new secret pass phrase: or Enter secret password: prompts,
9782 you should enter a password or phrase. Remember, this is not the password
9783 that you will use to login with, this is used to generate your one-time
9784 login keys. The ``ID'' line gives the parameters of your particular
9785 instance: your login name, the iteration count, and seed. When logging in
9786 the system will remember these parameters and present them back to you so
9787 you do not have to remember them. The last line gives the particular
9788 one-time password which corresponds to those parameters and your secret
9789 password; if you were to re-login immediately, this one-time password is
9790 the one you would use.
9792 ----------------------------------------------------------------------
9794 10.5.2 Insecure Connection Initialization
9796 To initialize or change your secret password over an insecure connection,
9797 you will need to already have a secure connection to some place where you
9798 can run key or opiekey; this might be in the form of a desk accessory on a
9799 Macintosh, or a shell prompt on a machine you trust. You will also need to
9800 make up an iteration count (100 is probably a good value), and you may
9801 make up your own seed or use a randomly-generated one. Over on the
9802 insecure connection (to the machine you are initializing), use the keyinit
9808 Reminder you need the 6 English words from the key command.
9809 Enter sequence count from 1 to 9999: 100
9810 Enter new key [default to17759]:
9812 s/key access password:
9813 s/key access password:CURE MIKE BANE HIM RACY GORE
9815 For OPIE, you need to use opiepasswd:
9820 You need the response from an OTP generator.
9821 Old secret pass phrase:
9822 otp-md5 498 to4268 ext
9823 Response: GAME GAG WELT OUT DOWN CHAT
9824 New secret pass phrase:
9826 Response: LINE PAP MILK NELL BUOY TROY
9828 ID mark OTP key is 499 gr4269
9829 LINE PAP MILK NELL BUOY TROY
9831 To accept the default seed (which the keyinit program confusingly calls a
9832 key), press Return. Then before entering an access password, move over to
9833 your secure connection or S/Key desk accessory, and give it the same
9837 Reminder - Do not use this program while logged in via telnet or rlogin.
9838 Enter secret password: <secret password>
9839 CURE MIKE BANE HIM RACY GORE
9843 % opiekey 498 to4268
9844 Using the MD5 algorithm to compute response.
9845 Reminder: Don't use opiekey from telnet or dial-in sessions.
9846 Enter secret pass phrase:
9847 GAME GAG WELT OUT DOWN CHAT
9849 Now switch back over to the insecure connection, and copy the one-time
9850 password generated over to the relevant program.
9852 ----------------------------------------------------------------------
9854 10.5.3 Generating a Single One-time Password
9856 Once you have initialized S/Key, when you login you will be presented with
9859 % telnet example.com
9861 Connected to example.com
9862 Escape character is '^]'.
9864 DragonFly/i386 (example.com) (ttypa)
9872 % telnet example.com
9874 Connected to example.com
9875 Escape character is '^]'.
9877 DragonFly/i386 (example.com) (ttypa)
9880 otp-md5 498 gr4269 ext
9883 As a side note, the S/Key and OPIE prompts have a useful feature (not
9884 shown here): if you press Return at the password prompt, the prompter will
9885 turn echo on, so you can see what you are typing. This can be extremely
9886 useful if you are attempting to type in a password by hand, such as from a
9889 At this point you need to generate your one-time password to answer this
9890 login prompt. This must be done on a trusted system that you can run key
9891 or opiekey on. (There are versions of these for DOS, Windows and Mac OS as
9892 well.) They need both the iteration count and the seed as command line
9893 options. You can cut-and-paste these right from the login prompt on the
9894 machine that you are logging in to.
9896 On the trusted system:
9899 Reminder - Do not use this program while logged in via telnet or rlogin.
9900 Enter secret password:
9901 WELD LIP ACTS ENDS ME HAAG
9905 % opiekey 498 to4268
9906 Using the MD5 algorithm to compute response.
9907 Reminder: Don't use opiekey from telnet or dial-in sessions.
9908 Enter secret pass phrase:
9909 GAME GAG WELT OUT DOWN CHAT
9911 Now that you have your one-time password you can continue logging in:
9915 Password: <return to enable echo>
9917 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
9918 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ...
9920 ----------------------------------------------------------------------
9922 10.5.4 Generating Multiple One-time Passwords
9924 Sometimes you have to go places where you do not have access to a trusted
9925 machine or secure connection. In this case, it is possible to use the key
9926 and opiekey commands to generate a number of one-time passwords beforehand
9927 to be printed out and taken with you. For example:
9929 % key -n 5 30 zz99999
9930 Reminder - Do not use this program while logged in via telnet or rlogin.
9931 Enter secret password: <secret password>
9932 26: SODA RUDE LEA LIND BUDD SILT
9933 27: JILT SPY DUTY GLOW COWL ROT
9934 28: THEM OW COLA RUNT BONG SCOT
9935 29: COT MASH BARR BRIM NAN FLAG
9936 30: CAN KNEE CAST NAME FOLK BILK
9940 % opiekey -n 5 30 zz99999
9941 Using the MD5 algorithm to compute response.
9942 Reminder: Don't use opiekey from telnet or dial-in sessions.
9943 Enter secret pass phrase: <secret password>
9944 26: JOAN BORE FOSS DES NAY QUIT
9945 27: LATE BIAS SLAY FOLK MUCH TRIG
9946 28: SALT TIN ANTI LOON NEAL USE
9947 29: RIO ODIN GO BYE FURY TIC
9948 30: GREW JIVE SAN GIRD BOIL PHI
9950 The -n 5 requests five keys in sequence, the 30 specifies what the last
9951 iteration number should be. Note that these are printed out in reverse
9952 order of eventual use. If you are really paranoid, you might want to write
9953 the results down by hand; otherwise you can cut-and-paste into lpr. Note
9954 that each line shows both the iteration count and the one-time password;
9955 you may still find it handy to scratch off passwords as you use them.
9957 ----------------------------------------------------------------------
9959 10.5.5 Restricting Use of UNIX(R) Passwords
9961 S/Key can place restrictions on the use of UNIX passwords based on the
9962 host name, user name, terminal port, or IP address of a login session.
9963 These restrictions can be found in the configuration file
9964 /etc/skey.access. The skey.access(5) manual page has more information on
9965 the complete format of the file and also details some security cautions to
9966 be aware of before depending on this file for security.
9968 If there is no /etc/skey.access file (this is the default), then all users
9969 will be allowed to use UNIX passwords. If the file exists, however, then
9970 all users will be required to use S/Key unless explicitly permitted to do
9971 otherwise by configuration statements in the skey.access file. In all
9972 cases, UNIX passwords are permitted on the console.
9974 Here is a sample skey.access configuration file which illustrates the
9975 three most common sorts of configuration statements:
9977 permit internet 192.168.0.0 255.255.0.0
9981 The first line (permit internet) allows users whose IP source address
9982 (which is vulnerable to spoofing) matches the specified value and mask, to
9983 use UNIX passwords. This should not be considered a security mechanism,
9984 but rather, a means to remind authorized users that they are using an
9985 insecure network and need to use S/Key for authentication.
9987 The second line (permit user) allows the specified username, in this case
9988 fnord, to use UNIX passwords at any time. Generally speaking, this should
9989 only be used for people who are either unable to use the key program, like
9990 those with dumb terminals, or those who are uneducable.
9992 The third line (permit port) allows all users logging in on the specified
9993 terminal line to use UNIX passwords; this would be used for dial-ups.
9995 Here is a sample opieaccess file:
9997 permit 192.168.0.0 255.255.0.0
9999 This line allows users whose IP source address (which is vulnerable to
10000 spoofing) matches the specified value and mask, to use UNIX passwords at
10003 If no rules in opieaccess are matched, the default is to deny non-OPIE
10006 ----------------------------------------------------------------------
10010 Contributed by Tillman Hodgson. Based on a contribution by Mark Murray.
10012 The following information only applies to Kerberos5. Users who wish to use
10013 the KerberosIV package may install the security/krb4 port.
10015 Kerberos is a network add-on system/protocol that allows users to
10016 authenticate themselves through the services of a secure server. Services
10017 such as remote login, remote copy, secure inter-system file copying and
10018 other high-risk tasks are made considerably safer and more controllable.
10020 Kerberos can be described as an identity-verifying proxy system. It can
10021 also be described as a trusted third-party authentication system. Kerberos
10022 provides only one function -- the secure authentication of users on the
10023 network. It does not provide authorization functions (what users are
10024 allowed to do) or auditing functions (what those users did). After a
10025 client and server have used Kerberos to prove their identity, they can
10026 also encrypt all of their communications to assure privacy and data
10027 integrity as they go about their business.
10029 Therefore it is highly recommended that Kerberos be used with other
10030 security methods which provide authorization and audit services.
10032 The following instructions can be used as a guide on how to set up
10033 Kerberos as distributed for DragonFly. However, you should refer to the
10034 relevant manual pages for a complete description.
10036 For purposes of demonstrating a Kerberos installation, the various
10037 namespaces will be handled as follows:
10039 * The DNS domain (``zone'') will be example.org.
10041 * The Kerberos realm will be EXAMPLE.ORG.
10043 Note: Please use real domain names when setting up Kerberos even if you
10044 intend to run it internally. This avoids DNS problems and assures
10045 inter-operation with other Kerberos realms.
10047 ----------------------------------------------------------------------
10051 Kerberos was created by MIT as a solution to network security problems.
10052 The Kerberos protocol uses strong cryptography so that a client can prove
10053 its identity to a server (and vice versa) across an insecure network
10056 Kerberos is both the name of a network authentication protocol and an
10057 adjective to describe programs that implement the program (Kerberos
10058 telnet, for example). The current version of the protocol is version 5,
10059 described in RFC 1510.
10061 Several free implementations of this protocol are available, covering a
10062 wide range of operating systems. The Massachusetts Institute of Technology
10063 (MIT), where Kerberos was originally developed, continues to develop their
10064 Kerberos package. It is commonly used in the US as a cryptography product,
10065 as such it has historically been affected by US export regulations. The
10066 MIT Kerberos is available as a port (security/krb5). Heimdal Kerberos is
10067 another version 5 implementation, and was explicitly developed outside of
10068 the US to avoid export regulations (and is thus often included in
10069 non-commercial UNIX variants). The Heimdal Kerberos distribution is
10070 available as a port (security/heimdal), and a minimal installation of it
10071 is included in the base DragonFly install.
10073 In order to reach the widest audience, these instructions assume the use
10074 of the Heimdal distribution included in DragonFly.
10076 ----------------------------------------------------------------------
10078 10.6.2 Setting up a Heimdal KDC
10080 The Key Distribution Center (KDC) is the centralized authentication
10081 service that Kerberos provides -- it is the computer that issues Kerberos
10082 tickets. The KDC is considered ``trusted'' by all other computers in the
10083 Kerberos realm, and thus has heightened security concerns.
10085 Note that while running the Kerberos server requires very few computing
10086 resources, a dedicated machine acting only as a KDC is recommended for
10089 To begin setting up a KDC, ensure that your /etc/rc.conf file contains the
10090 correct settings to act as a KDC (you may need to adjust paths to reflect
10093 kerberos5_server_enable="YES"
10094 kadmind5_server_enable="YES"
10095 kerberos_stash="YES"
10097 Next we will set up your Kerberos config file, /etc/krb5.conf:
10100 default_realm = EXAMPLE.ORG
10103 kdc = kerberos.example.org
10106 .example.org = EXAMPLE.ORG
10108 Note that this /etc/krb5.conf file implies that your KDC will have the
10109 fully-qualified hostname of kerberos.example.org. You will need to add a
10110 CNAME (alias) entry to your zone file to accomplish this if your KDC has a
10111 different hostname.
10113 Note: For large networks with a properly configured BIND DNS server, the
10114 above example could be trimmed to:
10117 default_realm = EXAMPLE.ORG
10119 With the following lines being appended to the example.org zonefile:
10121 _kerberos._udp IN SRV 01 00 88 kerberos.example.org.
10122 _kerberos._tcp IN SRV 01 00 88 kerberos.example.org.
10123 _kpasswd._udp IN SRV 01 00 464 kerberos.example.org.
10124 _kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org.
10125 _kerberos IN TXT EXAMPLE.ORG.
10127 Next we will create the Kerberos database. This database contains the keys
10128 of all principals encrypted with a master password. You are not required
10129 to remember this password, it will be stored in a file
10130 (/var/heimdal/m-key). To create the master key, run kstash and enter a
10133 Once the master key has been created, you can initialize the database
10134 using the kadmin program with the -l option (standing for ``local''). This
10135 option instructs kadmin to modify the database files directly rather than
10136 going through the kadmind network service. This handles the
10137 chicken-and-egg problem of trying to connect to the database before it is
10138 created. Once you have the kadmin prompt, use the init command to create
10139 your realms initial database.
10141 Lastly, while still in kadmin, create your first principal using the add
10142 command. Stick to the defaults options for the principal for now, you can
10143 always change them later with the modify command. Note that you can use
10144 the ? command at any prompt to see the available options.
10146 A sample database creation session is shown below:
10149 Master key: xxxxxxxx
10150 Verifying password - Master key: xxxxxxxx
10153 kadmin> init EXAMPLE.ORG
10154 Realm max ticket life [unlimited]:
10155 kadmin> add tillman
10156 Max ticket life [unlimited]:
10157 Max renewable life [unlimited]:
10160 Verifying password - Password: xxxxxxxx
10162 Now it is time to start up the KDC services. Run /etc/rc.d/kerberos start
10163 and /etc/rc.d/kadmind start to bring up the services. Note that you won't
10164 have any kerberized daemons running at this point but you should be able
10165 to confirm the that the KDC is functioning by obtaining and listing a
10166 ticket for the principal (user) that you just created from the
10167 command-line of the KDC itself:
10170 tillman@EXAMPLE.ORG's Password:
10173 Credentials cache: FILE:/tmp/krb5cc_500
10174 Principal: tillman@EXAMPLE.ORG
10176 Issued Expires Principal
10177 Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
10179 ----------------------------------------------------------------------
10181 10.6.3 Kerberos enabling a server with Heimdal services
10183 First, we need a copy of the Kerberos configuration file, /etc/krb5.conf.
10184 To do so, simply copy it over to the client computer from the KDC in a
10185 secure fashion (using network utilities, such as scp(1), or physically via
10188 Next you need a /etc/krb5.keytab file. This is the major difference
10189 between a server providing Kerberos enabled daemons and a workstation --
10190 the server must have a keytab file. This file contains the servers host
10191 key, which allows it and the KDC to verify each others identity. It must
10192 be transmitted to the server in a secure fashion, as the security of the
10193 server can be broken if the key is made public. This explicitly means that
10194 transferring it via a clear text channel, such as FTP, is a very bad idea.
10196 Typically, you transfer to the keytab to the server using the kadmin
10197 program. This is handy because you also need to create the host principal
10198 (the KDC end of the krb5.keytab) using kadmin.
10200 Note that you must have already obtained a ticket and that this ticket
10201 must be allowed to use the kadmin interface in the kadmind.acl. See the
10202 section titled ``Remote administration'' in the Heimdal info pages (info
10203 heimdal) for details on designing access control lists. If you do not want
10204 to enable remote kadmin access, you can simply securely connect to the KDC
10205 (via local console, ssh(1) or Kerberos telnet(1)) and perform
10206 administration locally using kadmin -l.
10208 After installing the /etc/krb5.conf file, you can use kadmin from the
10209 Kerberos server. The add --random-key command will let you add the servers
10210 host principal, and the ext command will allow you to extract the servers
10211 host principal to its own keytab. For example:
10214 kadmin> add --random-key host/myserver.example.org
10215 Max ticket life [unlimited]:
10216 Max renewable life [unlimited]:
10218 kadmin> ext host/myserver.example.org
10221 Note that the ext command (short for ``extract'') stores the extracted key
10222 in /etc/krb5.keytab by default.
10224 If you do not have kadmind running on the KDC (possibly for security
10225 reasons) and thus do not have access to kadmin remotely, you can add the
10226 host principal (host/myserver.EXAMPLE.ORG) directly on the KDC and then
10227 extract it to a temporary file (to avoid over-writing the /etc/krb5.keytab
10228 on the KDC) using something like this:
10231 kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org
10234 You can then securely copy the keytab to the server computer (using scp or
10235 a floppy, for example). Be sure to specify a non-default keytab name to
10236 avoid over-writing the keytab on the KDC.
10238 At this point your server can communicate with the KDC (due to its
10239 krb5.conf file) and it can prove its own identity (due to the krb5.keytab
10240 file). It is now ready for you to enable some Kerberos services. For this
10241 example we will enable the telnet service by putting a line like this into
10242 your /etc/inetd.conf and then restarting the inetd(8) service with
10243 /etc/rc.d/inetd restart:
10245 telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user
10247 The critical bit is that the -a (for authentication) type is set to user.
10248 Consult the telnetd(8) manual page for more details.
10250 ----------------------------------------------------------------------
10252 10.6.4 Kerberos enabling a client with Heimdal
10254 Setting up a client computer is almost trivially easy. As far as Kerberos
10255 configuration goes, you only need the Kerberos configuration file, located
10256 at /etc/krb5.conf. Simply securely copy it over to the client computer
10259 Test your client computer by attempting to use kinit, klist, and kdestroy
10260 from the client to obtain, show, and then delete a ticket for the
10261 principal you created above. You should also be able to use Kerberos
10262 applications to connect to Kerberos enabled servers, though if that does
10263 not work and obtaining a ticket does the problem is likely with the server
10264 and not with the client or the KDC.
10266 When testing an application like telnet, try using a packet sniffer (such
10267 as tcpdump(1)) to confirm that your password is not sent in the clear. Try
10268 using telnet with the -x option, which encrypts the entire data stream
10271 The core Kerberos client applications (traditionally named kinit, klist,
10272 kdestroy, and kpasswd) are installed in the base DragonFly install. Note
10273 that DragonFly versions prior to 5.0 renamed them to k5init, k5list,
10274 k5destroy, k5passwd, and k5stash (though it is typically only used once).
10276 Various non-core Kerberos client applications are also installed by
10277 default. This is where the ``minimal'' nature of the base Heimdal
10278 installation is felt: telnet is the only Kerberos enabled service.
10280 The Heimdal port adds some of the missing client applications: Kerberos
10281 enabled versions of ftp, rsh, rcp, rlogin, and a few other less common
10282 programs. The MIT port also contains a full suite of Kerberos client
10285 ----------------------------------------------------------------------
10287 10.6.5 User configuration files: .k5login and .k5users
10289 Users within a realm typically have their Kerberos principal (such as
10290 tillman@EXAMPLE.ORG) mapped to a local user account (such as a local
10291 account named tillman). Client applications such as telnet usually do not
10292 require a user name or a principal.
10294 Occasionally, however, you want to grant access to a local user account to
10295 someone who does not have a matching Kerberos principal. For example,
10296 tillman@EXAMPLE.ORG may need access to the local user account
10297 webdevelopers. Other principals may also need access to that local
10300 The .k5login and .k5users files, placed in a users home directory, can be
10301 used similar to a powerful combination of .hosts and .rhosts, solving this
10302 problem. For example, if a .k5login with the following contents:
10304 tillman@example.org
10307 Were to be placed into the home directory of the local user webdevelopers
10308 then both principals listed would have access to that account without
10309 requiring a shared password.
10311 Reading the manual pages for these commands is recommended. Note that the
10312 ksu manual page covers .k5users.
10314 ----------------------------------------------------------------------
10316 10.6.6 Kerberos Tips, Tricks, and Troubleshooting
10318 * When using either the Heimdal or MIT Kerberos ports ensure that your
10319 PATH environment variable lists the Kerberos versions of the client
10320 applications before the system versions.
10322 * Is your time in sync? Are you sure? If the time is not in sync
10323 (typically within five minutes) authentication will fail.
10325 * MIT and Heimdal inter-operate nicely. Except for kadmin, the protocol
10326 for which is not standardized.
10328 * If you change your hostname, you also need to change your host/
10329 principal and update your keytab. This also applies to special keytab
10330 entries like the www/ principal used for Apache's www/mod_auth_kerb.
10332 * All hosts in your realm must be resolvable (both forwards and reverse)
10333 in DNS (or /etc/hosts as a minimum). CNAMEs will work, but the A and
10334 PTR records must be correct and in place. The error message isn't very
10335 intuitive: ``Kerberos5 refuses authentication because Read req failed:
10336 Key table entry not found''.
10338 * Some operating systems that may being acting as clients to your KDC do
10339 not set the permissions for ksu to be setuid root. This means that ksu
10340 does not work, which is a good security idea but annoying. This is not
10343 * With MIT Kerberos, if you want to allow a principal to have a ticket
10344 life longer than the default ten hours, you must use modify_principal
10345 in kadmin to change the maxlife of both the principal in question and
10346 the krbtgt principal. Then the principal can use the -l option with
10347 kinit to request a ticket with a longer lifetime.
10349 * Note: If you run a packet sniffer on your KDC to add in
10350 troubleshooting and then run kinit from a workstation, you will
10351 notice that your TGT is sent immediately upon running kinit -- even
10352 before you type your password! The explanation is that the Kerberos
10353 server freely transmits a TGT (Ticket Granting Ticket) to any
10354 unauthorized request; however, every TGT is encrypted in a key
10355 derived from the user's password. Therefore, when a user types their
10356 password it is not being sent to the KDC, it is being used to
10357 decrypt the TGT that kinit already obtained. If the decryption
10358 process results in a valid ticket with a valid time stamp, the user
10359 has valid Kerberos credentials. These credentials include a session
10360 key for establishing secure communications with the Kerberos server
10361 in the future, as well as the actual ticket-granting ticket, which
10362 is actually encrypted with the Kerberos server's own key. This
10363 second layer of encryption is unknown to the user, but it is what
10364 allows the Kerberos server to verify the authenticity of each TGT.
10366 * You have to keep the time in sync between all the computers in your
10367 realm. NTP is perfect for this. For more information on NTP, see
10370 * If you want to use long ticket lifetimes (a week, for example) and you
10371 are using OpenSSH to connect to the machine where your ticket is
10372 stored, make sure that Kerberos TicketCleanup is set to no in your
10373 sshd_config or else your tickets will be deleted when you log out.
10375 * Remember that host principals can have a longer ticket lifetime as
10376 well. If your user principal has a lifetime of a week but the host you
10377 are connecting to has a lifetime of nine hours, you will have an
10378 expired host principal in your cache and the ticket cache will not
10381 * When setting up a krb5.dict file to prevent specific bad passwords
10382 from being used (the manual page for kadmind covers this briefly),
10383 remember that it only applies to principals that have a password
10384 policy assigned to them. The krb5.dict files format is simple: one
10385 string per line. Creating a symbolic link to /usr/share/dict/words
10388 ----------------------------------------------------------------------
10390 10.6.7 Differences with the MIT port
10392 The major difference between the MIT and Heimdal installs relates to the
10393 kadmin program which has a different (but equivalent) set of commands and
10394 uses a different protocol. This has a large implications if your KDC is
10395 MIT as you will not be able to use the Heimdal kadmin program to
10396 administer your KDC remotely (or vice versa, for that matter).
10398 The client applications may also take slightly different command line
10399 options to accomplish the same tasks. Following the instructions on the
10400 MIT Kerberos web site (http://web.mit.edu/Kerberos/www/) is recommended.
10401 Be careful of path issues: the MIT port installs into /usr/local/ by
10402 default, and the ``normal'' system applications may be run instead of MIT
10403 if your PATH environment variable lists the system directories first.
10405 Note: With the MIT security/krb5 port that is provided by DragonFly, be
10406 sure to read the /usr/local/share/doc/krb5/README.FreeBSD file installed
10407 by the port if you want to understand why logins via telnetd and klogind
10408 behave somewhat oddly. Most importantly, correcting the ``incorrect
10409 permissions on cache file'' behavior requires that the login.krb5 binary
10410 be used for authentication so that it can properly change ownership for
10411 the forwarded credentials.
10413 ----------------------------------------------------------------------
10415 10.6.8 Mitigating limitations found in Kerberos
10417 ----------------------------------------------------------------------
10419 10.6.8.1 Kerberos is an all-or-nothing approach
10421 Every service enabled on the network must be modified to work with
10422 Kerberos (or be otherwise secured against network attacks) or else the
10423 users credentials could be stolen and re-used. An example of this would be
10424 Kerberos enabling all remote shells (via rsh and telnet, for example) but
10425 not converting the POP3 mail server which sends passwords in plaintext.
10427 ----------------------------------------------------------------------
10429 10.6.8.2 Kerberos is intended for single-user workstations
10431 In a multi-user environment, Kerberos is less secure. This is because it
10432 stores the tickets in the /tmp directory, which is readable by all users.
10433 If a user is sharing a computer with several other people simultaneously
10434 (i.e. multi-user), it is possible that the user's tickets can be stolen
10435 (copied) by another user.
10437 This can be overcome with the -c filename command-line option or
10438 (preferably) the KRB5CCNAME environment variable, but this is rarely done.
10439 In principal, storing the ticket in the users home directory and using
10440 simple file permissions can mitigate this problem.
10442 ----------------------------------------------------------------------
10444 10.6.8.3 The KDC is a single point of failure
10446 By design, the KDC must be as secure as the master password database is
10447 contained on it. The KDC should have absolutely no other services running
10448 on it and should be physically secured. The danger is high because
10449 Kerberos stores all passwords encrypted with the same key (the ``master''
10450 key), which in turn is stored as a file on the KDC.
10452 As a side note, a compromised master key is not quite as bad as one might
10453 normally fear. The master key is only used to encrypt the Kerberos
10454 database and as a seed for the random number generator. As long as access
10455 to your KDC is secure, an attacker cannot do much with the master key.
10457 Additionally, if the KDC is unavailable (perhaps due to a denial of
10458 service attack or network problems) the network services are unusable as
10459 authentication can not be performed, a recipe for a denial-of-service
10460 attack. This can alleviated with multiple KDCs (a single master and one or
10461 more slaves) and with careful implementation of secondary or fall-back
10462 authentication (PAM is excellent for this).
10464 ----------------------------------------------------------------------
10466 10.6.8.4 Kerberos Shortcomings
10468 Kerberos allows users, hosts and services to authenticate between
10469 themselves. It does not have a mechanism to authenticate the KDC to the
10470 users, hosts or services. This means that a trojanned kinit (for example)
10471 could record all user names and passwords. Something like
10472 security/tripwire or other file system integrity checking tools can
10475 ----------------------------------------------------------------------
10477 10.6.9 Resources and further information
10481 * Designing an Authentication System: a Dialogue in Four Scenes
10483 * RFC 1510, The Kerberos Network Authentication Service (V5)
10485 * MIT Kerberos home page
10487 * Heimdal Kerberos home page
10489 ----------------------------------------------------------------------
10493 Contributed by Gary Palmer and Alex Nash.
10495 Firewalls are an area of increasing interest for people who are connected
10496 to the Internet, and are even finding applications on private networks to
10497 provide enhanced security. This section will hopefully explain what
10498 firewalls are, how to use them, and how to use the facilities provided in
10499 the DragonFly kernel to implement them.
10501 Note: People often think that having a firewall between your internal
10502 network and the ``Big Bad Internet'' will solve all your security
10503 problems. It may help, but a poorly set up firewall system is more of a
10504 security risk than not having one at all. A firewall can add another
10505 layer of security to your systems, but it cannot stop a really
10506 determined cracker from penetrating your internal network. If you let
10507 internal security lapse because you believe your firewall to be
10508 impenetrable, you have just made the crackers job that much easier.
10510 ----------------------------------------------------------------------
10512 10.7.1 What Is a Firewall?
10514 There are currently two distinct types of firewalls in common use on the
10515 Internet today. The first type is more properly called a packet filtering
10516 router. This type of firewall utilizes a multi-homed machine and a set of
10517 rules to determine whether to forward or block individual packets. A
10518 multi-homed machine is simply a device with multiple network interfaces.
10519 The second type, known as a proxy server, relies on daemons to provide
10520 authentication and to forward packets, possibly on a multi-homed machine
10521 which has kernel packet forwarding disabled.
10523 Sometimes sites combine the two types of firewalls, so that only a certain
10524 machine (known as a bastion host) is allowed to send packets through a
10525 packet filtering router onto an internal network. Proxy services are run
10526 on the bastion host, which are generally more secure than normal
10527 authentication mechanisms.
10529 DragonFly comes with a kernel packet filter (known as IPFW), which is what
10530 the rest of this section will concentrate on. Proxy servers can be built
10531 on DragonFly from third party software, but there is such a variety of
10532 proxy servers available that it would be impossible to cover them in this
10535 ----------------------------------------------------------------------
10537 10.7.1.1 Packet Filtering Routers
10539 A router is a machine which forwards packets between two or more networks.
10540 A packet filtering router is programmed to compare each packet to a list
10541 of rules before deciding if it should be forwarded or not. Most modern IP
10542 routing software includes packet filtering functionality that defaults to
10543 forwarding all packets. To enable the filters, you need to define a set of
10546 To decide whether a packet should be passed on, the firewall looks through
10547 its set of rules for a rule which matches the contents of the packet's
10548 headers. Once a match is found, the rule action is obeyed. The rule action
10549 could be to drop the packet, to forward the packet, or even to send an
10550 ICMP message back to the originator. Only the first match counts, as the
10551 rules are searched in order. Hence, the list of rules can be referred to
10552 as a ``rule chain''.
10554 The packet-matching criteria varies depending on the software used, but
10555 typically you can specify rules which depend on the source IP address of
10556 the packet, the destination IP address, the source port number, the
10557 destination port number (for protocols which support ports), or even the
10558 packet type (UDP, TCP, ICMP, etc).
10560 ----------------------------------------------------------------------
10562 10.7.1.2 Proxy Servers
10564 Proxy servers are machines which have had the normal system daemons
10565 (telnetd, ftpd, etc) replaced with special servers. These servers are
10566 called proxy servers, as they normally only allow onward connections to be
10567 made. This enables you to run (for example) a proxy telnet server on your
10568 firewall host, and people can telnet in to your firewall from the outside,
10569 go through some authentication mechanism, and then gain access to the
10570 internal network (alternatively, proxy servers can be used for signals
10571 coming from the internal network and heading out).
10573 Proxy servers are normally more secure than normal servers, and often have
10574 a wider variety of authentication mechanisms available, including
10575 ``one-shot'' password systems so that even if someone manages to discover
10576 what password you used, they will not be able to use it to gain access to
10577 your systems as the password expires immediately after the first use. As
10578 they do not actually give users access to the host machine, it becomes a
10579 lot more difficult for someone to install backdoors around your security
10582 Proxy servers often have ways of restricting access further, so that only
10583 certain hosts can gain access to the servers. Most will also allow the
10584 administrator to specify which users can talk to which destination
10585 machines. Again, what facilities are available depends largely on what
10586 proxy software you choose.
10588 ----------------------------------------------------------------------
10590 10.7.2 What Does IPFW Allow Me to Do?
10592 IPFW, the software supplied with DragonFly, is a packet filtering and
10593 accounting system which resides in the kernel, and has a user-land control
10594 utility, ipfw(8). Together, they allow you to define and query the rules
10595 used by the kernel in its routing decisions.
10597 There are two related parts to IPFW. The firewall section performs packet
10598 filtering. There is also an IP accounting section which tracks usage of
10599 the router, based on rules similar to those used in the firewall section.
10600 This allows the administrator to monitor how much traffic the router is
10601 getting from a certain machine, or how much WWW traffic it is forwarding,
10604 As a result of the way that IPFW is designed, you can use IPFW on
10605 non-router machines to perform packet filtering on incoming and outgoing
10606 connections. This is a special case of the more general use of IPFW, and
10607 the same commands and techniques should be used in this situation.
10609 ----------------------------------------------------------------------
10611 10.7.3 Enabling IPFW on DragonFly
10613 As the main part of the IPFW system lives in the kernel, you will need to
10614 add one or more options to your kernel configuration file, depending on
10615 what facilities you want, and recompile your kernel. See "Reconfiguring
10616 your Kernel" (Chapter 9) for more details on how to recompile your kernel.
10618 Warning: IPFW defaults to a policy of deny ip from any to any. If you do
10619 not add other rules during startup to allow access, you will lock
10620 yourself out of the server upon rebooting into a firewall-enabled
10621 kernel. We suggest that you set firewall_type=open in your /etc/rc.conf
10622 file when first enabling this feature, then refining the firewall rules
10623 in /etc/rc.firewall after you have tested that the new kernel feature
10624 works properly. To be on the safe side, you may wish to consider
10625 performing the initial firewall configuration from the local console
10626 rather than via ssh. Another option is to build a kernel using both the
10627 IPFIREWALL and IPFIREWALL_DEFAULT_TO_ACCEPT options. This will change
10628 the default rule of IPFW to allow ip from any to any and avoid the
10629 possibility of a lockout.
10631 There are currently four kernel configuration options relevant to IPFW:
10635 Compiles into the kernel the code for packet filtering.
10637 options IPFIREWALL_VERBOSE
10639 Enables code to allow logging of packets through syslogd(8).
10640 Without this option, even if you specify that packets should be
10641 logged in the filter rules, nothing will happen.
10643 options IPFIREWALL_VERBOSE_LIMIT=10
10645 Limits the number of packets logged through syslogd(8) on a per
10646 entry basis. You may wish to use this option in hostile
10647 environments in which you want to log firewall activity, but do
10648 not want to be open to a denial of service attack via syslog
10651 When a chain entry reaches the packet limit specified, logging is
10652 turned off for that particular entry. To resume logging, you will
10653 need to reset the associated counter using the ipfw(8) utility:
10657 Where 4500 is the chain entry you wish to continue logging.
10659 options IPFIREWALL_DEFAULT_TO_ACCEPT
10661 This changes the default rule action from ``deny'' to ``allow''.
10662 This avoids the possibility of locking yourself out if you happen
10663 to boot a kernel with IPFIREWALL support but have not configured
10664 your firewall yet. It is also very useful if you often use ipfw(8)
10665 as a filter for specific problems as they arise. Use with care
10666 though, as this opens up the firewall and changes the way it
10669 ----------------------------------------------------------------------
10671 10.7.4 Configuring IPFW
10673 The configuration of the IPFW software is done through the ipfw(8)
10674 utility. The syntax for this command looks quite complicated, but it is
10675 relatively simple once you understand its structure.
10677 There are currently four different command categories used by the utility:
10678 addition/deletion, listing, flushing, and clearing. Addition/deletion is
10679 used to build the rules that control how packets are accepted, rejected,
10680 and logged. Listing is used to examine the contents of your rule set
10681 (otherwise known as the chain) and packet counters (accounting). Flushing
10682 is used to remove all entries from the chain. Clearing is used to zero out
10683 one or more accounting entries.
10685 ----------------------------------------------------------------------
10687 10.7.4.1 Altering the IPFW Rules
10689 The syntax for this form of the command is:
10691 ipfw [-N] command [index] action [log] protocol addresses [options]
10693 There is one valid flag when using this form of the command:
10697 Resolve addresses and service names in output.
10699 The command given can be shortened to the shortest unique form. The valid
10704 Add an entry to the firewall/accounting rule list
10708 Delete an entry from the firewall/accounting rule list
10710 Previous versions of IPFW used separate firewall and accounting entries.
10711 The present version provides packet accounting with each firewall entry.
10713 If an index value is supplied, it is used to place the entry at a specific
10714 point in the chain. Otherwise, the entry is placed at the end of the chain
10715 at an index 100 greater than the last chain entry (this does not include
10716 the default policy, rule 65535, deny).
10718 The log option causes matching rules to be output to the system console if
10719 the kernel was compiled with IPFIREWALL_VERBOSE.
10725 Drop the packet, and send an ICMP host or port unreachable (as
10726 appropriate) packet to the source.
10730 Pass the packet on as normal. (aliases: pass, permit, and accept)
10734 Drop the packet. The source is not notified via an ICMP message
10735 (thus it appears that the packet never arrived at the
10740 Update packet counters but do not allow/deny the packet based on
10741 this rule. The search continues with the next chain entry.
10743 Each action will be recognized by the shortest unambiguous prefix.
10745 The protocols which can be specified are:
10749 Matches any IP packet
10753 Matches ICMP packets
10757 Matches TCP packets
10761 Matches UDP packets
10763 The address specification is:
10765 from address/mask [port] to address/mask [port] [via interface]
10767 You can only specify port in conjunction with protocols which support
10768 ports (UDP and TCP).
10770 The via is optional and may specify the IP address or domain name of a
10771 local IP interface, or an interface name (e.g. ed0) to match only packets
10772 coming through this interface. Interface unit numbers can be specified
10773 with an optional wildcard. For example, ppp* would match all kernel PPP
10776 The syntax used to specify an address/mask is:
10786 address:mask-pattern
10788 A valid hostname may be specified in place of the IP address. mask-bits is
10789 a decimal number representing how many bits in the address mask should be
10790 set. e.g. specifying 192.216.222.1/24 will create a mask which will allow
10791 any address in a class C subnet (in this case, 192.216.222) to be matched.
10792 mask-pattern is an IP address which will be logically AND'ed with the
10793 address given. The keyword any may be used to specify ``any IP address''.
10795 The port numbers to be blocked are specified as:
10797 port [,port [,port [...]]]
10799 to specify either a single port or a list of ports, or
10803 to specify a range of ports. You may also combine a single range with a
10804 list, but the range must always be specified first.
10806 The options available are:
10810 Matches if the packet is not the first fragment of the datagram.
10814 Matches if the packet is on the way in.
10818 Matches if the packet is on the way out.
10822 Matches if the IP header contains the comma separated list of
10823 options specified in spec. The supported IP options are: ssrr
10824 (strict source route), lsrr (loose source route), rr (record
10825 packet route), and ts (time stamp). The absence of a particular
10826 option may be specified with a leading !.
10830 Matches if the packet is part of an already established TCP
10831 connection (i.e. it has the RST or ACK bits set). You can optimize
10832 the performance of the firewall by placing established rules early
10837 Matches if the packet is an attempt to establish a TCP connection
10838 (the SYN bit is set but the ACK bit is not).
10842 Matches if the TCP header contains the comma separated list of
10843 flags. The supported flags are fin, syn, rst, psh, ack, and urg.
10844 The absence of a particular flag may be indicated by a leading !.
10848 Matches if the ICMP type is present in the list types. The list
10849 may be specified as any combination of ranges and/or individual
10850 types separated by commas. Commonly used ICMP types are: 0 echo
10851 reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo
10852 request (ping request), and 11 time exceeded (used to indicate TTL
10853 expiration as with traceroute(8)).
10855 ----------------------------------------------------------------------
10857 10.7.4.2 Listing the IPFW Rules
10859 The syntax for this form of the command is:
10861 ipfw [-a] [-c] [-d] [-e] [-t] [-N] [-S] list
10863 There are seven valid flags when using this form of the command:
10867 While listing, show counter values. This option is the only way to
10868 see accounting counters.
10872 List rules in compact form.
10876 Show dynamic rules in addition to static rules.
10880 If -d was specified, also show expired dynamic rules.
10884 Display the last match times for each chain entry. The time
10885 listing is incompatible with the input syntax used by the ipfw(8)
10890 Attempt to resolve given addresses and service names.
10894 Show the set each rule belongs to. If this flag is not specified,
10895 disabled rules will not be listed.
10897 ----------------------------------------------------------------------
10899 10.7.4.3 Flushing the IPFW Rules
10901 The syntax for flushing the chain is:
10905 This causes all entries in the firewall chain to be removed except the
10906 fixed default policy enforced by the kernel (index 65535). Use caution
10907 when flushing rules; the default deny policy will leave your system cut
10908 off from the network until allow entries are added to the chain.
10910 ----------------------------------------------------------------------
10912 10.7.4.4 Clearing the IPFW Packet Counters
10914 The syntax for clearing one or more packet counters is:
10918 When used without an index argument, all packet counters are cleared. If
10919 an index is supplied, the clearing operation only affects a specific chain
10922 ----------------------------------------------------------------------
10924 10.7.5 Example Commands for ipfw
10926 This command will deny all packets from the host evil.crackers.org to the
10927 telnet port of the host nice.people.org:
10929 # ipfw add deny tcp from evil.crackers.org to nice.people.org 23
10931 The next example denies and logs any TCP traffic from the entire
10932 crackers.org network (a class C) to the nice.people.org machine (any
10935 # ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org
10937 If you do not want people sending X sessions to your internal network (a
10938 subnet of a class C), the following command will do the necessary
10941 # ipfw add deny tcp from any to my.org/28 6000 setup
10943 To see the accounting records:
10947 or in the short form
10951 You can also see the last time a chain entry was matched with:
10955 ----------------------------------------------------------------------
10957 10.7.6 Building a Packet Filtering Firewall
10959 Note: The following suggestions are just that: suggestions. The
10960 requirements of each firewall are different and we cannot tell you how
10961 to build a firewall to meet your particular requirements.
10963 When initially setting up your firewall, unless you have a test bench
10964 setup where you can configure your firewall host in a controlled
10965 environment, it is strongly recommend you use the logging version of the
10966 commands and enable logging in the kernel. This will allow you to quickly
10967 identify problem areas and cure them without too much disruption. Even
10968 after the initial setup phase is complete, I recommend using the logging
10969 for `deny' as it allows tracing of possible attacks and also modification
10970 of the firewall rules if your requirements alter.
10972 Note: If you use the logging versions of the accept command, be aware
10973 that it can generate large amounts of log data. One log entry will be
10974 generated for every packet that passes through the firewall, so large
10975 FTP/http transfers, etc, will really slow the system down. It also
10976 increases the latencies on those packets as it requires more work to be
10977 done by the kernel before the packet can be passed on. syslogd will also
10978 start using up a lot more processor time as it logs all the extra data
10979 to disk, and it could quite easily fill the partition /var/log is
10982 You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf.
10983 The associated manual page explains which knobs to fiddle and lists some
10984 preset firewall configurations. If you do not use a preset configuration,
10985 ipfw list will output the current ruleset into a file that you can pass to
10986 rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable
10987 your firewall, it is important to make sure your firewall is enabled
10988 before any IP interfaces are configured.
10990 The next problem is what your firewall should actually do! This is largely
10991 dependent on what access to your network you want to allow from the
10992 outside, and how much access to the outside world you want to allow from
10993 the inside. Some general rules are:
10995 * Block all incoming access to ports below 1024 for TCP. This is where
10996 most of the security sensitive services are, like finger, SMTP (mail)
10999 * Block all incoming UDP traffic. There are very few useful services
11000 that travel over UDP, and what useful traffic there is, is normally a
11001 security threat (e.g. Suns RPC and NFS protocols). This has its
11002 disadvantages also, since UDP is a connectionless protocol, denying
11003 incoming UDP traffic also blocks the replies to outgoing UDP traffic.
11004 This can cause a problem for people (on the inside) using external
11005 archie (prospero) servers. If you want to allow access to archie, you
11006 will have to allow packets coming from ports 191 and 1525 to any
11007 internal UDP port through the firewall. ntp is another service you may
11008 consider allowing through, which comes from port 123.
11010 * Block traffic to port 6000 from the outside. Port 6000 is the port
11011 used for access to X11 servers, and can be a security threat
11012 (especially if people are in the habit of doing xhost + on their
11013 workstations). X11 can actually use a range of ports starting at 6000,
11014 the upper limit being how many X displays you can run on the machine.
11015 The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063.
11017 * Check what ports any internal servers use (e.g. SQL servers, etc). It
11018 is probably a good idea to block those as well, as they normally fall
11019 outside the 1-1024 range specified above.
11021 Another checklist for firewall configuration is available from CERT at
11022 http://www.cert.org/tech_tips/packet_filtering.html
11024 As stated above, these are only guidelines. You will have to decide what
11025 filter rules you want to use on your firewall yourself. We cannot accept
11026 ANY responsibility if someone breaks into your network, even if you follow
11027 the advice given above.
11029 ----------------------------------------------------------------------
11031 10.7.7 IPFW Overhead and Optimization
11033 Many people want to know how much overhead IPFW adds to a system. The
11034 answer to this depends mostly on your rule set and processor speed. For
11035 most applications dealing with Ethernet and small rule sets, the answer is
11036 ``negligible''. For those of you that need actual measurements to satisfy
11037 your curiosity, read on.
11039 The following measurements were made using FreeBSD 2.2.5-STABLE on a
11040 486-66. (While IPFW has changed slightly in later releases of DragonFly,
11041 it still performs with similar speed.) IPFW was modified to measure the
11042 time spent within the ip_fw_chk routine, displaying the results to the
11043 console every 1000 packets.
11045 Two rule sets, each with 1000 rules, were tested. The first set was
11046 designed to demonstrate a worst case scenario by repeating the rule:
11048 # ipfw add deny tcp from any to any 55555
11050 This demonstrates a worst case scenario by causing most of IPFW's packet
11051 check routine to be executed before finally deciding that the packet does
11052 not match the rule (by virtue of the port number). Following the 999th
11053 iteration of this rule was an allow ip from any to any.
11055 The second set of rules were designed to abort the rule check quickly:
11057 # ipfw add deny ip from 1.2.3.4 to 1.2.3.4
11059 The non-matching source IP address for the above rule causes these rules
11060 to be skipped very quickly. As before, the 1000th rule was an allow ip
11063 The per-packet processing overhead in the former case was approximately
11064 2.703 ms/packet, or roughly 2.7 microseconds per rule. Thus the
11065 theoretical packet processing limit with these rules is around 370 packets
11066 per second. Assuming 10 Mbps Ethernet and a ~1500 byte packet size, we
11067 would only be able to achieve 55.5% bandwidth utilization.
11069 For the latter case each packet was processed in approximately 1.172 ms,
11070 or roughly 1.2 microseconds per rule. The theoretical packet processing
11071 limit here would be about 853 packets per second, which could consume
11072 10 Mbps Ethernet bandwidth.
11074 The excessive number of rules tested and the nature of those rules do not
11075 provide a real-world scenario -- they were used only to generate the
11076 timing information presented here. Here are a few things to keep in mind
11077 when building an efficient rule set:
11079 * Place an established rule early on to handle the majority of TCP
11080 traffic. Do not put any allow tcp statements before this rule.
11082 * Place heavily triggered rules earlier in the rule set than those
11083 rarely used (without changing the permissiveness of the firewall, of
11084 course). You can see which rules are used most often by examining the
11085 packet counting statistics with ipfw -a l.
11087 ----------------------------------------------------------------------
11091 OpenSSL provides a general-purpose cryptography library, as well as the
11092 Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1
11093 (TLSv1) network security protocols.
11095 However, one of the algorithms (specifically IDEA) included in OpenSSL is
11096 protected by patents in the USA and elsewhere, and is not available for
11097 unrestricted use. IDEA is included in the OpenSSL sources in DragonFly,
11098 but it is not built by default. If you wish to use it, and you comply with
11099 the license terms, enable the MAKE_IDEA switch in /etc/make.conf and
11100 rebuild your sources using make world.
11102 Today, the RSA algorithm is free for use in USA and other countries. In
11103 the past it was protected by a patent.
11105 ----------------------------------------------------------------------
11107 10.8.1 Source Code Installations
11109 OpenSSL is part of the src-crypto and src-secure CVSup collections. See
11110 the Obtaining DragonFly section for more information about obtaining and
11111 updating DragonFly source code.
11113 ----------------------------------------------------------------------
11115 10.9 VPN over IPsec
11117 Written by Nik Clayton.
11119 Creating a VPN between two networks, separated by the Internet, using
11120 DragonFly gateways.
11122 ----------------------------------------------------------------------
11124 10.9.1 Understanding IPsec
11126 Written by Hiten M. Pandya.
11128 This section will guide you through the process of setting up IPsec, and
11129 to use it in an environment which consists of DragonFly and
11130 Microsoft Windows 2000/XP machines, to make them communicate securely. In
11131 order to set up IPsec, it is necessary that you are familiar with the
11132 concepts of building a custom kernel (see Chapter 9).
11134 IPsec is a protocol which sits on top of the Internet Protocol (IP) layer.
11135 It allows two or more hosts to communicate in a secure manner (hence the
11136 name). The DragonFly IPsec ``network stack'' is based on the KAME
11137 implementation, which has support for both protocol families, IPv4 and
11140 IPsec consists of two sub-protocols:
11142 * Encapsulated Security Payload (ESP), protects the IP packet data from
11143 third party interference, by encrypting the contents using symmetric
11144 cryptography algorithms (like Blowfish, 3DES).
11146 * Authentication Header (AH), protects the IP packet header from third
11147 party interference and spoofing, by computing a cryptographic checksum
11148 and hashing the IP packet header fields with a secure hashing
11149 function. This is then followed by an additional header that contains
11150 the hash, to allow the information in the packet to be authenticated.
11152 ESP and AH can either be used together or separately, depending on the
11155 IPsec can either be used to directly encrypt the traffic between two hosts
11156 (known as Transport Mode); or to build ``virtual tunnels'' between two
11157 subnets, which could be used for secure communication between two
11158 corporate networks (known as Tunnel Mode). The latter is more commonly
11159 known as a Virtual Private Network (VPN). The ipsec(4) manual page should
11160 be consulted for detailed information on the IPsec subsystem in DragonFly.
11162 To add IPsec support to your kernel, add the following options to your
11163 kernel configuration file:
11165 options IPSEC #IP security
11166 options IPSEC_ESP #IP security (crypto; define w/ IPSEC)
11169 If IPsec debugging support is desired, the following kernel option should
11172 options IPSEC_DEBUG #debug for IP security
11175 ----------------------------------------------------------------------
11179 There's no standard for what constitutes a VPN. VPNs can be implemented
11180 using a number of different technologies, each of which have their own
11181 strengths and weaknesses. This article presents a number of scenarios, and
11182 strategies for implementing a VPN for each scenario.
11184 ----------------------------------------------------------------------
11186 10.9.3 Scenario #1: Two networks, connected to the Internet, to behave as one
11188 This is the scenario that caused me to first investigating VPNs. The
11189 premise is as follows:
11191 * You have at least two sites
11193 * Both sites are using IP internally
11195 * Both sites are connected to the Internet, through a gateway that is
11198 * The gateway on each network has at least one public IP address.
11200 * The internal addresses of the two networks can be public or private IP
11201 addresses, it doesn't matter. You can be running NAT on the gateway
11202 machine if necessary.
11204 * The internal IP addresses of the two networks do not collide. While I
11205 expect it is theoretically possible to use a combination of VPN
11206 technology and NAT to get this to work, I expect it to be a
11207 configuration nightmare.
11209 If you find that you are trying to connect two networks, both of which,
11210 internally, use the same private IP address range (e.g., both of them use
11211 192.168.1.x), then one of the networks will have to be renumbered.
11213 The network topology might look something like this:
11215 Network #1 [ Internal Hosts ] Private Net, 192.168.1.2-254
11220 .---[fxp1]---. Private IP, 192.168.1.1
11222 `---[fxp0]---' Public IP, A.B.C.D
11225 -=-=- Internet -=-=-
11228 .---[fxp0]---. Public IP, W.X.Y.Z
11230 `---[fxp1]---' Private IP, 192.168.2.1
11233 Network #2 [ Internal Hosts ]
11234 [ Win9x/NT/2K ] Private Net, 192.168.2.2-254
11237 Notice the two public IP addresses. I'll use the letters to refer to them
11238 in the rest of this article. Anywhere you see those letters in this
11239 article, replace them with your own public IP addresses. Note also that
11240 internally, the two gateway machines have .1 IP addresses, and that the
11241 two networks have different private IP addresses (192.168.1.x and
11242 192.168.2.x respectively). All the machines on the private networks have
11243 been configured to use the .1 machine as their default gateway.
11245 The intention is that, from a network point of view, each network should
11246 view the machines on the other network as though they were directly
11247 attached the same router -- albeit a slightly slow router with an
11248 occasional tendency to drop packets.
11250 This means that (for example), machine 192.168.1.20 should be able to run
11254 and have it work, transparently. Windows machines should be able to see
11255 the machines on the other network, browse file shares, and so on, in
11256 exactly the same way that they can browse machines on the local network.
11258 And the whole thing has to be secure. This means that traffic between the
11259 two networks has to be encrypted.
11261 Creating a VPN between these two networks is a multi-step process. The
11262 stages are as follows:
11264 1. Create a ``virtual'' network link between the two networks, across the
11265 Internet. Test it, using tools like ping(8), to make sure it works.
11267 2. Apply security policies to ensure that traffic between the two
11268 networks is transparently encrypted and decrypted as necessary. Test
11269 this, using tools like tcpdump(1), to ensure that traffic is
11272 3. Configure additional software on the DragonFly gateways, to allow
11273 Windows machines to see one another across the VPN.
11275 ----------------------------------------------------------------------
11277 10.9.3.1 Step 1: Creating and testing a ``virtual'' network link
11279 Suppose that you were logged in to the gateway machine on network #1 (with
11280 public IP address A.B.C.D, private IP address 192.168.1.1), and you ran
11281 ping 192.168.2.1, which is the private address of the machine with IP
11282 address W.X.Y.Z. What needs to happen in order for this to work?
11284 1. The gateway machine needs to know how to reach 192.168.2.1. In other
11285 words, it needs to have a route to 192.168.2.1.
11287 2. Private IP addresses, such as those in the 192.168.x range are not
11288 supposed to appear on the Internet at large. Instead, each packet you
11289 send to 192.168.2.1 will need to be wrapped up inside another packet.
11290 This packet will need to appear to be from A.B.C.D, and it will have
11291 to be sent to W.X.Y.Z. This process is called encapsulation.
11293 3. Once this packet arrives at W.X.Y.Z it will need to
11294 ``unencapsulated'', and delivered to 192.168.2.1.
11296 You can think of this as requiring a ``tunnel'' between the two networks.
11297 The two ``tunnel mouths'' are the IP addresses A.B.C.D and W.X.Y.Z, and
11298 the tunnel must be told the addresses of the private IP addresses that
11299 will be allowed to pass through it. The tunnel is used to transfer traffic
11300 with private IP addresses across the public Internet.
11302 This tunnel is created by using the generic interface, or gif devices on
11303 DragonFly. As you can imagine, the gif interface on each gateway host must
11304 be configured with four IP addresses; two for the public IP addresses, and
11305 two for the private IP addresses.
11307 Support for the gif device must be compiled in to the DragonFly kernel on
11308 both machines. You can do this by adding the line:
11312 to the kernel configuration files on both machines, and then compile,
11313 install, and reboot as normal.
11315 Configuring the tunnel is a two step process. First the tunnel must be
11316 told what the outside (or public) IP addresses are, using gifconfig(8).
11317 Then the private IP addresses must be configured using ifconfig(8).
11319 On the gateway machine on network #1 you would run the following two
11320 commands to configure the tunnel.
11322 gifconfig gif0 A.B.C.D W.X.Y.Z
11323 ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
11326 On the other gateway machine you run the same commands, but with the order
11327 of the IP addresses reversed.
11329 gifconfig gif0 W.X.Y.Z A.B.C.D
11330 ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
11337 to see the configuration. For example, on the network #1 gateway, you
11341 gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280
11342 inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff
11343 physical address inet A.B.C.D --> W.X.Y.Z
11346 As you can see, a tunnel has been created between the physical addresses
11347 A.B.C.D and W.X.Y.Z, and the traffic allowed through the tunnel is that
11348 between 192.168.1.1 and 192.168.2.1.
11350 This will also have added an entry to the routing table on both machines,
11351 which you can examine with the command netstat -rn. This output is from
11352 the gateway host on network #1.
11358 Destination Gateway Flags Refs Use Netif Expire
11360 192.168.2.1 192.168.1.1 UH 0 0 gif0
11364 As the ``Flags'' value indicates, this is a host route, which means that
11365 each gateway knows how to reach the other gateway, but they do not know
11366 how to reach the rest of their respective networks. That problem will be
11369 It is likely that you are running a firewall on both machines. This will
11370 need to be circumvented for your VPN traffic. You might want to allow all
11371 traffic between both networks, or you might want to include firewall rules
11372 that protect both ends of the VPN from one another.
11374 It greatly simplifies testing if you configure the firewall to allow all
11375 traffic through the VPN. You can always tighten things up later. If you
11376 are using ipfw(8) on the gateway machines then a command like
11378 ipfw add 1 allow ip from any to any via gif0
11380 will allow all traffic between the two end points of the VPN, without
11381 affecting your other firewall rules. Obviously you will need to run this
11382 command on both gateway hosts.
11384 This is sufficient to allow each gateway machine to ping the other. On
11385 192.168.1.1, you should be able to run
11389 and get a response, and you should be able to do the same thing on the
11390 other gateway machine.
11392 However, you will not be able to reach internal machines on either network
11393 yet. This is because of the routing -- although the gateway machines know
11394 how to reach one another, they do not know how to reach the network behind
11397 To solve this problem you must add a static route on each gateway machine.
11398 The command to do this on the first gateway would be:
11400 route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
11403 This says ``In order to reach the hosts on the network 192.168.2.0, send
11404 the packets to the host 192.168.2.1''. You will need to run a similar
11405 command on the other gateway, but with the 192.168.1.x addresses instead.
11407 IP traffic from hosts on one network will now be able to reach hosts on
11410 That has now created two thirds of a VPN between the two networks, in as
11411 much as it is ``virtual'' and it is a ``network''. It is not private yet.
11412 You can test this using ping(8) and tcpdump(1). Log in to the gateway host
11415 tcpdump dst host 192.168.2.1
11417 In another log in session on the same host run
11421 You will see output that looks something like this:
11423 16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request
11424 16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply
11425 16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request
11426 16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply
11427 16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request
11428 16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply
11431 As you can see, the ICMP messages are going back and forth unencrypted. If
11432 you had used the -s parameter to tcpdump(1) to grab more bytes of data
11433 from the packets you would see more information.
11435 Obviously this is unacceptable. The next section will discuss securing the
11436 link between the two networks so that it all traffic is automatically
11441 * Configure both kernels with ``pseudo-device gif''.
11443 * Edit /etc/rc.conf on gateway host #1 and add the following lines
11444 (replacing IP addresses as necessary).
11446 gifconfig_gif0="A.B.C.D W.X.Y.Z"
11447 ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
11448 static_routes="vpn"
11449 route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
11452 * Edit your firewall script (/etc/rc.firewall, or similar) on both
11455 ipfw add 1 allow ip from any to any via gif0
11457 * Make similar changes to /etc/rc.conf on gateway host #2, reversing the
11458 order of IP addresses.
11460 ----------------------------------------------------------------------
11462 10.9.3.2 Step 2: Securing the link
11464 To secure the link we will be using IPsec. IPsec provides a mechanism for
11465 two hosts to agree on an encryption key, and to then use this key in order
11466 to encrypt data between the two hosts.
11468 The are two areas of configuration to be considered here.
11470 1. There must be a mechanism for two hosts to agree on the encryption
11471 mechanism to use. Once two hosts have agreed on this mechanism there
11472 is said to be a ``security association'' between them.
11474 2. There must be a mechanism for specifying which traffic should be
11475 encrypted. Obviously, you don't want to encrypt all your outgoing
11476 traffic -- you only want to encrypt the traffic that is part of the
11477 VPN. The rules that you put in place to determine what traffic will be
11478 encrypted are called ``security policies''.
11480 Security associations and security policies are both maintained by the
11481 kernel, and can be modified by userland programs. However, before you can
11482 do this you must configure the kernel to support IPsec and the
11483 Encapsulated Security Payload (ESP) protocol. This is done by configuring
11490 and recompiling, reinstalling, and rebooting. As before you will need to
11491 do this to the kernels on both of the gateway hosts.
11493 You have two choices when it comes to setting up security associations.
11494 You can configure them by hand between two hosts, which entails choosing
11495 the encryption algorithm, encryption keys, and so forth, or you can use
11496 daemons that implement the Internet Key Exchange protocol (IKE) to do this
11499 I recommend the latter. Apart from anything else, it is easier to set up.
11501 Editing and displaying security policies is carried out using setkey(8).
11502 By analogy, setkey is to the kernel's security policy tables as route(8)
11503 is to the kernel's routing tables. setkey can also display the current
11504 security associations, and to continue the analogy further, is akin to
11505 netstat -r in that respect.
11507 There are a number of choices for daemons to manage security associations
11508 with DragonFly. This article will describe how to use one of these,
11509 racoon. racoon is in the FreeBSD ports collection, in the security/
11510 category, and is installed in the usual way.
11512 racoon must be run on both gateway hosts. On each host it is configured
11513 with the IP address of the other end of the VPN, and a secret key (which
11514 you choose, and must be the same on both gateways).
11516 The two daemons then contact one another, confirm that they are who they
11517 say they are (by using the secret key that you configured). The daemons
11518 then generate a new secret key, and use this to encrypt the traffic over
11519 the VPN. They periodically change this secret, so that even if an attacker
11520 were to crack one of the keys (which is as theoretically close to
11521 unfeasible as it gets) it won't do them much good -- by the time they've
11522 cracked the key the two daemons have chosen another one.
11524 racoon's configuration is stored in ${PREFIX}/etc/racoon. You should find
11525 a configuration file there, which should not need to be changed too much.
11526 The other component of racoon's configuration, which you will need to
11527 change, is the ``pre-shared key''.
11529 The default racoon configuration expects to find this in the file
11530 ${PREFIX}/etc/racoon/psk.txt. It is important to note that the pre-shared
11531 key is not the key that will be used to encrypt your traffic across the
11532 VPN link, it is simply a token that allows the key management daemons to
11535 psk.txt contains a line for each remote site you are dealing with. In this
11536 example, where there are two sites, each psk.txt file will contain one
11537 line (because each end of the VPN is only dealing with one other end).
11539 On gateway host #1 this line should look like this:
11543 That is, the public IP address of the remote end, whitespace, and a text
11544 string that provides the secret. Obviously, you shouldn't use ``secret''
11545 as your key -- the normal rules for choosing a password apply.
11547 On gateway host #2 the line would look like this
11551 That is, the public IP address of the remote end, and the same secret key.
11552 psk.txt must be mode 0600 (i.e., only read/write to root) before racoon
11555 You must run racoon on both gateway machines. You will also need to add
11556 some firewall rules to allow the IKE traffic, which is carried over UDP to
11557 the ISAKMP (Internet Security Association Key Management Protocol) port.
11558 Again, this should be fairly early in your firewall ruleset.
11560 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
11561 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
11564 Once racoon is running you can try pinging one gateway host from the
11565 other. The connection is still not encrypted, but racoon will then set up
11566 the security associations between the two hosts -- this might take a
11567 moment, and you may see this as a short delay before the ping commands
11570 Once the security association has been set up you can view it using
11575 on either host to view the security association information.
11577 That's one half of the problem. They other half is setting your security
11580 To create a sensible security policy, let's review what's been set up so
11581 far. This discussions hold for both ends of the link.
11583 Each IP packet that you send out has a header that contains data about the
11584 packet. The header includes the IP addresses of both the source and
11585 destination. As we already know, private IP addresses, such as the
11586 192.168.x.y range are not supposed to appear on the public Internet.
11587 Instead, they must first be encapsulated inside another packet. This
11588 packet must have the public source and destination IP addresses
11589 substituted for the private addresses.
11591 So if your outgoing packet started looking like this:
11593 .----------------------.
11594 | Src: 192.168.1.1 |
11595 | Dst: 192.168.2.1 |
11596 | <other header info> |
11597 +----------------------+
11599 `----------------------'
11601 Then it will be encapsulated inside another packet, looking something like
11604 .--------------------------.
11607 | <other header info> |
11608 +--------------------------+
11609 | .----------------------. |
11610 | | Src: 192.168.1.1 | |
11611 | | Dst: 192.168.2.1 | |
11612 | | <other header info> | |
11613 | +----------------------+ |
11614 | | <packet data> | |
11615 | `----------------------' |
11616 `--------------------------'
11618 This encapsulation is carried out by the gif device. As you can see, the
11619 packet now has real IP addresses on the outside, and our original packet
11620 has been wrapped up as data inside the packet that will be put out on the
11623 Obviously, we want all traffic between the VPNs to be encrypted. You might
11624 try putting this in to words, as:
11626 ``If a packet leaves from A.B.C.D, and it is destined for W.X.Y.Z, then
11627 encrypt it, using the necessary security associations.''
11629 ``If a packet arrives from W.X.Y.Z, and it is destined for A.B.C.D, then
11630 decrypt it, using the necessary security associations.''
11632 That's close, but not quite right. If you did this, all traffic to and
11633 from W.X.Y.Z, even traffic that was not part of the VPN, would be
11634 encrypted. That's not quite what you want. The correct policy is as
11637 ``If a packet leaves from A.B.C.D, and that packet is encapsulating
11638 another packet, and it is destined for W.X.Y.Z, then encrypt it, using the
11639 necessary security associations.''
11641 ``If a packet arrives from W.X.Y.Z, and that packet is encapsulating
11642 another packet, and it is destined for A.B.C.D, then encrypt it, using the
11643 necessary security associations.''
11645 A subtle change, but a necessary one.
11647 Security policies are also set using setkey(8). setkey(8) features a
11648 configuration language for defining the policy. You can either enter
11649 configuration instructions via stdin, or you can use the -f option to
11650 specify a filename that contains configuration instructions.
11652 The configuration on gateway host #1 (which has the public IP address
11653 A.B.C.D) to force all outbound traffic to W.X.Y.Z to be encrypted is:
11655 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;
11658 Put these commands in a file (e.g., /etc/ipsec.conf) and then run
11660 # setkey -f /etc/ipsec.conf
11662 spdadd tells setkey(8) that we want to add a rule to the secure policy
11663 database. The rest of this line specifies which packets will match this
11664 policy. A.B.C.D/32 and W.X.Y.Z/32 are the IP addresses and netmasks that
11665 identify the network or hosts that this policy will apply to. In this
11666 case, we want it to apply to traffic between these two hosts. ipencap
11667 tells the kernel that this policy should only apply to packets that
11668 encapsulate other packets. -P out says that this policy applies to
11669 outgoing packets, and ipsec says that the packet will be secured.
11671 The second line specifies how this packet will be encrypted. esp is the
11672 protocol that will be used, while tunnel indicates that the packet will be
11673 further encapsulated in an IPsec packet. The repeated use of A.B.C.D and
11674 W.X.Y.Z is used to select the security association to use, and the final
11675 require mandates that packets must be encrypted if they match this rule.
11677 This rule only matches outgoing packets. You will need a similar rule to
11678 match incoming packets.
11680 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;
11682 Note the in instead of out in this case, and the necessary reversal of the
11685 The other gateway host (which has the public IP address W.X.Y.Z) will need
11688 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;
11689 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;
11691 Finally, you need to add firewall rules to allow ESP and IPENCAP packets
11692 back and forth. These rules will need to be added to both hosts.
11694 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
11695 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
11696 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
11697 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
11700 Because the rules are symmetric you can use the same rules on each gateway
11703 Outgoing packets will now look something like this:
11705 .------------------------------. --------------------------.
11708 | <other header info> | | Encrypted
11709 +------------------------------+ | packet.
11710 | .--------------------------. | -------------. | contents
11711 | | Src: A.B.C.D | | | | are
11712 | | Dst: W.X.Y.Z | | | | completely
11713 | | <other header info> | | | |- secure
11714 | +--------------------------+ | | Encap'd | from third
11715 | | .----------------------. | | -. | packet | party
11716 | | | Src: 192.168.1.1 | | | | Original |- with real | snooping
11717 | | | Dst: 192.168.2.1 | | | | packet, | IP addr |
11718 | | | <other header info> | | | |- private | |
11719 | | +----------------------+ | | | IP addr | |
11720 | | | <packet data> | | | | | |
11721 | | `----------------------' | | -' | |
11722 | `--------------------------' | -------------' |
11723 `------------------------------' --------------------------'
11726 When they are received by the far end of the VPN they will first be
11727 decrypted (using the security associations that have been negotiated by
11728 racoon). Then they will enter the gif interface, which will unwrap the
11729 second layer, until you are left with the innermost packet, which can then
11730 travel in to the inner network.
11732 You can check the security using the same ping(8) test from earlier.
11733 First, log in to the A.B.C.D gateway machine, and run:
11735 tcpdump dst host 192.168.2.1
11737 In another log in session on the same host run
11741 This time you should see output like the following:
11745 Now, as you can see, tcpdump(1) shows the ESP packets. If you try to
11746 examine them with the -s option you will see (apparently) gibberish,
11747 because of the encryption.
11749 Congratulations. You have just set up a VPN between two remote sites.
11753 * Configure both kernels with:
11759 * Install security/racoon. Edit ${PREFIX}/etc/racoon/psk.txt on both
11760 gateway hosts, adding an entry for the remote host's IP address and a
11761 secret key that they both know. Make sure this file is mode 0600.
11763 * Add the following lines to /etc/rc.conf on each host:
11766 ipsec_file="/etc/ipsec.conf"
11769 * Create an /etc/ipsec.conf on each host that contains the necessary
11770 spdadd lines. On gateway host #1 this would be:
11772 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
11773 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11774 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
11775 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11777 On gateway host #2 this would be:
11779 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
11780 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
11781 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
11782 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
11784 * Add firewall rules to allow IKE, ESP, and IPENCAP traffic to both
11787 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
11788 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
11789 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
11790 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
11791 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
11792 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
11795 The previous two steps should suffice to get the VPN up and running.
11796 Machines on each network will be able to refer to one another using IP
11797 addresses, and all traffic across the link will be automatically and
11798 securely encrypted.
11800 ----------------------------------------------------------------------
11804 Contributed by Chern Lee.
11806 OpenSSH is a set of network connectivity tools used to access remote
11807 machines securely. It can be used as a direct replacement for rlogin, rsh,
11808 rcp, and telnet. Additionally, any other TCP/IP connections can be
11809 tunneled/forwarded securely through SSH. OpenSSH encrypts all traffic to
11810 effectively eliminate eavesdropping, connection hijacking, and other
11811 network-level attacks.
11813 OpenSSH is maintained by the OpenBSD project, and is based upon SSH
11814 v1.2.12 with all the recent bug fixes and updates. It is compatible with
11815 both SSH protocols 1 and 2.
11817 ----------------------------------------------------------------------
11819 10.10.1 Advantages of Using OpenSSH
11821 Normally, when using telnet(1) or rlogin(1), data is sent over the network
11822 in an clear, un-encrypted form. Network sniffers anywhere in between the
11823 client and server can steal your user/password information or data
11824 transferred in your session. OpenSSH offers a variety of authentication
11825 and encryption methods to prevent this from happening.
11827 ----------------------------------------------------------------------
11829 10.10.2 Enabling sshd
11831 Be sure to make the following addition to your rc.conf file:
11835 This will load sshd(8), the daemon program for OpenSSH, the next time your
11836 system initializes. Alternatively, you can simply run directly the sshd
11837 daemon by typing sshd on the command line.
11839 ----------------------------------------------------------------------
11843 The ssh(1) utility works similarly to rlogin(1).
11845 # ssh user@example.com
11846 Host key not found from the list of known hosts.
11847 Are you sure you want to continue connecting (yes/no)? yes
11848 Host 'example.com' added to the list of known hosts.
11849 user@example.com's password: *******
11851 The login will continue just as it would have if a session was created
11852 using rlogin or telnet. SSH utilizes a key fingerprint system for
11853 verifying the authenticity of the server when the client connects. The
11854 user is prompted to enter yes only when connecting for the first time.
11855 Future attempts to login are all verified against the saved fingerprint
11856 key. The SSH client will alert you if the saved fingerprint differs from
11857 the received fingerprint on future login attempts. The fingerprints are
11858 saved in ~/.ssh/known_hosts, or ~/.ssh/known_hosts2 for SSH v2
11861 By default, OpenSSH servers are configured to accept both SSH v1 and SSH
11862 v2 connections. The client, however, can choose between the two. Version 2
11863 is known to be more robust and secure than its predecessor.
11865 The ssh(1) command can be forced to use either protocol by passing it the
11866 -1 or -2 argument for v1 and v2, respectively.
11868 ----------------------------------------------------------------------
11870 10.10.4 Secure Copy
11872 The scp(1) command works similarly to rcp(1); it copies a file to or from
11873 a remote machine, except in a secure fashion.
11875 # scp user@example.com:/COPYRIGHT COPYRIGHT
11876 user@example.com's password: *******
11877 COPYRIGHT 100% |*****************************| 4735
11881 Since the fingerprint was already saved for this host in the previous
11882 example, it is verified when using scp(1) here.
11884 The arguments passed to scp(1) are similar to cp(1), with the file or
11885 files in the first argument, and the destination in the second. Since the
11886 file is fetched over the network, through SSH, one or more of the file
11887 arguments takes on the form user@host:<path_to_remote_file>.
11889 ----------------------------------------------------------------------
11891 10.10.5 Configuration
11893 The system-wide configuration files for both the OpenSSH daemon and client
11894 reside within the /etc/ssh directory.
11896 ssh_config configures the client settings, while sshd_config configures
11899 Additionally, the sshd_program (/usr/sbin/sshd by default), and sshd_flags
11900 rc.conf options can provide more levels of configuration.
11902 ----------------------------------------------------------------------
11906 Instead of using passwords, ssh-keygen(1) can be used to generate RSA keys
11907 to authenticate a user:
11909 % ssh-keygen -t rsa1
11910 Initializing random number generator...
11911 Generating p: .++ (distance 66)
11912 Generating q: ..............................++ (distance 498)
11913 Computing the keys...
11914 Key generation complete.
11915 Enter file in which to save the key (/home/user/.ssh/identity):
11917 Enter the same passphrase again:
11918 Your identification has been saved in /home/user/.ssh/identity.
11921 ssh-keygen(1) will create a public and private key pair for use in
11922 authentication. The private key is stored in ~/.ssh/identity, whereas the
11923 public key is stored in ~/.ssh/identity.pub. The public key must be placed
11924 in ~/.ssh/authorized_keys of the remote machine in order for the setup to
11927 This will allow connection to the remote machine based upon RSA
11928 authentication instead of passwords.
11930 Note: The -t rsa1 option will create RSA keys for use by SSH protocol
11931 version 1. If you want to use RSA keys with the SSH protocol version 2,
11932 you have to use the command ssh-keygen -t rsa.
11934 If a passphrase is used in ssh-keygen(1), the user will be prompted for a
11935 password each time in order to use the private key.
11937 A SSH protocol version 2 DSA key can be created for the same purpose by
11938 using the ssh-keygen -t dsa command. This will create a public/private DSA
11939 key for use in SSH protocol version 2 sessions only. The public key is
11940 stored in ~/.ssh/id_dsa.pub, while the private key is in ~/.ssh/id_dsa.
11942 DSA public keys are also placed in ~/.ssh/authorized_keys on the remote
11945 ssh-agent(1) and ssh-add(1) are utilities used in managing multiple
11946 passworded private keys.
11948 Warning: The various options and files can be different according to the
11949 OpenSSH version you have on your system, to avoid problems you should
11950 consult the ssh-keygen(1) manual page.
11952 ----------------------------------------------------------------------
11954 10.10.7 SSH Tunneling
11956 OpenSSH has the ability to create a tunnel to encapsulate another protocol
11957 in an encrypted session.
11959 The following command tells ssh(1) to create a tunnel for telnet:
11961 % ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
11964 The ssh command is used with the following options:
11968 Forces ssh to use version 2 of the protocol. (Do not use if you
11969 are working with older SSH servers)
11973 Indicates no command, or tunnel only. If omitted, ssh would
11974 initiate a normal session.
11978 Forces ssh to run in the background.
11982 Indicates a local tunnel in localport:remotehost:remoteport
11985 user@foo.example.com
11987 The remote SSH server.
11989 An SSH tunnel works by creating a listen socket on localhost on the
11990 specified port. It then forwards any connection received on the local
11991 host/port via the SSH connection to the specified remote host and port.
11993 In the example, port 5023 on localhost is being forwarded to port 23 on
11994 localhost of the remote machine. Since 23 is telnet, this would create a
11995 secure telnet session through an SSH tunnel.
11997 This can be used to wrap any number of insecure TCP protocols such as
11998 SMTP, POP3, FTP, etc.
12000 Example 10-1. Using SSH to Create a Secure Tunnel for SMTP
12002 % ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com
12003 user@mailserver.example.com's password: *****
12004 % telnet localhost 5025
12005 Trying 127.0.0.1...
12006 Connected to localhost.
12007 Escape character is '^]'.
12008 220 mailserver.example.com ESMTP
12010 This can be used in conjunction with an ssh-keygen(1) and additional user
12011 accounts to create a more seamless/hassle-free SSH tunneling environment.
12012 Keys can be used in place of typing a password, and the tunnels can be run
12013 as a separate user.
12015 ----------------------------------------------------------------------
12017 10.10.7.1 Practical SSH Tunneling Examples
12019 10.10.7.1.1 Secure Access of a POP3 Server
12021 At work, there is an SSH server that accepts connections from the outside.
12022 On the same office network resides a mail server running a POP3 server.
12023 The network, or network path between your home and office may or may not
12024 be completely trustable. Because of this, you need to check your e-mail in
12025 a secure manner. The solution is to create an SSH connection to your
12026 office's SSH server, and tunnel through to the mail server.
12028 % ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com
12029 user@ssh-server.example.com's password: ******
12031 When the tunnel is up and running, you can point your mail client to send
12032 POP3 requests to localhost port 2110. A connection here will be forwarded
12033 securely across the tunnel to mail.example.com.
12035 ----------------------------------------------------------------------
12037 10.10.7.1.2 Bypassing a Draconian Firewall
12039 Some network administrators impose extremely draconian firewall rules,
12040 filtering not only incoming connections, but outgoing connections. You may
12041 be only given access to contact remote machines on ports 22 and 80 for SSH
12044 You may wish to access another (perhaps non-work related) service, such as
12045 an Ogg Vorbis server to stream music. If this Ogg Vorbis server is
12046 streaming on some other port than 22 or 80, you will not be able to access
12049 The solution is to create an SSH connection to a machine outside of your
12050 network's firewall, and use it to tunnel to the Ogg Vorbis server.
12052 % ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org
12053 user@unfirewalled-system.example.org's password: *******
12055 Your streaming client can now be pointed to localhost port 8888, which
12056 will be forwarded over to music.example.com port 8000, successfully
12057 evading the firewall.
12059 ----------------------------------------------------------------------
12061 10.10.8 Further Reading
12065 ssh(1) scp(1) ssh-keygen(1) ssh-agent(1) ssh-add(1)
12067 sshd(8) sftp-server(8)
12069 ----------------------------------------------------------------------
12071 Chapter 11 Printing
12073 Contributed by Sean Kelly. Restructured and updated by Jim Mock.
12077 DragonFly can be used to print to a wide variety of printers, from the
12078 oldest impact printer to the latest laser printers, and everything in
12079 between, allowing you to produce high quality printed output from the
12080 applications you run.
12082 DragonFly can also be configured to act as a print server on a network; in
12083 this capacity DragonFly can receive print jobs from a variety of other
12084 computers, including other DragonFly computers, Windows and Mac OS hosts.
12085 DragonFly will ensure that one job at a time is printed, and can keep
12086 statistics on which users and machines are doing the most printing,
12087 produce ``banner'' pages showing who's printout is who's, and more.
12089 After reading this chapter, you will know:
12091 * How to configure the DragonFly print spooler.
12093 * How to install print filters, to handle special print jobs
12094 differently, including converting incoming documents to print formats
12095 that your printers understand.
12097 * How to enable header, or banner pages on your printout.
12099 * How to print to printers connected to other computers.
12101 * How to print to printers connected directly to the network.
12103 * How to control printer restrictions, including limiting the size of
12104 print jobs, and preventing certain users from printing.
12106 * How to keep printer statistics, and account for printer usage.
12108 * How to troubleshoot printing problems.
12110 Before reading this chapter, you should:
12112 * Know how to configure and install a new kernel (Chapter 9).
12114 ----------------------------------------------------------------------
12118 In order to use printers with DragonFly, you will need to set them up to
12119 work with the Berkeley line printer spooling system, also known as the LPD
12120 spooling system. It is the standard printer control system in DragonFly.
12121 This chapter introduces the LPD spooling system, often simply called LPD,
12122 and will guide you through its configuration.
12124 If you are already familiar with LPD or another printer spooling system,
12125 you may wish to skip to section Setting up the spooling system.
12127 LPD controls everything about a host's printers. It is responsible for a
12130 * It controls access to attached printers and printers attached to other
12131 hosts on the network.
12133 * It enables users to submit files to be printed; these submissions are
12136 * It prevents multiple users from accessing a printer at the same time
12137 by maintaining a queue for each printer.
12139 * It can print header pages (also known as banner or burst pages) so
12140 users can easily find jobs they have printed in a stack of printouts.
12142 * It takes care of communications parameters for printers connected on
12145 * It can send jobs over the network to a LPD spooler on another host.
12147 * It can run special filters to format jobs to be printed for various
12148 printer languages or printer capabilities.
12150 * It can account for printer usage.
12152 Through a configuration file (/etc/printcap), and by providing the special
12153 filter programs, you can enable the LPD system to do all or some subset of
12154 the above for a great variety of printer hardware.
12156 ----------------------------------------------------------------------
12158 11.2.1 Why You Should Use the Spooler
12160 If you are the sole user of your system, you may be wondering why you
12161 should bother with the spooler when you do not need access control, header
12162 pages, or printer accounting. While it is possible to enable direct access
12163 to a printer, you should use the spooler anyway since:
12165 * LPD prints jobs in the background; you do not have to wait for data to
12166 be copied to the printer.
12168 * LPD can conveniently run a job to be printed through filters to add
12169 date/time headers or convert a special file format (such as a TeX DVI
12170 file) into a format the printer will understand. You will not have to
12171 do these steps manually.
12173 * Many free and commercial programs that provide a print feature usually
12174 expect to talk to the spooler on your system. By setting up the
12175 spooling system, you will more easily support other software you may
12176 later add or already have.
12178 ----------------------------------------------------------------------
12182 To use printers with the LPD spooling system, you will need to set up both
12183 your printer hardware and the LPD software. This document describes two
12186 * See section Simple Printer Setup to learn how to connect a printer,
12187 tell LPD how to communicate with it, and print plain text files to the
12190 * See section Advanced Printer Setup to find out how to print a variety
12191 of special file formats, to print header pages, to print across a
12192 network, to control access to printers, and to do printer accounting.
12194 ----------------------------------------------------------------------
12196 11.3.1 Simple Printer Setup
12198 This section tells how to configure printer hardware and the LPD software
12199 to use the printer. It teaches the basics:
12201 * Section Hardware Setup gives some hints on connecting the printer to a
12202 port on your computer.
12204 * Section Software Setup shows how to set up the LPD spooler
12205 configuration file (/etc/printcap).
12207 If you are setting up a printer that uses a network protocol to accept
12208 data to print instead of a serial or parallel interface, see Printers With
12209 Networked Data Stream Interfaces.
12211 Although this section is called ``Simple Printer Setup'', it is actually
12212 fairly complex. Getting the printer to work with your computer and the LPD
12213 spooler is the hardest part. The advanced options like header pages and
12214 accounting are fairly easy once you get the printer working.
12216 ----------------------------------------------------------------------
12218 11.3.1.1 Hardware Setup
12220 This section tells about the various ways you can connect a printer to
12221 your PC. It talks about the kinds of ports and cables, and also the kernel
12222 configuration you may need to enable DragonFly to speak to the printer.
12224 If you have already connected your printer and have successfully printed
12225 with it under another operating system, you can probably skip to section
12228 ----------------------------------------------------------------------
12230 11.3.1.1.1 Ports and Cables
12232 Printers sold for use on PC's today generally come with one or more of the
12233 following three interfaces:
12235 * Serial interfaces, also known as RS232C or RS232D, or COM ports, use a
12236 serial port on your computer to send data to the printer. Serial
12237 interfaces are common in the computer industry and cables are readily
12238 available and also easy to construct. Serial interfaces sometimes need
12239 special cables and might require you to configure somewhat complex
12240 communications options. Most PC serial ports have a maximum
12241 transmission rate of 115200 bps, which makes printing large graphic
12242 print jobs with them impractical.
12244 * Parallel interfaces use a parallel port on your computer to send data
12245 to the printer. Parallel interfaces are common in the PC market and
12246 are faster than RS232 serial. Cables are readily available but more
12247 difficult to construct by hand. There are usually no communications
12248 options with parallel interfaces, making their configuration
12249 exceedingly simple.
12251 Parallel interfaces are sometimes known as ``Centronics'' interfaces,
12252 named after the connector type on the printer.
12254 * USB interfaces, named for the Universal Serial Bus, can run at even
12255 faster speeds than parallel or RS232 serial interfaces. Cables are
12256 simple and cheap. USB is superior to RS232 Serial and to Parallel for
12257 printing, but it is not as well supported under UNIX systems. A way to
12258 avoid this problem is to purchase a printer that has both a USB
12259 interface and a Parallel interface, as many printers do.
12261 In general, Parallel interfaces usually offer just one-way communication
12262 (computer to printer) while serial and USB gives you two-way. Newer
12263 parallel ports (EPP and ECP) and printers can communicate in both
12264 directions under DragonFly when a IEEE1284 compliant cable is used.
12266 Two-way communication to the printer over a parallel port is generally
12267 done one of two ways. The first method uses a custom built printer driver
12268 for DragonFly that speaks the proprietary language used by the printer.
12269 This is common with inkjet printers and can be used for reporting ink
12270 levels and other status information. The second method is used when the
12271 printer supports PostScript.
12273 PostScript jobs are actually programs sent to the printer; they need not
12274 produce paper at all and may return results directly to the computer.
12275 PostScript also uses two-way communication to tell the computer about
12276 problems, such as errors in the PostScript program or paper jams. Your
12277 users may be appreciative of such information. Furthermore, the best way
12278 to do effective accounting with a PostScript printer requires two-way
12279 communication: you ask the printer for its page count (how many pages it
12280 has printed in its lifetime), then send the user's job, then ask again for
12281 its page count. Subtract the two values and you know how much paper to
12284 ----------------------------------------------------------------------
12286 11.3.1.1.2 Parallel Ports
12288 To hook up a printer using a parallel interface, connect the Centronics
12289 cable between the printer and the computer. The instructions that came
12290 with the printer, the computer, or both should give you complete guidance.
12292 Remember which parallel port you used on the computer. The first parallel
12293 port is /dev/ppc0 to DragonFly; the second is /dev/ppc1, and so on. The
12294 printer device name uses the same scheme: /dev/lpt0 for the printer on the
12295 first parallel ports etc.
12297 ----------------------------------------------------------------------
12299 11.3.1.1.3 Serial Ports
12301 To hook up a printer using a serial interface, connect the proper serial
12302 cable between the printer and the computer. The instructions that came
12303 with the printer, the computer, or both should give you complete guidance.
12305 If you are unsure what the ``proper serial cable'' is, you may wish to try
12306 one of the following alternatives:
12308 * A modem cable connects each pin of the connector on one end of the
12309 cable straight through to its corresponding pin of the connector on
12310 the other end. This type of cable is also known as a ``DTE-to-DCE''
12313 * A null-modem cable connects some pins straight through, swaps others
12314 (send data to receive data, for example), and shorts some internally
12315 in each connector hood. This type of cable is also known as a
12316 ``DTE-to-DTE'' cable.
12318 * A serial printer cable, required for some unusual printers, is like
12319 the null-modem cable, but sends some signals to their counterparts
12320 instead of being internally shorted.
12322 You should also set up the communications parameters for the printer,
12323 usually through front-panel controls or DIP switches on the printer.
12324 Choose the highest bps (bits per second, sometimes baud rate) rate that
12325 both your computer and the printer can support. Choose 7 or 8 data bits;
12326 none, even, or odd parity; and 1 or 2 stop bits. Also choose a flow
12327 control protocol: either none, or XON/XOFF (also known as ``in-band'' or
12328 ``software'') flow control. Remember these settings for the software
12329 configuration that follows.
12331 ----------------------------------------------------------------------
12333 11.3.1.2 Software Setup
12335 This section describes the software setup necessary to print with the LPD
12336 spooling system in DragonFly.
12338 Here is an outline of the steps involved:
12340 1. Configure your kernel, if necessary, for the port you are using for
12341 the printer; section Kernel Configuration tells you what you need to
12344 2. Set the communications mode for the parallel port, if you are using a
12345 parallel port; section Setting the Communication Mode for the Parallel
12346 Port gives details.
12348 3. Test if the operating system can send data to the printer. Section
12349 Checking Printer Communications gives some suggestions on how to do
12352 4. Set up LPD for the printer by modifying the file /etc/printcap. You
12353 will find out how to do this later in this chapter.
12355 ----------------------------------------------------------------------
12357 11.3.1.2.1 Kernel Configuration
12359 The operating system kernel is compiled to work with a specific set of
12360 devices. The serial or parallel interface for your printer is a part of
12361 that set. Therefore, it might be necessary to add support for an
12362 additional serial or parallel port if your kernel is not already
12363 configured for one.
12365 To find out if the kernel you are currently using supports a serial
12368 # grep sioN /var/run/dmesg.boot
12370 Where N is the number of the serial port, starting from zero. If you see
12371 output similar to the following:
12373 sio2 at port 0x3e8-0x3ef irq 5 on isa
12376 then the kernel supports the port.
12378 To find out if the kernel supports a parallel interface, type:
12380 # grep ppcN /var/run/dmesg.boot
12382 Where N is the number of the parallel port, starting from zero. If you see
12383 output similar to the following:
12385 ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0
12386 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
12387 ppc0: FIFO with 16/16/8 bytes threshold
12389 then the kernel supports the port.
12391 You might have to reconfigure your kernel in order for the operating
12392 system to recognize and use the parallel or serial port you are using for
12395 To add support for a serial port, see the section on kernel configuration.
12396 To add support for a parallel port, see that section and the section that
12399 ----------------------------------------------------------------------
12401 11.3.1.3 Adding /dev Entries for the Ports
12403 Even though the kernel may support communication along a serial or
12404 parallel port, you will still need a software interface through which
12405 programs running on the system can send and receive data. That is what
12406 entries in the /dev directory are for.
12408 To add a /dev entry for a port:
12410 1. Become root with the su(1) command. Enter the root password when
12413 2. Change to the /dev directory:
12421 Where port is the device entry for the port you want to make. Use lpt0
12422 for the printer on the first parallel port, lpt1 for the printer on
12423 the second port, and so on; use ttyd0 for the first serial port, ttyd1
12424 for the second, and so on.
12430 to make sure the device entry got created.
12432 ----------------------------------------------------------------------
12434 11.3.1.3.1 Setting the Communication Mode for the Parallel Port
12436 When you are using the parallel interface, you can choose whether
12437 DragonFly should use interrupt-driven or polled communication with the
12438 printer. The generic printer device driver (lpt(4)) on DragonFly uses the
12439 ppbus(4) system, which controls the port chipset with the ppc(4) driver.
12441 * The interrupt-driven method is the default with the GENERIC kernel.
12442 With this method, the operating system uses an IRQ line to determine
12443 when the printer is ready for data.
12445 * The polled method directs the operating system to repeatedly ask the
12446 printer if it is ready for more data. When it responds ready, the
12447 kernel sends more data.
12449 The interrupt-driven method is usually somewhat faster but uses up a
12450 precious IRQ line. Some newer HP printers are claimed not to work
12451 correctly in interrupt mode, apparently due to some (not yet exactly
12452 understood) timing problem. These printers need polled mode. You should
12453 use whichever one works. Some printers will work in both modes, but are
12454 painfully slow in interrupt mode.
12456 You can set the communications mode in two ways: by configuring the kernel
12457 or by using the lptcontrol(8) program.
12459 To set the communications mode by configuring the kernel:
12461 1. Edit your kernel configuration file. Look for an ppc0 entry. If you
12462 are setting up the second parallel port, use ppc1 instead. Use ppc2
12463 for the third port, and so on.
12465 * If you want interrupt-driven mode, add the irq specifier:
12467 device ppc0 at isa? irq N
12469 Where N is the IRQ number for your computer's parallel port.
12471 * If you want polled mode, do not add the irq specifier. Use the
12472 following line in your kernel configuration file:
12474 device ppc0 at isa?
12476 2. Save the file. Then configure, build, and install the kernel, then
12477 reboot. See kernel configuration for more details.
12479 To set the communications mode with lptcontrol(8):
12483 # lptcontrol -i -d /dev/lptN
12485 to set interrupt-driven mode for lptN.
12489 # lptcontrol -p -d /dev/lptN
12491 to set polled-mode for lptN.
12493 You could put these commands in your /etc/rc.local file to set the mode
12494 each time your system boots. See lptcontrol(8) for more information.
12496 ----------------------------------------------------------------------
12498 11.3.1.3.2 Checking Printer Communications
12500 Before proceeding to configure the spooling system, you should make sure
12501 the operating system can successfully send data to your printer. It is a
12502 lot easier to debug printer communication and the spooling system
12505 To test the printer, we will send some text to it. For printers that can
12506 immediately print characters sent to them, the program lptest(1) is
12507 perfect: it generates all 96 printable ASCII characters in 96 lines.
12509 For a PostScript (or other language-based) printer, we will need a more
12510 sophisticated test. A small PostScript program, such as the following,
12514 100 100 moveto 300 300 lineto stroke
12515 310 310 moveto /Helvetica findfont 12 scalefont setfont
12516 (Is this thing working?) show
12519 The above PostScript code can be placed into a file and used as shown in
12520 the examples appearing in the following sections.
12522 Note: When this document refers to a printer language, it is assuming a
12523 language like PostScript, and not Hewlett Packard's PCL. Although PCL
12524 has great functionality, you can intermingle plain text with its escape
12525 sequences. PostScript cannot directly print plain text, and that is the
12526 kind of printer language for which we must make special accommodations.
12528 ----------------------------------------------------------------------
12530 11.3.1.3.2.1 Checking a Parallel Printer
12532 This section tells you how to check if DragonFly can communicate with a
12533 printer connected to a parallel port.
12535 To test a printer on a parallel port:
12537 1. Become root with su(1).
12539 2. Send data to the printer.
12541 * If the printer can print plain text, then use lptest(1). Type:
12543 # lptest > /dev/lptN
12545 Where N is the number of the parallel port, starting from zero.
12547 * If the printer understands PostScript or other printer language,
12548 then send a small program to the printer. Type:
12552 Then, line by line, type the program carefully as you cannot edit
12553 a line once you have pressed RETURN or ENTER. When you have
12554 finished entering the program, press CONTROL+D, or whatever your
12555 end of file key is.
12557 Alternatively, you can put the program in a file and type:
12559 # cat file > /dev/lptN
12561 Where file is the name of the file containing the program you
12562 want to send to the printer.
12564 You should see something print. Do not worry if the text does not look
12565 right; we will fix such things later.
12567 ----------------------------------------------------------------------
12569 11.3.1.3.2.2 Checking a Serial Printer
12571 This section tells you how to check if DragonFly can communicate with a
12572 printer on a serial port.
12574 To test a printer on a serial port:
12576 1. Become root with su(1).
12578 2. Edit the file /etc/remote. Add the following entry:
12580 printer:dv=/dev/port:br#bps-rate:pa=parity
12582 Where port is the device entry for the serial port (ttyd0, ttyd1,
12583 etc.), bps-rate is the bits-per-second rate at which the printer
12584 communicates, and parity is the parity required by the printer (either
12585 even, odd, none, or zero).
12587 Here is a sample entry for a printer connected via a serial line to
12588 the third serial port at 19200 bps with no parity:
12590 printer:dv=/dev/ttyd2:br#19200:pa=none
12592 3. Connect to the printer with tip(1). Type:
12596 If this step does not work, edit the file /etc/remote again and try
12597 using /dev/cuaaN instead of /dev/ttydN.
12599 4. Send data to the printer.
12601 * If the printer can print plain text, then use lptest(1). Type:
12605 * If the printer understands PostScript or other printer language,
12606 then send a small program to the printer. Type the program, line
12607 by line, very carefully as backspacing or other editing keys may
12608 be significant to the printer. You may also need to type a
12609 special end-of-file key for the printer so it knows it received
12610 the whole program. For PostScript printers, press CONTROL+D.
12612 Alternatively, you can put the program in a file and type:
12616 Where file is the name of the file containing the program. After
12617 tip(1) sends the file, press any required end-of-file key.
12619 You should see something print. Do not worry if the text does not look
12620 right; we will fix that later.
12622 ----------------------------------------------------------------------
12624 11.3.1.4 Enabling the Spooler: the /etc/printcap File
12626 At this point, your printer should be hooked up, your kernel configured to
12627 communicate with it (if necessary), and you have been able to send some
12628 simple data to the printer. Now, we are ready to configure LPD to control
12629 access to your printer.
12631 You configure LPD by editing the file /etc/printcap. The LPD spooling
12632 system reads this file each time the spooler is used, so updates to the
12633 file take immediate effect.
12635 The format of the printcap(5) file is straightforward. Use your favorite
12636 text editor to make changes to /etc/printcap. The format is identical to
12637 other capability files like /usr/share/misc/termcap and /etc/remote. For
12638 complete information about the format, see the cgetent(3).
12640 The simple spooler configuration consists of the following steps:
12642 1. Pick a name (and a few convenient aliases) for the printer, and put
12643 them in the /etc/printcap file; see the Naming the Printer section for
12644 more information on naming.
12646 2. Turn off header pages (which are on by default) by inserting the sh
12647 capability; see the Suppressing Header Pages section for more
12650 3. Make a spooling directory, and specify its location with the sd
12651 capability; see the Making the Spooling Directory section for more
12654 4. Set the /dev entry to use for the printer, and note it in
12655 /etc/printcap with the lp capability; see the Identifying the Printer
12656 Device for more information. Also, if the printer is on a serial port,
12657 set up the communication parameters with the ms# capability which is
12658 discussed in the Configuring Spooler Communications Parameters
12661 5. Install a plain text input filter; see the Installing the Text Filter
12662 section for details.
12664 6. Test the setup by printing something with the lpr(1) command. More
12665 details are available in the Trying It Out and Troubleshooting
12668 Note: Language-based printers, such as PostScript printers, cannot
12669 directly print plain text. The simple setup outlined above and described
12670 in the following sections assumes that if you are installing such a
12671 printer you will print only files that the printer can understand.
12673 Users often expect that they can print plain text to any of the printers
12674 installed on your system. Programs that interface to LPD to do their
12675 printing usually make the same assumption. If you are installing such a
12676 printer and want to be able to print jobs in the printer language and
12677 print plain text jobs, you are strongly urged to add an additional step to
12678 the simple setup outlined above: install an automatic
12679 plain-text-to-PostScript (or other printer language) conversion program.
12680 The section entitled Accommodating Plain Text Jobs on PostScript Printers
12681 tells how to do this.
12683 ----------------------------------------------------------------------
12685 11.3.1.4.1 Naming the Printer
12687 The first (easy) step is to pick a name for your printer It really does
12688 not matter whether you choose functional or whimsical names since you can
12689 also provide a number of aliases for the printer.
12691 At least one of the printers specified in the /etc/printcap should have
12692 the alias lp. This is the default printer's name. If users do not have the
12693 PRINTER environment variable nor specify a printer name on the command
12694 line of any of the LPD commands, then lp will be the default printer they
12697 Also, it is common practice to make the last alias for a printer be a full
12698 description of the printer, including make and model.
12700 Once you have picked a name and some common aliases, put them in the
12701 /etc/printcap file. The name of the printer should start in the leftmost
12702 column. Separate each alias with a vertical bar and put a colon after the
12705 In the following example, we start with a skeletal /etc/printcap that
12706 defines two printers (a Diablo 630 line printer and a Panasonic KX-P4455
12707 PostScript laser printer):
12710 # /etc/printcap for host rose
12712 rattan|line|diablo|lp|Diablo 630 Line Printer:
12714 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:
12716 In this example, the first printer is named rattan and has as aliases
12717 line, diablo, lp, and Diablo 630 Line Printer. Since it has the alias lp,
12718 it is also the default printer. The second is named bamboo, and has as
12719 aliases ps, PS, S, panasonic, and Panasonic KX-P4455 PostScript v51.4.
12721 ----------------------------------------------------------------------
12723 11.3.1.4.2 Suppressing Header Pages
12725 The LPD spooling system will by default print a header page for each job.
12726 The header page contains the user name who requested the job, the host
12727 from which the job came, and the name of the job, in nice large letters.
12728 Unfortunately, all this extra text gets in the way of debugging the simple
12729 printer setup, so we will suppress header pages.
12731 To suppress header pages, add the sh capability to the entry for the
12732 printer in /etc/printcap. Here is an example /etc/printcap with sh added:
12735 # /etc/printcap for host rose - no header pages anywhere
12737 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12740 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12743 Note how we used the correct format: the first line starts in the leftmost
12744 column, and subsequent lines are indented with a single TAB. Every line in
12745 an entry except the last ends in a backslash character.
12747 ----------------------------------------------------------------------
12749 11.3.1.4.3 Making the Spooling Directory
12751 The next step in the simple spooler setup is to make a spooling directory,
12752 a directory where print jobs reside until they are printed, and where a
12753 number of other spooler support files live.
12755 Because of the variable nature of spooling directories, it is customary to
12756 put these directories under /var/spool. It is not necessary to backup the
12757 contents of spooling directories, either. Recreating them is as simple as
12760 It is also customary to make the directory with a name that is identical
12761 to the name of the printer, as shown below:
12763 # mkdir /var/spool/printer-name
12765 However, if you have a lot of printers on your network, you might want to
12766 put the spooling directories under a single directory that you reserve
12767 just for printing with LPD. We will do this for our two example printers
12770 # mkdir /var/spool/lpd
12771 # mkdir /var/spool/lpd/rattan
12772 # mkdir /var/spool/lpd/bamboo
12774 Note: If you are concerned about the privacy of jobs that users print,
12775 you might want to protect the spooling directory so it is not publicly
12776 accessible. Spooling directories should be owned and be readable,
12777 writable, and searchable by user daemon and group daemon, and no one
12778 else. We will do this for our example printers:
12780 # chown daemon:daemon /var/spool/lpd/rattan
12781 # chown daemon:daemon /var/spool/lpd/bamboo
12782 # chmod 770 /var/spool/lpd/rattan
12783 # chmod 770 /var/spool/lpd/bamboo
12785 Finally, you need to tell LPD about these directories using the
12786 /etc/printcap file. You specify the pathname of the spooling directory
12787 with the sd capability:
12790 # /etc/printcap for host rose - added spooling directories
12792 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12793 :sh:sd=/var/spool/lpd/rattan:
12795 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12796 :sh:sd=/var/spool/lpd/bamboo:
12798 Note that the name of the printer starts in the first column but all other
12799 entries describing the printer should be indented with a tab and each line
12800 escaped with a backslash.
12802 If you do not specify a spooling directory with sd, the spooling system
12803 will use /var/spool/lpd as a default.
12805 ----------------------------------------------------------------------
12807 11.3.1.4.4 Identifying the Printer Device
12809 In the Adding /dev Entries for the Ports section, we identified which
12810 entry in the /dev directory DragonFly will use to communicate with the
12811 printer. Now, we tell LPD that information. When the spooling system has a
12812 job to print, it will open the specified device on behalf of the filter
12813 program (which is responsible for passing data to the printer).
12815 List the /dev entry pathname in the /etc/printcap file using the lp
12818 In our running example, let us assume that rattan is on the first parallel
12819 port, and bamboo is on a sixth serial port; here are the additions to
12823 # /etc/printcap for host rose - identified what devices to use
12825 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12826 :sh:sd=/var/spool/lpd/rattan:\
12829 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12830 :sh:sd=/var/spool/lpd/bamboo:\
12833 If you do not specify the lp capability for a printer in your
12834 /etc/printcap file, LPD uses /dev/lp as a default. /dev/lp currently does
12835 not exist in DragonFly.
12837 If the printer you are installing is connected to a parallel port, skip to
12838 the section entitled, Installing the Text Filter. Otherwise, be sure to
12839 follow the instructions in the next section.
12841 ----------------------------------------------------------------------
12843 11.3.1.4.5 Configuring Spooler Communication Parameters
12845 For printers on serial ports, LPD can set up the bps rate, parity, and
12846 other serial communication parameters on behalf of the filter program that
12847 sends data to the printer. This is advantageous since:
12849 * It lets you try different communication parameters by simply editing
12850 the /etc/printcap file; you do not have to recompile the filter
12853 * It enables the spooling system to use the same filter program for
12854 multiple printers which may have different serial communication
12857 The following /etc/printcap capabilities control serial communication
12858 parameters of the device listed in the lp capability:
12862 Sets the communications speed of the device to bps-rate, where
12863 bps-rate can be 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800,
12864 2400, 4800, 9600, 19200, 38400, 57600, or 115200 bits-per-second.
12868 Sets the options for the terminal device after opening the device.
12869 stty(1) explains the available options.
12871 When LPD opens the device specified by the lp capability, it sets the
12872 characteristics of the device to those specified with the ms# capability.
12873 Of particular interest will be the parenb, parodd, cs5, cs6, cs7, cs8,
12874 cstopb, crtscts, and ixon modes, which are explained in the stty(1) manual
12877 Let us add to our example printer on the sixth serial port. We will set
12878 the bps rate to 38400. For the mode, we will set no parity with -parenb,
12879 8-bit characters with cs8, no modem control with clocal and hardware flow
12880 control with crtscts:
12882 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12883 :sh:sd=/var/spool/lpd/bamboo:\
12884 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:
12886 ----------------------------------------------------------------------
12888 11.3.1.4.6 Installing the Text Filter
12890 We are now ready to tell LPD what text filter to use to send jobs to the
12891 printer. A text filter, also known as an input filter, is a program that
12892 LPD runs when it has a job to print. When LPD runs the text filter for a
12893 printer, it sets the filter's standard input to the job to print, and its
12894 standard output to the printer device specified with the lp capability.
12895 The filter is expected to read the job from standard input, perform any
12896 necessary translation for the printer, and write the results to standard
12897 output, which will get printed. For more information on the text filter,
12898 see the Filters section.
12900 For our simple printer setup, the text filter can be a small shell script
12901 that just executes /bin/cat to send the job to the printer. DragonFly
12902 comes with another filter called lpf that handles backspacing and
12903 underlining for printers that might not deal with such character streams
12904 well. And, of course, you can use any other filter program you want. The
12905 filter lpf is described in detail in section entitled lpf: a Text Filter.
12907 First, let us make the shell script /usr/local/libexec/if-simple be a
12908 simple text filter. Put the following text into that file with your
12909 favorite text editor:
12913 # if-simple - Simple text input filter for lpd
12914 # Installed in /usr/local/libexec/if-simple
12916 # Simply copies stdin to stdout. Ignores all filter arguments.
12921 Make the file executable:
12923 # chmod 555 /usr/local/libexec/if-simple
12925 And then tell LPD to use it by specifying it with the if capability in
12926 /etc/printcap. We will add it to the two printers we have so far in the
12927 example /etc/printcap:
12930 # /etc/printcap for host rose - added text filter
12932 rattan|line|diablo|lp|Diablo 630 Line Printer:\
12933 :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\
12934 :if=/usr/local/libexec/if-simple:
12936 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
12937 :sh:sd=/var/spool/lpd/bamboo:\
12938 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:\
12939 :if=/usr/local/libexec/if-simple:
12941 ----------------------------------------------------------------------
12943 11.3.1.4.7 Turn on LPD
12945 lpd(8) is run from /etc/rc, controlled by the lpd_enable variable. This
12946 variable defaults to NO. If you have not done so already, add the line:
12950 to /etc/rc.conf, and then either restart your machine, or just run lpd(8).
12954 ----------------------------------------------------------------------
12956 11.3.1.4.8 Trying It Out
12958 You have reached the end of the simple LPD setup. Unfortunately,
12959 congratulations are not quite yet in order, since we still have to test
12960 the setup and correct any problems. To test the setup, try printing
12961 something. To print with the LPD system, you use the command lpr(1), which
12962 submits a job for printing.
12964 You can combine lpr(1) with the lptest(1) program, introduced in section
12965 Checking Printer Communications to generate some test text.
12967 To test the simple LPD setup:
12971 # lptest 20 5 | lpr -Pprinter-name
12973 Where printer-name is a the name of a printer (or an alias) specified in
12974 /etc/printcap. To test the default printer, type lpr(1) without any -P
12975 argument. Again, if you are testing a printer that expects PostScript,
12976 send a PostScript program in that language instead of using lptest(1). You
12977 can do so by putting the program in a file and typing lpr file.
12979 For a PostScript printer, you should get the results of the program. If
12980 you are using lptest(1), then your results should look like the following:
12982 !"#$%&'()*+,-./01234
12983 "#$%&'()*+,-./012345
12984 #$%&'()*+,-./0123456
12985 $%&'()*+,-./01234567
12986 %&'()*+,-./012345678
12988 To further test the printer, try downloading larger programs (for
12989 language-based printers) or running lptest(1) with different arguments.
12990 For example, lptest 80 60 will produce 60 lines of 80 characters each.
12992 If the printer did not work, see the Troubleshooting section.
12994 ----------------------------------------------------------------------
12996 11.4 Advanced Printer Setup
12998 This section describes filters for printing specially formatted files,
12999 header pages, printing across networks, and restricting and accounting for
13002 ----------------------------------------------------------------------
13006 Although LPD handles network protocols, queuing, access control, and other
13007 aspects of printing, most of the real work happens in the filters. Filters
13008 are programs that communicate with the printer and handle its device
13009 dependencies and special requirements. In the simple printer setup, we
13010 installed a plain text filter--an extremely simple one that should work
13011 with most printers (section Installing the Text Filter).
13013 However, in order to take advantage of format conversion, printer
13014 accounting, specific printer quirks, and so on, you should understand how
13015 filters work. It will ultimately be the filter's responsibility to handle
13016 these aspects. And the bad news is that most of the time you have to
13017 provide filters yourself. The good news is that many are generally
13018 available; when they are not, they are usually easy to write.
13020 Also, DragonFly comes with one, /usr/libexec/lpr/lpf, that works with many
13021 printers that can print plain text. (It handles backspacing and tabs in
13022 the file, and does accounting, but that is about all it does.) There are
13023 also several filters and filter components in pkgsrc.
13025 Here is what you will find in this section:
13027 * Section How Filters Work, tries to give an overview of a filter's role
13028 in the printing process. You should read this section to get an
13029 understanding of what is happening ``under the hood'' when LPD uses
13030 filters. This knowledge could help you anticipate and debug problems
13031 you might encounter as you install more and more filters on each of
13034 * LPD expects every printer to be able to print plain text by default.
13035 This presents a problem for PostScript (or other language-based
13036 printers) which cannot directly print plain text. Section
13037 Accommodating Plain Text Jobs on PostScript Printers tells you what
13038 you should do to overcome this problem. You should read this section
13039 if you have a PostScript printer.
13041 * PostScript is a popular output format for many programs. Even some
13042 people (myself included) write PostScript code directly. But
13043 PostScript printers are expensive. Section Simulating PostScript on
13044 Non PostScript Printers tells how you can further modify a printer's
13045 text filter to accept and print PostScript data on a non PostScript
13046 printer. You should read this section if you do not have a PostScript
13049 * Section Conversion Filters tells about a way you can automate the
13050 conversion of specific file formats, such as graphic or typesetting
13051 data, into formats your printer can understand. After reading this
13052 section, you should be able to set up your printers such that users
13053 can type lpr -t to print troff data, or lpr -d to print TeX DVI data,
13054 or lpr -v to print raster image data, and so forth. I recommend
13055 reading this section.
13057 * Section Output Filters tells all about a not often used feature of
13058 LPD: output filters. Unless you are printing header pages (see Header
13059 Pages), you can probably skip that section altogether.
13061 * Section lpf: a Text Filter describes lpf, a fairly complete if simple
13062 text filter for line printers (and laser printers that act like line
13063 printers) that comes with DragonFly. If you need a quick way to get
13064 printer accounting working for plain text, or if you have a printer
13065 which emits smoke when it sees backspace characters, you should
13066 definitely consider lpf.
13068 ----------------------------------------------------------------------
13070 11.4.1.1 How Filters Work
13072 As mentioned before, a filter is an executable program started by LPD to
13073 handle the device-dependent part of communicating with the printer.
13075 When LPD wants to print a file in a job, it starts a filter program. It
13076 sets the filter's standard input to the file to print, its standard output
13077 to the printer, and its standard error to the error logging file
13078 (specified in the lf capability in /etc/printcap, or /dev/console by
13081 Which filter LPD starts and the filter's arguments depend on what is
13082 listed in the /etc/printcap file and what arguments the user specified for
13083 the job on the lpr(1) command line. For example, if the user typed lpr -t,
13084 LPD would start the troff filter, listed in the tf capability for the
13085 destination printer. If the user wanted to print plain text, it would
13086 start the if filter (this is mostly true: see Output Filters for details).
13088 There are three kinds of filters you can specify in /etc/printcap:
13090 * The text filter, confusingly called the input filter in LPD
13091 documentation, handles regular text printing. Think of it as the
13092 default filter. LPD expects every printer to be able to print plain
13093 text by default, and it is the text filter's job to make sure
13094 backspaces, tabs, or other special characters do not confuse the
13095 printer. If you are in an environment where you have to account for
13096 printer usage, the text filter must also account for pages printed,
13097 usually by counting the number of lines printed and comparing that to
13098 the number of lines per page the printer supports. The text filter is
13099 started with the following argument list:
13101 filter-name [-c] -wwidth -llength -iindent -n login -h host acct-file
13107 appears if the job is submitted with lpr -l
13111 is the value from the pw (page width) capability
13112 specified in /etc/printcap, default 132
13116 is the value from the pl (page length) capability,
13121 is the amount of the indentation from lpr -i, default 0
13125 is the account name of the user printing the file
13129 is the host name from which the job was submitted
13133 is the name of the accounting file from the af
13136 * A conversion filter converts a specific file format into one the
13137 printer can render onto paper. For example, ditroff typesetting data
13138 cannot be directly printed, but you can install a conversion filter
13139 for ditroff files to convert the ditroff data into a form the printer
13140 can digest and print. Section Conversion Filters tells all about them.
13141 Conversion filters also need to do accounting, if you need printer
13142 accounting. Conversion filters are started with the following
13145 filter-name -xpixel-width -ypixel-height -n login -h host acct-file
13147 where pixel-width is the value from the px capability (default 0) and
13148 pixel-height is the value from the py capability (default 0).
13149 * The output filter is used only if there is no text filter, or if
13150 header pages are enabled. In my experience, output filters are rarely
13151 used. Section Output Filters describe them. There are only two
13152 arguments to an output filter:
13154 filter-name -wwidth -llength
13156 which are identical to the text filters -w and -l arguments.
13158 Filters should also exit with the following exit status:
13162 If the filter printed the file successfully.
13166 If the filter failed to print the file but wants LPD to try to
13167 print the file again. LPD will restart a filter if it exits with
13172 If the filter failed to print the file and does not want LPD to
13173 try again. LPD will throw out the file.
13175 The text filter that comes with the DragonFly release,
13176 /usr/libexec/lpr/lpf, takes advantage of the page width and length
13177 arguments to determine when to send a form feed and how to account for
13178 printer usage. It uses the login, host, and accounting file arguments to
13179 make the accounting entries.
13181 If you are shopping for filters, see if they are LPD-compatible. If they
13182 are, they must support the argument lists described above. If you plan on
13183 writing filters for general use, then have them support the same argument
13184 lists and exit codes.
13186 ----------------------------------------------------------------------
13188 11.4.1.2 Accommodating Plain Text Jobs on PostScript(R) Printers
13190 If you are the only user of your computer and PostScript (or other
13191 language-based) printer, and you promise to never send plain text to your
13192 printer and to never use features of various programs that will want to
13193 send plain text to your printer, then you do not need to worry about this
13196 But, if you would like to send both PostScript and plain text jobs to the
13197 printer, then you are urged to augment your printer setup. To do so, we
13198 have the text filter detect if the arriving job is plain text or
13199 PostScript. All PostScript jobs must start with %! (for other printer
13200 languages, see your printer documentation). If those are the first two
13201 characters in the job, we have PostScript, and can pass the rest of the
13202 job directly. If those are not the first two characters in the file, then
13203 the filter will convert the text into PostScript and print the result.
13207 ----------------------------------------------------------------------
13209 11.4.1.3 Simulating PostScript on Non PostScript Printers
13211 PostScript is the de facto standard for high quality typesetting and
13212 printing. PostScript is, however, an expensive standard. Thankfully,
13213 Aladdin Enterprises has a free PostScript work-alike called Ghostscript
13214 that runs with DragonFly. Ghostscript can read most PostScript files and
13215 can render their pages onto a variety of devices, including many brands of
13216 non-PostScript printers. By installing Ghostscript and using a special
13217 text filter for your printer, you can make your non PostScript printer act
13218 like a real PostScript printer.
13220 Ghostscript is in pkgsrc, if you would like to install it from there. You
13221 can fetch, build, and install it quite easily yourself, as well.
13223 To simulate PostScript, we have the text filter detect if it is printing a
13224 PostScript file. If it is not, then the filter will pass the file directly
13225 to the printer; otherwise, it will use Ghostscript to first convert the
13226 file into a format the printer will understand.
13228 Here is an example: the following script is a text filter for Hewlett
13229 Packard DeskJet 500 printers. For other printers, substitute the -sDEVICE
13230 argument to the gs (Ghostscript) command. (Type gs -h to get a list of
13231 devices the current installation of Ghostscript supports.)
13235 # ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
13236 # Installed in /usr/local/libexec/ifhp
13239 # Treat LF as CR+LF:
13241 printf "\033&k2G" || exit 2
13244 # Read first two characters of the file
13246 IFS="" read -r first_line
13247 first_two_chars=`expr "$first_line" : '\(..\)'`
13249 if [ "$first_two_chars" = "%!" ]; then
13251 # It is PostScript; use Ghostscript to scan-convert and print it.
13253 # Note that PostScript files are actually interpreted programs,
13254 # and those programs are allowed to write to stdout, which will
13255 # mess up the printed output. So, we redirect stdout to stderr
13256 # and then make descriptor 3 go to stdout, and have Ghostscript
13257 # write its output there. Exercise for the clever reader:
13258 # capture the stderr output from Ghostscript and mail it back to
13259 # the user originating the print job.
13262 /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
13263 -sOutputFile=/dev/fd/3 - && exit 0
13266 # Plain text or HP/PCL, so just print it directly; print a form feed
13267 # at the end to eject the last page.
13269 echo "$first_line" && cat && printf "\033&l0H" &&
13275 Finally, you need to notify LPD of the filter via the if capability:
13277 :if=/usr/local/libexec/ifhp:
13279 That is it. You can type lpr plain.text and lpr whatever.ps and both
13280 should print successfully.
13282 ----------------------------------------------------------------------
13284 11.4.1.4 Conversion Filters
13286 After completing the simple setup described in Simple Printer Setup, the
13287 first thing you will probably want to do is install conversion filters for
13288 your favorite file formats (besides plain ASCII text).
13290 ----------------------------------------------------------------------
13292 11.4.1.4.1 Why Install Conversion Filters?
13294 Conversion filters make printing various kinds of files easy. As an
13295 example, suppose we do a lot of work with the TeX typesetting system, and
13296 we have a PostScript printer. Every time we generate a DVI file from TeX,
13297 we cannot print it directly until we convert the DVI file into PostScript.
13298 The command sequence goes like this:
13300 % dvips seaweed-analysis.dvi
13301 % lpr seaweed-analysis.ps
13303 By installing a conversion filter for DVI files, we can skip the hand
13304 conversion step each time by having LPD do it for us. Now, each time we
13305 get a DVI file, we are just one step away from printing it:
13307 % lpr -d seaweed-analysis.dvi
13309 We got LPD to do the DVI file conversion for us by specifying the -d
13310 option. Section Formatting and Conversion Options lists the conversion
13313 For each of the conversion options you want a printer to support, install
13314 a conversion filter and specify its pathname in /etc/printcap. A
13315 conversion filter is like the text filter for the simple printer setup
13316 (see section Installing the Text Filter) except that instead of printing
13317 plain text, the filter converts the file into a format the printer can
13320 ----------------------------------------------------------------------
13322 11.4.1.4.2 Which Conversions Filters Should I Install?
13324 You should install the conversion filters you expect to use. If you print
13325 a lot of DVI data, then a DVI conversion filter is in order. If you have
13326 got plenty of troff to print out, then you probably want a troff filter.
13328 The following table summarizes the filters that LPD works with, their
13329 capability entries for the /etc/printcap file, and how to invoke them with
13332 File type /etc/printcap capability lpr option
13340 plain text if none, -p, or -l
13342 In our example, using lpr -d means the printer needs a df capability in
13343 its entry in /etc/printcap.
13345 Despite what others might contend, formats like FORTRAN text and plot are
13346 probably obsolete. At your site, you can give new meanings to these or any
13347 of the formatting options just by installing custom filters. For example,
13348 suppose you would like to directly print Printerleaf files (files from the
13349 Interleaf desktop publishing program), but will never print plot files.
13350 You could install a Printerleaf conversion filter under the gf capability
13351 and then educate your users that lpr -g mean ``print Printerleaf files.''
13353 ----------------------------------------------------------------------
13355 11.4.1.4.3 Installing Conversion Filters
13357 Since conversion filters are programs you install outside of the base
13358 DragonFly installation, they should probably go under /usr/local. The
13359 directory /usr/local/libexec is a popular location, since they are
13360 specialized programs that only LPD will run; regular users should not ever
13363 To enable a conversion filter, specify its pathname under the appropriate
13364 capability for the destination printer in /etc/printcap.
13366 In our example, we will add the DVI conversion filter to the entry for the
13367 printer named bamboo. Here is the example /etc/printcap file again, with
13368 the new df capability for the printer bamboo.
13371 # /etc/printcap for host rose - added df filter for bamboo
13373 rattan|line|diablo|lp|Diablo 630 Line Printer:\
13374 :sh:sd=/var/spool/lpd/rattan:\
13376 :if=/usr/local/libexec/if-simple:
13378 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
13379 :sh:sd=/var/spool/lpd/bamboo:\
13380 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
13381 :if=/usr/local/libexec/psif:\
13382 :df=/usr/local/libexec/psdf:
13384 The DVI filter is a shell script named /usr/local/libexec/psdf. Here is
13389 # psdf - DVI to PostScript printer filter
13390 # Installed in /usr/local/libexec/psdf
13392 # Invoked by lpd when user runs lpr -d
13394 exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"
13396 This script runs dvips in filter mode (the -f argument) on standard input,
13397 which is the job to print. It then starts the PostScript printer filter
13398 lprps (see section Accommodating Plain Text Jobs on PostScript Printers)
13399 with the arguments LPD passed to this script. lprps will use those
13400 arguments to account for the pages printed.
13402 ----------------------------------------------------------------------
13404 11.4.1.4.4 More Conversion Filter Examples
13406 Since there is no fixed set of steps to install conversion filters, let me
13407 instead provide more examples. Use these as guidance to making your own
13408 filters. Use them directly, if appropriate.
13410 This example script is a raster (well, GIF file, actually) conversion
13411 filter for a Hewlett Packard LaserJet III-Si printer:
13415 # hpvf - Convert GIF files into HP/PCL, then print
13416 # Installed in /usr/local/libexec/hpvf
13418 PATH=/usr/X11R6/bin:$PATH; export PATH
13419 giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \
13423 It works by converting the GIF file into a portable anymap, converting
13424 that into a portable graymap, converting that into a portable bitmap, and
13425 converting that into LaserJet/PCL-compatible data.
13427 Here is the /etc/printcap file with an entry for a printer using the above
13431 # /etc/printcap for host orchid
13433 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
13434 :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
13435 :if=/usr/local/libexec/hpif:\
13436 :vf=/usr/local/libexec/hpvf:
13438 The following script is a conversion filter for troff data from the groff
13439 typesetting system for the PostScript printer named bamboo:
13443 # pstf - Convert groff's troff data into PS, then print.
13444 # Installed in /usr/local/libexec/pstf
13446 exec grops | /usr/local/libexec/lprps "$@"
13448 The above script makes use of lprps again to handle the communication with
13449 the printer. If the printer were on a parallel port, we would use this
13454 # pstf - Convert groff's troff data into PS, then print.
13455 # Installed in /usr/local/libexec/pstf
13459 That is it. Here is the entry we need to add to /etc/printcap to enable
13462 :tf=/usr/local/libexec/pstf:
13464 Here is an example that might make old hands at FORTRAN blush. It is a
13465 FORTRAN-text filter for any printer that can directly print plain text. We
13466 will install it for the printer teak:
13470 # hprf - FORTRAN text filter for LaserJet 3si:
13471 # Installed in /usr/local/libexec/hprf
13474 printf "\033&k2G" && fpr && printf "\033&l0H" &&
13478 And we will add this line to the /etc/printcap for the printer teak to
13479 enable this filter:
13481 :rf=/usr/local/libexec/hprf:
13483 ----------------------------------------------------------------------
13485 11.4.1.4.5 Automated Conversion: an Alternative to Conversion Filters
13487 All these conversion filters accomplish a lot for your printing
13488 environment, but at the cost forcing the user to specify (on the lpr(1)
13489 command line) which one to use. If your users are not particularly
13490 computer literate, having to specify a filter option will become annoying.
13491 What is worse, though, is that an incorrectly specified filter option may
13492 run a filter on the wrong type of file and cause your printer to spew out
13493 hundreds of sheets of paper.
13495 Rather than install conversion filters at all, you might want to try
13496 having the text filter (since it is the default filter) detect the type of
13497 file it has been asked to print and then automatically run the right
13498 conversion filter. Tools such as file can be of help here. Of course, it
13499 will be hard to determine the differences between some file types--and, of
13500 course, you can still provide conversion filters just for them.
13502 The pkgsrc collection has a text filter that performs automatic conversion
13503 called apsfilter. It can detect plain text, PostScript, and DVI files, run
13504 the proper conversions, and print.
13506 ----------------------------------------------------------------------
13508 11.4.1.5 Output Filters
13510 The LPD spooling system supports one other type of filter that we have not
13511 yet explored: an output filter. An output filter is intended for printing
13512 plain text only, like the text filter, but with many simplifications. If
13513 you are using an output filter but no text filter, then:
13515 * LPD starts an output filter once for the entire job instead of once
13516 for each file in the job.
13518 * LPD does not make any provision to identify the start or the end of
13519 files within the job for the output filter.
13521 * LPD does not pass the user's login or host to the filter, so it is not
13522 intended to do accounting. In fact, it gets only two arguments:
13524 filter-name -wwidth -llength
13526 Where width is from the pw capability and length is from the pl
13527 capability for the printer in question.
13529 Do not be seduced by an output filter's simplicity. If you would like each
13530 file in a job to start on a different page an output filter will not work.
13531 Use a text filter (also known as an input filter); see section Installing
13532 the Text Filter. Furthermore, an output filter is actually more complex in
13533 that it has to examine the byte stream being sent to it for special flag
13534 characters and must send signals to itself on behalf of LPD.
13536 However, an output filter is necessary if you want header pages and need
13537 to send escape sequences or other initialization strings to be able to
13538 print the header page. (But it is also futile if you want to charge header
13539 pages to the requesting user's account, since LPD does not give any user
13540 or host information to the output filter.)
13542 On a single printer, LPD allows both an output filter and text or other
13543 filters. In such cases, LPD will start the output filter to print the
13544 header page (see section Header Pages) only. LPD then expects the output
13545 filter to stop itself by sending two bytes to the filter: ASCII 031
13546 followed by ASCII 001. When an output filter sees these two bytes (031,
13547 001), it should stop by sending SIGSTOP to itself. When LPD's done running
13548 other filters, it will restart the output filter by sending SIGCONT to it.
13550 If there is an output filter but no text filter and LPD is working on a
13551 plain text job, LPD uses the output filter to do the job. As stated
13552 before, the output filter will print each file of the job in sequence with
13553 no intervening form feeds or other paper advancement, and this is probably
13554 not what you want. In almost all cases, you need a text filter.
13556 The program lpf, which we introduced earlier as a text filter, can also
13557 run as an output filter. If you need a quick-and-dirty output filter but
13558 do not want to write the byte detection and signal sending code, try lpf.
13559 You can also wrap lpf in a shell script to handle any initialization codes
13560 the printer might require.
13562 ----------------------------------------------------------------------
13564 11.4.1.6 lpf: a Text Filter
13566 The program /usr/libexec/lpr/lpf that comes with DragonFly is a text
13567 filter (input filter) that can indent output (job submitted with lpr -i),
13568 allow literal characters to pass (job submitted with lpr -l), adjust the
13569 printing position for backspaces and tabs in the job, and account for
13570 pages printed. It can also act like an output filter.
13572 lpf is suitable for many printing environments. And although it has no
13573 capability to send initialization sequences to a printer, it is easy to
13574 write a shell script to do the needed initialization and then execute lpf.
13576 In order for lpf to do page accounting correctly, it needs correct values
13577 filled in for the pw and pl capabilities in the /etc/printcap file. It
13578 uses these values to determine how much text can fit on a page and how
13579 many pages were in a user's job. For more information on printer
13580 accounting, see Accounting for Printer Usage.
13582 ----------------------------------------------------------------------
13584 11.4.2 Header Pages
13586 If you have lots of users, all of them using various printers, then you
13587 probably want to consider header pages as a necessary evil.
13589 Header pages, also known as banner or burst pages identify to whom jobs
13590 belong after they are printed. They are usually printed in large, bold
13591 letters, perhaps with decorative borders, so that in a stack of printouts
13592 they stand out from the real documents that comprise users' jobs. They
13593 enable users to locate their jobs quickly. The obvious drawback to a
13594 header page is that it is yet one more sheet that has to be printed for
13595 every job, their ephemeral usefulness lasting not more than a few minutes,
13596 ultimately finding themselves in a recycling bin or rubbish heap. (Note
13597 that header pages go with each job, not each file in a job, so the paper
13598 waste might not be that bad.)
13600 The LPD system can provide header pages automatically for your printouts
13601 if your printer can directly print plain text. If you have a PostScript
13602 printer, you will need an external program to generate the header page;
13603 see Header Pages on PostScript Printers.
13605 ----------------------------------------------------------------------
13607 11.4.2.1 Enabling Header Pages
13609 In the Simple Printer Setup section, we turned off header pages by
13610 specifying sh (meaning ``suppress header'') in the /etc/printcap file. To
13611 enable header pages for a printer, just remove the sh capability.
13613 Sounds too easy, right?
13615 You are right. You might have to provide an output filter to send
13616 initialization strings to the printer. Here is an example output filter
13617 for Hewlett Packard PCL-compatible printers:
13621 # hpof - Output filter for Hewlett Packard PCL-compatible printers
13622 # Installed in /usr/local/libexec/hpof
13624 printf "\033&k2G" || exit 2
13625 exec /usr/libexec/lpr/lpf
13627 Specify the path to the output filter in the of capability. See the Output
13628 Filters section for more information.
13630 Here is an example /etc/printcap file for the printer teak that we
13631 introduced earlier; we enabled header pages and added the above output
13635 # /etc/printcap for host orchid
13637 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
13638 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
13639 :if=/usr/local/libexec/hpif:\
13640 :vf=/usr/local/libexec/hpvf:\
13641 :of=/usr/local/libexec/hpof:
13643 Now, when users print jobs to teak, they get a header page with each job.
13644 If users want to spend time searching for their printouts, they can
13645 suppress header pages by submitting the job with lpr -h; see the Header
13646 Page Options section for more lpr(1) options.
13648 Note: LPD prints a form feed character after the header page. If your
13649 printer uses a different character or sequence of characters to eject a
13650 page, specify them with the ff capability in /etc/printcap.
13652 ----------------------------------------------------------------------
13654 11.4.2.2 Controlling Header Pages
13656 By enabling header pages, LPD will produce a long header, a full page of
13657 large letters identifying the user, host, and job. Here is an example
13658 (kelly printed the job named outline from host rose):
13668 k k eeee lll lll yyy y
13677 oooo u u ttttt l ii n nnn eeee
13678 o o u u t l i nn n e e
13679 o o u u t l i n n eeeeee
13680 o o u u t l i n n e
13681 o o u uu t t l i n n e e
13682 oooo uuu u tt lll iii n n eeee
13692 r rrr oooo ssss eeee
13706 Date: Sun Sep 17 11:04:58 1995
13708 LPD appends a form feed after this text so the job starts on a new page
13709 (unless you have sf (suppress form feeds) in the destination printer's
13710 entry in /etc/printcap).
13712 If you prefer, LPD can make a short header; specify sb (short banner) in
13713 the /etc/printcap file. The header page will look like this:
13715 rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995
13717 Also by default, LPD prints the header page first, then the job. To
13718 reverse that, specify hl (header last) in /etc/printcap.
13720 ----------------------------------------------------------------------
13722 11.4.2.3 Accounting for Header Pages
13724 Using LPD's built-in header pages enforces a particular paradigm when it
13725 comes to printer accounting: header pages must be free of charge.
13729 Because the output filter is the only external program that will have
13730 control when the header page is printed that could do accounting, and it
13731 is not provided with any user or host information or an accounting file,
13732 so it has no idea whom to charge for printer use. It is also not enough to
13733 just ``add one page'' to the text filter or any of the conversion filters
13734 (which do have user and host information) since users can suppress header
13735 pages with lpr -h. They could still be charged for header pages they did
13736 not print. Basically, lpr -h will be the preferred option of
13737 environmentally-minded users, but you cannot offer any incentive to use
13740 It is still not enough to have each of the filters generate their own
13741 header pages (thereby being able to charge for them). If users wanted the
13742 option of suppressing the header pages with lpr -h, they will still get
13743 them and be charged for them since LPD does not pass any knowledge of the
13744 -h option to any of the filters.
13746 So, what are your options?
13750 * Accept LPD's paradigm and make header pages free.
13752 * Install an alternative to LPD, such as LPRng. Section Alternatives to
13753 the Standard Spooler tells more about other spooling software you can
13754 substitute for LPD.
13756 * Write a smart output filter. Normally, an output filter is not meant
13757 to do anything more than initialize a printer or do some simple
13758 character conversion. It is suited for header pages and plain text
13759 jobs (when there is no text (input) filter). But, if there is a text
13760 filter for the plain text jobs, then LPD will start the output filter
13761 only for the header pages. And the output filter can parse the header
13762 page text that LPD generates to determine what user and host to charge
13763 for the header page. The only other problem with this method is that
13764 the output filter still does not know what accounting file to use (it
13765 is not passed the name of the file from the af capability), but if you
13766 have a well-known accounting file, you can hard-code that into the
13767 output filter. To facilitate the parsing step, use the sh (short
13768 header) capability in /etc/printcap. Then again, all that might be too
13769 much trouble, and users will certainly appreciate the more generous
13770 system administrator who makes header pages free.
13772 ----------------------------------------------------------------------
13774 11.4.2.4 Header Pages on PostScript Printers
13776 As described above, LPD can generate a plain text header page suitable for
13777 many printers. Of course, PostScript cannot directly print plain text, so
13778 the header page feature of LPD is useless--or mostly so.
13780 One obvious way to get header pages is to have every conversion filter and
13781 the text filter generate the header page. The filters should use the user
13782 and host arguments to generate a suitable header page. The drawback of
13783 this method is that users will always get a header page, even if they
13784 submit jobs with lpr -h.
13786 Let us explore this method. The following script takes three arguments
13787 (user login name, host name, and job name) and makes a simple PostScript
13792 # make-ps-header - make a PostScript header page on stdout
13793 # Installed in /usr/local/libexec/make-ps-header
13797 # These are PostScript units (72 to the inch). Modify for A4 or
13798 # whatever size paper you are using:
13807 if [ $# -ne 3 ]; then
13808 echo "Usage: `basename $0` <user> <host> <job>" 1>&2
13813 # Save these, mostly for readability in the PostScript, below.
13821 # Send the PostScript code to stdout.
13827 % Make sure we do not interfere with user's job that will follow
13832 % Make a thick, unpleasant border around the edge of the paper.
13834 $border $border moveto
13835 $page_width $border 2 mul sub 0 rlineto
13836 0 $page_height $border 2 mul sub rlineto
13837 currentscreen 3 -1 roll pop 100 3 1 roll setscreen
13838 $border 2 mul $page_width sub 0 rlineto closepath
13839 0.8 setgray 10 setlinewidth stroke 0 setgray
13842 % Display user's login name, nice and large and prominent
13844 /Helvetica-Bold findfont 64 scalefont setfont
13845 $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
13849 % Now show the boring particulars
13851 /Helvetica findfont 14 scalefont setfont
13853 [ (Job:) (Host:) (Date:) ] {
13854 200 y moveto show /y y 18 sub def }
13857 /Helvetica-Bold findfont 14 scalefont setfont
13859 [ ($job) ($host) ($date) ] {
13860 270 y moveto show /y y 18 sub def
13870 Now, each of the conversion filters and the text filter can call this
13871 script to first generate the header page, and then print the user's job.
13872 Here is the DVI conversion filter from earlier in this document, modified
13873 to make a header page:
13877 # psdf - DVI to PostScript printer filter
13878 # Installed in /usr/local/libexec/psdf
13880 # Invoked by lpd when user runs lpr -d
13890 while getopts "x:y:n:h:" option; do
13893 n) login=$OPTARG ;;
13895 *) echo "LPD started `basename $0` wrong." 1>&2
13901 [ "$login" ] || fail "No login name"
13902 [ "$host" ] || fail "No host name"
13904 ( /usr/local/libexec/make-ps-header $login $host "DVI File"
13905 /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args
13907 Notice how the filter has to parse the argument list in order to determine
13908 the user and host name. The parsing for the other conversion filters is
13909 identical. The text filter takes a slightly different set of arguments,
13910 though (see section How Filters Work).
13912 As we have mentioned before, the above scheme, though fairly simple,
13913 disables the ``suppress header page'' option (the -h option) to lpr. If
13914 users wanted to save a tree (or a few pennies, if you charge for header
13915 pages), they would not be able to do so, since every filter's going to
13916 print a header page with every job.
13918 To allow users to shut off header pages on a per-job basis, you will need
13919 to use the trick introduced in section Accounting for Header Pages: write
13920 an output filter that parses the LPD-generated header page and produces a
13921 PostScript version. If the user submits the job with lpr -h, then LPD will
13922 not generate a header page, and neither will your output filter.
13923 Otherwise, your output filter will read the text from LPD and send the
13924 appropriate header page PostScript code to the printer.
13926 If you have a PostScript printer on a serial line, you can make use of
13927 lprps, which comes with an output filter, psof, which does the above. Note
13928 that psof does not charge for header pages.
13930 ----------------------------------------------------------------------
13932 11.4.3 Networked Printing
13934 DragonFly supports networked printing: sending jobs to remote printers.
13935 Networked printing generally refers to two different things:
13937 * Accessing a printer attached to a remote host. You install a printer
13938 that has a conventional serial or parallel interface on one host.
13939 Then, you set up LPD to enable access to the printer from other hosts
13940 on the network. Section Printers Installed on Remote Hosts tells how
13943 * Accessing a printer attached directly to a network. The printer has a
13944 network interface in addition (or in place of) a more conventional
13945 serial or parallel interface. Such a printer might work as follows:
13947 * It might understand the LPD protocol and can even queue jobs from
13948 remote hosts. In this case, it acts just like a regular host
13949 running LPD. Follow the same procedure in section Printers
13950 Installed on Remote Hosts to set up such a printer.
13952 * It might support a data stream network connection. In this case,
13953 you ``attach'' the printer to one host on the network by making
13954 that host responsible for spooling jobs and sending them to the
13955 printer. Section Printers with Networked Data Stream Interfaces
13956 gives some suggestions on installing such printers.
13958 ----------------------------------------------------------------------
13960 11.4.3.1 Printers Installed on Remote Hosts
13962 The LPD spooling system has built-in support for sending jobs to other
13963 hosts also running LPD (or are compatible with LPD). This feature enables
13964 you to install a printer on one host and make it accessible from other
13965 hosts. It also works with printers that have network interfaces that
13966 understand the LPD protocol.
13968 To enable this kind of remote printing, first install a printer on one
13969 host, the printer host, using the simple printer setup described in the
13970 Simple Printer Setup section. Do any advanced setup in Advanced Printer
13971 Setup that you need. Make sure to test the printer and see if it works
13972 with the features of LPD you have enabled. Also ensure that the local host
13973 has authorization to use the LPD service in the remote host (see
13974 Restricting Jobs from Remote Printers).
13976 If you are using a printer with a network interface that is compatible
13977 with LPD, then the printer host in the discussion below is the printer
13978 itself, and the printer name is the name you configured for the printer.
13979 See the documentation that accompanied your printer and/or printer-network
13982 Tip: If you are using a Hewlett Packard Laserjet then the printer name
13983 text will automatically perform the LF to CRLF conversion for you, so
13984 you will not require the hpif script.
13986 Then, on the other hosts you want to have access to the printer, make an
13987 entry in their /etc/printcap files with the following:
13989 1. Name the entry anything you want. For simplicity, though, you probably
13990 want to use the same name and aliases as on the printer host.
13992 2. Leave the lp capability blank, explicitly (:lp=:).
13994 3. Make a spooling directory and specify its location in the sd
13995 capability. LPD will store jobs here before they get sent to the
13998 4. Place the name of the printer host in the rm capability.
14000 5. Place the printer name on the printer host in the rp capability.
14002 That is it. You do not need to list conversion filters, page dimensions,
14003 or anything else in the /etc/printcap file.
14005 Here is an example. The host rose has two printers, bamboo and rattan. We
14006 will enable users on the host orchid to print to those printers. Here is
14007 the /etc/printcap file for orchid (back from section Enabling Header
14008 Pages). It already had the entry for the printer teak; we have added
14009 entries for the two printers on the host rose:
14012 # /etc/printcap for host orchid - added (remote) printers on rose
14016 # teak is local; it is connected directly to orchid:
14018 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
14019 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
14020 :if=/usr/local/libexec/ifhp:\
14021 :vf=/usr/local/libexec/vfhp:\
14022 :of=/usr/local/libexec/ofhp:
14025 # rattan is connected to rose; send jobs for rattan to rose:
14027 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14028 :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
14031 # bamboo is connected to rose as well:
14033 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14034 :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:
14036 Then, we just need to make spooling directories on orchid:
14038 # mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo
14039 # chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo
14040 # chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo
14042 Now, users on orchid can print to rattan and bamboo. If, for example, a
14043 user on orchid typed
14045 % lpr -P bamboo -d sushi-review.dvi
14047 the LPD system on orchid would copy the job to the spooling directory
14048 /var/spool/lpd/bamboo and note that it was a DVI job. As soon as the host
14049 rose has room in its bamboo spooling directory, the two LPDs would
14050 transfer the file to rose. The file would wait in rose's queue until it
14051 was finally printed. It would be converted from DVI to PostScript (since
14052 bamboo is a PostScript printer) on rose.
14054 ----------------------------------------------------------------------
14056 11.4.3.2 Printers with Networked Data Stream Interfaces
14058 Often, when you buy a network interface card for a printer, you can get
14059 two versions: one which emulates a spooler (the more expensive version),
14060 or one which just lets you send data to it as if you were using a serial
14061 or parallel port (the cheaper version). This section tells how to use the
14062 cheaper version. For the more expensive one, see the previous section
14063 Printers Installed on Remote Hosts.
14065 The format of the /etc/printcap file lets you specify what serial or
14066 parallel interface to use, and (if you are using a serial interface), what
14067 baud rate, whether to use flow control, delays for tabs, conversion of
14068 newlines, and more. But there is no way to specify a connection to a
14069 printer that is listening on a TCP/IP or other network port.
14071 To send data to a networked printer, you need to develop a communications
14072 program that can be called by the text and conversion filters. Here is one
14073 such example: the script netprint takes all data on standard input and
14074 sends it to a network-attached printer. We specify the hostname of the
14075 printer as the first argument and the port number to which to connect as
14076 the second argument to netprint. Note that this supports one-way
14077 communication only (DragonFly to printer); many network printers support
14078 two-way communication, and you might want to take advantage of that (to
14079 get printer status, perform accounting, etc.).
14083 # netprint - Text filter for printer attached to network
14084 # Installed in /usr/local/libexec/netprint
14086 $#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>";
14088 $printer_host = $ARGV[0];
14089 $printer_port = $ARGV[1];
14091 require 'sys/socket.ph';
14093 ($ignore, $ignore, $protocol) = getprotobyname('tcp');
14094 ($ignore, $ignore, $ignore, $ignore, $address)
14095 = gethostbyname($printer_host);
14097 $sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);
14099 socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
14100 || die "Can't create TCP/IP stream socket: $!";
14101 connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
14102 while (<STDIN>) { print PRINTER; }
14105 We can then use this script in various filters. Suppose we had a Diablo
14106 750-N line printer connected to the network. The printer accepts data to
14107 print on port number 5100. The host name of the printer is scrivener. Here
14108 is the text filter for the printer:
14112 # diablo-if-net - Text filter for Diablo printer `scrivener' listening
14113 # on port 5100. Installed in /usr/local/libexec/diablo-if-net
14115 exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100
14117 ----------------------------------------------------------------------
14119 11.4.4 Restricting Printer Usage
14121 This section gives information on restricting printer usage. The LPD
14122 system lets you control who can access a printer, both locally or
14123 remotely, whether they can print multiple copies, how large their jobs can
14124 be, and how large the printer queues can get.
14126 ----------------------------------------------------------------------
14128 11.4.4.1 Restricting Multiple Copies
14130 The LPD system makes it easy for users to print multiple copies of a file.
14131 Users can print jobs with lpr -#5 (for example) and get five copies of
14132 each file in the job. Whether this is a good thing is up to you.
14134 If you feel multiple copies cause unnecessary wear and tear on your
14135 printers, you can disable the -# option to lpr(1) by adding the sc
14136 capability to the /etc/printcap file. When users submit jobs with the -#
14137 option, they will see:
14139 lpr: multiple copies are not allowed
14141 Note that if you have set up access to a printer remotely (see section
14142 Printers Installed on Remote Hosts), you need the sc capability on the
14143 remote /etc/printcap files as well, or else users will still be able to
14144 submit multiple-copy jobs by using another host.
14146 Here is an example. This is the /etc/printcap file for the host rose. The
14147 printer rattan is quite hearty, so we will allow multiple copies, but the
14148 laser printer bamboo is a bit more delicate, so we will disable multiple
14149 copies by adding the sc capability:
14152 # /etc/printcap for host rose - restrict multiple copies on bamboo
14154 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14155 :sh:sd=/var/spool/lpd/rattan:\
14157 :if=/usr/local/libexec/if-simple:
14159 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14160 :sh:sd=/var/spool/lpd/bamboo:sc:\
14161 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14162 :if=/usr/local/libexec/psif:\
14163 :df=/usr/local/libexec/psdf:
14165 Now, we also need to add the sc capability on the host orchid's
14166 /etc/printcap (and while we are at it, let us disable multiple copies for
14170 # /etc/printcap for host orchid - no multiple copies for local
14171 # printer teak or remote printer bamboo
14172 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
14173 :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\
14174 :if=/usr/local/libexec/ifhp:\
14175 :vf=/usr/local/libexec/vfhp:\
14176 :of=/usr/local/libexec/ofhp:
14178 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14179 :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
14181 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14182 :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:
14184 By using the sc capability, we prevent the use of lpr -#, but that still
14185 does not prevent users from running lpr(1) multiple times, or from
14186 submitting the same file multiple times in one job like this:
14188 % lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign
14190 There are many ways to prevent this abuse (including ignoring it) which
14191 you are free to explore.
14193 ----------------------------------------------------------------------
14195 11.4.4.2 Restricting Access to Printers
14197 You can control who can print to what printers by using the UNIX group
14198 mechanism and the rg capability in /etc/printcap. Just place the users you
14199 want to have access to a printer in a certain group, and then name that
14200 group in the rg capability.
14202 Users outside the group (including root) will be greeted with ``lpr: Not a
14203 member of the restricted group'' if they try to print to the controlled
14206 As with the sc (suppress multiple copies) capability, you need to specify
14207 rg on remote hosts that also have access to your printers, if you feel it
14208 is appropriate (see section Printers Installed on Remote Hosts).
14210 For example, we will let anyone access the printer rattan, but only those
14211 in group artists can use bamboo. Here is the familiar /etc/printcap for
14215 # /etc/printcap for host rose - restricted group for bamboo
14217 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14218 :sh:sd=/var/spool/lpd/rattan:\
14220 :if=/usr/local/libexec/if-simple:
14222 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14223 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\
14224 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14225 :if=/usr/local/libexec/psif:\
14226 :df=/usr/local/libexec/psdf:
14228 Let us leave the other example /etc/printcap file (for the host orchid)
14229 alone. Of course, anyone on orchid can print to bamboo. It might be the
14230 case that we only allow certain logins on orchid anyway, and want them to
14231 have access to the printer. Or not.
14233 Note: There can be only one restricted group per printer.
14235 ----------------------------------------------------------------------
14237 11.4.4.3 Controlling Sizes of Jobs Submitted
14239 If you have many users accessing the printers, you probably need to put an
14240 upper limit on the sizes of the files users can submit to print. After
14241 all, there is only so much free space on the filesystem that houses the
14242 spooling directories, and you also need to make sure there is room for the
14243 jobs of other users.
14245 LPD enables you to limit the maximum byte size a file in a job can be with
14246 the mx capability. The units are in BUFSIZ blocks, which are 1024 bytes.
14247 If you put a zero for this capability, there will be no limit on file
14248 size; however, if no mx capability is specified, then a default limit of
14249 1000 blocks will be used.
14251 Note: The limit applies to files in a job, and not the total job size.
14253 LPD will not refuse a file that is larger than the limit you place on a
14254 printer. Instead, it will queue as much of the file up to the limit, which
14255 will then get printed. The rest will be discarded. Whether this is correct
14256 behavior is up for debate.
14258 Let us add limits to our example printers rattan and bamboo. Since those
14259 artists' PostScript files tend to be large, we will limit them to five
14260 megabytes. We will put no limit on the plain text line printer:
14263 # /etc/printcap for host rose
14267 # No limit on job size:
14269 rattan|line|diablo|lp|Diablo 630 Line Printer:\
14270 :sh:mx#0:sd=/var/spool/lpd/rattan:\
14272 :if=/usr/local/libexec/if-simple:
14275 # Limit of five megabytes:
14277 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14278 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
14279 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\
14280 :if=/usr/local/libexec/psif:\
14281 :df=/usr/local/libexec/psdf:
14283 Again, the limits apply to the local users only. If you have set up access
14284 to your printers remotely, remote users will not get those limits. You
14285 will need to specify the mx capability in the remote /etc/printcap files
14286 as well. See section Printers Installed on Remote Hosts for more
14287 information on remote printing.
14289 There is another specialized way to limit job sizes from remote printers;
14290 see section Restricting Jobs from Remote Printers.
14292 ----------------------------------------------------------------------
14294 11.4.4.4 Restricting Jobs from Remote Printers
14296 The LPD spooling system provides several ways to restrict print jobs
14297 submitted from remote hosts:
14301 You can control from which remote hosts a local LPD accepts
14302 requests with the files /etc/hosts.equiv and /etc/hosts.lpd. LPD
14303 checks to see if an incoming request is from a host listed in
14304 either one of these files. If not, LPD refuses the request.
14306 The format of these files is simple: one host name per line. Note
14307 that the file /etc/hosts.equiv is also used by the ruserok(3)
14308 protocol, and affects programs like rsh(1) and rcp(1), so be
14311 For example, here is the /etc/hosts.lpd file on the host rose:
14315 madrigal.fishbaum.de
14317 This means rose will accept requests from the hosts orchid,
14318 violet, and madrigal.fishbaum.de. If any other host tries to
14319 access rose's LPD, the job will be refused.
14323 You can control how much free space there needs to remain on the
14324 filesystem where a spooling directory resides. Make a file called
14325 minfree in the spooling directory for the local printer. Insert in
14326 that file a number representing how many disk blocks (512 bytes)
14327 of free space there has to be for a remote job to be accepted.
14329 This lets you insure that remote users will not fill your
14330 filesystem. You can also use it to give a certain priority to
14331 local users: they will be able to queue jobs long after the free
14332 disk space has fallen below the amount specified in the minfree
14335 For example, let us add a minfree file for the printer bamboo. We
14336 examine /etc/printcap to find the spooling directory for this
14337 printer; here is bamboo's entry:
14339 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
14340 :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
14341 :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\
14342 :if=/usr/local/libexec/psif:\
14343 :df=/usr/local/libexec/psdf:
14345 The spooling directory is given in the sd capability. We will make
14346 three megabytes (which is 6144 disk blocks) the amount of free
14347 disk space that must exist on the filesystem for LPD to accept
14350 # echo 6144 > /var/spool/lpd/bamboo/minfree
14355 You can control which remote users can print to local printers by
14356 specifying the rs capability in /etc/printcap. When rs appears in
14357 the entry for a locally-attached printer, LPD will accept jobs
14358 from remote hosts if the user submitting the job also has an
14359 account of the same login name on the local host. Otherwise, LPD
14362 This capability is particularly useful in an environment where
14363 there are (for example) different departments sharing a network,
14364 and some users transcend departmental boundaries. By giving them
14365 accounts on your systems, they can use your printers from their
14366 own departmental systems. If you would rather allow them to use
14367 only your printers and not your computer resources, you can give
14368 them ``token'' accounts, with no home directory and a useless
14369 shell like /usr/bin/false.
14371 ----------------------------------------------------------------------
14373 11.4.5 Accounting for Printer Usage
14375 So, you need to charge for printouts. And why not? Paper and ink cost
14376 money. And then there are maintenance costs--printers are loaded with
14377 moving parts and tend to break down. You have examined your printers,
14378 usage patterns, and maintenance fees and have come up with a per-page (or
14379 per-foot, per-meter, or per-whatever) cost. Now, how do you actually start
14380 accounting for printouts?
14382 Well, the bad news is the LPD spooling system does not provide much help
14383 in this department. Accounting is highly dependent on the kind of printer
14384 in use, the formats being printed, and your requirements in charging for
14387 To implement accounting, you have to modify a printer's text filter (to
14388 charge for plain text jobs) and the conversion filters (to charge for
14389 other file formats), to count pages or query the printer for pages
14390 printed. You cannot get away with using the simple output filter, since it
14391 cannot do accounting. See section Filters.
14393 Generally, there are two ways to do accounting:
14395 * Periodic accounting is the more common way, possibly because it is
14396 easier. Whenever someone prints a job, the filter logs the user, host,
14397 and number of pages to an accounting file. Every month, semester,
14398 year, or whatever time period you prefer, you collect the accounting
14399 files for the various printers, tally up the pages printed by users,
14400 and charge for usage. Then you truncate all the logging files,
14401 starting with a clean slate for the next period.
14403 * Timely accounting is less common, probably because it is more
14404 difficult. This method has the filters charge users for printouts as
14405 soon as they use the printers. Like disk quotas, the accounting is
14406 immediate. You can prevent users from printing when their account goes
14407 in the red, and might provide a way for users to check and adjust
14408 their ``print quotas.'' But this method requires some database code to
14409 track users and their quotas.
14411 The LPD spooling system supports both methods easily: since you have to
14412 provide the filters (well, most of the time), you also have to provide the
14413 accounting code. But there is a bright side: you have enormous flexibility
14414 in your accounting methods. For example, you choose whether to use
14415 periodic or timely accounting. You choose what information to log: user
14416 names, host names, job types, pages printed, square footage of paper used,
14417 how long the job took to print, and so forth. And you do so by modifying
14418 the filters to save this information.
14420 ----------------------------------------------------------------------
14422 11.4.5.1 Quick and Dirty Printer Accounting
14424 DragonFly comes with two programs that can get you set up with simple
14425 periodic accounting right away. They are the text filter lpf, described in
14426 section lpf: a Text Filter, and pac(8), a program to gather and total
14427 entries from printer accounting files.
14429 As mentioned in the section on filters (Filters), LPD starts the text and
14430 the conversion filters with the name of the accounting file to use on the
14431 filter command line. The filters can use this argument to know where to
14432 write an accounting file entry. The name of this file comes from the af
14433 capability in /etc/printcap, and if not specified as an absolute path, is
14434 relative to the spooling directory.
14436 LPD starts lpf with page width and length arguments (from the pw and pl
14437 capabilities). lpf uses these arguments to determine how much paper will
14438 be used. After sending the file to the printer, it then writes an
14439 accounting entry in the accounting file. The entries look like this:
14447 You should use a separate accounting file for each printer, as lpf has no
14448 file locking logic built into it, and two lpfs might corrupt each other's
14449 entries if they were to write to the same file at the same time. An easy
14450 way to insure a separate accounting file for each printer is to use
14451 af=acct in /etc/printcap. Then, each accounting file will be in the
14452 spooling directory for a printer, in a file named acct.
14454 When you are ready to charge users for printouts, run the pac(8) program.
14455 Just change to the spooling directory for the printer you want to collect
14456 on and type pac. You will get a dollar-centric summary like the following:
14458 Login pages/feet runs price
14459 orchid:kelly 5.00 1 $ 0.10
14460 orchid:mary 31.00 3 $ 0.62
14461 orchid:zhang 9.00 1 $ 0.18
14462 rose:andy 2.00 1 $ 0.04
14463 rose:kelly 177.00 104 $ 3.54
14464 rose:mary 87.00 32 $ 1.74
14465 rose:root 26.00 12 $ 0.52
14467 total 337.00 154 $ 6.74
14469 These are the arguments pac(8) expects:
14473 Which printer to summarize. This option works only if there is an
14474 absolute path in the af capability in /etc/printcap.
14478 Sort the output by cost instead of alphabetically by user name.
14482 Ignore host name in the accounting files. With this option, user
14483 smith on host alpha is the same user smith on host gamma. Without,
14484 they are different users.
14488 Compute charges with price dollars per page or per foot instead of
14489 the price from the pc capability in /etc/printcap, or two cents
14490 (the default). You can specify price as a floating point number.
14494 Reverse the sort order.
14498 Make an accounting summary file and truncate the accounting file.
14502 Print accounting information for the given user names only.
14504 In the default summary that pac(8) produces, you see the number of pages
14505 printed by each user from various hosts. If, at your site, host does not
14506 matter (because users can use any host), run pac -m, to produce the
14509 Login pages/feet runs price
14511 kelly 182.00 105 $ 3.64
14512 mary 118.00 35 $ 2.36
14513 root 26.00 12 $ 0.52
14514 zhang 9.00 1 $ 0.18
14516 total 337.00 154 $ 6.74
14518 To compute the dollar amount due, pac(8) uses the pc capability in the
14519 /etc/printcap file (default of 200, or 2 cents per page). Specify, in
14520 hundredths of cents, the price per page or per foot you want to charge for
14521 printouts in this capability. You can override this value when you run
14522 pac(8) with the -p option. The units for the -p option are in dollars,
14523 though, not hundredths of cents. For example,
14527 makes each page cost one dollar and fifty cents. You can really rake in
14528 the profits by using this option.
14530 Finally, running pac -s will save the summary information in a summary
14531 accounting file, which is named the same as the printer's accounting file,
14532 but with _sum appended to the name. It then truncates the accounting file.
14533 When you run pac(8) again, it rereads the summary file to get starting
14534 totals, then adds information from the regular accounting file.
14536 ----------------------------------------------------------------------
14538 11.4.5.2 How Can You Count Pages Printed?
14540 In order to perform even remotely accurate accounting, you need to be able
14541 to determine how much paper a job uses. This is the essential problem of
14542 printer accounting.
14544 For plain text jobs, the problem is not that hard to solve: you count how
14545 many lines are in a job and compare it to how many lines per page your
14546 printer supports. Do not forget to take into account backspaces in the
14547 file which overprint lines, or long logical lines that wrap onto one or
14548 more additional physical lines.
14550 The text filter lpf (introduced in lpf: a Text Filter) takes into account
14551 these things when it does accounting. If you are writing a text filter
14552 which needs to do accounting, you might want to examine lpf's source code.
14554 How do you handle other file formats, though?
14556 Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you can have
14557 your filter parse the diagnostic output of dvilj or dvips and look to see
14558 how many pages were converted. You might be able to do similar things with
14559 other file formats and conversion programs.
14561 But these methods suffer from the fact that the printer may not actually
14562 print all those pages. For example, it could jam, run out of toner, or
14563 explode--and the user would still get charged.
14565 So, what can you do?
14567 There is only one sure way to do accurate accounting. Get a printer that
14568 can tell you how much paper it uses, and attach it via a serial line or a
14569 network connection. Nearly all PostScript printers support this notion.
14570 Other makes and models do as well (networked Imagen laser printers, for
14571 example). Modify the filters for these printers to get the page usage
14572 after they print each job and have them log accounting information based
14573 on that value only. There is no line counting nor error-prone file
14574 examination required.
14576 Of course, you can always be generous and make all printouts free.
14578 ----------------------------------------------------------------------
14580 11.5 Using Printers
14582 This section tells you how to use printers you have set up with DragonFly.
14583 Here is an overview of the user-level commands:
14591 Check printer queues
14595 Remove jobs from a printer's queue
14597 There is also an administrative command, lpc(8), described in the section
14598 Administering the LPD Spooler, used to control printers and their queues.
14600 All three of the commands lpr(1), lprm(1), and lpq(1) accept an option -P
14601 printer-name to specify on which printer/queue to operate, as listed in
14602 the /etc/printcap file. This enables you to submit, remove, and check on
14603 jobs for various printers. If you do not use the -P option, then these
14604 commands use the printer specified in the PRINTER environment variable.
14605 Finally, if you do not have a PRINTER environment variable, these commands
14606 default to the printer named lp.
14608 Hereafter, the terminology default printer means the printer named in the
14609 PRINTER environment variable, or the printer named lp when there is no
14610 PRINTER environment variable.
14612 ----------------------------------------------------------------------
14614 11.5.1 Printing Jobs
14616 To print files, type:
14620 This prints each of the listed files to the default printer. If you list
14621 no files, lpr(1) reads data to print from standard input. For example,
14622 this command prints some important system files:
14624 % lpr /etc/host.conf /etc/hosts.equiv
14626 To select a specific printer, type:
14628 % lpr -P printer-name filename ...
14630 This example prints a long listing of the current directory to the printer
14633 % ls -l | lpr -P rattan
14635 Because no files were listed for the lpr(1) command, lpr read the data to
14636 print from standard input, which was the output of the ls -l command.
14638 The lpr(1) command can also accept a wide variety of options to control
14639 formatting, apply file conversions, generate multiple copies, and so
14640 forth. For more information, see the section Printing Options.
14642 ----------------------------------------------------------------------
14644 11.5.2 Checking Jobs
14646 When you print with lpr(1), the data you wish to print is put together in
14647 a package called a ``print job'', which is sent to the LPD spooling
14648 system. Each printer has a queue of jobs, and your job waits in that queue
14649 along with other jobs from yourself and from other users. The printer
14650 prints those jobs in a first-come, first-served order.
14652 To display the queue for the default printer, type lpq(1). For a specific
14653 printer, use the -P option. For example, the command
14657 shows the queue for the printer named bamboo. Here is an example of the
14658 output of the lpq command:
14660 bamboo is ready and printing
14661 Rank Owner Job Files Total Size
14662 active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes
14663 2nd kelly 10 (standard input) 1635 bytes
14664 3rd mary 11 ... 78519 bytes
14666 This shows three jobs in the queue for bamboo. The first job, submitted by
14667 user kelly, got assigned ``job number'' 9. Every job for a printer gets a
14668 unique job number. Most of the time you can ignore the job number, but you
14669 will need it if you want to cancel the job; see section Removing Jobs for
14672 Job number nine consists of two files; multiple files given on the lpr(1)
14673 command line are treated as part of a single job. It is the currently
14674 active job (note the word active under the ``Rank'' column), which means
14675 the printer should be currently printing that job. The second job consists
14676 of data passed as the standard input to the lpr(1) command. The third job
14677 came from user mary; it is a much larger job. The pathname of the file she
14678 is trying to print is too long to fit, so the lpq(1) command just shows
14681 The very first line of the output from lpq(1) is also useful: it tells
14682 what the printer is currently doing (or at least what LPD thinks the
14685 The lpq(1) command also support a -l option to generate a detailed long
14686 listing. Here is an example of lpq -l:
14688 waiting for bamboo to become ready (offline ?)
14689 kelly: 1st [job 009rose]
14690 /etc/host.conf 73 bytes
14691 /etc/hosts.equiv 15 bytes
14693 kelly: 2nd [job 010rose]
14694 (standard input) 1635 bytes
14696 mary: 3rd [job 011rose]
14697 /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes
14699 ----------------------------------------------------------------------
14701 11.5.3 Removing Jobs
14703 If you change your mind about printing a job, you can remove the job from
14704 the queue with the lprm(1) command. Often, you can even use lprm(1) to
14705 remove an active job, but some or all of the job might still get printed.
14707 To remove a job from the default printer, first use lpq(1) to find the job
14712 To remove the job from a specific printer, add the -P option. The
14713 following command removes job number 10 from the queue for the printer
14716 % lprm -P bamboo 10
14718 The lprm(1) command has a few shortcuts:
14722 Removes all jobs (for the default printer) belonging to you.
14726 Removes all jobs (for the default printer) belonging to user. The
14727 superuser can remove other users' jobs; you can remove only your
14732 With no job number, user name, or - appearing on the command line,
14733 lprm(1) removes the currently active job on the default printer,
14734 if it belongs to you. The superuser can remove any active job.
14736 Just use the -P option with the above shortcuts to operate on a specific
14737 printer instead of the default. For example, the following command removes
14738 all jobs for the current user in the queue for the printer named rattan:
14742 Note: If you are working in a networked environment, lprm(1) will let
14743 you remove jobs only from the host from which the jobs were submitted,
14744 even if the same printer is available from other hosts. The following
14745 command sequence demonstrates this:
14747 % lpr -P rattan myfile
14750 Rank Owner Job Files Total Size
14751 active seeyan 12 ... 49123 bytes
14752 2nd kelly 13 myfile 12 bytes
14753 % lprm -P rattan 13
14754 rose: Permission denied
14756 % lprm -P rattan 13
14757 dfA013rose dequeued
14758 cfA013rose dequeued
14761 ----------------------------------------------------------------------
14763 11.5.4 Beyond Plain Text: Printing Options
14765 The lpr(1) command supports a number of options that control formatting
14766 text, converting graphic and other file formats, producing multiple
14767 copies, handling of the job, and more. This section describes the options.
14769 ----------------------------------------------------------------------
14771 11.5.4.1 Formatting and Conversion Options
14773 The following lpr(1) options control formatting of the files in the job.
14774 Use these options if the job does not contain plain text or if you want
14775 plain text formatted through the pr(1) utility.
14777 For example, the following command prints a DVI file (from the TeX
14778 typesetting system) named fish-report.dvi to the printer named bamboo:
14780 % lpr -P bamboo -d fish-report.dvi
14782 These options apply to every file in the job, so you cannot mix (say) DVI
14783 and ditroff files together in a job. Instead, submit the files as separate
14784 jobs, using a different conversion option for each job.
14786 Note: All of these options except -p and -T require conversion filters
14787 installed for the destination printer. For example, the -d option
14788 requires the DVI conversion filter. Section Conversion Filters gives
14793 Print cifplot files.
14801 Print FORTRAN text files.
14809 Indent the output by number columns; if you omit number, indent by
14810 8 columns. This option works only with certain conversion filters.
14812 Note: Do not put any space between the -i and the number.
14816 Print literal text data, including control characters.
14820 Print ditroff (device independent troff) data.
14824 Format plain text with pr(1) before printing. See pr(1) for more
14829 Use title on the pr(1) header instead of the file name. This
14830 option has effect only when used with the -p option.
14840 Here is an example: this command prints a nicely formatted version of the
14841 ls(1) manual page on the default printer:
14843 % zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t
14845 The zcat(1) command uncompresses the source of the ls(1) manual page and
14846 passes it to the troff(1) command, which formats that source and makes GNU
14847 troff output and passes it to lpr(1), which submits the job to the LPD
14848 spooler. Because we used the -t option to lpr(1), the spooler will convert
14849 the GNU troff output into a format the default printer can understand when
14852 ----------------------------------------------------------------------
14854 11.5.4.2 Job Handling Options
14856 The following options to lpr(1) tell LPD to handle the job specially:
14860 Produce a number of copies of each file in the job instead of just
14861 one copy. An administrator may disable this option to reduce
14862 printer wear-and-tear and encourage photocopier usage. See section
14863 Restricting Multiple Copies.
14865 This example prints three copies of parser.c followed by three
14866 copies of parser.h to the default printer:
14868 % lpr -#3 parser.c parser.h
14872 Send mail after completing the print job. With this option, the
14873 LPD system will send mail to your account when it finishes
14874 handling your job. In its message, it will tell you if the job
14875 completed successfully or if there was an error, and (often) what
14880 Do not copy the files to the spooling directory, but make symbolic
14881 links to them instead.
14883 If you are printing a large job, you probably want to use this
14884 option. It saves space in the spooling directory (your job might
14885 overflow the free space on the filesystem where the spooling
14886 directory resides). It saves time as well since LPD will not have
14887 to copy each and every byte of your job to the spooling directory.
14889 There is a drawback, though: since LPD will refer to the original
14890 files directly, you cannot modify or remove them until they have
14893 Note: If you are printing to a remote printer, LPD will
14894 eventually have to copy files from the local host to the remote
14895 host, so the -s option will save space only on the local
14896 spooling directory, not the remote. It is still useful, though.
14900 Remove the files in the job after copying them to the spooling
14901 directory, or after printing them with the -s option. Be careful
14904 ----------------------------------------------------------------------
14906 11.5.4.3 Header Page Options
14908 These options to lpr(1) adjust the text that normally appears on a job's
14909 header page. If header pages are suppressed for the destination printer,
14910 these options have no effect. See section Header Pages for information
14911 about setting up header pages.
14915 Replace the hostname on the header page with text. The hostname is
14916 normally the name of the host from which the job was submitted.
14920 Replace the job name on the header page with text. The job name is
14921 normally the name of the first file of the job, or stdin if you
14922 are printing standard input.
14926 Do not print any header page.
14928 Note: At some sites, this option may have no effect due to the
14929 way header pages are generated. See Header Pages for details.
14931 ----------------------------------------------------------------------
14933 11.5.5 Administering Printers
14935 As an administrator for your printers, you have had to install, set up,
14936 and test them. Using the lpc(8) command, you can interact with your
14937 printers in yet more ways. With lpc(8), you can
14939 * Start and stop the printers
14941 * Enable and disable their queues
14943 * Rearrange the order of the jobs in each queue.
14945 First, a note about terminology: if a printer is stopped, it will not
14946 print anything in its queue. Users can still submit jobs, which will wait
14947 in the queue until the printer is started or the queue is cleared.
14949 If a queue is disabled, no user (except root) can submit jobs for the
14950 printer. An enabled queue allows jobs to be submitted. A printer can be
14951 started for a disabled queue, in which case it will continue to print jobs
14952 in the queue until the queue is empty.
14954 In general, you have to have root privileges to use the lpc(8) command.
14955 Ordinary users can use the lpc(8) command to get printer status and to
14956 restart a hung printer only.
14958 Here is a summary of the lpc(8) commands. Most of the commands take a
14959 printer-name argument to tell on which printer to operate. You can use all
14960 for the printer-name to mean all printers listed in /etc/printcap.
14964 Cancel the current job and stop the printer. Users can still
14965 submit jobs if the queue is enabled.
14969 Remove old files from the printer's spooling directory.
14970 Occasionally, the files that make up a job are not properly
14971 removed by LPD, particularly if there have been errors during
14972 printing or a lot of administrative activity. This command finds
14973 files that do not belong in the spooling directory and removes
14976 disable printer-name
14978 Disable queuing of new jobs. If the printer is running, it will
14979 continue to print any jobs remaining in the queue. The superuser
14980 (root) can always submit jobs, even to a disabled queue.
14982 This command is useful while you are testing a new printer or
14983 filter installation: disable the queue and submit jobs as root.
14984 Other users will not be able to submit jobs until you complete
14985 your testing and re-enable the queue with the enable command.
14987 down printer-name message
14989 Take a printer down. Equivalent to disable followed by stop. The
14990 message appears as the printer's status whenever a user checks the
14991 printer's queue with lpq(1) or status with lpc status.
14993 enable printer-name
14995 Enable the queue for a printer. Users can submit jobs but the
14996 printer will not print anything until it is started.
15000 Print help on the command command-name. With no command-name,
15001 print a summary of the commands available.
15003 restart printer-name
15005 Start the printer. Ordinary users can use this command if some
15006 extraordinary circumstance hangs LPD, but they cannot start a
15007 printer stopped with either the stop or down commands. The restart
15008 command is equivalent to abort followed by start.
15012 Start the printer. The printer will print jobs in its queue.
15016 Stop the printer. The printer will finish the current job and will
15017 not print anything else in its queue. Even though the printer is
15018 stopped, users can still submit jobs to an enabled queue.
15020 topq printer-name job-or-username
15022 Rearrange the queue for printer-name by placing the jobs with the
15023 listed job numbers or the jobs belonging to username at the top of
15024 the queue. For this command, you cannot use all as the
15029 Bring a printer up; the opposite of the down command. Equivalent
15030 to start followed by enable.
15032 lpc(8) accepts the above commands on the command line. If you do not enter
15033 any commands, lpc(8) enters an interactive mode, where you can enter
15034 commands until you type exit, quit, or end-of-file.
15036 ----------------------------------------------------------------------
15038 11.6 Alternatives to the Standard Spooler
15040 If you have been reading straight through this manual, by now you have
15041 learned just about everything there is to know about the LPD spooling
15042 system that comes with DragonFly. You can probably appreciate many of its
15043 shortcomings, which naturally leads to the question: ``What other spooling
15044 systems are out there (and work with DragonFly)?''
15048 LPRng, which purportedly means ``LPR: the Next Generation'' is a
15049 complete rewrite of PLP. Patrick Powell and Justin Mason (the
15050 principal maintainer of PLP) collaborated to make LPRng. The main
15051 site for LPRng is http://www.lprng.org/.
15055 CUPS, the Common UNIX Printing System, provides a portable
15056 printing layer for UNIX-based operating systems. It has been
15057 developed by Easy Software Products to promote a standard printing
15058 solution for all UNIX vendors and users.
15060 CUPS uses the Internet Printing Protocol (IPP) as the basis for
15061 managing print jobs and queues. The Line Printer Daemon (LPD)
15062 Server Message Block (SMB), and AppSocket (a.k.a. JetDirect)
15063 protocols are also supported with reduced functionality. CUPS adds
15064 network printer browsing and PostScript Printer Description (PPD)
15065 based printing options to support real-world printing under UNIX.
15067 The main site for CUPS is http://www.cups.org/.
15069 ----------------------------------------------------------------------
15071 11.7 Troubleshooting
15073 After performing the simple test with lptest(1), you might have gotten one
15074 of the following results instead of the correct printout:
15076 It worked, after awhile; or, it did not eject a full sheet.
15078 The printer printed the above, but it sat for awhile and did
15079 nothing. In fact, you might have needed to press a PRINT REMAINING
15080 or FORM FEED button on the printer to get any results to appear.
15082 If this is the case, the printer was probably waiting to see if
15083 there was any more data for your job before it printed anything.
15084 To fix this problem, you can have the text filter send a FORM FEED
15085 character (or whatever is necessary) to the printer. This is
15086 usually sufficient to have the printer immediately print any text
15087 remaining in its internal buffer. It is also useful to make sure
15088 each print job ends on a full sheet, so the next job does not
15089 start somewhere on the middle of the last page of the previous
15092 The following replacement for the shell script
15093 /usr/local/libexec/if-simple prints a form feed after it sends the
15094 job to the printer:
15098 # if-simple - Simple text input filter for lpd
15099 # Installed in /usr/local/libexec/if-simple
15101 # Simply copies stdin to stdout. Ignores all filter arguments.
15102 # Writes a form feed character (\f) after printing job.
15104 /bin/cat && printf "\f" && exit 0
15107 It produced the ``staircase effect.''
15109 You got the following on paper:
15111 !"#$%&'()*+,-./01234
15112 "#$%&'()*+,-./012345
15113 #$%&'()*+,-./0123456
15115 You have become another victim of the staircase effect, caused by
15116 conflicting interpretations of what characters should indicate a
15117 new line. UNIX style operating systems use a single character:
15118 ASCII code 10, the line feed (LF). MS-DOS, OS/2(R), and others
15119 uses a pair of characters, ASCII code 10 and ASCII code 13 (the
15120 carriage return or CR). Many printers use the MS-DOS convention
15121 for representing new-lines.
15123 When you print with DragonFly, your text used just the line feed
15124 character. The printer, upon seeing a line feed character,
15125 advanced the paper one line, but maintained the same horizontal
15126 position on the page for the next character to print. That is what
15127 the carriage return is for: to move the location of the next
15128 character to print to the left edge of the paper.
15130 Here is what DragonFly wants your printer to do:
15132 Printer received CR Printer prints CR
15133 Printer received LF Printer prints CR + LF
15135 Here are some ways to achieve this:
15137 * Use the printer's configuration switches or control panel to
15138 alter its interpretation of these characters. Check your
15139 printer's manual to find out how to do this.
15141 Note: If you boot your system into other operating systems
15142 besides DragonFly, you may have to reconfigure the printer
15143 to use a an interpretation for CR and LF characters that
15144 those other operating systems use. You might prefer one of
15145 the other solutions, below.
15147 * Have DragonFly's serial line driver automatically convert LF
15148 to CR+LF. Of course, this works with printers on serial ports
15149 only. To enable this feature, use the ms# capability and set
15150 the onlcr mode in the /etc/printcap file for the printer.
15152 * Send an escape code to the printer to have it temporarily
15153 treat LF characters differently. Consult your printer's
15154 manual for escape codes that your printer might support. When
15155 you find the proper escape code, modify the text filter to
15156 send the code first, then send the print job.
15158 Here is an example text filter for printers that understand
15159 the Hewlett-Packard PCL escape codes. This filter makes the
15160 printer treat LF characters as a LF and CR; then it sends the
15161 job; then it sends a form feed to eject the last page of the
15162 job. It should work with nearly all Hewlett Packard printers.
15166 # hpif - Simple text input filter for lpd for HP-PCL based printers
15167 # Installed in /usr/local/libexec/hpif
15169 # Simply copies stdin to stdout. Ignores all filter arguments.
15170 # Tells printer to treat LF as CR+LF. Ejects the page when done.
15172 printf "\033&k2G" && cat && printf "\033&l0H" && exit 0
15175 Here is an example /etc/printcap from a host called orchid.
15176 It has a single printer attached to its first parallel port,
15177 a Hewlett Packard LaserJet 3Si named teak. It is using the
15178 above script as its text filter:
15181 # /etc/printcap for host orchid
15183 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
15184 :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
15185 :if=/usr/local/libexec/hpif:
15187 It overprinted each line.
15189 The printer never advanced a line. All of the lines of text were
15190 printed on top of each other on one line.
15192 This problem is the ``opposite'' of the staircase effect,
15193 described above, and is much rarer. Somewhere, the LF characters
15194 that DragonFly uses to end a line are being treated as CR
15195 characters to return the print location to the left edge of the
15196 paper, but not also down a line.
15198 Use the printer's configuration switches or control panel to
15199 enforce the following interpretation of LF and CR characters:
15201 Printer receives Printer prints
15205 The printer lost characters.
15207 While printing, the printer did not print a few characters in each
15208 line. The problem might have gotten worse as the printer ran,
15209 losing more and more characters.
15211 The problem is that the printer cannot keep up with the speed at
15212 which the computer sends data over a serial line (this problem
15213 should not occur with printers on parallel ports). There are two
15214 ways to overcome the problem:
15216 * If the printer supports XON/XOFF flow control, have DragonFly
15217 use it by specifying the ixon mode in the ms# capability.
15219 * If the printer supports carrier flow control, specify the
15220 crtscts mode in the ms# capability. Make sure the cable
15221 connecting the printer to the computer is correctly wired for
15222 carrier flow control.
15224 It printed garbage.
15226 The printer printed what appeared to be random garbage, but not
15229 This is usually another symptom of incorrect communications
15230 parameters with a serial printer. Double-check the bps rate in the
15231 br capability, and the parity setting in the ms# capability; make
15232 sure the printer is using the same settings as specified in the
15233 /etc/printcap file.
15237 If nothing happened, the problem is probably within DragonFly and
15238 not the hardware. Add the log file (lf) capability to the entry
15239 for the printer you are debugging in the /etc/printcap file. For
15240 example, here is the entry for rattan, with the lf capability:
15242 rattan|line|diablo|lp|Diablo 630 Line Printer:\
15243 :sh:sd=/var/spool/lpd/rattan:\
15245 :if=/usr/local/libexec/if-simple:\
15246 :lf=/var/log/rattan.log
15248 Then, try printing again. Check the log file (in our example,
15249 /var/log/rattan.log) to see any error messages that might appear.
15250 Based on the messages you see, try to correct the problem.
15252 If you do not specify a lf capability, LPD uses /dev/console as a
15255 ----------------------------------------------------------------------
15261 This chapter covers the use of disks in DragonFly. This includes
15262 memory-backed disks, network-attached disks, and standard SCSI/IDE storage
15265 After reading this chapter, you will know:
15267 * The terminology DragonFly uses to describe the organization of data on
15268 a physical disk (partitions and slices).
15270 * How to add additional hard disks to your system.
15272 * How to set up virtual file systems, such as memory disks.
15274 * How to use quotas to limit disk space usage.
15276 * How to encrypt disks to secure them against attackers.
15278 * How to create and burn CDs and DVDs on DragonFly.
15280 * The various storage media options for backups.
15282 * How to use backup programs available under DragonFly.
15284 * How to backup to floppy disks.
15286 * What snapshots are and how to use them efficiently.
15288 ----------------------------------------------------------------------
15292 The following is a list of physical storage devices supported in
15293 DragonFly, and the device names associated with them.
15295 Table 12-1. Physical Disk Naming Conventions
15297 +------------------------------------------------------------------------+
15298 | Drive type | Drive device name |
15299 |-----------------------------+------------------------------------------|
15300 | IDE hard drives | ad |
15301 |-----------------------------+------------------------------------------|
15302 | IDE CDROM drives | acd |
15303 |-----------------------------+------------------------------------------|
15304 | SCSI hard drives and USB | da |
15305 | Mass storage devices | |
15306 |-----------------------------+------------------------------------------|
15307 | SCSI CDROM drives | cd |
15308 |-----------------------------+------------------------------------------|
15309 | Assorted non-standard CDROM | mcd for Mitsumi CD-ROM, scd for Sony |
15310 | drives | CD-ROM, |
15311 |-----------------------------+------------------------------------------|
15312 | Floppy drives | fd |
15313 |-----------------------------+------------------------------------------|
15314 | SCSI tape drives | sa |
15315 |-----------------------------+------------------------------------------|
15316 | IDE tape drives | ast |
15317 |-----------------------------+------------------------------------------|
15318 | Flash drives | fla for DiskOnChip(R) Flash device |
15319 |-----------------------------+------------------------------------------|
15320 | | aacd for Adaptec(R) AdvancedRAID, mlxd |
15321 | RAID drives | and mlyd for Mylex(R), amrd for AMI |
15322 | | MegaRAID(R), idad for Compaq Smart RAID, |
15323 | | twed for 3ware(R) RAID. |
15324 +------------------------------------------------------------------------+
15326 ----------------------------------------------------------------------
15330 Originally contributed by David O'Brien.
15332 Lets say we want to add a new SCSI disk to a machine that currently only
15333 has a single drive. First turn off the computer and install the drive in
15334 the computer following the instructions of the computer, controller, and
15335 drive manufacturer. Due to the wide variations of procedures to do this,
15336 the details are beyond the scope of this document.
15338 Login as user root. After you have installed the drive, inspect
15339 /var/run/dmesg.boot to ensure the new disk was found. Continuing with our
15340 example, the newly added drive will be da1 and we want to mount it on /1
15341 (if you are adding an IDE drive, the device name will be ad1).
15343 Because DragonFly runs on IBM-PC compatible computers, it must take into
15344 account the PC BIOS partitions. These are different from the traditional
15345 BSD partitions. A PC disk has up to four BIOS partition entries. If the
15346 disk is going to be truly dedicated to DragonFly, you can use the
15347 dedicated mode. Otherwise, DragonFly will have to live within one of the
15348 PC BIOS partitions. DragonFly calls the PC BIOS partitions slices so as
15349 not to confuse them with traditional BSD partitions. You may also use
15350 slices on a disk that is dedicated to DragonFly, but used in a computer
15351 that also has another operating system installed. This is to not confuse
15352 the fdisk utility of the other operating system.
15354 In the slice case the drive will be added as /dev/da1s1e. This is read as:
15355 SCSI disk, unit number 1 (second SCSI disk), slice 1 (PC BIOS partition
15356 1), and e BSD partition. In the dedicated case, the drive will be added
15357 simply as /dev/da1e.
15359 ----------------------------------------------------------------------
15361 12.3.1 Using Command Line Utilities
15363 12.3.1.1 Using Slices
15365 This setup will allow your disk to work correctly with other operating
15366 systems that might be installed on your computer and will not confuse
15367 other operating systems' fdisk utilities. It is recommended to use this
15368 method for new disk installs. Only use dedicated mode if you have a good
15371 # dd if=/dev/zero of=/dev/da1 bs=1k count=1
15372 # fdisk -BI da1 #Initialize your new disk
15373 # disklabel -B -w -r da1s1 auto #Label it.
15374 # disklabel -e da1s1 # Edit the disklabel just created and add any partitions.
15376 # newfs /dev/da1s1e # Repeat this for every partition you created.
15377 # mount /dev/da1s1e /1 # Mount the partition(s)
15378 # vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab.
15380 If you have an IDE disk, substitute ad for da.
15382 ----------------------------------------------------------------------
15386 If you will not be sharing the new drive with another operating system,
15387 you may use the dedicated mode. Remember this mode can confuse Microsoft
15388 operating systems; however, no damage will be done by them. IBM's OS/2
15389 however, will ``appropriate'' any partition it finds which it does not
15392 # dd if=/dev/zero of=/dev/da1 bs=1k count=1
15393 # disklabel -Brw da1 auto
15394 # disklabel -e da1 # create the `e' partition
15395 # newfs -d0 /dev/da1e
15397 # vi /etc/fstab # add an entry for /dev/da1e
15400 An alternate method is:
15402 # dd if=/dev/zero of=/dev/da1 count=2
15403 # disklabel /dev/da1 | disklabel -BrR da1 /dev/stdin
15406 # vi /etc/fstab # add an entry for /dev/da1e
15409 ----------------------------------------------------------------------
15413 12.4.1 Software RAID
15415 12.4.1.1 Concatenated Disk Driver (CCD) Configuration
15417 Original work by Christopher Shumway. Revised by Jim Brown.
15419 When choosing a mass storage solution the most important factors to
15420 consider are speed, reliability, and cost. It is rare to have all three in
15421 balance; normally a fast, reliable mass storage device is expensive, and
15422 to cut back on cost either speed or reliability must be sacrificed.
15424 In designing the system described below, cost was chosen as the most
15425 important factor, followed by speed, then reliability. Data transfer speed
15426 for this system is ultimately constrained by the network. And while
15427 reliability is very important, the CCD drive described below serves online
15428 data that is already fully backed up on CD-R's and can easily be replaced.
15430 Defining your own requirements is the first step in choosing a mass
15431 storage solution. If your requirements prefer speed or reliability over
15432 cost, your solution will differ from the system described in this section.
15434 ----------------------------------------------------------------------
15436 12.4.1.1.1 Installing the Hardware
15438 In addition to the IDE system disk, three Western Digital 30GB, 5400 RPM
15439 IDE disks form the core of the CCD disk described below providing
15440 approximately 90GB of online storage. Ideally, each IDE disk would have
15441 its own IDE controller and cable, but to minimize cost, additional IDE
15442 controllers were not used. Instead the disks were configured with jumpers
15443 so that each IDE controller has one master, and one slave.
15445 Upon reboot, the system BIOS was configured to automatically detect the
15446 disks attached. More importantly, DragonFly detected them on reboot:
15448 ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33
15449 ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33
15450 ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33
15451 ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33
15453 Note: If DragonFly does not detect all the disks, ensure that you have
15454 jumpered them correctly. Most IDE drives also have a ``Cable Select''
15455 jumper. This is not the jumper for the master/slave relationship.
15456 Consult the drive documentation for help in identifying the correct
15459 Next, consider how to attach them as part of the file system. You should
15460 research both vinum(8) (Chapter 13) and ccd(4). In this particular
15461 configuration, ccd(4) was chosen.
15463 ----------------------------------------------------------------------
15465 12.4.1.1.2 Setting Up the CCD
15467 The driver ccd(4) allows you to take several identical disks and
15468 concatenate them into one logical file system. In order to use ccd(4), you
15469 need a kernel with ccd(4) support built in. Add this line to your kernel
15470 configuration file, rebuild, and reinstall the kernel:
15472 pseudo-device ccd 4
15474 The ccd(4) support can also be loaded as a kernel loadable module.
15476 To set up ccd(4), you must first use disklabel(8) to label the disks:
15478 disklabel -r -w ad1 auto
15479 disklabel -r -w ad2 auto
15480 disklabel -r -w ad3 auto
15482 This creates a disklabel for ad1c, ad2c and ad3c that spans the entire
15485 The next step is to change the disk label type. You can use disklabel(8)
15492 This opens up the current disk label on each disk with the editor
15493 specified by the EDITOR environment variable, typically vi(1).
15495 An unmodified disk label will look something like this:
15498 # size offset fstype [fsize bsize bps/cpg]
15499 c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
15501 Add a new e partition for ccd(4) to use. This can usually be copied from
15502 the c partition, but the fstype must be 4.2BSD. The disk label should now
15503 look something like this:
15506 # size offset fstype [fsize bsize bps/cpg]
15507 c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
15508 e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)
15510 ----------------------------------------------------------------------
15512 12.4.1.1.3 Building the File System
15514 The device node for ccd0c may not exist yet, so to create it, perform the
15515 following commands:
15520 Now that you have all of the disks labeled, you must build the ccd(4). To
15521 do that, use ccdconfig(8), with options similar to the following:
15523 ccdconfig ccd0(1) 32(2) 0(3) /dev/ad1e(4) /dev/ad2e /dev/ad3e
15525 The use and meaning of each option is shown below:
15528 The first argument is the device to configure, in this case,
15529 /dev/ccd0c. The /dev/ portion is optional.
15531 The interleave for the file system. The interleave defines the
15532 size of a stripe in disk blocks, each normally 512 bytes. So, an
15533 interleave of 32 would be 16,384 bytes.
15535 Flags for ccdconfig(8). If you want to enable drive mirroring, you
15536 can specify a flag here. This configuration does not provide
15537 mirroring for ccd(4), so it is set at 0 (zero).
15539 The final arguments to ccdconfig(8) are the devices to place into
15540 the array. Use the complete pathname for each device.
15542 After running ccdconfig(8) the ccd(4) is configured. A file system can be
15543 installed. Refer to newfs(8) for options, or simply run:
15547 ----------------------------------------------------------------------
15549 12.4.1.1.4 Making it All Automatic
15551 Generally, you will want to mount the ccd(4) upon each reboot. To do this,
15552 you must configure it first. Write out your current configuration to
15553 /etc/ccd.conf using the following command:
15555 ccdconfig -g > /etc/ccd.conf
15557 During reboot, the script /etc/rc runs ccdconfig -C if /etc/ccd.conf
15558 exists. This automatically configures the ccd(4) so it can be mounted.
15560 Note: If you are booting into single user mode, before you can mount(8)
15561 the ccd(4), you need to issue the following command to configure the
15566 To automatically mount the ccd(4), place an entry for the ccd(4) in
15567 /etc/fstab so it will be mounted at boot time:
15569 /dev/ccd0c /media ufs rw 2 2
15571 ----------------------------------------------------------------------
15573 12.4.1.2 The Vinum Volume Manager
15575 The Vinum Volume Manager is a block device driver which implements virtual
15576 disk drives. It isolates disk hardware from the block device interface and
15577 maps data in ways which result in an increase in flexibility, performance
15578 and reliability compared to the traditional slice view of disk storage.
15579 vinum(8) implements the RAID-0, RAID-1 and RAID-5 models, both
15580 individually and in combination.
15582 See Chapter 13 for more information about vinum(8).
15584 ----------------------------------------------------------------------
15586 12.4.2 Hardware RAID
15588 DragonFly also supports a variety of hardware RAID controllers. These
15589 devices control a RAID subsystem without the need for DragonFly specific
15590 software to manage the array.
15592 Using an on-card BIOS, the card controls most of the disk operations
15593 itself. The following is a brief setup description using a Promise IDE
15594 RAID controller. When this card is installed and the system is started up,
15595 it displays a prompt requesting information. Follow the instructions to
15596 enter the card's setup screen. From here, you have the ability to combine
15597 all the attached drives. After doing so, the disk(s) will look like a
15598 single drive to DragonFly. Other RAID levels can be set up accordingly.
15600 ----------------------------------------------------------------------
15602 12.4.3 Rebuilding ATA RAID1 Arrays
15604 DragonFly allows you to hot-replace a failed disk in an array. This
15605 requires that you catch it before you reboot.
15607 You will probably see something like the following in /var/log/messages or
15608 in the dmesg(8) output:
15610 ad6 on monster1 suffered a hard error.
15611 ad6: READ command timeout tag=0 serv=0 - resetting
15612 ad6: trying fallback to PIO mode
15613 ata3: resetting devices .. done
15614 ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11) status=59 error=40
15615 ar0: WARNING - mirror lost
15617 Using atacontrol(8), check for further information:
15621 Master: no device present
15622 Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0
15625 Master: no device present
15626 Slave: no device present
15629 Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15630 Slave: no device present
15633 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15634 Slave: no device present
15636 # atacontrol status ar0
15637 ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED
15639 1. You will first need to detach the disk from the array so that you can
15642 # atacontrol detach 3
15644 2. Replace the disk.
15646 3. Reattach the disk as a spare:
15648 # atacontrol attach 3
15649 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
15650 Slave: no device present
15652 4. Rebuild the array:
15654 # atacontrol rebuild ar0
15656 5. The rebuild command hangs until complete. However, it is possible to
15657 open another terminal (using Alt+Fn) and check on the progress by
15658 issuing the following command:
15662 ad6: removed from configuration
15663 ad6: deleted from ar0 disk1
15664 ad6: inserted into ar0 disk1 as spare
15666 # atacontrol status ar0
15667 ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed
15669 6. Wait until this operation completes.
15671 ----------------------------------------------------------------------
15673 12.5 Creating and Using Optical Media (CDs)
15675 Contributed by Mike Meyer.
15677 ----------------------------------------------------------------------
15679 12.5.1 Introduction
15681 CDs have a number of features that differentiate them from conventional
15682 disks. Initially, they were not writable by the user. They are designed so
15683 that they can be read continuously without delays to move the head between
15684 tracks. They are also much easier to transport between systems than
15685 similarly sized media were at the time.
15687 CDs do have tracks, but this refers to a section of data to be read
15688 continuously and not a physical property of the disk. To produce a CD on
15689 DragonFly, you prepare the data files that are going to make up the tracks
15690 on the CD, then write the tracks to the CD.
15692 The ISO 9660 file system was designed to deal with these differences. It
15693 unfortunately codifies file system limits that were common then.
15694 Fortunately, it provides an extension mechanism that allows properly
15695 written CDs to exceed those limits while still working with systems that
15696 do not support those extensions.
15698 The sysutils/mkisofs program is used to produce a data file containing an
15699 ISO 9660 file system. It has options that support various extensions, and
15700 is described below. It is installed by default.
15702 Which tool to use to burn the CD depends on whether your CD burner is
15703 ATAPI or something else. ATAPI CD burners use the burncd program that is
15704 part of the base system. SCSI and USB CD burners should use cdrecord from
15705 the sysutils/cdrtools port.
15707 burncd has a limited number of supported drives. To find out if a drive is
15708 supported, see the CD-R/RW supported drives list.
15710 Note: It ispossible to use cdrecord and other tools for SCSI drives on
15711 an ATAPI hardware with the ATAPI/CAM module.
15713 ----------------------------------------------------------------------
15717 sysutils/mkisofs produces an ISO 9660 file system that is an image of a
15718 directory tree in the UNIX file system name space. The simplest usage is:
15720 # mkisofs -o imagefile.iso /path/to/tree
15722 This command will create an imagefile.iso containing an ISO 9660 file
15723 system that is a copy of the tree at /path/to/tree. In the process, it
15724 will map the file names to names that fit the limitations of the standard
15725 ISO 9660 file system, and will exclude files that have names
15726 uncharacteristic of ISO file systems.
15728 A number of options are available to overcome those restrictions. In
15729 particular, -R enables the Rock Ridge extensions common to UNIX systems,
15730 -J enables Joliet extensions used by Microsoft systems, and -hfs can be
15731 used to create HFS file systems used by Mac OS.
15733 For CDs that are going to be used only on DragonFly systems, -U can be
15734 used to disable all filename restrictions. When used with -R, it produces
15735 a file system image that is identical to the DragonFly tree you started
15736 from, though it may violate the ISO 9660 standard in a number of ways.
15738 The last option of general use is -b. This is used to specify the location
15739 of the boot image for use in producing an ``El Torito'' bootable CD. This
15740 option takes an argument which is the path to a boot image from the top of
15741 the tree being written to the CD. So, given that /tmp/myboot holds a
15742 bootable DragonFly system with the boot image in /tmp/myboot/boot/cdboot,
15743 you could produce the image of an ISO 9660 file system in
15744 /tmp/bootable.iso like so:
15746 # mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot
15748 Having done that, if you have vn configured in your kernel, you can mount
15749 the file system with:
15751 # vnconfig -e vn0c /tmp/bootable.iso
15752 # mount -t cd9660 /dev/vn0c /mnt
15754 At which point you can verify that /mnt and /tmp/myboot are identical.
15756 There are many other options you can use with sysutils/mkisofs to
15757 fine-tune its behavior. In particular: modifications to an ISO 9660 layout
15758 and the creation of Joliet and HFS discs. See the mkisofs(8) manual page
15761 ----------------------------------------------------------------------
15765 If you have an ATAPI CD burner, you can use the burncd command to burn an
15766 ISO image onto a CD. burncd is part of the base system, installed as
15767 /usr/sbin/burncd. Usage is very simple, as it has few options:
15769 # burncd -f cddevice data imagefile.iso fixate
15771 Will burn a copy of imagefile.iso on cddevice. The default device is
15772 /dev/acd0c. See burncd(8) for options to set the write speed, eject the CD
15773 after burning, and write audio data.
15775 ----------------------------------------------------------------------
15779 If you do not have an ATAPI CD burner, you will have to use cdrecord to
15780 burn your CDs. cdrecord is not part of the base system; you must install
15781 it from either the port at sysutils/cdrtools or the appropriate package.
15782 Changes to the base system can cause binary versions of this program to
15783 fail, possibly resulting in a ``coaster''. You should therefore either
15784 upgrade the port when you upgrade your system.
15786 While cdrecord has many options, basic usage is even simpler than burncd.
15787 Burning an ISO 9660 image is done with:
15789 # cdrecord dev=device imagefile.iso
15791 The tricky part of using cdrecord is finding the dev to use. To find the
15792 proper setting, use the -scanbus flag of cdrecord, which might produce
15795 # cdrecord -scanbus
15796 Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jo:rg Schilling
15797 Using libscg version 'schily-0.1'
15799 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk
15800 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk
15802 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk
15803 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
15813 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM
15814 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner
15817 This lists the appropriate dev value for the devices on the list. Locate
15818 your CD burner, and use the three numbers separated by commas as the value
15819 for dev. In this case, the CRW device is 1,5,0, so the appropriate input
15820 would be dev=1,5,0. There are easier ways to specify this value; see
15821 cdrecord(1) for details. That is also the place to look for information on
15822 writing audio tracks, controlling the speed, and other things.
15824 ----------------------------------------------------------------------
15826 12.5.5 Duplicating Audio CDs
15828 You can duplicate an audio CD by extracting the audio data from the CD to
15829 a series of files, and then writing these files to a blank CD. The process
15830 is slightly different for ATAPI and SCSI drives.
15834 1. Use cdda2wav to extract the audio.
15836 % cdda2wav -v255 -D2,0 -B -Owav
15838 2. Use cdrecord to write the .wav files.
15840 % cdrecord -v dev=2,0 -dao -useinfo *.wav
15842 Make sure that 2.0 is set appropriately, as described in Section
15847 1. The ATAPI CD driver makes each track available as /dev/acddtnn, where
15848 d is the drive number, and nn is the track number written with two
15849 decimal digits, prefixed with zero as needed. So the first track on
15850 the first disk is /dev/acd0t01, the second is /dev/acd0t02, the third
15851 is /dev/acd0t03, and so on.
15853 Make sure the appropriate files exist in /dev.
15856 # sh MAKEDEV acd0t99
15858 2. Extract each track using dd(1). You must also use a specific block
15859 size when extracting the files.
15861 # dd if=/dev/acd0t01 of=track1.cdr bs=2352
15862 # dd if=/dev/acd0t02 of=track2.cdr bs=2352
15865 3. Burn the extracted files to disk using burncd. You must specify that
15866 these are audio files, and that burncd should fixate the disk when
15869 # burncd -f /dev/acd0c audio track1.cdr track2.cdr ... fixate
15871 ----------------------------------------------------------------------
15873 12.5.6 Duplicating Data CDs
15875 You can copy a data CD to a image file that is functionally equivalent to
15876 the image file created with sysutils/mkisofs, and you can use it to
15877 duplicate any data CD. The example given here assumes that your CDROM
15878 device is acd0c. Substitute your correct CDROM device. A c must be
15879 appended to the end of the device name to indicate the entire partition
15880 or, in the case of CDROMs, the entire disc.
15882 # dd if=/dev/acd0c of=file.iso bs=2048
15884 Now that you have an image, you can burn it to CD as described above.
15886 ----------------------------------------------------------------------
15888 12.5.7 Using Data CDs
15890 Now that you have created a standard data CDROM, you probably want to
15891 mount it and read the data on it. By default, mount(8) assumes that a file
15892 system is of type ufs. If you try something like:
15894 # mount /dev/cd0 /mnt
15896 you will get a complaint about ``Incorrect super block'', and no mount.
15897 The CDROM is not a UFS file system, so attempts to mount it as such will
15898 fail. You just need to tell mount(8) that the file system is of type
15899 ISO9660, and everything will work. You do this by specifying the -t cd9660
15900 option mount(8). For example, if you want to mount the CDROM device,
15901 /dev/cd0, under /mnt, you would execute:
15903 # mount -t cd9660 /dev/cd0 /mnt
15905 Note that your device name (/dev/cd0 in this example) could be different,
15906 depending on the interface your CDROM uses. Also, the -t cd9660 option
15907 just executes mount_cd9660(8). The above example could be shortened to:
15909 # mount_cd9660 /dev/cd0 /mnt
15911 You can generally use data CDROMs from any vendor in this way. Disks with
15912 certain ISO 9660 extensions might behave oddly, however. For example,
15913 Joliet disks store all filenames in two-byte Unicode characters. The
15914 DragonFly kernel does not speak Unicode (yet!), so non-English characters
15915 show up as question marks. (The CD9660 driver includes hooks to load an
15916 appropriate Unicode conversion table on the fly. Modules for some of the
15917 common encodings are available via the sysutils/cd9660_unicode port.)
15919 Occasionally, you might get ``Device not configured'' when trying to mount
15920 a CDROM. This usually means that the CDROM drive thinks that there is no
15921 disk in the tray, or that the drive is not visible on the bus. It can take
15922 a couple of seconds for a CDROM drive to realize that it has been fed, so
15925 Sometimes, a SCSI CDROM may be missed because it did not have enough time
15926 to answer the bus reset. If you have a SCSI CDROM please add the following
15927 option to your kernel configuration and rebuild your kernel.
15929 options SCSI_DELAY=15000
15931 This tells your SCSI bus to pause 15 seconds during boot, to give your
15932 CDROM drive every possible chance to answer the bus reset.
15934 ----------------------------------------------------------------------
15936 12.5.8 Burning Raw Data CDs
15938 You can choose to burn a file directly to CD, without creating an ISO 9660
15939 file system. Some people do this for backup purposes. This runs more
15940 quickly than burning a standard CD:
15942 # burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate
15944 In order to retrieve the data burned to such a CD, you must read data from
15945 the raw device node:
15947 # tar xzvf /dev/acd1
15949 You cannot mount this disk as you would a normal CDROM. Such a CDROM
15950 cannot be read under any operating system except DragonFly. If you want to
15951 be able to mount the CD, or share data with another operating system, you
15952 must use sysutils/mkisofs as described above.
15954 ----------------------------------------------------------------------
15956 12.5.9 Using the ATAPI/CAM Driver
15958 Contributed by Marc Fonvieille.
15960 This driver allows ATAPI devices (CD-ROM, CD-RW, DVD drives etc...) to be
15961 accessed through the SCSI subsystem, and so allows the use of applications
15962 like sysutils/cdrdao or cdrecord(1).
15964 To use this driver, you will need to add the following lines to your
15965 kernel configuration file:
15972 You also need the following line in your kernel configuration file:
15976 which should already be present.
15978 Then rebuild, install your new kernel, and reboot your machine. During the
15979 boot process, your burner should show up, like so:
15981 acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4
15982 cd0 at ata1 bus 0 target 0 lun 0
15983 cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device
15984 cd0: 16.000MB/s transfers
15985 cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed
15987 The drive could now be accessed via the /dev/cd0 device name, for example
15988 to mount a CD-ROM on /mnt, just type the following:
15990 # mount -t cd9660 /dev/cd0 /mnt
15992 As root, you can run the following command to get the SCSI address of the
15995 # camcontrol devlist
15996 <MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0)
15998 So 1,0,0 will be the SCSI address to use with cdrecord(1) and other SCSI
16001 For more information about ATAPI/CAM and SCSI system, refer to the
16002 atapicam(4) and cam(4) manual pages.
16004 ----------------------------------------------------------------------
16006 12.6 Creating and Using Optical Media (DVDs)
16008 Contributed by Marc Fonvieille. With inputs from Andy Polyakov.
16010 ----------------------------------------------------------------------
16012 12.6.1 Introduction
16014 Compared to the CD, the DVD is the next generation of optical media
16015 storage technology. The DVD can hold more data than any CD and is nowadays
16016 the standard for video publishing.
16018 Five physical recordable formats can be defined for what we will call a
16021 * DVD-R: This was the first DVD recordable format available. The DVD-R
16022 standard is defined by the DVD Forum. This format is write once.
16024 * DVD-RW: This is the rewriteable version of the DVD-R standard. A
16025 DVD-RW can be rewritten about 1000 times.
16027 * DVD-RAM: This is also a rewriteable format supported by the DVD Forum.
16028 A DVD-RAM can be seen as a removable hard drive. However, this media
16029 is not compatible with most DVD-ROM drives and DVD-Video players; only
16030 a few DVD writers support the DVD-RAM format.
16032 * DVD+RW: This is a rewriteable format defined by the DVD+RW Alliance. A
16033 DVD+RW can be rewritten about 1000 times.
16035 * DVD+R: This format is the write once variation of the DVD+RW format.
16037 A single layer recordable DVD can hold up to 4,700,000,000 bytes which is
16038 actually 4.38 GB or 4485 MB (1 kilobyte is 1024 bytes).
16040 Note: A distinction must be made between the physical media and the
16041 application. For example, a DVD-Video is a specific file layout that can
16042 be written on any recordable DVD physical media: DVD-R, DVD+R, DVD-RW
16043 etc. Before choosing the type of media, you must be sure that both the
16044 burner and the DVD-Video player (a standalone player or a DVD-ROM drive
16045 on a computer) are compatible with the media under consideration.
16047 ----------------------------------------------------------------------
16049 12.6.2 Configuration
16051 The program growisofs(1) will be used to perform DVD recording. This
16052 command is part of the dvd+rw-tools utilities (sysutils/dvd+rw-tools). The
16053 dvd+rw-tools support all DVD media types.
16055 These tools use the SCSI subsystem to access to the devices, therefore the
16056 ATAPI/CAM support must be added to your kernel.
16058 You also have to enable DMA access for ATAPI devices, this can be done in
16059 adding the following line to the /boot/loader.conf file:
16061 hw.ata.atapi_dma="1"
16063 Before attempting to use the dvd+rw-tools you should consult the
16064 dvd+rw-tools' hardware compatibility notes for any information related to
16067 ----------------------------------------------------------------------
16069 12.6.3 Burning Data DVDs
16071 The growisofs(1) command is a frontend to mkisofs, it will invoke
16072 mkisofs(8) to create the file system layout and will perform the write on
16073 the DVD. This means you do not need to create an image of the data before
16074 the burning process.
16076 To burn onto a DVD+R or a DVD-R the data from the /path/to/data directory,
16077 use the following command:
16079 # growisofs -dvd-compat -Z /dev/cd0 -J -R /path/to/data
16081 The options -J -R are passed to mkisofs(8) for the file system creation
16082 (in this case: an ISO 9660 file system with Joliet and Rock Ridge
16083 extensions), consult the mkisofs(8) manual page for more details.
16085 The option -Z is used for the initial session recording in any case:
16086 multiple sessions or not. The DVD device, /dev/cd0, must be changed
16087 according to your configuration. The -dvd-compat parameter will close the
16088 disk, the recording will be unappendable. In return this should provide
16089 better media compatibility with DVD-ROM drives.
16091 It is also possible to burn a pre-mastered image, for example to burn the
16092 image imagefile.iso, we will run:
16094 # growisofs -dvd-compat -Z /dev/cd0=imagefile.iso
16096 The write speed should be detected and automatically set according to the
16097 media and the drive being used. If you want to force the write speed, use
16098 the -speed= parameter. For more information, read the growisofs(1) manual
16101 ----------------------------------------------------------------------
16103 12.6.4 Burning a DVD-Video
16105 A DVD-Video is a specific file layout based on ISO 9660 and the micro-UDF
16106 (M-UDF) specifications. The DVD-Video also presents a specific data
16107 structure hierarchy, it is the reason why you need a particular program
16108 such as multimedia/dvdauthor to author the DVD.
16110 If you already have an image of the DVD-Video file system, just burn it in
16111 the same way as for any image, see the previous section for an example. If
16112 you have made the DVD authoring and the result is in, for example, the
16113 directory /path/to/video, the following command should be used to burn the
16116 # growisofs -Z /dev/cd0 -dvd-video /path/to/video
16118 The -dvd-video option will be passed down to mkisofs(8) and will instruct
16119 it to create a DVD-Video file system layout. Beside this, the -dvd-video
16120 option implies -dvd-compat growisofs(1) option.
16122 ----------------------------------------------------------------------
16124 12.6.5 Using a DVD+RW
16126 Unlike CD-RW, a virgin DVD+RW needs to be formatted before first use. The
16127 growisofs(1) program will take care of it automatically whenever
16128 appropriate, which is the recommended way. However you can use the
16129 dvd+rw-format command to format the DVD+RW:
16131 # dvd+rw-format /dev/cd0
16133 You need to perform this operation just once, keep in mind that only
16134 virgin DVD+RW medias need to be formatted. Then you can burn the DVD+RW in
16135 the way seen in previous sections.
16137 If you want to burn new data (burn a totally new file system not append
16138 some data) onto a DVD+RW, you do not need to blank it, you just have to
16139 write over the previous recording (in performing a new initial session),
16142 # growisofs -Z /dev/cd0 -J -R /path/to/newdata
16144 DVD+RW format offers the possibility to easily append data to a previous
16145 recording. The operation consists in merging a new session to the existing
16146 one, it is not multisession writing, growisofs(1) will grow the ISO 9660
16147 file system present on the media.
16149 For example, if we want to append data to our previous DVD+RW, we have to
16152 # growisofs -M /dev/cd0 -J -R /path/to/nextdata
16154 The same mkisofs(8) options we used to burn the initial session should be
16155 used during next writes.
16157 Note: You may want to use the -dvd-compat option if you want better
16158 media compatibility with DVD-ROM drives. In the DVD+RW case, this will
16159 not prevent you from adding data.
16161 If for any reason you really want to blank the media, do the following:
16163 # growisofs -Z /dev/cd0=/dev/zero
16165 ----------------------------------------------------------------------
16167 12.6.6 Using a DVD-RW
16169 A DVD-RW accepts two disc formats: the incremental sequential one and the
16170 restricted overwrite. By default DVD-RW discs are in sequential format.
16172 A virgin DVD-RW can be directly written without the need of a formatting
16173 operation, however a non-virgin DVD-RW in sequential format needs to be
16174 blanked before to be able to write a new initial session.
16176 To blank a DVD-RW in sequential mode, run:
16178 # dvd+rw-format -blank=full /dev/cd0
16180 Note: A full blanking (-blank=full) will take about one hour on a 1x
16181 media. A fast blanking can be performed using the -blank option if the
16182 DVD-RW will be recorded in Disk-At-Once (DAO) mode. To burn the DVD-RW
16183 in DAO mode, use the command:
16185 # growisofs -use-the-force-luke=dao -Z /dev/cd0=imagefile.iso
16187 The -use-the-force-luke=dao option should not be required since
16188 growisofs(1) attempts to detect minimally (fast blanked) media and
16191 In fact one should use restricted overwrite mode with any DVD-RW, this
16192 format is more flexible than the default incremental sequential one.
16194 To write data on a sequential DVD-RW, use the same instructions as for the
16197 # growisofs -Z /dev/cd0 -J -R /path/to/data
16199 If you want to append some data to your previous recording, you will have
16200 to use the growisofs(1) -M option. However, if you perform data addition
16201 on a DVD-RW in incremental sequential mode, a new session will be created
16202 on the disc and the result will be a multi-session disc.
16204 A DVD-RW in restricted overwrite format does not need to be blanked before
16205 a new initial session, you just have to overwrite the disc with the -Z
16206 option, this is similar to the DVD+RW case. It is also possible to grow an
16207 existing ISO 9660 file system written on the disc in a same way as for a
16208 DVD+RW with the -M option. The result will be a one-session DVD.
16210 To put a DVD-RW in the restricted overwrite format, the following command
16213 # dvd+rw-format /dev/cd0
16215 To change back to the sequential format use:
16217 # dvd+rw-format -blank=full /dev/cd0
16219 ----------------------------------------------------------------------
16221 12.6.7 Multisession
16223 Very few DVD-ROM and DVD-Video players support multisession DVDs, they
16224 will most of time, hopefully, only read the first session. DVD+R, DVD-R
16225 and DVD-RW in sequential format can accept multiple sessions, the notion
16226 of multiple sessions does not exist for the DVD+RW and the DVD-RW
16227 restricted overwrite formats.
16229 Using the following command after an initial (non-closed) session on a
16230 DVD+R, DVD-R, or DVD-RW in sequential format, will add a new session to
16233 # growisofs -M /dev/cd0 -J -R /path/to/nextdata
16235 Using this command line with a DVD+RW or a DVD-RW in restricted overwrite
16236 mode, will append data in merging the new session to the existing one. The
16237 result will be a single-session disc. This is the way used to add data
16238 after an initial write on these medias.
16240 Note: Some space on the media is used between each session for end and
16241 start of sessions. Therefore, one should add sessions with large amount
16242 of data to optimize media space. The number of sessions is limited to
16243 154 for a DVD+R and about 2000 for a DVD-R.
16245 ----------------------------------------------------------------------
16247 12.6.8 For More Information
16249 To obtain more information about a DVD, the dvd+rw-mediainfo /dev/cd0
16250 command can be ran with the disc in the drive.
16252 More information about the dvd+rw-tools can be found in the growisofs(1)
16253 manual page, on the dvd+rw-tools web site and in the cdwrite mailing list
16256 Note: The dvd+rw-mediainfo output of the resulting recording or the
16257 media with issues is mandatory for any problem report. Without this
16258 output, it will be quite impossible to help you.
16260 ----------------------------------------------------------------------
16262 12.7 Creating and Using Floppy Disks
16264 Original work by Julio Merino. Rewritten by Martin Karlsson.
16266 Storing data on floppy disks is sometimes useful, for example when one
16267 does not have any other removable storage media or when one needs to
16268 transfer small amounts of data to another computer.
16270 This section will explain how to use floppy disks in DragonFly. It will
16271 primarily cover formatting and usage of 3.5inch DOS floppies, but the
16272 concepts are similar for other floppy disk formats.
16274 ----------------------------------------------------------------------
16276 12.7.1 Formatting Floppies
16278 12.7.1.1 The Device
16280 Floppy disks are accessed through entries in /dev, just like other
16281 devices. To access the raw floppy disk, one uses /dev/fdN, where N stands
16282 for the drive number, usually 0, or /dev/fdNX, where X stands for a
16285 There are also /dev/fdN.size devices, where size is a floppy disk size in
16286 kilobytes. These entries are used at low-level format time to determine
16287 the disk size. 1440kB is the size that will be used in the following
16290 Sometimes the entries under /dev will have to be (re)created. To do that,
16293 # cd /dev && ./MAKEDEV "fd*"
16295 ----------------------------------------------------------------------
16297 12.7.1.2 Formatting
16299 A floppy disk needs to be low-level formated before it can be used. This
16300 is usually done by the vendor, but formatting is a good way to check media
16301 integrity. Although it is possible to force larger (or smaller) disk
16302 sizes, 1440kB is what most floppy disks are designed for.
16304 To low-level format the floppy disk you need to use fdformat(1). This
16305 utility expects the device name as an argument.
16307 Make note of any error messages, as these can help determine if the disk
16310 Use the /dev/fdN.size devices to format the floppy. Insert a new 3.5inch
16311 floppy disk in your drive and issue:
16313 # /usr/sbin/fdformat /dev/fd0.1440
16315 ----------------------------------------------------------------------
16317 12.7.2 The Disk Label
16319 After low-level formatting the disk, you will need to place a disk label
16320 on it. This disk label will be destroyed later, but it is needed by the
16321 system to determine the size of the disk and its geometry later.
16323 The new disk label will take over the whole disk, and will contain all the
16324 proper information about the geometry of the floppy. The geometry values
16325 for the disk label are listed in /etc/disktab.
16327 You can run now disklabel(8) like so:
16329 # /sbin/disklabel -B -r -w /dev/fd0 fd1440
16331 ----------------------------------------------------------------------
16333 12.7.3 The File System
16335 Now the floppy is ready to be high-level formated. This will place a new
16336 file system on it, which will let DragonFly read and write to the disk.
16337 After creating the new file system, the disk label is destroyed, so if you
16338 want to reformat the disk, you will have to recreate the disk label.
16340 The floppy's file system can be either UFS or FAT. FAT is generally a
16341 better choice for floppies.
16343 To put a new file system on the floppy, issue:
16345 # /sbin/newfs_msdos /dev/fd0
16347 The disk is now ready for use.
16349 ----------------------------------------------------------------------
16351 12.7.4 Using the Floppy
16353 To use the floppy, mount it with mount_msdos(8). One can also use
16354 sysutils/mtools from pkgsrc.
16356 ----------------------------------------------------------------------
16358 12.8 Creating and Using Data Tapes
16360 The major tape media are the 4mm, 8mm, QIC, mini-cartridge and DLT.
16362 ----------------------------------------------------------------------
16364 12.8.1 4mm (DDS: Digital Data Storage)
16366 4mm tapes are replacing QIC as the workstation backup media of choice.
16367 This trend accelerated greatly when Conner purchased Archive, a leading
16368 manufacturer of QIC drives, and then stopped production of QIC drives. 4mm
16369 drives are small and quiet but do not have the reputation for reliability
16370 that is enjoyed by 8mm drives. The cartridges are less expensive and
16371 smaller (3 x 2 x 0.5 inches, 76 x 51 x 12 mm) than 8mm cartridges. 4mm,
16372 like 8mm, has comparatively short head life for the same reason, both use
16375 Data throughput on these drives starts ~150 kB/s, peaking at ~500 kB/s.
16376 Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware compression,
16377 available with most of these drives, approximately doubles the capacity.
16378 Multi-drive tape library units can have 6 drives in a single cabinet with
16379 automatic tape changing. Library capacities reach 240 GB.
16381 The DDS-3 standard now supports tape capacities up to 12 GB (or 24 GB
16384 4mm drives, like 8mm drives, use helical-scan. All the benefits and
16385 drawbacks of helical-scan apply to both 4mm and 8mm drives.
16387 Tapes should be retired from use after 2,000 passes or 100 full backups.
16389 ----------------------------------------------------------------------
16391 12.8.2 8mm (Exabyte)
16393 8mm tapes are the most common SCSI tape drives; they are the best choice
16394 of exchanging tapes. Nearly every site has an Exabyte 2 GB 8mm tape drive.
16395 8mm drives are reliable, convenient and quiet. Cartridges are inexpensive
16396 and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). One downside of 8mm
16397 tape is relatively short head and tape life due to the high rate of
16398 relative motion of the tape across the heads.
16400 Data throughput ranges from ~250 kB/s to ~500 kB/s. Data sizes start at
16401 300 MB and go up to 7 GB. Hardware compression, available with most of
16402 these drives, approximately doubles the capacity. These drives are
16403 available as single units or multi-drive tape libraries with 6 drives and
16404 120 tapes in a single cabinet. Tapes are changed automatically by the
16405 unit. Library capacities reach 840+ GB.
16407 The Exabyte ``Mammoth'' model supports 12 GB on one tape (24 GB with
16408 compression) and costs approximately twice as much as conventional tape
16411 Data is recorded onto the tape using helical-scan, the heads are
16412 positioned at an angle to the media (approximately 6 degrees). The tape
16413 wraps around 270 degrees of the spool that holds the heads. The spool
16414 spins while the tape slides over the spool. The result is a high density
16415 of data and closely packed tracks that angle across the tape from one edge
16418 ----------------------------------------------------------------------
16422 QIC-150 tapes and drives are, perhaps, the most common tape drive and
16423 media around. QIC tape drives are the least expensive ``serious'' backup
16424 drives. The downside is the cost of media. QIC tapes are expensive
16425 compared to 8mm or 4mm tapes, up to 5 times the price per GB data storage.
16426 But, if your needs can be satisfied with a half-dozen tapes, QIC may be
16427 the correct choice. QIC is the most common tape drive. Every site has a
16428 QIC drive of some density or another. Therein lies the rub, QIC has a
16429 large number of densities on physically similar (sometimes identical)
16430 tapes. QIC drives are not quiet. These drives audibly seek before they
16431 begin to record data and are clearly audible whenever reading, writing or
16432 seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7 mm).
16433 Mini-cartridges, which also use 1/4" wide tape are discussed separately.
16434 Tape libraries and changers are not available.
16436 Data throughput ranges from ~150 kB/s to ~500 kB/s. Data capacity ranges
16437 from 40 MB to 15 GB. Hardware compression is available on many of the
16438 newer QIC drives. QIC drives are less frequently installed; they are being
16439 supplanted by DAT drives.
16441 Data is recorded onto the tape in tracks. The tracks run along the long
16442 axis of the tape media from one end to the other. The number of tracks,
16443 and therefore the width of a track, varies with the tape's capacity. Most
16444 if not all newer drives provide backward-compatibility at least for
16445 reading (but often also for writing). QIC has a good reputation regarding
16446 the safety of the data (the mechanics are simpler and more robust than for
16447 helical scan drives).
16449 Tapes should be retired from use after 5,000 backups.
16451 ----------------------------------------------------------------------
16453 12.8.4 XXX* Mini-Cartridge
16455 ----------------------------------------------------------------------
16459 DLT has the fastest data transfer rate of all the drive types listed here.
16460 The 1/2" (12.5mm) tape is contained in a single spool cartridge (4 x 4 x 1
16461 inches; 100 x 100 x 25 mm). The cartridge has a swinging gate along one
16462 entire side of the cartridge. The drive mechanism opens this gate to
16463 extract the tape leader. The tape leader has an oval hole in it which the
16464 drive uses to ``hook'' the tape. The take-up spool is located inside the
16465 tape drive. All the other tape cartridges listed here (9 track tapes are
16466 the only exception) have both the supply and take-up spools located inside
16467 the tape cartridge itself.
16469 Data throughput is approximately 1.5 MB/s, three times the throughput of
16470 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 GB
16471 for a single drive. Drives are available in both multi-tape changers and
16472 multi-tape, multi-drive tape libraries containing from 5 to 900 tapes over
16473 1 to 20 drives, providing from 50 GB to 9 TB of storage.
16475 With compression, DLT Type IV format supports up to 70 GB capacity.
16477 Data is recorded onto the tape in tracks parallel to the direction of
16478 travel (just like QIC tapes). Two tracks are written at once. Read/write
16479 head lifetimes are relatively long; once the tape stops moving, there is
16480 no relative motion between the heads and the tape.
16482 ----------------------------------------------------------------------
16486 AIT is a new format from Sony, and can hold up to 50 GB (with compression)
16487 per tape. The tapes contain memory chips which retain an index of the
16488 tape's contents. This index can be rapidly read by the tape drive to
16489 determine the position of files on the tape, instead of the several
16490 minutes that would be required for other tapes. Software such as
16491 SAMS:Alexandria can operate forty or more AIT tape libraries,
16492 communicating directly with the tape's memory chip to display the contents
16493 on screen, determine what files were backed up to which tape, locate the
16494 correct tape, load it, and restore the data from the tape.
16496 Libraries like this cost in the region of $20,000, pricing them a little
16497 out of the hobbyist market.
16499 ----------------------------------------------------------------------
16501 12.8.7 Using a New Tape for the First Time
16503 The first time that you try to read or write a new, completely blank tape,
16504 the operation will fail. The console messages should be similar to:
16506 sa0(ncr1:4:0): NOT READY asc:4,1
16507 sa0(ncr1:4:0): Logical unit is in process of becoming ready
16509 The tape does not contain an Identifier Block (block number 0). All QIC
16510 tape drives since the adoption of QIC-525 standard write an Identifier
16511 Block to the tape. There are two solutions:
16513 * mt fsf 1 causes the tape drive to write an Identifier Block to the
16516 * Use the front panel button to eject the tape.
16518 Re-insert the tape and dump data to the tape.
16520 dump will report ``DUMP: End of tape detected'' and the console will
16521 show: ``HARDWARE FAILURE info:280 asc:80,96''.
16523 rewind the tape using: mt rewind.
16525 Subsequent tape operations are successful.
16527 ----------------------------------------------------------------------
16529 12.9 Backups to Floppies
16531 12.9.1 Can I Use Floppies for Backing Up My Data?
16533 Floppy disks are not really a suitable media for making backups as:
16535 * The media is unreliable, especially over long periods of time.
16537 * Backing up and restoring is very slow.
16539 * They have a very limited capacity (the days of backing up an entire
16540 hard disk onto a dozen or so floppies has long since passed).
16542 However, if you have no other method of backing up your data then floppy
16543 disks are better than no backup at all.
16545 If you do have to use floppy disks then ensure that you use good quality
16546 ones. Floppies that have been lying around the office for a couple of
16547 years are a bad choice. Ideally use new ones from a reputable
16550 ----------------------------------------------------------------------
16552 12.9.2 So How Do I Backup My Data to Floppies?
16554 The best way to backup to floppy disk is to use tar(1) with the -M (multi
16555 volume) option, which allows backups to span multiple floppies.
16557 To backup all the files in the current directory and sub-directory use
16560 # tar Mcvf /dev/fd0 *
16562 When the first floppy is full tar(1) will prompt you to insert the next
16563 volume (because tar(1) is media independent it refers to volumes; in this
16564 context it means floppy disk).
16566 Prepare volume #2 for /dev/fd0 and hit return:
16568 This is repeated (with the volume number incrementing) until all the
16569 specified files have been archived.
16571 ----------------------------------------------------------------------
16573 12.9.3 Can I Compress My Backups?
16575 Unfortunately, tar(1) will not allow the -z option to be used for
16576 multi-volume archives. You could, of course, gzip(1) all the files, tar(1)
16577 them to the floppies, then gunzip(1) the files again!
16579 ----------------------------------------------------------------------
16581 12.9.4 How Do I Restore My Backups?
16583 To restore the entire archive use:
16585 # tar Mxvf /dev/fd0
16587 There are two ways that you can use to restore only specific files. First,
16588 you can start with the first floppy and use:
16590 # tar Mxvf /dev/fd0 filename
16592 The utility tar(1) will prompt you to insert subsequent floppies until it
16593 finds the required file.
16595 Alternatively, if you know which floppy the file is on then you can simply
16596 insert that floppy and use the same command as above. Note that if the
16597 first file on the floppy is a continuation from the previous one then
16598 tar(1) will warn you that it cannot restore it, even if you have not asked
16601 ----------------------------------------------------------------------
16603 12.10 Backup Basics
16605 The three major backup programs are dump(8), tar(1), and cpio(1).
16607 ----------------------------------------------------------------------
16609 12.10.1 Dump and Restore
16611 The traditional UNIX backup programs are dump and restore. They operate on
16612 the drive as a collection of disk blocks, below the abstractions of files,
16613 links and directories that are created by the file systems. dump backs up
16614 an entire file system on a device. It is unable to backup only part of a
16615 file system or a directory tree that spans more than one file system. dump
16616 does not write files and directories to tape, but rather writes the raw
16617 data blocks that comprise files and directories.
16619 Note: If you use dump on your root directory, you would not back up
16620 /home, /usr or many other directories since these are typically mount
16621 points for other file systems or symbolic links into those file systems.
16623 dump has quirks that remain from its early days in Version 6 of AT&T UNIX
16624 (circa 1975). The default parameters are suitable for 9-track tapes (6250
16625 bpi), not the high-density media available today (up to 62,182 ftpi).
16626 These defaults must be overridden on the command line to utilize the
16627 capacity of current tape drives.
16629 It is also possible to backup data across the network to a tape drive
16630 attached to another computer with rdump and rrestore. Both programs rely
16631 upon rcmd and ruserok to access the remote tape drive. Therefore, the user
16632 performing the backup must be listed in the .rhosts file on the remote
16633 computer. The arguments to rdump and rrestore must be suitable to use on
16634 the remote computer. When rdumping from a DragonFly computer to an Exabyte
16635 tape drive connected to a Sun called komodo, use:
16637 # /sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1
16639 Beware: there are security implications to allowing .rhosts
16640 authentication. Evaluate your situation carefully.
16642 It is also possible to use dump and restore in a more secure fashion over
16645 Example 12-1. Using dump over ssh
16647 # /sbin/dump -0uan -f - /usr | gzip -2 | ssh1 -c blowfish \
16648 targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz
16650 Or using dump's built-in method, setting the enviroment variable RSH:
16652 Example 12-2. Using dump over ssh with RSH set
16654 # RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0
16656 ----------------------------------------------------------------------
16660 tar(1) also dates back to Version 6 of AT&T UNIX (circa 1975). tar
16661 operates in cooperation with the file system; tar writes files and
16662 directories to tape. tar does not support the full range of options that
16663 are available from cpio(1), but tar does not require the unusual command
16664 pipeline that cpio uses.
16666 Most versions of tar do not support backups across the network. The GNU
16667 version of tar, which DragonFly utilizes, supports remote devices using
16668 the same syntax as rdump. To tar to an Exabyte tape drive connected to a
16669 Sun called komodo, use:
16671 # /usr/bin/tar cf komodo:/dev/nsa8 . 2>&1
16673 For versions without remote device support, you can use a pipeline and rsh
16674 to send the data to a remote tape drive.
16676 # tar cf - . | rsh hostname dd of=tape-device obs=20b
16678 If you are worried about the security of backing up over a network you
16679 should use the ssh command instead of rsh.
16681 ----------------------------------------------------------------------
16685 cpio(1) is the original UNIX file interchange tape program for magnetic
16686 media. cpio has options (among many others) to perform byte-swapping,
16687 write a number of different archive formats, and pipe the data to other
16688 programs. This last feature makes cpio an excellent choice for
16689 installation media. cpio does not know how to walk the directory tree and
16690 a list of files must be provided through stdin.
16692 cpio does not support backups across the network. You can use a pipeline
16693 and rsh to send the data to a remote tape drive.
16695 # for f in directory_list; do
16696 find $f >> backup.list
16698 # cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device"
16700 Where directory_list is the list of directories you want to back up,
16701 user@host is the user/hostname combination that will be performing the
16702 backups, and backup_device is where the backups should be written to
16705 ----------------------------------------------------------------------
16709 pax(1) is IEEE/POSIX's answer to tar and cpio. Over the years the various
16710 versions of tar and cpio have gotten slightly incompatible. So rather than
16711 fight it out to fully standardize them, POSIX created a new archive
16712 utility. pax attempts to read and write many of the various cpio and tar
16713 formats, plus new formats of its own. Its command set more resembles cpio
16716 ----------------------------------------------------------------------
16720 Amanda (Advanced Maryland Network Disk Archiver) is a client/server backup
16721 system, rather than a single program. An Amanda server will backup to a
16722 single tape drive any number of computers that have Amanda clients and a
16723 network connection to the Amanda server. A common problem at sites with a
16724 number of large disks is that the length of time required to backup to
16725 data directly to tape exceeds the amount of time available for the task.
16726 Amanda solves this problem. Amanda can use a ``holding disk'' to backup
16727 several file systems at the same time. Amanda creates ``archive sets'': a
16728 group of tapes used over a period of time to create full backups of all
16729 the file systems listed in Amanda's configuration file. The ``archive
16730 set'' also contains nightly incremental (or differential) backups of all
16731 the file systems. Restoring a damaged file system requires the most recent
16732 full backup and the incremental backups.
16734 The configuration file provides fine control of backups and the network
16735 traffic that Amanda generates. Amanda will use any of the above backup
16736 programs to write the data to tape. Amanda is available as either a port
16737 or a package, it is not installed by default.
16739 ----------------------------------------------------------------------
16743 ``Do nothing'' is not a computer program, but it is the most widely used
16744 backup strategy. There are no initial costs. There is no backup schedule
16745 to follow. Just say no. If something happens to your data, grin and bear
16748 If your time and your data is worth little to nothing, then ``Do nothing''
16749 is the most suitable backup program for your computer. But beware, UNIX is
16750 a useful tool, you may find that within six months you have a collection
16751 of files that are valuable to you.
16753 ``Do nothing'' is the correct backup method for /usr/obj and other
16754 directory trees that can be exactly recreated by your computer. An example
16755 is the files that comprise the HTML or PostScript version of this
16756 Handbook. These document formats have been created from SGML input files.
16757 Creating backups of the HTML or PostScript files is not necessary. The
16758 SGML files are backed up regularly.
16760 ----------------------------------------------------------------------
16762 12.10.7 Which Backup Program Is Best?
16764 dump(8) Period. Elizabeth D. Zwicky torture tested all the backup programs
16765 discussed here. The clear choice for preserving all your data and all the
16766 peculiarities of UNIX file systems is dump. Elizabeth created file systems
16767 containing a large variety of unusual conditions (and some not so unusual
16768 ones) and tested each program by doing a backup and restore of those file
16769 systems. The peculiarities included: files with holes, files with holes
16770 and a block of nulls, files with funny characters in their names,
16771 unreadable and unwritable files, devices, files that change size during
16772 the backup, files that are created/deleted during the backup and more. She
16773 presented the results at LISA V in Oct. 1991. Read the ``Torture-testing
16774 Backup and Archive Programs'' study for more information.
16776 ----------------------------------------------------------------------
16778 12.10.8 Emergency Restore Procedure
16780 12.10.8.1 Before the Disaster
16782 There are only four steps that you need to perform in preparation for any
16783 disaster that may occur.
16785 First, print the disklabel from each of your disks (e.g. disklabel da0 |
16786 lpr), your file system table (/etc/fstab) and all boot messages, two
16789 Second, determine that the boot and fix-it floppies (boot.flp and
16790 fixit.flp) have all your devices. The easiest way to check is to reboot
16791 your machine with the boot floppy in the floppy drive and check the boot
16792 messages. If all your devices are listed and functional, skip on to step
16795 Otherwise, you have to create two custom bootable floppies which have a
16796 kernel that can mount all of your disks and access your tape drive. These
16797 floppies must contain: fdisk, disklabel, newfs, mount, and whichever
16798 backup program you use. These programs must be statically linked. If you
16799 use dump, the floppy must contain restore.
16801 Third, create backup tapes regularly. Any changes that you make after your
16802 last backup may be irretrievably lost. Write-protect the backup tapes.
16804 Fourth, test the floppies (either boot.flp and fixit.flp or the two custom
16805 bootable floppies you made in step two.) and backup tapes. Make notes of
16806 the procedure. Store these notes with the bootable floppy, the printouts
16807 and the backup tapes. You will be so distraught when restoring that the
16808 notes may prevent you from destroying your backup tapes (How? In place of
16809 tar xvf /dev/sa0, you might accidentally type tar cvf /dev/sa0 and
16810 over-write your backup tape).
16812 For an added measure of security, make bootable floppies and two backup
16813 tapes each time. Store one of each at a remote location. A remote location
16814 is NOT the basement of the same office building. A number of firms in the
16815 World Trade Center learned this lesson the hard way. A remote location
16816 should be physically separated from your computers and disk drives by a
16817 significant distance.
16819 Example 12-3. A Script for Creating a Bootable Floppy
16823 # create a restore floppy
16825 # format the floppy
16827 PATH=/bin:/sbin:/usr/sbin:/usr/bin
16832 echo "Bad floppy, please use a new one"
16836 # place boot blocks on the floppy
16838 disklabel -w -B /dev/fd0c fd1440
16841 # newfs the one and only partition
16843 newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/fd0a
16846 # mount the new floppy
16848 mount /dev/fd0a /mnt
16851 # create required directories
16858 mkdir /mnt/mnt # for the root partition
16863 # populate the directories
16865 if [ ! -x /sys/compile/MINI/kernel ]
16868 The MINI kernel does not exist, please create one.
16869 Here is an example config file:
16871 # MINI -- A kernel to get &os; onto a disk.
16878 options INET # needed for _tcp _icmpstat _ipstat
16879 # _udpstat _tcpstat _udb
16880 options FFS #Berkeley Fast File System
16881 options FAT_CURSOR #block cursor in syscons or pccons
16882 options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device
16883 options NCONS=2 #1 virtual consoles
16884 options USERCONFIG #Allow user configuration with -c XXX
16886 config kernel root on da0 swap on da0 and da1 dumps on da0
16891 device fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr
16892 device fd0 at fdc0 drive 0
16898 device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr
16899 device npx0 at isa? port "IO_NPX" irq 13 vector npxintr
16907 pseudo-device loop # required by INET
16908 pseudo-device gzip # Exec gzipped a.out's
16913 cp -f /sys/compile/MINI/kernel /mnt
16915 gzip -c -best /sbin/init > /mnt/sbin/init
16916 gzip -c -best /sbin/fsck > /mnt/sbin/fsck
16917 gzip -c -best /sbin/mount > /mnt/sbin/mount
16918 gzip -c -best /sbin/halt > /mnt/sbin/halt
16919 gzip -c -best /sbin/restore > /mnt/sbin/restore
16921 gzip -c -best /bin/sh > /mnt/bin/sh
16922 gzip -c -best /bin/sync > /mnt/bin/sync
16924 cp /root/.profile /mnt/root
16926 cp -f /dev/MAKEDEV /mnt/dev
16927 chmod 755 /mnt/dev/MAKEDEV
16929 chmod 500 /mnt/sbin/init
16930 chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt
16931 chmod 555 /mnt/bin/sh /mnt/bin/sync
16932 chmod 6555 /mnt/sbin/restore
16935 # create the devices nodes
16947 # create minimum file system table
16949 cat > /mnt/etc/fstab <<EOM
16950 /dev/fd0a / ufs rw 1 1
16954 # create minimum passwd file
16956 cat > /mnt/etc/passwd <<EOM
16957 root:*:0:0:Charlie &:/root:/bin/sh
16960 cat > /mnt/etc/master.passwd <<EOM
16961 root::0:0::0:0:Charlie &:/root:/bin/sh
16964 chmod 600 /mnt/etc/master.passwd
16965 chmod 644 /mnt/etc/passwd
16966 /usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd
16969 # umount the floppy and inform the user
16972 echo "The floppy has been unmounted and is now ready."
16974 ----------------------------------------------------------------------
16976 12.10.8.2 After the Disaster
16978 The key question is: did your hardware survive? You have been doing
16979 regular backups so there is no need to worry about the software.
16981 If the hardware has been damaged, the parts should be replaced before
16982 attempting to use the computer.
16984 If your hardware is okay, check your floppies. If you are using a custom
16985 boot floppy, boot single-user (type -s at the boot: prompt). Skip the
16986 following paragraph.
16988 If you are using the boot.flp and fixit.flp floppies, keep reading. Insert
16989 the boot.flp floppy in the first floppy drive and boot the computer. The
16990 original install menu will be displayed on the screen. Select the
16991 Fixit--Repair mode with CDROM or floppy. option. Insert the fixit.flp when
16992 prompted. restore and the other programs that you need are located in
16995 Recover each file system separately.
16997 Try to mount (e.g. mount /dev/da0a /mnt) the root partition of your first
16998 disk. If the disklabel was damaged, use disklabel to re-partition and
16999 label the disk to match the label that you printed and saved. Use newfs to
17000 re-create the file systems. Re-mount the root partition of the floppy
17001 read-write (mount -u -o rw /mnt). Use your backup program and backup tapes
17002 to recover the data for this file system (e.g. restore vrf /dev/sa0).
17003 Unmount the file system (e.g. umount /mnt). Repeat for each file system
17006 Once your system is running, backup your data onto new tapes. Whatever
17007 caused the crash or data loss may strike again. Another hour spent now may
17008 save you from further distress later.
17010 ----------------------------------------------------------------------
17012 12.11 Network, Memory, and File-Backed File Systems
17014 Reorganized and enhanced by Marc Fonvieille.
17016 Aside from the disks you physically insert into your computer: floppies,
17017 CDs, hard drives, and so forth; other forms of disks are understood by
17018 DragonFly - the virtual disks.
17020 These include network file systems such as the Network File System and
17021 Coda, memory-based file systems and file-backed file systems.
17023 ----------------------------------------------------------------------
17025 12.11.1 File-Backed File System
17027 The utility vnconfig(8) configures and enables vnode pseudo-disk devices.
17028 A vnode is a representation of a file, and is the focus of file activity.
17029 This means that vnconfig(8) uses files to create and operate a file
17030 system. One possible use is the mounting of floppy or CD images kept in
17033 To use vnconfig(8), you need vn(4) support in your kernel configuration
17038 To mount an existing file system image:
17040 Example 12-4. Using vnconfig to Mount an Existing File System Image
17042 # vnconfig vn0 diskimage
17043 # mount /dev/vn0c /mnt
17045 To create a new file system image with vnconfig(8):
17047 Example 12-5. Creating a New File-Backed Disk with vnconfig
17049 # dd if=/dev/zero of=newimage bs=1k count=5k
17052 # vnconfig -s labels -c vn0 newimage
17053 # disklabel -r -w vn0 auto
17055 Warning: 2048 sector(s) in last cylinder unallocated
17056 /dev/vn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors
17057 5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g)
17058 super-block backups (for fsck -b #) at:
17060 # mount /dev/vn0c /mnt
17062 Filesystem 1K-blocks Used Avail Capacity Mounted on
17063 /dev/vn0c 4927 1 4532 0% /mnt
17065 ----------------------------------------------------------------------
17067 12.11.2 Memory-Based File System
17069 The md(4) driver is a simple, efficient means to create memory file
17070 systems. malloc(9) is used to allocate the memory.
17072 Simply take a file system you have prepared with, for example,
17075 Example 12-6. md Memory Disk
17077 # dd if=newimage of=/dev/md0
17080 # mount /dev/md0c /mnt
17082 Filesystem 1K-blocks Used Avail Capacity Mounted on
17083 /dev/md0c 4927 1 4532 0% /mnt
17085 For more details, please refer to md(4) manual page.
17087 ----------------------------------------------------------------------
17089 12.11.3 Detaching a Memory Disk from the System
17091 When a memory-based or file-based file system is not used, you should
17092 release all resources to the system. The first thing to do is to unmount
17093 the file system, then use mdconfig(8) to detach the disk from the system
17094 and release the resources.
17096 For example to detach and free all resources used by /dev/md4:
17100 It is possible to list information about configured md(4) devices in using
17101 the command mdconfig -l.
17103 vnconfig(8) is used to detach the device. For example to detach and free
17104 all resources used by /dev/vn4:
17108 ----------------------------------------------------------------------
17110 12.12 File System Quotas
17112 Quotas are an optional feature of the operating system that allow you to
17113 limit the amount of disk space and/or the number of files a user or
17114 members of a group may allocate on a per-file system basis. This is used
17115 most often on timesharing systems where it is desirable to limit the
17116 amount of resources any one user or group of users may allocate. This will
17117 prevent one user or group of users from consuming all of the available
17120 ----------------------------------------------------------------------
17122 12.12.1 Configuring Your System to Enable Disk Quotas
17124 Before attempting to use disk quotas, it is necessary to make sure that
17125 quotas are configured in your kernel. This is done by adding the following
17126 line to your kernel configuration file:
17130 The stock GENERIC kernel does not have this enabled by default, so you
17131 will have to configure, build and install a custom kernel in order to use
17132 disk quotas. Please refer to Chapter 9 for more information on kernel
17135 Next you will need to enable disk quotas in /etc/rc.conf. This is done by
17138 enable_quotas="YES"
17140 For finer control over your quota startup, there is an additional
17141 configuration variable available. Normally on bootup, the quota integrity
17142 of each file system is checked by the quotacheck(8) program. The
17143 quotacheck(8) facility insures that the data in the quota database
17144 properly reflects the data on the file system. This is a very time
17145 consuming process that will significantly affect the time your system
17146 takes to boot. If you would like to skip this step, a variable in
17147 /etc/rc.conf is made available for the purpose:
17151 Finally you will need to edit /etc/fstab to enable disk quotas on a
17152 per-file system basis. This is where you can either enable user or group
17153 quotas or both for all of your file systems.
17155 To enable per-user quotas on a file system, add the userquota option to
17156 the options field in the /etc/fstab entry for the file system you want to
17157 enable quotas on. For example:
17159 /dev/da1s2g /home ufs rw,userquota 1 2
17161 Similarly, to enable group quotas, use the groupquota option instead of
17162 userquota. To enable both user and group quotas, change the entry as
17165 /dev/da1s2g /home ufs rw,userquota,groupquota 1 2
17167 By default, the quota files are stored in the root directory of the file
17168 system with the names quota.user and quota.group for user and group quotas
17169 respectively. See fstab(5) for more information. Even though the fstab(5)
17170 manual page says that you can specify an alternate location for the quota
17171 files, this is not recommended because the various quota utilities do not
17172 seem to handle this properly.
17174 At this point you should reboot your system with your new kernel. /etc/rc
17175 will automatically run the appropriate commands to create the initial
17176 quota files for all of the quotas you enabled in /etc/fstab, so there is
17177 no need to manually create any zero length quota files.
17179 In the normal course of operations you should not be required to run the
17180 quotacheck(8), quotaon(8), or quotaoff(8) commands manually. However, you
17181 may want to read their manual pages just to be familiar with their
17184 ----------------------------------------------------------------------
17186 12.12.2 Setting Quota Limits
17188 Once you have configured your system to enable quotas, verify that they
17189 really are enabled. An easy way to do this is to run:
17193 You should see a one line summary of disk usage and current quota limits
17194 for each file system that quotas are enabled on.
17196 You are now ready to start assigning quota limits with the edquota(8)
17199 You have several options on how to enforce limits on the amount of disk
17200 space a user or group may allocate, and how many files they may create.
17201 You may limit allocations based on disk space (block quotas) or number of
17202 files (inode quotas) or a combination of both. Each of these limits are
17203 further broken down into two categories: hard and soft limits.
17205 A hard limit may not be exceeded. Once a user reaches his hard limit he
17206 may not make any further allocations on the file system in question. For
17207 example, if the user has a hard limit of 500 blocks on a file system and
17208 is currently using 490 blocks, the user can only allocate an additional 10
17209 blocks. Attempting to allocate an additional 11 blocks will fail.
17211 Soft limits, on the other hand, can be exceeded for a limited amount of
17212 time. This period of time is known as the grace period, which is one week
17213 by default. If a user stays over his or her soft limit longer than the
17214 grace period, the soft limit will turn into a hard limit and no further
17215 allocations will be allowed. When the user drops back below the soft
17216 limit, the grace period will be reset.
17218 The following is an example of what you might see when you run the
17219 edquota(8) command. When the edquota(8) command is invoked, you are placed
17220 into the editor specified by the EDITOR environment variable, or in the vi
17221 editor if the EDITOR variable is not set, to allow you to edit the quota
17226 Quotas for user test:
17227 /usr: blocks in use: 65, limits (soft = 50, hard = 75)
17228 inodes in use: 7, limits (soft = 50, hard = 60)
17229 /usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
17230 inodes in use: 0, limits (soft = 50, hard = 60)
17232 You will normally see two lines for each file system that has quotas
17233 enabled. One line for the block limits, and one line for inode limits.
17234 Simply change the value you want updated to modify the quota limit. For
17235 example, to raise this user's block limit from a soft limit of 50 and a
17236 hard limit of 75 to a soft limit of 500 and a hard limit of 600, change:
17238 /usr: blocks in use: 65, limits (soft = 50, hard = 75)
17242 /usr: blocks in use: 65, limits (soft = 500, hard = 600)
17244 The new quota limits will be in place when you exit the editor.
17246 Sometimes it is desirable to set quota limits on a range of UIDs. This can
17247 be done by use of the -p option on the edquota(8) command. First, assign
17248 the desired quota limit to a user, and then run edquota -p protouser
17249 startuid-enduid. For example, if user test has the desired quota limits,
17250 the following command can be used to duplicate those quota limits for UIDs
17251 10,000 through 19,999:
17253 # edquota -p test 10000-19999
17255 For more information see edquota(8) manual page.
17257 ----------------------------------------------------------------------
17259 12.12.3 Checking Quota Limits and Disk Usage
17261 You can use either the quota(1) or the repquota(8) commands to check quota
17262 limits and disk usage. The quota(1) command can be used to check
17263 individual user or group quotas and disk usage. A user may only examine
17264 his own quota, and the quota of a group he is a member of. Only the
17265 super-user may view all user and group quotas. The repquota(8) command can
17266 be used to get a summary of all quotas and disk usage for file systems
17267 with quotas enabled.
17269 The following is some sample output from the quota -v command for a user
17270 that has quota limits on two file systems.
17272 Disk quotas for user test (uid 1002):
17273 Filesystem blocks quota limit grace files quota limit grace
17274 /usr 65* 50 75 5days 7 50 60
17275 /usr/var 0 50 75 0 50 60
17277 On the /usr file system in the above example, this user is currently 15
17278 blocks over the soft limit of 50 blocks and has 5 days of the grace period
17279 left. Note the asterisk * which indicates that the user is currently over
17282 Normally file systems that the user is not using any disk space on will
17283 not show up in the output from the quota(1) command, even if he has a
17284 quota limit assigned for that file system. The -v option will display
17285 those file systems, such as the /usr/var file system in the above example.
17287 ----------------------------------------------------------------------
17289 12.12.4 Quotas over NFS
17291 Quotas are enforced by the quota subsystem on the NFS server. The
17292 rpc.rquotad(8) daemon makes quota information available to the quota(1)
17293 command on NFS clients, allowing users on those machines to see their
17296 Enable rpc.rquotad in /etc/inetd.conf like so:
17298 rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad
17302 # kill -HUP `cat /var/run/inetd.pid`
17304 ----------------------------------------------------------------------
17306 Chapter 13 The Vinum Volume Manager
17308 Contributed by Greg Lehey.
17312 No matter what disks you have, there will always be limitations:
17314 * They can be too small.
17316 * They can be too slow.
17318 * They can be too unreliable.
17320 ----------------------------------------------------------------------
17322 13.2 Disks Are Too Small
17324 Originally written by Greg Lehey.
17326 Vinum is a so-called Volume Manager, a virtual disk driver that addresses
17327 these three problems. Let us look at them in more detail. Various
17328 solutions to these problems have been proposed and implemented:
17330 Disks are getting bigger, but so are data storage requirements. Often you
17331 will find you want a file system that is bigger than the disks you have
17332 available. Admittedly, this problem is not as acute as it was ten years
17333 ago, but it still exists. Some systems have solved this by creating an
17334 abstract device which stores its data on a number of disks.
17336 ----------------------------------------------------------------------
17338 13.3 Access Bottlenecks
17340 Modern systems frequently need to access data in a highly concurrent
17341 manner. For example, large FTP or HTTP servers can maintain thousands of
17342 concurrent sessions and have multiple 100 Mbit/s connections to the
17343 outside world, well beyond the sustained transfer rate of most disks.
17345 Current disk drives can transfer data sequentially at up to 70 MB/s, but
17346 this value is of little importance in an environment where many
17347 independent processes access a drive, where they may achieve only a
17348 fraction of these values. In such cases it is more interesting to view the
17349 problem from the viewpoint of the disk subsystem: the important parameter
17350 is the load that a transfer places on the subsystem, in other words the
17351 time for which a transfer occupies the drives involved in the transfer.
17353 In any disk transfer, the drive must first position the heads, wait for
17354 the first sector to pass under the read head, and then perform the
17355 transfer. These actions can be considered to be atomic: it does not make
17356 any sense to interrupt them.
17358 Consider a typical transfer of about 10 kB: the current generation of
17359 high-performance disks can position the heads in an average of 3.5 ms. The
17360 fastest drives spin at 15,000 rpm, so the average rotational latency (half
17361 a revolution) is 2 ms. At 70 MB/s, the transfer itself takes about 150 ms,
17362 almost nothing compared to the positioning time. In such a case, the
17363 effective transfer rate drops to a little over 1 MB/s and is clearly
17364 highly dependent on the transfer size.
17366 The traditional and obvious solution to this bottleneck is ``more
17367 spindles'': rather than using one large disk, it uses several smaller
17368 disks with the same aggregate storage space. Each disk is capable of
17369 positioning and transferring independently, so the effective throughput
17370 increases by a factor close to the number of disks used.
17372 The exact throughput improvement is, of course, smaller than the number of
17373 disks involved: although each drive is capable of transferring in
17374 parallel, there is no way to ensure that the requests are evenly
17375 distributed across the drives. Inevitably the load on one drive will be
17376 higher than on another.
17378 The evenness of the load on the disks is strongly dependent on the way the
17379 data is shared across the drives. In the following discussion, it is
17380 convenient to think of the disk storage as a large number of data sectors
17381 which are addressable by number, rather like the pages in a book. The most
17382 obvious method is to divide the virtual disk into groups of consecutive
17383 sectors the size of the individual physical disks and store them in this
17384 manner, rather like taking a large book and tearing it into smaller
17385 sections. This method is called concatenation and has the advantage that
17386 the disks are not required to have any specific size relationships. It
17387 works well when the access to the virtual disk is spread evenly about its
17388 address space. When access is concentrated on a smaller area, the
17389 improvement is less marked. Figure 13-1 illustrates the sequence in which
17390 storage units are allocated in a concatenated organization.
17392 Figure 13-1. Concatenated Organization
17394 An alternative mapping is to divide the address space into smaller,
17395 equal-sized components and store them sequentially on different devices.
17396 For example, the first 256 sectors may be stored on the first disk, the
17397 next 256 sectors on the next disk and so on. After filling the last disk,
17398 the process repeats until the disks are full. This mapping is called
17399 striping or RAID-0 [11]. Striping requires somewhat more effort to locate
17400 the data, and it can cause additional I/O load where a transfer is spread
17401 over multiple disks, but it can also provide a more constant load across
17402 the disks. Figure 13-2 illustrates the sequence in which storage units are
17403 allocated in a striped organization.
17405 Figure 13-2. Striped Organization
17407 ----------------------------------------------------------------------
17409 13.4 Data Integrity
17411 The final problem with current disks is that they are unreliable. Although
17412 disk drive reliability has increased tremendously over the last few years,
17413 they are still the most likely core component of a server to fail. When
17414 they do, the results can be catastrophic: replacing a failed disk drive
17415 and restoring data to it can take days.
17417 The traditional way to approach this problem has been mirroring, keeping
17418 two copies of the data on different physical hardware. Since the advent of
17419 the RAID levels, this technique has also been called RAID level 1 or
17420 RAID-1. Any write to the volume writes to both locations; a read can be
17421 satisfied from either, so if one drive fails, the data is still available
17422 on the other drive.
17424 Mirroring has two problems:
17426 * The price. It requires twice as much disk storage as a non-redundant
17429 * The performance impact. Writes must be performed to both drives, so
17430 they take up twice the bandwidth of a non-mirrored volume. Reads do
17431 not suffer from a performance penalty: it even looks as if they are
17434 An alternative solution is parity, implemented in the RAID levels 2, 3, 4
17435 and 5. Of these, RAID-5 is the most interesting. As implemented in Vinum,
17436 it is a variant on a striped organization which dedicates one block of
17437 each stripe to parity of the other blocks. As implemented by Vinum, a
17438 RAID-5 plex is similar to a striped plex, except that it implements RAID-5
17439 by including a parity block in each stripe. As required by RAID-5, the
17440 location of this parity block changes from one stripe to the next. The
17441 numbers in the data blocks indicate the relative block numbers.
17443 Figure 13-3. RAID-5 Organization
17445 Compared to mirroring, RAID-5 has the advantage of requiring significantly
17446 less storage space. Read access is similar to that of striped
17447 organizations, but write access is significantly slower, approximately 25%
17448 of the read performance. If one drive fails, the array can continue to
17449 operate in degraded mode: a read from one of the remaining accessible
17450 drives continues normally, but a read from the failed drive is
17451 recalculated from the corresponding block from all the remaining drives.
17453 ----------------------------------------------------------------------
17457 In order to address these problems, Vinum implements a four-level
17458 hierarchy of objects:
17460 * The most visible object is the virtual disk, called a volume. Volumes
17461 have essentially the same properties as a UNIX disk drive, though
17462 there are some minor differences. They have no size limitations.
17464 * Volumes are composed of plexes, each of which represent the total
17465 address space of a volume. This level in the hierarchy thus provides
17466 redundancy. Think of plexes as individual disks in a mirrored array,
17467 each containing the same data.
17469 * Since Vinum exists within the UNIX disk storage framework, it would be
17470 possible to use UNIX partitions as the building block for multi-disk
17471 plexes, but in fact this turns out to be too inflexible: UNIX disks
17472 can have only a limited number of partitions. Instead, Vinum
17473 subdivides a single UNIX partition (the drive) into contiguous areas
17474 called subdisks, which it uses as building blocks for plexes.
17476 * Subdisks reside on Vinum drives, currently UNIX partitions. Vinum
17477 drives can contain any number of subdisks. With the exception of a
17478 small area at the beginning of the drive, which is used for storing
17479 configuration and state information, the entire drive is available for
17482 The following sections describe the way these objects provide the
17483 functionality required of Vinum.
17485 ----------------------------------------------------------------------
17487 13.5.1 Volume Size Considerations
17489 Plexes can include multiple subdisks spread over all drives in the Vinum
17490 configuration. As a result, the size of an individual drive does not limit
17491 the size of a plex, and thus of a volume.
17493 ----------------------------------------------------------------------
17495 13.5.2 Redundant Data Storage
17497 Vinum implements mirroring by attaching multiple plexes to a volume. Each
17498 plex is a representation of the data in a volume. A volume may contain
17499 between one and eight plexes.
17501 Although a plex represents the complete data of a volume, it is possible
17502 for parts of the representation to be physically missing, either by design
17503 (by not defining a subdisk for parts of the plex) or by accident (as a
17504 result of the failure of a drive). As long as at least one plex can
17505 provide the data for the complete address range of the volume, the volume
17506 is fully functional.
17508 ----------------------------------------------------------------------
17510 13.5.3 Performance Issues
17512 Vinum implements both concatenation and striping at the plex level:
17514 * A concatenated plex uses the address space of each subdisk in turn.
17516 * A striped plex stripes the data across each subdisk. The subdisks must
17517 all have the same size, and there must be at least two subdisks in
17518 order to distinguish it from a concatenated plex.
17520 ----------------------------------------------------------------------
17522 13.5.4 Which Plex Organization?
17524 Vinum implements two kinds of plex:
17526 * Concatenated plexes are the most flexible: they can contain any number
17527 of subdisks, and the subdisks may be of different length. The plex may
17528 be extended by adding additional subdisks. They require less CPU time
17529 than striped plexes, though the difference in CPU overhead is not
17530 measurable. On the other hand, they are most susceptible to hot spots,
17531 where one disk is very active and others are idle.
17533 * The greatest advantage of striped (RAID-0) plexes is that they reduce
17534 hot spots: by choosing an optimum sized stripe (about 256 kB), you can
17535 even out the load on the component drives. The disadvantages of this
17536 approach are (fractionally) more complex code and restrictions on
17537 subdisks: they must be all the same size, and extending a plex by
17538 adding new subdisks is so complicated that Vinum currently does not
17539 implement it. Vinum imposes an additional, trivial restriction: a
17540 striped plex must have at least two subdisks, since otherwise it is
17541 indistinguishable from a concatenated plex.
17543 Table 13-1 summarizes the advantages and disadvantages of each plex
17546 Table 13-1. Vinum Plex Organizations
17548 +------------------------------------------------------------------------+
17549 | | Minimum | Can add | Must be | |
17550 | Plex type | subdisks | subdisks | equal | Application |
17552 |--------------+----------+----------+---------+-------------------------|
17553 | | | | | Large data storage with |
17554 | concatenated | 1 | yes | no | maximum placement |
17555 | | | | | flexibility and |
17556 | | | | | moderate performance |
17557 |--------------+----------+----------+---------+-------------------------|
17558 | | | | | High performance in |
17559 | striped | 2 | no | yes | combination with highly |
17560 | | | | | concurrent access |
17561 +------------------------------------------------------------------------+
17563 ----------------------------------------------------------------------
17567 Vinum maintains a configuration database which describes the objects known
17568 to an individual system. Initially, the user creates the configuration
17569 database from one or more configuration files with the aid of the vinum(8)
17570 utility program. Vinum stores a copy of its configuration database on each
17571 disk slice (which Vinum calls a device) under its control. This database
17572 is updated on each state change, so that a restart accurately restores the
17573 state of each Vinum object.
17575 ----------------------------------------------------------------------
17577 13.6.1 The Configuration File
17579 The configuration file describes individual Vinum objects. The definition
17580 of a simple volume might be:
17582 drive a device /dev/da3h
17585 sd length 512m drive a
17587 This file describes four Vinum objects:
17589 * The drive line describes a disk partition (drive) and its location
17590 relative to the underlying hardware. It is given the symbolic name a.
17591 This separation of the symbolic names from the device names allows
17592 disks to be moved from one location to another without confusion.
17594 * The volume line describes a volume. The only required attribute is the
17595 name, in this case myvol.
17597 * The plex line defines a plex. The only required parameter is the
17598 organization, in this case concat. No name is necessary: the system
17599 automatically generates a name from the volume name by adding the
17600 suffix .px, where x is the number of the plex in the volume. Thus this
17601 plex will be called myvol.p0.
17603 * The sd line describes a subdisk. The minimum specifications are the
17604 name of a drive on which to store it, and the length of the subdisk.
17605 As with plexes, no name is necessary: the system automatically assigns
17606 names derived from the plex name by adding the suffix .sx, where x is
17607 the number of the subdisk in the plex. Thus Vinum gives this subdisk
17608 the name myvol.p0.s0.
17610 After processing this file, vinum(8) produces the following output:
17612 # vinum -> create config1
17613 Configuration summary
17614 Drives: 1 (4 configured)
17615 Volumes: 1 (4 configured)
17616 Plexes: 1 (8 configured)
17617 Subdisks: 1 (16 configured)
17619 D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)
17621 V myvol State: up Plexes: 1 Size: 512 MB
17623 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17625 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17627 This output shows the brief listing format of vinum(8). It is represented
17628 graphically in Figure 13-4.
17630 Figure 13-4. A Simple Vinum Volume
17632 This figure, and the ones which follow, represent a volume, which contains
17633 the plexes, which in turn contain the subdisks. In this trivial example,
17634 the volume contains one plex, and the plex contains one subdisk.
17636 This particular volume has no specific advantage over a conventional disk
17637 partition. It contains a single plex, so it is not redundant. The plex
17638 contains a single subdisk, so there is no difference in storage allocation
17639 from a conventional disk partition. The following sections illustrate
17640 various more interesting configuration methods.
17642 ----------------------------------------------------------------------
17644 13.6.2 Increased Resilience: Mirroring
17646 The resilience of a volume can be increased by mirroring. When laying out
17647 a mirrored volume, it is important to ensure that the subdisks of each
17648 plex are on different drives, so that a drive failure will not take down
17649 both plexes. The following configuration mirrors a volume:
17651 drive b device /dev/da4h
17654 sd length 512m drive a
17656 sd length 512m drive b
17658 In this example, it was not necessary to specify a definition of drive a
17659 again, since Vinum keeps track of all objects in its configuration
17660 database. After processing this definition, the configuration looks like:
17662 Drives: 2 (4 configured)
17663 Volumes: 2 (4 configured)
17664 Plexes: 3 (8 configured)
17665 Subdisks: 3 (16 configured)
17667 D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)
17668 D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)
17670 V myvol State: up Plexes: 1 Size: 512 MB
17671 V mirror State: up Plexes: 2 Size: 512 MB
17673 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17674 P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
17675 P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
17677 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17678 S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
17679 S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
17681 Figure 13-5 shows the structure graphically.
17683 Figure 13-5. A Mirrored Vinum Volume
17685 In this example, each plex contains the full 512 MB of address space. As
17686 in the previous example, each plex contains only a single subdisk.
17688 ----------------------------------------------------------------------
17690 13.6.3 Optimizing Performance
17692 The mirrored volume in the previous example is more resistant to failure
17693 than an unmirrored volume, but its performance is less: each write to the
17694 volume requires a write to both drives, using up a greater proportion of
17695 the total disk bandwidth. Performance considerations demand a different
17696 approach: instead of mirroring, the data is striped across as many disk
17697 drives as possible. The following configuration shows a volume with a plex
17698 striped across four disk drives:
17700 drive c device /dev/da5h
17701 drive d device /dev/da6h
17703 plex org striped 512k
17704 sd length 128m drive a
17705 sd length 128m drive b
17706 sd length 128m drive c
17707 sd length 128m drive d
17709 As before, it is not necessary to define the drives which are already
17710 known to Vinum. After processing this definition, the configuration looks
17713 Drives: 4 (4 configured)
17714 Volumes: 3 (4 configured)
17715 Plexes: 4 (8 configured)
17716 Subdisks: 7 (16 configured)
17718 D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%)
17719 D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%)
17720 D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%)
17721 D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%)
17723 V myvol State: up Plexes: 1 Size: 512 MB
17724 V mirror State: up Plexes: 2 Size: 512 MB
17725 V striped State: up Plexes: 1 Size: 512 MB
17727 P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
17728 P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
17729 P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
17730 P striped.p1 State: up Subdisks: 1 Size: 512 MB
17732 S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
17733 S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
17734 S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
17735 S striped.p0.s0 State: up PO: 0 B Size: 128 MB
17736 S striped.p0.s1 State: up PO: 512 kB Size: 128 MB
17737 S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB
17738 S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB
17740 Figure 13-6. A Striped Vinum Volume
17742 This volume is represented in Figure 13-6. The darkness of the stripes
17743 indicates the position within the plex address space: the lightest stripes
17744 come first, the darkest last.
17746 ----------------------------------------------------------------------
17748 13.6.4 Resilience and Performance
17750 With sufficient hardware, it is possible to build volumes which show both
17751 increased resilience and increased performance compared to standard UNIX
17752 partitions. A typical configuration file might be:
17755 plex org striped 512k
17756 sd length 102480k drive a
17757 sd length 102480k drive b
17758 sd length 102480k drive c
17759 sd length 102480k drive d
17760 sd length 102480k drive e
17761 plex org striped 512k
17762 sd length 102480k drive c
17763 sd length 102480k drive d
17764 sd length 102480k drive e
17765 sd length 102480k drive a
17766 sd length 102480k drive b
17768 The subdisks of the second plex are offset by two drives from those of the
17769 first plex: this helps ensure that writes do not go to the same subdisks
17770 even if a transfer goes over two drives.
17772 Figure 13-7 represents the structure of this volume.
17774 Figure 13-7. A Mirrored, Striped Vinum Volume
17776 ----------------------------------------------------------------------
17780 As described above, Vinum assigns default names to plexes and subdisks,
17781 although they may be overridden. Overriding the default names is not
17782 recommended: experience with the VERITAS volume manager, which allows
17783 arbitrary naming of objects, has shown that this flexibility does not
17784 bring a significant advantage, and it can cause confusion.
17786 Names may contain any non-blank character, but it is recommended to
17787 restrict them to letters, digits and the underscore characters. The names
17788 of volumes, plexes and subdisks may be up to 64 characters long, and the
17789 names of drives may be up to 32 characters long.
17791 Vinum objects are assigned device nodes in the hierarchy /dev/vinum. The
17792 configuration shown above would cause Vinum to create the following device
17795 * The control devices /dev/vinum/control and /dev/vinum/controld, which
17796 are used by vinum(8) and the Vinum daemon respectively.
17798 * Block and character device entries for each volume. These are the main
17799 devices used by Vinum. The block device names are the name of the
17800 volume, while the character device names follow the BSD tradition of
17801 prepending the letter r to the name. Thus the configuration above
17802 would include the block devices /dev/vinum/myvol, /dev/vinum/mirror,
17803 /dev/vinum/striped, /dev/vinum/raid5 and /dev/vinum/raid10, and the
17804 character devices /dev/vinum/rmyvol, /dev/vinum/rmirror,
17805 /dev/vinum/rstriped, /dev/vinum/rraid5 and /dev/vinum/rraid10. There
17806 is obviously a problem here: it is possible to have two volumes called
17807 r and rr, but there will be a conflict creating the device node
17808 /dev/vinum/rr: is it a character device for volume r or a block device
17809 for volume rr? Currently Vinum does not address this conflict: the
17810 first-defined volume will get the name.
17812 * A directory /dev/vinum/drive with entries for each drive. These
17813 entries are in fact symbolic links to the corresponding disk nodes.
17815 * A directory /dev/vinum/volume with entries for each volume. It
17816 contains subdirectories for each plex, which in turn contain
17817 subdirectories for their component subdisks.
17819 * The directories /dev/vinum/plex, /dev/vinum/sd, and /dev/vinum/rsd,
17820 which contain block device nodes for each plex and block and character
17821 device nodes respectively for each subdisk.
17823 For example, consider the following configuration file:
17825 drive drive1 device /dev/sd1h
17826 drive drive2 device /dev/sd2h
17827 drive drive3 device /dev/sd3h
17828 drive drive4 device /dev/sd4h
17829 volume s64 setupstate
17830 plex org striped 64k
17831 sd length 100m drive drive1
17832 sd length 100m drive drive2
17833 sd length 100m drive drive3
17834 sd length 100m drive drive4
17836 After processing this file, vinum(8) creates the following structure in
17839 brwx------ 1 root wheel 25, 0x40000001 Apr 13 16:46 Control
17840 brwx------ 1 root wheel 25, 0x40000002 Apr 13 16:46 control
17841 brwx------ 1 root wheel 25, 0x40000000 Apr 13 16:46 controld
17842 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 drive
17843 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex
17844 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 rs64
17845 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rsd
17846 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rvol
17847 brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
17848 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd
17849 drwxr-xr-x 3 root wheel 512 Apr 13 16:46 vol
17853 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive1 -> /dev/sd1h
17854 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive2 -> /dev/sd2h
17855 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive3 -> /dev/sd3h
17856 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive4 -> /dev/sd4h
17860 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
17864 crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0
17865 crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1
17866 crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2
17867 crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3
17871 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
17875 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
17876 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
17877 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
17878 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3
17882 brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
17883 drwxr-xr-x 3 root wheel 512 Apr 13 16:46 s64.plex
17885 /dev/vinum/vol/s64.plex:
17887 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
17888 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 s64.p0.sd
17890 /dev/vinum/vol/s64.plex/s64.p0.sd:
17892 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
17893 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
17894 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
17895 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3
17897 Although it is recommended that plexes and subdisks should not be
17898 allocated specific names, Vinum drives must be named. This makes it
17899 possible to move a drive to a different location and still recognize it
17900 automatically. Drive names may be up to 32 characters long.
17902 ----------------------------------------------------------------------
17904 13.7.1 Creating File Systems
17906 Volumes appear to the system to be identical to disks, with one exception.
17907 Unlike UNIX drives, Vinum does not partition volumes, which thus do not
17908 contain a partition table. This has required modification to some disk
17909 utilities, notably newfs(8), which previously tried to interpret the last
17910 letter of a Vinum volume name as a partition identifier. For example, a
17911 disk drive may have a name like /dev/ad0a or /dev/da2h. These names
17912 represent the first partition (a) on the first (0) IDE disk (ad) and the
17913 eighth partition (h) on the third (2) SCSI disk (da) respectively. By
17914 contrast, a Vinum volume might be called /dev/vinum/concat, a name which
17915 has no relationship with a partition name.
17917 Normally, newfs(8) interprets the name of the disk and complains if it
17918 cannot understand it. For example:
17920 # newfs /dev/vinum/concat
17921 newfs: /dev/vinum/concat: can't figure out file system partition
17923 ----------------------------------------------------------------------
17925 13.8 Configuring Vinum
17927 The GENERIC kernel does not contain Vinum. It is possible to build a
17928 special kernel which includes Vinum, but this is not recommended. The
17929 standard way to start Vinum is as a kernel module (kld). You do not even
17930 need to use kldload(8) for Vinum: when you start vinum(8), it checks
17931 whether the module has been loaded, and if it is not, it loads it
17934 ----------------------------------------------------------------------
17938 Vinum stores configuration information on the disk slices in essentially
17939 the same form as in the configuration files. When reading from the
17940 configuration database, Vinum recognizes a number of keywords which are
17941 not allowed in the configuration files. For example, a disk configuration
17942 might contain the following text:
17944 volume myvol state up
17945 volume bigraid state down
17946 plex name myvol.p0 state up org concat vol myvol
17947 plex name myvol.p1 state up org concat vol myvol
17948 plex name myvol.p2 state init org striped 512b vol myvol
17949 plex name bigraid.p0 state initializing org raid5 512b vol bigraid
17950 sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b
17951 sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b
17952 sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b
17953 sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b
17954 sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b
17955 sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b
17956 sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b
17957 sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b
17958 sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b
17959 sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b
17960 sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b
17961 sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b
17962 sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b
17964 The obvious differences here are the presence of explicit location
17965 information and naming (both of which are also allowed, but discouraged,
17966 for use by the user) and the information on the states (which are not
17967 available to the user). Vinum does not store information about drives in
17968 the configuration information: it finds the drives by scanning the
17969 configured disk drives for partitions with a Vinum label. This enables
17970 Vinum to identify drives correctly even if they have been assigned
17971 different UNIX drive IDs.
17973 ----------------------------------------------------------------------
17975 13.8.1.1 Automatic Startup
17977 In order to start Vinum automatically when you boot the system, ensure
17978 that you have the following line in your /etc/rc.conf:
17980 start_vinum="YES" # set to YES to start vinum
17982 If you do not have a file /etc/rc.conf, create one with this content. This
17983 will cause the system to load the Vinum kld at startup, and to start any
17984 objects mentioned in the configuration. This is done before mounting file
17985 systems, so it is possible to automatically fsck(8) and mount file systems
17988 When you start Vinum with the vinum start command, Vinum reads the
17989 configuration database from one of the Vinum drives. Under normal
17990 circumstances, each drive contains an identical copy of the configuration
17991 database, so it does not matter which drive is read. After a crash,
17992 however, Vinum must determine which drive was updated most recently and
17993 read the configuration from this drive. It then updates the configuration
17994 if necessary from progressively older drives.
17996 ----------------------------------------------------------------------
17998 13.9 Using Vinum for the Root Filesystem
18000 For a machine that has fully-mirrored filesystems using Vinum, it is
18001 desirable to also mirror the root filesystem. Setting up such a
18002 configuration is less trivial than mirroring an arbitrary filesystem
18005 * The root filesystem must be available very early during the boot
18006 process, so the Vinum infrastructure must already be available at this
18009 * The volume containing the root filesystem also contains the system
18010 bootstrap and the kernel, which must be read using the host system's
18011 native utilities (e. g. the BIOS on PC-class machines) which often
18012 cannot be taught about the details of Vinum.
18014 In the following sections, the term ``root volume'' is generally used to
18015 describe the Vinum volume that contains the root filesystem. It is
18016 probably a good idea to use the name "root" for this volume, but this is
18017 not technically required in any way. All command examples in the following
18018 sections assume this name though.
18020 ----------------------------------------------------------------------
18022 13.9.1 Starting up Vinum Early Enough for the Root Filesystem
18024 There are several measures to take for this to happen:
18026 * Vinum must be available in the kernel at boot-time. Thus, the method
18027 to start Vinum automatically described in Section 13.8.1.1 is not
18028 applicable to accomplish this task, and the start_vinum parameter must
18029 actually not be set when the following setup is being arranged. The
18030 first option would be to compile Vinum statically into the kernel, so
18031 it is available all the time, but this is usually not desirable. There
18032 is another option as well, to have /boot/loader (Section 7.3.3) load
18033 the vinum kernel module early, before starting the kernel. This can be
18034 accomplished by putting the line
18038 into the file /boot/loader.conf.
18040 * Vinum must be initialized early since it needs to supply the volume
18041 for the root filesystem. By default, the Vinum kernel part is not
18042 looking for drives that might contain Vinum volume information until
18043 the administrator (or one of the startup scripts) issues a vinum start
18046 Vinum must explicitly be told which disks to scan, using a line like
18047 the following one in /boot/loader.conf:
18049 vinum.drives="/dev/da0 /dev/da1"
18051 It is important that all drives are mentioned that could possibly
18052 contain Vinum data. It does not harm if more drives are listed, nor is
18053 it necessary to add each slice and/or partition explicitly, since
18054 Vinum will scan all slices and partitions of the named drives for
18055 valid Vinum headers.
18057 Since the routines used to parse the name of the root filesystem, and
18058 derive the device ID (major/minor number) are only prepared to handle
18059 ``classical'' device names like /dev/ad0s1a, they cannot make any
18060 sense out of a root volume name like /dev/vinum/root. For that reason,
18061 Vinum itself needs to pre-setup the internal kernel parameter that
18062 holds the ID of the root device during its own initialization. This is
18063 requested by passing the name of the root volume in the loader
18064 variable vinum.root. The entry in /boot/loader.conf to accomplish this
18069 Now, when the kernel initialization tries to find out the root device
18070 to mount, it sees whether some kernel module has already
18071 pre-initialized the kernel parameter for it. If that is the case, and
18072 the device claiming the root device matches the major number of the
18073 driver as figured out from the name of the root device string being
18074 passed (that is, "vinum" in our case), it will use the pre-allocated
18075 device ID, instead of trying to figure out one itself. That way,
18076 during the usual automatic startup, it can continue to mount the Vinum
18077 root volume for the root filesystem.
18079 However, when boot -a has been requesting to ask for entering the name
18080 of the root device manually, it must be noted that this routine still
18081 cannot actually parse a name entered there that refers to a Vinum
18082 volume. If any device name is entered that does not refer to a Vinum
18083 device, the mismatch between the major numbers of the pre-allocated
18084 root parameter and the driver as figured out from the given name will
18085 make this routine enter its normal parser, so entering a string like
18086 ufs:da0d will work as expected. Note that if this fails, it is however
18087 no longer possible to re-enter a string like ufs:vinum/root again,
18088 since it cannot be parsed. The only way out is to reboot again, and
18089 start over then. (At the ``askroot'' prompt, the initial /dev/ can
18090 always be omitted.)
18092 By placing the line:
18094 vinum.drives="/dev/da0 /dev/da1"
18096 vinum.autostart="YES"
18098 into /boot/loader.conf, Vinum is instructed to automatically scan all
18099 drives for Vinum information as part of the kernel startup.
18101 It is important that all drives are mentioned that could possibly
18102 contain Vinum data. It does not harm if more drives are listed, nor is
18103 it necessary to add each slice and/or partition explicitly, since
18104 Vinum will scan all slices and partitions of the named drives for
18105 valid Vinum headers.
18107 Vinum itself needs to pre-setup the internal kernel parameter that
18108 holds the ID of the root device during its own initialization. This is
18109 requested by passing the name of the root volume in the loader
18110 variable vinum.root. The entry in /boot/loader.conf to accomplish this
18115 Now, when the kernel initialization tries to find out the root device
18116 to mount, it sees whether some kernel module has already
18117 pre-initialized the kernel parameter for it. If that is the case, and
18118 the device claiming the root device matches the major number of the
18119 driver as figured out from the name of the root device string being
18120 passed (that is, "vinum" in our case), it will use the pre-allocated
18121 device ID, instead of trying to figure out one itself. That way,
18122 during the usual automatic startup, it can continue to mount the Vinum
18123 root volume for the root filesystem.
18125 However, when boot -a has been requesting to ask for entering the name
18126 of the root device manually, it must be noted that this routine still
18127 cannot actually parse a name entered there that refers to a Vinum
18128 volume. If any device name is entered that does not refer to a Vinum
18129 device, the mismatch between the major numbers of the pre-allocated
18130 root parameter and the driver as figured out from the given name will
18131 make this routine enter its normal parser, so entering a string like
18132 ufs:da0d will work as expected. Note that if this fails, it is however
18133 no longer possible to re-enter a string like ufs:vinum/root again,
18134 since it cannot be parsed. The only way out is to reboot again, and
18135 start over then. (At the ``askroot'' prompt, the initial /dev/ can
18136 always be omitted.)
18138 ----------------------------------------------------------------------
18140 13.9.2 Making a Vinum-based Root Volume Accessible to the Bootstrap
18142 Since the current DragonFly bootstrap is very small, and already has the
18143 burden of reading files (like /boot/loader) from the UFS filesystem, it is
18144 sheer impossible to also teach it about internal Vinum structures so it
18145 could parse the Vinum configuration data, and figure out about the
18146 elements of a boot volume itself. Thus, some tricks are necessary to
18147 provide the bootstrap code with the illusion of a standard "a" partition
18148 that contains the root filesystem.
18150 For this to be possible at all, the following requirements must be met for
18153 * The root volume must not be striped or RAID-5.
18155 * The root volume must not contain more than one concatenated subdisk
18158 Note that it is desirable and possible that there are multiple plexes,
18159 each containing one replica of the root filesystem. The bootstrap process
18160 will, however, only use one of these replica for finding the bootstrap and
18161 all the files, until the kernel will eventually mount the root filesystem
18162 itself. Each single subdisk within these plexes will then need its own "a"
18163 partition illusion, for the respective device to become bootable. It is
18164 not strictly needed that each of these faked "a" partitions is located at
18165 the same offset within its device, compared with other devices containing
18166 plexes of the root volume. However, it is probably a good idea to create
18167 the Vinum volumes that way so the resulting mirrored devices are
18168 symmetric, to avoid confusion.
18170 In order to set up these "a" partitions, for each device containing part
18171 of the root volume, the following needs to be done:
18173 1. The location (offset from the beginning of the device) and size of
18174 this device's subdisk that is part of the root volume need to be
18175 examined, using the command
18179 Note that Vinum offsets and sizes are measured in bytes. They must be
18180 divided by 512 in order to obtain the block numbers that are to be
18181 used in the disklabel command.
18185 disklabel -e devname
18187 for each device that participates in the root volume. devname must be
18188 either the name of the disk (like da0) for disks without a slice (aka.
18189 fdisk) table, or the name of the slice (like ad0s1).
18191 If there is already an "a" partition on the device (presumably,
18192 containing a pre-Vinum root filesystem), it should be renamed to
18193 something else, so it remains accessible (just in case), but will no
18194 longer be used by default to bootstrap the system. Note that active
18195 partitions (like a root filesystem currently mounted) cannot be
18196 renamed, so this must be executed either when being booted from a
18197 ``Fixit'' medium, or in a two-step process, where (in a mirrored
18198 situation) the disk that has not been currently booted is being
18201 Then, the offset the Vinum partition on this device (if any) must be
18202 added to the offset of the respective root volume subdisk on this
18203 device. The resulting value will become the "offset" value for the new
18204 "a" partition. The "size" value for this partition can be taken
18205 verbatim from the calculation above. The "fstype" should be 4.2BSD.
18206 The "fsize", "bsize", and "cpg" values should best be chosen to match
18207 the actual filesystem, though they are fairly unimportant within this
18210 That way, a new "a" partition will be established that overlaps the
18211 Vinum partition on this device. Note that the disklabel will only
18212 allow for this overlap if the Vinum partition has properly been marked
18213 using the "vinum" fstype.
18215 3. That's all! A faked "a" partition does exist now on each device that
18216 has one replica of the root volume. It is highly recommendable to
18217 verify the result again, using a command like
18219 fsck -n /dev/devnamea
18221 It should be remembered that all files containing control information must
18222 be relative to the root filesystem in the Vinum volume which, when setting
18223 up a new Vinum root volume, might not match the root filesystem that is
18224 currently active. So in particular, the files /etc/fstab and
18225 /boot/loader.conf need to be taken care of.
18227 At next reboot, the bootstrap should figure out the appropriate control
18228 information from the new Vinum-based root filesystem, and act accordingly.
18229 At the end of the kernel initialization process, after all devices have
18230 been announced, the prominent notice that shows the success of this setup
18233 Mounting root from ufs:/dev/vinum/root
18235 ----------------------------------------------------------------------
18237 13.9.3 Example of a Vinum-based Root Setup
18239 After the Vinum root volume has been set up, the output of vinum l -rv
18240 root could look like:
18243 Subdisk root.p0.s0:
18244 Size: 125829120 bytes (120 MB)
18246 Plex root.p0 at offset 0 (0 B)
18247 Drive disk0 (/dev/da0h) at offset 135680 (132 kB)
18249 Subdisk root.p1.s0:
18250 Size: 125829120 bytes (120 MB)
18252 Plex root.p1 at offset 0 (0 B)
18253 Drive disk1 (/dev/da1h) at offset 135680 (132 kB)
18256 The values to note are 135680 for the offset (relative to partition
18257 /dev/da0h). This translates to 265 512-byte disk blocks in disklabel's
18258 terms. Likewise, the size of this root volume is 245760 512-byte blocks.
18259 /dev/da1h, containing the second replica of this root volume, has a
18262 The disklabel for these devices might look like:
18266 # size offset fstype [fsize bsize bps/cpg]
18267 a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*)
18268 c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*)
18269 h: 71771672 16 vinum # (Cyl. 0*- 4467*)
18272 It can be observed that the "size" parameter for the faked "a" partition
18273 matches the value outlined above, while the "offset" parameter is the sum
18274 of the offset within the Vinum partition "h", and the offset of this
18275 partition within the device (or slice). This is a typical setup that is
18276 necessary to avoid the problem described in Section 13.9.4.3. It can also
18277 be seen that the entire "a" partition is completely within the "h"
18278 partition containing all the Vinum data for this device.
18280 Note that in the above example, the entire device is dedicated to Vinum,
18281 and there is no leftover pre-Vinum root partition, since this has been a
18282 newly set-up disk that was only meant to be part of a Vinum configuration,
18285 ----------------------------------------------------------------------
18287 13.9.4 Troubleshooting
18289 If something goes wrong, a way is needed to recover from the situation.
18290 The following list contains few known pitfalls and solutions.
18292 ----------------------------------------------------------------------
18294 13.9.4.1 System Bootstrap Loads, but System Does Not Boot
18296 If for any reason the system does not continue to boot, the bootstrap can
18297 be interrupted with by pressing the space key at the 10-seconds warning.
18298 The loader variables (like vinum.autostart) can be examined using the
18299 show, and manipulated using set or unset commands.
18301 If the only problem was that the Vinum kernel module was not yet in the
18302 list of modules to load automatically, a simple load vinum will help.
18304 When ready, the boot process can be continued with a boot -as. The options
18305 -as will request the kernel to ask for the root filesystem to mount (-a),
18306 and make the boot process stop in single-user mode (-s), where the root
18307 filesystem is mounted read-only. That way, even if only one plex of a
18308 multi-plex volume has been mounted, no data inconsistency between plexes
18311 At the prompt asking for a root filesystem to mount, any device that
18312 contains a valid root filesystem can be entered. If /etc/fstab had been
18313 set up correctly, the default should be something like
18314 ufs:/dev/vinum/root. A typical alternate choice would be something like
18315 ufs:da0d which could be a hypothetical partition that contains the
18316 pre-Vinum root filesystem. Care should be taken if one of the alias "a"
18317 partitions are entered here that are actually reference to the subdisks of
18318 the Vinum root device, because in a mirrored setup, this would only mount
18319 one piece of a mirrored root device. If this filesystem is to be mounted
18320 read-write later on, it is necessary to remove the other plex(es) of the
18321 Vinum root volume since these plexes would otherwise carry inconsistent
18324 ----------------------------------------------------------------------
18326 13.9.4.2 Only Primary Bootstrap Loads
18328 If /boot/loader fails to load, but the primary bootstrap still loads
18329 (visible by a single dash in the left column of the screen right after the
18330 boot process starts), an attempt can be made to interrupt the primary
18331 bootstrap at this point, using the space key. This will make the bootstrap
18332 stop in stage two, see Section 7.3.2. An attempt can be made here to boot
18333 off an alternate partition, like the partition containing the previous
18334 root filesystem that has been moved away from "a" above.
18336 ----------------------------------------------------------------------
18338 13.9.4.3 Nothing Boots, the Bootstrap Panics
18340 This situation will happen if the bootstrap had been destroyed by the
18341 Vinum installation. Unfortunately, Vinum accidentally currently leaves
18342 only 4 KB at the beginning of its partition free before starting to write
18343 its Vinum header information. However, the stage one and two bootstraps
18344 plus the disklabel embedded between them currently require 8 KB. So if a
18345 Vinum partition was started at offset 0 within a slice or disk that was
18346 meant to be bootable, the Vinum setup will trash the bootstrap.
18348 Similarly, if the above situation has been recovered, for example by
18349 booting from a ``Fixit'' medium, and the bootstrap has been re-installed
18350 using disklabel -B as described in Section 7.3.2, the bootstrap will trash
18351 the Vinum header, and Vinum will no longer find its disk(s). Though no
18352 actual Vinum configuration data or data in Vinum volumes will be trashed
18353 by this, and it would be possible to recover all the data by entering
18354 exact the same Vinum configuration data again, the situation is hard to
18355 fix at all. It would be necessary to move the entire Vinum partition by at
18356 least 4 KB off, in order to have the Vinum header and the system bootstrap
18359 ----------------------------------------------------------------------
18361 Chapter 14 Localization - I18N/L10N Usage and Setup
18363 Contributed by Andrey A. Chernov. Rewritten by Michael C. Wu.
18367 DragonFly is a very distributed project with users and contributors
18368 located all over the world. This chapter discusses the
18369 internationalization and localization features of DragonFly that allow
18370 non-English speaking users to get real work done. There are many aspects
18371 of the i18n implementation in both the system and application levels, so
18372 where applicable we refer the reader to more specific sources of
18375 After reading this chapter, you will know:
18377 * How different languages and locales are encoded on modern operating
18380 * How to set the locale for your login shell.
18382 * How to configure your console for non-English languages.
18384 * How to use X Window System effectively with different languages.
18386 * Where to find more information about writing i18n-compliant
18389 Before reading this chapter, you should:
18391 * Know how to install additional third-party applications (Chapter 4).
18393 ----------------------------------------------------------------------
18397 14.2.1 What Is I18N/L10N?
18399 Developers shortened internationalization into the term I18N, counting the
18400 number of letters between the first and the last letters of
18401 internationalization. L10N uses the same naming scheme, coming from
18402 ``localization''. Combined together, I18N/L10N methods, protocols, and
18403 applications allow users to use languages of their choice.
18405 I18N applications are programmed using I18N kits under libraries. It
18406 allows for developers to write a simple file and translate displayed menus
18407 and texts to each language. We strongly encourage programmers to follow
18410 ----------------------------------------------------------------------
18412 14.2.2 Why Should I Use I18N/L10N?
18414 I18N/L10N is used whenever you wish to either view, input, or process data
18415 in non-English languages.
18417 ----------------------------------------------------------------------
18419 14.2.3 What Languages Are Supported in the I18N Effort?
18421 I18N and L10N are not DragonFly specific. Currently, one can choose from
18422 most of the major languages of the World, including but not limited to:
18423 Chinese, German, Japanese, Korean, French, Russian, Vietnamese and others.
18425 ----------------------------------------------------------------------
18427 14.3 Using Localization
18429 In all its splendor, I18N is not DragonFly-specific and is a convention.
18430 We encourage you to help DragonFly in following this convention.
18432 Localization settings are based on three main terms: Language Code,
18433 Country Code, and Encoding. Locale names are constructed from these parts
18436 LanguageCode_CountryCode.Encoding
18438 ----------------------------------------------------------------------
18440 14.3.1 Language and Country Codes
18442 In order to localize a DragonFly system to a specific language (or any
18443 other I18N-supporting UNIX like systems), the user needs to find out the
18444 codes for the specify country and language (country codes tell
18445 applications what variation of given language to use). In addition, web
18446 browsers, SMTP/POP servers, web servers, etc. make decisions based on
18447 them. The following are examples of language/country codes:
18449 Language/Country Code Description
18450 en_US English - United States
18451 ru_RU Russian for Russia
18452 zh_TW Traditional Chinese for Taiwan
18454 ----------------------------------------------------------------------
18458 Some languages use non-ASCII encodings that are 8-bit, wide or multibyte
18459 characters, see multibyte(3) for more details. Older applications do not
18460 recognize them and mistake them for control characters. Newer applications
18461 usually do recognize 8-bit characters. Depending on the implementation,
18462 users may be required to compile an application with wide or multibyte
18463 characters support, or configure it correctly. To be able to input and
18464 process wide or multibyte characters, the FreeBSD Ports collection has
18465 provided each language with different programs. Refer to the I18N
18466 documentation in the respective FreeBSD Port.
18468 Specifically, the user needs to look at the application documentation to
18469 decide on how to configure it correctly or to pass correct values into the
18470 configure/Makefile/compiler.
18472 Some things to keep in mind are:
18474 * Language specific single C chars character sets (see multibyte(3)),
18475 e.g. ISO-8859-1, ISO-8859-15, KOI8-R, CP437.
18477 * Wide or multibyte encodings, e.g. EUC, Big5.
18479 You can check the active list of character sets at the IANA Registry.
18481 Note: DragonFly uses X11-compatible locale encodings instead.
18483 ----------------------------------------------------------------------
18485 14.3.3 I18N Applications
18487 In the FreeBSD Ports and Package system, I18N applications have been named
18488 with I18N in their names for easy identification. However, they do not
18489 always support the language needed.
18491 ----------------------------------------------------------------------
18493 14.3.4 Setting Locale
18495 Usually it is sufficient to export the value of the locale name as LANG in
18496 the login shell. This could be done in the user's ~/.login_conf file or in
18497 the startup file of the user's shell (~/.profile, ~/.bashrc, ~/.cshrc).
18498 There is no need to set the locale subsets such as LC_CTYPE, LC_CTIME.
18499 Please refer to language-specific DragonFly documentation for more
18502 You should set the following two environment variables in your
18503 configuration files:
18505 * LANG for POSIX setlocale(3) family functions
18507 * MM_CHARSET for applications' MIME character set
18509 This includes the user shell configuration, the specific application
18510 configuration, and the X11 configuration.
18512 ----------------------------------------------------------------------
18514 14.3.4.1 Setting Locale Methods
18516 There are two methods for setting locale, and both are described below.
18517 The first (recommended one) is by assigning the environment variables in
18518 login class, and the second is by adding the environment variable
18519 assignments to the system's shell startup file.
18521 ----------------------------------------------------------------------
18523 14.3.4.1.1 Login Classes Method
18525 This method allows environment variables needed for locale name and MIME
18526 character sets to be assigned once for every possible shell instead of
18527 adding specific shell assignments to each shell's startup file. User Level
18528 Setup can be done by an user himself and Administrator Level Setup require
18529 superuser privileges.
18531 ----------------------------------------------------------------------
18533 14.3.4.1.1.1 User Level Setup
18535 Here is a minimal example of a .login_conf file in user's home directory
18536 which has both variables set for Latin-1 encoding:
18539 :charset=ISO-8859-1:\
18540 :lang=de_DE.ISO8859-1:
18542 Here is an example of a .login_conf that sets the variables for
18543 Traditional Chinese in BIG-5 encoding. Notice the many more variables set
18544 because some software does not respect locale variables correctly for
18545 Chinese, Japanese, and Korean.
18547 #Users who do not wish to use monetary units or time formats
18548 #of Taiwan can manually change each variable
18551 :lc_all=zh_TW.Big:\
18552 :lc_collate=zh_TW.Big5:\
18553 :lc_ctype=zh_TW.Big5:\
18554 :lc_messages=zh_TW.Big5:\
18555 :lc_monetary=zh_TW.Big5:\
18556 :lc_numeric=zh_TW.Big5:\
18557 :lc_time=zh_TW.Big5:\
18559 :xmodifiers="@im=xcin": #Setting the XIM Input Server
18561 See Administrator Level Setup and login.conf(5) for more details.
18563 ----------------------------------------------------------------------
18565 14.3.4.1.1.2 Administrator Level Setup
18567 Verify that the user's login class in /etc/login.conf sets the correct
18568 language. Make sure these settings appear in /etc/login.conf:
18570 language_name:accounts_title:\
18571 :charset=MIME_charset:\
18572 :lang=locale_name:\
18575 So sticking with our previous example using Latin-1, it would look like
18578 german:German Users Accounts:\
18579 :charset=ISO-8859-1:\
18580 :lang=de_DE.ISO8859-1:\
18583 Changing Login Classes with vipw(8)
18585 Use vipw to add new users, and make the entry look like this:
18587 user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh
18589 Changing Login Classes with adduser(8)
18591 Use adduser to add new users, and do the following:
18593 * Set defaultclass = language in /etc/adduser.conf. Keep in mind you
18594 must enter a default class for all users of other languages in this
18597 * An alternative variant is answering the specified language each time
18600 Enter login class: default []:
18602 appears from adduser(8).
18604 * Another alternative is to use the following for each user of a
18605 different language that you wish to add:
18607 # adduser -class language
18609 Changing Login Classes with pw(8)
18611 If you use pw(8) for adding new users, call it in this form:
18613 # pw useradd user_name -L language
18615 ----------------------------------------------------------------------
18617 14.3.4.1.2 Shell Startup File Method
18619 Note: This method is not recommended because it requires a different
18620 setup for each possible shell program chosen. Use the Login Class Method
18623 To add the locale name and MIME character set, just set the two
18624 environment variables shown below in the /etc/profile and/or
18625 /etc/csh.login shell startup files. We will use the German language as an
18630 LANG=de_DE.ISO8859-1; export LANG
18631 MM_CHARSET=ISO-8859-1; export MM_CHARSET
18633 Or in /etc/csh.login:
18635 setenv LANG de_DE.ISO8859-1
18636 setenv MM_CHARSET ISO-8859-1
18638 Alternatively, you can add the above instructions to
18639 /usr/share/skel/dot.profile (similar to what was used in /etc/profile
18640 above), or /usr/share/skel/dot.login (similar to what was used in
18641 /etc/csh.login above).
18647 LANG=de_DE.ISO8859-1; export LANG
18651 setenv LANG de_DE.ISO8859-1
18653 Depending on your shell (see above).
18655 ----------------------------------------------------------------------
18657 14.3.5 Console Setup
18659 For all single C chars character sets, set the correct console fonts in
18660 /etc/rc.conf for the language in question with:
18666 The font_name here is taken from the /usr/share/syscons/fonts directory,
18667 without the .fnt suffix.
18669 Also be sure to set the correct keymap and screenmap for your single C
18670 chars character set. You can add the following to /etc/rc.conf:
18672 scrnmap=screenmap_name
18674 keychange="fkey_number sequence"
18676 The screenmap_name here is taken from the /usr/share/syscons/scrnmaps
18677 directory, without the .scm suffix. A screenmap with a corresponding
18678 mapped font is usually needed as a workaround for expanding bit 8 to bit 9
18679 on a VGA adapter's font character matrix in pseudographics area, i.e., to
18680 move letters out of that area if screen font uses a bit 8 column.
18682 If you have the moused daemon enabled by setting the following in your
18685 moused_enable="YES"
18687 then examine the mouse cursor information in the next paragraph.
18689 By default the mouse cursor of the syscons(4) driver occupies the
18690 0xd0-0xd3 range in the character set. If your language uses this range,
18691 you need to move the cursor's range outside of it. To enable this
18692 workaround, insert the following line into your kernel configuration:
18694 options SC_MOUSE_CHAR=0x03
18696 Insert the following line into /etc/rc.conf:
18700 The keymap_name here is taken from the /usr/share/syscons/keymaps
18701 directory, without the .kbd suffix. If you're uncertain which keymap to
18702 use, you use can kbdmap(1) to test keymaps without rebooting.
18704 The keychange is usually needed to program function keys to match the
18705 selected terminal type because function key sequences cannot be defined in
18708 Also be sure to set the correct console terminal type in /etc/ttys for all
18709 ttyv* entries. Current pre-defined correspondences are:
18711 Character Set Terminal Type
18712 ISO-8859-1 or ISO-8859-15 cons25l1
18713 ISO-8859-2 cons25l2
18714 ISO-8859-7 cons25l7
18717 CP437 (VGA default) cons25
18720 For wide or multibyte characters languages, use the correct FreeBSD port
18721 in your /usr/ports/language directory. Some ports appear as console while
18722 the system sees it as serial vtty's, hence you must reserve enough vtty's
18723 for both X11 and the pseudo-serial console. Here is a partial list of
18724 applications for using other languages in console:
18727 Traditional Chinese (BIG-5) chinese/big5con
18728 Japanese japanese/ja-kon2-* or japanese/Mule_Wnn
18729 Korean korean/ko-han
18731 ----------------------------------------------------------------------
18735 Although X11 is not part of DragonFly, we have included some information
18736 here for DragonFly users. For more details, refer to the XFree86 web site
18737 or whichever X11 Server you use.
18739 In ~/.Xresources, you can additionally tune application specific I18N
18740 settings (e.g., fonts, menus, etc.).
18742 ----------------------------------------------------------------------
18744 14.3.6.1 Displaying Fonts
18746 Install the X11 TrueType Common server (x11-servers/XttXF86srv-common) and
18747 install the language TrueType fonts. Setting the correct locale should
18748 allow you to view your selected language in menus and such.
18750 ----------------------------------------------------------------------
18752 14.3.6.2 Inputting Non-English Characters
18754 The X11 Input Method (XIM) Protocol is a new standard for all X11 clients.
18755 All X11 applications should be written as XIM clients that take input from
18756 XIM Input servers. There are several XIM servers available for different
18759 ----------------------------------------------------------------------
18761 14.3.7 Printer Setup
18763 Some single C chars character sets are usually hardware coded into
18764 printers. Wide or multibyte character sets require special setup and we
18765 recommend using apsfilter. You may also convert the document to PostScript
18766 or PDF formats using language specific converters.
18768 ----------------------------------------------------------------------
18770 14.3.8 Kernel and File Systems
18772 The DragonFly fast filesystem (FFS) is 8-bit clean, so it can be used with
18773 any single C chars character set (see multibyte(3)), but there is no
18774 character set name stored in the filesystem; i.e., it is raw 8-bit and
18775 does not know anything about encoding order. Officially, FFS does not
18776 support any form of wide or multibyte character sets yet. However, some
18777 wide or multibyte character sets have independent patches for FFS enabling
18778 such support. They are only temporary unportable solutions or hacks and we
18779 have decided to not include them in the source tree. Refer to respective
18780 languages' web sites for more informations and the patch files.
18782 The DragonFly MS-DOS filesystem has the configurable ability to convert
18783 between MS-DOS, Unicode character sets and chosen DragonFly filesystem
18784 character sets. See mount_msdos(8) for details.
18786 ----------------------------------------------------------------------
18788 14.4 Compiling I18N Programs
18790 Many FreeBSD Ports have been ported with I18N support. Some of them are
18791 marked with -I18N in the port name. These and many other programs have
18792 built in support for I18N and need no special consideration.
18794 However, some applications such as MySQL need to be have the Makefile
18795 configured with the specific charset. This is usually done in the Makefile
18796 or done by passing a value to configure in the source.
18798 ----------------------------------------------------------------------
18800 14.5 Localizing DragonFly to Specific Languages
18802 14.5.1 Russian Language (KOI8-R Encoding)
18804 Originally contributed by Andrey A. Chernov.
18806 For more information about KOI8-R encoding, see the KOI8-R References
18807 (Russian Net Character Set).
18809 ----------------------------------------------------------------------
18811 14.5.1.1 Locale Setup
18813 Put the following lines into your ~/.login_conf file:
18817 :lang=ru_RU.KOI8-R:
18819 See earlier in this chapter for examples of setting up the locale.
18821 ----------------------------------------------------------------------
18823 14.5.1.2 Console Setup
18825 * Add the following line to your kernel configuration file:
18827 options SC_MOUSE_CHAR=0x03
18829 Insert the following line into /etc/rc.conf:
18833 * Use following settings in /etc/rc.conf:
18836 scrnmap="koi8-r2cp866"
18837 font8x16="cp866b-8x16"
18838 font8x14="cp866-8x14"
18839 font8x8="cp866-8x8"
18841 * For each ttyv* entry in /etc/ttys, use cons25r as the terminal type.
18843 See earlier in this chapter for examples of setting up the console.
18845 ----------------------------------------------------------------------
18847 14.5.1.3 Printer Setup
18849 Since most printers with Russian characters come with hardware code page
18850 CP866, a special output filter is needed to convert from KOI8-R to CP866.
18851 Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A
18852 Russian printer /etc/printcap entry should look like:
18854 lp|Russian local line printer:\
18855 :sh:of=/usr/libexec/lpr/ru/koi2alt:\
18856 :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
18858 See printcap(5) for a detailed description.
18860 ----------------------------------------------------------------------
18862 14.5.1.4 MS-DOS(R) FS and Russian Filenames
18864 The following example fstab(5) entry enables support for Russian filenames
18865 in mounted MS-DOS filesystems:
18867 /dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0
18869 The option -L selects the locale name used, and -W sets the character
18870 conversion table. To use the -W option, be sure to mount /usr before the
18871 MS-DOS partition because the conversion tables are located in
18872 /usr/libdata/msdosfs. For more informations, see the mount_msdos(8) manual
18875 ----------------------------------------------------------------------
18879 1. Do non-X locale setup first as described.
18881 Note: The Russian KOI8-R locale may not work with old XFree86
18882 releases (lower than 3.3). XFree86 4.X is now the default version of
18883 the X Window System on DragonFly. This should not be an issue unless
18884 you explicitly install an older version of XFree86.
18886 2. Go to the russian/X.language directory and issue the following
18891 The above port installs the latest version of the KOI8-R fonts.
18892 XFree86 3.3 already has some KOI8-R fonts, but these are scaled
18895 Check the "Files" section in your /etc/XF86Config file. The following
18896 lines must be added before any other FontPath entries:
18898 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
18899 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
18900 FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"
18902 If you use a high resolution video mode, swap the 75 dpi and 100 dpi
18905 3. To activate a Russian keyboard, add the following to the "Keyboard"
18906 section of your XF86Config file.
18911 XkbOptions "grp:caps_toggle"
18915 Option "XkbLayout" "ru"
18916 Option "XkbOptions" "grp:caps_toggle"
18918 Also make sure that XkbDisable is turned off (commented out) there.
18920 The RUS/LAT switch will be CapsLock. The old CapsLock function is
18921 still available via Shift+CapsLock (in LAT mode only).
18923 If you have ``Windows'' keys on your keyboard, and notice that some
18924 non-alphabetical keys are mapped incorrectly in RUS mode, add the
18925 following line in your XF86Config file.
18929 XkbVariant "winkeys"
18933 Option "XkbVariant" "winkeys"
18935 Note: The Russian XKB keyboard may not work with old XFree86
18936 versions, see the above note for more information. The Russian XKB
18937 keyboard may also not work with non-localized applications as well.
18938 Minimally localized applications should call a XtSetLanguageProc
18939 (NULL, NULL, NULL); function early in the program. See KOI8-R for X
18940 Window for more instructions on localizing X11 applications.
18942 ----------------------------------------------------------------------
18944 14.5.2 Traditional Chinese Localization for Taiwan
18946 The FreeBSD-Taiwan Project has an I18N/L10N tutorial for FreeBSD at
18947 http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/ using many Chinese ports.
18948 Much of that project can apply to DragonFly. The editor for the
18949 zh-L10N-tut is Clive Lin <Clive@CirX.org>. You can also cvsup the
18950 following collections at freebsd.sinica.edu.tw:
18952 Collection Description
18953 outta-port tag=. Beta-quality ports collection for Chinese
18954 zh-L10N-tut tag=. Localizing FreeBSD Tutorial in BIG-5 Traditional Chinese
18955 zh-doc tag=. FreeBSD Documentation Translation to BIG-5 Traditional
18958 Chuan-Hsing Shen <s874070@mail.yzu.edu.tw> has created the Chinese FreeBSD
18959 Collection (CFC) using FreeBSD-Taiwan's zh-L10N-tut. The packages and the
18960 script files are available at
18961 ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/.
18963 ----------------------------------------------------------------------
18965 14.5.3 German Language Localization (for All ISO 8859-1 Languages)
18967 Slaven Rezic <eserte@cs.tu-berlin.de> wrote a tutorial how to use umlauts
18968 on a FreeBSD machine. The tutorial is written in German and available at
18969 http://www.de.FreeBSD.org/de/umlaute/.
18971 ----------------------------------------------------------------------
18973 14.5.4 Japanese and Korean Language Localization
18975 For Japanese, refer to http://www.jp.FreeBSD.org/, and for Korean, refer
18976 to http://www.kr.FreeBSD.org/.
18978 ----------------------------------------------------------------------
18980 14.5.5 Non-English DragonFly Documentation
18982 Non-English documentation will be made available as it is created, at the
18983 main site or in /usr/share/doc.
18985 ----------------------------------------------------------------------
18987 Chapter 15 Desktop Applications
18989 Contributed by Christophe Juniet.
18993 DragonFly can run a wide variety of desktop applications, such as browsers
18994 and word processors. Most of these are available as packages or can be
18995 automatically built from the ports collection. Many new users expect to
18996 find these kinds of applications on their desktop. This chapter will show
18997 you how to install some popular desktop applications effortlessly, either
18998 from their packages or from the ports collection.
19000 Warning: This chapter contains a number of outdated references to the
19001 FreeBSD ports collection. Most instructions still apply to pkgsrc, but
19002 proceed with caution until this chapter is updated.
19004 Note that when installing programs from the ports, they are compiled from
19005 source. This can take a very long time, depending on what you are
19006 compiling and the processing power of your machine(s). If building from
19007 source takes a prohibitively long amount of time for you, you can install
19008 most of the programs of the ports collection from pre-built packages.
19010 As DragonFly features Linux binary compatibility, many applications
19011 originally developed for Linux are available for your desktop. It is
19012 strongly recommended that you read Chapter 22 before installing any of the
19013 Linux applications. Many of the ports using the Linux binary compatibility
19014 start with ``linux-''. Remember this when you search for a particular
19015 port, for instance with whereis(1). In the following text, it is assumed
19016 that you have enabled Linux binary compatibility before installing any of
19017 the Linux applications.
19019 Here are the categories covered by this chapter:
19021 * Browsers (such as Mozilla, Netscape, Opera)
19023 * Productivity (such as KOffice, AbiWord, The GIMP, OpenOffice.org)
19025 * Document Viewers (such as Acrobat Reader(R), gv, Xpdf, GQview)
19027 * Finance (such as GnuCash, Gnumeric, Abacus)
19029 Before reading this chapter, you should:
19031 * Know how to install additional third-party software (Chapter 4).
19033 * Know how to install additional Linux software (Chapter 22).
19035 For information on how to get a multimedia environment, read Chapter 16.
19036 If you want to set up and use electronic mail, please refer to Chapter 20.
19038 ----------------------------------------------------------------------
19042 DragonFly does not come with a particular browser pre-installed. Instead,
19043 the www directory of the ports collection contains a lot of browsers ready
19044 to be installed. If you do not have time to compile everything (this can
19045 take a very long time in some cases) many of them are available as
19048 KDE and GNOME already provide HTML browsers. Please refer to Section 5.7
19049 for more information on how to set up these complete desktops.
19051 If you are looking for light-weight browsers, you should investigate the
19052 ports collection for www/dillo, www/links, or www/w3m.
19054 This section covers these applications:
19056 +------------------------------------------------------------------------+
19057 | Application | Resources | Installation | Major Dependencies |
19058 | Name | Needed | from Ports | |
19059 |-------------+-----------+--------------+-------------------------------|
19060 | Mozilla | heavy | heavy | Gtk+ |
19061 |-------------+-----------+--------------+-------------------------------|
19062 | Netscape | heavy | light | Linux Binary Compatibility |
19063 |-------------+-----------+--------------+-------------------------------|
19064 | | | | FreeBSD version (should work |
19065 | | | | on DragonFly): None. Linux |
19066 | Opera | light | light | version: Linux Binary |
19067 | | | | Compatibility and |
19068 | | | | linux-openmotif |
19069 +------------------------------------------------------------------------+
19071 ----------------------------------------------------------------------
19075 Mozilla is perhaps the most suitable browser for your DragonFly Desktop.
19076 It is modern and stable. It features a very standards-compliant HTML
19077 display engine. It provides a mail and news reader. It even has a HTML
19078 composer if you plan to write some web pages yourself. Users of Netscape
19079 will recognize the similarities with Communicator suite, as both browsers
19080 shared the same basis.
19082 On slow machines, with a CPU speed less than 233MHz or with less than 64MB
19083 of RAM, Mozilla can be too resource-consuming to be fully usable. You may
19084 want to look at the Opera browser instead, described a little later in
19087 The Mozilla package from the network by:
19091 If the package is not available, and you have enough time and disk space,
19092 you can get the source for Mozilla, compile it and install it on your
19093 system. This is accomplished by:
19095 # cd /usr/ports/www/mozilla
19096 # make install clean
19098 The Mozilla port ensures a correct initialization by running the chrome
19099 registry setup with root privileges. However, if you want to fetch some
19100 add-ons like mouse gestures, you must run Mozilla as root to get them
19101 properly installed.
19103 Once you have completed the installation of Mozilla, you do not need to be
19104 root any longer. You can start Mozilla as a browser by typing:
19108 You can start it directly as a mail and news reader as shown below:
19112 ----------------------------------------------------------------------
19114 15.2.2 Mozilla, Java(TM), and Macromedia(R) Flash(TM)
19116 Contributed by Tom Rhodes.
19118 Installing Mozilla is simple, but unfortunately installing Mozilla with
19119 support for add-ons like Java(TM) and Macromedia(R) Flash(TM) consumes
19120 both time and disk space.
19122 The first thing is to download the files which will be used with Mozilla.
19123 Take your current web browser up to
19124 http://www.sun.com/software/java2/download.html and create an account on
19125 their website. Remember to save the username and password from here as it
19126 may be needed in the future. Download a copy of the file
19127 j2sdk-1_3_1-src.tar.gz and place this in /usr/ports/distfiles/ as the port
19128 will not fetch it automatically. This is due to license restrictions.
19129 While we are here, download the ``java environment'' from
19130 http://java.sun.com/webapps/download/Display?BundleId=7905. The filename
19131 is j2sdk-1_3_1_08-linux-i586.bin and is large (about 25 megabytes!). Like
19132 before, this file must be placed into /usr/ports/distfiles/. Finally
19133 download a copy of the ``java patchkit'' from
19134 http://www.eyesbeyond.com/freebsddom/java/ and place it into
19135 /usr/ports/distfiles/.
19137 Install the java/jdk13 port with the standard make install clean and then
19138 install the www/flashpluginwrapper port. This port requires
19139 emulators/linux_base which is a large port. True that other Flash plugins
19140 exist, however they have not worked for me.
19142 Install the www/mozilla port, if Mozilla is not already installed.
19144 Now copy the Flash plug-in files with:
19146 # cp /usr/local/lib/flash/libflashplayer.so \
19147 /usr/X11R6/lib/browser_plugins/libflashplayer_linux.so
19149 # cp /usr/local/lib/flash/ShockwaveFlash.class \
19150 /usr/X11R6/lib/browser_plugins/
19152 Now add the following lines to the top of (but right under #!/bin/sh)
19153 Mozilla startup script: /usr/X11R6/bin/mozilla.
19155 LD_PRELOAD=/usr/local/lib/libflashplayer.so.1
19158 This will enable the Flash plug-in.
19160 Now just start Mozilla with:
19164 And access the About Plug-ins option from the Help menu. A list should
19165 appear with all the currently available plugins. Java and Shockwave(R)
19166 Flash should both be listed.
19168 ----------------------------------------------------------------------
19172 The ports collection contains several versions of the Netscape browser.
19173 Since the native FreeBSD ones contain a serious security bug, installing
19174 them is strongly discouraged. Instead, use a more recent Linux or DIGITAL
19177 The latest stable release of the Netscape browser is Netscape 7. It can be
19178 installed from the ports collection:
19180 # cd /usr/ports/www/netscape7
19181 # make install clean
19183 There are localized versions in the French, German, and Japanese
19186 Caution: Netscape 4.x versions are not recommended because they are not
19187 compliant with today's standards. However, Netscape 7.x and newer
19188 versions are only available for the i386 platform.
19190 ----------------------------------------------------------------------
19194 Opera is a very fast, full-featured, and standards-compliant browser. It
19195 comes in a version that runs under Linux emulation. There is a no-cost
19196 version of the browser that displays advertising and an ad-free version
19197 that can be purchased on the Opera web site.
19199 To browse the Web with Opera, install the package:
19203 Some FTP sites do not have all the packages, but the same result can be
19204 obtained with the ports collection by typing:
19206 # cd /usr/ports/www/opera
19207 # make install clean
19209 ----------------------------------------------------------------------
19213 When it comes to productivity, new users often look for a good office
19214 suite or a friendly word processor. While some desktop environments like
19215 KDE already provide an office suite, there is no default application.
19216 DragonFly provides all that is needed, regardless of your desktop
19219 This section covers these applications:
19221 +------------------------------------------------------------------------+
19222 | Application Name | Resources | Installation | Major Dependencies |
19223 | | Needed | from Ports | |
19224 |------------------+-----------+--------------+--------------------------|
19225 | KOffice | light | heavy | KDE |
19226 |------------------+-----------+--------------+--------------------------|
19227 | AbiWord | light | light | Gtk+ or GNOME |
19228 |------------------+-----------+--------------+--------------------------|
19229 | The Gimp | light | heavy | Gtk+ |
19230 |------------------+-----------+--------------+--------------------------|
19231 | OpenOffice.org | heavy | huge | GCC 3.1, JDK(TM) 1.3, |
19233 +------------------------------------------------------------------------+
19235 ----------------------------------------------------------------------
19239 The KDE community has provided its desktop environment with an office
19240 suite which can be used outside KDE. It includes the four standard
19241 components that can be found in other office suites. KWord is the word
19242 processor, KSpread is the spreadsheet program, KPresenter manages slide
19243 presentations, and Kontour lets you draw graphical documents.
19245 Before installing the latest KOffice, make sure you have an up-to-date
19248 To install KOffice as a package, issue the following command:
19252 If the package is not available, you can use the ports collection. For
19253 instance, to install KOffice for KDE3, do:
19255 # cd /usr/ports/editors/koffice-kde3
19256 # make install clean
19258 ----------------------------------------------------------------------
19262 AbiWord is a free word processing program similar in look and feel to
19263 Microsoft Word. It is suitable for typing papers, letters, reports, memos,
19264 and so forth. It is very fast, contains many features, and is very
19267 AbiWord can import or export many file formats, including some proprietary
19268 ones like Microsoft .doc.
19270 AbiWord is available as a package. You can install it by:
19274 If the package is not available, it can be compiled from the ports
19275 collection. The ports collection should be more up to date. It can be done
19278 # cd /usr/ports/editors/AbiWord
19279 # make install clean
19281 ----------------------------------------------------------------------
19285 For image authoring or picture retouching, The GIMP is a very
19286 sophisticated image manipulation program. It can be used as a simple paint
19287 program or as a quality photo retouching suite. It supports a large number
19288 of plug-ins and features a scripting interface. The GIMP can read and
19289 write a wide range of file formats. It supports interfaces with scanners
19292 You can install the package by issuing this command:
19296 If your FTP site does not have this package, you can use the ports
19297 collection. The graphics directory of the ports collection also contains
19298 The Gimp Manual. Here is how to get them installed:
19300 # cd /usr/ports/graphics/gimp1
19301 # make install clean
19302 # cd /usr/ports/graphics/gimp-manual-pdf
19303 # make install clean
19305 Note: The graphics directory of the ports collection holds the
19306 development version of The GIMP in graphics/gimp-devel. HTML and
19307 PostScript versions of The Gimp Manual are in graphics/gimp-manual-html
19308 and graphics/gimp-manual-ps.
19310 ----------------------------------------------------------------------
19312 15.3.4 OpenOffice.org
19314 OpenOffice.org includes all of the mandatory applications in a complete
19315 office productivity suite: a word processor, a spreadsheet, a presentation
19316 manager, and a drawing program. Its user interface is very similar to
19317 other office suites, and it can import and export in various popular file
19318 formats. It is available in a number of different languages including
19319 interfaces, spell checkers, and dictionaries.
19321 The word processor of OpenOffice.org uses a native XML file format for
19322 increased portability and flexibility. The spreadsheet program features a
19323 macro language and it can be interfaced with external databases.
19324 OpenOffice.org is already stable and runs natively on Windows,
19325 Solaris(TM), Linux, FreeBSD, and Mac OS X. More information about
19326 OpenOffice.org can be found on the OpenOffice web site. For FreeBSD
19327 specific information, and to directly download packages use the FreeBSD
19328 OpenOffice Porting Team's web site. These packages should work on
19331 To install OpenOffice.org, do:
19333 # pkg_add openoffice
19335 Once the package is installed, you must run the setup program and choose a
19336 standard workstation installation. Run this command as the user who will
19337 use OpenOffice.org:
19341 If the OpenOffice.org packages are not available, you still have the
19342 option to compile the port. However, you must bear in mind that it
19343 requires a lot of disk space and a fairly long time to compile.
19345 # cd /usr/ports/editors/openoffice
19346 # make install clean
19348 Once this is done, run the setup as the user who will use OpenOffice.org
19349 and choose a standard workstation installation by:
19351 % cd /usr/ports/editors/openoffice
19352 % make install-user
19354 If you want to use a localized version, here are the available ports:
19356 +------------------------------------+
19357 | Language | Port |
19358 |------------+-----------------------|
19359 | Arabic | editors/openoffice-ar |
19360 |------------+-----------------------|
19361 | Danish | editors/openoffice-dk |
19362 |------------+-----------------------|
19363 | Spanish | editors/openoffice-es |
19364 |------------+-----------------------|
19365 | Greek | editors/openoffice-gr |
19366 |------------+-----------------------|
19367 | Italian | editors/openoffice-it |
19368 |------------+-----------------------|
19369 | Dutch | editors/openoffice-nl |
19370 |------------+-----------------------|
19371 | Swedish | editors/openoffice-se |
19372 |------------+-----------------------|
19373 | Turkish | editors/openoffice-tr |
19374 |------------+-----------------------|
19375 | French | french/openoffice |
19376 |------------+-----------------------|
19377 | German | german/openoffice |
19378 |------------+-----------------------|
19379 | Japanese | japanese/openoffice |
19380 |------------+-----------------------|
19381 | Korean | korean/openoffice |
19382 |------------+-----------------------|
19383 | Polish | polish/openoffice |
19384 |------------+-----------------------|
19385 | Portuguese | portuguese/openoffice |
19386 |------------+-----------------------|
19387 | Russian | russian/openoffice |
19388 +------------------------------------+
19390 ----------------------------------------------------------------------
19392 15.4 Document Viewers
19394 Some new document formats have recently gained popularity. The standard
19395 viewers they require may not be available in the base system. We will see
19396 how to install them in this section.
19398 This section covers these applications:
19400 +------------------------------------------------------------------------+
19401 | Application Name | Resources | Installation | Major Dependencies |
19402 | | Needed | from Ports | |
19403 |------------------+-----------+--------------+--------------------------|
19404 | Acrobat Reader | light | light | Linux Binary |
19405 | | | | Compatibility |
19406 |------------------+-----------+--------------+--------------------------|
19407 | gv | light | light | Xaw3d |
19408 |------------------+-----------+--------------+--------------------------|
19409 | Xpdf | light | light | FreeType |
19410 |------------------+-----------+--------------+--------------------------|
19411 | GQview | light | light | Gtk+ or GNOME |
19412 +------------------------------------------------------------------------+
19414 ----------------------------------------------------------------------
19416 15.4.1 Acrobat Reader(R)
19418 Many documents are now distributed as PDF files, which stands for
19419 ``Portable Document Format''. One of the recommended viewers for these
19420 types of files is Acrobat Reader, released by Adobe for Linux. As
19421 DragonFly can run Linux binaries, it is also available for DragonFly.
19423 To install the Acrobat Reader 5 package, do:
19425 # pkg_add acroread5
19427 As usual, if the package is not available or you want the latest version,
19428 you can use the ports collection as well:
19430 # cd /usr/ports/print/acroread5
19431 # make install clean
19433 Note: Acrobat Reader is available in several different versions. At this
19434 time of writing, there are: print/acroread (version 3.0.2),
19435 print/acroread4 (version 4.0.5), and print/acroread5 (version 5.0.6).
19436 They may not all have been packaged for your version of DragonFly. The
19437 ports collection will always contain the latest versions.
19439 ----------------------------------------------------------------------
19443 gv is a PostScript and PDF viewer. It is originally based on ghostview but
19444 it has a nicer look thanks to the Xaw3d library. It is fast and its
19445 interface is clean. gv has many features like orientation, paper size,
19446 scale, or antialias. Almost any operation can be done either from the
19447 keyboard or the mouse.
19449 To install gv as a package, do:
19453 If you cannot get the package, you can use the ports collection:
19455 # cd /usr/ports/print/gv
19456 # make install clean
19458 ----------------------------------------------------------------------
19462 If you want a small DragonFly PDF viewer, Xpdf is a light-weight and
19463 efficient viewer. It requires very few resources and is very stable. It
19464 uses the standard X fonts and does not require Motif or any other X
19467 To install the Xpdf package, issue this command:
19471 If the package is not available or you prefer to use the ports collection,
19474 # cd /usr/ports/graphics/xpdf
19475 # make install clean
19477 Once the installation is complete, you can launch Xpdf and use the right
19478 mouse button to activate the menu.
19480 ----------------------------------------------------------------------
19484 GQview is an image manager. You can view a file with a single click,
19485 launch an external editor, get thumbnail previews, and much more. It also
19486 features a slideshow mode and some basic file operations. You can manage
19487 image collections and easily find duplicates. GQview can do full screen
19488 viewing and supports internationalization.
19490 If you want to install the GQview package, do:
19494 If the package is not available or you prefer to use the ports collection,
19497 # cd /usr/ports/graphics/gqview
19498 # make install clean
19500 ----------------------------------------------------------------------
19504 If, for any reason, you would like to manage your personal finances on
19505 your DragonFly Desktop, there are some powerful and easy to use
19506 applications ready to be installed. Some of them are compatible with
19507 widespread file formats like those of Quicken(R) or Excel documents.
19509 This section covers these applications:
19511 +------------------------------------------------------------------------+
19512 | Application | Resources | Installation from | Major |
19513 | Name | Needed | Ports | Dependencies |
19514 |-----------------+---------------+-------------------+------------------|
19515 | GnuCash | light | heavy | GNOME |
19516 |-----------------+---------------+-------------------+------------------|
19517 | Gnumeric | light | heavy | GNOME |
19518 |-----------------+---------------+-------------------+------------------|
19519 | Abacus | light | light | Tcl/Tk |
19520 +------------------------------------------------------------------------+
19522 ----------------------------------------------------------------------
19526 GnuCash is part of the GNOME effort to provide user-friendly yet powerful
19527 applications to end-users. With GnuCash, you can keep track of your income
19528 and expenses, your bank accounts, or your stocks. It features an intuitive
19529 interface while remaining very professional.
19531 GnuCash provides a smart register, a hierarchical system of accounts, many
19532 keyboard accelerators and auto-completion methods. It can split a single
19533 transaction into several more detailed pieces. GnuCash can import and
19534 merge Quicken QIF files. It also handles most international date and
19537 To install GnuCash on your system, do:
19541 If the package is not available, you can use the ports collection:
19543 # cd /usr/ports/finance/gnucash
19544 # make install clean
19546 ----------------------------------------------------------------------
19550 Gnumeric is a spreadsheet, part of the GNOME desktop environment. It
19551 features convenient automatic ``guessing'' of user input according to the
19552 cell format and an autofill system for many sequences. It can import files
19553 in a number of popular formats like those of Excel, Lotus 1-2-3, or
19554 Quattro Pro. Gnumeric supports graphs through the math/guppi graphing
19555 program. It has a large number of built-in functions and allows all of the
19556 usual cell formats such as number, currency, date, time, and much more.
19558 To install Gnumeric as a package, type in:
19562 If the package is not available, you can use the ports collection by
19565 # cd /usr/ports/math/gnumeric
19566 # make install clean
19568 ----------------------------------------------------------------------
19572 Abacus is a small and easy to use spreadsheet. It includes many built-in
19573 functions useful in several domains such as statistics, finances, and
19574 mathematics. It can import and export the Excel file format. Abacus can
19575 produce PostScript output.
19577 To install Abacus from its package, do:
19581 If the package is not available, you can use the ports collection by
19584 # cd /usr/ports/deskutils/abacus
19585 # make install clean
19587 ----------------------------------------------------------------------
19591 DragonFly is quite ready for day-to-day use as a desktop. With several
19592 thousand applications available as packages or ports, you can build a
19593 perfect desktop that suits all your needs.
19595 Once you have achieved the installation of your desktop, you may want to
19596 go one step further with misc/instant-workstation. This ``meta-port''
19597 allows you to build a typical set of ports for a workstation. You can
19598 customize it by editing /usr/ports/misc/instant-workstation/Makefile.
19599 Follow the syntax used for the default set to add or remove ports, and
19600 build it with the usual procedure. Eventually, you will be able to create
19601 a big package that corresponds to your very own desktop and install it to
19602 your other workstations!
19604 Here is a quick review of all the desktop applications covered in this
19607 +-----------------------------------------------------------+
19608 | Application Name | Package Name | Ports Name |
19609 |------------------+-----------------+----------------------|
19610 | Mozilla | mozilla | www/mozilla |
19611 |------------------+-----------------+----------------------|
19612 | Netscape | linux-netscape7 | www/netscape7 |
19613 |------------------+-----------------+----------------------|
19614 | Opera | linux-opera | www/linux-opera |
19615 |------------------+-----------------+----------------------|
19616 | KOffice | koffice-kde3 | editors/koffice-kde3 |
19617 |------------------+-----------------+----------------------|
19618 | AbiWord | AbiWord | editors/AbiWord |
19619 |------------------+-----------------+----------------------|
19620 | The GIMP | gimp | graphics/gimp1 |
19621 |------------------+-----------------+----------------------|
19622 | OpenOffice.org | openoffice | editors/openoffice |
19623 |------------------+-----------------+----------------------|
19624 | Acrobat Reader | acroread5 | print/acroread5 |
19625 |------------------+-----------------+----------------------|
19626 | gv | gv | print/gv |
19627 |------------------+-----------------+----------------------|
19628 | Xpdf | xpdf | graphics/xpdf |
19629 |------------------+-----------------+----------------------|
19630 | GQview | gqview | graphics/gqview |
19631 |------------------+-----------------+----------------------|
19632 | GnuCash | gnucash | finance/gnucash |
19633 |------------------+-----------------+----------------------|
19634 | Gnumeric | gnumeric | math/gnumeric |
19635 |------------------+-----------------+----------------------|
19636 | Abacus | abacus | deskutils/abacus |
19637 +-----------------------------------------------------------+
19639 ----------------------------------------------------------------------
19641 Chapter 16 Multimedia
19643 Edited by Ross Lippert.
19647 DragonFly supports a wide variety of sound cards, allowing you to enjoy
19648 high fidelity output from your computer. This includes the ability to
19649 record and playback audio in the MPEG Audio Layer 3 (MP3), WAV, and Ogg
19650 Vorbis formats as well as many other formats. The pkgsrc collection also
19651 contain applications allowing you to edit your recorded audio, add sound
19652 effects, and control attached MIDI devices.
19654 With some willingness to experiment, DragonFly can support playback of
19655 video files and DVD's. The number of applications to encode, convert, and
19656 playback various video media is more limited than the number of sound
19657 applications. For example as of this writing, there is no good re-encoding
19658 application in the FreeBSD Ports Collection, which could be use to convert
19659 between formats, as there is with audio/sox. However, the software
19660 landscape in this area is changing rapidly.
19662 This chapter will describe the necessary steps to configure your sound
19663 card. The configuration and installation of X11 (Chapter 5) has already
19664 taken care of the hardware issues for your video card, though there may be
19665 some tweaks to apply for better playback.
19667 After reading this chapter, you will know:
19669 * How to configure your system so that your sound card is recognized.
19671 * Methods to test that your card is working using sample applications.
19673 * How to troubleshoot your sound setup.
19675 * How to playback and encode MP3s and other audio.
19677 * How video is supported by the X server.
19679 * Some video player/encoder ports which give good results.
19681 * How to playback DVD's, .mpg and .avi files.
19683 * How to rip CD and DVD information into files.
19685 * How to configure a TV card.
19687 Before reading this chapter, you should:
19689 * Know how to configure and install a new kernel (Chapter 9).
19691 Warning: Trying to mount audio CDs with the mount(8) command will result
19692 in an error, at least, and a kernel panic, at worst. These media have
19693 specialized encodings which differ from the usual ISO-filesystem.
19695 ----------------------------------------------------------------------
19697 16.2 Setting Up the Sound Card
19699 Contributed by Moses Moore.
19701 16.2.1 Locating the Correct Device
19703 Before you begin, you should know the model of the card you have, the chip
19704 it uses, and whether it is a PCI or ISA card. DragonFly supports a wide
19705 variety of both PCI and ISA cards. If you do not see your card in the
19706 following list, check the pcm(4) manual page. This is not a complete list;
19707 however, it does list some of the most common cards.
19709 * Crystal 4237, 4236, 4232, 4231
19715 * Ensoniq AudioPCI 1370/1371
19719 * NeoMagic 256AV/ZX
19721 * SoundBlaster(R) Pro, 16, 32, AWE64, AWE128, Live
19725 * Advanced Asound 100, 110, and Logic ALS120
19727 * ES 1868, 1869, 1879, 1888
19729 * Gravis UltraSound
19731 * Aureal Vortex 1 or 2
19733 To use your sound device, you will need to load the proper device driver.
19734 This may be accomplished in one of two ways. The easiest way is to simply
19735 load a kernel module for your sound card with kldload(8) which can either
19736 be done from the command line:
19738 # kldload snd_emu10k1.ko
19740 or by adding the appropriate line to the file /boot/loader.conf like this:
19742 snd_emu10k1_load="YES"
19744 These examples are for a Creative SoundBlaster Live! sound card. Other
19745 available loadable sound modules are listed in /boot/defaults/loader.conf.
19747 Alternatively, you may statically compile in support for your sound card
19748 in your kernel. The sections below provide the information you need to add
19749 support for your hardware in this manner. For more information about
19750 recompiling your kernel, please see Chapter 9.
19752 ----------------------------------------------------------------------
19754 16.2.1.1 Creative, Advance, and ESS Sound Cards
19756 If you have one of the above cards, you will need to add:
19760 to your kernel configuration file. If you have a PnP ISA card, you will
19765 For a non-PnP ISA card, add:
19768 device sbc0 at isa? port 0x220 irq 5 drq 1 flags 0x15
19770 to your kernel configuration file. The settings shown above are the
19771 defaults. You may need to change the IRQ or the other settings to match
19772 your card. See the sbc(4) manual page for more information.
19774 ----------------------------------------------------------------------
19776 16.2.1.2 Gravis UltraSound Cards
19778 For a PnP ISA card, you will need to add:
19783 to your kernel configuration file. If you have a non-PnP ISA card, you
19787 device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13
19789 to your kernel configuration file. You may need to change the IRQ or the
19790 other settings to match your card. See the gusc(4) manual page for more
19793 ----------------------------------------------------------------------
19795 16.2.1.3 Crystal Sound Cards
19797 For Crystal cards, you will need to add:
19802 to your kernel configuration file.
19804 ----------------------------------------------------------------------
19806 16.2.1.4 Generic Support
19808 For PnP ISA or PCI cards, you will need to add:
19812 to your kernel configuration file. If you have a non-PnP ISA sound card
19813 that does not have a bridge driver, you will need to add:
19815 device pcm0 at isa? irq 10 drq 1 flags 0x0
19817 to your kernel configuration file. You may need to change the IRQ or the
19818 other settings to match your card.
19820 ----------------------------------------------------------------------
19822 16.2.1.5 Onboard Sound
19824 Some systems with built-in motherboard sound devices may require the
19825 following device in your kernel configuration:
19829 ----------------------------------------------------------------------
19831 16.2.2 Creating and Testing the Device Nodes
19833 After you reboot, log in and check for the device in the
19834 /var/run/dmesg.boot file, as shown below:
19836 # grep pcm /var/run/dmesg.boot
19837 pcm0: <SB16 DSP 4.11> on sbc0
19839 The output from your system may look different. If no pcm devices show up,
19840 something went wrong earlier. If that happens, go through your kernel
19841 configuration file again and make sure you chose the correct device.
19842 Common problems are listed in Section 16.2.2.1.
19844 If the previous command returned pcm0, you will have to run the following
19850 If the command returned pcm1, follow the same steps as shown above,
19851 replacing snd0 with snd1.
19853 Note: The above commands will not create a /dev/snd device!
19855 MAKEDEV will create a group of device nodes, including:
19858 /dev/audio Sparc(R) compatible audio device
19859 /dev/dsp Digitized voice device
19860 /dev/dspW Like /dev/dsp, but 16 bits per sample
19861 /dev/midi Raw midi access device
19862 /dev/mixer Control port mixer device
19863 /dev/music Level 2 sequencer interface
19864 /dev/sequencer Sequencer device
19865 /dev/pss Programmable device interface
19867 If all goes well, you should now have a functioning sound card. If your
19868 CD-ROM or DVD-ROM drive is properly coupled to your sound card, you can
19869 put a CD in the drive and play it with cdcontrol(1):
19871 % cdcontrol -f /dev/acd0c play 1
19873 Various applications, such as audio/workman offer a better interface. You
19874 may want to install an application such as audio/mpg123 to listen to MP3
19877 ----------------------------------------------------------------------
19879 16.2.2.1 Common Problems
19881 +------------------------------------------------------------------------+
19882 | Error | Solution |
19883 |------------------------------+-----------------------------------------|
19884 | | One or more of the device nodes was not |
19885 | ``unsupported subdevice XX'' | created correctly. Repeat the steps |
19887 |------------------------------+-----------------------------------------|
19888 | ``sb_dspwr(XX) timed out'' | The I/O port is not set correctly. |
19889 |------------------------------+-----------------------------------------|
19890 | | The IRQ is set incorrectly. Make sure |
19891 | ``bad irq XX'' | that the set IRQ and the sound IRQ are |
19893 |------------------------------+-----------------------------------------|
19894 | ``xxx: gus pcm not attached, | There is not enough available memory to |
19895 | out of memory'' | use the device. |
19896 |------------------------------+-----------------------------------------|
19897 | | Check with fstat | grep dsp if another |
19898 | ``xxx: can't open | application is holding the device open. |
19899 | /dev/dsp!'' | Noteworthy troublemakers are esound and |
19900 | | KDE's sound support. |
19901 +------------------------------------------------------------------------+
19903 ----------------------------------------------------------------------
19905 16.2.3 Utilizing Multiple Sound Sources
19907 Contributed by Munish Chopra.
19909 It is often desirable to have multiple sources of sound that are able to
19910 play simultaneously, such as when esound or artsd do not support sharing
19911 of the sound device with a certain application.
19913 DragonFly lets you do this through Virtual Sound Channels, which can be
19914 set with the sysctl(8) facility. Virtual channels allow you to multiplex
19915 your sound card's playback channels by mixing sound in the kernel.
19917 To set the number of virtual channels, there are two sysctl knobs which,
19918 if you are the root user, can be set like this:
19920 # sysctl hw.snd.pcm0.vchans=4
19921 # sysctl hw.snd.maxautovchans=4
19923 The above example allocates four virtual channels, which is a practical
19924 number for everyday use. hw.snd.pcm0.vchans is the number of virtual
19925 channels pcm0 has, and is configurable once a device has been attached.
19926 hw.snd.maxautovchans is the number of virtual channels a new audio device
19927 is given when it is attached using kldload(8). Since the pcm module can be
19928 loaded independently of the hardware drivers, hw.snd.maxautovchans can
19929 store how many virtual channels any devices which are attached later will
19932 If you are not using devfs(5), you will have to point your applications at
19933 /dev/dsp0.x, where x is 0 to 3 if hw.snd.pcm.0.vchans is set to 4 as in
19934 the above example. On a system using devfs(5), the above will
19935 automatically be allocated transparently to the user.
19937 ----------------------------------------------------------------------
19941 Contributed by Chern Lee.
19943 MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound, leaving no
19944 reason to let your DragonFly workstation fall short of its offerings.
19946 ----------------------------------------------------------------------
19950 A popular X11 MP3 player is XMMS (X Multimedia System). Winamp skins can
19951 be used with XMMS since the GUI is almost identical to that of Nullsoft's
19952 Winamp. XMMS also has native plug-in support.
19954 XMMS can be installed from the multimedia/xmms port or package.
19956 XMMS' interface is intuitive, with a playlist, graphic equalizer, and
19957 more. Those familiar with Winamp will find XMMS simple to use.
19959 The audio/mpg123 port is an alternative, command-line MP3 player.
19961 mpg123 can be run by specifying the sound device and the MP3 file on the
19962 command line, as shown below:
19964 # mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3
19965 High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
19966 Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
19967 Uses code from various people. See 'README' for more!
19968 THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!
19974 Playing MPEG stream from Foobar-GreatestHits.mp3 ...
19975 MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
19977 /dev/dsp1.0 should be replaced with the dsp device entry on your system.
19979 ----------------------------------------------------------------------
19981 16.3.2 Ripping CD Audio Tracks
19983 Before encoding a CD or CD track to MP3, the audio data on the CD must be
19984 ripped onto the hard drive. This is done by copying the raw CDDA (CD
19985 Digital Audio) data to WAV files.
19987 The cdda2wav tool, which is a part of the sysutils/cdrtools suite, is used
19988 for ripping audio information from CDs and the information associated with
19991 With the audio CD in the drive, the following command can be issued (as
19992 root) to rip an entire CD into individual (per track) WAV files:
19994 # cdda2wav -D 0,1,0 -B
19996 cdda2wav will support ATAPI (IDE) CDROM drives. To rip from an IDE drive,
19997 specify the device name in place of the SCSI unit numbers. For example, to
19998 rip track 7 from an IDE drive:
20000 # cdda2wav -D /dev/acd0a -t 7
20002 The -D 0,1,0 indicates the SCSI device 0,1,0, which corresponds to the
20003 output of cdrecord -scanbus.
20005 To rip individual tracks, make use of the -t option as shown:
20007 # cdda2wav -D 0,1,0 -t 7
20009 This example rips track seven of the audio CDROM. To rip a range of
20010 tracks, for example, track one to seven, specify a range:
20012 # cdda2wav -D 0,1,0 -t 1+7
20014 The utility dd(1) can also be used to extract audio tracks on ATAPI
20015 drives, read Section 12.5.5 for more information on that possibility.
20017 ----------------------------------------------------------------------
20019 16.3.3 Encoding MP3s
20021 Nowadays, the mp3 encoder of choice is lame. Lame can be found at
20022 audio/lame in the pkgsrc and ports trees.
20024 Using the ripped WAV files, the following command will convert audio01.wav
20028 --tt "Foo Song Title" \
20029 --ta "FooBar Artist" \
20030 --tl "FooBar Album" \
20032 --tc "Ripped and encoded by Foo" \
20034 audio01.wav audio01.mp3
20036 128 kbits seems to be the standard MP3 bitrate in use. Many enjoy the
20037 higher quality 160, or 192. The higher the bitrate, the more disk space
20038 the resulting MP3 will consume--but the quality will be higher. The -h
20039 option turns on the ``higher quality but a little slower'' mode. The
20040 options beginning with --t indicate ID3 tags, which usually contain song
20041 information, to be embedded within the MP3 file. Additional encoding
20042 options can be found by consulting the lame man page.
20044 ----------------------------------------------------------------------
20046 16.3.4 Decoding MP3s
20048 In order to burn an audio CD from MP3s, they must be converted to a
20049 non-compressed WAV format. Both XMMS and mpg123 support the output of MP3
20050 to an uncompressed file format.
20052 Writing to Disk in XMMS:
20056 2. Right-click on the window to bring up the XMMS menu.
20058 3. Select Preference under Options.
20060 4. Change the Output Plugin to ``Disk Writer Plugin''.
20062 5. Press Configure.
20064 6. Enter (or choose browse) a directory to write the uncompressed files
20067 7. Load the MP3 file into XMMS as usual, with volume at 100% and EQ
20068 settings turned off.
20070 8. Press Play -- XMMS will appear as if it is playing the MP3, but no
20071 music will be heard. It is actually playing the MP3 to a file.
20073 9. Be sure to set the default Output Plugin back to what it was before in
20074 order to listen to MP3s again.
20076 Writing to stdout in mpg123:
20078 1. Run mpg123 -s audio01.mp3 > audio01.pcm
20080 XMMS writes a file in the WAV format, while mpg123 converts the MP3 into
20081 raw PCM audio data. Both of these formats can be used with cdrecord to
20082 create audio CDs. You have to use raw PCM with burncd(8). If you use WAV
20083 files, you will notice a small tick sound at the beginning of each track,
20084 this sound is the header of the WAV file. You can simply remove the header
20085 of a WAV file with the utility SoX (it can be installed from the audio/sox
20088 % sox -t wav -r 44100 -s -w -c 2 track.wav track.raw
20090 Read Section 12.5 for more information on using a CD burner in DragonFly.
20092 ----------------------------------------------------------------------
20094 16.4 Video Playback
20096 Contributed by Ross Lippert.
20098 Video playback is a very new and rapidly developing application area. Be
20099 patient. Not everything is going to work as smoothly as it did with sound.
20101 Before you begin, you should know the model of the video card you have and
20102 the chip it uses. While XFree86 and X.org support a wide variety of video
20103 cards, fewer give good playback performance. To obtain a list of
20104 extensions supported by the X server using your card use the command
20105 xdpyinfo(1) while X11 is running.
20107 It is a good idea to have a short MPEG file which can be treated as a test
20108 file for evaluating various players and options. Since some DVD players
20109 will look for DVD media in /dev/dvd by default, or have this device name
20110 hardcoded in them, you might find it useful to make symbolic links to the
20113 # ln -sf /dev/acd0c /dev/dvd
20114 # ln -sf /dev/racd0c /dev/rdvd
20116 Additionally, DVD decryption, which requires invoking special DVD-ROM
20117 functions, requires write permission on the DVD devices.
20119 Some of the packages discussed rely on the following kernel options to
20120 build correctly. Before attempting to build, add these options to the
20121 kernel configuration file, build a new kernel, and reboot:
20123 option CPU_ENABLE_SSE
20126 To enhance the shared memory X11 interface, it is recommended that the
20127 values of some sysctl(8) variables should be increased:
20129 kern.ipc.shmmax=67108864
20130 kern.ipc.shmall=32768
20132 ----------------------------------------------------------------------
20134 16.4.1 Determining Video Capabilities
20136 There are several possible ways to display video under X11. What will
20137 really work is largely hardware dependent. Each method described below
20138 will have varying quality across different hardware. Secondly, the
20139 rendering of video in X11 is a topic receiving a lot of attention lately,
20140 and with each version of X.org or XFree86 there may be significant
20143 A list of common video interfaces:
20145 1. X11: normal X11 output using shared memory.
20147 2. XVideo: an extension to the X11 interface which supports video in any
20150 3. SDL: the Simple Directmedia Layer.
20152 4. DGA: the Direct Graphics Access.
20154 5. SVGAlib: low level console graphics layer.
20156 ----------------------------------------------------------------------
20160 Both XFree86 4.X and X.org have an extension called XVideo (aka Xvideo,
20161 aka Xv, aka xv) which allows video to be directly displayed in drawable
20162 objects through a special acceleration. This extension provides very good
20163 quality playback even on low-end machines (for example my PIII 400 Mhz
20164 laptop). Unfortunately, the list of cards in which this feature is
20165 supported ``out of the box'' is currently:
20169 2. Intel i810 and i815
20171 3. some S3 chips (such as Savage/IX and Savage/MX)
20173 If your card is not one of these, do not be disappointed yet. XFree86 4.X
20174 adds new xv capabilities with each release [12]. To check whether the
20175 extension is running, use xvinfo:
20179 XVideo is supported for your card if the result looks like:
20181 X-Video Extension version 2.2
20183 Adaptor #0: "Savage Streams Engine"
20186 operations supported: PutImage
20188 depth 16, visualID 0x22
20189 depth 16, visualID 0x23
20190 number of attributes: 5
20191 "XV_COLORKEY" (range 0 to 16777215)
20192 client settable attribute
20193 client gettable attribute (current value is 2110)
20194 "XV_BRIGHTNESS" (range -128 to 127)
20195 client settable attribute
20196 client gettable attribute (current value is 0)
20197 "XV_CONTRAST" (range 0 to 255)
20198 client settable attribute
20199 client gettable attribute (current value is 128)
20200 "XV_SATURATION" (range 0 to 255)
20201 client settable attribute
20202 client gettable attribute (current value is 128)
20203 "XV_HUE" (range -180 to 180)
20204 client settable attribute
20205 client gettable attribute (current value is 0)
20206 maximum XvImage size: 1024 x 1024
20207 Number of image formats: 7
20208 id: 0x32595559 (YUY2)
20209 guid: 59555932-0000-0010-8000-00aa00389b71
20211 number of planes: 1
20213 id: 0x32315659 (YV12)
20214 guid: 59563132-0000-0010-8000-00aa00389b71
20216 number of planes: 3
20218 id: 0x30323449 (I420)
20219 guid: 49343230-0000-0010-8000-00aa00389b71
20221 number of planes: 3
20223 id: 0x36315652 (RV16)
20224 guid: 52563135-0000-0000-0000-000000000000
20226 number of planes: 1
20229 red, green, blue masks: 0x1f, 0x3e0, 0x7c00
20230 id: 0x35315652 (RV15)
20231 guid: 52563136-0000-0000-0000-000000000000
20233 number of planes: 1
20236 red, green, blue masks: 0x1f, 0x7e0, 0xf800
20237 id: 0x31313259 (Y211)
20238 guid: 59323131-0000-0010-8000-00aa00389b71
20240 number of planes: 3
20243 guid: 00000000-0000-0000-0000-000000000000
20245 number of planes: 0
20248 red, green, blue masks: 0x0, 0x0, 0x0
20250 Also note that the formats listed (YUV2, YUV12, etc) are not present with
20251 every implementation of XVideo and their absence may hinder some players.
20253 If the result looks like:
20255 X-Video Extension version 2.2
20257 no adaptors present
20259 Then XVideo is probably not supported for your card.
20261 If XVideo is not supported for your card, this only means that it will be
20262 more difficult for your display to meet the computational demands of
20263 rendering video. Depending on your video card and processor, though, you
20264 might still be able to have a satisfying experience. You should probably
20265 read about ways of improving performance in the advanced reading Section
20268 ----------------------------------------------------------------------
20270 16.4.1.2 Simple Directmedia Layer
20272 The Simple Directmedia Layer, SDL, was intended to be a porting layer
20273 between Microsoft Windows, BeOS, and UNIX, allowing cross-platform
20274 applications to be developed which made efficient use of sound and
20275 graphics. The SDL layer provides a low-level abstraction to the hardware
20276 which can sometimes be more efficient than the X11 interface.
20278 The SDL can be found at devel/sdl12 (or pkgsrc/devel/SDL2).
20280 ----------------------------------------------------------------------
20282 16.4.1.3 Direct Graphics Access
20284 Direct Graphics Access is an X11 extension which allows a program to
20285 bypass the X server and directly alter the framebuffer. Because it relies
20286 on a low level memory mapping to effect this sharing, programs using it
20287 must be run as root.
20289 The DGA extension can be tested and benchmarked by dga(1). When dga is
20290 running, it changes the colors of the display whenever a key is pressed.
20293 ----------------------------------------------------------------------
20295 16.4.2 Ports and Packages Dealing with Video
20297 This section discusses the software available from the pkgsrc collection
20298 which can be used for video playback. Video playback is a very active area
20299 of software development, and the capabilities of various applications are
20300 bound to diverge somewhat from the descriptions given here.
20302 Firstly, it is important to know that many of the video applications which
20303 run on DragonFly were developed as Linux applications. Many of these
20304 applications are still beta-quality. Some of the problems that you may
20305 encounter with video packages on DragonFly include:
20307 1. An application cannot playback a file which another application
20310 2. An application cannot playback a file which the application itself
20313 3. The same application on two different machines, rebuilt on each
20314 machine for that machine, plays back the same file differently.
20316 4. A seemingly trivial filter like rescaling of the image size results in
20317 very bad artifacts from a buggy rescaling routine.
20319 5. An application frequently dumps core.
20321 6. Documentation is not installed with the port and can be found either
20322 on the web or under the port's work directory.
20324 Many of these applications may also exhibit ``Linux-isms''. That is, there
20325 may be issues resulting from the way some standard libraries are
20326 implemented in the Linux distributions, or some features of the Linux
20327 kernel which have been assumed by the authors of the applications. These
20328 issues are not always noticed and worked around by the port maintainers,
20329 which can lead to problems like these:
20331 1. The use of /proc/cpuinfo to detect processor characteristics.
20333 2. A misuse of threads which causes a program to hang upon completion
20334 instead of truly terminating.
20336 3. Software not yet in the pkgsrc collection which is commonly used in
20337 conjunction with the application.
20339 So far, these application developers have been cooperative with port
20340 maintainers to minimize the work-arounds needed for port-ing.
20342 ----------------------------------------------------------------------
20346 MPlayer is a recently developed and rapidly developing video player. The
20347 goals of the MPlayer team are speed and flexibility on Linux and other
20348 Unices. The project was started when the team founder got fed up with bad
20349 playback performance on then available players. Some would say that the
20350 graphical interface has been sacrificed for a streamlined design. However,
20351 once you get used to the command line options and the key-stroke controls,
20352 it works very well.
20354 ----------------------------------------------------------------------
20356 16.4.2.1.1 Building MPlayer
20358 MPlayer resides in multimedia/mplayer. MPlayer performs a variety of
20359 hardware checks during the build process, resulting in a binary which will
20360 not be portable from one system to another. Therefore, it is important to
20361 build it from ports and not to use a binary package. Additionally, a
20362 number of options can be specified in the make command line, as described
20363 at the start of the build.
20365 # cd /usr/ports/multimedia/mplayer
20367 You can enable additional compilation optimizations
20368 by defining WITH_OPTIMIZED_CFLAGS
20369 You can enable GTK GUI by defining WITH_GUI.
20370 You can enable DVD support by defining WITH_DVD.
20371 You can enable SVGALIB support by defining WITH_SVGALIB.
20372 You can enable VORBIS sound support by defining WITH_VORBIS.
20373 You can enable XAnim DLL support by defining WITH_XANIM.
20375 If you have x11-toolkits/gtk12 installed, then you might as well enable
20376 the GUI. Otherwise, it is not worth the effort. If you intend to play
20377 (possibly CSS encoded) DVD's with MPlayer you must enable the DVD support
20378 option here [13]. Some reasonable options are:
20380 # make WITH_DVD=yes WITH_SVGALIB=yes
20382 As of this writing, the MPlayer port will build its HTML documentation and
20383 one executable, mplayer. It can also be made to build an encoder,
20384 mencoder, which is a tool for re-encoding video. A modification to the
20385 Makefile can enable it. It may be enabled by default in subsequent
20386 versions of the port.
20388 The HTML documentation for MPlayer is very informative. If the reader
20389 finds the information on video hardware and interfaces in this chapter
20390 lacking, the MPlayer documentation is a very thorough supplement. You
20391 should definitely take the time to read the MPlayer documentation if you
20392 are looking for information about video support in UNIX.
20394 ----------------------------------------------------------------------
20396 16.4.2.1.2 Using MPlayer
20398 Any user of MPlayer must set up a .mplayer subdirectory of her home
20399 directory. To create this necessary subdirectory, you can type the
20402 % cd /usr/ports/multimedia/mplayer
20403 % make install-user
20405 The command options for mplayer are listed in the manual page. For even
20406 more detail there is HTML documentation. In this section, we will describe
20407 only a few common uses.
20409 To play a file, such as testfile.avi, through one of the various video
20410 interfaces set the -vo option:
20412 % mplayer -vo xv testfile.avi
20414 % mplayer -vo sdl testfile.avi
20416 % mplayer -vo x11 testfile.avi
20418 # mplayer -vo dga testfile.avi
20420 # mplayer -vo 'sdl:dga' testfile.avi
20422 It is worth trying all of these options, as their relative performance
20423 depends on many factors and will vary significantly with hardware.
20425 To play from a DVD, replace the testfile.avi with -dvd N DEVICE where N is
20426 the title number to play and DEVICE is the device node for the DVD-ROM.
20427 For example, to play title 3 from /dev/dvd:
20429 # mplayer -vo dga -dvd 3 /dev/dvd
20431 To stop, pause, advance and so on, consult the keybindings, which are
20432 output by running mplayer -h or read the manual page.
20434 Additional important options for playback are: -fs -zoom which engages the
20435 fullscreen mode and -framedrop which helps performance.
20437 In order for the mplayer command line to not become too large, the user
20438 can create a file .mplayer/config and set default options there:
20444 Finally, mplayer can be used to rip a DVD title into a .vob file. To dump
20445 out the second title from a DVD, type this:
20447 # mplayer -dumpstream -dumpfile out.vob -dvd 2 /dev/dvd
20449 The output file, out.vob, will be MPEG and can be manipulated by the other
20450 packages described in this section.
20452 ----------------------------------------------------------------------
20454 16.4.2.1.3 mencoder
20456 If you opt to install mencoder when you build MPlayer, be forewarned that
20457 it is still an experimental component. Before using mencoder it is a good
20458 idea to familiarize yourself with the options from the HTML documentation.
20459 There is a manual page, but it is not very useful without the HTML
20460 documentation. There are innumerable ways to improve quality, lower
20461 bitrate, and change formats, and some of these tricks may make the
20462 difference between good or bad performance. Here are a couple of examples
20463 to get you going. First a simple copy:
20465 % mencoder input.avi -oac copy -ovc copy -o output.avi
20467 Improper combinations of command line options can yield output files that
20468 are unplayable even by mplayer. Thus, if you just want to rip to a file,
20469 stick to the -dumpfile in mplayer.
20471 To convert input.avi to the MPEG4 codec with MPEG3 audio encoding
20472 (audio/lame is required):
20474 % mencoder input.avi -oac mp3lame -lameopts br=192 \
20475 -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi
20477 This has produced output playable by mplayer and xine.
20479 input.avi can be replaced with -dvd 1 /dev/dvd and run as root to
20480 re-encode a DVD title directly. Since you are likely to be dissatisfied
20481 with your results the first time around, it is recommended you dump the
20482 title to a file and work on the file.
20484 ----------------------------------------------------------------------
20486 16.4.2.2 The xine Video Player
20488 The xine video player is a project of wide scope aiming not only at being
20489 an all in one video solution, but also in producing a reusable base
20490 library and a modular executable which can be extended with plugins. It
20491 comes both as a package and as a port, multimedia/xine.
20493 The xine player is still very rough around the edges, but it is clearly
20494 off to a good start. In practice, xine requires either a fast CPU with a
20495 fast video card, or support for the XVideo extension. The GUI is usable,
20498 As of this writing, there is no input module shipped with xine which will
20499 play CSS encoded DVD's. There are third party builds which do have modules
20500 for this built in them, but none of these are in the FreeBSD Ports
20503 Compared to MPlayer, xine does more for the user, but at the same time,
20504 takes some of the more fine-grained control away from the user. The xine
20505 video player performs best on XVideo interfaces.
20507 By default, xine player will start up in a graphical user interface. The
20508 menus can then be used to open a specific file:
20512 Alternatively, it may be invoked to play a file immediately without the
20513 GUI with the command:
20515 % xine -g -p mymovie.avi
20517 ----------------------------------------------------------------------
20519 16.4.2.3 The transcode Utilities
20521 The software transcode is not a player, but a suite of tools for
20522 re-encoding .avi and .mpg files. With transcode, one has the ability to
20523 merge video files, repair broken files, using command line tools with
20524 stdin/stdout stream interfaces.
20526 Like MPlayer, transcode is very experimental software which must be build
20527 from ports or pkgsrc at multimedia/transcode. Using a great many options
20528 to the make command. I recommend:
20530 # make WITH_LIBMPEG2=yes
20532 If you plan to install multimedia/avifile, then add the WITH_AVIFILE
20533 option to your make command line, as shown here:
20535 # make WITH_AVIFILE=yes WITH_LIBMPEG2=yes
20537 Here are two examples of using transcode for video conversion which
20538 produce rescaled output. The first encodes the output to an openDIVX AVI
20539 file, while the second encodes to the much more portable MPEG format.
20541 % transcode -i input.vob -x vob -V -Z 320x240 \
20542 -y opendivx -N 0x55 -o output.avi
20544 % transcode -i input.vob -x vob -V -Z 320x240 \
20545 -y mpeg -N 0x55 -o output.tmp
20546 % tcmplex -o output.mpg -i output.tmp.m1v -p output.tmp.mpa -m 1
20548 There is a manual page for transcode, but there is little documentation
20549 for the various tc* utilities (such as tcmplex) which are also installed.
20550 However, the -h command line option can always be given to get curt usage
20551 instructions for a command.
20553 In comparison, transcode runs significantly slower than mencoder, but it
20554 has a better chance of producing a more widely playable file. MPEGs
20555 created by transcode have been known to play on Windows Media(R) Player
20556 and Apple's Quicktime(R), for example.
20558 ----------------------------------------------------------------------
20560 16.4.3 Further Reading
20562 The various video software packages for DragonFly are developing rapidly.
20563 It is quite possible that in the near future many of the problems
20564 discussed here will have been resolved. In the mean time, those who want
20565 to get the very most out of DragonFly's A/V capabilities will have to
20566 cobble together knowledge from several FAQs and tutorials and use a few
20567 different applications. This section exists to give the reader pointers to
20568 such additional information.
20570 The MPlayer documentation is very technically informative. These documents
20571 should probably be consulted by anyone wishing to obtain a high level of
20572 expertise with UNIX video. The MPlayer mailing list is hostile to anyone
20573 who has not bothered to read the documentation, so if you plan on making
20574 bug reports to them, RTFM.
20576 The xine HOWTO contains a chapter on performance improvement which is
20577 general to all players.
20579 Finally, there are some other promising applications which the reader may
20582 * Avifile which is also a port multimedia/avifile.
20584 * Ogle which is also a port multimedia/ogle.
20588 * multimedia/dvdauthor, an open source package for authoring DVD
20591 ----------------------------------------------------------------------
20593 16.5 Setting Up TV Cards
20595 Original contribution by Josef El-Rayes. Enhanced and adapted by Marc
20598 ----------------------------------------------------------------------
20600 16.5.1 Introduction
20602 TV cards allow you to watch broadcast or cable TV on your computer. Most
20603 of them accept composite video via an RCA or S-video input and some of
20604 these cards come with a FM radio tuner.
20606 DragonFly provides support for PCI-based TV cards using a Brooktree
20607 Bt848/849/878/879 or a Conexant CN-878/Fusion 878a Video Capture Chip with
20608 the bktr(4) driver. You must also ensure the board comes with a supported
20609 tuner, consult the bktr(4) manual page for a list of supported tuners.
20611 ----------------------------------------------------------------------
20613 16.5.2 Adding the Driver
20615 To use your card, you will need to load the bktr(4) driver, this can be
20616 done by adding the following line to the /boot/loader.conf file like this:
20620 Alternatively, you may statically compile the support for the TV card in
20621 your kernel, in that case add the following lines to your kernel
20629 These additional device drivers are necessary because of the card
20630 components being interconnected via an I2C bus. Then build and install a
20633 Once the support was added to your system, you have to reboot your
20634 machine. During the boot process, your TV card should show up, like this:
20636 bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
20637 iicbb0: <I2C bit-banging driver> on bti2c0
20638 iicbus0: <Philips I2C bus> on iicbb0 master-only
20639 iicbus1: <Philips I2C bus> on iicbb0 master-only
20640 smbus0: <System Management Bus> on bti2c0
20641 bktr0: Pinnacle/Miro TV, Philips SECAM tuner.
20643 Of course these messages can differ according to your hardware. However
20644 you should check if the tuner is correctly detected; it is still possible
20645 to override some of the detected parameters with sysctl(8) MIBs and kernel
20646 configuration file options. For example, if you want to force the tuner to
20647 a Philips SECAM tuner, you should add the following line to your kernel
20648 configuration file:
20650 options OVERRIDE_TUNER=6
20652 or you can directly use sysctl(8):
20654 # sysctl hw.bt848.tuner=6
20656 See the bktr(4) manual page and the /usr/src/sys/i386/conf/LINT file for
20657 more details on the available options.
20659 ----------------------------------------------------------------------
20661 16.5.3 Useful Applications
20663 To use your TV card you need to install one of the following applications:
20665 * multimedia/fxtv provides TV-in-a-window and image/audio/video capture
20668 * multimedia/xawtv is also a TV application, with the same features as
20671 * misc/alevt (or pkgsrc/multimedia/alevt) decodes and displays
20672 Videotext/Teletext.
20674 * audio/xmradio, an application to use the FM radio tuner coming with
20677 * audio/wmtune, a handy desktop application for radio tuners.
20679 More applications are available in the pkgsrc and FreeBSD Ports
20682 ----------------------------------------------------------------------
20684 16.5.4 Troubleshooting
20686 If you encounter any problem with your TV card, you should check at first
20687 if the video capture chip and the tuner are really supported by the
20688 bktr(4) driver and if you used the right configuration options. For more
20689 support and various questions about your TV card you may want to contact
20690 and use the archives of the freebsd-multimedia mailing list.
20692 ----------------------------------------------------------------------
20694 Chapter 17 Serial Communications
20698 UNIX has always had support for serial communications. In fact, the very
20699 first UNIX machines relied on serial lines for user input and output.
20700 Things have changed a lot from the days when the average ``terminal''
20701 consisted of a 10-character-per-second serial printer and a keyboard. This
20702 chapter will cover some of the ways in which DragonFly uses serial
20705 After reading this chapter, you will know:
20707 * How to connect terminals to your DragonFly system.
20709 * How to use a modem to dial out to remote hosts.
20711 * How to allow remote users to login to your system with a modem.
20713 * How to boot your system from a serial console.
20715 Before reading this chapter, you should:
20717 * Know how to configure and install a new kernel (Chapter 9).
20719 * Understand UNIX permissions and processes (Chapter 3).
20721 * Have access to the technical manual for the serial hardware (modem or
20722 multi-port card) that you would like to use with DragonFly.
20724 ----------------------------------------------------------------------
20732 Bits per Second -- the rate at which data is transmitted
20736 Data Terminal Equipment -- for example, your computer
20740 Data Communications Equipment -- your modem
20744 EIA standard for hardware serial communications
20746 When talking about communications data rates, this section does not use
20747 the term ``baud''. Baud refers to the number of electrical state
20748 transitions that may be made in a period of time, while ``bps'' (bits per
20749 second) is the correct term to use (at least it does not seem to bother
20750 the curmudgeons quite as much).
20752 ----------------------------------------------------------------------
20754 17.2.2 Cables and Ports
20756 To connect a modem or terminal to your DragonFly system, you will need a
20757 serial port on your computer and the proper cable to connect to your
20758 serial device. If you are already familiar with your hardware and the
20759 cable it requires, you can safely skip this section.
20761 ----------------------------------------------------------------------
20765 There are several different kinds of serial cables. The two most common
20766 types for our purposes are null-modem cables and standard (``straight'')
20767 RS-232 cables. The documentation for your hardware should describe the
20768 type of cable required.
20770 ----------------------------------------------------------------------
20772 17.2.2.1.1 Null-modem Cables
20774 A null-modem cable passes some signals, such as ``signal ground'',
20775 straight through, but switches other signals. For example, the ``send
20776 data'' pin on one end goes to the ``receive data'' pin on the other end.
20778 If you like making your own cables, you can construct a null-modem cable
20779 for use with terminals. This table shows the RS-232C signal names and the
20780 pin numbers on a DB-25 connector.
20782 Signal Pin # Pin # Signal
20783 SG 7 connects to 7 SG
20784 TxD 2 connects to 3 RxD
20785 RxD 3 connects to 2 TxD
20786 RTS 4 connects to 5 CTS
20787 CTS 5 connects to 4 RTS
20788 DTR 20 connects to 6 DSR
20790 DSR 6 connects to 20 DTR
20792 Note: Connect ``Data Set Ready'' (DSR) and ``Data Carrier Detect'' (DCD)
20793 internally in the connector hood, and then to ``Data Terminal Ready''
20794 (DTR) in the remote hood.
20796 ----------------------------------------------------------------------
20798 17.2.2.1.2 Standard RS-232C Cables
20800 A standard serial cable passes all the RS-232C signals straight-through.
20801 That is, the ``send data'' pin on one end of the cable goes to the ``send
20802 data'' pin on the other end. This is the type of cable to use to connect a
20803 modem to your DragonFly system, and is also appropriate for some
20806 ----------------------------------------------------------------------
20810 Serial ports are the devices through which data is transferred between the
20811 DragonFly host computer and the terminal. This section describes the kinds
20812 of ports that exist and how they are addressed in DragonFly.
20814 ----------------------------------------------------------------------
20816 17.2.2.2.1 Kinds of Ports
20818 Several kinds of serial ports exist. Before you purchase or construct a
20819 cable, you need to make sure it will fit the ports on your terminal and on
20820 the DragonFly system.
20822 Most terminals will have DB25 ports. Personal computers, including PCs
20823 running DragonFly, will have DB25 or DB9 ports. If you have a multiport
20824 serial card for your PC, you may have RJ-12 or RJ-45 ports.
20826 See the documentation that accompanied the hardware for specifications on
20827 the kind of port in use. A visual inspection of the port often works too.
20829 ----------------------------------------------------------------------
20831 17.2.2.2.2 Port Names
20833 In DragonFly, you access each serial port through an entry in the /dev
20834 directory. There are two different kinds of entries:
20836 * Call-in ports are named /dev/ttydN where N is the port number,
20837 starting from zero. Generally, you use the call-in port for terminals.
20838 Call-in ports require that the serial line assert the data carrier
20839 detect (DCD) signal to work correctly.
20841 * Call-out ports are named /dev/cuaaN. You usually do not use the
20842 call-out port for terminals, just for modems. You may use the call-out
20843 port if the serial cable or the terminal does not support the carrier
20846 If you have connected a terminal to the first serial port (COM1 in
20847 MS-DOS), then you will use /dev/ttyd0 to refer to the terminal. If the
20848 terminal is on the second serial port (also known as COM2), use
20849 /dev/ttyd1, and so forth.
20851 ----------------------------------------------------------------------
20853 17.2.3 Kernel Configuration
20855 DragonFly supports four serial ports by default. In the MS-DOS world,
20856 these are known as COM1, COM2, COM3, and COM4. DragonFly currently
20857 supports ``dumb'' multiport serial interface cards, such as the BocaBoard
20858 1008 and 2016, as well as more intelligent multi-port cards such as those
20859 made by Digiboard and Stallion Technologies. However, the default kernel
20860 only looks for the standard COM ports.
20862 To see if your kernel recognizes any of your serial ports, watch for
20863 messages while the kernel is booting, or use the /sbin/dmesg command to
20864 replay the kernel's boot messages. In particular, look for messages that
20865 start with the characters sio.
20867 Tip: To view just the messages that have the word sio, use the command:
20869 # /sbin/dmesg | grep 'sio'
20871 For example, on a system with four serial ports, these are the serial-port
20872 specific kernel boot messages:
20874 sio0 at 0x3f8-0x3ff irq 4 on isa
20876 sio1 at 0x2f8-0x2ff irq 3 on isa
20878 sio2 at 0x3e8-0x3ef irq 5 on isa
20880 sio3 at 0x2e8-0x2ef irq 9 on isa
20883 If your kernel does not recognize all of your serial ports, you will
20884 probably need to configure a custom DragonFly kernel for your system. For
20885 detailed information on configuring your kernel, please see Chapter 9.
20887 The relevant device lines for your kernel configuration file would look
20890 device sio0 at isa? port IO_COM1 irq 4
20891 device sio1 at isa? port IO_COM2 irq 3
20892 device sio2 at isa? port IO_COM3 irq 5
20893 device sio3 at isa? port IO_COM4 irq 9
20895 You can comment-out or completely remove lines for devices you do not
20896 have. Please refer to the sio(4) manual page for more information on
20897 serial ports and multiport boards configuration.
20899 Note: port IO_COM1 is a substitution for port 0x3f8, IO_COM2 is 0x2f8,
20900 IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8, which are fairly common port
20901 addresses for their respective serial ports; interrupts 4, 3, 5, and 9
20902 are fairly common interrupt request lines. Also note that regular serial
20903 ports cannot share interrupts on ISA-bus PCs (multiport boards have
20904 on-board electronics that allow all the 16550A's on the board to share
20905 one or two interrupt request lines).
20907 ----------------------------------------------------------------------
20909 17.2.4 Device Special Files
20911 Most devices in the kernel are accessed through ``device special files'',
20912 which are located in the /dev directory. The sio devices are accessed
20913 through the /dev/ttydN (dial-in) and /dev/cuaaN (call-out) devices.
20914 DragonFly also provides initialization devices (/dev/ttyidN and
20915 /dev/cuaiaN) and locking devices (/dev/ttyldN and /dev/cualaN). The
20916 initialization devices are used to initialize communications port
20917 parameters each time a port is opened, such as crtscts for modems which
20918 use RTS/CTS signaling for flow control. The locking devices are used to
20919 lock flags on ports to prevent users or programs changing certain
20920 parameters; see the manual pages termios(4), sio(4), and stty(1) for
20921 information on the terminal settings, locking and initializing devices,
20922 and setting terminal options, respectively.
20924 ----------------------------------------------------------------------
20926 17.2.4.1 Making Device Special Files
20928 A shell script called MAKEDEV in the /dev directory manages the device
20929 special files. To use MAKEDEV to make dial-up device special files for
20930 COM1 (port 0), cd to /dev and issue the command MAKEDEV ttyd0. Likewise,
20931 to make dial-up device special files for COM2 (port 1), use MAKEDEV ttyd1.
20933 MAKEDEV not only creates the /dev/ttydN device special files, but also the
20934 /dev/cuaaN, /dev/cuaiaN, /dev/cualaN, /dev/ttyldN, and /dev/ttyidN nodes.
20936 After making new device special files, be sure to check the permissions on
20937 the files (especially the /dev/cua* files) to make sure that only users
20938 who should have access to those device special files can read and write on
20939 them -- you probably do not want to allow your average user to use your
20940 modems to dial-out. The default permissions on the /dev/cua* files should
20943 crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cuaa1
20944 crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuaia1
20945 crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cuala1
20947 These permissions allow the user uucp and users in the group dialer to use
20948 the call-out devices.
20950 ----------------------------------------------------------------------
20952 17.2.5 Serial Port Configuration
20954 The ttydN (or cuaaN) device is the regular device you will want to open
20955 for your applications. When a process opens the device, it will have a
20956 default set of terminal I/O settings. You can see these settings with the
20959 # stty -a -f /dev/ttyd1
20961 When you change the settings to this device, the settings are in effect
20962 until the device is closed. When it is reopened, it goes back to the
20963 default set. To make changes to the default set, you can open and adjust
20964 the settings of the ``initial state'' device. For example, to turn on
20965 CLOCAL mode, 8 bit communication, and XON/XOFF flow control by default for
20968 # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
20970 System-wide initialization of the serial devices is controlled in
20971 /etc/rc.serial. This file affects the default settings of serial devices.
20973 To prevent certain settings from being changed by an application, make
20974 adjustments to the ``lock state'' device. For example, to lock the speed
20975 of ttyd5 to 57600 bps, type:
20977 # stty -f /dev/ttyld5 57600
20979 Now, an application that opens ttyd5 and tries to change the speed of the
20980 port will be stuck with 57600 bps.
20982 Naturally, you should make the initial state and lock state devices
20983 writable only by the root account.
20985 ----------------------------------------------------------------------
20989 Contributed by Sean Kelly.
20991 Terminals provide a convenient and low-cost way to access your DragonFly
20992 system when you are not at the computer's console or on a connected
20993 network. This section describes how to use terminals with DragonFly.
20995 ----------------------------------------------------------------------
20997 17.3.1 Uses and Types of Terminals
20999 The original UNIX systems did not have consoles. Instead, people logged in
21000 and ran programs through terminals that were connected to the computer's
21001 serial ports. It is quite similar to using a modem and terminal software
21002 to dial into a remote system to do text-only work.
21004 Today's PCs have consoles capable of high quality graphics, but the
21005 ability to establish a login session on a serial port still exists in
21006 nearly every UNIX style operating system today; DragonFly is no exception.
21007 By using a terminal attached to an unused serial port, you can log in and
21008 run any text program that you would normally run on the console or in an
21009 xterm window in the X Window System.
21011 For the business user, you can attach many terminals to a DragonFly system
21012 and place them on your employees' desktops. For a home user, a spare
21013 computer such as an older IBM PC or a Macintosh can be a terminal wired
21014 into a more powerful computer running DragonFly. You can turn what might
21015 otherwise be a single-user computer into a powerful multiple user system.
21017 For DragonFly, there are three kinds of terminals:
21021 * PCs acting as terminals
21025 The remaining subsections describe each kind.
21027 ----------------------------------------------------------------------
21029 17.3.1.1 Dumb Terminals
21031 Dumb terminals are specialized pieces of hardware that let you connect to
21032 computers over serial lines. They are called ``dumb'' because they have
21033 only enough computational power to display, send, and receive text. You
21034 cannot run any programs on them. It is the computer to which you connect
21035 them that has all the power to run text editors, compilers, email, games,
21038 There are hundreds of kinds of dumb terminals made by many manufacturers,
21039 including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just
21040 about any kind will work with DragonFly. Some high-end terminals can even
21041 display graphics, but only certain software packages can take advantage of
21042 these advanced features.
21044 Dumb terminals are popular in work environments where workers do not need
21045 access to graphical applications such as those provided by the X Window
21048 ----------------------------------------------------------------------
21050 17.3.1.2 PCs Acting as Terminals
21052 If a dumb terminal has just enough ability to display, send, and receive
21053 text, then certainly any spare personal computer can be a dumb terminal.
21054 All you need is the proper cable and some terminal emulation software to
21055 run on the computer.
21057 Such a configuration is popular in homes. For example, if your spouse is
21058 busy working on your DragonFly system's console, you can do some text-only
21059 work at the same time from a less powerful personal computer hooked up as
21060 a terminal to the DragonFly system.
21062 ----------------------------------------------------------------------
21064 17.3.1.3 X Terminals
21066 X terminals are the most sophisticated kind of terminal available. Instead
21067 of connecting to a serial port, they usually connect to a network like
21068 Ethernet. Instead of being relegated to text-only applications, they can
21069 display any X application.
21071 We introduce X terminals just for the sake of completeness. However, this
21072 chapter does not cover setup, configuration, or use of X terminals.
21074 ----------------------------------------------------------------------
21076 17.3.2 Configuration
21078 This section describes what you need to configure on your DragonFly system
21079 to enable a login session on a terminal. It assumes you have already
21080 configured your kernel to support the serial port to which the terminal is
21081 connected--and that you have connected it.
21083 Recall from Chapter 7 that the init process is responsible for all process
21084 control and initialization at system startup. One of the tasks performed
21085 by init is to read the /etc/ttys file and start a getty process on the
21086 available terminals. The getty process is responsible for reading a login
21087 name and starting the login program.
21089 Thus, to configure terminals for your DragonFly system the following steps
21090 should be taken as root:
21092 1. Add a line to /etc/ttys for the entry in the /dev directory for the
21093 serial port if it is not already there.
21095 2. Specify that /usr/libexec/getty be run on the port, and specify the
21096 appropriate getty type from the /etc/gettytab file.
21098 3. Specify the default terminal type.
21100 4. Set the port to ``on.''
21102 5. Specify whether the port should be ``secure.''
21104 6. Force init to reread the /etc/ttys file.
21106 As an optional step, you may wish to create a custom getty type for use in
21107 step 2 by making an entry in /etc/gettytab. This chapter does not explain
21108 how to do so; you are encouraged to see the gettytab(5) and the getty(8)
21109 manual pages for more information.
21111 ----------------------------------------------------------------------
21113 17.3.2.1 Adding an Entry to /etc/ttys
21115 The /etc/ttys file lists all of the ports on your DragonFly system where
21116 you want to allow logins. For example, the first virtual console ttyv0 has
21117 an entry in this file. You can log in on the console using this entry.
21118 This file also contains entries for the other virtual consoles, serial
21119 ports, and pseudo-ttys. For a hardwired terminal, just list the serial
21120 port's /dev entry without the /dev part (for example, /dev/ttyv0 would be
21123 A default DragonFly install includes an /etc/ttys file with support for
21124 the first four serial ports: ttyd0 through ttyd3. If you are attaching a
21125 terminal to one of those ports, you do not need to add another entry.
21127 Example 17-1. Adding Terminal Entries to /etc/ttys
21129 Suppose we would like to connect two terminals to the system: a Wyse-50
21130 and an old 286 IBM PC running Procomm terminal software emulating a VT-100
21131 terminal. We connect the Wyse to the second serial port and the 286 to the
21132 sixth serial port (a port on a multiport serial card). The corresponding
21133 entries in the /etc/ttys file would look like this:
21135 ttyd1(1) "/usr/libexec/getty std.38400"(2) wy50(3) on(4) insecure(5)
21136 ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure
21140 The first field normally specifies the name of the terminal
21141 special file as it is found in /dev.
21143 The second field is the command to execute for this line, which is
21144 usually getty(8). getty initializes and opens the line, sets the
21145 speed, prompts for a user name and then executes the login(1)
21148 The getty program accepts one (optional) parameter on its command
21149 line, the getty type. A getty type configures characteristics on
21150 the terminal line, like bps rate and parity. The getty program
21151 reads these characteristics from the file /etc/gettytab.
21153 The file /etc/gettytab contains lots of entries for terminal lines
21154 both old and new. In almost all cases, the entries that start with
21155 the text std will work for hardwired terminals. These entries
21156 ignore parity. There is a std entry for each bps rate from 110 to
21157 115200. Of course, you can add your own entries to this file. The
21158 gettytab(5) manual page provides more information.
21160 When setting the getty type in the /etc/ttys file, make sure that
21161 the communications settings on the terminal match.
21163 For our example, the Wyse-50 uses no parity and connects at
21164 38400 bps. The 286 PC uses no parity and connects at 19200 bps.
21167 The third field is the type of terminal usually connected to that
21168 tty line. For dial-up ports, unknown or dialup is typically used
21169 in this field since users may dial up with practically any type of
21170 terminal or software. For hardwired terminals, the terminal type
21171 does not change, so you can put a real terminal type from the
21172 termcap(5) database file in this field.
21174 For our example, the Wyse-50 uses the real terminal type while the
21175 286 PC running Procomm will be set to emulate at VT-100.
21178 The fourth field specifies if the port should be enabled. Putting
21179 on here will have the init process start the program in the second
21180 field, getty. If you put off in this field, there will be no
21181 getty, and hence no logins on the port.
21183 The final field is used to specify whether the port is secure.
21184 Marking a port as secure means that you trust it enough to allow
21185 the root account (or any account with a user ID of 0) to login
21186 from that port. Insecure ports do not allow root logins. On an
21187 insecure port, users must login from unprivileged accounts and
21188 then use su(1) or a similar mechanism to gain superuser
21191 It is highly recommended that you use ``insecure'' even for
21192 terminals that are behind locked doors. It is quite easy to login
21193 and use su if you need superuser privileges.
21195 ----------------------------------------------------------------------
21197 17.3.2.2 Force init to Reread /etc/ttys
21199 After making the necessary changes to the /etc/ttys file you should send a
21200 SIGHUP (hangup) signal to the init process to force it to re-read its
21201 configuration file. For example:
21205 Note: init is always the first process run on a system, therefore it
21206 will always have PID 1.
21208 If everything is set up correctly, all cables are in place, and the
21209 terminals are powered up, then a getty process should be running on each
21210 terminal and you should see login prompts on your terminals at this point.
21212 ----------------------------------------------------------------------
21214 17.3.3 Troubleshooting Your Connection
21216 Even with the most meticulous attention to detail, something could still
21217 go wrong while setting up a terminal. Here is a list of symptoms and some
21220 ----------------------------------------------------------------------
21222 17.3.3.1 No Login Prompt Appears
21224 Make sure the terminal is plugged in and powered up. If it is a personal
21225 computer acting as a terminal, make sure it is running terminal emulation
21226 software on the correct serial port.
21228 Make sure the cable is connected firmly to both the terminal and the
21229 DragonFly computer. Make sure it is the right kind of cable.
21231 Make sure the terminal and DragonFly agree on the bps rate and parity
21232 settings. If you have a video display terminal, make sure the contrast and
21233 brightness controls are turned up. If it is a printing terminal, make sure
21234 paper and ink are in good supply.
21236 Make sure that a getty process is running and serving the terminal. For
21237 example, to get a list of running getty processes with ps, type:
21239 # ps -axww|grep getty
21241 You should see an entry for the terminal. For example, the following
21242 display shows that a getty is running on the second serial port ttyd1 and
21243 is using the std.38400 entry in /etc/gettytab:
21245 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1
21247 If no getty process is running, make sure you have enabled the port in
21248 /etc/ttys. Also remember to run kill -HUP 1 after modifying the ttys file.
21250 If the getty process is running but the terminal still does not display a
21251 login prompt, or if it displays a prompt but will not allow you to type,
21252 your terminal or cable may not support hardware handshaking. Try changing
21253 the entry in /etc/ttys from std.38400 to 3wire.38400 remember to run kill
21254 -HUP 1 after modifying /etc/ttys). The 3wire entry is similar to std, but
21255 ignores hardware handshaking. You may need to reduce the baud rate or
21256 enable software flow control when using 3wire to prevent buffer overflows.
21258 ----------------------------------------------------------------------
21260 17.3.3.2 If Garbage Appears Instead of a Login Prompt
21262 Make sure the terminal and DragonFly agree on the bps rate and parity
21263 settings. Check the getty processes to make sure the correct getty type is
21264 in use. If not, edit /etc/ttys and run kill -HUP 1.
21266 ----------------------------------------------------------------------
21268 17.3.3.3 Characters Appear Doubled; the Password Appears When Typed
21270 Switch the terminal (or the terminal emulation software) from ``half
21271 duplex'' or ``local echo'' to ``full duplex.''
21273 ----------------------------------------------------------------------
21275 17.4 Dial-in Service
21277 Contributed by Guy Helmer. Additions by Sean Kelly.
21279 Configuring your DragonFly system for dial-in service is very similar to
21280 connecting terminals except that you are dealing with modems instead of
21283 ----------------------------------------------------------------------
21285 17.4.1 External vs. Internal Modems
21287 External modems seem to be more convenient for dial-up, because external
21288 modems often can be semi-permanently configured via parameters stored in
21289 non-volatile RAM and they usually provide lighted indicators that display
21290 the state of important RS-232 signals. Blinking lights impress visitors,
21291 but lights are also very useful to see whether a modem is operating
21294 Internal modems usually lack non-volatile RAM, so their configuration may
21295 be limited only to setting DIP switches. If your internal modem has any
21296 signal indicator lights, it is probably difficult to view the lights when
21297 the system's cover is in place.
21299 ----------------------------------------------------------------------
21301 17.4.1.1 Modems and Cables
21303 If you are using an external modem, then you will of course need the
21304 proper cable. A standard RS-232C serial cable should suffice as long as
21305 all of the normal signals are wired:
21307 * Transmitted Data (SD)
21309 * Received Data (RD)
21311 * Request to Send (RTS)
21313 * Clear to Send (CTS)
21315 * Data Set Ready (DSR)
21317 * Data Terminal Ready (DTR)
21319 * Carrier Detect (CD)
21321 * Signal Ground (SG)
21323 DragonFly needs the RTS and CTS signals for flow-control at speeds above
21324 2400 bps, the CD signal to detect when a call has been answered or the
21325 line has been hung up, and the DTR signal to reset the modem after a
21326 session is complete. Some cables are wired without all of the needed
21327 signals, so if you have problems, such as a login session not going away
21328 when the line hangs up, you may have a problem with your cable.
21330 Like other UNIX like operating systems, DragonFly uses the hardware
21331 signals to find out when a call has been answered or a line has been hung
21332 up and to hangup and reset the modem after a call. DragonFly avoids
21333 sending commands to the modem or watching for status reports from the
21334 modem. If you are familiar with connecting modems to PC-based bulletin
21335 board systems, this may seem awkward.
21337 ----------------------------------------------------------------------
21339 17.4.2 Serial Interface Considerations
21341 DragonFly supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA
21342 RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices
21343 have single-character buffers. The 16550 device provides a 16-character
21344 buffer, which allows for better system performance. (Bugs in plain 16550's
21345 prevent the use of the 16-character buffer, so use 16550A's if possible).
21346 Because single-character-buffer devices require more work by the operating
21347 system than the 16-character-buffer devices, 16550A-based serial interface
21348 cards are much preferred. If the system has many active serial ports or
21349 will have a heavy load, 16550A-based cards are better for low-error-rate
21352 ----------------------------------------------------------------------
21354 17.4.3 Quick Overview
21356 As with terminals, init spawns a getty process for each configured serial
21357 port for dial-in connections. For example, if a modem is attached to
21358 /dev/ttyd0, the command ps ax might show this:
21360 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
21362 When a user dials the modem's line and the modems connect, the CD (Carrier
21363 Detect) line is reported by the modem. The kernel notices that carrier has
21364 been detected and completes getty's open of the port. getty sends a login:
21365 prompt at the specified initial line speed. getty watches to see if
21366 legitimate characters are received, and, in a typical configuration, if it
21367 finds junk (probably due to the modem's connection speed being different
21368 than getty's speed), getty tries adjusting the line speeds until it
21369 receives reasonable characters.
21371 After the user enters his/her login name, getty executes /usr/bin/login,
21372 which completes the login by asking for the user's password and then
21373 starting the user's shell.
21375 ----------------------------------------------------------------------
21377 17.4.4 Configuration Files
21379 There are three system configuration files in the /etc directory that you
21380 will probably need to edit to allow dial-up access to your DragonFly
21381 system. The first, /etc/gettytab, contains configuration information for
21382 the /usr/libexec/getty daemon. Second, /etc/ttys holds information that
21383 tells /sbin/init what tty devices should have getty processes running on
21384 them. Lastly, you can place port initialization commands in the
21385 /etc/rc.serial script.
21387 There are two schools of thought regarding dial-up modems on UNIX. One
21388 group likes to configure their modems and systems so that no matter at
21389 what speed a remote user dials in, the local computer-to-modem RS-232
21390 interface runs at a locked speed. The benefit of this configuration is
21391 that the remote user always sees a system login prompt immediately. The
21392 downside is that the system does not know what a user's true data rate is,
21393 so full-screen programs like Emacs will not adjust their screen-painting
21394 methods to make their response better for slower connections.
21396 The other school configures their modems' RS-232 interface to vary its
21397 speed based on the remote user's connection speed. For example, V.32bis
21398 (14.4 Kbps) connections to the modem might make the modem run its RS-232
21399 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232
21400 interface run at 2400 bps. Because getty does not understand any
21401 particular modem's connection speed reporting, getty gives a login:
21402 message at an initial speed and watches the characters that come back in
21403 response. If the user sees junk, it is assumed that they know they should
21404 press the Enter key until they see a recognizable prompt. If the data
21405 rates do not match, getty sees anything the user types as ``junk'', tries
21406 going to the next speed and gives the login: prompt again. This procedure
21407 can continue ad nauseam, but normally only takes a keystroke or two before
21408 the user sees a good prompt. Obviously, this login sequence does not look
21409 as clean as the former ``locked-speed'' method, but a user on a low-speed
21410 connection should receive better interactive response from full-screen
21413 This section will try to give balanced configuration information, but is
21414 biased towards having the modem's data rate follow the connection rate.
21416 ----------------------------------------------------------------------
21418 17.4.4.1 /etc/gettytab
21420 /etc/gettytab is a termcap(5)-style file of configuration information for
21421 getty(8). Please see the gettytab(5) manual page for complete information
21422 on the format of the file and the list of capabilities.
21424 ----------------------------------------------------------------------
21426 17.4.4.1.1 Locked-speed Config
21428 If you are locking your modem's data communications rate at a particular
21429 speed, you probably will not need to make any changes to /etc/gettytab.
21431 ----------------------------------------------------------------------
21433 17.4.4.1.2 Matching-speed Config
21435 You will need to set up an entry in /etc/gettytab to give getty
21436 information about the speeds you wish to use for your modem. If you have a
21437 2400 bps modem, you can probably use the existing D2400 entry.
21440 # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
21442 D2400|d2400|Fast-Dial-2400:\
21443 :nx=D1200:tc=2400-baud:
21444 3|D1200|Fast-Dial-1200:\
21445 :nx=D300:tc=1200-baud:
21446 5|D300|Fast-Dial-300:\
21447 :nx=D2400:tc=300-baud:
21449 If you have a higher speed modem, you will probably need to add an entry
21450 in /etc/gettytab; here is an entry you could use for a 14.4 Kbps modem
21451 with a top interface speed of 19.2 Kbps:
21454 # Additions for a V.32bis Modem
21456 um|V300|High Speed Modem at 300,8-bit:\
21457 :nx=V19200:tc=std.300:
21458 un|V1200|High Speed Modem at 1200,8-bit:\
21459 :nx=V300:tc=std.1200:
21460 uo|V2400|High Speed Modem at 2400,8-bit:\
21461 :nx=V1200:tc=std.2400:
21462 up|V9600|High Speed Modem at 9600,8-bit:\
21463 :nx=V2400:tc=std.9600:
21464 uq|V19200|High Speed Modem at 19200,8-bit:\
21465 :nx=V9600:tc=std.19200:
21467 This will result in 8-bit, no parity connections.
21469 The example above starts the communications rate at 19.2 Kbps (for a
21470 V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps,
21471 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is
21472 implemented with the nx= (``next table'') capability. Each of the lines
21473 uses a tc= (``table continuation'') entry to pick up the rest of the
21474 ``standard'' settings for a particular data rate.
21476 If you have a 28.8 Kbps modem and/or you want to take advantage of
21477 compression on a 14.4 Kbps modem, you need to use a higher communications
21478 rate than 19.2 Kbps. Here is an example of a gettytab entry starting a
21482 # Additions for a V.32bis or V.34 Modem
21483 # Starting at 57.6 Kbps
21485 vm|VH300|Very High Speed Modem at 300,8-bit:\
21486 :nx=VH57600:tc=std.300:
21487 vn|VH1200|Very High Speed Modem at 1200,8-bit:\
21488 :nx=VH300:tc=std.1200:
21489 vo|VH2400|Very High Speed Modem at 2400,8-bit:\
21490 :nx=VH1200:tc=std.2400:
21491 vp|VH9600|Very High Speed Modem at 9600,8-bit:\
21492 :nx=VH2400:tc=std.9600:
21493 vq|VH57600|Very High Speed Modem at 57600,8-bit:\
21494 :nx=VH9600:tc=std.57600:
21496 If you have a slow CPU or a heavily loaded system and do not have
21497 16550A-based serial ports, you may receive ``sio'' ``silo'' errors at
21500 ----------------------------------------------------------------------
21504 Configuration of the /etc/ttys file was covered in Example 17-1.
21505 Configuration for modems is similar but we must pass a different argument
21506 to getty and specify a different terminal type. The general format for
21507 both locked-speed and matching-speed configurations is:
21509 ttyd0 "/usr/libexec/getty xxx" dialup on
21511 The first item in the above line is the device special file for this entry
21512 -- ttyd0 means /dev/ttyd0 is the file that this getty will be watching.
21513 The second item, "/usr/libexec/getty xxx" (xxx will be replaced by the
21514 initial gettytab capability) is the process init will run on the device.
21515 The third item, dialup, is the default terminal type. The fourth
21516 parameter, on, indicates to init that the line is operational. There can
21517 be a fifth parameter, secure, but it should only be used for terminals
21518 which are physically secure (such as the system console).
21520 The default terminal type (dialup in the example above) may depend on
21521 local preferences. dialup is the traditional default terminal type on
21522 dial-up lines so that users may customize their login scripts to notice
21523 when the terminal is dialup and automatically adjust their terminal type.
21524 However, the author finds it easier at his site to specify vt102 as the
21525 default terminal type, since the users just use VT102 emulation on their
21528 After you have made changes to /etc/ttys, you may send the init process a
21529 HUP signal to re-read the file. You can use the command
21533 to send the signal. If this is your first time setting up the system, you
21534 may want to wait until your modem(s) are properly configured and connected
21535 before signaling init.
21537 ----------------------------------------------------------------------
21539 17.4.4.2.1 Locked-speed Config
21541 For a locked-speed configuration, your ttys entry needs to have a
21542 fixed-speed entry provided to getty. For a modem whose port speed is
21543 locked at 19.2 Kbps, the ttys entry might look like this:
21545 ttyd0 "/usr/libexec/getty std.19200" dialup on
21547 If your modem is locked at a different data rate, substitute the
21548 appropriate value for std.speed instead of std.19200. Make sure that you
21549 use a valid type listed in /etc/gettytab.
21551 ----------------------------------------------------------------------
21553 17.4.4.2.2 Matching-speed Config
21555 In a matching-speed configuration, your ttys entry needs to reference the
21556 appropriate beginning ``auto-baud'' (sic) entry in /etc/gettytab. For
21557 example, if you added the above suggested entry for a matching-speed modem
21558 that starts at 19.2 Kbps (the gettytab entry containing the V19200
21559 starting point), your ttys entry might look like this:
21561 ttyd0 "/usr/libexec/getty V19200" dialup on
21563 ----------------------------------------------------------------------
21565 17.4.4.3 /etc/rc.serial
21567 High-speed modems, like V.32, V.32bis, and V.34 modems, need to use
21568 hardware (RTS/CTS) flow control. You can add stty commands to
21569 /etc/rc.serial to set the hardware flow control flag in the DragonFly
21570 kernel for the modem ports.
21572 For example to set the termios flag crtscts on serial port #1's (COM2)
21573 dial-in and dial-out initialization devices, the following lines could be
21574 added to /etc/rc.serial:
21576 # Serial port initial configuration
21577 stty -f /dev/ttyid1 crtscts
21578 stty -f /dev/cuaia1 crtscts
21580 ----------------------------------------------------------------------
21582 17.4.5 Modem Settings
21584 If you have a modem whose parameters may be permanently set in
21585 non-volatile RAM, you will need to use a terminal program (such as Telix
21586 under MS-DOS or tip under DragonFly) to set the parameters. Connect to the
21587 modem using the same communications speed as the initial speed getty will
21588 use and configure the modem's non-volatile RAM to match these
21591 * CD asserted when connected
21593 * DTR asserted for operation; dropping DTR hangs up line and resets
21596 * CTS transmitted data flow control
21598 * Disable XON/XOFF flow control
21600 * RTS received data flow control
21602 * Quiet mode (no result codes)
21606 Please read the documentation for your modem to find out what commands
21607 and/or DIP switch settings you need to give it.
21609 For example, to set the above parameters on a U.S. Robotics(R)
21610 Sportster(R) 14,400 external modem, one could give these commands to the
21614 AT&C1&D2&H1&I0&R2&W
21616 You might also want to take this opportunity to adjust other settings in
21617 the modem, such as whether it will use V.42bis and/or MNP5 compression.
21619 The U.S. Robotics Sportster 14,400 external modem also has some DIP
21620 switches that need to be set; for other modems, perhaps you can use these
21621 settings as an example:
21623 * Switch 1: UP -- DTR Normal
21625 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
21627 * Switch 3: UP -- Suppress Result Codes
21629 * Switch 4: DOWN -- No echo, offline commands
21631 * Switch 5: UP -- Auto Answer
21633 * Switch 6: UP -- Carrier Detect Normal
21635 * Switch 7: UP -- Load NVRAM Defaults
21637 * Switch 8: N/A (Smart Mode/Dumb Mode)
21639 Result codes should be disabled/suppressed for dial-up modems to avoid
21640 problems that can occur if getty mistakenly gives a login: prompt to a
21641 modem that is in command mode and the modem echoes the command or returns
21642 a result code. This sequence can result in a extended, silly conversation
21643 between getty and the modem.
21645 ----------------------------------------------------------------------
21647 17.4.5.1 Locked-speed Config
21649 For a locked-speed configuration, you will need to configure the modem to
21650 maintain a constant modem-to-computer data rate independent of the
21651 communications rate. On a U.S. Robotics Sportster 14,400 external modem,
21652 these commands will lock the modem-to-computer data rate at the speed used
21653 to issue the commands:
21658 ----------------------------------------------------------------------
21660 17.4.5.2 Matching-speed Config
21662 For a variable-speed configuration, you will need to configure your modem
21663 to adjust its serial port data rate to match the incoming call rate. On a
21664 U.S. Robotics Sportster 14,400 external modem, these commands will lock
21665 the modem's error-corrected data rate to the speed used to issue the
21666 commands, but allow the serial port rate to vary for non-error-corrected
21672 ----------------------------------------------------------------------
21674 17.4.5.3 Checking the Modem's Configuration
21676 Most high-speed modems provide commands to view the modem's current
21677 operating parameters in a somewhat human-readable fashion. On the U.S.
21678 Robotics Sportster 14,400 external modems, the command ATI5 displays the
21679 settings that are stored in the non-volatile RAM. To see the true
21680 operating parameters of the modem (as influenced by the modem's DIP switch
21681 settings), use the commands ATZ and then ATI4.
21683 If you have a different brand of modem, check your modem's manual to see
21684 how to double-check your modem's configuration parameters.
21686 ----------------------------------------------------------------------
21688 17.4.6 Troubleshooting
21690 Here are a few steps you can follow to check out the dial-up modem on your
21693 ----------------------------------------------------------------------
21695 17.4.6.1 Checking Out the DragonFly System
21697 Hook up your modem to your DragonFly system, boot the system, and, if your
21698 modem has status indication lights, watch to see whether the modem's DTR
21699 indicator lights when the login: prompt appears on the system's console --
21700 if it lights up, that should mean that DragonFly has started a getty
21701 process on the appropriate communications port and is waiting for the
21702 modem to accept a call.
21704 If the DTR indicator does not light, login to the DragonFly system through
21705 the console and issue a ps ax to see if DragonFly is trying to run a getty
21706 process on the correct port. You should see lines like these among the
21707 processes displayed:
21709 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
21710 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
21712 If you see something different, like this:
21714 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
21716 and the modem has not accepted a call yet, this means that getty has
21717 completed its open on the communications port. This could indicate a
21718 problem with the cabling or a mis-configured modem, because getty should
21719 not be able to open the communications port until CD (carrier detect) has
21720 been asserted by the modem.
21722 If you do not see any getty processes waiting to open the desired ttydN
21723 port, double-check your entries in /etc/ttys to see if there are any
21724 mistakes there. Also, check the log file /var/log/messages to see if there
21725 are any log messages from init or getty regarding any problems. If there
21726 are any messages, triple-check the configuration files /etc/ttys and
21727 /etc/gettytab, as well as the appropriate device special files /dev/ttydN,
21728 for any mistakes, missing entries, or missing device special files.
21730 ----------------------------------------------------------------------
21732 17.4.6.2 Try Dialing In
21734 Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop
21735 bit on the remote system. If you do not get a prompt right away, or get
21736 garbage, try pressing Enter about once per second. If you still do not see
21737 a login: prompt after a while, try sending a BREAK. If you are using a
21738 high-speed modem to do the dialing, try dialing again after locking the
21739 dialing modem's interface speed (via AT&B1 on a U.S. Robotics Sportster
21740 modem, for example).
21742 If you still cannot get a login: prompt, check /etc/gettytab again and
21745 * The initial capability name specified in /etc/ttys for the line
21746 matches a name of a capability in /etc/gettytab
21748 * Each nx= entry matches another gettytab capability name
21750 * Each tc= entry matches another gettytab capability name
21752 If you dial but the modem on the DragonFly system will not answer, make
21753 sure that the modem is configured to answer the phone when DTR is
21754 asserted. If the modem seems to be configured correctly, verify that the
21755 DTR line is asserted by checking the modem's indicator lights (if it has
21758 If you have gone over everything several times and it still does not work,
21759 take a break and come back to it later. If it still does not work, perhaps
21760 you can send an electronic mail message to the DragonFly User related
21761 mailing list describing your modem and your problem, and the good folks on
21762 the list will try to help.
21764 ----------------------------------------------------------------------
21766 17.5 Dial-out Service
21768 The following are tips for getting your host to be able to connect over
21769 the modem to another computer. This is appropriate for establishing a
21770 terminal session with a remote host.
21772 This is useful to log onto a BBS.
21774 This kind of connection can be extremely helpful to get a file on the
21775 Internet if you have problems with PPP. If you need to FTP something and
21776 PPP is broken, use the terminal session to FTP it. Then use zmodem to
21777 transfer it to your machine.
21779 ----------------------------------------------------------------------
21781 17.5.1 My Stock Hayes Modem Is Not Supported, What Can I Do?
21783 Actually, the manual page for tip is out of date. There is a generic Hayes
21784 dialer already built in. Just use at=hayes in your /etc/remote file.
21786 The Hayes driver is not smart enough to recognize some of the advanced
21787 features of newer modems--messages like BUSY, NO DIALTONE, or CONNECT
21788 115200 will just confuse it. You should turn those messages off when you
21789 use tip (using ATX0&W).
21791 Also, the dial timeout for tip is 60 seconds. Your modem should use
21792 something less, or else tip will think there is a communication problem.
21795 Note: As shipped, tip does not yet support Hayes modems fully. The
21796 solution is to edit the file tipconf.h in the directory
21797 /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to
21800 Edit the line #define HAYES 0 to #define HAYES 1. Then make and make
21801 install. Everything works nicely after that.
21803 ----------------------------------------------------------------------
21805 17.5.2 How Am I Expected to Enter These AT Commands?
21807 Make what is called a ``direct'' entry in your /etc/remote file. For
21808 example, if your modem is hooked up to the first serial port, /dev/cuaa0,
21809 then put in the following line:
21811 cuaa0:dv=/dev/cuaa0:br#19200:pa=none
21813 Use the highest bps rate your modem supports in the br capability. Then,
21814 type tip cuaa0 and you will be connected to your modem.
21816 If there is no /dev/cuaa0 on your system, do this:
21821 Or use cu as root with the following command:
21823 # cu -lline -sspeed
21825 line is the serial port (e.g./dev/cuaa0) and speed is the speed
21826 (e.g.57600). When you are done entering the AT commands hit ~. to exit.
21828 ----------------------------------------------------------------------
21830 17.5.3 The @ Sign for the pn Capability Does Not Work!
21832 The @ sign in the phone number capability tells tip to look in /etc/phones
21833 for a phone number. But the @ sign is also a special character in
21834 capability files like /etc/remote. Escape it with a backslash:
21838 ----------------------------------------------------------------------
21840 17.5.4 How Can I Dial a Phone Number on the Command Line?
21842 Put what is called a ``generic'' entry in your /etc/remote file. For
21845 tip115200|Dial any phone number at 115200 bps:\
21846 :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
21847 tip57600|Dial any phone number at 57600 bps:\
21848 :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:
21850 Then you can do things like:
21852 # tip -115200 5551234
21854 If you prefer cu over tip, use a generic cu entry:
21856 cu115200|Use cu to dial any number at 115200bps:\
21857 :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:
21861 # cu 5551234 -s 115200
21863 ----------------------------------------------------------------------
21865 17.5.5 Do I Have to Type in the bps Rate Every Time I Do That?
21867 Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps
21868 rate is appropriate with the br capability. tip thinks a good default is
21869 1200 bps which is why it looks for a tip1200 entry. You do not have to use
21872 ----------------------------------------------------------------------
21874 17.5.6 I Access a Number of Hosts Through a Terminal Server
21876 Rather than waiting until you are connected and typing CONNECT <host> each
21877 time, use tip's cm capability. For example, these entries in /etc/remote:
21879 pain|pain.deep13.com|Forrester's machine:\
21880 :cm=CONNECT pain\n:tc=deep13:
21881 muffin|muffin.deep13.com|Frank's machine:\
21882 :cm=CONNECT muffin\n:tc=deep13:
21883 deep13:Gizmonics Institute terminal server:\
21884 :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:
21886 will let you type tip pain or tip muffin to connect to the hosts pain or
21887 muffin, and tip deep13 to get to the terminal server.
21889 ----------------------------------------------------------------------
21891 17.5.7 Can Tip Try More Than One Line for Each Site?
21893 This is often a problem where a university has several modem lines and
21894 several thousand students trying to use them.
21896 Make an entry for your university in /etc/remote and use @ for the pn
21902 :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:
21904 Then, list the phone numbers for the university in /etc/phones:
21906 big-university 5551111
21907 big-university 5551112
21908 big-university 5551113
21909 big-university 5551114
21911 tip will try each one in the listed order, then give up. If you want to
21912 keep retrying, run tip in a while loop.
21914 ----------------------------------------------------------------------
21916 17.5.8 Why Do I Have to Hit Ctrl+P Twice to Send Ctrl+P Once?
21918 Ctrl+P is the default ``force'' character, used to tell tip that the next
21919 character is literal data. You can set the force character to any other
21920 character with the ~s escape, which means ``set a variable.''
21922 Type ~sforce=single-char followed by a newline. single-char is any single
21923 character. If you leave out single-char, then the force character is the
21924 nul character, which you can get by typing Ctrl+2 or Ctrl+Space. A pretty
21925 good value for single-char is Shift+Ctrl+6, which is only used on some
21928 You can have the force character be whatever you want by specifying the
21929 following in your $HOME/.tiprc file:
21931 force=<single-char>
21933 ----------------------------------------------------------------------
21935 17.5.9 Suddenly Everything I Type Is in Upper Case??
21937 You must have pressed Ctrl+A, tip's ``raise character,'' specially
21938 designed for people with broken caps-lock keys. Use ~s as above and set
21939 the variable raisechar to something reasonable. In fact, you can set it to
21940 the same as the force character, if you never expect to use either of
21943 Here is a sample .tiprc file perfect for Emacs users who need to type
21944 Ctrl+2 and Ctrl+A a lot:
21949 The ^^ is Shift+Ctrl+6.
21951 ----------------------------------------------------------------------
21953 17.5.10 How Can I Do File Transfers with tip?
21955 If you are talking to another UNIX system, you can send and receive files
21956 with ~p (put) and ~t (take). These commands run cat and echo on the remote
21957 system to accept and send files. The syntax is:
21959 ~p local-file [remote-file]
21961 ~t remote-file [local-file]
21963 There is no error checking, so you probably should use another protocol,
21966 ----------------------------------------------------------------------
21968 17.5.11 How Can I Run zmodem with tip?
21970 To receive files, start the sending program on the remote end. Then, type
21971 ~C rz to begin receiving them locally.
21973 To send files, start the receiving program on the remote end. Then, type
21974 ~C sz files to send them to the remote system.
21976 ----------------------------------------------------------------------
21978 17.6 Setting Up the Serial Console
21980 Contributed by Kazutaka YOKOTA. Based on a document by Bill Paul.
21982 ----------------------------------------------------------------------
21984 17.6.1 Introduction
21986 DragonFly has the ability to boot on a system with only a dumb terminal on
21987 a serial port as a console. Such a configuration should be useful for two
21988 classes of people: system administrators who wish to install DragonFly on
21989 machines that have no keyboard or monitor attached, and developers who
21990 want to debug the kernel or device drivers.
21992 As described in Chapter 7, DragonFly employs a three stage bootstrap. The
21993 first two stages are in the boot block code which is stored at the
21994 beginning of the DragonFly slice on the boot disk. The boot block will
21995 then load and run the boot loader (/boot/loader) as the third stage code.
21997 In order to set up the serial console you must configure the boot block
21998 code, the boot loader code and the kernel.
22000 ----------------------------------------------------------------------
22002 17.6.2 Serial Console Configuration, Terse Version
22004 This section assumes that you are using the default setup, know how to
22005 connect serial ports and just want a fast overview of a serial console. If
22006 you encounter difficulty with these steps, please see the more extensive
22007 explaination of all the options and advanced settings in Section 17.6.3.
22009 1. Connect the serial port. The serial console will be on COM1.
22011 2. echo -h > /boot.config to enable the serial console for the boot
22014 3. Edit /etc/ttys and change off to on for the ttyd0 entry. This enables
22015 a login prompt on the serial console, which mirrors how video consoles
22016 are typically setup.
22018 4. shutdown -r now will reboot the system with the serial console.
22020 ----------------------------------------------------------------------
22022 17.6.3 Serial Console Configuration
22024 1. Prepare a serial cable.
22026 You will need either a null-modem cable or a standard serial cable and
22027 a null-modem adapter. See Section 17.2.2 for a discussion on serial
22030 2. Unplug your keyboard.
22032 Most PC systems probe for the keyboard during the Power-On Self-Test
22033 (POST) and will generate an error if the keyboard is not detected.
22034 Some machines complain loudly about the lack of a keyboard and will
22035 not continue to boot until it is plugged in.
22037 If your computer complains about the error, but boots anyway, then you
22038 do not have to do anything special. (Some machines with Phoenix BIOS
22039 installed merely say ``Keyboard failed'' and continue to boot
22042 If your computer refuses to boot without a keyboard attached then you
22043 will have to configure the BIOS so that it ignores this error (if it
22044 can). Consult your motherboard's manual for details on how to do this.
22046 Tip: Setting the keyboard to ``Not installed'' in the BIOS setup
22047 does not mean that you will not be able to use your keyboard. All
22048 this does is tell the BIOS not to probe for a keyboard at power-on,
22049 so it will not complain if the keyboard is not plugged in. You can
22050 leave the keyboard plugged in even with this flag set to ``Not
22051 installed'' and the keyboard will still work.
22053 Note: If your system has a PS/2(R) mouse, chances are very good that
22054 you may have to unplug your mouse as well as your keyboard. This is
22055 because PS/2 mice share some hardware with the keyboard and leaving
22056 the mouse plugged in can fool the keyboard probe into thinking the
22057 keyboard is still there. In general, this is not a problem since the
22058 mouse is not much good without the keyboard anyway.
22060 3. Plug a dumb terminal into COM1 (sio0).
22062 If you do not have a dumb terminal, you can use an old PC/XT with a
22063 modem program, or the serial port on another UNIX box. If you do not
22064 have a COM1 (sio0), get one. At this time, there is no way to select a
22065 port other than COM1 for the boot blocks without recompiling the boot
22066 blocks. If you are already using COM1 for another device, you will
22067 have to temporarily remove that device and install a new boot block
22068 and kernel once you get DragonFly up and running. (It is assumed that
22069 COM1 will be available on a file/compute/terminal server anyway; if
22070 you really need COM1 for something else (and you cannot switch that
22071 something else to COM2 (sio1)), then you probably should not even be
22072 bothering with all this in the first place.)
22074 4. Make sure the configuration file of your kernel has appropriate flags
22075 set for COM1 (sio0).
22077 Relevant flags are:
22081 Enables console support for this unit. The other console
22082 flags are ignored unless this is set. Currently, at most
22083 one unit can have console support; the first one (in
22084 config file order) with this flag set is preferred. This
22085 option alone will not make the serial port the console.
22086 Set the following flag or use the -h option described
22087 below, together with this flag.
22091 Forces this unit to be the console (unless there is
22092 another higher priority console), regardless of the -h
22093 option discussed below. This flag replaces the COMCONSOLE
22094 option in DragonFly versions 2.X. The flag 0x20 must be
22095 used together with the 0x10 flag.
22099 Reserves this unit (in conjunction with 0x10) and makes
22100 the unit unavailable for normal access. You should not
22101 set this flag to the serial port unit which you want to
22102 use as the serial console. This reserves this port for
22103 "low-level IO", i.e. kernel debugging.
22107 This port will be used for remote kernel debugging.
22111 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
22113 See the sio(4) manual page for more details.
22115 If the flags were not set, you need to run UserConfig (on a different
22116 console) or recompile the kernel.
22118 5. Create boot.config in the root directory of the a partition on the
22121 This file will instruct the boot block code how you would like to boot
22122 the system. In order to activate the serial console, you need one or
22123 more of the following options--if you want multiple options, include
22124 them all on the same line:
22128 Toggles internal and serial consoles. You can use this to
22129 switch console devices. For instance, if you boot from
22130 the internal (video) console, you can use -h to direct
22131 the boot loader and the kernel to use the serial port as
22132 its console device. Alternatively, if you boot from the
22133 serial port, you can use the -h to tell the boot loader
22134 and the kernel to use the video display as the console
22139 Toggles single and dual console configurations. In the
22140 single configuration the console will be either the
22141 internal console (video display) or the serial port,
22142 depending on the state of the -h option above. In the
22143 dual console configuration, both the video display and
22144 the serial port will become the console at the same time,
22145 regardless of the state of the -h option. However, note
22146 that the dual console configuration takes effect only
22147 during the boot block is running. Once the boot loader
22148 gets control, the console specified by the -h option
22149 becomes the only console.
22153 Makes the boot block probe the keyboard. If no keyboard
22154 is found, the -D and -h options are automatically set.
22156 Note: Due to space constraints in the current version
22157 of the boot blocks, the -P option is capable of
22158 detecting extended keyboards only. Keyboards with less
22159 than 101 keys (and without F11 and F12 keys) may not be
22160 detected. Keyboards on some laptop computers may not be
22161 properly found because of this limitation. If this is
22162 the case with your system, you have to abandon using
22163 the -P option. Unfortunately there is no workaround for
22166 Use either the -P option to select the console automatically, or the
22167 -h option to activate the serial console.
22169 You may include other options described in boot(8) as well.
22171 The options, except for -P, will be passed to the boot loader
22172 (/boot/loader). The boot loader will determine which of the internal
22173 video or the serial port should become the console by examining the
22174 state of the -h option alone. This means that if you specify the -D
22175 option but not the -h option in /boot.config, you can use the serial
22176 port as the console only during the boot block; the boot loader will
22177 use the internal video display as the console.
22179 6. Boot the machine.
22181 When you start your DragonFly box, the boot blocks will echo the
22182 contents of /boot.config to the console. For example:
22187 The second line appears only if you put -P in /boot.config and
22188 indicates presence/absence of the keyboard. These messages go to
22189 either serial or internal console, or both, depending on the option in
22192 Options Message goes to
22193 none internal console
22195 -D serial and internal consoles
22196 -Dh serial and internal consoles
22197 -P, keyboard present internal console
22198 -P, keyboard absent serial console
22200 After the above messages, there will be a small pause before the boot
22201 blocks continue loading the boot loader and before any further
22202 messages printed to the console. Under normal circumstances, you do
22203 not need to interrupt the boot blocks, but you may want to do so in
22204 order to make sure things are set up correctly.
22206 Hit any key, other than Enter, at the console to interrupt the boot
22207 process. The boot blocks will then prompt you for further action. You
22208 should now see something like:
22210 >> DragonFly/i386 BOOT
22211 Default: 0:ad(0,a)/boot/loader
22214 Verify the above message appears on either the serial or internal
22215 console or both, according to the options you put in /boot.config. If
22216 the message appears in the correct console, hit Enter to continue the
22219 If you want the serial console but you do not see the prompt on the
22220 serial terminal, something is wrong with your settings. In the
22221 meantime, you enter -h and hit Enter/Return (if possible) to tell the
22222 boot block (and then the boot loader and the kernel) to choose the
22223 serial port for the console. Once the system is up, go back and check
22226 After the boot loader is loaded and you are in the third stage of the boot
22227 process you can still switch between the internal console and the serial
22228 console by setting appropriate environment variables in the boot loader.
22229 See Section 17.6.6.
22231 ----------------------------------------------------------------------
22235 Here is the summary of various settings discussed in this section and the
22236 console eventually selected.
22238 ----------------------------------------------------------------------
22240 17.6.4.1 Case 1: You Set the Flags to 0x10 for sio0
22242 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
22244 Options in Console during Console during Console in
22245 /boot.config boot blocks boot loader kernel
22246 nothing internal internal internal
22247 -h serial serial serial
22248 -D serial and internal internal
22250 -Dh serial and serial serial
22252 -P, keyboard present internal internal internal
22253 -P, keyboard absent serial and serial serial
22256 ----------------------------------------------------------------------
22258 17.6.4.2 Case 2: You Set the Flags to 0x30 for sio0
22260 device sio0 at isa? port IO_COM1 flags 0x30 irq 4
22262 Options in Console during Console during Console in
22263 /boot.config boot blocks boot loader kernel
22264 nothing internal internal serial
22265 -h serial serial serial
22266 -D serial and internal serial
22268 -Dh serial and serial serial
22270 -P, keyboard present internal internal serial
22271 -P, keyboard absent serial and serial serial
22274 ----------------------------------------------------------------------
22276 17.6.5 Tips for the Serial Console
22278 17.6.5.1 Setting a Faster Serial Port Speed
22280 By default, the serial port settings are: 9600 baud, 8 bits, no parity,
22281 and 1 stop bit. If you wish to change the speed, you need to recompile at
22282 least the boot blocks. Add the following line to /etc/make.conf and
22283 compile new boot blocks:
22285 BOOT_COMCONSOLE_SPEED=19200
22287 If the serial console is configured in some other way than by booting with
22288 -h, or if the serial console used by the kernel is different from the one
22289 used by the boot blocks, then you must also add the following option to
22290 the kernel configuration file and compile a new kernel:
22292 options CONSPEED=19200
22294 ----------------------------------------------------------------------
22296 17.6.5.2 Using Serial Port Other Than sio0 for the Console
22298 Using a port other than sio0 as the console requires some recompiling. If
22299 you want to use another serial port for whatever reasons, recompile the
22300 boot blocks, the boot loader and the kernel as follows.
22302 1. Get the kernel source. (See Section 21.1)
22304 2. Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the
22305 port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only sio0 through
22306 sio3 (COM1 through COM4) can be used; multiport serial cards will not
22307 work. No interrupt setting is needed.
22309 3. Create a custom kernel configuration file and add appropriate flags
22310 for the serial port you want to use. For example, if you want to make
22311 sio1 (COM2) the console:
22313 device sio1 at isa? port IO_COM2 flags 0x10 irq 3
22317 device sio1 at isa? port IO_COM2 flags 0x30 irq 3
22319 The console flags for the other serial ports should not be set.
22321 4. Recompile and install the boot blocks and the boot loader:
22327 5. Rebuild and install the kernel.
22329 6. Write the boot blocks to the boot disk with disklabel(8) and boot from
22332 ----------------------------------------------------------------------
22334 17.6.5.3 Entering the DDB Debugger from the Serial Line
22336 If you wish to drop into the kernel debugger from the serial console
22337 (useful for remote diagnostics, but also dangerous if you generate a
22338 spurious BREAK on the serial port!) then you should compile your kernel
22339 with the following options:
22341 options BREAK_TO_DEBUGGER
22344 ----------------------------------------------------------------------
22346 17.6.5.4 Getting a Login Prompt on the Serial Console
22348 While this is not required, you may wish to get a login prompt over the
22349 serial line, now that you can see boot messages and can enter the kernel
22350 debugging session through the serial console. Here is how to do it.
22352 Open the file /etc/ttys with an editor and locate the lines:
22354 ttyd0 "/usr/libexec/getty std.9600" unknown off secure
22355 ttyd1 "/usr/libexec/getty std.9600" unknown off secure
22356 ttyd2 "/usr/libexec/getty std.9600" unknown off secure
22357 ttyd3 "/usr/libexec/getty std.9600" unknown off secure
22359 ttyd0 through ttyd3 corresponds to COM1 through COM4. Change off to on for
22360 the desired port. If you have changed the speed of the serial port, you
22361 need to change std.9600 to match the current setting, e.g. std.19200.
22363 You may also want to change the terminal type from unknown to the actual
22364 type of your serial terminal.
22366 After editing the file, you must kill -HUP 1 to make this change take
22369 ----------------------------------------------------------------------
22371 17.6.6 Changing Console from the Boot Loader
22373 Previous sections described how to set up the serial console by tweaking
22374 the boot block. This section shows that you can specify the console by
22375 entering some commands and environment variables in the boot loader. As
22376 the boot loader is invoked at the third stage of the boot process, after
22377 the boot block, the settings in the boot loader will override the settings
22380 ----------------------------------------------------------------------
22382 17.6.6.1 Setting Up the Serial Console
22384 You can easily specify the boot loader and the kernel to use the serial
22385 console by writing just one line in /boot/loader.rc:
22387 set console=comconsole
22389 This will take effect regardless of the settings in the boot block
22390 discussed in the previous section.
22392 You had better put the above line as the first line of /boot/loader.rc so
22393 as to see boot messages on the serial console as early as possible.
22395 Likewise, you can specify the internal console as:
22397 set console=vidconsole
22399 If you do not set the boot loader environment variable console, the boot
22400 loader, and subsequently the kernel, will use whichever console indicated
22401 by the -h option in the boot block.
22403 In versions 3.2 or later, you may specify the console in
22404 /boot/loader.conf.local or /boot/loader.conf, rather than in
22405 /boot/loader.rc. In this method your /boot/loader.rc should look like:
22407 include /boot/loader.4th
22410 Then, create /boot/loader.conf.local and put the following line there.
22418 See loader.conf(5) for more information.
22420 Note: At the moment, the boot loader has no option equivalent to the -P
22421 option in the boot block, and there is no provision to automatically
22422 select the internal console and the serial console based on the presence
22425 ----------------------------------------------------------------------
22427 17.6.6.2 Using a Serial Port Other Than sio0 for the Console
22429 You need to recompile the boot loader to use a serial port other than sio0
22430 for the serial console. Follow the procedure described in Section
22433 ----------------------------------------------------------------------
22437 The idea here is to allow people to set up dedicated servers that require
22438 no graphics hardware or attached keyboards. Unfortunately, while most
22439 systems will let you boot without a keyboard, there are quite a few that
22440 will not let you boot without a graphics adapter. Machines with AMI BIOSes
22441 can be configured to boot with no graphics adapter installed simply by
22442 changing the ``graphics adapter'' setting in the CMOS configuration to
22445 However, many machines do not support this option and will refuse to boot
22446 if you have no display hardware in the system. With these machines, you
22447 will have to leave some kind of graphics card plugged in, (even if it is
22448 just a junky mono board) although you will not have to attach a monitor.
22449 You might also try installing an AMI BIOS.
22451 ----------------------------------------------------------------------
22453 Chapter 18 PPP and SLIP
22455 Restructured, reorganized, and updated by Jim Mock.
22459 DragonFly has a number of ways to link one computer to another. To
22460 establish a network or Internet connection through a dial-up modem, or to
22461 allow others to do so through you, requires the use of PPP or SLIP. This
22462 chapter describes setting up these modem-based communication services in
22465 After reading this chapter, you will know:
22467 * How to set up user PPP.
22469 * How to set up kernel PPP.
22471 * How to set up PPPoE (PPP over Ethernet).
22473 * How to set up PPPoA (PPP over ATM).
22475 * How to configure and set up a SLIP client and server.
22477 Before reading this chapter, you should:
22479 * Be familiar with basic network terminology.
22481 * Understand the basics and purpose of a dialup connection and PPP
22484 You may be wondering what the main difference is between user PPP and
22485 kernel PPP. The answer is simple: user PPP processes the inbound and
22486 outbound data in userland rather than in the kernel. This is expensive in
22487 terms of copying the data between the kernel and userland, but allows a
22488 far more feature-rich PPP implementation. User PPP uses the tun device to
22489 communicate with the outside world whereas kernel PPP uses the ppp device.
22491 Note: Throughout in this chapter, user PPP will simply be referred to as
22492 ppp unless a distinction needs to be made between it and any other PPP
22493 software such as pppd. Unless otherwise stated, all of the commands
22494 explained in this chapter should be executed as root.
22496 ----------------------------------------------------------------------
22498 18.2 Using User PPP
22500 Updated and enhanced by Tom Rhodes. Originally contributed by Brian
22501 Somers. With input from Nik Clayton, Dirk Fro:mberg, and Peter Childs.
22505 18.2.1.1 Assumptions
22507 This document assumes you have the following:
22509 * An account with an Internet Service Provider (ISP) which you connect
22512 * You have a modem or other device connected to your system and
22513 configured correctly which allows you to connect to your ISP.
22515 * The dial-up number(s) of your ISP.
22517 * Your login name and password. (Either a regular UNIX style login and
22518 password pair, or a PAP or CHAP login and password pair.)
22520 * The IP address of one or more name servers. Normally, you will be
22521 given two IP addresses by your ISP to use for this. If they have not
22522 given you at least one, then you can use the enable dns command in
22523 ppp.conf and ppp will set the name servers for you. This feature
22524 depends on your ISPs PPP implementation supporting DNS negotiation.
22526 The following information may be supplied by your ISP, but is not
22527 completely necessary:
22529 * The IP address of your ISP's gateway. The gateway is the machine to
22530 which you will connect and will be set up as your default route. If
22531 you do not have this information, we can make one up and your ISP's
22532 PPP server will tell us the correct value when we connect.
22534 This IP number is referred to as HISADDR by ppp.
22536 * The netmask you should use. If your ISP has not provided you with one,
22537 you can safely use 255.255.255.255.
22539 * If your ISP provides you with a static IP address and hostname, you
22540 can enter it. Otherwise, we simply let the peer assign whatever IP
22541 address it sees fit.
22543 If you do not have any of the required information, contact your ISP.
22545 Note: Throughout this section, many of the examples showing the contents
22546 of configuration files are numbered by line. These numbers serve to aid
22547 in the presentation and discussion only and are not meant to be placed
22548 in the actual file. Proper indentation with tab and space characters is
22551 ----------------------------------------------------------------------
22553 18.2.1.2 Creating PPP Device Nodes
22555 Under normal circumstances, most users will only need one tun device
22556 (/dev/tun0). References to tun0 below may be changed to tunN where N is
22557 any unit number corresponding to your system.
22559 The easiest way to make sure that the tun0 device is configured correctly
22560 is to remake the device. To remake the device, do the following:
22565 If you need 16 tunnel devices in your kernel, you will need to create
22566 them. This can be done by executing the following commands:
22571 ----------------------------------------------------------------------
22573 18.2.1.3 Automatic PPP Configuration
22575 Both ppp and pppd (the kernel level implementation of PPP) use the
22576 configuration files located in the /etc/ppp directory. Examples for user
22577 ppp can be found in /usr/share/examples/ppp/.
22579 Configuring ppp requires that you edit a number of files, depending on
22580 your requirements. What you put in them depends to some extent on whether
22581 your ISP allocates IP addresses statically (i.e., you get given one IP
22582 address, and always use that one) or dynamically (i.e., your IP address
22583 changes each time you connect to your ISP).
22585 ----------------------------------------------------------------------
22587 18.2.1.3.1 PPP and Static IP Addresses
22589 You will need to edit the /etc/ppp/ppp.conf configuration file. It should
22590 look similar to the example below.
22592 Note: Lines that end in a : start in the first column (beginning of the
22593 line)-- all other lines should be indented as shown using spaces or
22597 2 set log Phase Chat LCP IPCP CCP tun command
22598 3 ident user-ppp VERSION (built COMPILATIONDATE)
22599 4 set device /dev/cuaa0
22601 6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
22602 7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
22607 12 set phone "(123) 456 7890"
22608 13 set authname foo
22610 15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
22612 17 set ifaddr x.x.x.x y.y.y.y 255.255.255.255 0.0.0.0
22613 18 add default HISADDR
22617 Identifies the default entry. Commands in this entry are executed
22618 automatically when ppp is run.
22622 Enables logging parameters. When the configuration is working
22623 satisfactorily, this line should be reduced to saying
22627 in order to avoid excessive log file sizes.
22631 Tells PPP how to identify itself to the peer. PPP identifies
22632 itself to the peer if it has any trouble negotiating and setting
22633 up the link, providing information that the peers administrator
22634 may find useful when investigating such problems.
22638 Identifies the device to which the modem is connected. COM1 is
22639 /dev/cuaa0 and COM2 is /dev/cuaa1.
22643 Sets the speed you want to connect at. If 115200 does not work (it
22644 should with any reasonably new modem), try 38400 instead.
22648 The dial string. User PPP uses an expect-send syntax similar to
22649 the chat(8) program. Refer to the manual page for information on
22650 the features of this language.
22652 Note that this command continues onto the next line for
22653 readability. Any command in ppp.conf may do this if the last
22654 character on the line is a ``\'' character.
22658 Sets the idle timeout for the link. 180 seconds is the default, so
22659 this line is purely cosmetic.
22663 Tells PPP to ask the peer to confirm the local resolver settings.
22664 If you run a local name server, this line should be commented out
22669 A blank line for readability. Blank lines are ignored by PPP.
22673 Identifies an entry for a provider called ``provider''. This could
22674 be changed to the name of your ISP so that later you can use the
22675 load ISP to start the connection.
22679 Sets the phone number for this provider. Multiple phone numbers
22680 may be specified using the colon (:) or pipe character (|)as a
22681 separator. The difference between the two separators is described
22682 in ppp(8). To summarize, if you want to rotate through the
22683 numbers, use a colon. If you want to always attempt to dial the
22684 first number first and only use the other numbers if the first
22685 number fails, use the pipe character. Always quote the entire set
22686 of phone numbers as shown.
22688 You must enclose the phone number in quotation marks (") if there
22689 is any intention on using spaces in the phone number. This can
22690 cause a simple, yet subtle error.
22694 Identifies the user name and password. When connecting using a
22695 UNIX style login prompt, these values are referred to by the set
22696 login command using the \U and \P variables. When connecting using
22697 PAP or CHAP, these values are used at authentication time.
22701 If you are using PAP or CHAP, there will be no login at this
22702 point, and this line should be commented out or removed. See PAP
22703 and CHAP authentication for further details.
22705 The login string is of the same chat-like syntax as the dial
22706 string. In this example, the string works for a service whose
22707 login session looks like this:
22714 You will need to alter this script to suit your own needs. When
22715 you write this script for the first time, you should ensure that
22716 you have enabled ``chat'' logging so you can determine if the
22717 conversation is going as expected.
22721 Sets the default idle timeout (in seconds) for the connection.
22722 Here, the connection will be closed automatically after 300
22723 seconds of inactivity. If you never want to timeout, set this
22724 value to zero or use the -ddial command line switch.
22728 Sets the interface addresses. The string x.x.x.x should be
22729 replaced by the IP address that your provider has allocated to
22730 you. The string y.y.y.y should be replaced by the IP address that
22731 your ISP indicated for their gateway (the machine to which you
22732 connect). If your ISP has not given you a gateway address, use
22733 10.0.0.2/0. If you need to use a ``guessed'' address, make sure
22734 that you create an entry in /etc/ppp/ppp.linkup as per the
22735 instructions for PPP and Dynamic IP addresses. If this line is
22736 omitted, ppp cannot run in -auto mode.
22740 Adds a default route to your ISP's gateway. The special word
22741 HISADDR is replaced with the gateway address specified on line 17.
22742 It is important that this line appears after line 17, otherwise
22743 HISADDR will not yet be initialized.
22745 If you do not wish to run ppp in -auto, this line should be moved
22746 to the ppp.linkup file.
22748 It is not necessary to add an entry to ppp.linkup when you have a static
22749 IP address and are running ppp in -auto mode as your routing table entries
22750 are already correct before you connect. You may however wish to create an
22751 entry to invoke programs after connection. This is explained later with
22752 the sendmail example.
22754 Example configuration files can be found in the /usr/share/examples/ppp/
22757 ----------------------------------------------------------------------
22759 18.2.1.3.2 PPP and Dynamic IP Addresses
22761 If your service provider does not assign static IP addresses, ppp can be
22762 configured to negotiate the local and remote addresses. This is done by
22763 ``guessing'' an IP address and allowing ppp to set it up correctly using
22764 the IP Configuration Protocol (IPCP) after connecting. The ppp.conf
22765 configuration is the same as PPP and Static IP Addresses, with the
22768 17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255
22770 Again, do not include the line number, it is just for reference.
22771 Indentation of at least one space is required.
22775 The number after the / character is the number of bits of the
22776 address that ppp will insist on. You may wish to use IP numbers
22777 more appropriate to your circumstances, but the above example will
22780 The last argument (0.0.0.0) tells PPP to start negotiations using
22781 address 0.0.0.0 rather than 10.0.0.1 and is necessary for some
22782 ISPs. Do not use 0.0.0.0 as the first argument to set ifaddr as it
22783 prevents PPP from setting up an initial route in -auto mode.
22785 If you are not running in -auto mode, you will need to create an entry in
22786 /etc/ppp/ppp.linkup. ppp.linkup is used after a connection has been
22787 established. At this point, ppp will have assigned the interface addresses
22788 and it will now be possible to add the routing table entries:
22791 2 add default HISADDR
22795 On establishing a connection, ppp will look for an entry in
22796 ppp.linkup according to the following rules: First, try to match
22797 the same label as we used in ppp.conf. If that fails, look for an
22798 entry for the IP address of our gateway. This entry is a
22799 four-octet IP style label. If we still have not found an entry,
22800 look for the MYADDR entry.
22804 This line tells ppp to add a default route that points to HISADDR.
22805 HISADDR will be replaced with the IP number of the gateway as
22806 negotiated by the IPCP.
22808 See the pmdemand entry in the files
22809 /usr/share/examples/ppp/ppp.conf.sample and
22810 /usr/share/examples/ppp/ppp.linkup.sample for a detailed example.
22812 ----------------------------------------------------------------------
22814 18.2.1.3.3 Receiving Incoming Calls
22816 When you configure ppp to receive incoming calls on a machine connected to
22817 a LAN, you must decide if you wish to forward packets to the LAN. If you
22818 do, you should allocate the peer an IP number from your LAN's subnet, and
22819 use the command enable proxy in your /etc/ppp/ppp.conf file. You should
22820 also confirm that the /etc/rc.conf file contains the following:
22822 gateway_enable="YES"
22824 ----------------------------------------------------------------------
22826 18.2.1.3.4 Which getty?
22828 Configuring DragonFly for Dial-up Services provides a good description on
22829 enabling dial-up services using getty(8).
22831 An alternative to getty is mgetty, a smarter version of getty designed
22832 with dial-up lines in mind.
22834 The advantages of using mgetty is that it actively talks to modems,
22835 meaning if port is turned off in /etc/ttys then your modem will not answer
22838 Later versions of mgetty (from 0.99beta onwards) also support the
22839 automatic detection of PPP streams, allowing your clients script-less
22840 access to your server.
22842 Refer to Mgetty and AutoPPP for more information on mgetty.
22844 ----------------------------------------------------------------------
22846 18.2.1.3.5 PPP Permissions
22848 The ppp command must normally be run as the root user. If however, you
22849 wish to allow ppp to run in server mode as a normal user by executing ppp
22850 as described below, that user must be given permission to run ppp by
22851 adding them to the network group in /etc/group.
22853 You will also need to give them access to one or more sections of the
22854 configuration file using the allow command:
22856 allow users fred mary
22858 If this command is used in the default section, it gives the specified
22859 users access to everything.
22861 ----------------------------------------------------------------------
22863 18.2.1.3.6 PPP Shells for Dynamic-IP Users
22865 Create a file called /etc/ppp/ppp-shell containing the following:
22868 IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
22872 if [ x$IDENT = xdialup ]; then
22873 IDENT=`basename $TTY`
22876 echo "PPP for $CALLEDAS on $TTY"
22877 echo "Starting PPP for $IDENT"
22879 exec /usr/sbin/ppp -direct $IDENT
22881 This script should be executable. Now make a symbolic link called
22882 ppp-dialup to this script using the following commands:
22884 # ln -s ppp-shell /etc/ppp/ppp-dialup
22886 You should use this script as the shell for all of your dialup users. This
22887 is an example from /etc/password for a dialup PPP user with username
22888 pchilds (remember do not directly edit the password file, use vipw).
22890 pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup
22892 Create a /home/ppp directory that is world readable containing the
22893 following 0 byte files:
22895 -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
22896 -r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts
22898 which prevents /etc/motd from being displayed.
22900 ----------------------------------------------------------------------
22902 18.2.1.3.7 PPP Shells for Static-IP Users
22904 Create the ppp-shell file as above, and for each account with statically
22905 assigned IPs create a symbolic link to ppp-shell.
22907 For example, if you have three dialup customers, fred, sam, and mary, that
22908 you route class C networks for, you would type the following:
22910 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
22911 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
22912 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary
22914 Each of these users dialup accounts should have their shell set to the
22915 symbolic link created above (for example, mary's shell should be
22916 /etc/ppp/ppp-mary).
22918 ----------------------------------------------------------------------
22920 18.2.1.3.8 Setting Up ppp.conf for Dynamic-IP Users
22922 The /etc/ppp/ppp.conf file should contain something along the lines of:
22925 set debug phase lcp chat
22929 set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
22933 set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
22936 Note: The indenting is important.
22938 The default: section is loaded for each session. For each dialup line
22939 enabled in /etc/ttys create an entry similar to the one for ttyd0: above.
22940 Each line should get a unique IP address from your pool of IP addresses
22943 ----------------------------------------------------------------------
22945 18.2.1.3.9 Setting Up ppp.conf for Static-IP Users
22947 Along with the contents of the sample /usr/share/examples/ppp/ppp.conf
22948 above you should add a section for each of the statically assigned dialup
22949 users. We will continue with our fred, sam, and mary example.
22952 set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
22955 set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
22958 set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255
22960 The file /etc/ppp/ppp.linkup should also contain routing information for
22961 each static IP user if required. The line below would add a route for the
22962 203.14.101.0 class C via the client's ppp link.
22965 add 203.14.101.0 netmask 255.255.255.0 HISADDR
22968 add 203.14.102.0 netmask 255.255.255.0 HISADDR
22971 add 203.14.103.0 netmask 255.255.255.0 HISADDR
22973 ----------------------------------------------------------------------
22975 18.2.1.3.10 mgetty and AutoPPP
22977 Configuring and compiling mgetty with the AUTO_PPP option enabled allows
22978 mgetty to detect the LCP phase of PPP connections and automatically spawn
22979 off a ppp shell. However, since the default login/password sequence does
22980 not occur it is necessary to authenticate users using either PAP or CHAP.
22982 This section assumes the user has successfully configured, compiled, and
22983 installed a version of mgetty with the AUTO_PPP option (v0.99beta or
22986 Make sure your /usr/local/etc/mgetty+sendfax/login.config file has the
22989 /AutoPPP/ - - /etc/ppp/ppp-pap-dialup
22991 This will tell mgetty to run the ppp-pap-dialup script for detected PPP
22994 Create a file called /etc/ppp/ppp-pap-dialup containing the following (the
22995 file should be executable):
22998 exec /usr/sbin/ppp -direct pap$IDENT
23000 For each dialup line enabled in /etc/ttys, create a corresponding entry in
23001 /etc/ppp/ppp.conf. This will happily co-exist with the definitions we
23006 set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
23009 Each user logging in with this method will need to have a
23010 username/password in /etc/ppp/ppp.secret file, or alternatively add the
23011 following option to authenticate users via PAP from /etc/password file.
23015 If you wish to assign some users a static IP number, you can specify the
23016 number as the third argument in /etc/ppp/ppp.secret. See
23017 /usr/share/examples/ppp/ppp.secret.sample for examples.
23019 ----------------------------------------------------------------------
23021 18.2.1.3.11 MS Extensions
23023 It is possible to configure PPP to supply DNS and NetBIOS nameserver
23024 addresses on demand.
23026 To enable these extensions with PPP version 1.x, the following lines might
23027 be added to the relevant section of /etc/ppp/ppp.conf.
23030 set ns 203.14.100.1 203.14.100.2
23031 set nbns 203.14.100.5
23033 And for PPP version 2 and above:
23036 set dns 203.14.100.1 203.14.100.2
23037 set nbns 203.14.100.5
23039 This will tell the clients the primary and secondary name server
23040 addresses, and a NetBIOS nameserver host.
23042 In version 2 and above, if the set dns line is omitted, PPP will use the
23043 values found in /etc/resolv.conf.
23045 ----------------------------------------------------------------------
23047 18.2.1.3.12 PAP and CHAP Authentication
23049 Some ISPs set their system up so that the authentication part of your
23050 connection is done using either of the PAP or CHAP authentication
23051 mechanisms. If this is the case, your ISP will not give a login: prompt
23052 when you connect, but will start talking PPP immediately.
23054 PAP is less secure than CHAP, but security is not normally an issue here
23055 as passwords, although being sent as plain text with PAP, are being
23056 transmitted down a serial line only. There is not much room for crackers
23059 Referring back to the PPP and Static IP addresses or PPP and Dynamic IP
23060 addresses sections, the following alterations must be made:
23062 13 set authname MyUserName
23063 14 set authkey MyPassword
23068 This line specifies your PAP/CHAP user name. You will need to
23069 insert the correct value for MyUserName.
23073 This line specifies your PAP/CHAP password. You will need to
23074 insert the correct value for MyPassword. You may want to add an
23075 additional line, such as:
23083 to make it obvious that this is the intention, but PAP and CHAP
23084 are both accepted by default.
23088 Your ISP will not normally require that you log into the server if
23089 you are using PAP or CHAP. You must therefore disable your ``set
23092 ----------------------------------------------------------------------
23094 18.2.1.3.13 Changing Your ppp Configuration on the Fly
23096 It is possible to talk to the ppp program while it is running in the
23097 background, but only if a suitable diagnostic port has been set up. To do
23098 this, add the following line to your configuration:
23100 set server /var/run/ppp-tun%d DiagnosticPassword 0177
23102 This will tell PPP to listen to the specified UNIX domain socket, asking
23103 clients for the specified password before allowing access. The %d in the
23104 name is replaced with the tun device number that is in use.
23106 Once a socket has been set up, the pppctl(8) program may be used in
23107 scripts that wish to manipulate the running program.
23109 ----------------------------------------------------------------------
23111 18.2.1.4 Using PPP Network Address Translation Capability
23113 PPP has ability to use internal NAT without kernel diverting capabilities.
23114 This functionality may be enabled by the following line in
23119 Alternatively, PPP NAT may be enabled by command-line option -nat. There
23120 is also /etc/rc.conf knob named ppp_nat, which is enabled by default.
23122 If you use this feature, you may also find useful the following
23123 /etc/ppp/ppp.conf options to enable incoming connections forwarding:
23125 nat port tcp 10.0.0.2:ftp ftp
23126 nat port tcp 10.0.0.2:http http
23128 or do not trust the outside at all
23130 nat deny_incoming yes
23132 ----------------------------------------------------------------------
23134 18.2.1.5 Final System Configuration
23136 You now have ppp configured, but there are a few more things to do before
23137 it is ready to work. They all involve editing the /etc/rc.conf file.
23139 Working from the top down in this file, make sure the hostname= line is
23142 hostname="foo.example.com"
23144 If your ISP has supplied you with a static IP address and name, it is
23145 probably best that you use this name as your host name.
23147 Look for the network_interfaces variable. If you want to configure your
23148 system to dial your ISP on demand, make sure the tun0 device is added to
23149 the list, otherwise remove it.
23151 network_interfaces="lo0 tun0"
23154 Note: The ifconfig_tun0 variable should be empty, and a file called
23155 /etc/start_if.tun0 should be created. This file should contain the line:
23159 This script is executed at network configuration time, starting your ppp
23160 daemon in automatic mode. If you have a LAN for which this machine is a
23161 gateway, you may also wish to use the -alias switch. Refer to the manual
23162 page for further details.
23164 Make sure the router program set to NO with following line in your
23169 It is important that the routed daemon is not started (it is by default),
23170 as routed tends to delete the default routing table entries created by
23173 It is probably worth your while ensuring that the sendmail_flags line does
23174 not include the -q option, otherwise sendmail will attempt to do a network
23175 lookup every now and then, possibly causing your machine to dial out. You
23178 sendmail_flags="-bd"
23180 The downside of this is that you must force sendmail to re-examine the
23181 mail queue whenever the ppp link is up by typing:
23183 # /usr/sbin/sendmail -q
23185 You may wish to use the !bg command in ppp.linkup to do this
23191 4 !bg sendmail -bd -q30m
23193 If you do not like this, it is possible to set up a ``dfilter'' to block
23194 SMTP traffic. Refer to the sample files for further details.
23196 All that is left is to reboot the machine. After rebooting, you can now
23201 and then dial provider to start the PPP session, or, if you want ppp to
23202 establish sessions automatically when there is outbound traffic (and you
23203 have not created the start_if.tun0 script), type:
23205 # ppp -auto provider
23207 ----------------------------------------------------------------------
23211 To recap, the following steps are necessary when setting up ppp for the
23216 1. Ensure that the tun device is built into your kernel.
23218 2. Ensure that the tunN device file is available in the /dev directory.
23220 3. Create an entry in /etc/ppp/ppp.conf. The pmdemand example should
23221 suffice for most ISPs.
23223 4. If you have a dynamic IP address, create an entry in
23224 /etc/ppp/ppp.linkup.
23226 5. Update your /etc/rc.conf file.
23228 6. Create a start_if.tun0 script if you require demand dialing.
23232 1. Ensure that the tun device is built into your kernel.
23234 2. Ensure that the tunN device file is available in the /dev directory.
23236 3. Create an entry in /etc/passwd (using the vipw(8) program).
23238 4. Create a profile in this users home directory that runs ppp -direct
23239 direct-server or similar.
23241 5. Create an entry in /etc/ppp/ppp.conf. The direct-server example should
23244 6. Create an entry in /etc/ppp/ppp.linkup.
23246 7. Update your /etc/rc.conf file.
23248 ----------------------------------------------------------------------
23250 18.3 Using Kernel PPP
23252 Parts originally contributed by Gennady B. Sorokopud and Robert Huff.
23254 18.3.1 Setting Up Kernel PPP
23256 Before you start setting up PPP on your machine, make sure that pppd is
23257 located in /usr/sbin and the directory /etc/ppp exists.
23259 pppd can work in two modes:
23261 1. As a ``client'' -- you want to connect your machine to the outside
23262 world via a PPP serial connection or modem line.
23264 2. As a ``server'' -- your machine is located on the network, and is used
23265 to connect other computers using PPP.
23267 In both cases you will need to set up an options file (/etc/ppp/options or
23268 ~/.ppprc if you have more than one user on your machine that uses PPP).
23270 You will also need some modem/serial software (preferably comms/kermit),
23271 so you can dial and establish a connection with the remote host.
23273 ----------------------------------------------------------------------
23275 18.3.2 Using pppd as a Client
23277 Based on information provided by Trev Roydhouse.
23279 The following /etc/ppp/options might be used to connect to a Cisco
23280 terminal server PPP line.
23282 crtscts # enable hardware flow control
23283 modem # modem control line
23284 noipdefault # remote PPP server must supply your IP address
23285 # if the remote host does not send your IP during IPCP
23286 # negotiation, remove this option
23287 passive # wait for LCP packets
23288 domain ppp.foo.com # put your domain name here
23290 :<remote_ip> # put the IP of remote PPP host here
23291 # it will be used to route packets via PPP link
23292 # if you didn't specified the noipdefault option
23293 # change this line to <local_ip>:<remote_ip>
23295 defaultroute # put this if you want that PPP server will be your
23300 1. Dial to the remote host using kermit (or some other modem program),
23301 and enter your user name and password (or whatever is needed to enable
23302 PPP on the remote host).
23304 2. Exit kermit (without hanging up the line).
23306 3. Enter the following:
23308 # /usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200
23310 Be sure to use the appropriate speed and device name.
23312 Now your computer is connected with PPP. If the connection fails, you can
23313 add the debug option to the /etc/ppp/options file, and check console
23314 messages to track the problem.
23316 Following /etc/ppp/pppup script will make all 3 stages automatic:
23319 ps ax |grep pppd |grep -v grep
23320 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23321 if [ "X${pid}" != "X" ] ; then
23322 echo 'killing pppd, PID=' ${pid}
23325 ps ax |grep kermit |grep -v grep
23326 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23327 if [ "X${pid}" != "X" ] ; then
23328 echo 'killing kermit, PID=' ${pid}
23333 ifconfig ppp0 delete
23335 kermit -y /etc/ppp/kermit.dial
23336 pppd /dev/tty01 19200
23338 /etc/ppp/kermit.dial is a kermit script that dials and makes all necessary
23339 authorization on the remote host (an example of such a script is attached
23340 to the end of this document).
23342 Use the following /etc/ppp/pppdown script to disconnect the PPP line:
23345 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23346 if [ X${pid} != "X" ] ; then
23347 echo 'killing pppd, PID=' ${pid}
23351 ps ax |grep kermit |grep -v grep
23352 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23353 if [ "X${pid}" != "X" ] ; then
23354 echo 'killing kermit, PID=' ${pid}
23358 /sbin/ifconfig ppp0 down
23359 /sbin/ifconfig ppp0 delete
23360 kermit -y /etc/ppp/kermit.hup
23363 Check to see if pppd is still running by executing /usr/etc/ppp/ppptest,
23364 which should look like this:
23367 pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
23368 if [ X${pid} != "X" ] ; then
23369 echo 'pppd running: PID=' ${pid-NONE}
23371 echo 'No pppd running.'
23377 To hang up the modem, execute /etc/ppp/kermit.hup, which should contain:
23379 set line /dev/tty01 ; put your modem device here
23381 set file type binary
23382 set file names literal
23387 set term bytesize 8
23388 set command bytesize 8
23398 Here is an alternate method using chat instead of kermit:
23400 The following two files are sufficient to accomplish a pppd connection.
23406 crtscts # enable hardware flow control
23407 modem # modem control line
23408 connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
23409 noipdefault # remote PPP serve must supply your IP address
23410 # if the remote host doesn't send your IP during
23411 # IPCP negotiation, remove this option
23412 passive # wait for LCP packets
23413 domain <your.domain> # put your domain name here
23415 : # put the IP of remote PPP host here
23416 # it will be used to route packets via PPP link
23417 # if you didn't specified the noipdefault option
23418 # change this line to <local_ip>:<remote_ip>
23420 defaultroute # put this if you want that PPP server will be
23421 # your default router
23423 /etc/ppp/login.chat.script:
23425 Note: The following should go on a single line.
23427 ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number>
23428 CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id>
23429 TIMEOUT 5 sword: <password>
23431 Once these are installed and modified correctly, all you need to do is run
23436 ----------------------------------------------------------------------
23438 18.3.3 Using pppd as a Server
23440 /etc/ppp/options should contain something similar to the following:
23442 crtscts # Hardware flow control
23443 netmask 255.255.255.0 # netmask (not required)
23444 192.114.208.20:192.114.208.165 # IP's of local and remote hosts
23445 # local ip must be different from one
23446 # you assigned to the ethernet (or other)
23447 # interface on your machine.
23448 # remote IP is IP address that will be
23449 # assigned to the remote machine
23450 domain ppp.foo.com # your domain
23451 passive # wait for LCP
23454 The following /etc/ppp/pppserv script will tell pppd to behave as a
23458 ps ax |grep pppd |grep -v grep
23459 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23460 if [ "X${pid}" != "X" ] ; then
23461 echo 'killing pppd, PID=' ${pid}
23464 ps ax |grep kermit |grep -v grep
23465 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23466 if [ "X${pid}" != "X" ] ; then
23467 echo 'killing kermit, PID=' ${pid}
23471 # reset ppp interface
23473 ifconfig ppp0 delete
23475 # enable autoanswer mode
23476 kermit -y /etc/ppp/kermit.ans
23479 pppd /dev/tty01 19200
23481 Use this /etc/ppp/pppservdown script to stop the server:
23484 ps ax |grep pppd |grep -v grep
23485 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
23486 if [ "X${pid}" != "X" ] ; then
23487 echo 'killing pppd, PID=' ${pid}
23490 ps ax |grep kermit |grep -v grep
23491 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
23492 if [ "X${pid}" != "X" ] ; then
23493 echo 'killing kermit, PID=' ${pid}
23497 ifconfig ppp0 delete
23499 kermit -y /etc/ppp/kermit.noans
23501 The following kermit script (/etc/ppp/kermit.ans) will enable/disable
23502 autoanswer mode on your modem. It should look like this:
23504 set line /dev/tty01
23506 set file type binary
23507 set file names literal
23512 set term bytesize 8
23513 set command bytesize 8
23522 out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable
23528 A script named /etc/ppp/kermit.dial is used for dialing and authenticating
23529 on the remote host. You will need to customize it for your needs. Put your
23530 login and password in this script; you will also need to change the input
23531 statement depending on responses from your modem and remote host.
23534 ; put the com line attached to the modem here:
23536 set line /dev/tty01
23538 ; put the modem speed here:
23541 set file type binary ; full 8 bit file xfer
23542 set file names literal
23547 set term bytesize 8
23548 set command bytesize 8
23551 set dial hangup off
23552 set carrier auto ; Then SET CARRIER if necessary,
23553 set dial display on ; Then SET DIAL if necessary,
23555 set input timeout proceed
23556 set input case ignore
23557 def \%x 0 ; login prompt counter
23560 :slcmd ; put the modem in command mode
23561 echo Put the modem in command mode.
23562 clear ; Clear unread characters from input buffer
23564 output +++ ; hayes escape sequence
23565 input 1 OK\13\10 ; wait for OK
23566 if success goto slhup
23571 if fail goto slcmd ; if modem doesn't answer OK, try again
23573 :slhup ; hang up the phone
23574 clear ; Clear unread characters from input buffer
23576 echo Hanging up the phone.
23577 output ath0\13 ; hayes command for on hook
23579 if fail goto slcmd ; if no OK answer, put modem in command mode
23581 :sldial ; dial the number
23584 output atdt9,550311\13\10 ; put phone number here
23585 assign \%x 0 ; zero the time counter
23588 clear ; Clear unread characters from input buffer
23589 increment \%x ; Count the seconds
23591 if success goto sllogin
23592 reinput 1 {NO CARRIER\13\10}
23593 if success goto sldial
23594 reinput 1 {NO DIALTONE\13\10}
23595 if success goto slnodial
23597 if success goto slhup
23599 if success goto slhup
23600 if < \%x 60 goto look
23604 assign \%x 0 ; zero the time counter
23606 echo Looking for login prompt.
23609 increment \%x ; Count the seconds
23610 clear ; Clear unread characters from input buffer
23613 ; put your expected login prompt here:
23615 input 1 {Username: }
23616 if success goto sluid
23618 if success goto slhup
23620 if success goto slhup
23621 if < \%x 10 goto slloop ; try 10 times to get a login prompt
23622 else goto slhup ; hang up and start again if 10 failures
23626 ; put your userid here:
23628 output ppp-login\13
23629 input 1 {Password: }
23631 ; put your password here:
23633 output ppp-password\13
23634 input 1 {Entering SLIP mode.}
23639 echo \7No dialtone. Check the telephone line!\7
23644 ; comment-start: "; "
23645 ; comment-start-skip: "; "
23648 ----------------------------------------------------------------------
23650 18.4 Troubleshooting PPP Connections
23652 Contributed by Tom Rhodes.
23654 This section covers a few issues which may arise when using PPP over a
23655 modem connection. For instance, perhaps you need to know exactly what
23656 prompts the system you are dialing into will present. Some ISPs present
23657 the ssword prompt, and others will present password; if the ppp script is
23658 not written accordingly, the login attempt will fail. The most common way
23659 to debug ppp connections is by connecting manually. The following
23660 information will walk you through a manual connection step by step.
23662 ----------------------------------------------------------------------
23664 18.4.1 Check the Device Nodes
23666 If you reconfigured your kernel then you recall the sio device. If you did
23667 not configure your kernel, there is no reason to worry. Just check the
23668 dmesg output for the modem device with:
23672 You should get some pertinent output about the sio devices. These are the
23673 COM ports we need. If your modem acts like a standard serial port then you
23674 should see it listed on sio1, or COM2. If so, you are not required to
23675 rebuild the kernel, you just need to make the serial device. You can do
23676 this by changing your directory to /dev and running the MAKEDEV script
23677 like above. Now make the serial devices with:
23679 # sh MAKEDEV cuaa0 cuaa1 cuaa2 cuaa3
23681 which will create the serial devices for your system. When matching up sio
23682 modem is on sio1 or COM2 if you are in DOS, then your modem device would
23685 ----------------------------------------------------------------------
23687 18.4.2 Connecting Manually
23689 Connecting to the Internet by manually controlling ppp is quick, easy, and
23690 a great way to debug a connection or just get information on how your ISP
23691 treats ppp client connections. Lets start PPP from the command line. Note
23692 that in all of our examples we will use example as the hostname of the
23693 machine running PPP. You start ppp by just typing ppp:
23697 We have now started ppp.
23699 ppp ON example> set device /dev/cuaa1
23701 We set our modem device, in this case it is cuaa1.
23703 ppp ON example> set speed 115200
23705 Set the connection speed, in this case we are using 115,200 kbps.
23707 ppp ON example> enable dns
23709 Tell ppp to configure our resolver and add the nameserver lines to
23710 /etc/resolv.conf. If ppp cannot determine our hostname, we can set one
23713 ppp ON example> term
23715 Switch to ``terminal'' mode so that we can manually control the modem.
23717 deflink: Entering terminal mode on /dev/cuaa1
23724 Use at to initialize the modem, then use atdt and the number for your ISP
23725 to begin the dial in process.
23729 Confirmation of the connection, if we are going to have any connection
23730 problems, unrelated to hardware, here is where we will attempt to resolve
23733 ISP Login:myusername
23735 Here you are prompted for a username, return the prompt with the username
23736 that was provided by the ISP.
23738 ISP Pass:mypassword
23740 This time we are prompted for a password, just reply with the password
23741 that was provided by the ISP. Just like logging into DragonFly, the
23742 password will not echo.
23746 Depending on your ISP this prompt may never appear. Here we are being
23747 asked if we wish to use a shell on the provider, or to start ppp. In this
23748 example, we have chosen to use ppp as we want an Internet connection.
23752 Notice that in this example the first p has been capitalized. This shows
23753 that we have successfully connected to the ISP.
23757 We have successfully authenticated with our ISP and are waiting for the
23758 assigned IP address.
23762 We have made an agreement on an IP address and successfully completed our
23765 PPP ON example>add default HISADDR
23767 Here we add our default route, we need to do this before we can talk to
23768 the outside world as currently the only established connection is with the
23769 peer. If this fails due to existing routes you can put a bang character !
23770 in front of the add. Alternatively, you can set this before making the
23771 actual connection and it will negotiate a new route accordingly.
23773 If everything went good we should now have an active connection to the
23774 Internet, which could be thrown into the background using CTRL+z If you
23775 notice the PPP return to ppp then we have lost our connection. This is
23776 good to know because it shows our connection status. Capital P's show that
23777 we have a connection to the ISP and lowercase p's show that the connection
23778 has been lost for whatever reason. ppp only has these 2 states.
23780 ----------------------------------------------------------------------
23784 If you have a direct line and cannot seem to make a connection, then turn
23785 hardware flow CTS/RTS to off with the set ctsrts off. This is mainly the
23786 case if you are connected to some PPP capable terminal servers, where PPP
23787 hangs when it tries to write data to your communication link, so it would
23788 be waiting for a CTS, or Clear To Send signal which may never come. If you
23789 use this option however, you should also use the set accmap option, which
23790 may be required to defeat hardware dependent on passing certain characters
23791 from end to end, most of the time XON/XOFF. See the ppp(8) manual page for
23792 more information on this option, and how it is used.
23794 If you have an older modem, you may need to use the set parity even.
23795 Parity is set at none be default, but is used for error checking (with a
23796 large increase in traffic) on older modems and some ISPs. You may need
23797 this option for the Compuserve ISP.
23799 PPP may not return to the command mode, which is usually a negotiation
23800 error where the ISP is waiting for your side to start negotiating. At this
23801 point, using the ~p command will force ppp to start sending the
23802 configuration information.
23804 If you never obtain a login prompt, then most likely you need to use PAP
23805 or CHAP authentication instead of the UNIX style in the example above. To
23806 use PAP or CHAP just add the following options to PPP before going into
23809 ppp ON example> set authname myusername
23811 Where myusername should be replaced with the username that was assigned by
23814 ppp ON example> set authkey mypassword
23816 Where mypassword should be replaced with the password that was assigned by
23819 If you connect fine, but cannot seem to find any domain name, try to use
23820 ping(8) with an IP address and see if you can get any return information.
23821 If you experience 100 percent (100%) packet loss, then it is most likely
23822 that you were not assigned a default route. Double check that the option
23823 add default HISADDR was set during the connection. If you can connect to a
23824 remote IP address then it is possible that a resolver address has not been
23825 added to the /etc/resolv.conf. This file should look like:
23831 Where x.x.x.x and y.y.y.y should be replaced with the IP address of your
23832 ISP's DNS servers. This information may or may not have been provided when
23833 you signed up, but a quick call to your ISP should remedy that.
23835 You could also have syslog(3) provide a logging function for your PPP
23836 connection. Just add:
23839 *.* /var/log/ppp.log
23841 to /etc/syslog.conf. In most cases, this functionality already exists.
23843 ----------------------------------------------------------------------
23845 18.5 Using PPP over Ethernet (PPPoE)
23848 http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by Jim Mock.
23850 This section describes how to set up PPP over Ethernet (PPPoE).
23852 ----------------------------------------------------------------------
23854 18.5.1 Configuring the Kernel
23856 No kernel configuration is necessary for PPPoE any longer. If the
23857 necessary netgraph support is not built into the kernel, it will be
23858 dynamically loaded by ppp.
23860 ----------------------------------------------------------------------
23862 18.5.2 Setting Up ppp.conf
23864 Here is an example of a working ppp.conf:
23867 set log Phase tun command # you can add more detailed logging if you wish
23868 set ifaddr 10.0.0.1/0 10.0.0.2/0
23870 name_of_service_provider:
23871 set device PPPoE:xl1 # replace xl1 with your ethernet device
23872 set authname YOURLOGINNAME
23873 set authkey YOURPASSWORD
23876 add default HISADDR
23878 ----------------------------------------------------------------------
23882 As root, you can run:
23884 # ppp -ddial name_of_service_provider
23886 ----------------------------------------------------------------------
23888 18.5.4 Starting ppp at Boot
23890 Add the following to your /etc/rc.conf file:
23894 ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO
23895 ppp_profile="name_of_service_provider"
23897 ----------------------------------------------------------------------
23899 18.5.5 Using a PPPoE Service Tag
23901 Sometimes it will be necessary to use a service tag to establish your
23902 connection. Service tags are used to distinguish between different PPPoE
23903 servers attached to a given network.
23905 You should have been given any required service tag information in the
23906 documentation provided by your ISP. If you cannot locate it there, ask
23907 your ISP's tech support personnel.
23909 As a last resort, you could try the method suggested by the Roaring
23910 Penguin PPPoE program which can be found in the pkgsrc collection. Bear in
23911 mind however, this may de-program your modem and render it useless, so
23912 think twice before doing it. Simply install the program shipped with the
23913 modem by your provider. Then, access the System menu from the program. The
23914 name of your profile should be listed there. It is usually ISP.
23916 The profile name (service tag) will be used in the PPPoE configuration
23917 entry in ppp.conf as the provider part of the set device command (see the
23918 ppp(8) manual page for full details). It should look like this:
23920 set device PPPoE:xl1:ISP
23922 Do not forget to change xl1 to the proper device for your Ethernet card.
23924 Do not forget to change ISP to the profile you have just found above.
23926 For additional information, see:
23928 * Cheaper Broadband with FreeBSD on DSL by Renaud Waldura.
23930 * Nutzung von T-DSL und T-Online mit FreeBSD by Udo Erdelhoff (in
23933 ----------------------------------------------------------------------
23935 18.5.6 PPPoE with a 3Com(R) HomeConnect(R) ADSL Modem Dual Link
23937 This modem does not follow RFC 2516 (A Method for transmitting PPP over
23938 Ethernet (PPPoE), written by L. Mamakos, K. Lidl, J. Evarts, D. Carrel, D.
23939 Simone, and R. Wheeler). Instead, different packet type codes have been
23940 used for the Ethernet frames. Please complain to 3Com if you think it
23941 should comply with the PPPoE specification.
23943 In order to make DragonFly capable of communicating with this device, a
23944 sysctl must be set. This can be done automatically at boot time by
23945 updating /etc/sysctl.conf:
23947 net.graph.nonstandard_pppoe=1
23949 or can be done for immediate effect with the command sysctl
23950 net.graph.nonstandard_pppoe=1.
23952 Unfortunately, because this is a system-wide setting, it is not possible
23953 to talk to a normal PPPoE client or server and a 3Com(R) HomeConnect(R)
23954 ADSL Modem at the same time.
23956 ----------------------------------------------------------------------
23960 Originally contributed by Satoshi Asami. With input from Guy Helmer and
23963 ----------------------------------------------------------------------
23965 18.6.1 Setting Up a SLIP Client
23967 The following is one way to set up a DragonFly machine for SLIP on a
23968 static host network. For dynamic hostname assignments (your address
23969 changes each time you dial up), you probably need to have a more complex
23972 First, determine which serial port your modem is connected to. Many people
23973 set up a symbolic link, such as /dev/modem, to point to the real device
23974 name, /dev/cuaaN. This allows you to abstract the actual device name
23975 should you ever need to move the modem to a different port. It can become
23976 quite cumbersome when you need to fix a bunch of files in /etc and .kermrc
23977 files all over the system!
23979 Note: /dev/cuaa0 is COM1, cuaa1 is COM2, etc.
23981 Make sure you have the following in your kernel configuration file:
23985 It is included in the GENERIC kernel, so this should not be a problem
23986 unless you have deleted it.
23988 ----------------------------------------------------------------------
23990 18.6.1.1 Things You Have to Do Only Once
23992 1. Add your home machine, the gateway and nameservers to your /etc/hosts
23993 file. Mine looks like this:
23995 127.0.0.1 localhost loghost
23996 136.152.64.181 water.CS.Example.EDU water.CS water
23997 136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway
23998 128.32.136.9 ns1.Example.EDU ns1
23999 128.32.136.12 ns2.Example.EDU ns2
24001 2. Make sure you have hosts before bind in your /etc/host.conf.
24003 3. Edit the /etc/rc.conf file.
24005 1. Set your hostname by editing the line that says:
24007 hostname="myname.my.domain"
24009 Your machine's full Internet hostname should be placed here.
24011 2. Add sl0 to the list of network interfaces by changing the line
24014 network_interfaces="lo0"
24018 network_interfaces="lo0 sl0"
24020 3. Set the startup flags of sl0 by adding a line:
24022 ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"
24024 4. Designate the default router by changing the line:
24030 defaultrouter="slip-gateway"
24032 4. Make a file /etc/resolv.conf which contains:
24034 domain CS.Example.EDU
24035 nameserver 128.32.136.9
24036 nameserver 128.32.136.12
24038 As you can see, these set up the nameserver hosts. Of course, the
24039 actual domain names and addresses depend on your environment.
24041 5. Set the password for root and toor (and any other accounts that do not
24044 6. Reboot your machine and make sure it comes up with the correct
24047 ----------------------------------------------------------------------
24049 18.6.1.2 Making a SLIP Connection
24051 1. Dial up, type slip at the prompt, enter your machine name and
24052 password. What is required to be entered depends on your environment.
24053 If you use kermit, you can try a script like this:
24057 set line /dev/modem
24061 set terminal bytesize 8
24062 set file type binary
24063 # The next macro will dial up and login
24064 define slip dial 643-9600, input 10 =>, if failure stop, -
24065 output slip\x0d, input 10 Username:, if failure stop, -
24066 output silvia\x0d, input 10 Password:, if failure stop, -
24067 output ***\x0d, echo \x0aCONNECTED\x0a
24069 Of course, you have to change the hostname and password to fit yours.
24070 After doing so, you can just type slip from the kermit prompt to
24073 Note: Leaving your password in plain text anywhere in the filesystem
24074 is generally a bad idea. Do it at your own risk.
24076 2. Leave the kermit there (you can suspend it by Ctrl-z) and as root,
24079 # slattach -h -c -s 115200 /dev/modem
24081 If you are able to ping hosts on the other side of the router, you are
24082 connected! If it does not work, you might want to try -a instead of -c
24083 as an argument to slattach.
24085 ----------------------------------------------------------------------
24087 18.6.1.3 How to Shutdown the Connection
24091 # kill -INT `cat /var/run/slattach.modem.pid`
24093 to kill slattach. Keep in mind you must be root to do the above. Then go
24094 back to kermit (by running fg if you suspended it) and exit from it (q).
24096 The slattach manual page says you have to use ifconfig sl0 down to mark
24097 the interface down, but this does not seem to make any difference for me.
24098 (ifconfig sl0 reports the same thing.)
24100 Some times, your modem might refuse to drop the carrier (mine often does).
24101 In that case, simply start kermit and quit it again. It usually goes out
24104 ----------------------------------------------------------------------
24106 18.6.1.4 Troubleshooting
24108 If it does not work, feel free to ask me. The things that people tripped
24111 * Not using -c or -a in slattach (This should not be fatal, but some
24112 users have reported that this solves their problems.)
24114 * Using s10 instead of sl0 (might be hard to see the difference on some
24117 * Try ifconfig sl0 to see your interface status. For example, you might
24121 sl0: flags=10<POINTOPOINT>
24122 inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00
24124 * If you get ``no route to host'' messages from ping, there may be a
24125 problem with your routing table. You can use the netstat -r command to
24126 display the current routes :
24130 Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks:
24135 Route Tree for Protocol Family inet:
24137 default inr-3.Example.EDU UG 8 224515 sl0 - -
24138 localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438
24139 inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - -
24140 water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438
24143 The preceding examples are from a relatively busy system. The numbers
24144 on your system will vary depending on network activity.
24146 ----------------------------------------------------------------------
24148 18.6.2 Setting Up a SLIP Server
24150 This document provides suggestions for setting up SLIP Server services on
24151 a DragonFly system, which typically means configuring your system to
24152 automatically startup connections upon login for remote SLIP clients.
24154 ----------------------------------------------------------------------
24156 18.6.2.1 Prerequisites
24158 This section is very technical in nature, so background knowledge is
24159 required. It is assumed that you are familiar with the TCP/IP network
24160 protocol, and in particular, network and node addressing, network address
24161 masks, subnetting, routing, and routing protocols, such as RIP.
24162 Configuring SLIP services on a dial-up server requires a knowledge of
24163 these concepts, and if you are not familiar with them, please read a copy
24164 of either Craig Hunt's TCP/IP Network Administration published by O'Reilly
24165 & Associates, Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books
24166 on the TCP/IP protocol.
24168 It is further assumed that you have already set up your modem(s) and
24169 configured the appropriate system files to allow logins through your
24170 modems. If you have not prepared your system for this yet, please see the
24171 tutorial for configuring dialup services. You may also want to check the
24172 manual pages for sio(4) for information on the serial port device driver
24173 and ttys(5), gettytab(5), getty(8), & init(8) for information relevant to
24174 configuring the system to accept logins on modems, and perhaps stty(1) for
24175 information on setting serial port parameters (such as clocal for
24176 directly-connected serial interfaces).
24178 ----------------------------------------------------------------------
24180 18.6.2.2 Quick Overview
24182 In its typical configuration, using DragonFly as a SLIP server works as
24183 follows: a SLIP user dials up your DragonFly SLIP Server system and logs
24184 in with a special SLIP login ID that uses /usr/sbin/sliplogin as the
24185 special user's shell. The sliplogin program browses the file
24186 /etc/sliphome/slip.hosts to find a matching line for the special user, and
24187 if it finds a match, connects the serial line to an available SLIP
24188 interface and then runs the shell script /etc/sliphome/slip.login to
24189 configure the SLIP interface.
24191 ----------------------------------------------------------------------
24193 18.6.2.2.1 An Example of a SLIP Server Login
24195 For example, if a SLIP user ID were Shelmerg, Shelmerg's entry in
24196 /etc/master.passwd would look something like this:
24198 Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin
24200 When Shelmerg logs in, sliplogin will search /etc/sliphome/slip.hosts for
24201 a line that had a matching user ID; for example, there may be a line in
24202 /etc/sliphome/slip.hosts that reads:
24204 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
24206 sliplogin will find that matching line, hook the serial line into the next
24207 available SLIP interface, and then execute /etc/sliphome/slip.login like
24210 /etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
24212 If all goes well, /etc/sliphome/slip.login will issue an ifconfig for the
24213 SLIP interface to which sliplogin attached itself (slip interface 0, in
24214 the above example, which was the first parameter in the list given to
24215 slip.login) to set the local IP address (dc-slip), remote IP address
24216 (sl-helmer), network mask for the SLIP interface (0xfffffc00), and any
24217 additional flags (autocomp). If something goes wrong, sliplogin usually
24218 logs good informational messages via the daemon syslog facility, which
24219 usually logs to /var/log/messages (see the manual pages for syslogd(8) and
24220 syslog.conf(5) and perhaps check /etc/syslog.conf to see to what syslogd
24221 is logging and where it is logging to).
24223 OK, enough of the examples -- let us dive into setting up the system.
24225 ----------------------------------------------------------------------
24227 18.6.2.3 Kernel Configuration
24229 DragonFly's default kernels usually come with two SLIP interfaces defined
24230 (sl0 and sl1); you can use netstat -i to see whether these interfaces are
24231 defined in your kernel.
24233 Sample output from netstat -i:
24235 Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll
24236 ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133
24237 ed0 1500 138.247.224 ivory 291311 0 174209 0 133
24238 lo0 65535 <Link> 79 0 79 0 0
24239 lo0 65535 loop localhost 79 0 79 0 0
24240 sl0* 296 <Link> 0 0 0 0 0
24241 sl1* 296 <Link> 0 0 0 0 0
24243 The sl0 and sl1 interfaces shown from netstat -i indicate that there are
24244 two SLIP interfaces built into the kernel. (The asterisks after the sl0
24245 and sl1 indicate that the interfaces are ``down''.)
24247 However, DragonFly's default kernel does not come configured to forward
24248 packets (by default, your DragonFly machine will not act as a router) due
24249 to Internet RFC requirements for Internet hosts (see RFCs 1009
24250 [Requirements for Internet Gateways], 1122 [Requirements for Internet
24251 Hosts -- Communication Layers], and perhaps 1127 [A Perspective on the
24252 Host Requirements RFCs]). If you want your DragonFly SLIP Server to act as
24253 a router, you will have to edit the /etc/rc.conf file and change the
24254 setting of the gateway_enable variable to YES.
24256 You will then need to reboot for the new settings to take effect.
24258 You will notice that near the end of the default kernel configuration file
24259 (/sys/i386/conf/GENERIC) is a line that reads:
24263 This is the line that defines the number of SLIP devices available in the
24264 kernel; the number at the end of the line is the maximum number of SLIP
24265 connections that may be operating simultaneously.
24267 Please refer to Chapter 9 on Configuring the DragonFly Kernel for help in
24268 reconfiguring your kernel.
24270 ----------------------------------------------------------------------
24272 18.6.2.4 Sliplogin Configuration
24274 As mentioned earlier, there are three files in the /etc/sliphome directory
24275 that are part of the configuration for /usr/sbin/sliplogin (see
24276 sliplogin(8) for the actual manual page for sliplogin): slip.hosts, which
24277 defines the SLIP users and their associated IP addresses; slip.login,
24278 which usually just configures the SLIP interface; and (optionally)
24279 slip.logout, which undoes slip.login's effects when the serial connection
24282 ----------------------------------------------------------------------
24284 18.6.2.4.1 slip.hosts Configuration
24286 /etc/sliphome/slip.hosts contains lines which have at least four items
24287 separated by whitespace:
24289 * SLIP user's login ID
24291 * Local address (local to the SLIP server) of the SLIP link
24293 * Remote address of the SLIP link
24297 The local and remote addresses may be host names (resolved to IP addresses
24298 by /etc/hosts or by the domain name service, depending on your
24299 specifications in /etc/host.conf), and the network mask may be a name that
24300 can be resolved by a lookup into /etc/networks. On a sample system,
24301 /etc/sliphome/slip.hosts looks like this:
24304 # login local-addr remote-addr mask opt1 opt2
24305 # (normal,compress,noicmp)
24307 Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp
24309 At the end of the line is one or more of the options.
24311 * normal -- no header compression
24313 * compress -- compress headers
24315 * autocomp -- compress headers if the remote end allows it
24317 * noicmp -- disable ICMP packets (so any ``ping'' packets will be
24318 dropped instead of using up your bandwidth)
24320 Your choice of local and remote addresses for your SLIP links depends on
24321 whether you are going to dedicate a TCP/IP subnet or if you are going to
24322 use ``proxy ARP'' on your SLIP server (it is not ``true'' proxy ARP, but
24323 that is the terminology used in this section to describe it). If you are
24324 not sure which method to select or how to assign IP addresses, please
24325 refer to the TCP/IP books referenced in the SLIP Prerequisites (Section
24326 18.6.2.1) and/or consult your IP network manager.
24328 If you are going to use a separate subnet for your SLIP clients, you will
24329 need to allocate the subnet number out of your assigned IP network number
24330 and assign each of your SLIP client's IP numbers out of that subnet. Then,
24331 you will probably need to configure a static route to the SLIP subnet via
24332 your SLIP server on your nearest IP router.
24334 Otherwise, if you will use the ``proxy ARP'' method, you will need to
24335 assign your SLIP client's IP addresses out of your SLIP server's Ethernet
24336 subnet, and you will also need to adjust your /etc/sliphome/slip.login and
24337 /etc/sliphome/slip.logout scripts to use arp(8) to manage the proxy-ARP
24338 entries in the SLIP server's ARP table.
24340 ----------------------------------------------------------------------
24342 18.6.2.4.2 slip.login Configuration
24344 The typical /etc/sliphome/slip.login file looks like this:
24348 # @(#)slip.login 5.1 (Berkeley) 7/1/90
24351 # generic login file for a slip line. sliplogin invokes this with
24354 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24356 /sbin/ifconfig sl$1 inet $4 $5 netmask $6
24358 This slip.login file merely runs ifconfig for the appropriate SLIP
24359 interface with the local and remote addresses and network mask of the SLIP
24362 If you have decided to use the ``proxy ARP'' method (instead of using a
24363 separate subnet for your SLIP clients), your /etc/sliphome/slip.login file
24364 will need to look something like this:
24368 # @(#)slip.login 5.1 (Berkeley) 7/1/90
24371 # generic login file for a slip line. sliplogin invokes this with
24374 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24376 /sbin/ifconfig sl$1 inet $4 $5 netmask $6
24377 # Answer ARP requests for the SLIP client with our Ethernet addr
24378 /usr/sbin/arp -s $5 00:11:22:33:44:55 pub
24380 The additional line in this slip.login, arp -s $5 00:11:22:33:44:55 pub,
24381 creates an ARP entry in the SLIP server's ARP table. This ARP entry causes
24382 the SLIP server to respond with the SLIP server's Ethernet MAC address
24383 whenever another IP node on the Ethernet asks to speak to the SLIP
24384 client's IP address.
24386 When using the example above, be sure to replace the Ethernet MAC address
24387 (00:11:22:33:44:55) with the MAC address of your system's Ethernet card,
24388 or your ``proxy ARP'' will definitely not work! You can discover your SLIP
24389 server's Ethernet MAC address by looking at the results of running netstat
24390 -i; the second line of the output should look something like:
24392 ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116
24394 This indicates that this particular system's Ethernet MAC address is
24395 00:02:c1:28:5f:4a -- the periods in the Ethernet MAC address given by
24396 netstat -i must be changed to colons and leading zeros should be added to
24397 each single-digit hexadecimal number to convert the address into the form
24398 that arp(8) desires; see the manual page on arp(8) for complete
24399 information on usage.
24401 Note: When you create /etc/sliphome/slip.login and
24402 /etc/sliphome/slip.logout, the ``execute'' bit (chmod 755
24403 /etc/sliphome/slip.login /etc/sliphome/slip.logout) must be set, or
24404 sliplogin will be unable to execute it.
24406 ----------------------------------------------------------------------
24408 18.6.2.4.3 slip.logout Configuration
24410 /etc/sliphome/slip.logout is not strictly needed (unless you are
24411 implementing ``proxy ARP''), but if you decide to create it, this is an
24412 example of a basic slip.logout script:
24419 # logout file for a slip line. sliplogin invokes this with
24422 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24424 /sbin/ifconfig sl$1 down
24426 If you are using ``proxy ARP'', you will want to have
24427 /etc/sliphome/slip.logout remove the ARP entry for the SLIP client:
24434 # logout file for a slip line. sliplogin invokes this with
24437 # slipunit ttyspeed loginname local-addr remote-addr mask opt-args
24439 /sbin/ifconfig sl$1 down
24440 # Quit answering ARP requests for the SLIP client
24441 /usr/sbin/arp -d $5
24443 The arp -d $5 removes the ARP entry that the ``proxy ARP'' slip.login
24444 added when the SLIP client logged in.
24446 It bears repeating: make sure /etc/sliphome/slip.logout has the execute
24447 bit set after you create it (ie, chmod 755 /etc/sliphome/slip.logout).
24449 ----------------------------------------------------------------------
24451 18.6.2.5 Routing Considerations
24453 If you are not using the ``proxy ARP'' method for routing packets between
24454 your SLIP clients and the rest of your network (and perhaps the Internet),
24455 you will probably have to add static routes to your closest default
24456 router(s) to route your SLIP client subnet via your SLIP server.
24458 ----------------------------------------------------------------------
24460 18.6.2.5.1 Static Routes
24462 Adding static routes to your nearest default routers can be troublesome
24463 (or impossible if you do not have authority to do so...). If you have a
24464 multiple-router network in your organization, some routers, such as those
24465 made by Cisco and Proteon, may not only need to be configured with the
24466 static route to the SLIP subnet, but also need to be told which static
24467 routes to tell other routers about, so some expertise and
24468 troubleshooting/tweaking may be necessary to get static-route-based
24471 ----------------------------------------------------------------------
24473 18.6.2.5.2 Running GateD(R)
24475 Note: GateD(R) is proprietary software now and will not be available as
24476 source code to the public anymore (more info on the GateD website). This
24477 section only exists to ensure backwards compatibility for those that are
24478 still using an older version.
24480 An alternative to the headaches of static routes is to install GateD on
24481 your DragonFly SLIP server and configure it to use the appropriate routing
24482 protocols (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP subnet.
24483 You'll need to write a /etc/gated.conf file to configure your gated; here
24484 is a sample, similar to what the author used on a FreeBSD SLIP server:
24487 # gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
24488 # Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
24493 traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;
24496 interface sl noripout noripin ;
24497 interface ed ripin ripout version 1 ;
24498 traceoptions route ;
24502 # Turn on a bunch of tracing info for the interface to the kernel:
24504 traceoptions remnants request routes info interface ;
24508 # Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
24511 export proto rip interface ed {
24513 xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections
24518 # Accept routes from RIP via ed Ethernet interfaces
24520 import proto rip interface ed {
24524 The above sample gated.conf file broadcasts routing information regarding
24525 the SLIP subnet xxx.xxx.yy via RIP onto the Ethernet; if you are using a
24526 different Ethernet driver than the ed driver, you will need to change the
24527 references to the ed interface appropriately. This sample file also sets
24528 up tracing to /var/tmp/gated.output for debugging GateD's activity; you
24529 can certainly turn off the tracing options if GateD works OK for you. You
24530 will need to change the xxx.xxx.yy's into the network address of your own
24531 SLIP subnet (be sure to change the net mask in the proto direct clause as
24534 Once you have installed and configured GateD on your system, you will need
24535 to tell the DragonFly startup scripts to run GateD in place of routed. The
24536 easiest way to accomplish this is to set the router and router_flags
24537 variables in /etc/rc.conf. Please see the manual page for GateD for
24538 information on command-line parameters.
24540 ----------------------------------------------------------------------
24542 Chapter 19 Advanced Networking
24546 This chapter will cover some of the more frequently used network services
24547 on UNIX systems. We will cover how to define, set up, test and maintain
24548 all of the network services that DragonFly utilizes. In addition, there
24549 have been example configuration files included throughout this chapter for
24550 you to benefit from.
24552 After reading this chapter, you will know:
24554 * The basics of gateways and routes.
24556 * How to set up IEEE 802.11 and Bluetooth(R) devices.
24558 * How to make DragonFly act as a bridge.
24560 * How to set up a network filesystem.
24562 * How to set up network booting on a diskless machine.
24564 * How to set up a network information server for sharing user accounts.
24566 * How to set up automatic network settings using DHCP.
24568 * How to set up a domain name server.
24570 * How to synchronize the time and date, and set up a time server, with
24573 * How to set up network address translation.
24575 * How to manage the inetd daemon.
24577 * How to connect two computers via PLIP.
24579 * How to set up IPv6 on a DragonFly machine.
24581 Before reading this chapter, you should:
24583 * Understand the basics of the /etc/rc scripts.
24585 * Be familiar with basic network terminology.
24587 ----------------------------------------------------------------------
24589 19.2 Gateways and Routes
24591 Contributed by Coranth Gryphon.
24593 For one machine to be able to find another over a network, there must be a
24594 mechanism in place to describe how to get from one to the other. This is
24595 called routing. A ``route'' is a defined pair of addresses: a
24596 ``destination'' and a ``gateway''. The pair indicates that if you are
24597 trying to get to this destination, communicate through this gateway. There
24598 are three types of destinations: individual hosts, subnets, and
24599 ``default''. The ``default route'' is used if none of the other routes
24600 apply. We will talk a little bit more about default routes later on. There
24601 are also three types of gateways: individual hosts, interfaces (also
24602 called ``links''), and Ethernet hardware addresses (MAC addresses).
24604 ----------------------------------------------------------------------
24608 To illustrate different aspects of routing, we will use the following
24609 example from netstat:
24614 Destination Gateway Flags Refs Use Netif Expire
24616 default outside-gw UGSc 37 418 ppp0
24617 localhost localhost UH 0 181 lo0
24618 test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
24619 10.20.30.255 link#1 UHLW 1 2421
24620 example.com link#1 UC 0 0
24621 host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
24622 host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
24623 host2.example.com link#1 UC 0 0
24626 The first two lines specify the default route (which we will cover in the
24627 next section) and the localhost route.
24629 The interface (Netif column) that this routing table specifies to use for
24630 localhost is lo0, also known as the loopback device. This says to keep all
24631 traffic for this destination internal, rather than sending it out over the
24632 LAN, since it will only end up back where it started.
24634 The next thing that stands out are the addresses beginning with 0:e0:.
24635 These are Ethernet hardware addresses, which are also known as MAC
24636 addresses. DragonFly will automatically identify any hosts (test0 in the
24637 example) on the local Ethernet and add a route for that host, directly to
24638 it over the Ethernet interface, ed0. There is also a timeout (Expire
24639 column) associated with this type of route, which is used if we fail to
24640 hear from the host in a specific amount of time. When this happens, the
24641 route to this host will be automatically deleted. These hosts are
24642 identified using a mechanism known as RIP (Routing Information Protocol),
24643 which figures out routes to local hosts based upon a shortest path
24646 DragonFly will also add subnet routes for the local subnet (10.20.30.255
24647 is the broadcast address for the subnet 10.20.30, and example.com is the
24648 domain name associated with that subnet). The designation link#1 refers to
24649 the first Ethernet card in the machine. You will notice no additional
24650 interface is specified for those.
24652 Both of these groups (local network hosts and local subnets) have their
24653 routes automatically configured by a daemon called routed. If this is not
24654 run, then only routes which are statically defined (i.e. entered
24655 explicitly) will exist.
24657 The host1 line refers to our host, which it knows by Ethernet address.
24658 Since we are the sending host, DragonFly knows to use the loopback
24659 interface (lo0) rather than sending it out over the Ethernet interface.
24661 The two host2 lines are an example of what happens when we use an
24662 ifconfig(8) alias (see the section on Ethernet for reasons why we would do
24663 this). The => symbol after the lo0 interface says that not only are we
24664 using the loopback (since this address also refers to the local host), but
24665 specifically it is an alias. Such routes only show up on the host that
24666 supports the alias; all other hosts on the local network will simply have
24667 a link#1 line for such routes.
24669 The final line (destination subnet 224) deals with multicasting, which
24670 will be covered in another section.
24672 Finally, various attributes of each route can be seen in the Flags column.
24673 Below is a short table of some of these flags and their meanings:
24675 U Up: The route is active.
24676 H Host: The route destination is a single host.
24677 G Gateway: Send anything for this destination on to this remote system,
24678 which will figure out from there where to send it.
24679 S Static: This route was configured manually, not automatically generated
24681 C Clone: Generates a new route based upon this route for machines we
24682 connect to. This type of route is normally used for local networks.
24683 W WasCloned: Indicated a route that was auto-configured based upon a local
24684 area network (Clone) route.
24685 L Link: Route involves references to Ethernet hardware.
24687 ----------------------------------------------------------------------
24689 19.2.2 Default Routes
24691 When the local system needs to make a connection to a remote host, it
24692 checks the routing table to determine if a known path exists. If the
24693 remote host falls into a subnet that we know how to reach (Cloned routes),
24694 then the system checks to see if it can connect along that interface.
24696 If all known paths fail, the system has one last option: the ``default''
24697 route. This route is a special type of gateway route (usually the only one
24698 present in the system), and is always marked with a c in the flags field.
24699 For hosts on a local area network, this gateway is set to whatever machine
24700 has a direct connection to the outside world (whether via PPP link, DSL,
24701 cable modem, T1, or another network interface).
24703 If you are configuring the default route for a machine which itself is
24704 functioning as the gateway to the outside world, then the default route
24705 will be the gateway machine at your Internet Service Provider's (ISP)
24708 Let us look at an example of default routes. This is a common
24711 [Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
24714 The hosts Local1 and Local2 are at your site. Local1 is connected to an
24715 ISP via a dial up PPP connection. This PPP server computer is connected
24716 through a local area network to another gateway computer through an
24717 external interface to the ISPs Internet feed.
24719 The default routes for each of your machines will be:
24721 Host Default Gateway Interface
24722 Local2 Local1 Ethernet
24725 A common question is ``Why (or how) would we set the T1-GW to be the
24726 default gateway for Local1, rather than the ISP server it is connected
24729 Remember, since the PPP interface is using an address on the ISP's local
24730 network for your side of the connection, routes for any other machines on
24731 the ISP's local network will be automatically generated. Hence, you will
24732 already know how to reach the T1-GW machine, so there is no need for the
24733 intermediate step of sending traffic to the ISP server.
24735 It is common to use the address X.X.X.1 as the gateway address for your
24736 local network. So (using the same example), if your local class-C address
24737 space was 10.20.30 and your ISP was using 10.9.9 then the default routes
24741 Local2 (10.20.30.2) Local1 (10.20.30.1)
24742 Local1 (10.20.30.1, 10.9.9.30) T1-GW (10.9.9.1)
24744 You can easily define the default route via the /etc/rc.conf file. In our
24745 example, on the Local2 machine, we added the following line in
24748 defaultrouter="10.20.30.1"
24750 It is also possible to do it directly from the command line with the
24753 # route add default 10.20.30.1
24755 For more informations on manual manipulation of network routing tables,
24756 consult route(8) manual page.
24758 ----------------------------------------------------------------------
24760 19.2.3 Dual Homed Hosts
24762 There is one other type of configuration that we should cover, and that is
24763 a host that sits on two different networks. Technically, any machine
24764 functioning as a gateway (in the example above, using a PPP connection)
24765 counts as a dual-homed host. But the term is really only used to refer to
24766 a machine that sits on two local-area networks.
24768 In one case, the machine has two Ethernet cards, each having an address on
24769 the separate subnets. Alternately, the machine may only have one Ethernet
24770 card, and be using ifconfig(8) aliasing. The former is used if two
24771 physically separate Ethernet networks are in use, the latter if there is
24772 one physical network segment, but two logically separate subnets.
24774 Either way, routing tables are set up so that each subnet knows that this
24775 machine is the defined gateway (inbound route) to the other subnet. This
24776 configuration, with the machine acting as a router between the two
24777 subnets, is often used when we need to implement packet filtering or
24778 firewall security in either or both directions.
24780 If you want this machine to actually forward packets between the two
24781 interfaces, you need to tell DragonFly to enable this ability. See the
24782 next section for more details on how to do this.
24784 ----------------------------------------------------------------------
24786 19.2.4 Building a Router
24788 A network router is simply a system that forwards packets from one
24789 interface to another. This is not enabled by default in DragonFly. You can
24790 enable this feature by changing the following variable to YES in
24793 gateway_enable=YES # Set to YES if this host will be a gateway
24795 This option will set the sysctl(8) variable net.inet.ip.forwarding to 1.
24796 If you should need to stop routing temporarily, you can reset this to 0
24799 Your new router will need routes to know where to send the traffic. If
24800 your network is simple enough you can use static routes. DragonFly also
24801 comes with the standard BSD routing daemon routed(8), which speaks RIP
24802 (both version 1 and version 2) and IRDP. Support for BGP v4, OSPF v2, and
24803 other sophisticated routing protocols is available with the net/zebra
24804 package. Commercial products such as GateD are also available for more
24805 complex network routing solutions.
24807 Even when DragonFly is configured in this way, it does not completely
24808 comply with the Internet standard requirements for routers. It comes close
24809 enough for ordinary use, however.
24811 ----------------------------------------------------------------------
24813 19.2.5 Setting Up Static Routes
24815 Contributed by Al Hoang.
24817 19.2.5.1 Manual Configuration
24819 Let us assume we have a network as follows:
24822 | (10.0.0.1/24) Default Router to Internet
24828 | | (DragonFly gateway)
24833 +--------------------------------+
24834 Internal Net 1 | 192.168.1.2/24
24845 In this scenario, RouterA is our DragonFly machine that is acting as a
24846 router to the rest of the Internet. It has a default route set to 10.0.0.1
24847 which allows it to connect with the outside world. We will assume that
24848 RouterB is already configured properly and knows how to get wherever it
24849 needs to go. (This is simple in this picture. Just add a default route on
24850 RouterB using 192.168.1.1 as the gateway.)
24852 If we look at the routing table for RouterA we would see something like
24859 Destination Gateway Flags Refs Use Netif Expire
24860 default 10.0.0.1 UGS 0 49378 xl0
24861 127.0.0.1 127.0.0.1 UH 0 6 lo0
24862 10.0.0/24 link#1 UC 0 0 xl0
24863 192.168.1/24 link#2 UC 0 0 xl1
24865 With the current routing table RouterA will not be able to reach our
24866 Internal Net 2. It does not have a route for 192.168.2.0/24. One way to
24867 alleviate this is to manually add the route. The following command would
24868 add the Internal Net 2 network to RouterA's routing table using
24869 192.168.1.2 as the next hop:
24871 # route add -net 192.168.2.0/24 192.168.1.2
24873 Now RouterA can reach any hosts on the 192.168.2.0/24 network.
24875 ----------------------------------------------------------------------
24877 19.2.5.2 Persistent Configuration
24879 The above example is perfect for configuring a static route on a running
24880 system. However, one problem is that the routing information will not
24881 persist if you reboot your DragonFly machine. The way to handle the
24882 addition of a static route is to put it in your /etc/rc.conf file:
24884 # Add Internal Net 2 as a static route
24885 static_routes="internalnet2"
24886 route_internalnet2="-net 192.168.2.0/24 192.168.1.2"
24888 The static_routes configuration variable is a list of strings seperated by
24889 a space. Each string references to a route name. In our above example we
24890 only have one string in static_routes. This string is internalnet2. We
24891 then add a configuration variable called route_internalnet2 where we put
24892 all of the configuration parameters we would give to the route(8) command.
24893 For our example above we would have used the command:
24895 # route add -net 192.168.2.0/24 192.168.1.2
24897 so we need "-net 192.168.2.0/24 192.168.1.2".
24899 As said above, we can have more than one string in static_routes. This
24900 allows us to create multiple static routes. The following lines shows an
24901 example of adding static routes for the 192.168.0.0/24 and 192.168.1.0/24
24902 networks on an imaginary router:
24904 static_routes="net1 net2"
24905 route_net1="-net 192.168.0.0/24 192.168.0.1"
24906 route_net2="-net 192.168.1.0/24 192.168.1.1"
24908 ----------------------------------------------------------------------
24910 19.2.6 Routing Propagation
24912 We have already talked about how we define our routes to the outside
24913 world, but not about how the outside world finds us.
24915 We already know that routing tables can be set up so that all traffic for
24916 a particular address space (in our examples, a class-C subnet) can be sent
24917 to a particular host on that network, which will forward the packets
24920 When you get an address space assigned to your site, your service provider
24921 will set up their routing tables so that all traffic for your subnet will
24922 be sent down your PPP link to your site. But how do sites across the
24923 country know to send to your ISP?
24925 There is a system (much like the distributed DNS information) that keeps
24926 track of all assigned address-spaces, and defines their point of
24927 connection to the Internet Backbone. The ``Backbone'' are the main trunk
24928 lines that carry Internet traffic across the country, and around the
24929 world. Each backbone machine has a copy of a master set of tables, which
24930 direct traffic for a particular network to a specific backbone carrier,
24931 and from there down the chain of service providers until it reaches your
24934 It is the task of your service provider to advertise to the backbone sites
24935 that they are the point of connection (and thus the path inward) for your
24936 site. This is known as route propagation.
24938 ----------------------------------------------------------------------
24940 19.2.7 Troubleshooting
24942 Sometimes, there is a problem with routing propagation, and some sites are
24943 unable to connect to you. Perhaps the most useful command for trying to
24944 figure out where routing is breaking down is the traceroute(8) command. It
24945 is equally useful if you cannot seem to make a connection to a remote
24946 machine (i.e. ping(8) fails).
24948 The traceroute(8) command is run with the name of the remote host you are
24949 trying to connect to. It will show the gateway hosts along the path of the
24950 attempt, eventually either reaching the target host, or terminating
24951 because of a lack of connection.
24953 For more information, see the manual page for traceroute(8).
24955 ----------------------------------------------------------------------
24957 19.2.8 Multicast Routing
24959 DragonFly supports both multicast applications and multicast routing
24960 natively. Multicast applications do not require any special configuration
24961 of DragonFly; applications will generally run out of the box. Multicast
24962 routing requires that support be compiled into the kernel:
24966 In addition, the multicast routing daemon, mrouted(8) must be configured
24967 to set up tunnels and DVMRP via /etc/mrouted.conf. More details on
24968 multicast configuration may be found in the manual page for mrouted(8).
24970 ----------------------------------------------------------------------
24972 19.3 Wireless Networking
24974 Written by Eric Anderson.
24976 ----------------------------------------------------------------------
24978 19.3.1 Introduction
24980 It can be very useful to be able to use a computer without the annoyance
24981 of having a network cable attached at all times. DragonFly can be used as
24982 a wireless client, and even as a wireless ``access point''.
24984 ----------------------------------------------------------------------
24986 19.3.2 Wireless Modes of Operation
24988 There are two different ways to configure 802.11 wireless devices: BSS and
24991 ----------------------------------------------------------------------
24995 BSS mode is the mode that typically is used. BSS mode is also called
24996 infrastructure mode. In this mode, a number of wireless access points are
24997 connected to a wired network. Each wireless network has its own name. This
24998 name is called the SSID of the network.
25000 Wireless clients connect to these wireless access points. The IEEE 802.11
25001 standard defines the protocol that wireless networks use to connect. A
25002 wireless client can be tied to a specific network, when a SSID is set. A
25003 wireless client can also attach to any network by not explicitly setting a
25006 ----------------------------------------------------------------------
25010 IBSS mode, also called ad-hoc mode, is designed for point to point
25011 connections. There are actually two types of ad-hoc mode. One is IBSS
25012 mode, also called ad-hoc or IEEE ad-hoc mode. This mode is defined by the
25013 IEEE 802.11 standards. The second is called demo ad-hoc mode or Lucent
25014 ad-hoc mode (and sometimes, confusingly, ad-hoc mode). This is the old,
25015 pre-802.11 ad-hoc mode and should only be used for legacy installations.
25016 We will not cover either of the ad-hoc modes further.
25018 ----------------------------------------------------------------------
25020 19.3.3 Infrastructure Mode
25022 19.3.3.1 Access Points
25024 Access points are wireless networking devices that allow one or more
25025 wireless clients to use the device as a central hub. When using an access
25026 point, all clients communicate through the access point. Multiple access
25027 points are often used to cover a complete area such as a house, business,
25028 or park with a wireless network.
25030 Access points typically have multiple network connections: the wireless
25031 card, and one or more wired Ethernet adapters for connection to the rest
25034 Access points can either be purchased prebuilt, or you can build your own
25035 with DragonFly and a supported wireless card. Several vendors make
25036 wireless access points and wireless cards with various features.
25038 ----------------------------------------------------------------------
25040 19.3.3.2 Building a DragonFly Access Point
25042 ----------------------------------------------------------------------
25044 19.3.3.2.1 Requirements
25046 In order to set up a wireless access point with DragonFly, you need to
25047 have a compatible wireless card. Currently, only cards with the Prism
25048 chipset are supported. You will also need a wired network card that is
25049 supported by DragonFly (this should not be difficult to find, DragonFly
25050 supports a lot of different devices). For this guide, we will assume you
25051 want to bridge(4) all traffic between the wireless device and the network
25052 attached to the wired network card.
25054 The hostap functionality that DragonFly uses to implement the access point
25055 works best with certain versions of firmware. Prism 2 cards should use
25056 firmware version 1.3.4 or newer. Prism 2.5 and Prism 3 cards should use
25057 firmware 1.4.9. Older versions of the firmware way or may not function
25058 correctly. At this time, the only way to update cards is with Windows
25059 firmware update utilities available from your card's manufacturer.
25061 ----------------------------------------------------------------------
25063 19.3.3.2.2 Setting It Up
25065 First, make sure your system can see the wireless card:
25068 wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
25069 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
25070 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
25071 ether 00:09:2d:2d:c9:50
25072 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
25075 stationname "DragonFly Wireless node"
25076 channel 10 authmode OPEN powersavemode OFF powersavesleep 100
25077 wepmode OFF weptxkey 1
25079 Do not worry about the details now, just make sure it shows you something
25080 to indicate you have a wireless card installed. If you have trouble seeing
25081 the wireless interface, and you are using a PC Card, you may want to check
25082 out pccardc(8) and pccardd(8) manual pages for more information.
25084 Next, you will need to load a module in order to get the bridging part of
25085 DragonFly ready for the access point. To load the bridge(4) module, simply
25086 run the following command:
25090 It should not have produced any errors when loading the module. If it did,
25091 you may need to compile the bridge(4) code into your kernel. The Bridging
25092 section of this handbook should be able to help you accomplish that task.
25094 Now that you have the bridging stuff done, we need to tell the DragonFly
25095 kernel which interfaces to bridge together. We do that by using sysctl(8):
25097 # sysctl net.link.ether.bridge=1
25098 # sysctl net.link.ether.bridge_cfg="wi0,xl0"
25099 # sysctl net.inet.ip.forwarding=1
25101 Now it is time for the wireless card setup. The following command will set
25102 the card into an access point:
25104 # ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "DragonFly AP"
25107 The ifconfig(8) line brings the wi0 interface up, sets its SSID to my_net,
25108 and sets the station name to DragonFly AP. The media DS/11Mbps sets the
25109 card into 11Mbps mode and is needed for any mediaopt to take effect. The
25110 mediaopt hostap option places the interface into access point mode. The
25111 channel 11 option sets the 802.11b channel to use. The wicontrol(8) manual
25112 page has valid channel options for your regulatory domain.
25114 Now you should have a complete functioning access point up and running.
25115 You are encouraged to read wicontrol(8), ifconfig(8), and wi(4) for
25116 further information.
25118 It is also suggested that you read the section on encryption that follows.
25120 ----------------------------------------------------------------------
25122 19.3.3.2.3 Status Information
25124 Once the access point is configured and operational, operators will want
25125 to see the clients that are associated with the access point. At any time,
25126 the operator may type:
25130 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
25132 This shows that there is one station associated, along with its
25133 parameters. The signal indicated should be used as a relative indication
25134 of strength only. Its translation to dBm or other units varies between
25135 different firmware revisions.
25137 ----------------------------------------------------------------------
25141 A wireless client is a system that accesses an access point or another
25144 Typically, wireless clients only have one network device, the wireless
25147 There are a few different ways to configure a wireless client. These are
25148 based on the different wireless modes, generally BSS (infrastructure mode,
25149 which requires an access point), and IBSS (ad-hoc, or peer-to-peer mode).
25150 In our example, we will use the most popular of the two, BSS mode, to talk
25151 to an access point.
25153 ----------------------------------------------------------------------
25155 19.3.3.3.1 Requirements
25157 There is only one real requirement for setting up DragonFly as a wireless
25158 client. You will need a wireless card that is supported by DragonFly.
25160 ----------------------------------------------------------------------
25162 19.3.3.3.2 Setting Up a Wireless DragonFly Client
25164 You will need to know a few things about the wireless network you are
25165 joining before you start. In this example, we are joining a network that
25166 has a name of my_net, and encryption turned off.
25168 Note: In this example, we are not using encryption, which is a dangerous
25169 situation. In the next section, you will learn how to turn on
25170 encryption, why it is important to do so, and why some encryption
25171 technologies still do not completely protect you.
25173 Make sure your card is recognized by DragonFly:
25176 wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
25177 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
25178 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
25179 ether 00:09:2d:2d:c9:50
25180 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
25183 stationname "DragonFly Wireless node"
25184 channel 10 authmode OPEN powersavemode OFF powersavesleep 100
25185 wepmode OFF weptxkey 1
25187 Now, we can set the card to the correct settings for our network:
25189 # ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net
25191 Replace 192.168.0.20 and 255.255.255.0 with a valid IP address and netmask
25192 on your wired network. Remember, our access point is bridging the data
25193 between the wireless network, and the wired network, so it will appear to
25194 the other devices on your network that you are on the wired network just
25197 Once you have done that, you should be able to ping hosts on the wired
25198 network just as if you were connected using a standard wired connection.
25200 If you are experiencing problems with your wireless connection, check to
25201 make sure that your are associated (connected) to the access point:
25205 should return some information, and you should see:
25209 If it does not show associated, then you may be out of range of the access
25210 point, have encryption on, or possibly have a configuration problem.
25212 ----------------------------------------------------------------------
25214 19.3.3.4 Encryption
25216 Encryption on a wireless network is important because you no longer have
25217 the ability to keep the network contained in a well protected area. Your
25218 wireless data will be broadcast across your entire neighborhood, so anyone
25219 who cares to read it can. This is where encryption comes in. By encrypting
25220 the data that is sent over the airwaves, you make it much more difficult
25221 for any interested party to grab your data right out of the air.
25223 The two most common ways to encrypt the data between your client and the
25224 access point are WEP, and ipsec(4).
25226 ----------------------------------------------------------------------
25230 WEP is an abbreviation for Wired Equivalency Protocol. WEP is an attempt
25231 to make wireless networks as safe and secure as a wired network.
25232 Unfortunately, it has been cracked, and is fairly trivial to break. This
25233 also means it is not something to rely on when it comes to encrypting
25236 It is better than nothing, so use the following to turn on WEP on your new
25237 DragonFly access point:
25239 # ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap
25241 And you can turn on WEP on a client with this command:
25243 # ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890
25245 Note that you should replace the 0x1234567890 with a more unique key.
25247 ----------------------------------------------------------------------
25251 ipsec(4) is a much more robust and powerful tool for encrypting data
25252 across a network. This is definitely the preferred way to encrypt data
25253 over a wireless network. You can read more about ipsec(4) security and how
25254 to implement it in the IPsec section of this handbook.
25256 ----------------------------------------------------------------------
25260 There are a small number of tools available for use in debugging and
25261 setting up your wireless network, and here we will attempt to describe
25262 some of them and what they do.
25264 ----------------------------------------------------------------------
25266 19.3.3.5.1 The wicontrol, ancontrol and raycontrol Utilities
25268 These are the tools you can use to control how your wireless card behaves
25269 on the wireless network. In the examples above, we have chosen to use
25270 wicontrol(8), since our wireless card is a wi0 interface. If you had a
25271 Cisco wireless device, it would come up as an0, and therefore you would
25274 ----------------------------------------------------------------------
25276 19.3.3.5.2 The ifconfig Command
25278 The ifconfig(8) command can be used to do many of the same options as
25279 wicontrol(8), however it does lack a few options. Check ifconfig(8) for
25280 command line parameters and options.
25282 ----------------------------------------------------------------------
25284 19.3.3.6 Supported Cards
25286 19.3.3.6.1 Access Points
25288 The only cards that are currently supported for BSS (as an access point)
25289 mode are devices based on the Prism 2, 2.5, or 3 chipsets. For a complete
25290 list, look at wi(4).
25292 ----------------------------------------------------------------------
25296 Almost all 802.11b wireless cards are currently supported under DragonFly.
25297 Most cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will
25298 work as a wireless network card in IBSS (ad-hoc, peer-to-peer, and BSS)
25301 ----------------------------------------------------------------------
25305 Written by Pav Lucistnik.
25307 ----------------------------------------------------------------------
25309 19.4.1 Introduction
25311 Bluetooth is a wireless technology for creating personal networks
25312 operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
25313 Networks are usually formed ad-hoc from portable devices such as cellular
25314 phones, handhelds and laptops. Unlike the other popular wireless
25315 technology, Wi-Fi, Bluetooth offers higher level service profiles, e.g.
25316 FTP-like file servers, file pushing, voice transport, serial line
25317 emulation, and more.
25319 The Bluetooth stack in DragonFly is implemented using the Netgraph
25320 framework (see netgraph(4)). A broad variety of Bluetooth USB dongles is
25321 supported by the ng_ubt(4) driver. The Broadcom BCM2033 chip based
25322 Bluetooth devices are supported via the ubtbcmfw(4) and ng_ubt(4) drivers.
25323 The 3Com Bluetooth PC Card 3CRWB60-A is supported by the ng_bt3c(4)
25324 driver. Serial and UART based Bluetooth devices are supported via sio(4),
25325 ng_h4(4) and hcseriald(8). This chapter describes the use of the USB
25326 Bluetooth dongle. Bluetooth support is available in DragonFly 5.0 and
25329 ----------------------------------------------------------------------
25331 19.4.2 Plugging in the Device
25333 By default Bluetooth device drivers are available as kernel modules.
25334 Before attaching a device, you will need to load the driver into the
25339 If the Bluetooth device is present in the system during system startup,
25340 load the module from /boot/loader.conf.
25344 Plug in your USB dongle. The output similar to the following will appear
25345 on the console (or in syslog).
25347 ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
25348 ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
25349 ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
25350 wMaxPacketSize=49, nframes=6, buffer size=294
25352 Copy /usr/share/examples/netgraph/bluetooth/rc.bluetooth into some
25353 convenient place, like /etc/rc.bluetooth. This script is used to start and
25354 stop the Bluetooth stack. It is a good idea to stop the stack before
25355 unplugging the device, but it is not (usually) fatal. When starting the
25356 stack, you will receive output similar to the following:
25358 # /etc/rc.bluetooth start ubt0
25359 BD_ADDR: 00:02:72:00:d4:1a
25360 Features: 0xff 0xff 0xf 00 00 00 00 00
25361 <3-Slot> <5-Slot> <Encryption> <Slot offset>
25362 <Timing accuracy> <Switch> <Hold mode> <Sniff mode>
25363 <Park mode> <RSSI> <Channel quality> <SCO link>
25364 <HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
25365 <Paging scheme> <Power control> <Transparent SCO data>
25366 Max. ACL packet size: 192 bytes
25367 Number of ACL packets: 8
25368 Max. SCO packet size: 64 bytes
25369 Number of SCO packets: 8
25371 ----------------------------------------------------------------------
25373 19.4.3 Host Controller Interface (HCI)
25375 Host Controller Interface (HCI) provides a command interface to the
25376 baseband controller and link manager, and access to hardware status and
25377 control registers. This interface provides a uniform method of accessing
25378 the Bluetooth baseband capabilities. HCI layer on the Host exchanges data
25379 and commands with the HCI firmware on the Bluetooth hardware. The Host
25380 Controller Transport Layer (i.e. physical bus) driver provides both HCI
25381 layers with the ability to exchange information with each other.
25383 A single Netgraph node of type hci is created for a single Bluetooth
25384 device. The HCI node is normally connected to the Bluetooth device driver
25385 node (downstream) and the L2CAP node (upstream). All HCI operations must
25386 be performed on the HCI node and not on the device driver node. Default
25387 name for the HCI node is ``devicehci''. For more details refer to the
25388 ng_hci(4) man page.
25390 One of the most common tasks is discovery of Bluetooth devices in RF
25391 proximity. This operation is called inquiry. Inquiry and other HCI
25392 realated operations are done with the hccontrol(8) utility. The example
25393 below shows how to find out which Bluetooth devices are in range. You
25394 should receive the list of devices in a few seconds. Note that a remote
25395 device will only answer the inquiry if it put into discoverable mode.
25397 % hccontrol -n ubt0hci inquiry
25398 Inquiry result, num_responses=1
25400 BD_ADDR: 00:80:37:29:19:a4
25401 Page Scan Rep. Mode: 0x1
25402 Page Scan Period Mode: 00
25405 Clock offset: 0x78ef
25406 Inquiry complete. Status: No error [00]
25408 BD_ADDR is unique address of a Bluetooth device, similar to MAC addresses
25409 of a network card. This address is needed for further communication with a
25410 device. It is possible to assign human readable name to a BD_ADDR. The
25411 /etc/bluetooth/hosts file contains information regarding the known
25412 Bluetooth hosts. The following example shows how to obtain human readable
25413 name that was assigned to the remote device.
25415 % hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4
25416 BD_ADDR: 00:80:37:29:19:a4
25419 If you perform an inquiry on a remote Bluetooth device, it will find your
25420 computer as ``your.host.name (ubt0)''. The name assigned to the local
25421 device can be changed at any time.
25423 The Bluetooth system provides a point-to-point connection (only two
25424 Bluetooth units involved), or a point-to-multipoint connection. In the
25425 point-to-multipoint connection the connection is shared among several
25426 Bluetooth devices. The following example shows how to obtain the list of
25427 active baseband connections for the local device.
25429 % hccontrol -n ubt0hci read_connection_list
25430 Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
25431 00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN
25433 A connection handle is useful when termination of the baseband connection
25434 is required. Note, that it is normally not required to do it by hand. The
25435 stack will automatically terminate inactive baseband connections.
25437 # hccontrol -n ubt0hci disconnect 41
25438 Connection handle: 41
25439 Reason: Connection terminated by local host [0x16]
25441 Refer to hccontrol help for a complete listing of available HCI commands.
25442 Most of the HCI commands do not require superuser privileges.
25444 ----------------------------------------------------------------------
25446 19.4.4 Logical Link Control and Adaptation Protocol (L2CAP)
25448 Logical Link Control and Adaptation Protocol (L2CAP) provides
25449 connection-oriented and connectionless data services to upper layer
25450 protocols with protocol multiplexing capability and segmentation and
25451 reassembly operation. L2CAP permits higher level protocols and
25452 applications to transmit and receive L2CAP data packets up to 64 kilobytes
25455 L2CAP is based around the concept of channels. Channel is a logical
25456 connection on top of baseband connection. Each channel is bound to a
25457 single protocol in a many-to-one fashion. Multiple channels can be bound
25458 to the same protocol, but a channel cannot be bound to multiple protocols.
25459 Each L2CAP packet received on a channel is directed to the appropriate
25460 higher level protocol. Multiple channels can share the same baseband
25463 A single Netgraph node of type l2cap is created for a single Bluetooth
25464 device. The L2CAP node is normally connected to the Bluetooth HCI node
25465 (downstream) and Bluetooth sockets nodes (upstream). Default name for the
25466 L2CAP node is ``devicel2cap''. For more details refer to the ng_l2cap(4)
25469 A useful command is l2ping(8), which can be used to ping other devices.
25470 Some Bluetooth implementations might not return all of the data sent to
25471 them, so 0 bytes in the following example is normal.
25473 # l2ping -a 00:80:37:29:19:a4
25474 0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
25475 0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
25476 0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
25477 0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0
25479 The l2control(8) utility is used to perform various operations on L2CAP
25480 nodes. This example shows how to obtain the list of logical connections
25481 (channels) and the list of baseband connections for the local device.
25483 % l2control -a 00:02:72:00:d4:1a read_channel_list
25485 Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State
25486 00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN
25487 % l2control -a 00:02:72:00:d4:1a read_connection_list
25489 Remote BD_ADDR Handle Flags Pending State
25490 00:07:e0:00:0b:ca 41 O 0 OPEN
25492 Another diagnostic tool is btsockstat(1). It does a job similar to as
25493 netstat(1) does, but for Bluetooth network-related data structures. The
25494 example below shows the same logical connection as l2control(8) above.
25497 Active L2CAP sockets
25498 PCB Recv-Q Send-Q Local address/PSM Foreign address CID State
25499 c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN
25500 Active RFCOMM sessions
25501 L2PCB PCB Flag MTU Out-Q DLCs State
25502 c2afe900 c2b53380 1 127 0 Yes OPEN
25503 Active RFCOMM sockets
25504 PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State
25505 c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN
25507 ----------------------------------------------------------------------
25509 19.4.5 RFCOMM Protocol
25511 The RFCOMM protocol provides emulation of serial ports over the L2CAP
25512 protocol. The protocol is based on the ETSI standard TS 07.10. RFCOMM is a
25513 simple transport protocol, with additional provisions for emulating the 9
25514 circuits of RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol
25515 supports up to 60 simultaneous connections (RFCOMM channels) between two
25518 For the purposes of RFCOMM, a complete communication path involves two
25519 applications running on different devices (the communication endpoints)
25520 with a communication segment between them. RFCOMM is intended to cover
25521 applications that make use of the serial ports of the devices in which
25522 they reside. The communication segment is a Bluetooth link from one device
25523 to another (direct connect).
25525 RFCOMM is only concerned with the connection between the devices in the
25526 direct connect case, or between the device and a modem in the network
25527 case. RFCOMM can support other configurations, such as modules that
25528 communicate via Bluetooth wireless technology on one side and provide a
25529 wired interface on the other side.
25531 In DragonFly the RFCOMM protocol is implemented at the Bluetooth sockets
25534 ----------------------------------------------------------------------
25536 19.4.6 Pairing of Devices
25538 By default, Bluetooth communication is not authenticated, and any device
25539 can talk to any other device. A Bluetooth device (for example, cellular
25540 phone) may choose to require authentication to provide a particular
25541 service (for example, Dial-Up service). Bluetooth authentication is
25542 normally done with PIN codes. A PIN code is an ASCII string up to 16
25543 characters in length. User is required to enter the same PIN code on both
25544 devices. Once user has entered the PIN code, both devices will generate a
25545 link key. After that the link key can be stored either in the devices
25546 themselves or in a persistent storage. Next time both devices will use
25547 previously generated link key. The described above procedure is called
25548 pairing. Note that if the link key is lost by any device then pairing must
25551 The hcsecd(8) daemon is responsible for handling of all Bluetooth
25552 authentication requests. The default configuration file is
25553 /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with
25554 the PIN code arbitrarily set to ``1234'' is shown below.
25557 bdaddr 00:80:37:29:19:a4;
25563 There is no limitation on PIN codes (except length). Some devices (for
25564 example Bluetooth headsets) may have a fixed PIN code built in. The -d
25565 switch forces the hcsecd(8) daemon to stay in the foreground, so it is
25566 easy to see what is happening. Set the remote device to receive pairing
25567 and initiate the Bluetooth connection to the remote device. The remote
25568 device should say that pairing was accepted, and request the PIN code.
25569 Enter the same PIN code as you have in hcsecd.conf. Now your PC and the
25570 remote device are paired. Alternatively, you can initiate pairing on the
25571 remote device. Below in the sample hcsecd output.
25573 hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
25574 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
25575 hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
25576 hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
25577 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
25578 hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
25580 ----------------------------------------------------------------------
25582 19.4.7 Service Discovery Protocol (SDP)
25584 The Service Discovery Protocol (SDP) provides the means for client
25585 applications to discover the existence of services provided by server
25586 applications as well as the attributes of those services. The attributes
25587 of a service include the type or class of service offered and the
25588 mechanism or protocol information needed to utilize the service.
25590 SDP involves communication between a SDP server and a SDP client. The
25591 server maintains a list of service records that describe the
25592 characteristics of services associated with the server. Each service
25593 record contains information about a single service. A client may retrieve
25594 information from a service record maintained by the SDP server by issuing
25595 a SDP request. If the client, or an application associated with the
25596 client, decides to use a service, it must open a separate connection to
25597 the service provider in order to utilize the service. SDP provides a
25598 mechanism for discovering services and their attributes, but it does not
25599 provide a mechanism for utilizing those services.
25601 Normally, a SDP client searches for services based on some desired
25602 characteristics of the services. However, there are times when it is
25603 desirable to discover which types of services are described by an SDP
25604 server's service records without any a priori information about the
25605 services. This process of looking for any offered services is called
25608 The Bluetooth SDP server sdpd(8) and command line client sdpcontrol(8) are
25609 included in the standard DragonFly installation. The following example
25610 shows how to perform a SDP browse query.
25612 % sdpcontrol -a 00:01:03:fc:6e:ec browse
25613 Record Handle: 00000000
25614 Service Class ID List:
25615 Service Discovery Server (0x1000)
25616 Protocol Descriptor List:
25618 Protocol specific parameter #1: u/int/uuid16 1
25619 Protocol specific parameter #2: u/int/uuid16 1
25621 Record Handle: 0x00000001
25622 Service Class ID List:
25623 Browse Group Descriptor (0x1001)
25625 Record Handle: 0x00000002
25626 Service Class ID List:
25627 LAN Access Using PPP (0x1102)
25628 Protocol Descriptor List:
25631 Protocol specific parameter #1: u/int8/bool 1
25632 Bluetooth Profile Descriptor List:
25633 LAN Access Using PPP (0x1102) ver. 1.0
25635 ... and so on. Note that each service has a list of attributes (RFCOMM
25636 channel for example). Depending on the service you might need to make a
25637 note of some of the attributes. Some Bluetooth implementations do not
25638 support service browsing and may return an empty list. In this case it is
25639 possible to search for the specific service. The example below shows how
25640 to search for the OBEX Object Push (OPUSH) service.
25642 % sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH
25644 Offering services on DragonFly to Bluetooth clients is done with the
25649 The local server application that wants to provide Bluetooth service to
25650 the remote clients will register service with the local SDP daemon. The
25651 example of such application is rfcomm_pppd(8). Once started it will
25652 register Bluetooth LAN service with the local SDP daemon.
25654 The list of services registered with the local SDP server can be obtained
25655 by issuing SDP browse query via local control channel.
25657 # sdpcontrol -l browse
25659 ----------------------------------------------------------------------
25661 19.4.8 Dial-Up Networking (DUN) and Network Access with PPP (LAN) Profiles
25663 The Dial-Up Networking (DUN) profile is mostly used with modems and
25664 cellular phones. The scenarios covered by this profile are the following:
25666 * use of a cellular phone or modem by a computer as a wireless modem for
25667 connecting to a dial-up internet access server, or using other dial-up
25670 * use of a cellular phone or modem by a computer to receive data calls.
25672 Network Access with PPP (LAN) profile can be used in the following
25675 * LAN access for a single Bluetooth device;
25677 * LAN access for multiple Bluetooth devices;
25679 * PC to PC (using PPP networking over serial cable emulation).
25681 In DragonFly both profiles are implemented with ppp(8) and rfcomm_pppd(8)
25682 - a wrapper that converts RFCOMM Bluetooth connection into something PPP
25683 can operate with. Before any profile can be used, a new PPP label in the
25684 /etc/ppp/ppp.conf must be created. Consult rfcomm_pppd(8) manual page for
25687 In the following example rfcomm_pppd(8) will be used to open RFCOMM
25688 connection to remote device with BD_ADDR 00:80:37:29:19:a4 on DUN RFCOMM
25689 channel. The actual RFCOMM channel number will be obtained from the remote
25690 device via SDP. It is possible to specify RFCOMM channel by hand, and in
25691 this case rfcomm_pppd(8) will not perform SDP query. Use sdpcontrol(8) to
25692 find out RFCOMM channel on the remote device.
25694 # rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup
25696 In order to provide Network Access with PPP (LAN) service the sdpd(8)
25697 server must be running. A new entry for LAN clients must be created in the
25698 /etc/ppp/ppp.conf file. Consult rfcomm_pppd(8) manual page for examples.
25699 Finally, start RFCOMM PPP server on valid RFCOMM channel number. The
25700 RFCOMM PPP server will automatically register Bluetooth LAN service with
25701 the local SDP daemon. The example below shows how to start RFCOMM PPP
25704 # rfcomm_pppd -s -C 7 -l rfcomm-server
25706 ----------------------------------------------------------------------
25708 19.4.9 OBEX Object Push (OPUSH) Profile
25710 OBEX is a widely used protocol for simple file transfers between mobile
25711 devices. Its main use is in infrared communication, where it is used for
25712 generic file transfers between notebooks or Palm handhelds, and for
25713 sending business cards or calendar entries between cellular phones and
25714 other devices with PIM applications.
25716 The OBEX server and client are implemented as a third-party package
25717 obexapp, which is available as comms/obexapp port.
25719 OBEX client is used to push and/or pull objects from the OBEX server. An
25720 object can, for example, be a business card or an appointment. The OBEX
25721 client can obtain RFCOMM channel number from the remote device via SDP.
25722 This can be done by specifying service name instead of RFCOMM channel
25723 number. Supported service names are: IrMC, FTRN and OPUSH. It is possible
25724 to specify RFCOMM channel as a number. Below is an example of an OBEX
25725 session, where device information object is pulled from the cellular
25726 phone, and a new object (business card) is pushed into the phone's
25729 % obexapp -a 00:80:37:29:19:a4 -C IrMC
25731 get: remote file> telecom/devinfo.txt
25732 get: local file> devinfo-t39.txt
25733 Success, response: OK, Success (0x20)
25735 put: local file> new.vcf
25736 put: remote file> new.vcf
25737 Success, response: OK, Success (0x20)
25739 Success, response: OK, Success (0x20)
25741 In order to provide OBEX Object Push service, sdpd(8) server must be
25742 running. A root folder, where all incoming objects will be stored, must be
25743 created. The default path to the root folder is /var/spool/obex. Finally,
25744 start OBEX server on valid RFCOMM channel number. The OBEX server will
25745 automatically register OBEX Object Push service with the local SDP daemon.
25746 The example below shows how to start OBEX server.
25750 ----------------------------------------------------------------------
25752 19.4.10 Serial Port (SP) Profile
25754 The Serial Port (SP) profile allows Bluetooth device to perform RS232 (or
25755 similar) serial cable emulation. The scenario covered by this profile
25756 deals with legacy applications using Bluetooth as a cable replacement,
25757 through a virtual serial port abstraction.
25759 The rfcomm_sppd(1) utility implements the Serial Port profile. Pseudo tty
25760 is used as a virtual serial port abstraction. The example below shows how
25761 to connect to a remote device Serial Port service. Note that you do not
25762 have to specify RFCOMM channel - rfcomm_sppd(1) can obtain it from the
25763 remote device via SDP. If you would like to override this, specify RFCOMM
25764 channel in the command line.
25766 # rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6
25767 rfcomm_sppd[94692]: Starting on /dev/ttyp6...
25769 Once connected pseudo tty can be used as serial port.
25773 ----------------------------------------------------------------------
25775 19.4.11 Troubleshooting
25777 19.4.11.1 A remote device cannot connect
25779 Some older Bluetooth devices do not support role switching. By default,
25780 when DragonFly is accepting a new connection, it tries to perform role
25781 switch and become a master. Devices, which do not support this will not be
25782 able to connect. Note the role switching is performed when a new
25783 connection is being established, so it is not possible to ask the remote
25784 device if it does support role switching. There is a HCI option to disable
25785 role switching on the local side.
25787 # hccontrol -n ubt0hci write_node_role_switch 0
25789 ----------------------------------------------------------------------
25791 19.4.11.2 Something is going wrong, can I see what exactly is happening?
25793 Yes, you can. Use the hcidump-1.5 third-party package that can be
25794 downloaded from here. The hcidump utility is similar to tcpdump(1). It can
25795 be used to display the content of the Bluetooth packets on the terminal
25796 and to dump the Bluetooth packets to a file.
25798 ----------------------------------------------------------------------
25802 Written by Steve Peterson.
25804 19.5.1 Introduction
25806 It is sometimes useful to divide one physical network (such as an Ethernet
25807 segment) into two separate network segments without having to create IP
25808 subnets and use a router to connect the segments together. A device that
25809 connects two networks together in this fashion is called a ``bridge''. A
25810 DragonFly system with two network interface cards can act as a bridge.
25812 The bridge works by learning the MAC layer addresses (Ethernet addresses)
25813 of the devices on each of its network interfaces. It forwards traffic
25814 between two networks only when its source and destination are on different
25817 In many respects, a bridge is like an Ethernet switch with very few ports.
25819 ----------------------------------------------------------------------
25821 19.5.2 Situations Where Bridging Is Appropriate
25823 There are two common situations in which a bridge is used today.
25825 ----------------------------------------------------------------------
25827 19.5.2.1 High Traffic on a Segment
25829 Situation one is where your physical network segment is overloaded with
25830 traffic, but you do not want for whatever reason to subnet the network and
25831 interconnect the subnets with a router.
25833 Let us consider an example of a newspaper where the Editorial and
25834 Production departments are on the same subnetwork. The Editorial users all
25835 use server A for file service, and the Production users are on server B.
25836 An Ethernet network is used to connect all users together, and high loads
25837 on the network are slowing things down.
25839 If the Editorial users could be segregated on one network segment and the
25840 Production users on another, the two network segments could be connected
25841 with a bridge. Only the network traffic destined for interfaces on the
25842 ``other'' side of the bridge would be sent to the other network, reducing
25843 congestion on each network segment.
25845 ----------------------------------------------------------------------
25847 19.5.2.2 Filtering/Traffic Shaping Firewall
25849 The second common situation is where firewall functionality is needed
25850 without network address translation (NAT).
25852 An example is a small company that is connected via DSL or ISDN to their
25853 ISP. They have a 13 globally-accessible IP addresses from their ISP and
25854 have 10 PCs on their network. In this situation, using a router-based
25855 firewall is difficult because of subnetting issues.
25857 A bridge-based firewall can be configured and dropped into the path just
25858 downstream of their DSL/ISDN router without any IP numbering issues.
25860 ----------------------------------------------------------------------
25862 19.5.3 Configuring a Bridge
25864 19.5.3.1 Network Interface Card Selection
25866 A bridge requires at least two network cards to function. Unfortunately,
25867 not all network interface cards support bridging. Read bridge(4) for
25868 details on the cards that are supported.
25870 Install and test the two network cards before continuing.
25872 ----------------------------------------------------------------------
25874 19.5.3.2 Kernel Configuration Changes
25876 To enable kernel support for bridging, add the:
25880 statement to your kernel configuration file, and rebuild your kernel.
25882 ----------------------------------------------------------------------
25884 19.5.3.3 Firewall Support
25886 If you are planning to use the bridge as a firewall, you will need to add
25887 the IPFIREWALL option as well. Read Section 10.7 for general information
25888 on configuring the bridge as a firewall.
25890 If you need to allow non-IP packets (such as ARP) to flow through the
25891 bridge, there is a firewall option that must be set. This option is
25892 IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this changes the default rule for
25893 the firewall to accept any packet. Make sure you know how this changes the
25894 meaning of your ruleset before you set it.
25896 ----------------------------------------------------------------------
25898 19.5.3.4 Traffic Shaping Support
25900 If you want to use the bridge as a traffic shaper, you will need to add
25901 the DUMMYNET option to your kernel configuration. Read dummynet(4) for
25902 further information.
25904 ----------------------------------------------------------------------
25906 19.5.4 Enabling the Bridge
25910 net.link.ether.bridge=1
25912 to /etc/sysctl.conf to enable the bridge at runtime, and the line:
25914 net.link.ether.bridge_cfg=if1,if2
25916 to enable bridging on the specified interfaces (replace if1 and if2 with
25917 the names of your two network interfaces). If you want the bridged packets
25918 to be filtered by ipfw(8), you should add:
25920 net.link.ether.bridge_ipfw=1
25924 ----------------------------------------------------------------------
25926 19.5.5 Other Information
25928 If you want to be able to telnet(1) into the bridge from the network, it
25929 is correct to assign one of the network cards an IP address. The consensus
25930 is that assigning both cards an address is a bad idea.
25932 If you have multiple bridges on your network, there cannot be more than
25933 one path between any two workstations. Technically, this means that there
25934 is no support for spanning tree link management.
25936 A bridge can add latency to your ping(8) times, especially for traffic
25937 from one segment to another.
25939 ----------------------------------------------------------------------
25943 Reorganized and enhanced by Tom Rhodes. Written by Bill Swingle.
25945 Among the many different filesystems that DragonFly supports is the
25946 Network File System, also known as NFS. NFS allows a system to share
25947 directories and files with others over a network. By using NFS, users and
25948 programs can access files on remote systems almost as if they were local
25951 Some of the most notable benefits that NFS can provide are:
25953 * Local workstations use less disk space because commonly used data can
25954 be stored on a single machine and still remain accessible to others
25957 * There is no need for users to have separate home directories on every
25958 network machine. Home directories could be set up on the NFS server
25959 and made available throughout the network.
25961 * Storage devices such as floppy disks, CDROM drives, and ZIP drives can
25962 be used by other machines on the network. This may reduce the number
25963 of removable media drives throughout the network.
25965 ----------------------------------------------------------------------
25967 19.6.1 How NFS Works
25969 NFS consists of at least two main parts: a server and one or more clients.
25970 The client remotely accesses the data that is stored on the server
25971 machine. In order for this to function properly a few processes have to be
25972 configured and running:
25974 The server has to be running the following daemons:
25977 nfsd The NFS daemon which services requests from the NFS clients.
25978 mountd The NFS mount daemon which carries out the requests that nfsd(8)
25980 portmap The portmapper daemon allows NFS clients to discover which port
25981 the NFS server is using.
25983 The client can also run a daemon, known as nfsiod. The nfsiod daemon
25984 services the requests from the NFS server. This is optional, and improves
25985 performance, but is not required for normal and correct operation. See the
25986 nfsiod(8) manual page for more information.
25988 ----------------------------------------------------------------------
25990 19.6.2 Configuring NFS
25992 NFS configuration is a relatively straightforward process. The processes
25993 that need to be running can all start at boot time with a few
25994 modifications to your /etc/rc.conf file.
25996 On the NFS server, make sure that the following options are configured in
25997 the /etc/rc.conf file:
25999 portmap_enable="YES"
26000 nfs_server_enable="YES"
26003 mountd runs automatically whenever the NFS server is enabled.
26005 On the client, make sure this option is present in /etc/rc.conf:
26007 nfs_client_enable="YES"
26009 The /etc/exports file specifies which filesystems NFS should export
26010 (sometimes referred to as ``share''). Each line in /etc/exports specifies
26011 a filesystem to be exported and which machines have access to that
26012 filesystem. Along with what machines have access to that filesystem,
26013 access options may also be specified. There are many such options that can
26014 be used in this file but only a few will be mentioned here. You can easily
26015 discover other options by reading over the exports(5) manual page.
26017 Here are a few example /etc/exports entries:
26019 The following examples give an idea of how to export filesystems, although
26020 the settings may be different depending on your environment and network
26021 configuration. For instance, to export the /cdrom directory to three
26022 example machines that have the same domain name as the server (hence the
26023 lack of a domain name for each) or have entries in your /etc/hosts file.
26024 The -ro flag makes the exported filesystem read-only. With this flag, the
26025 remote system will not be able to write any changes to the exported
26028 /cdrom -ro host1 host2 host3
26030 The following line exports /home to three hosts by IP address. This is a
26031 useful setup if you have a private network without a DNS server
26032 configured. Optionally the /etc/hosts file could be configured for
26033 internal hostnames; please review hosts(5) for more information. The
26034 -alldirs flag allows the subdirectories to be mount points. In other
26035 words, it will not mount the subdirectories but permit the client to mount
26036 only the directories that are required or needed.
26038 /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4
26040 The following line exports /a so that two clients from different domains
26041 may access the filesystem. The -maproot=root flag allows the root user on
26042 the remote system to write data on the exported filesystem as root. If the
26043 -maproot=root flag is not specified, then even if a user has root access
26044 on the remote system, they will not be able to modify files on the
26045 exported filesystem.
26047 /a -maproot=root host.example.com box.example.org
26049 In order for a client to access an exported filesystem, the client must
26050 have permission to do so. Make sure the client is listed in your
26053 In /etc/exports, each line represents the export information for one
26054 filesystem to one host. A remote host can only be specified once per
26055 filesystem, and may only have one default entry. For example, assume that
26056 /usr is a single filesystem. The following /etc/exports would be invalid:
26061 One filesystem, /usr, has two lines specifying exports to the same host,
26062 client. The correct format for this situation is:
26064 /usr/src /usr/ports client
26066 The properties of one filesystem exported to a given host must all occur
26067 on one line. Lines without a client specified are treated as a single
26068 host. This limits how you can export filesystems, but for most people this
26071 The following is an example of a valid export list, where /usr and
26072 /exports are local filesystems:
26074 # Export src and ports to client01 and client02, but only
26075 # client01 has root privileges on it
26076 /usr/src /usr/ports -maproot=root client01
26077 /usr/src /usr/ports client02
26078 # The client machines have root and can mount anywhere
26079 # on /exports. Anyone in the world can mount /exports/obj read-only
26080 /exports -alldirs -maproot=root client01 client02
26083 You must restart mountd whenever you modify /etc/exports so the changes
26084 can take effect. This can be accomplished by sending the HUP signal to the
26087 # kill -HUP `cat /var/run/mountd.pid`
26089 Alternatively, a reboot will make DragonFly set everything up properly. A
26090 reboot is not necessary though. Executing the following commands as root
26091 should start everything up.
26103 Now everything should be ready to actually mount a remote file system. In
26104 these examples the server's name will be server and the client's name will
26105 be client. If you only want to temporarily mount a remote filesystem or
26106 would rather test the configuration, just execute a command like this as
26107 root on the client:
26109 # mount server:/home /mnt
26111 This will mount the /home directory on the server at /mnt on the client.
26112 If everything is set up correctly you should be able to enter /mnt on the
26113 client and see all the files that are on the server.
26115 If you want to automatically mount a remote filesystem each time the
26116 computer boots, add the filesystem to the /etc/fstab file. Here is an
26119 server:/home /mnt nfs rw 0 0
26121 The fstab(5) manual page lists all the available options.
26123 ----------------------------------------------------------------------
26125 19.6.3 Practical Uses
26127 NFS has many practical uses. Some of the more common ones are listed
26130 * Set several machines to share a CDROM or other media among them. This
26131 is cheaper and often a more convenient method to install software on
26134 * On large networks, it might be more convenient to configure a central
26135 NFS server in which to store all the user home directories. These home
26136 directories can then be exported to the network so that users would
26137 always have the same home directory, regardless of which workstation
26140 * Several machines could have a common /usr/ports/distfiles directory.
26141 That way, when you need to install a port on several machines, you can
26142 quickly access the source without downloading it on each machine.
26144 ----------------------------------------------------------------------
26146 19.6.4 Automatic Mounts with amd
26148 Contributed by Wylie Stilwell. Rewritten by Chern Lee.
26150 amd(8) (the automatic mounter daemon) automatically mounts a remote
26151 filesystem whenever a file or directory within that filesystem is
26152 accessed. Filesystems that are inactive for a period of time will also be
26153 automatically unmounted by amd. Using amd provides a simple alternative to
26154 permanent mounts, as permanent mounts are usually listed in /etc/fstab.
26156 amd operates by attaching itself as an NFS server to the /host and /net
26157 directories. When a file is accessed within one of these directories, amd
26158 looks up the corresponding remote mount and automatically mounts it. /net
26159 is used to mount an exported filesystem from an IP address, while /host is
26160 used to mount an export from a remote hostname.
26162 An access to a file within /host/foobar/usr would tell amd to attempt to
26163 mount the /usr export on the host foobar.
26165 Example 19-1. Mounting an Export with amd
26167 You can view the available mounts of a remote host with the showmount
26168 command. For example, to view the mounts of a host named foobar, you can
26171 % showmount -e foobar
26172 Exports list on foobar:
26175 % cd /host/foobar/usr
26177 As seen in the example, the showmount shows /usr as an export. When
26178 changing directories to /host/foobar/usr, amd attempts to resolve the
26179 hostname foobar and automatically mount the desired export.
26181 amd can be started by the startup scripts by placing the following lines
26186 Additionally, custom flags can be passed to amd from the amd_flags option.
26187 By default, amd_flags is set to:
26189 amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"
26191 The /etc/amd.map file defines the default options that exports are mounted
26192 with. The /etc/amd.conf file defines some of the more advanced features of
26195 Consult the amd(8) and amd.conf(5) manual pages for more information.
26197 ----------------------------------------------------------------------
26199 19.6.5 Problems Integrating with Other Systems
26201 Contributed by John Lind.
26203 Certain Ethernet adapters for ISA PC systems have limitations which can
26204 lead to serious network problems, particularly with NFS. This difficulty
26205 is not specific to DragonFly, but DragonFly systems are affected by it.
26207 The problem nearly always occurs when (DragonFly) PC systems are networked
26208 with high-performance workstations, such as those made by Silicon
26209 Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will work fine,
26210 and some operations may succeed, but suddenly the server will seem to
26211 become unresponsive to the client, even though requests to and from other
26212 systems continue to be processed. This happens to the client system,
26213 whether the client is the DragonFly system or the workstation. On many
26214 systems, there is no way to shut down the client gracefully once this
26215 problem has manifested itself. The only solution is often to reset the
26216 client, because the NFS situation cannot be resolved.
26218 Though the ``correct'' solution is to get a higher performance and
26219 capacity Ethernet adapter for the DragonFly system, there is a simple
26220 workaround that will allow satisfactory operation. If the DragonFly system
26221 is the server, include the option -w=1024 on the mount from the client. If
26222 the DragonFly system is the client, then mount the NFS filesystem with the
26223 option -r=1024. These options may be specified using the fourth field of
26224 the fstab entry on the client for automatic mounts, or by using the -o
26225 parameter of the mount(8) command for manual mounts.
26227 It should be noted that there is a different problem, sometimes mistaken
26228 for this one, when the NFS servers and clients are on different networks.
26229 If that is the case, make certain that your routers are routing the
26230 necessary UDP information, or you will not get anywhere, no matter what
26231 else you are doing.
26233 In the following examples, fastws is the host (interface) name of a
26234 high-performance workstation, and freebox is the host (interface) name of
26235 a DragonFly system with a lower-performance Ethernet adapter. Also,
26236 /sharedfs will be the exported NFS filesystem (see exports(5)), and
26237 /project will be the mount point on the client for the exported
26238 filesystem. In all cases, note that additional options, such as hard or
26239 soft and bg may be desirable in your application.
26241 Examples for the DragonFly system (freebox) as the client in /etc/fstab on
26244 fastws:/sharedfs /project nfs rw,-r=1024 0 0
26246 As a manual mount command on freebox:
26248 # mount -t nfs -o -r=1024 fastws:/sharedfs /project
26250 Examples for the DragonFly system as the server in /etc/fstab on fastws:
26252 freebox:/sharedfs /project nfs rw,-w=1024 0 0
26254 As a manual mount command on fastws:
26256 # mount -t nfs -o -w=1024 freebox:/sharedfs /project
26258 Nearly any 16-bit Ethernet adapter will allow operation without the above
26259 restrictions on the read or write size.
26261 For anyone who cares, here is what happens when the failure occurs, which
26262 also explains why it is unrecoverable. NFS typically works with a
26263 ``block'' size of 8 k (though it may do fragments of smaller sizes). Since
26264 the maximum Ethernet packet is around 1500 bytes, the NFS ``block'' gets
26265 split into multiple Ethernet packets, even though it is still a single
26266 unit to the upper-level code, and must be received, assembled, and
26267 acknowledged as a unit. The high-performance workstations can pump out the
26268 packets which comprise the NFS unit one right after the other, just as
26269 close together as the standard allows. On the smaller, lower capacity
26270 cards, the later packets overrun the earlier packets of the same unit
26271 before they can be transferred to the host and the unit as a whole cannot
26272 be reconstructed or acknowledged. As a result, the workstation will time
26273 out and try again, but it will try again with the entire 8 K unit, and the
26274 process will be repeated, ad infinitum.
26276 By keeping the unit size below the Ethernet packet size limitation, we
26277 ensure that any complete Ethernet packet received can be acknowledged
26278 individually, avoiding the deadlock situation.
26280 Overruns may still occur when a high-performance workstations is slamming
26281 data out to a PC system, but with the better cards, such overruns are not
26282 guaranteed on NFS ``units''. When an overrun occurs, the units affected
26283 will be retransmitted, and there will be a fair chance that they will be
26284 received, assembled, and acknowledged.
26286 ----------------------------------------------------------------------
26288 19.7 Diskless Operation
26290 Updated by Jean-Franc,ois Dockes. Reorganized and enhanced by Alex Dupre.
26292 A DragonFly machine can boot over the network and operate without a local
26293 disk, using filesystems mounted from an NFS server. No system modification
26294 is necessary, beyond standard configuration files. Such a system is
26295 relatively easy to set up because all the necessary elements are readily
26298 * There are at least two possible methods to load the kernel over the
26301 * PXE: The Intel Preboot Execution Environment system is a form of
26302 smart boot ROM built into some networking cards or motherboards.
26303 See pxeboot(8) for more details.
26305 * The etherboot port (net/etherboot) produces ROM-able code to boot
26306 kernels over the network. The code can be either burnt into a
26307 boot PROM on a network card, or loaded from a local floppy (or
26308 hard) disk drive, or from a running MS-DOS system. Many network
26309 cards are supported.
26311 * A sample script (/usr/share/examples/diskless/clone_root) eases the
26312 creation and maintenance of the workstation's root filesystem on the
26313 server. The script will probably require a little customization but it
26314 will get you started very quickly.
26316 * Standard system startup files exist in /etc to detect and support a
26317 diskless system startup.
26319 * Swapping, if needed, can be done either to an NFS file or to a local
26322 There are many ways to set up diskless workstations. Many elements are
26323 involved, and most can be customized to suit local taste. The following
26324 will describe variations on the setup of a complete system, emphasizing
26325 simplicity and compatibility with the standard DragonFly startup scripts.
26326 The system described has the following characteristics:
26328 * The diskless workstations use a shared read-only root filesystem, and
26329 a shared read-only /usr.
26331 The root filesystem is a copy of a standard DragonFly root (typically
26332 the server's), with some configuration files overridden by ones
26333 specific to diskless operation or, possibly, to the workstation they
26336 The parts of the root which have to be writable are overlaid with
26337 mfs(8) filesystems. Any changes will be lost when the system reboots.
26339 * The kernel is transferred and loaded either with etherboot or PXE as
26340 some situations may mandate the use of either method.
26342 Caution: As described, this system is insecure. It should live in a
26343 protected area of a network, and be untrusted by other hosts.
26345 ----------------------------------------------------------------------
26347 19.7.1 Background Information
26349 Setting up diskless workstations is both relatively straightforward and
26350 prone to errors. These are sometimes difficult to diagnose for a number of
26351 reasons. For example:
26353 * Compile time options may determine different behaviours at runtime.
26355 * Error messages are often cryptic or totally absent.
26357 In this context, having some knowledge of the background mechanisms
26358 involved is very useful to solve the problems that may arise.
26360 Several operations need to be performed for a successful bootstrap:
26362 * The machine needs to obtain initial parameters such as its IP address,
26363 executable filename, server name, root path. This is done using the
26364 DHCP or BOOTP protocols. DHCP is a compatible extension of BOOTP, and
26365 uses the same port numbers and basic packet format.
26367 It is possible to configure a system to use only BOOTP. The bootpd(8)
26368 server program is included in the base DragonFly system.
26370 However, DHCP has a number of advantages over BOOTP (nicer
26371 configuration files, possibility of using PXE, plus many others not
26372 directly related to diskless operation), and we will describe mainly a
26373 DHCP configuration, with equivalent exemples using bootpd(8) when
26374 possible. The sample configuration will use the ISC DHCP software
26375 package (release 3.0.1.r12 was installed on the test server).
26377 * The machine needs to transfer one or several programs to local memory.
26378 Either TFTP or NFS are used. The choice between TFTP and NFS is a
26379 compile time option in several places. A common source of error is to
26380 specify filenames for the wrong protocol: TFTP typically transfers all
26381 files from a single directory on the server, and would expect
26382 filenames relative to this directory. NFS needs absolute file paths.
26384 * The possible intermediate bootstrap programs and the kernel need to be
26385 initialized and executed. There are several important variations in
26388 * PXE will load pxeboot(8), which is a modified version of the
26389 DragonFly third stage loader. The loader(8) will obtain most
26390 parameters necessary to system startup, and leave them in the
26391 kernel environment before transferring control. It is possible to
26392 use a GENERIC kernel in this case.
26394 * etherboot, will directly load the kernel, with less preparation.
26395 You will need to build a kernel with specific options.
26397 * Finally, the machine needs to access its filesystems. NFS is used in
26400 See also diskless(8) manual page.
26402 ----------------------------------------------------------------------
26404 19.7.2 Setup Instructions
26406 19.7.2.1 Configuration Using ISC DHCP
26408 The ISC DHCP server can answer both BOOTP and DHCP requests.
26410 ISC DHCP needs a configuration file to run, (normally named
26411 /usr/local/etc/dhcpd.conf). Here follows a commented example, where host
26412 margaux uses etherboot and host corbieres uses PXE:
26414 default-lease-time 600;
26415 max-lease-time 7200;
26418 option domain-name "example.com";
26419 option domain-name-servers 192.168.4.1;
26420 option routers 192.168.4.1;
26422 subnet 192.168.4.0 netmask 255.255.255.0 {
26423 use-host-decl-names on; (1)
26424 option subnet-mask 255.255.255.0;
26425 option broadcast-address 192.168.4.255;
26428 hardware ethernet 01:23:45:67:89:ab;
26429 fixed-address margaux.example.com;
26430 next-server 192.168.4.4; (2)
26431 filename "/data/misc/kernel.diskless"; (3)
26432 option root-path "192.168.4.4:/data/misc/diskless"; (4)
26435 hardware ethernet 00:02:b3:27:62:df;
26436 fixed-address corbieres.example.com;
26437 next-server 192.168.4.4;
26438 filename "pxeboot";
26439 option root-path "192.168.4.4:/data/misc/diskless";
26445 This option tells dhcpd to send the value in the host declarations
26446 as the hostname for the diskless host. An alternate way would be
26447 to add an option host-name margaux inside the host declarations.
26449 The next-server directive designates the TFTP or NFS server to use
26450 for loading loader or kernel file (the default is to use the same
26451 host as the DHCP server).
26453 The filename directive defines the file that etherboot or PXE will
26454 load for the next execution step. It must be specified according
26455 to the transfer method used. etherboot can be compiled to use NFS
26456 or TFTP. The DragonFly port configures NFS by default. PXE uses
26457 TFTP, which is why a relative filename is used here (this may
26458 depend on the TFTP server configuration, but would be fairly
26459 typical). Also, PXE loads pxeboot, not the kernel. There are other
26460 interesting possibilities, like loading pxeboot from a DragonFly
26461 CD-ROM /boot directory (as pxeboot(8) can load a GENERIC kernel,
26462 this makes it possible to use PXE to boot from a remote CD-ROM).
26464 The root-path option defines the path to the root filesystem, in
26465 usual NFS notation. When using PXE, it is possible to leave off
26466 the host's IP as long as you do not enable the kernel option
26467 BOOTP. The NFS server will then be the same as the TFTP one.
26469 ----------------------------------------------------------------------
26471 19.7.2.2 Configuration Using BOOTP
26473 Here follows an equivalent bootpd configuration (reduced to one client).
26474 This would be found in /etc/bootptab.
26476 Please note that etherboot must be compiled with the non-default option
26477 NO_DHCP_SUPPORT in order to use BOOTP, and that PXE needs DHCP. The only
26478 obvious advantage of bootpd is that it exists in the base system.
26481 :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
26482 :sm=255.255.255.0:\
26486 :bf="/kernel.diskless":\
26487 :rp="192.168.4.4:/data/misc/diskless":
26489 margaux:ha=0123456789ab:tc=.def100
26492 ----------------------------------------------------------------------
26494 19.7.2.3 Booting with PXE
26496 By default, the pxeboot(8) loader loads the kernel via NFS. It can be
26497 compiled to use TFTP instead by specifying the LOADER_TFTP_SUPPORT option
26498 in /etc/make.conf. See the comments in /etc/defaults/make.conf (or
26499 /usr/share/examples/etc/make.conf for 5.X systems) for instructions.
26501 There are two other undocumented make.conf options which may be useful for
26502 setting up a serial console diskless machine: BOOT_PXELDR_PROBE_KEYBOARD,
26503 and BOOT_PXELDR_ALWAYS_SERIAL.
26505 To use PXE when the machine starts, you will usually need to select the
26506 Boot from network option in your BIOS setup, or type a function key during
26507 the PC initialization.
26509 ----------------------------------------------------------------------
26511 19.7.2.4 Configuring the TFTP and NFS Servers
26513 If you are using PXE or etherboot configured to use TFTP, you need to
26514 enable tftpd on the file server:
26516 1. Create a directory from which tftpd will serve the files, e.g.
26519 2. Add this line to your /etc/inetd.conf:
26521 tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot
26523 Note: It appears that at least some PXE versions want the TCP
26524 version of TFTP. In this case, add a second line, replacing dgram
26525 udp with stream tcp.
26527 3. Tell inetd to reread its configuration file:
26529 # kill -HUP `cat /var/run/inetd.pid`
26531 You can place the tftpboot directory anywhere on the server. Make sure
26532 that the location is set in both inetd.conf and dhcpd.conf.
26534 In all cases, you also need to enable NFS and export the appropriate
26535 filesystem on the NFS server.
26537 1. Add this to /etc/rc.conf:
26539 nfs_server_enable="YES"
26541 2. Export the filesystem where the diskless root directory is located by
26542 adding the following to /etc/exports (adjust the volume mount point
26543 and replace margaux corbieres with the names of the diskless
26546 /data/misc -alldirs -ro margaux corbieres
26548 3. Tell mountd to reread its configuration file. If you actually needed
26549 to enable NFS in /etc/rc.conf at the first step, you probably want to
26552 # kill -HUP `cat /var/run/mountd.pid`
26554 ----------------------------------------------------------------------
26556 19.7.2.5 Building a Diskless Kernel
26558 If using etherboot, you need to create a kernel configuration file for the
26559 diskless client with the following options (in addition to the usual
26562 options BOOTP # Use BOOTP to obtain IP address/hostname
26563 options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
26566 You may also want to use BOOTP_NFSV3, BOOT_COMPAT and BOOTP_WIRED_TO
26569 These option names are historical and slightly misleading as they actually
26570 enable indifferent use of DHCP and BOOTP inside the kernel (it is also
26571 possible to force strict BOOTP or DHCP use).
26573 Build the kernel (see Chapter 9), and copy it to the place specified in
26576 Note: When using PXE, building a kernel with the above options is not
26577 strictly necessary (though suggested). Enabling them will cause more
26578 DHCP requests to be issued during kernel startup, with a small risk of
26579 inconsistency between the new values and those retrieved by pxeboot(8)
26580 in some special cases. The advantage of using them is that the host name
26581 will be set as a side effect. Otherwise you will need to set the host
26582 name by another method, for example in a client-specific rc.conf file.
26584 ----------------------------------------------------------------------
26586 19.7.2.6 Preparing the Root Filesystem
26588 You need to create a root filesystem for the diskless workstations, in the
26589 location listed as root-path in dhcpd.conf. The following sections
26590 describe two ways to do it.
26592 ----------------------------------------------------------------------
26594 19.7.2.6.1 Using the clone_root Script
26596 This is the quickest way to create a root filesystem. but This shell
26597 script is located at /usr/share/examples/diskless/clone_root and needs
26598 customization, at least to adjust the place where the filesystem will be
26599 created (the DEST variable).
26601 Refer to the comments at the top of the script for instructions. They
26602 explain how the base filesystem is built, and how files may be selectively
26603 overridden by versions specific to diskless operation, to a subnetwork, or
26604 to an individual workstation. They also give examples for the diskless
26605 /etc/fstab and /etc/rc.conf files.
26607 The README files in /usr/share/examples/diskless contain a lot of
26608 interesting background information, but, together with the other examples
26609 in the diskless directory, they actually document a configuration method
26610 which is distinct from the one used by clone_root and the system startup
26611 scripts in /etc, which is a little confusing. Use them for reference only,
26612 except if you prefer the method that they describe, in which case you will
26613 need customized rc scripts.
26615 ----------------------------------------------------------------------
26617 19.7.2.6.2 Using the Standard make world Procedure
26619 This method will install a complete virgin system (not only the root
26620 filesystem) into DESTDIR. All you have to do is simply execute the
26624 export DESTDIR=/data/misc/diskless
26625 mkdir -p ${DESTDIR}
26626 cd /usr/src; make world && make kernel
26627 cd /usr/src/etc; make distribution
26629 Once done, you may need to customize your /etc/rc.conf and /etc/fstab
26630 placed into DESTDIR according to your needs.
26632 ----------------------------------------------------------------------
26634 19.7.2.7 Configuring Swap
26636 If needed, a swap file located on the server can be accessed via NFS.
26638 ----------------------------------------------------------------------
26640 19.7.2.7.1 NFS Swap with DragonFly
26642 The swap file location and size can be specified with BOOTP/DHCP
26643 DragonFly-specific options 128 and 129. Examples of configuration files
26644 for ISC DHCP 3.0 or bootpd follow:
26646 1. Add the following lines to dhcpd.conf:
26649 option swap-path code 128 = string;
26650 option swap-size code 129 = integer 32;
26653 ... # Standard lines, see above
26654 option swap-path "192.168.4.4:/netswapvolume/netswap";
26655 option swap-size 64000;
26659 swap-path is the path to a directory where swap files will be located.
26660 Each file will be named swap.client-ip.
26662 Older versions of dhcpd used a syntax of option option-128 "..., which
26663 is no longer supported.
26665 /etc/bootptab would use the following syntax instead:
26667 T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00
26669 Note: In /etc/bootptab, the swap size must be expressed in
26670 hexadecimal format.
26672 2. On the NFS swap file server, create the swap file(s)
26674 # mkdir /netswapvolume/netswap
26675 # cd /netswapvolume/netswap
26676 # dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6
26677 # chmod 0600 swap.192.168.4.6
26680 192.168.4.6 is the IP address for the diskless client.
26682 3. On the NFS swap file server, add the following line to /etc/exports:
26684 /netswapvolume -maproot=0:10 -alldirs margaux corbieres
26687 Then tell mountd to reread the exports file, as above.
26689 ----------------------------------------------------------------------
26691 19.7.2.8 Miscellaneous Issues
26693 19.7.2.8.1 Running with a Read-only /usr
26695 If the diskless workstation is configured to run X, you will have to
26696 adjust the xdm configuration file, which puts the error log on /usr by
26699 ----------------------------------------------------------------------
26701 19.7.2.8.2 Using a Non-DragonFly Server
26703 When the server for the root filesystem is not running DragonFly, you will
26704 have to create the root filesystem on a DragonFly machine, then copy it to
26705 its destination, using tar or cpio.
26707 In this situation, there are sometimes problems with the special files in
26708 /dev, due to differing major/minor integer sizes. A solution to this
26709 problem is to export a directory from the non-DragonFly server, mount this
26710 directory onto a DragonFly machine, and run MAKEDEV on the DragonFly
26711 machine to create the correct device entries.
26713 ----------------------------------------------------------------------
26717 A good resource for information on ISDN technology and hardware is Dan
26720 A quick simple road map to ISDN follows:
26722 * If you live in Europe you might want to investigate the ISDN card
26725 * If you are planning to use ISDN primarily to connect to the Internet
26726 with an Internet Provider on a dial-up non-dedicated basis, you might
26727 look into Terminal Adapters. This will give you the most flexibility,
26728 with the fewest problems, if you change providers.
26730 * If you are connecting two LANs together, or connecting to the Internet
26731 with a dedicated ISDN connection, you might consider the stand alone
26732 router/bridge option.
26734 Cost is a significant factor in determining what solution you will choose.
26735 The following options are listed from least expensive to most expensive.
26737 ----------------------------------------------------------------------
26741 Contributed by Hellmuth Michaelis.
26743 DragonFly's ISDN implementation supports only the DSS1/Q.931 (or
26744 Euro-ISDN) standard using passive cards. Some active cards are supported
26745 where the firmware also supports other signaling protocols; this also
26746 includes the first supported Primary Rate (PRI) ISDN card.
26748 The isdn4bsd software allows you to connect to other ISDN routers using
26749 either IP over raw HDLC or by using synchronous PPP: either by using
26750 kernel PPP with isppp, a modified sppp(4) driver, or by using userland
26751 ppp(8). By using userland ppp(8), channel bonding of two or more ISDN
26752 B-channels is possible. A telephone answering machine application is also
26753 available as well as many utilities such as a software 300 Baud modem.
26755 Some growing number of PC ISDN cards are supported under DragonFly and the
26756 reports show that it is successfully used all over Europe and in many
26757 other parts of the world.
26759 The passive ISDN cards supported are mostly the ones with the Infineon
26760 (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, but also ISDN cards with
26761 chips from Cologne Chip (ISA bus only), PCI cards with Winbond W6692
26762 chips, some cards with the Tiger300/320/ISAC chipset combinations and some
26763 vendor specific chipset based cards such as the AVM Fritz!Card PCI V.1.0
26764 and the AVM Fritz!Card PnP.
26766 Currently the active supported ISDN cards are the AVM B1 (ISA and PCI) BRI
26767 cards and the AVM T1 PCI PRI cards.
26769 For documentation on isdn4bsd, have a look at /usr/share/examples/isdn/
26770 directory on your DragonFly system or at the homepage of isdn4bsd which
26771 also has pointers to hints, erratas and much more documentation such as
26772 the isdn4bsd handbook.
26774 For questions regarding the installation, configuration and
26775 troubleshooting isdn4bsd, a freebsd-isdn mailing list is available.
26777 ----------------------------------------------------------------------
26779 19.8.2 ISDN Terminal Adapters
26781 Terminal adapters (TA), are to ISDN what modems are to regular phone
26784 Most TA's use the standard Hayes modem AT command set, and can be used as
26785 a drop in replacement for a modem.
26787 A TA will operate basically the same as a modem except connection and
26788 throughput speeds will be much faster than your old modem. You will need
26789 to configure PPP exactly the same as for a modem setup. Make sure you set
26790 your serial speed as high as possible.
26792 The main advantage of using a TA to connect to an Internet Provider is
26793 that you can do Dynamic PPP. As IP address space becomes more and more
26794 scarce, most providers are not willing to provide you with a static IP
26795 anymore. Most stand-alone routers are not able to accommodate dynamic IP
26798 TA's completely rely on the PPP daemon that you are running for their
26799 features and stability of connection. This allows you to upgrade easily
26800 from using a modem to ISDN on a DragonFly machine, if you already have PPP
26801 set up. However, at the same time any problems you experienced with the
26802 PPP program and are going to persist.
26804 If you want maximum stability, use the kernel PPP option, not the userland
26807 The following TA's are known to work with DragonFly:
26809 * Motorola BitSurfer and Bitsurfer Pro
26813 Most other TA's will probably work as well, TA vendors try to make sure
26814 their product can accept most of the standard modem AT command set.
26816 The real problem with external TA's is that, like modems, you need a good
26817 serial card in your computer.
26819 You should read the DragonFly Serial Hardware tutorial for a detailed
26820 understanding of serial devices, and the differences between asynchronous
26821 and synchronous serial ports.
26823 A TA running off a standard PC serial port (asynchronous) limits you to
26824 115.2 Kbs, even though you have a 128 Kbs connection. To fully utilize the
26825 128 Kbs that ISDN is capable of, you must move the TA to a synchronous
26828 Do not be fooled into buying an internal TA and thinking you have avoided
26829 the synchronous/asynchronous issue. Internal TA's simply have a standard
26830 PC serial port chip built into them. All this will do is save you having
26831 to buy another serial cable and find another empty electrical socket.
26833 A synchronous card with a TA is at least as fast as a stand-alone router,
26834 and with a simple 386 DragonFly box driving it, probably more flexible.
26836 The choice of synchronous card/TA v.s. stand-alone router is largely a
26837 religious issue. There has been some discussion of this in the mailing
26838 lists. We suggest you search the archives for the complete discussion.
26840 ----------------------------------------------------------------------
26842 19.8.3 Stand-alone ISDN Bridges/Routers
26844 ISDN bridges or routers are not at all specific to DragonFly or any other
26845 operating system. For a more complete description of routing and bridging
26846 technology, please refer to a networking reference book.
26848 In the context of this section, the terms router and bridge will be used
26851 As the cost of low end ISDN routers/bridges comes down, it will likely
26852 become a more and more popular choice. An ISDN router is a small box that
26853 plugs directly into your local Ethernet network, and manages its own
26854 connection to the other bridge/router. It has built in software to
26855 communicate via PPP and other popular protocols.
26857 A router will allow you much faster throughput than a standard TA, since
26858 it will be using a full synchronous ISDN connection.
26860 The main problem with ISDN routers and bridges is that interoperability
26861 between manufacturers can still be a problem. If you are planning to
26862 connect to an Internet provider, you should discuss your needs with them.
26864 If you are planning to connect two LAN segments together, such as your
26865 home LAN to the office LAN, this is the simplest lowest maintenance
26866 solution. Since you are buying the equipment for both sides of the
26867 connection you can be assured that the link will work.
26869 For example to connect a home computer or branch office network to a head
26870 office network the following setup could be used:
26872 Example 19-2. Branch Office or Home Network
26874 Network uses a bus based topology with 10 base 2 Ethernet (``thinnet'').
26875 Connect router to network cable with AUI/10BT transceiver, if necessary.
26887 If your home/branch office is only one computer you can use a twisted pair
26888 crossover cable to connect to the stand-alone router directly.
26890 Example 19-3. Head Office or Other LAN
26892 Network uses a star topology with 10 base T Ethernet (``Twisted Pair'').
26894 -------Novell Server
26902 |___---Stand-alone router
26906 One large advantage of most routers/bridges is that they allow you to have
26907 two separate independent PPP connections to two separate sites at the same
26908 time. This is not supported on most TA's, except for specific (usually
26909 expensive) models that have two serial ports. Do not confuse this with
26910 channel bonding, MPP, etc.
26912 This can be a very useful feature if, for example, you have an dedicated
26913 ISDN connection at your office and would like to tap into it, but do not
26914 want to get another ISDN line at work. A router at the office location can
26915 manage a dedicated B channel connection (64 Kbps) to the Internet and use
26916 the other B channel for a separate data connection. The second B channel
26917 can be used for dial-in, dial-out or dynamically bonding (MPP, etc.) with
26918 the first B channel for more bandwidth.
26920 An Ethernet bridge will also allow you to transmit more than just IP
26921 traffic. You can also send IPX/SPX or whatever other protocols you use.
26923 ----------------------------------------------------------------------
26927 Written by Bill Swingle. Enhanced by Eric Ogren and Udo Erdelhoff.
26931 NIS, which stands for Network Information Services, was developed by Sun
26932 Microsystems to centralize administration of UNIX (originally SunOS)
26933 systems. It has now essentially become an industry standard; all major
26934 UNIX like systems (Solaris, HP-UX, AIX(R), Linux, NetBSD, OpenBSD,
26935 FreeBSD, DragonFly, etc.) support NIS.
26937 NIS was formerly known as Yellow Pages, but because of trademark issues,
26938 Sun changed the name. The old term (and yp) is still often seen and used.
26940 It is a RPC-based client/server system that allows a group of machines
26941 within an NIS domain to share a common set of configuration files. This
26942 permits a system administrator to set up NIS client systems with only
26943 minimal configuration data and add, remove or modify configuration data
26944 from a single location.
26946 It is similar to the Windows NT(R) domain system; although the internal
26947 implementation of the two are not at all similar, the basic functionality
26950 ----------------------------------------------------------------------
26952 19.9.2 Terms/Processes You Should Know
26954 There are several terms and several important user processes that you will
26955 come across when attempting to implement NIS on DragonFly, whether you are
26956 trying to create an NIS server or act as an NIS client:
26958 +------------------------------------------------------------------------+
26959 | Term | Description |
26960 |----------------+-------------------------------------------------------|
26961 | | An NIS master server and all of its clients |
26962 | NIS domainname | (including its slave servers) have a NIS domainname. |
26963 | | Similar to an Windows NT domain name, the NIS |
26964 | | domainname does not have anything to do with DNS. |
26965 |----------------+-------------------------------------------------------|
26966 | | Must be running in order to enable RPC (Remote |
26967 | portmap | Procedure Call, a network protocol used by NIS). If |
26968 | | portmap is not running, it will be impossible to run |
26969 | | an NIS server, or to act as an NIS client. |
26970 |----------------+-------------------------------------------------------|
26971 | | ``Binds'' an NIS client to its NIS server. It will |
26972 | | take the NIS domainname from the system, and using |
26973 | ypbind | RPC, connect to the server. ypbind is the core of |
26974 | | client-server communication in an NIS environment; if |
26975 | | ypbind dies on a client machine, it will not be able |
26976 | | to access the NIS server. |
26977 |----------------+-------------------------------------------------------|
26978 | | Should only be running on NIS servers; this is the |
26979 | | NIS server process itself. If ypserv(8) dies, then |
26980 | | the server will no longer be able to respond to NIS |
26981 | | requests (hopefully, there is a slave server to take |
26982 | ypserv | over for it). There are some implementations of NIS |
26983 | | (but not the DragonFly one), that do not try to |
26984 | | reconnect to another server if the server it used |
26985 | | before dies. Often, the only thing that helps in this |
26986 | | case is to restart the server process (or even the |
26987 | | whole server) or the ypbind process on the client. |
26988 |----------------+-------------------------------------------------------|
26989 | | Another process that should only be running on NIS |
26990 | | master servers; this is a daemon that will allow NIS |
26991 | rpc.yppasswdd | clients to change their NIS passwords. If this daemon |
26992 | | is not running, users will have to login to the NIS |
26993 | | master server and change their passwords there. |
26994 +------------------------------------------------------------------------+
26996 ----------------------------------------------------------------------
26998 19.9.3 How Does It Work?
27000 There are three types of hosts in an NIS environment: master servers,
27001 slave servers, and clients. Servers act as a central repository for host
27002 configuration information. Master servers hold the authoritative copy of
27003 this information, while slave servers mirror this information for
27004 redundancy. Clients rely on the servers to provide this information to
27007 Information in many files can be shared in this manner. The master.passwd,
27008 group, and hosts files are commonly shared via NIS. Whenever a process on
27009 a client needs information that would normally be found in these files
27010 locally, it makes a query to the NIS server that it is bound to instead.
27012 ----------------------------------------------------------------------
27014 19.9.3.1 Machine Types
27016 * A NIS master server. This server, analogous to a Windows NT primary
27017 domain controller, maintains the files used by all of the NIS clients.
27018 The passwd, group, and other various files used by the NIS clients
27019 live on the master server.
27021 Note: It is possible for one machine to be an NIS master server for
27022 more than one NIS domain. However, this will not be covered in this
27023 introduction, which assumes a relatively small-scale NIS
27026 * NIS slave servers. Similar to the Windows NT backup domain
27027 controllers, NIS slave servers maintain copies of the NIS master's
27028 data files. NIS slave servers provide the redundancy, which is needed
27029 in important environments. They also help to balance the load of the
27030 master server: NIS Clients always attach to the NIS server whose
27031 response they get first, and this includes slave-server-replies.
27033 * NIS clients. NIS clients, like most Windows NT workstations,
27034 authenticate against the NIS server (or the Windows NT domain
27035 controller in the Windows NT Workstation case) to log on.
27037 ----------------------------------------------------------------------
27039 19.9.4 Using NIS/YP
27041 This section will deal with setting up a sample NIS environment.
27043 ----------------------------------------------------------------------
27047 Let us assume that you are the administrator of a small university lab.
27048 This lab, which consists of 15 DragonFly machines, currently has no
27049 centralized point of administration; each machine has its own /etc/passwd
27050 and /etc/master.passwd. These files are kept in sync with each other only
27051 through manual intervention; currently, when you add a user to the lab,
27052 you must run adduser on all 15 machines. Clearly, this has to change, so
27053 you have decided to convert the lab to use NIS, using two of the machines
27056 Therefore, the configuration of the lab now looks something like:
27058 +------------------------------------------------------+
27059 | Machine name | IP address | Machine role |
27060 |--------------+---------------+-----------------------|
27061 | ellington | 10.0.0.2 | NIS master |
27062 |--------------+---------------+-----------------------|
27063 | coltrane | 10.0.0.3 | NIS slave |
27064 |--------------+---------------+-----------------------|
27065 | basie | 10.0.0.4 | Faculty workstation |
27066 |--------------+---------------+-----------------------|
27067 | bird | 10.0.0.5 | Client machine |
27068 |--------------+---------------+-----------------------|
27069 | cli[1-11] | 10.0.0.[6-17] | Other client machines |
27070 +------------------------------------------------------+
27072 If you are setting up a NIS scheme for the first time, it is a good idea
27073 to think through how you want to go about it. No matter what the size of
27074 your network, there are a few decisions that need to be made.
27076 ----------------------------------------------------------------------
27078 19.9.4.1.1 Choosing a NIS Domain Name
27080 This might not be the ``domainname'' that you are used to. It is more
27081 accurately called the ``NIS domainname''. When a client broadcasts its
27082 requests for info, it includes the name of the NIS domain that it is part
27083 of. This is how multiple servers on one network can tell which server
27084 should answer which request. Think of the NIS domainname as the name for a
27085 group of hosts that are related in some way.
27087 Some organizations choose to use their Internet domainname for their NIS
27088 domainname. This is not recommended as it can cause confusion when trying
27089 to debug network problems. The NIS domainname should be unique within your
27090 network and it is helpful if it describes the group of machines it
27091 represents. For example, the Art department at Acme Inc. might be in the
27092 ``acme-art'' NIS domain. For this example, assume you have chosen the name
27095 However, some operating systems (notably SunOS) use their NIS domain name
27096 as their Internet domain name. If one or more machines on your network
27097 have this restriction, you must use the Internet domain name as your NIS
27100 ----------------------------------------------------------------------
27102 19.9.4.1.2 Physical Server Requirements
27104 There are several things to keep in mind when choosing a machine to use as
27105 a NIS server. One of the unfortunate things about NIS is the level of
27106 dependency the clients have on the server. If a client cannot contact the
27107 server for its NIS domain, very often the machine becomes unusable. The
27108 lack of user and group information causes most systems to temporarily
27109 freeze up. With this in mind you should make sure to choose a machine that
27110 will not be prone to being rebooted regularly, or one that might be used
27111 for development. The NIS server should ideally be a stand alone machine
27112 whose sole purpose in life is to be an NIS server. If you have a network
27113 that is not very heavily used, it is acceptable to put the NIS server on a
27114 machine running other services, just keep in mind that if the NIS server
27115 becomes unavailable, it will affect all of your NIS clients adversely.
27117 ----------------------------------------------------------------------
27119 19.9.4.2 NIS Servers
27121 The canonical copies of all NIS information are stored on a single machine
27122 called the NIS master server. The databases used to store the information
27123 are called NIS maps. In DragonFly, these maps are stored in
27124 /var/yp/[domainname] where [domainname] is the name of the NIS domain
27125 being served. A single NIS server can support several domains at once,
27126 therefore it is possible to have several such directories, one for each
27127 supported domain. Each domain will have its own independent set of maps.
27129 NIS master and slave servers handle all NIS requests with the ypserv
27130 daemon. ypserv is responsible for receiving incoming requests from NIS
27131 clients, translating the requested domain and map name to a path to the
27132 corresponding database file and transmitting data from the database back
27135 ----------------------------------------------------------------------
27137 19.9.4.2.1 Setting Up a NIS Master Server
27139 Setting up a master NIS server can be relatively straight forward,
27140 depending on your needs. DragonFly comes with support for NIS
27141 out-of-the-box. All you need is to add the following lines to
27142 /etc/rc.conf, and DragonFly will do the rest for you.
27144 1. nisdomainname="test-domain"
27146 This line will set the NIS domainname to test-domain upon network
27147 setup (e.g. after reboot).
27149 2. nis_server_enable="YES"
27151 This will tell DragonFly to start up the NIS server processes when the
27152 networking is next brought up.
27154 3. nis_yppasswdd_enable="YES"
27156 This will enable the rpc.yppasswdd daemon which, as mentioned above,
27157 will allow users to change their NIS password from a client machine.
27159 Note: Depending on your NIS setup, you may need to add further entries.
27160 See the section about NIS servers that are also NIS clients, below, for
27163 Now, all you have to do is to run the command /etc/netstart as superuser.
27164 It will set up everything for you, using the values you defined in
27167 ----------------------------------------------------------------------
27169 19.9.4.2.2 Initializing the NIS Maps
27171 The NIS maps are database files, that are kept in the /var/yp directory.
27172 They are generated from configuration files in the /etc directory of the
27173 NIS master, with one exception: the /etc/master.passwd file. This is for a
27174 good reason; you do not want to propagate passwords to your root and other
27175 administrative accounts to all the servers in the NIS domain. Therefore,
27176 before we initialize the NIS maps, you should:
27178 # cp /etc/master.passwd /var/yp/master.passwd
27182 You should remove all entries regarding system accounts (bin, tty, kmem,
27183 games, etc), as well as any accounts that you do not want to be propagated
27184 to the NIS clients (for example root and any other UID 0 (superuser)
27187 Note: Make sure the /var/yp/master.passwd is neither group nor world
27188 readable (mode 600)! Use the chmod command, if appropriate.
27190 When you have finished, it is time to initialize the NIS maps! DragonFly
27191 includes a script named ypinit to do this for you (see its manual page for
27192 more information). Note that this script is available on most UNIX
27193 Operating Systems, but not on all. On Digital UNIX/Compaq Tru64 UNIX it is
27194 called ypsetup. Because we are generating maps for an NIS master, we are
27195 going to pass the -m option to ypinit. To generate the NIS maps, assuming
27196 you already performed the steps above, run:
27198 ellington# ypinit -m test-domain
27199 Server Type: MASTER Domain: test-domain
27200 Creating an YP server will require that you answer a few questions.
27201 Questions will all be asked at the beginning of the procedure.
27202 Do you want this procedure to quit on non-fatal errors? [y/n: n] n
27203 Ok, please remember to go back and redo manually whatever fails.
27204 If you don't, something might not work.
27205 At this point, we have to construct a list of this domains YP servers.
27206 rod.darktech.org is already known as master server.
27207 Please continue to add any slave servers, one per line. When you are
27208 done with the list, type a <control D>.
27209 master server : ellington
27210 next host to add: coltrane
27211 next host to add: ^D
27212 The current list of NIS servers looks like this:
27215 Is this correct? [y/n: y] y
27217 [..output from map generation..]
27219 NIS Map update completed.
27220 ellington has been setup as an YP master server without any errors.
27222 ypinit should have created /var/yp/Makefile from /var/yp/Makefile.dist.
27223 When created, this file assumes that you are operating in a single server
27224 NIS environment with only DragonFly machines. Since test-domain has a
27225 slave server as well, you must edit /var/yp/Makefile:
27227 ellington# vi /var/yp/Makefile
27229 You should comment out the line that says
27233 (if it is not commented out already).
27235 ----------------------------------------------------------------------
27237 19.9.4.2.3 Setting up a NIS Slave Server
27239 Setting up an NIS slave server is even more simple than setting up the
27240 master. Log on to the slave server and edit the file /etc/rc.conf as you
27241 did before. The only difference is that we now must use the -s option when
27242 running ypinit. The -s option requires the name of the NIS master be
27243 passed to it as well, so our command line looks like:
27245 coltrane# ypinit -s ellington test-domain
27247 Server Type: SLAVE Domain: test-domain Master: ellington
27249 Creating an YP server will require that you answer a few questions.
27250 Questions will all be asked at the beginning of the procedure.
27252 Do you want this procedure to quit on non-fatal errors? [y/n: n] n
27254 Ok, please remember to go back and redo manually whatever fails.
27255 If you don't, something might not work.
27256 There will be no further questions. The remainder of the procedure
27257 should take a few minutes, to copy the databases from ellington.
27258 Transferring netgroup...
27259 ypxfr: Exiting: Map successfully transferred
27260 Transferring netgroup.byuser...
27261 ypxfr: Exiting: Map successfully transferred
27262 Transferring netgroup.byhost...
27263 ypxfr: Exiting: Map successfully transferred
27264 Transferring master.passwd.byuid...
27265 ypxfr: Exiting: Map successfully transferred
27266 Transferring passwd.byuid...
27267 ypxfr: Exiting: Map successfully transferred
27268 Transferring passwd.byname...
27269 ypxfr: Exiting: Map successfully transferred
27270 Transferring group.bygid...
27271 ypxfr: Exiting: Map successfully transferred
27272 Transferring group.byname...
27273 ypxfr: Exiting: Map successfully transferred
27274 Transferring services.byname...
27275 ypxfr: Exiting: Map successfully transferred
27276 Transferring rpc.bynumber...
27277 ypxfr: Exiting: Map successfully transferred
27278 Transferring rpc.byname...
27279 ypxfr: Exiting: Map successfully transferred
27280 Transferring protocols.byname...
27281 ypxfr: Exiting: Map successfully transferred
27282 Transferring master.passwd.byname...
27283 ypxfr: Exiting: Map successfully transferred
27284 Transferring networks.byname...
27285 ypxfr: Exiting: Map successfully transferred
27286 Transferring networks.byaddr...
27287 ypxfr: Exiting: Map successfully transferred
27288 Transferring netid.byname...
27289 ypxfr: Exiting: Map successfully transferred
27290 Transferring hosts.byaddr...
27291 ypxfr: Exiting: Map successfully transferred
27292 Transferring protocols.bynumber...
27293 ypxfr: Exiting: Map successfully transferred
27294 Transferring ypservers...
27295 ypxfr: Exiting: Map successfully transferred
27296 Transferring hosts.byname...
27297 ypxfr: Exiting: Map successfully transferred
27299 coltrane has been setup as an YP slave server without any errors.
27300 Don't forget to update map ypservers on ellington.
27302 You should now have a directory called /var/yp/test-domain. Copies of the
27303 NIS master server's maps should be in this directory. You will need to
27304 make sure that these stay updated. The following /etc/crontab entries on
27305 your slave servers should do the job:
27307 20 * * * * root /usr/libexec/ypxfr passwd.byname
27308 21 * * * * root /usr/libexec/ypxfr passwd.byuid
27310 These two lines force the slave to sync its maps with the maps on the
27311 master server. Although these entries are not mandatory, since the master
27312 server attempts to ensure any changes to its NIS maps are communicated to
27313 its slaves and because password information is vital to systems depending
27314 on the server, it is a good idea to force the updates. This is more
27315 important on busy networks where map updates might not always complete.
27317 Now, run the command /etc/netstart on the slave server as well, which
27318 again starts the NIS server.
27320 ----------------------------------------------------------------------
27322 19.9.4.3 NIS Clients
27324 An NIS client establishes what is called a binding to a particular NIS
27325 server using the ypbind daemon. ypbind checks the system's default domain
27326 (as set by the domainname command), and begins broadcasting RPC requests
27327 on the local network. These requests specify the name of the domain for
27328 which ypbind is attempting to establish a binding. If a server that has
27329 been configured to serve the requested domain receives one of the
27330 broadcasts, it will respond to ypbind, which will record the server's
27331 address. If there are several servers available (a master and several
27332 slaves, for example), ypbind will use the address of the first one to
27333 respond. From that point on, the client system will direct all of its NIS
27334 requests to that server. ypbind will occasionally ``ping'' the server to
27335 make sure it is still up and running. If it fails to receive a reply to
27336 one of its pings within a reasonable amount of time, ypbind will mark the
27337 domain as unbound and begin broadcasting again in the hopes of locating
27340 ----------------------------------------------------------------------
27342 19.9.4.3.1 Setting Up a NIS Client
27344 Setting up a DragonFly machine to be a NIS client is fairly
27347 1. Edit the file /etc/rc.conf and add the following lines in order to set
27348 the NIS domainname and start ypbind upon network startup:
27350 nisdomainname="test-domain"
27351 nis_client_enable="YES"
27353 2. To import all possible password entries from the NIS server, remove
27354 all user accounts from your /etc/master.passwd file and use vipw to
27355 add the following line to the end of the file:
27359 Note: This line will afford anyone with a valid account in the NIS
27360 server's password maps an account. There are many ways to configure
27361 your NIS client by changing this line. See the netgroups section
27362 below for more information. For more detailed reading see O'Reilly's
27363 book on Managing NFS and NIS.
27365 Note: You should keep at least one local account (i.e. not imported
27366 via NIS) in your /etc/master.passwd and this account should also be
27367 a member of the group wheel. If there is something wrong with NIS,
27368 this account can be used to log in remotely, become root, and fix
27371 3. To import all possible group entries from the NIS server, add this
27372 line to your /etc/group file:
27376 After completing these steps, you should be able to run ypcat passwd and
27377 see the NIS server's passwd map.
27379 ----------------------------------------------------------------------
27381 19.9.5 NIS Security
27383 In general, any remote user can issue an RPC to ypserv(8) and retrieve the
27384 contents of your NIS maps, provided the remote user knows your domainname.
27385 To prevent such unauthorized transactions, ypserv(8) supports a feature
27386 called securenets which can be used to restrict access to a given set of
27387 hosts. At startup, ypserv(8) will attempt to load the securenets
27388 information from a file called /var/yp/securenets.
27390 Note: This path varies depending on the path specified with the -p
27391 option. This file contains entries that consist of a network
27392 specification and a network mask separated by white space. Lines
27393 starting with ``#'' are considered to be comments. A sample securenets
27394 file might look like this:
27396 # allow connections from local host -- mandatory
27397 127.0.0.1 255.255.255.255
27398 # allow connections from any host
27399 # on the 192.168.128.0 network
27400 192.168.128.0 255.255.255.0
27401 # allow connections from any host
27402 # between 10.0.0.0 to 10.0.15.255
27403 # this includes the machines in the testlab
27404 10.0.0.0 255.255.240.0
27406 If ypserv(8) receives a request from an address that matches one of these
27407 rules, it will process the request normally. If the address fails to match
27408 a rule, the request will be ignored and a warning message will be logged.
27409 If the /var/yp/securenets file does not exist, ypserv will allow
27410 connections from any host.
27412 The ypserv program also has support for Wietse Venema's tcpwrapper
27413 package. This allows the administrator to use the tcpwrapper configuration
27414 files for access control instead of /var/yp/securenets.
27416 Note: While both of these access control mechanisms provide some
27417 security, they, like the privileged port test, are vulnerable to ``IP
27418 spoofing'' attacks. All NIS-related traffic should be blocked at your
27421 Servers using /var/yp/securenets may fail to serve legitimate NIS
27422 clients with archaic TCP/IP implementations. Some of these
27423 implementations set all host bits to zero when doing broadcasts and/or
27424 fail to observe the subnet mask when calculating the broadcast address.
27425 While some of these problems can be fixed by changing the client
27426 configuration, other problems may force the retirement of the client
27427 systems in question or the abandonment of /var/yp/securenets.
27429 Using /var/yp/securenets on a server with such an archaic implementation
27430 of TCP/IP is a really bad idea and will lead to loss of NIS
27431 functionality for large parts of your network.
27433 The use of the tcpwrapper package increases the latency of your NIS
27434 server. The additional delay may be long enough to cause timeouts in
27435 client programs, especially in busy networks or with slow NIS servers.
27436 If one or more of your client systems suffers from these symptoms, you
27437 should convert the client systems in question into NIS slave servers and
27438 force them to bind to themselves.
27440 ----------------------------------------------------------------------
27442 19.9.6 Barring Some Users from Logging On
27444 In our lab, there is a machine basie that is supposed to be a faculty only
27445 workstation. We do not want to take this machine out of the NIS domain,
27446 yet the passwd file on the master NIS server contains accounts for both
27447 faculty and students. What can we do?
27449 There is a way to bar specific users from logging on to a machine, even if
27450 they are present in the NIS database. To do this, all you must do is add
27451 -username to the end of the /etc/master.passwd file on the client machine,
27452 where username is the username of the user you wish to bar from logging
27453 in. This should preferably be done using vipw, since vipw will sanity
27454 check your changes to /etc/master.passwd, as well as automatically rebuild
27455 the password database when you finish editing. For example, if we wanted
27456 to bar user bill from logging on to basie we would:
27459 [add -bill to the end, exit]
27460 vipw: rebuilding the database...
27463 basie# cat /etc/master.passwd
27465 root:[password]:0:0::0:0:The super-user:/root:/bin/csh
27466 toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
27467 daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
27468 operator:*:2:5::0:0:System &:/:/sbin/nologin
27469 bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
27470 tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
27471 kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
27472 games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
27473 news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
27474 man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
27475 bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
27476 uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
27477 xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
27478 pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
27479 nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
27485 ----------------------------------------------------------------------
27487 19.9.7 Using Netgroups
27489 Contributed by Udo Erdelhoff.
27491 The method shown in the previous section works reasonably well if you need
27492 special rules for a very small number of users and/or machines. On larger
27493 networks, you will forget to bar some users from logging onto sensitive
27494 machines, or you may even have to modify each machine separately, thus
27495 losing the main benefit of NIS, centralized administration.
27497 The NIS developers' solution for this problem is called netgroups. Their
27498 purpose and semantics can be compared to the normal groups used by UNIX
27499 file systems. The main differences are the lack of a numeric id and the
27500 ability to define a netgroup by including both user accounts and other
27503 Netgroups were developed to handle large, complex networks with hundreds
27504 of users and machines. On one hand, this is a Good Thing if you are forced
27505 to deal with such a situation. On the other hand, this complexity makes it
27506 almost impossible to explain netgroups with really simple examples. The
27507 example used in the remainder of this section demonstrates this problem.
27509 Let us assume that your successful introduction of NIS in your laboratory
27510 caught your superiors' interest. Your next job is to extend your NIS
27511 domain to cover some of the other machines on campus. The two tables
27512 contain the names of the new users and new machines as well as brief
27513 descriptions of them.
27515 +----------------------------------------------------------------------+
27516 | User Name(s) | Description |
27517 |---------------------------+------------------------------------------|
27518 | alpha, beta | Normal employees of the IT department |
27519 |---------------------------+------------------------------------------|
27520 | charlie, delta | The new apprentices of the IT department |
27521 |---------------------------+------------------------------------------|
27522 | echo, foxtrott, golf, ... | Ordinary employees |
27523 |---------------------------+------------------------------------------|
27524 | able, baker, ... | The current interns |
27525 +----------------------------------------------------------------------+
27527 +------------------------------------------------------------------------+
27528 | Machine Name(s) | Description |
27529 |----------------------------+-------------------------------------------|
27530 | war, death, famine, | Your most important servers. Only the IT |
27531 | pollution | employees are allowed to log onto these |
27533 |----------------------------+-------------------------------------------|
27534 | pride, greed, envy, wrath, | Less important servers. All members of |
27535 | lust, sloth | the IT department are allowed to login |
27536 | | onto these machines. |
27537 |----------------------------+-------------------------------------------|
27538 | | Ordinary workstations. Only the real |
27539 | one, two, three, four, ... | employees are allowed to use these |
27541 |----------------------------+-------------------------------------------|
27542 | | A very old machine without any critical |
27543 | trashcan | data. Even the intern is allowed to use |
27545 +------------------------------------------------------------------------+
27547 If you tried to implement these restrictions by separately blocking each
27548 user, you would have to add one -user line to each system's passwd for
27549 each user who is not allowed to login onto that system. If you forget just
27550 one entry, you could be in trouble. It may be feasible to do this
27551 correctly during the initial setup, however you will eventually forget to
27552 add the lines for new users during day-to-day operations. After all,
27553 Murphy was an optimist.
27555 Handling this situation with netgroups offers several advantages. Each
27556 user need not be handled separately; you assign a user to one or more
27557 netgroups and allow or forbid logins for all members of the netgroup. If
27558 you add a new machine, you will only have to define login restrictions for
27559 netgroups. If a new user is added, you will only have to add the user to
27560 one or more netgroups. Those changes are independent of each other; no
27561 more ``for each combination of user and machine do...'' If your NIS setup
27562 is planned carefully, you will only have to modify exactly one central
27563 configuration file to grant or deny access to machines.
27565 The first step is the initialization of the NIS map netgroup. DragonFly's
27566 ypinit(8) does not create this map by default, but its NIS implementation
27567 will support it once it has been created. To create an empty map, simply
27570 ellington# vi /var/yp/netgroup
27572 and start adding content. For our example, we need at least four
27573 netgroups: IT employees, IT apprentices, normal employees and interns.
27575 IT_EMP (,alpha,test-domain) (,beta,test-domain)
27576 IT_APP (,charlie,test-domain) (,delta,test-domain)
27577 USERS (,echo,test-domain) (,foxtrott,test-domain) \
27578 (,golf,test-domain)
27579 INTERNS (,able,test-domain) (,baker,test-domain)
27581 IT_EMP, IT_APP etc. are the names of the netgroups. Each bracketed group
27582 adds one or more user accounts to it. The three fields inside a group are:
27584 1. The name of the host(s) where the following items are valid. If you do
27585 not specify a hostname, the entry is valid on all hosts. If you do
27586 specify a hostname, you will enter a realm of darkness, horror and
27589 2. The name of the account that belongs to this netgroup.
27591 3. The NIS domain for the account. You can import accounts from other NIS
27592 domains into your netgroup if you are one of the unlucky fellows with
27593 more than one NIS domain.
27595 Each of these fields can contain wildcards. See netgroup(5) for details.
27597 Note: Netgroup names longer than 8 characters should not be used,
27598 especially if you have machines running other operating systems within
27599 your NIS domain. The names are case sensitive; using capital letters for
27600 your netgroup names is an easy way to distinguish between user, machine
27601 and netgroup names.
27603 Some NIS clients (other than DragonFly) cannot handle netgroups with a
27604 large number of entries. For example, some older versions of SunOS start
27605 to cause trouble if a netgroup contains more than 15 entries. You can
27606 circumvent this limit by creating several sub-netgroups with 15 users or
27607 less and a real netgroup that consists of the sub-netgroups:
27609 BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...]
27610 BIGGRP2 (,joe16,domain) (,joe17,domain) [...]
27611 BIGGRP3 (,joe31,domain) (,joe32,domain)
27612 BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3
27614 You can repeat this process if you need more than 225 users within a
27617 Activating and distributing your new NIS map is easy:
27619 ellington# cd /var/yp
27622 This will generate the three NIS maps netgroup, netgroup.byhost and
27623 netgroup.byuser. Use ypcat(1) to check if your new NIS maps are available:
27625 ellington% ypcat -k netgroup
27626 ellington% ypcat -k netgroup.byhost
27627 ellington% ypcat -k netgroup.byuser
27629 The output of the first command should resemble the contents of
27630 /var/yp/netgroup. The second command will not produce output if you have
27631 not specified host-specific netgroups. The third command can be used to
27632 get the list of netgroups for a user.
27634 The client setup is quite simple. To configure the server war, you only
27635 have to start vipw(8) and replace the line
27643 Now, only the data for the users defined in the netgroup IT_EMP is
27644 imported into war's password database and only these users are allowed to
27647 Unfortunately, this limitation also applies to the ~ function of the shell
27648 and all routines converting between user names and numerical user IDs. In
27649 other words, cd ~user will not work, ls -l will show the numerical id
27650 instead of the username and find . -user joe -print will fail with ``No
27651 such user''. To fix this, you will have to import all user entries without
27652 allowing them to login onto your servers.
27654 This can be achieved by adding another line to /etc/master.passwd. This
27655 line should contain:
27657 +:::::::::/sbin/nologin, meaning ``Import all entries but replace the
27658 shell with /sbin/nologin in the imported entries''. You can replace any
27659 field in the passwd entry by placing a default value in your
27660 /etc/master.passwd.
27662 Warning: Make sure that the line +:::::::::/sbin/nologin is placed after
27663 +@IT_EMP:::::::::. Otherwise, all user accounts imported from NIS will
27664 have /sbin/nologin as their login shell.
27666 After this change, you will only have to change one NIS map if a new
27667 employee joins the IT department. You could use a similar approach for the
27668 less important servers by replacing the old +::::::::: in their local
27669 version of /etc/master.passwd with something like this:
27673 +:::::::::/sbin/nologin
27675 The corresponding lines for the normal workstations could be:
27679 +:::::::::/sbin/nologin
27681 And everything would be fine until there is a policy change a few weeks
27682 later: The IT department starts hiring interns. The IT interns are allowed
27683 to use the normal workstations and the less important servers; and the IT
27684 apprentices are allowed to login onto the main servers. You add a new
27685 netgroup IT_INTERN, add the new IT interns to this netgroup and start to
27686 change the config on each and every machine... As the old saying goes:
27687 ``Errors in centralized planning lead to global mess''.
27689 NIS' ability to create netgroups from other netgroups can be used to
27690 prevent situations like these. One possibility is the creation of
27691 role-based netgroups. For example, you could create a netgroup called
27692 BIGSRV to define the login restrictions for the important servers, another
27693 netgroup called SMALLSRV for the less important servers and a third
27694 netgroup called USERBOX for the normal workstations. Each of these
27695 netgroups contains the netgroups that are allowed to login onto these
27696 machines. The new entries for your NIS map netgroup should look like this:
27698 BIGSRV IT_EMP IT_APP
27699 SMALLSRV IT_EMP IT_APP ITINTERN
27700 USERBOX IT_EMP ITINTERN USERS
27702 This method of defining login restrictions works reasonably well if you
27703 can define groups of machines with identical restrictions. Unfortunately,
27704 this is the exception and not the rule. Most of the time, you will need
27705 the ability to define login restrictions on a per-machine basis.
27707 Machine-specific netgroup definitions are the other possibility to deal
27708 with the policy change outlined above. In this scenario, the
27709 /etc/master.passwd of each box contains two lines starting with ``+''. The
27710 first of them adds a netgroup with the accounts allowed to login onto this
27711 machine, the second one adds all other accounts with /sbin/nologin as
27712 shell. It is a good idea to use the ALL-CAPS version of the machine name
27713 as the name of the netgroup. In other words, the lines should look like
27717 +:::::::::/sbin/nologin
27719 Once you have completed this task for all your machines, you will not have
27720 to modify the local versions of /etc/master.passwd ever again. All further
27721 changes can be handled by modifying the NIS map. Here is an example of a
27722 possible netgroup map for this scenario with some additional goodies.
27724 # Define groups of users first
27725 IT_EMP (,alpha,test-domain) (,beta,test-domain)
27726 IT_APP (,charlie,test-domain) (,delta,test-domain)
27727 DEPT1 (,echo,test-domain) (,foxtrott,test-domain)
27728 DEPT2 (,golf,test-domain) (,hotel,test-domain)
27729 DEPT3 (,india,test-domain) (,juliet,test-domain)
27730 ITINTERN (,kilo,test-domain) (,lima,test-domain)
27731 D_INTERNS (,able,test-domain) (,baker,test-domain)
27733 # Now, define some groups based on roles
27734 USERS DEPT1 DEPT2 DEPT3
27735 BIGSRV IT_EMP IT_APP
27736 SMALLSRV IT_EMP IT_APP ITINTERN
27737 USERBOX IT_EMP ITINTERN USERS
27739 # And a groups for a special tasks
27740 # Allow echo and golf to access our anti-virus-machine
27741 SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain)
27743 # machine-based netgroups
27747 # User india needs access to this server
27748 POLLUTION BIGSRV (,india,test-domain)
27750 # This one is really important and needs more access restrictions
27753 # The anti-virus-machine mentioned above
27756 # Restrict a machine to a single user
27757 TWO (,hotel,test-domain)
27758 # [...more groups to follow]
27760 If you are using some kind of database to manage your user accounts, you
27761 should be able to create the first part of the map with your database's
27762 report tools. This way, new users will automatically have access to the
27765 One last word of caution: It may not always be advisable to use
27766 machine-based netgroups. If you are deploying a couple of dozen or even
27767 hundreds of identical machines for student labs, you should use role-based
27768 netgroups instead of machine-based netgroups to keep the size of the NIS
27769 map within reasonable limits.
27771 ----------------------------------------------------------------------
27773 19.9.8 Important Things to Remember
27775 There are still a couple of things that you will need to do differently
27776 now that you are in an NIS environment.
27778 * Every time you wish to add a user to the lab, you must add it to the
27779 master NIS server only, and you must remember to rebuild the NIS maps.
27780 If you forget to do this, the new user will not be able to login
27781 anywhere except on the NIS master. For example, if we needed to add a
27782 new user ``jsmith'' to the lab, we would:
27784 # pw useradd jsmith
27788 You could also run adduser jsmith instead of pw useradd jsmith.
27790 * Keep the administration accounts out of the NIS maps. You do not want
27791 to be propagating administrative accounts and passwords to machines
27792 that will have users that should not have access to those accounts.
27794 * Keep the NIS master and slave secure, and minimize their downtime. If
27795 somebody either hacks or simply turns off these machines, they have
27796 effectively rendered many people without the ability to login to the
27799 This is the chief weakness of any centralized administration system.
27800 If you do not protect your NIS servers, you will have a lot of angry
27803 ----------------------------------------------------------------------
27805 19.9.9 NIS v1 Compatibility
27807 DragonFly's ypserv has some support for serving NIS v1 clients.
27808 DragonFly's NIS implementation only uses the NIS v2 protocol, however
27809 other implementations include support for the v1 protocol for backwards
27810 compatibility with older systems. The ypbind daemons supplied with these
27811 systems will try to establish a binding to an NIS v1 server even though
27812 they may never actually need it (and they may persist in broadcasting in
27813 search of one even after they receive a response from a v2 server). Note
27814 that while support for normal client calls is provided, this version of
27815 ypserv does not handle v1 map transfer requests; consequently, it cannot
27816 be used as a master or slave in conjunction with older NIS servers that
27817 only support the v1 protocol. Fortunately, there probably are not any such
27818 servers still in use today.
27820 ----------------------------------------------------------------------
27822 19.9.10 NIS Servers That Are Also NIS Clients
27824 Care must be taken when running ypserv in a multi-server domain where the
27825 server machines are also NIS clients. It is generally a good idea to force
27826 the servers to bind to themselves rather than allowing them to broadcast
27827 bind requests and possibly become bound to each other. Strange failure
27828 modes can result if one server goes down and others are dependent upon it.
27829 Eventually all the clients will time out and attempt to bind to other
27830 servers, but the delay involved can be considerable and the failure mode
27831 is still present since the servers might bind to each other all over
27834 You can force a host to bind to a particular server by running ypbind with
27835 the -S flag. If you do not want to do this manually each time you reboot
27836 your NIS server, you can add the following lines to your /etc/rc.conf:
27838 nis_client_enable="YES" # run client stuff as well
27839 nis_client_flags="-S NIS domain,server"
27841 See ypbind(8) for further information.
27843 ----------------------------------------------------------------------
27845 19.9.11 Password Formats
27847 One of the most common issues that people run into when trying to
27848 implement NIS is password format compatibility. If your NIS server is
27849 using DES encrypted passwords, it will only support clients that are also
27850 using DES. For example, if you have Solaris NIS clients in your network,
27851 then you will almost certainly need to use DES encrypted passwords.
27853 To check which format your servers and clients are using, look at
27854 /etc/login.conf. If the host is configured to use DES encrypted passwords,
27855 then the default class will contain an entry like this:
27858 :passwd_format=des:\
27859 :copyright=/etc/COPYRIGHT:\
27860 [Further entries elided]
27862 Other possible values for the passwd_format capability include blf and md5
27863 (for Blowfish and MD5 encrypted passwords, respectively).
27865 If you have made changes to /etc/login.conf, you will also need to rebuild
27866 the login capability database, which is achieved by running the following
27869 # cap_mkdb /etc/login.conf
27871 Note: The format of passwords already in /etc/master.passwd will not be
27872 updated until a user changes their password for the first time after the
27873 login capability database is rebuilt.
27875 Next, in order to ensure that passwords are encrypted with the format that
27876 you have chosen, you should also check that the crypt_default in
27877 /etc/auth.conf gives precedence to your chosen password format. To do
27878 this, place the format that you have chosen first in the list. For
27879 example, when using DES encrypted passwords, the entry would be:
27881 crypt_default = des blf md5
27883 Having followed the above steps on each of the DragonFly based NIS servers
27884 and clients, you can be sure that they all agree on which password format
27885 is used within your network. If you have trouble authenticating on an NIS
27886 client, this is a pretty good place to start looking for possible
27887 problems. Remember: if you want to deploy an NIS server for a heterogenous
27888 network, you will probably have to use DES on all systems because it is
27889 the lowest common standard.
27891 ----------------------------------------------------------------------
27895 Written by Greg Sutter.
27897 19.10.1 What Is DHCP?
27899 DHCP, the Dynamic Host Configuration Protocol, describes the means by
27900 which a system can connect to a network and obtain the necessary
27901 information for communication upon that network. DragonFly uses the ISC
27902 (Internet Software Consortium) DHCP implementation, so all
27903 implementation-specific information here is for use with the ISC
27906 ----------------------------------------------------------------------
27908 19.10.2 What This Section Covers
27910 This section describes both the client-side and server-side components of
27911 the ISC DHCP system. The client-side program, dhclient, and the server,
27912 come integrated within DragonFly. The dhclient(8), dhcp-options(5), and
27913 dhclient.conf(5) manual pages, in addition to the references below, are
27916 ----------------------------------------------------------------------
27918 19.10.3 How It Works
27920 When dhclient, the DHCP client, is executed on the client machine, it
27921 begins broadcasting requests for configuration information. By default,
27922 these requests are on UDP port 68. The server replies on UDP 67, giving
27923 the client an IP address and other relevant network information such as
27924 netmask, router, and DNS servers. All of this information comes in the
27925 form of a DHCP ``lease'' and is only valid for a certain time (configured
27926 by the DHCP server maintainer). In this manner, stale IP addresses for
27927 clients no longer connected to the network can be automatically reclaimed.
27929 DHCP clients can obtain a great deal of information from the server. An
27930 exhaustive list may be found in dhcp-options(5).
27932 ----------------------------------------------------------------------
27934 19.10.4 DragonFly Integration
27936 DragonFly fully integrates the ISC DHCP client, dhclient. DHCP client
27937 support is provided within both the installer and the base system,
27938 obviating the need for detailed knowledge of network configurations on any
27939 network that runs a DHCP server.
27941 There are two things you must do to have your system use DHCP upon
27944 * Make sure that the bpf device is compiled into your kernel. To do
27945 this, add pseudo-device bpf to your kernel configuration file, and
27946 rebuild the kernel. For more information about building kernels, see
27949 The bpf device is already part of the GENERIC kernel that is supplied
27950 with DragonFly, so if you do not have a custom kernel, you should not
27951 need to create one in order to get DHCP working.
27953 Note: For those who are particularly security conscious, you should
27954 be warned that bpf is also the device that allows packet sniffers to
27955 work correctly (although they still have to be run as root). bpf is
27956 required to use DHCP, but if you are very sensitive about security,
27957 you probably should not add bpf to your kernel in the expectation
27958 that at some point in the future you will be using DHCP.
27960 * Edit your /etc/rc.conf to include the following:
27962 ifconfig_fxp0="DHCP"
27964 Note: Be sure to replace fxp0 with the designation for the interface
27965 that you wish to dynamically configure, as described in Section 6.8.
27967 If you are using a different location for dhclient, or if you wish to
27968 pass additional flags to dhclient, also include the following (editing
27971 dhcp_program="/sbin/dhclient"
27974 The DHCP server, dhcpd, is included as part of the net/isc-dhcp3-server
27975 port in the ports collection. This port contains the ISC DHCP server and
27978 ----------------------------------------------------------------------
27982 * /etc/dhclient.conf
27984 dhclient requires a configuration file, /etc/dhclient.conf. Typically
27985 the file contains only comments, the defaults being reasonably sane.
27986 This configuration file is described by the dhclient.conf(5) manual
27991 dhclient is statically linked and resides in /sbin. The dhclient(8)
27992 manual page gives more information about dhclient.
27994 * /sbin/dhclient-script
27996 dhclient-script is the DragonFly-specific DHCP client configuration
27997 script. It is described in dhclient-script(8), but should not need any
27998 user modification to function properly.
28000 * /var/db/dhclient.leases
28002 The DHCP client keeps a database of valid leases in this file, which
28003 is written as a log. dhclient.leases(5) gives a slightly longer
28006 ----------------------------------------------------------------------
28008 19.10.6 Further Reading
28010 The DHCP protocol is fully described in RFC 2131. An informational
28011 resource has also been set up at dhcp.org.
28013 ----------------------------------------------------------------------
28015 19.10.7 Installing and Configuring a DHCP Server
28017 19.10.7.1 What This Section Covers
28019 This section provides information on how to configure a DragonFly system
28020 to act as a DHCP server using the ISC (Internet Software Consortium)
28021 implementation of the DHCP suite.
28023 ----------------------------------------------------------------------
28025 19.10.7.2 DHCP Server Installation
28027 In order to configure your DragonFly system as a DHCP server, you will
28028 need to ensure that the bpf(4) device is compiled into your kernel. To do
28029 this, add pseudo-device bpf to your kernel configuration file, and rebuild
28030 the kernel. For more information about building kernels, see Chapter 9.
28032 The bpf device is already part of the GENERIC kernel that is supplied with
28033 DragonFly, so you do not need to create a custom kernel in order to get
28036 Note: Those who are particularly security conscious should note that bpf
28037 is also the device that allows packet sniffers to work correctly
28038 (although such programs still need privileged access). bpf is required
28039 to use DHCP, but if you are very sensitive about security, you probably
28040 should not include bpf in your kernel purely because you expect to use
28041 DHCP at some point in the future.
28043 The next thing that you will need to do is edit the sample dhcpd.conf
28044 which was installed by the net/isc-dhcp3-server port. By default, this
28045 will be /usr/local/etc/dhcpd.conf.sample, and you should copy this to
28046 /usr/local/etc/dhcpd.conf before proceeding to make changes.
28048 ----------------------------------------------------------------------
28050 19.10.7.3 Configuring the DHCP Server
28052 dhcpd.conf is comprised of declarations regarding subnets and hosts, and
28053 is perhaps most easily explained using an example :
28055 option domain-name "example.com";(1)
28056 option domain-name-servers 192.168.4.100;(2)
28057 option subnet-mask 255.255.255.0;(3)
28059 default-lease-time 3600;(4)
28060 max-lease-time 86400;(5)
28061 ddns-update-style none;(6)
28063 subnet 192.168.4.0 netmask 255.255.255.0 {
28064 range 192.168.4.129 192.168.4.254;(7)
28065 option routers 192.168.4.1;(8)
28069 hardware ethernet 02:03:04:05:06:07;(9)
28070 fixed-address mailhost.example.com;(10)
28074 This option specifies the domain that will be provided to clients
28075 as the default search domain. See resolv.conf(5) for more
28076 information on what this means.
28078 This option specifies a comma separated list of DNS servers that
28079 the client should use.
28081 The netmask that will be provided to clients.
28083 A client may request a specific length of time that a lease will
28084 be valid. Otherwise the server will assign a lease with this
28085 expiry value (in seconds).
28087 This is the maximum length of time that the server will lease for.
28088 Should a client request a longer lease, a lease will be issued,
28089 although it will only be valid for max-lease-time seconds.
28091 This option specifies whether the DHCP server should attempt to
28092 update DNS when a lease is accepted or released. In the ISC
28093 implementation, this option is required.
28095 This denotes which IP addresses should be used in the pool
28096 reserved for allocating to clients. IP addresses between, and
28097 including, the ones stated are handed out to clients.
28099 Declares the default gateway that will be provided to clients.
28101 The hardware MAC address of a host (so that the DHCP server can
28102 recognize a host when it makes a request).
28104 Specifies that the host should always be given the same IP
28105 address. Note that using a hostname is correct here, since the
28106 DHCP server will resolve the hostname itself before returning the
28109 Once you have finished writing your dhcpd.conf, you can proceed to start
28110 the server by issuing the following command:
28112 # /usr/local/etc/rc.d/isc-dhcpd.sh start
28114 Should you need to make changes to the configuration of your server in the
28115 future, it is important to note that sending a SIGHUP signal to dhcpd does
28116 not result in the configuration being reloaded, as it does with most
28117 daemons. You will need to send a SIGTERM signal to stop the process, and
28118 then restart it using the command above.
28120 ----------------------------------------------------------------------
28126 dhcpd is statically linked and resides in /usr/local/sbin. The
28127 dhcpd(8) manual page installed with the port gives more information
28132 dhcpd requires a configuration file, /usr/local/etc/dhcpd.conf before
28133 it will start providing service to clients. This file needs to contain
28134 all the information that should be provided to clients that are being
28135 serviced, along with information regarding the operation of the
28136 server. This configuration file is described by the dhcpd.conf(5)
28137 manual page installed by the port.
28139 * /var/db/dhcpd.leases
28141 The DHCP server keeps a database of leases it has issued in this file,
28142 which is written as a log. The manual page dhcpd.leases(5), installed
28143 by the port gives a slightly longer description.
28145 * /usr/sbin/dhcrelay
28147 dhcrelay is used in advanced environments where one DHCP server
28148 forwards a request from a client to another DHCP server on a separate
28151 ----------------------------------------------------------------------
28155 Contributed by Chern Lee.
28159 DragonFly utilizes, by default, a version of BIND (Berkeley Internet Name
28160 Domain), which is the most common implementation of the DNS protocol. DNS
28161 is the protocol through which names are mapped to IP addresses, and vice
28162 versa. For example, a query for www.dragonflybsd.org will receive a reply
28163 with the IP address of The DragonFly Project's web server, whereas, a
28164 query for ftp.dragonflybsd.org will return the IP address of the
28165 corresponding FTP machine. Likewise, the opposite can happen. A query for
28166 an IP address can resolve its hostname. It is not necessary to run a name
28167 server to perform DNS lookups on a system.
28169 DNS is coordinated across the Internet through a somewhat complex system
28170 of authoritative root name servers, and other smaller-scale name servers
28171 who host and cache individual domain information.
28173 This document refers to BIND 9.x.
28175 RFC1034 and RFC1035 dictate the DNS protocol.
28177 Currently, BIND is maintained by the Internet Software Consortium
28180 ----------------------------------------------------------------------
28182 19.11.2 Terminology
28184 To understand this document, some terms related to DNS must be understood.
28187 Forward DNS Mapping of hostnames to IP addresses
28188 Origin Refers to the domain covered in a particular zone
28190 named, BIND, name server Common names for the BIND name server package
28192 Resolver A system process through which a machine queries
28193 a name server for zone information
28194 Reverse DNS The opposite of forward DNS; mapping of IP
28195 addresses to hostnames
28196 The beginning of the Internet zone hierarchy. All
28197 Root zone zones fall under the root zone, similar to how
28198 all files in a file system fall under the root
28200 Zone An individual domain, subdomain, or portion of
28201 the DNS administered by the same authority
28205 * . is the root zone
28207 * org. is a zone under the root zone
28209 * example.org is a zone under the org. zone
28211 * foo.example.org. is a subdomain, a zone under the example.org. zone
28213 * 1.2.3.in-addr.arpa is a zone referencing all IP addresses which fall
28214 under the 3.2.1.* IP space.
28216 As one can see, the more specific part of a hostname appears to its left.
28217 For example, example.org. is more specific than org., as org. is more
28218 specific than the root zone. The layout of each part of a hostname is much
28219 like a filesystem: the /dev directory falls within the root, and so on.
28221 ----------------------------------------------------------------------
28223 19.11.3 Reasons to Run a Name Server
28225 Name servers usually come in two forms: an authoritative name server, and
28226 a caching name server.
28228 An authoritative name server is needed when:
28230 * one wants to serve DNS information to the world, replying
28231 authoritatively to queries.
28233 * a domain, such as example.org, is registered and IP addresses need to
28234 be assigned to hostnames under it.
28236 * an IP address block requires reverse DNS entries (IP to hostname).
28238 * a backup name server, called a slave, must reply to queries when the
28239 primary is down or inaccessible.
28241 A caching name server is needed when:
28243 * a local DNS server may cache and respond more quickly than querying an
28244 outside name server.
28246 * a reduction in overall network traffic is desired (DNS traffic has
28247 been measured to account for 5% or more of total Internet traffic).
28249 When one queries for www.dragonflybsd.org, the resolver usually queries
28250 the uplink ISP's name server, and retrieves the reply. With a local,
28251 caching DNS server, the query only has to be made once to the outside
28252 world by the caching DNS server. Every additional query will not have to
28253 look to the outside of the local network, since the information is cached
28256 ----------------------------------------------------------------------
28258 19.11.4 How It Works
28260 In DragonFly, the BIND daemon is called named for obvious reasons.
28263 named the BIND daemon
28264 ndc name daemon control program
28265 /etc/namedb directory where BIND zone information resides
28266 /etc/namedb/named.conf daemon configuration file
28268 Zone files are usually contained within the /etc/namedb directory, and
28269 contain the DNS zone information served by the name server.
28271 ----------------------------------------------------------------------
28273 19.11.5 Starting BIND
28275 Since BIND is installed by default, configuring it all is relatively
28278 To ensure the named daemon is started at boot, put the following
28279 modifications in /etc/rc.conf:
28283 To start the daemon manually (after configuring it)
28287 ----------------------------------------------------------------------
28289 19.11.6 Configuration Files
28291 ----------------------------------------------------------------------
28293 19.11.6.1 Using make-localhost
28298 # sh make-localhost
28300 to properly create the local reverse DNS zone file in
28301 /etc/namedb/localhost.rev.
28303 ----------------------------------------------------------------------
28305 19.11.6.2 /etc/namedb/named.conf
28307 // Refer to the named(8) manual page for details. If you are ever going
28308 // to setup a primary server, make sure you've understood the hairy
28309 // details of how DNS is working. Even with simple mistakes, you can
28310 // break connectivity for affected parties, or cause huge amount of
28311 // useless Internet traffic.
28314 directory "/etc/namedb";
28316 // In addition to the "forwarders" clause, you can force your name
28317 // server to never initiate queries of its own, but always ask its
28318 // forwarders only, by enabling the following line:
28322 // If you've got a DNS server around at your upstream provider, enter
28323 // its IP address here, and enable the line below. This will make you
28324 // benefit from its cache, thus reduce overall DNS traffic in the
28332 Just as the comment says, to benefit from an uplink's cache, forwarders
28333 can be enabled here. Under normal circumstances, a name server will
28334 recursively query the Internet looking at certain name servers until it
28335 finds the answer it is looking for. Having this enabled will have it query
28336 the uplink's name server (or name server provided) first, taking advantage
28337 of its cache. If the uplink name server in question is a heavily
28338 trafficked, fast name server, enabling this may be worthwhile.
28340 Warning: 127.0.0.1 will not work here. Change this IP address to a name
28341 server at your uplink.
28344 * If there is a firewall between you and name servers you want
28345 * to talk to, you might need to uncomment the query-source
28346 * directive below. Previous versions of BIND always asked
28347 * questions using port 53, but BIND 8.1 uses an unprivileged
28350 // query-source address * port 53;
28353 * If running in a sandbox, you may have to specify a different
28354 * location for the dumpfile.
28356 // dump-file "s/named_dump.db";
28359 // Note: the following will be supported in a future release.
28368 // Setting up secondaries is way easier and the rough picture for this
28369 // is explained below.
28371 // If you enable a local name server, don't forget to enter 127.0.0.1
28372 // into your /etc/resolv.conf so this server will be queried first.
28373 // Also, make sure to enable it in /etc/rc.conf.
28380 zone "0.0.127.IN-ADDR.ARPA" {
28382 file "localhost.rev";
28386 "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" {
28388 file "localhost.rev";
28391 // NB: Do not use the IP addresses below, they are faked, and only
28392 // serve demonstration/documentation purposes!
28394 // Example secondary config entries. It can be convenient to become
28395 // a secondary at least for the zone where your own domain is in. Ask
28396 // your network administrator for the IP address of the responsible
28399 // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
28400 // (This is the first bytes of the respective IP address, in reverse
28401 // order, with ".IN-ADDR.ARPA" appended.)
28403 // Before starting to setup a primary zone, better make sure you fully
28404 // understand how DNS and BIND works, however. There are sometimes
28405 // unobvious pitfalls. Setting up a secondary is comparably simpler.
28407 // NB: Don't blindly enable the examples below. :-) Use actual names
28408 // and addresses instead.
28410 // NOTE!!! DragonFly runs bind in a sandbox (see named_flags in rc.conf).
28411 // The directory containing the secondary zones must be write accessible
28412 // to bind. The following sequence is suggested:
28414 // mkdir /etc/namedb/s
28415 // chown bind:bind /etc/namedb/s
28416 // chmod 750 /etc/namedb/s
28418 For more information on running BIND in a sandbox, see Running named in a
28422 zone "example.com" {
28424 file "s/example.com.bak";
28430 zone "0.168.192.in-addr.arpa" {
28432 file "s/0.168.192.in-addr.arpa.bak";
28439 In named.conf, these are examples of slave entries for a forward and
28442 For each new zone served, a new zone entry must be added to named.conf
28444 For example, the simplest zone entry for example.org can look like:
28446 zone "example.org" {
28448 file "example.org";
28451 The zone is a master, as indicated by the type statement, holding its zone
28452 information in /etc/namedb/example.org indicated by the file statement.
28454 zone "example.org" {
28456 file "example.org";
28459 In the slave case, the zone information is transferred from the master
28460 name server for the particular zone, and saved in the file specified. If
28461 and when the master server dies or is unreachable, the slave name server
28462 will have the transferred zone information and will be able to serve it.
28464 ----------------------------------------------------------------------
28466 19.11.6.3 Zone Files
28468 An example master zone file for example.org (existing within
28469 /etc/namedb/example.org) is as follows:
28473 example.org. IN SOA ns1.example.org. admin.example.org. (
28478 86400 ) ; Minimum TTL
28481 @ IN NS ns1.example.org.
28482 @ IN NS ns2.example.org.
28485 localhost IN A 127.0.0.1
28495 @ IN MX 10 mail.example.org.
28497 Note that every hostname ending in a ``.'' is an exact hostname, whereas
28498 everything without a trailing ``.'' is referenced to the origin. For
28499 example, www is translated into www + origin. In our fictitious zone file,
28500 our origin is example.org., so www would translate to www.example.org.
28502 The format of a zone file follows:
28504 recordname IN recordtype value
28506 The most commonly used DNS records:
28510 start of zone authority
28514 an authoritative name server
28522 the canonical name for an alias
28530 a domain name pointer (used in reverse DNS)
28532 example.org. IN SOA ns1.example.org. admin.example.org. (
28534 10800 ; Refresh after 3 hours
28535 3600 ; Retry after 1 hour
28536 604800 ; Expire after 1 week
28537 86400 ) ; Minimum TTL of 1 day
28541 the domain name, also the origin for this zone file.
28545 the primary/authoritative name server for this zone
28549 the responsible person for this zone, email address with @
28550 replaced. (<admin@example.org> becomes admin.example.org)
28554 the serial number of the file. this must be incremented each time
28555 the zone file is modified. Nowadays, many admins prefer a
28556 yyyymmddrr format for the serial number. 2001041002 would mean
28557 last modified 04/10/2001, the latter 02 being the second time the
28558 zone file has been modified this day. The serial number is
28559 important as it alerts slave name servers for a zone when it is
28562 @ IN NS ns1.example.org.
28564 This is an NS entry. Every name server that is going to reply
28565 authoritatively for the zone must have one of these entries. The @ as seen
28566 here could have been example.org. The @ translates to the origin.
28568 localhost IN A 127.0.0.1
28574 The A record indicates machine names. As seen above, ns1.example.org would
28575 resolve to 3.2.1.2. Again, the origin symbol, @, is used here, thus
28576 meaning example.org would resolve to 3.2.1.30.
28580 The canonical name record is usually used for giving aliases to a machine.
28581 In the example, www is aliased to the machine addressed to the origin, or
28582 example.org (3.2.1.30). CNAMEs can be used to provide alias hostnames, or
28583 round robin one hostname among multiple machines.
28585 @ IN MX 10 mail.example.org.
28587 The MX record indicates which mail servers are responsible for handling
28588 incoming mail for the zone. mail.example.org is the hostname of the mail
28589 server, and 10 being the priority of that mail server.
28591 One can have several mail servers, with priorities of 3, 2, 1. A mail
28592 server attempting to deliver to example.org would first try the highest
28593 priority MX, then the second highest, etc, until the mail can be properly
28596 For in-addr.arpa zone files (reverse DNS), the same format is used, except
28597 with PTR entries instead of A or CNAME.
28601 1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
28608 @ IN NS ns1.example.org.
28609 @ IN NS ns2.example.org.
28611 2 IN PTR ns1.example.org.
28612 3 IN PTR ns2.example.org.
28613 10 IN PTR mail.example.org.
28614 30 IN PTR example.org.
28616 This file gives the proper IP address to hostname mappings of our above
28619 ----------------------------------------------------------------------
28621 19.11.7 Caching Name Server
28623 A caching name server is a name server that is not authoritative for any
28624 zones. It simply asks queries of its own, and remembers them for later
28625 use. To set one up, just configure the name server as usual, omitting any
28626 inclusions of zones.
28628 ----------------------------------------------------------------------
28630 19.11.8 Running named in a Sandbox
28632 For added security you may want to run named(8) as an unprivileged user,
28633 and configure it to chroot(8) into a sandbox directory. This makes
28634 everything outside of the sandbox inaccessible to the named daemon. Should
28635 named be compromised, this will help to reduce the damage that can be
28636 caused. By default, DragonFly has a user and a group called bind, intended
28639 Note: Various people would recommend that instead of configuring named
28640 to chroot, you should run named inside a jail(8). This section does not
28641 attempt to cover this situation.
28643 Since named will not be able to access anything outside of the sandbox
28644 (such as shared libraries, log sockets, and so on), there are a number of
28645 steps that need to be followed in order to allow named to function
28646 correctly. In the following checklist, it is assumed that the path to the
28647 sandbox is /etc/namedb and that you have made no prior modifications to
28648 the contents of this directory. Perform the following steps as root.
28650 * Create all directories that named expects to see:
28653 # mkdir -p bin dev etc var/tmp var/run master slave
28654 # chown bind:bind slave var/*(1)
28657 named only needs write access to these directories, so
28658 that is all we give it.
28659 * Rearrange and create basic zone and configuration files:
28661 # cp /etc/localtime etc(1)
28662 # mv named.conf etc && ln -sf etc/named.conf
28663 # mv named.root master
28664 # sh make-localhost && mv localhost.rev localhost-v6.rev master
28665 # cat > master/named.localhost
28668 @ IN SOA localhost. postmaster.localhost. (
28672 604800 ; expiration
28679 This allows named to log the correct time to syslogd(8)
28680 * Use cp(1) to copy named-xfer in /usr/libexec into your sandbox.
28682 * Make a dev/null that named can see and write to:
28684 # cd /etc/namedb/dev && mknod null c 2 2
28687 * Symlink /var/run/ndc to /etc/namedb/var/run/ndc:
28689 # ln -sf /etc/namedb/var/run/ndc /var/run/ndc
28691 Note: This simply avoids having to specify the -c option to ndc(8)
28692 every time you run it. Since the contents of /var/run are deleted on
28693 boot, if this is something that you find useful you may wish to add
28694 this command to root's crontab, making use of the @reboot option.
28695 See crontab(5) for more information regarding this.
28697 * Configure syslogd(8) to create an extra log socket that named can
28698 write to. To do this, add -l /etc/namedb/dev/log to the syslogd_flags
28699 variable in /etc/rc.conf.
28701 * Arrange to have named start and chroot itself to the sandbox by adding
28702 the following to /etc/rc.conf:
28705 named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"
28707 Note: Note that the configuration file /etc/named.conf is denoted by
28708 a full pathname relative to the sandbox, i.e. in the line above, the
28709 file referred to is actually /etc/namedb/etc/named.conf.
28711 The next step is to edit /etc/namedb/etc/named.conf so that named knows
28712 which zones to load and where to find them on the disk. There follows a
28713 commented example (anything not specifically commented here is no
28714 different from the setup for a DNS server not running in a sandbox):
28718 named-xfer "/bin/named-xfer";(2)
28719 version ""; // Don't reveal BIND version
28720 query-source address * port 53;
28722 // ndc control socket
28724 unix "/var/run/ndc" perm 0600 owner 0 group 0;
28727 zone "localhost" IN {
28729 file "master/named.localhost";(3)
28730 allow-transfer { localhost; };
28733 zone "0.0.127.in-addr.arpa" IN {
28735 file "master/localhost.rev";
28736 allow-transfer { localhost; };
28739 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" {
28741 file "master/localhost-v6.rev";
28742 allow-transfer { localhost; };
28747 file "master/named.root";
28749 zone "private.example.net" in {
28751 file "master/private.example.net.db";
28752 allow-transfer { 192.168.10.0/24; };
28754 zone "10.168.192.in-addr.arpa" in {
28756 masters { 192.168.10.2; };
28757 file "slave/192.168.10.db";(4)
28761 The directory statement is specified as /, since all files that
28762 named needs are within this directory (recall that this is
28763 equivalent to a ``normal'' user's /etc/namedb.
28765 Specifies the full path to the named-xfer binary (from named's
28766 frame of reference). This is necessary since named is compiled to
28767 look for named-xfer in /usr/libexec by default.
28769 Specifies the filename (relative to the directory statement above)
28770 where named can find the zonefile for this zone.
28772 Specifies the filename (relative to the directory statement above)
28773 where named should write a copy of the zonefile for this zone
28774 after successfully transferring it from the master server. This is
28775 why we needed to change the ownership of the directory slave to
28776 bind in the setup stages above.
28778 After completing the steps above, either reboot your server or restart
28779 syslogd(8) and start named(8), making sure to use the new options
28780 specified in syslogd_flags and named_flags. You should now be running a
28781 sandboxed copy of named!
28783 ----------------------------------------------------------------------
28787 Although BIND is the most common implementation of DNS, there is always
28788 the issue of security. Possible and exploitable security holes are
28791 It is a good idea to subscribe to CERT and freebsd-security-notifications
28792 to stay up to date with the current Internet and FreeBSD security issues.
28794 Tip: If a problem arises, keeping sources up to date and having a fresh
28795 build of named would not hurt.
28797 ----------------------------------------------------------------------
28799 19.11.10 Further Reading
28801 BIND/named manual pages: ndc(8) named(8) named.conf(5)
28803 * Official ISC Bind Page
28807 * O'Reilly DNS and BIND 4th Edition
28809 * RFC1034 - Domain Names - Concepts and Facilities
28811 * RFC1035 - Domain Names - Implementation and Specification
28813 ----------------------------------------------------------------------
28817 Contributed by Tom Hukins.
28819 ----------------------------------------------------------------------
28823 Over time, a computer's clock is prone to drift. As time passes, the
28824 computer's clock becomes less accurate. NTP (Network Time Protocol) is one
28825 way to ensure your clock is right.
28827 Many Internet services rely on, or greatly benefit from, computers' clocks
28828 being accurate. For example, a Web server may receive requests to send a
28829 file if it has modified since a certain time. Services such as cron(8) run
28830 commands at a given time. If the clock is inaccurate, these commands may
28831 not run when expected.
28833 DragonFly ships with the ntpd(8) NTP server which can be used to query
28834 other NTP servers to set the clock on your machine or provide time
28835 services to others.
28837 ----------------------------------------------------------------------
28839 19.12.2 Choosing Appropriate NTP Servers
28841 In order to synchronize your clock, you will need to find one or more NTP
28842 servers to use. Your network administrator or ISP may have set up an NTP
28843 server for this purpose--check their documentation to see if this is the
28844 case. There is a list of publicly accessible NTP servers which you can use
28845 to find an NTP server near to you. Make sure you are aware of the policy
28846 for any servers you choose, and ask for permission if required.
28848 Choosing several unconnected NTP servers is a good idea in case one of the
28849 servers you are using becomes unreachable or its clock is unreliable.
28850 ntpd(8) uses the responses it receives from other servers
28851 intelligently--it will favor unreliable servers less than reliable ones.
28853 ----------------------------------------------------------------------
28855 19.12.3 Configuring Your Machine
28857 ----------------------------------------------------------------------
28859 19.12.3.1 Basic Configuration
28861 If you only wish to synchronize your clock when the machine boots up, you
28862 can use ntpdate(8). This may be appropriate for some desktop machines
28863 which are frequently rebooted and only require infrequent synchronization,
28864 but most machines should run ntpd(8).
28866 Using ntpdate(8) at boot time is also a good idea for machines that run
28867 ntpd(8). The ntpd(8) program changes the clock gradually, whereas
28868 ntpdate(8) sets the clock, no matter how great the difference between a
28869 machine's current clock setting and the correct time.
28871 To enable ntpdate(8) at boot time, add ntpdate_enable="YES" to
28872 /etc/rc.conf. You will also need to specify all servers you wish to
28873 synchronize with and any flags to be passed to ntpdate(8) in
28876 ----------------------------------------------------------------------
28878 19.12.3.2 General Configuration
28880 NTP is configured by the /etc/ntp.conf file in the format described in
28881 ntp.conf(5). Here is a simple example:
28883 server ntplocal.example.com prefer
28884 server timeserver.example.org
28885 server ntp2a.example.net
28887 driftfile /var/db/ntp.drift
28889 The server option specifies which servers are to be used, with one server
28890 listed on each line. If a server is specified with the prefer argument, as
28891 with ntplocal.example.com, that server is preferred over other servers. A
28892 response from a preferred server will be discarded if it differs
28893 significantly from other servers' responses, otherwise it will be used
28894 without any consideration to other responses. The prefer argument is
28895 normally used for NTP servers that are known to be highly accurate, such
28896 as those with special time monitoring hardware.
28898 The driftfile option specifies which file is used to store the system
28899 clock's frequency offset. The ntpd(8) program uses this to automatically
28900 compensate for the clock's natural drift, allowing it to maintain a
28901 reasonably correct setting even if it is cut off from all external time
28902 sources for a period of time.
28904 The driftfile option specifies which file is used to store information
28905 about previous responses from the NTP servers you are using. This file
28906 contains internal information for NTP. It should not be modified by any
28909 ----------------------------------------------------------------------
28911 19.12.3.3 Controlling Access to Your Server
28913 By default, your NTP server will be accessible to all hosts on the
28914 Internet. The restrict option in /etc/ntp.conf allows you to control which
28915 machines can access your server.
28917 If you want to deny all machines from accessing your NTP server, add the
28918 following line to /etc/ntp.conf:
28920 restrict default ignore
28922 If you only want to allow machines within your own network to synchronize
28923 their clocks with your server, but ensure they are not allowed to
28924 configure the server or used as peers to synchronize against, add
28926 restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap
28928 instead, where 192.168.1.0 is an IP address on your network and
28929 255.255.255.0 is your network's netmask.
28931 /etc/ntp.conf can contain multiple restrict options. For more details, see
28932 the Access Control Support subsection of ntp.conf(5).
28934 ----------------------------------------------------------------------
28936 19.12.4 Running the NTP Server
28938 To ensure the NTP server is started at boot time, add the line
28939 xntpd_enable="YES" to /etc/rc.conf. If you wish to pass additional flags
28940 to ntpd(8), edit the xntpd_flags parameter in /etc/rc.conf.
28942 To start the server without rebooting your machine, run ntpd being sure to
28943 specify any additional parameters from xntpd_flags in /etc/rc.conf. For
28946 # ntpd -p /var/run/ntpd.pid
28948 ----------------------------------------------------------------------
28950 19.12.5 Using ntpd with a Temporary Internet Connection
28952 The ntpd(8) program does not need a permanent connection to the Internet
28953 to function properly. However, if you have a temporary connection that is
28954 configured to dial out on demand, it is a good idea to prevent NTP traffic
28955 from triggering a dial out or keeping the connection alive. If you are
28956 using user PPP, you can use filter directives in /etc/ppp/ppp.conf. For
28959 set filter dial 0 deny udp src eq 123
28960 # Prevent NTP traffic from initiating dial out
28961 set filter dial 1 permit 0 0
28962 set filter alive 0 deny udp src eq 123
28963 # Prevent incoming NTP traffic from keeping the connection open
28964 set filter alive 1 deny udp dst eq 123
28965 # Prevent outgoing NTP traffic from keeping the connection open
28966 set filter alive 2 permit 0/0 0/0
28968 For more details see the PACKET FILTERING section in ppp(8) and the
28969 examples in /usr/share/examples/ppp/.
28971 Note: Some Internet access providers block low-numbered ports,
28972 preventing NTP from functioning since replies never reach your machine.
28974 ----------------------------------------------------------------------
28976 19.12.6 Further Information
28978 Documentation for the NTP server can be found in /usr/share/doc/ntp/ in
28981 ----------------------------------------------------------------------
28983 19.13 Network Address Translation
28985 Contributed by Chern Lee.
28989 DragonFly's Network Address Translation daemon, commonly known as natd(8)
28990 is a daemon that accepts incoming raw IP packets, changes the source to
28991 the local machine and re-injects these packets back into the outgoing IP
28992 packet stream. natd(8) does this by changing the source IP address and
28993 port such that when data is received back, it is able to determine the
28994 original location of the data and forward it back to its original
28997 The most common use of NAT is to perform what is commonly known as
28998 Internet Connection Sharing.
29000 ----------------------------------------------------------------------
29004 Due to the diminishing IP space in IPv4, and the increased number of users
29005 on high-speed consumer lines such as cable or DSL, people are increasingly
29006 in need of an Internet Connection Sharing solution. The ability to connect
29007 several computers online through one connection and IP address makes
29008 natd(8) a reasonable choice.
29010 Most commonly, a user has a machine connected to a cable or DSL line with
29011 one IP address and wishes to use this one connected computer to provide
29012 Internet access to several more over a LAN.
29014 To do this, the DragonFly machine on the Internet must act as a gateway.
29015 This gateway machine must have two NICs--one for connecting to the
29016 Internet router, the other connecting to a LAN. All the machines on the
29017 LAN are connected through a hub or switch.
29019 _______ __________ ________
29021 | Hub |-----| Client B |-----| Router |----- Internet
29022 |_______| |__________| |________|
29029 A setup like this is commonly used to share an Internet connection. One of
29030 the LAN machines is connected to the Internet. The rest of the machines
29031 access the Internet through that ``gateway'' machine.
29033 ----------------------------------------------------------------------
29035 19.13.3 Configuration
29037 The following options must be in the kernel configuration file:
29042 Additionally, at choice, the following may also be suitable:
29044 options IPFIREWALL_DEFAULT_TO_ACCEPT
29045 options IPFIREWALL_VERBOSE
29047 The following must be in /etc/rc.conf:
29049 gateway_enable="YES"
29050 firewall_enable="YES"
29051 firewall_type="OPEN"
29053 natd_interface="fxp0"
29056 Sets up the machine to act as a gateway. Running
29057 gateway_enable="YES" sysctl net.inet.ip.forwarding=1 would have the same
29059 firewall_enable="YES" Enables the firewall rules in /etc/rc.firewall at
29061 This specifies a predefined firewall ruleset that
29062 firewall_type="OPEN" allows anything in. See /etc/rc.firewall for
29064 natd_interface="fxp0" Indicates which interface to forward packets through
29065 (the interface connected to the Internet).
29066 natd_flags="" Any additional configuration options passed to
29069 Having the previous options defined in /etc/rc.conf would run natd
29070 -interface fxp0 at boot. This can also be run manually.
29072 Note: It is also possible to use a configuration file for natd(8) when
29073 there are too many options to pass. In this case, the configuration file
29074 must be defined by adding the following line to /etc/rc.conf:
29076 natd_flags="-f /etc/natd.conf"
29078 The /etc/natd.conf file will contain a list of configuration options,
29079 one per line. For example the next section case would use the following
29082 redirect_port tcp 192.168.0.2:6667 6667
29083 redirect_port tcp 192.168.0.3:80 80
29085 For more information about the configuration file, consult the natd(8)
29086 manual page about the -f option.
29088 Each machine and interface behind the LAN should be assigned IP address
29089 numbers in the private network space as defined by RFC 1918 and have a
29090 default gateway of the natd machine's internal IP address.
29092 For example, client A and B behind the LAN have IP addresses of
29093 192.168.0.2 and 192.168.0.3, while the natd machine's LAN interface has an
29094 IP address of 192.168.0.1. Client A and B's default gateway must be set to
29095 that of the natd machine, 192.168.0.1. The natd machine's external, or
29096 Internet interface does not require any special modification for natd(8)
29099 ----------------------------------------------------------------------
29101 19.13.4 Port Redirection
29103 The drawback with natd(8) is that the LAN clients are not accessible from
29104 the Internet. Clients on the LAN can make outgoing connections to the
29105 world but cannot receive incoming ones. This presents a problem if trying
29106 to run Internet services on one of the LAN client machines. A simple way
29107 around this is to redirect selected Internet ports on the natd machine to
29110 For example, an IRC server runs on client A, and a web server runs on
29111 client B. For this to work properly, connections received on ports 6667
29112 (IRC) and 80 (web) must be redirected to the respective machines.
29114 The -redirect_port must be passed to natd(8) with the proper options. The
29115 syntax is as follows:
29117 -redirect_port proto targetIP:targetPORT[-targetPORT]
29118 [aliasIP:]aliasPORT[-aliasPORT]
29119 [remoteIP[:remotePORT[-remotePORT]]]
29121 In the above example, the argument should be:
29123 -redirect_port tcp 192.168.0.2:6667 6667
29124 -redirect_port tcp 192.168.0.3:80 80
29126 This will redirect the proper tcp ports to the LAN client machines.
29128 The -redirect_port argument can be used to indicate port ranges over
29129 individual ports. For example, tcp 192.168.0.2:2000-3000 2000-3000 would
29130 redirect all connections received on ports 2000 to 3000 to ports 2000 to
29133 These options can be used when directly running natd(8), placed within the
29134 natd_flags="" option in /etc/rc.conf, or passed via a configuration file.
29136 For further configuration options, consult natd(8)
29138 ----------------------------------------------------------------------
29140 19.13.5 Address Redirection
29142 Address redirection is useful if several IP addresses are available, yet
29143 they must be on one machine. With this, natd(8) can assign each LAN client
29144 its own external IP address. natd(8) then rewrites outgoing packets from
29145 the LAN clients with the proper external IP address and redirects all
29146 traffic incoming on that particular IP address back to the specific LAN
29147 client. This is also known as static NAT. For example, the IP addresses
29148 128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway machine.
29149 128.1.1.1 can be used as the natd gateway machine's external IP address,
29150 while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN clients A and B.
29152 The -redirect_address syntax is as follows:
29154 -redirect_address localIP publicIP
29156 localIP The internal IP address of the LAN client.
29157 publicIP The external IP address corresponding to the LAN client.
29159 In the example, this argument would read:
29161 -redirect_address 192.168.0.2 128.1.1.2
29162 -redirect_address 192.168.0.3 128.1.1.3
29164 Like -redirect_port, these arguments are also placed within the
29165 natd_flags="" option of /etc/rc.conf, or passed via a configuration file.
29166 With address redirection, there is no need for port redirection since all
29167 data received on a particular IP address is redirected.
29169 The external IP addresses on the natd machine must be active and aliased
29170 to the external interface. Look at rc.conf(5) to do so.
29172 ----------------------------------------------------------------------
29174 19.14 The inetd ``Super-Server''
29176 Contributed by Chern Lee.
29180 inetd(8) is referred to as the ``Internet Super-Server'' because it
29181 manages connections for several daemons. Programs that provide network
29182 service are commonly known as daemons. inetd serves as a managing server
29183 for other daemons. When a connection is received by inetd, it determines
29184 which daemon the connection is destined for, spawns the particular daemon
29185 and delegates the socket to it. Running one instance of inetd reduces the
29186 overall system load as compared to running each daemon individually in
29189 Primarily, inetd is used to spawn other daemons, but several trivial
29190 protocols are handled directly, such as chargen, auth, and daytime.
29192 This section will cover the basics in configuring inetd through its
29193 command-line options and its configuration file, /etc/inetd.conf.
29195 ----------------------------------------------------------------------
29199 inetd is initialized through the /etc/rc.conf system. The inetd_enable
29200 option is set to NO by default. Placing:
29208 into /etc/rc.conf can enable or disable inetd starting at boot time.
29210 Additionally, different command-line options can be passed to inetd via
29211 the inetd_flags option.
29213 ----------------------------------------------------------------------
29215 19.14.3 Command-Line Options
29219 inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
29220 [-p filename] [-R rate] [configuration file]
29228 Turn on logging of successful connections.
29232 Turn on TCP Wrapping for external services (on by default).
29236 Turn on TCP Wrapping for internal services which are built into
29237 inetd (on by default).
29241 Specify the default maximum number of simultaneous invocations of
29242 each service; the default is unlimited. May be overridden on a
29243 per-service basis with the max-child parameter.
29247 Specify the default maximum number of times a service can be
29248 invoked from a single IP address in one minute; the default is
29249 unlimited. May be overridden on a per-service basis with the
29250 max-connections-per-ip-per-minute parameter.
29254 Specify the maximum number of times a service can be invoked in
29255 one minute; the default is 256. A rate of 0 allows an unlimited
29256 number of invocations.
29260 Specify one specific IP address to bind to. Alternatively, a
29261 hostname can be specified, in which case the IPv4 or IPv6 address
29262 which corresponds to that hostname is used. Usually a hostname is
29263 specified when inetd is run inside a jail(8), in which case the
29264 hostname corresponds to the jail(8) environment.
29266 When hostname specification is used and both IPv4 and IPv6
29267 bindings are desired, one entry with the appropriate protocol type
29268 for each binding is required for each service in /etc/inetd.conf.
29269 For example, a TCP-based service would need two entries, one using
29270 tcp4 for the protocol and the other using tcp6.
29274 Specify an alternate file in which to store the process ID.
29276 These options can be passed to inetd using the inetd_flags option in
29277 /etc/rc.conf. By default, inetd_flags is set to -wW, which turns on TCP
29278 wrapping for inetd's internal and external services. For novice users,
29279 these parameters usually do not need to be modified or even entered in
29282 Note: An external service is a daemon outside of inetd, which is invoked
29283 when a connection is received for it. On the other hand, an internal
29284 service is one that inetd has the facility of offering within itself.
29286 ----------------------------------------------------------------------
29290 Configuration of inetd is controlled through the /etc/inetd.conf file.
29292 When a modification is made to /etc/inetd.conf, inetd can be forced to
29293 re-read its configuration file by sending a HangUP signal to the inetd
29296 Example 19-4. Sending inetd a HangUP Signal
29298 # kill -HUP `cat /var/run/inetd.pid`
29300 Each line of the configuration file specifies an individual daemon.
29301 Comments in the file are preceded by a ``#''. The format of
29302 /etc/inetd.conf is as follows:
29307 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
29308 user[:group][/login-class]
29310 server-program-arguments
29312 An example entry for the ftpd daemon using IPv4:
29314 ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
29318 This is the service name of the particular daemon. It must
29319 correspond to a service listed in /etc/services. This determines
29320 which port inetd must listen to. If a new service is being
29321 created, it must be placed in /etc/services first.
29325 Either stream, dgram, raw, or seqpacket. stream must be used for
29326 connection-based, TCP daemons, while dgram is used for daemons
29327 utilizing the UDP transport protocol.
29331 One of the following:
29333 +----------------------------------+
29334 | Protocol | Explanation |
29335 |-----------+----------------------|
29336 | tcp, tcp4 | TCP IPv4 |
29337 |-----------+----------------------|
29338 | udp, udp4 | UDP IPv4 |
29339 |-----------+----------------------|
29340 | tcp6 | TCP IPv6 |
29341 |-----------+----------------------|
29342 | udp6 | UDP IPv6 |
29343 |-----------+----------------------|
29344 | tcp46 | Both TCP IPv4 and v6 |
29345 |-----------+----------------------|
29346 | udp46 | Both UDP IPv4 and v6 |
29347 +----------------------------------+
29349 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
29351 wait|nowait indicates whether the daemon invoked from inetd is
29352 able to handle its own socket or not. dgram socket types must use
29353 the wait option, while stream socket daemons, which are usually
29354 multi-threaded, should use nowait. wait usually hands off multiple
29355 sockets to a single daemon, while nowait spawns a child daemon for
29358 The maximum number of child daemons inetd may spawn can be set
29359 using the max-child option. If a limit of ten instances of a
29360 particular daemon is needed, a /10 would be placed after nowait.
29362 In addition to max-child, another option limiting the maximum
29363 connections from a single place to a particular daemon can be
29364 enabled. max-connections-per-ip-per-minute does just this. A value
29365 of ten here would limit any particular IP address connecting to a
29366 particular service to ten attempts per minute. This is useful to
29367 prevent intentional or unintentional resource consumption and
29368 Denial of Service (DoS) attacks to a machine.
29370 In this field, wait or nowait is mandatory. max-child and
29371 max-connections-per-ip-per-minute are optional.
29373 A stream-type multi-threaded daemon without any max-child or
29374 max-connections-per-ip-per-minute limits would simply be: nowait.
29376 The same daemon with a maximum limit of ten daemons would read:
29379 Additionally, the same setup with a limit of twenty connections
29380 per IP address per minute and a maximum total limit of ten child
29381 daemons would read: nowait/10/20.
29383 These options are all utilized by the default settings of the
29384 fingerd daemon, as seen here:
29386 finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s
29390 This is the username that the particular daemon should run as.
29391 Most commonly, daemons run as the root user. For security
29392 purposes, it is common to find some servers running as the daemon
29393 user, or the least privileged nobody user.
29397 The full path of the daemon to be executed when a connection is
29398 received. If the daemon is a service provided by inetd internally,
29399 then internal should be used.
29401 server-program-arguments
29403 This works in conjunction with server-program by specifying the
29404 arguments, starting with argv[0], passed to the daemon on
29405 invocation. If mydaemon -d is the command line, mydaemon -d would
29406 be the value of server-program-arguments. Again, if the daemon is
29407 an internal service, use internal here.
29409 ----------------------------------------------------------------------
29413 Depending on the security profile chosen at install, many of inetd's
29414 daemons may be enabled by default. If there is no apparent need for a
29415 particular daemon, disable it! Place a ``#'' in front of the daemon in
29416 question, and send a hangup signal to inetd. Some daemons, such as
29417 fingerd, may not be desired at all because they provide an attacker with
29418 too much information.
29420 Some daemons are not security-conscious and have long, or non-existent
29421 timeouts for connection attempts. This allows an attacker to slowly send
29422 connections to a particular daemon, thus saturating available resources.
29423 It may be a good idea to place max-connections-per-ip-per-minute and
29424 max-child limitations on certain daemons.
29426 By default, TCP wrapping is turned on. Consult the hosts_access(5) manual
29427 page for more information on placing TCP restrictions on various inetd
29430 ----------------------------------------------------------------------
29432 19.14.6 Miscellaneous
29434 daytime, time, echo, discard, chargen, and auth are all internally
29435 provided services of inetd.
29437 The auth service provides identity (ident, identd) network services, and
29438 is configurable to a certain degree.
29440 Consult the inetd(8) manual page for more in-depth information.
29442 ----------------------------------------------------------------------
29444 19.15 Parallel Line IP (PLIP)
29446 PLIP lets us run TCP/IP between parallel ports. It is useful on machines
29447 without network cards, or to install on laptops. In this section, we will
29450 * Creating a parallel (laplink) cable.
29452 * Connecting two computers with PLIP.
29454 ----------------------------------------------------------------------
29456 19.15.1 Creating a Parallel Cable
29458 You can purchase a parallel cable at most computer supply stores. If you
29459 cannot do that, or you just want to know how it is done, the following
29460 table shows how to make one out of a normal parallel printer cable.
29462 Table 19-1. Wiring a Parallel Cable for Networking
29464 +--------------------------------------------+
29465 | A-name | A-End | B-End | Descr. | Post/Bit |
29466 |--------+-------+-------+--------+----------|
29467 | DATA0 | 2 | 15 | Data | 0/0x01 |
29468 | -ERROR | 15 | 2 | | 1/0x08 |
29469 |--------+-------+-------+--------+----------|
29470 | DATA1 | 3 | 13 | Data | 0/0x02 |
29471 | +SLCT | 13 | 3 | | 1/0x10 |
29472 |--------+-------+-------+--------+----------|
29473 | DATA2 | 4 | 12 | Data | 0/0x04 |
29474 | +PE | 12 | 4 | | 1/0x20 |
29475 |--------+-------+-------+--------+----------|
29476 | DATA3 | 5 | 10 | Strobe | 0/0x08 |
29477 | -ACK | 10 | 5 | | 1/0x40 |
29478 |--------+-------+-------+--------+----------|
29479 | DATA4 | 6 | 11 | Data | 0/0x10 |
29480 | BUSY | 11 | 6 | | 1/0x80 |
29481 |--------+-------+-------+--------+----------|
29482 | GND | 18-25 | 18-25 | GND | - |
29483 +--------------------------------------------+
29485 ----------------------------------------------------------------------
29487 19.15.2 Setting Up PLIP
29489 First, you have to get a laplink cable. Then, confirm that both computers
29490 have a kernel with lpt(4) driver support:
29492 # grep lp /var/run/dmesg.boot
29493 lpt0: <Printer> on ppbus0
29494 lpt0: Interrupt-driven port
29496 The parallel port must be an interrupt driven port. You should have a line
29497 similar to the following in your kernel configuration file:
29499 device ppc0 at isa? irq 7
29501 Then check if the kernel configuration file has a device plip line or if
29502 the plip.ko kernel module is loaded. In both cases the parallel networking
29503 interface should appear when you directly use the ifconfig(8) command.
29506 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
29508 Plug in the laplink cable into the parallel interface on both computers.
29510 Configure the network interface parameters on both sites as root. For
29511 example, if you want connect the host host1 with host2:
29513 host1 <-----> host2
29514 IP Address 10.0.0.1 10.0.0.2
29516 Configure the interface on host1 by doing:
29518 # ifconfig lp0 10.0.0.1 10.0.0.2
29520 Configure the interface on host2 by doing:
29522 # ifconfig lp0 10.0.0.2 10.0.0.1
29524 You now should have a working connection. Please read the manual pages
29525 lp(4) and lpt(4) for more details.
29527 You should also add both hosts to /etc/hosts:
29529 127.0.0.1 localhost.my.domain localhost
29530 10.0.0.1 host1.my.domain host1
29531 10.0.0.2 host2.my.domain
29533 To confirm the connection works, go to each host and ping the other. For
29537 lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500
29538 inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000
29543 Destination Gateway Flags Refs Use Netif Expire
29544 host2 host1 UH 0 0 lp0
29546 PING host2 (10.0.0.2): 56 data bytes
29547 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
29548 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
29549 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
29550 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
29552 --- host2 ping statistics ---
29553 4 packets transmitted, 4 packets received, 0% packet loss
29554 round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms
29556 ----------------------------------------------------------------------
29560 Originally Written by Aaron Kaplan. Restructured and Added by Tom Rhodes.
29562 IPv6 (also know as IPng ``IP next generation'') is the new version of the
29563 well known IP protocol (also know as IPv4). Like the other current *BSD
29564 systems, DragonFly includes the KAME IPv6 reference implementation. So
29565 your DragonFly system comes with all you will need to experiment with
29566 IPv6. This section focuses on getting IPv6 configured and running.
29568 In the early 1990s, people became aware of the rapidly diminishing address
29569 space of IPv4. Given the expansion rate of the Internet there were two
29572 * Running out of addresses. Today this is not so much of a concern
29573 anymore since private address spaces (10.0.0.0/8, 192.168.0.0/24,
29574 etc.) and Network Address Translation (NAT) are being employed.
29576 * Router table entries were getting too large. This is still a concern
29579 IPv6 deals with these and many other issues:
29581 * 128 bit address space. In other words theoretically there are
29582 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
29583 available. This means there are approximately 6.67 * 10^27 IPv6
29584 addresses per square meter on our planet.
29586 * Routers will only store network aggregation addresses in their routing
29587 tables thus reducing the average space of a routing table to 8192
29590 There are also lots of other useful features of IPv6 such as:
29592 * Address autoconfiguration (RFC2462)
29594 * Anycast addresses (``one-out-of many'')
29596 * Mandatory multicast addresses
29598 * IPsec (IP security)
29600 * Simplified header structure
29604 * IPv4-to-IPv6 transition mechanisms
29606 For more information see:
29608 * IPv6 overview at playground.sun.com
29614 ----------------------------------------------------------------------
29616 19.16.1 Background on IPv6 Addresses
29618 There are different types of IPv6 addresses: Unicast, Anycast and
29621 Unicast addresses are the well known addresses. A packet sent to a unicast
29622 address arrives exactly at the interface belonging to the address.
29624 Anycast addresses are syntactically indistinguishable from unicast
29625 addresses but they address a group of interfaces. The packet destined for
29626 an anycast address will arrive at the nearest (in router metric)
29627 interface. Anycast addresses may only be used by routers.
29629 Multicast addresses identify a group of interfaces. A packet destined for
29630 a multicast address will arrive at all interfaces belonging to the
29633 Note: The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
29634 by multicast addresses in IPv6.
29636 Table 19-2. Reserved IPv6 addresses
29638 +------------------------------------------------------------------------+
29639 | IPv6 address | Prefixlength | Description | Notes |
29641 |------------------+--------------+----------------+---------------------|
29642 | :: | 128 bits | unspecified | cf. 0.0.0.0 in IPv4 |
29643 |------------------+--------------+----------------+---------------------|
29644 | ::1 | 128 bits | loopback | cf. 127.0.0.1 in |
29645 | | | address | IPv4 |
29646 |------------------+--------------+----------------+---------------------|
29647 | | | | The lower 32 bits |
29648 | | | | are the IPv4 |
29649 | ::00:xx:xx:xx:xx | 96 bits | embedded IPv4 | address. Also |
29650 | | | | called ``IPv4 |
29651 | | | | compatible IPv6 |
29652 | | | | address'' |
29653 |------------------+--------------+----------------+---------------------|
29654 | | | | The lower 32 bits |
29655 | | | IPv4 mapped | are the IPv4 |
29656 | ::ff:xx:xx:xx:xx | 96 bits | IPv6 address | address. For hosts |
29657 | | | | which do not |
29658 | | | | support IPv6. |
29659 |------------------+--------------+----------------+---------------------|
29660 | fe80:: - feb:: | 10 bits | link-local | cf. loopback |
29661 | | | | address in IPv4 |
29662 |------------------+--------------+----------------+---------------------|
29663 | fec0:: - fef:: | 10 bits | site-local | |
29664 |------------------+--------------+----------------+---------------------|
29665 | ff:: | 8 bits | multicast | |
29666 |------------------+--------------+----------------+---------------------|
29667 | | | | All global unicast |
29668 | | | | addresses are |
29669 | 001 (base 2) | 3 bits | global unicast | assigned from this |
29670 | | | | pool. The first 3 |
29671 | | | | bits are ``001''. |
29672 +------------------------------------------------------------------------+
29674 ----------------------------------------------------------------------
29676 19.16.2 Reading IPv6 Addresses
29678 The canonical form is represented as: x:x:x:x:x:x:x:x, each ``x'' being a
29679 16 Bit hex value. For example FEBC:A574:382B:23C1:AA49:4592:4EFE:9982
29681 Often an address will have long substrings of all zeros therefore each
29682 such substring can be abbreviated by ``::''. For example fe80::1
29683 corresponds to the canonical form fe80:0000:0000:0000:0000:0000:0000:0001.
29685 A third form is to write the last 32 Bit part in the well known (decimal)
29686 IPv4 style with dots ``.'' as separators. For example 2002::10.0.0.1
29687 corresponds to the (hexadecimal) canonical representation
29688 2002:0000:0000:0000:0000:0000:0a00:0001 which in turn is equivalent to
29689 writing 2002::a00:1.
29691 By now the reader should be able to understand the following:
29695 rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
29696 inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
29697 inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
29698 ether 00:00:21:03:08:e1
29699 media: Ethernet autoselect (100baseTX )
29702 fe80::200:21ff:fe03:8e1%rl0 is an auto configured link-local address. It
29703 includes the scrambled Ethernet MAC as part of the auto configuration.
29705 For further information on the structure of IPv6 addresses see RFC3513.
29707 ----------------------------------------------------------------------
29709 19.16.3 Getting Connected
29711 Currently there are four ways to connect to other IPv6 hosts and networks:
29713 * Join the experimental 6bone
29715 * Getting an IPv6 network from your upstream provider. Talk to your
29716 Internet provider for instructions.
29718 * Tunnel via 6-to-4
29720 * Use the net/freenet6 port if you are on a dial-up connection.
29722 Here we will talk on how to connect to the 6bone since it currently seems
29723 to be the most popular way.
29725 First take a look at the 6bone site and find a 6bone connection nearest to
29726 you. Write to the responsible person and with a little bit of luck you
29727 will be given instructions on how to set up your connection. Usually this
29728 involves setting up a GRE (gif) tunnel.
29730 Here is a typical example on setting up a gif(4) tunnel:
29732 # ifconfig gif0 create
29734 gif0: flags=8010<POINTOPOINT,MULTICAST> mtu 1280
29735 # ifconfig gif0 tunnel MY_IPv4_ADDR HIS_IPv4_ADDR
29736 # ifconfig gif0 inet6 alias MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR
29738 Replace the capitalized words by the information you received from the
29739 upstream 6bone node.
29741 This establishes the tunnel. Check if the tunnel is working by ping6(8)
29742 'ing ff02::1%gif0. You should receive two ping replies.
29744 Note: In case you are intrigued by the address ff02:1%gif0, this is a
29745 multicast address. %gif0 states that the multicast address at network
29746 interface gif0 is to be used. Since we ping a multicast address the
29747 other endpoint of the tunnel should reply as well.
29749 By now setting up a route to your 6bone uplink should be rather
29752 # route add -inet6 default -interface gif0
29753 # ping6 -n MY_UPLINK
29755 # traceroute6 www.jp.FreeBSD.org
29756 (3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
29757 1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms
29758 2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms *
29759 3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms
29760 4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms
29761 5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms
29762 6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 ms
29764 This output will differ from machine to machine. By now you should be able
29765 to reach the IPv6 site www.kame.net and see the dancing tortoise -- that
29766 is if you have a IPv6 enabled browser such as www/mozilla.
29768 ----------------------------------------------------------------------
29770 19.16.4 DNS in the IPv6 World
29772 There are two new types of DNS records for IPv6:
29778 Using AAAA records is straightforward. Assign your hostname to the new
29779 IPv6 address you just got by adding:
29781 MYHOSTNAME AAAA MYIPv6ADDR
29783 To your primary zone DNS file. In case you do not serve your own DNS zones
29784 ask your DNS provider. Current versions of bind (version 8.3 and 9)
29785 support AAAA records.
29787 ----------------------------------------------------------------------
29789 Chapter 20 Electronic Mail
29791 Original work by Bill Lloyd. Rewritten by Jim Mock.
29795 ``Electronic Mail'', better known as email, is one of the most widely used
29796 forms of communication today. This chapter provides a basic introduction
29797 to running a mail server on DragonFly, as well as an introduction to
29798 sending and receiving email using DragonFly; however, it is not a complete
29799 reference and in fact many important considerations are omitted. For more
29800 complete coverage of the subject, the reader is referred to the many
29801 excellent books listed in Appendix B.
29803 After reading this chapter, you will know:
29805 * What software components are involved in sending and receiving
29808 * Where basic sendmail configuration files are located in DragonFly.
29810 * The difference between remote and local mailboxes.
29812 * How to block spammers from illegally using your mail server as a
29815 * How to install and configure an alternate Mail Transfer Agent on your
29816 system, replacing sendmail.
29818 * How to troubleshoot common mail server problems.
29820 * How to use SMTP with UUCP.
29822 * How to set up the system to send mail only.
29824 * How to use mail with a dialup connection.
29826 * How to configure SMTP Authentication for added security.
29828 * How to install and use a Mail User Agent, such as mutt to send and
29831 * How to download your mail from a remote POP or IMAP server.
29833 * How to automatically apply filters and rules to incoming email.
29835 Before reading this chapter, you should:
29837 * Properly set up your network connection (Chapter 19).
29839 * Properly set up the DNS information for your mail host (Chapter 19).
29841 * Know how to install additional third-party software (Chapter 4).
29843 ----------------------------------------------------------------------
29845 20.2 Using Electronic Mail
29847 There are five major parts involved in an email exchange. They are: the
29848 user program, the server daemon, DNS, a remote or local mailbox, and of
29849 course, the mailhost itself.
29851 ----------------------------------------------------------------------
29853 20.2.1 The User Program
29855 This includes command line programs such as mutt, pine, elm, and mail, and
29856 GUI programs such as balsa, xfmail to name a few, and something more
29857 ``sophisticated'' like a WWW browser. These programs simply pass off the
29858 email transactions to the local ``mailhost'', either by calling one of the
29859 server daemons available, or delivering it over TCP.
29861 ----------------------------------------------------------------------
29863 20.2.2 Mailhost Server Daemon
29865 DragonFly ships with sendmail by default, but also support numerous other
29866 mail server daemons, just some of which include:
29874 The server daemon usually has two functions--it is responsible for
29875 receiving incoming mail as well as delivering outgoing mail. It is not
29876 responsible for the collection of mail using protocols such as POP or IMAP
29877 to read your email, nor does it allow connecting to local mbox or Maildir
29878 mailboxes. You may require an additional daemon for that.
29880 Warning: Older versions of sendmail have some serious security issues
29881 which may result in an attacker gaining local and/or remote access to
29882 your machine. Make sure that you are running a current version to avoid
29883 these problems. Optionally, install an alternative MTA from the
29884 DragonFly Pkgsrc Collection.
29886 ----------------------------------------------------------------------
29888 20.2.3 Email and DNS
29890 The Domain Name System (DNS) and its daemon named play a large role in the
29891 delivery of email. In order to deliver mail from your site to another, the
29892 server daemon will look up the remote site in the DNS to determine the
29893 host that will receive mail for the destination. This process also occurs
29894 when mail is sent from a remote host to your mail server.
29896 DNS is responsible for mapping hostnames to IP addresses, as well as for
29897 storing information specific to mail delivery, known as MX records. The MX
29898 (Mail eXchanger) record specifies which host, or hosts, will receive mail
29899 for a particular domain. If you do not have an MX record for your hostname
29900 or domain, the mail will be delivered directly to your host provided you
29901 have an A record pointing your hostname to your IP address.
29903 You may view the MX records for any domain by using the host(1) command,
29904 as seen in the example below:
29906 % host -t mx DragonflyBSD.org
29907 DragonflyBSD.org mail is handled (pri=10) by crater.dragonflybsd.org
29909 ----------------------------------------------------------------------
29911 20.2.4 Receiving Mail
29913 Receiving mail for your domain is done by the mail host. It will collect
29914 all mail sent to your domain and store it either in mbox (the default
29915 method for storing mail) or Maildir format, depending on your
29916 configuration. Once mail has been stored, it may either be read locally
29917 using applications such as mail(1) or mutt, or remotely accessed and
29918 collected using protocols such as POP or IMAP. This means that should you
29919 only wish to read mail locally, you are not required to install a POP or
29922 ----------------------------------------------------------------------
29924 20.2.4.1 Accessing remote mailboxes using POP and IMAP
29926 In order to access mailboxes remotely, you are required to have access to
29927 a POP or IMAP server. These protocols allow users to connect to their
29928 mailboxes from remote locations with ease. Though both POP and IMAP allow
29929 users to remotely access mailboxes, IMAP offers many advantages, some of
29932 * IMAP can store messages on a remote server as well as fetch them.
29934 * IMAP supports concurrent updates.
29936 * IMAP can be extremely useful over low-speed links as it allows users
29937 to fetch the structure of messages without downloading them; it can
29938 also perform tasks such as searching on the server in order to
29939 minimize data transfer between clients and servers.
29941 In order to install a POP or IMAP server, the following steps should be
29944 1. Choose an IMAP or POP server that best suits your needs. The following
29945 POP and IMAP servers are well known and serve as some good examples:
29955 2. Install the POP or IMAP daemon of your choosing from the ports
29958 3. Where required, modify /etc/inetd.conf to load the POP or IMAP server.
29960 Warning: It should be noted that both POP and IMAP transmit information,
29961 including username and password credentials in clear-text. This means
29962 that if you wish to secure the transmission of information across these
29963 protocols, you should consider tunneling sessions over ssh(1). Tunneling
29964 sessions is described in Section 10.10.7.
29966 ----------------------------------------------------------------------
29968 20.2.4.2 Accessing local mailboxes
29970 Mailboxes may be accessed locally by directly utilizing MUAs on the server
29971 on which the mailbox resides. This can be done using applications such as
29974 ----------------------------------------------------------------------
29976 20.2.5 The Mail Host
29978 The mail host is the name given to a server that is responsible for
29979 delivering and receiving mail for your host, and possibly your network.
29981 ----------------------------------------------------------------------
29983 20.3 sendmail Configuration
29985 Contributed by Christopher Shumway.
29987 sendmail(8) is the default Mail Transfer Agent (MTA) in DragonFly.
29988 sendmail's job is to accept mail from Mail User Agents (MUA) and deliver
29989 it to the appropriate mailer as defined by its configuration file.
29990 sendmail can also accept network connections and deliver mail to local
29991 mailboxes or deliver it to another program.
29993 sendmail uses the following configuration files:
29995 +-----------------------------------------------------------------------+
29996 | Filename | Function |
29997 |----------------------------+------------------------------------------|
29998 | /etc/mail/access | sendmail access database file |
29999 |----------------------------+------------------------------------------|
30000 | /etc/mail/aliases | Mailbox aliases |
30001 |----------------------------+------------------------------------------|
30002 | /etc/mail/local-host-names | Lists of hosts sendmail accepts mail for |
30003 |----------------------------+------------------------------------------|
30004 | /etc/mail/mailer.conf | Mailer program configuration |
30005 |----------------------------+------------------------------------------|
30006 | /etc/mail/mailertable | Mailer delivery table |
30007 |----------------------------+------------------------------------------|
30008 | /etc/mail/sendmail.cf | sendmail master configuration file |
30009 |----------------------------+------------------------------------------|
30010 | /etc/mail/virtusertable | Virtual users and domain tables |
30011 +-----------------------------------------------------------------------+
30013 ----------------------------------------------------------------------
30015 20.3.1 /etc/mail/access
30017 The access database defines what host(s) or IP addresses have access to
30018 the local mail server and what kind of access they have. Hosts can be
30019 listed as OK, REJECT, RELAY or simply passed to sendmail's error handling
30020 routine with a given mailer error. Hosts that are listed as OK, which is
30021 the default, are allowed to send mail to this host as long as the mail's
30022 final destination is the local machine. Hosts that are listed as REJECT
30023 are rejected for all mail connections. Hosts that have the RELAY option
30024 for their hostname are allowed to send mail for any destination through
30027 Example 20-1. Configuring the sendmail Access Database
30029 cyberspammer.com 550 We don't accept mail from spammers
30030 FREE.STEALTH.MAILER@ 550 We don't accept mail from spammers
30031 another.source.of.spam REJECT
30032 okay.cyberspammer.com OK
30035 In this example we have five entries. Mail senders that match the left
30036 hand side of the table are affected by the action on the right side of the
30037 table. The first two examples give an error code to sendmail's error
30038 handling routine. The message is printed to the remote host when a mail
30039 matches the left hand side of the table. The next entry rejects mail from
30040 a specific host on the Internet, another.source.of.spam. The next entry
30041 accepts mail connections from a host okay.cyberspammer.com, which is more
30042 exact than the cyberspammer.com line above. More specific matches override
30043 less exact matches. The last entry allows relaying of electronic mail from
30044 hosts with an IP address that begins with 128.32. These hosts would be
30045 able to send mail through this mail server that are destined for other
30048 When this file is updated, you need to run make in /etc/mail/ to update
30051 ----------------------------------------------------------------------
30053 20.3.2 /etc/mail/aliases
30055 The aliases database contains a list of virtual mailboxes that are
30056 expanded to other user(s), files, programs or other aliases. Here are a
30057 few examples that can be used in /etc/mail/aliases:
30059 Example 20-2. Mail Aliases
30062 ftp-bugs: joe,eric,paul
30063 bit.bucket: /dev/null
30064 procmail: "|/usr/local/bin/procmail"
30066 The file format is simple; the mailbox name on the left side of the colon
30067 is expanded to the target(s) on the right. The first example simply
30068 expands the mailbox root to the mailbox localuser, which is then looked up
30069 again in the aliases database. If no match is found, then the message is
30070 delivered to the local user localuser. The next example shows a mail list.
30071 Mail to the mailbox ftp-bugs is expanded to the three local mailboxes joe,
30072 eric, and paul. Note that a remote mailbox could be specified as
30073 user@example.com. The next example shows writing mail to a file, in this
30074 case /dev/null. The last example shows sending mail to a program, in this
30075 case the mail message is written to the standard input of
30076 /usr/local/bin/procmail through a UNIX pipe.
30078 When this file is updated, you need to run make in /etc/mail/ to update
30081 ----------------------------------------------------------------------
30083 20.3.3 /etc/mail/local-host-names
30085 This is a list of hostnames sendmail(8) is to accept as the local host
30086 name. Place any domains or hosts that sendmail is to be receiving mail
30087 for. For example, if this mail server was to accept mail for the domain
30088 example.com and the host mail.example.com, its local-host-names might look
30089 something like this:
30094 When this file is updated, sendmail(8) needs to be restarted to read the
30097 ----------------------------------------------------------------------
30099 20.3.4 /etc/mail/sendmail.cf
30101 sendmail's master configuration file, sendmail.cf controls the overall
30102 behavior of sendmail, including everything from rewriting e-mail addresses
30103 to printing rejection messages to remote mail servers. Naturally, with
30104 such a diverse role, this configuration file is quite complex and its
30105 details are a bit out of the scope of this section. Fortunately, this file
30106 rarely needs to be changed for standard mail servers.
30108 The master sendmail configuration file can be built from m4(1) macros that
30109 define the features and behavior of sendmail. Please see
30110 /usr/src/contrib/sendmail/cf/README for some of the details.
30112 When changes to this file are made, sendmail needs to be restarted for the
30113 changes to take effect.
30115 ----------------------------------------------------------------------
30117 20.3.5 /etc/mail/virtusertable
30119 The virtusertable maps mail addresses for virtual domains and mailboxes to
30120 real mailboxes. These mailboxes can be local, remote, aliases defined in
30121 /etc/mail/aliases or files.
30123 Example 20-3. Example Virtual Domain Mail Map
30125 root@example.com root
30126 postmaster@example.com postmaster@noc.example.net
30129 In the above example, we have a mapping for a domain example.com. This
30130 file is processed in a first match order down the file. The first item
30131 maps root@example.com to the local mailbox root. The next entry maps
30132 postmaster@example.com to the mailbox postmaster on the host
30133 noc.example.net. Finally, if nothing from example.com has matched so far,
30134 it will match the last mapping, which matches every other mail message
30135 addressed to someone at example.com. This will be mapped to the local
30138 ----------------------------------------------------------------------
30140 20.4 Changing Your Mail Transfer Agent
30142 Written by Andrew Boothman. Information taken from e-mails written by
30143 Gregory Neil Shapiro.
30145 As already mentioned, DragonFly comes with sendmail already installed as
30146 your MTA (Mail Transfer Agent). Therefore by default it is in charge of
30147 your outgoing and incoming mail.
30149 However, for a variety of reasons, some system administrators want to
30150 change their system's MTA. These reasons range from simply wanting to try
30151 out another MTA to needing a specific feature or package which relies on
30152 another mailer. Fortunately, whatever the reason, DragonFly makes it easy
30153 to make the change.
30155 ----------------------------------------------------------------------
30157 20.4.1 Install a New MTA
30159 You have a wide choice of MTAs available. A good starting point is the
30160 pkgsrc collectionor where you will be able to find many. Of course you are
30161 free to use any MTA you want from any location, as long as you can make it
30162 run under DragonFly.
30164 Start by installing your new MTA. Once it is installed it gives you a
30165 chance to decide if it really fulfills your needs, and also gives you the
30166 opportunity to configure your new software before getting it to take over
30167 from sendmail. When doing this, you should be sure that installing the new
30168 software will not attempt to overwrite system binaries such as
30169 /usr/bin/sendmail. Otherwise, your new mail software has essentially been
30170 put into service before you have configured it.
30172 Please refer to your chosen MTA's documentation for information on how to
30173 configure the software you have chosen.
30175 ----------------------------------------------------------------------
30177 20.4.2 Disable sendmail
30179 In order to completely disable sendmail you must use
30181 sendmail_enable="NONE"
30185 Warning: If you disable sendmail's outgoing mail service in this way, it
30186 is important that you replace it with a fully working alternative mail
30187 delivery system. If you choose not to, system functions such as
30188 periodic(8) will be unable to deliver their results by e-mail as they
30189 would normally expect to. Many parts of your system may expect to have a
30190 functional sendmail-compatible system. If applications continue to use
30191 sendmail's binaries to try to send e-mail after you have disabled them,
30192 mail could go into an inactive sendmail queue, and never be delivered.
30194 If you only want to disable sendmail's incoming mail service, you should
30197 sendmail_enable="NO"
30199 in /etc/rc.conf. More information on sendmail's startup options is
30200 available from the rc.sendmail(8) manual page.
30202 ----------------------------------------------------------------------
30204 20.4.3 Running Your New MTA on Boot
30206 You may have a choice of two methods for running your new MTA on boot,
30207 again depending on what version of DragonFly you are running.
30209 With later versions of DragonFly, you can use the above method or you can
30212 mta_start_script="filename"
30214 in /etc/rc.conf, where filename is the name of some script that you want
30215 executed at boot to start your MTA.
30217 ----------------------------------------------------------------------
30219 20.4.4 Replacing sendmail as the System's Default Mailer
30221 The program sendmail is so ubiquitous as standard software on UNIX systems
30222 that some software just assumes it is already installed and configured.
30223 For this reason, many alternative MTA's provide their own compatible
30224 implementations of the sendmail command-line interface; this facilitates
30225 using them as ``drop-in'' replacements for sendmail.
30227 Therefore, if you are using an alternative mailer, you will need to make
30228 sure that software trying to execute standard sendmail binaries such as
30229 /usr/bin/sendmail actually executes your chosen mailer instead.
30230 Fortunately, DragonFly provides a system called mailwrapper(8) that does
30233 When sendmail is operating as installed, you will find something like the
30234 following in /etc/mail/mailer.conf:
30236 sendmail /usr/libexec/sendmail/sendmail
30237 send-mail /usr/libexec/sendmail/sendmail
30238 mailq /usr/libexec/sendmail/sendmail
30239 newaliases /usr/libexec/sendmail/sendmail
30240 hoststat /usr/libexec/sendmail/sendmail
30241 purgestat /usr/libexec/sendmail/sendmail
30243 This means that when any of these common commands (such as sendmail
30244 itself) are run, the system actually invokes a copy of mailwrapper named
30245 sendmail, which checks mailer.conf and executes
30246 /usr/libexec/sendmail/sendmail instead. This system makes it easy to
30247 change what binaries are actually executed when these default sendmail
30248 functions are invoked.
30250 Therefore if you wanted /usr/local/supermailer/bin/sendmail-compat to be
30251 run instead of sendmail, you could change /etc/mail/mailer.conf to read:
30253 sendmail /usr/local/supermailer/bin/sendmail-compat
30254 send-mail /usr/local/supermailer/bin/sendmail-compat
30255 mailq /usr/local/supermailer/bin/mailq-compat
30256 newaliases /usr/local/supermailer/bin/newaliases-compat
30257 hoststat /usr/local/supermailer/bin/hoststat-compat
30258 purgestat /usr/local/supermailer/bin/purgestat-compat
30260 ----------------------------------------------------------------------
30264 Once you have everything configured the way you want it, you should either
30265 kill the sendmail processes that you no longer need and start the
30266 processes belonging to your new software, or simply reboot. Rebooting will
30267 also give you the opportunity to ensure that you have correctly configured
30268 your system to start your new MTA automatically on boot.
30270 ----------------------------------------------------------------------
30272 20.5 Troubleshooting
30274 20.5.1. Why do I have to use the FQDN for hosts on my site?
30276 20.5.2. sendmail says ``mail loops back to myself''
30278 20.5.3. How can I run a mail server on a dial-up PPP host?
30280 20.5.4. Why do I keep getting ``Relaying Denied'' errors when sending mail
30283 20.5.1. Why do I have to use the FQDN for hosts on my site?
30285 You will probably find that the host is actually in a different domain;
30286 for example, if you are in foo.bar.edu and you wish to reach a host called
30287 mumble in the bar.edu domain, you will have to refer to it by the
30288 fully-qualified domain name, mumble.bar.edu, instead of just mumble.
30290 Traditionally, this was allowed by BSD BIND resolvers. However the current
30291 version of BIND that ships with DragonFly no longer provides default
30292 abbreviations for non-fully qualified domain names other than the domain
30293 you are in. So an unqualified host mumble must either be found as
30294 mumble.foo.bar.edu, or it will be searched for in the root domain.
30296 This is different from the previous behavior, where the search continued
30297 across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535 for why
30298 this was considered bad practice, or even a security hole.
30300 As a good workaround, you can place the line:
30302 search foo.bar.edu bar.edu
30304 instead of the previous:
30308 into your /etc/resolv.conf. However, make sure that the search order does
30309 not go beyond the ``boundary between local and public administration'', as
30312 20.5.2. sendmail says ``mail loops back to myself''
30314 This is answered in the sendmail FAQ as follows:
30316 I'm getting these error messages:
30318 553 MX list for domain.net points back to relay.domain.net
30319 554 <user@domain.net>... Local configuration error
30321 How can I solve this problem?
30323 You have asked mail to the domain (e.g., domain.net) to be
30324 forwarded to a specific host (in this case, relay.domain.net)
30325 by using an MX record, but the relay machine does not recognize
30326 itself as domain.net. Add domain.net to /etc/mail/local-host-names
30327 [known as /etc/sendmail.cw prior to version 8.10]
30328 (if you are using FEATURE(use_cw_file)) or add ``Cw domain.net''
30329 to /etc/mail/sendmail.cf.
30331 The sendmail FAQ can be found at http://www.sendmail.org/faq/ and is
30332 recommended reading if you want to do any ``tweaking'' of your mail setup.
30334 20.5.3. How can I run a mail server on a dial-up PPP host?
30336 You want to connect a DragonFly box on a LAN to the Internet. The
30337 DragonFly box will be a mail gateway for the LAN. The PPP connection is
30340 There are at least two ways to do this. One way is to use UUCP.
30342 Another way is to get a full-time Internet server to provide secondary MX
30343 services for your domain. For example, if your company's domain is
30344 example.com and your Internet service provider has set example.net up to
30345 provide secondary MX services to your domain:
30347 example.com. MX 10 example.com.
30350 Only one host should be specified as the final recipient (add Cw
30351 example.com in /etc/mail/sendmail.cf on example.com).
30353 When the sending sendmail is trying to deliver the mail it will try to
30354 connect to you (example.com) over the modem link. It will most likely time
30355 out because you are not online. The program sendmail will automatically
30356 deliver it to the secondary MX site, i.e. your Internet provider
30357 (example.net). The secondary MX site will then periodically try to connect
30358 to your host and deliver the mail to the primary MX host (example.com).
30360 You might want to use something like this as a login script:
30363 # Put me in /usr/local/bin/pppmyisp
30364 ( sleep 60 ; /usr/sbin/sendmail -q ) &
30365 /usr/sbin/ppp -direct pppmyisp
30367 If you are going to create a separate login script for a user you could
30368 use sendmail -qRexample.com instead in the script above. This will force
30369 all mail in your queue for example.com to be processed immediately.
30371 A further refinement of the situation is as follows:
30373 Message stolen from the FreeBSD Internet service provider's mailing list.
30375 > we provide the secondary MX for a customer. The customer connects to
30376 > our services several times a day automatically to get the mails to
30377 > his primary MX (We do not call his site when a mail for his domains
30378 > arrived). Our sendmail sends the mailqueue every 30 minutes. At the
30379 > moment he has to stay 30 minutes online to be sure that all mail is
30380 > gone to the primary MX.
30382 > Is there a command that would initiate sendmail to send all the mails
30383 > now? The user has not root-privileges on our machine of course.
30385 In the ``privacy flags'' section of sendmail.cf, there is a
30386 definition Opgoaway,restrictqrun
30388 Remove restrictqrun to allow non-root users to start the queue processing.
30389 You might also like to rearrange the MXs. We are the 1st MX for our
30390 customers like this, and we have defined:
30392 # If we are the best MX for a host, try directly instead of generating
30393 # local config error.
30396 That way a remote site will deliver straight to you, without trying
30397 the customer connection. You then send to your customer. Only works for
30398 ``hosts'', so you need to get your customer to name their mail
30399 machine ``customer.com'' as well as
30400 ``hostname.customer.com'' in the DNS. Just put an A record in
30401 the DNS for ``customer.com''.
30403 20.5.4. Why do I keep getting ``Relaying Denied'' errors when sending mail
30406 In default DragonFly installations, sendmail is configured to only send
30407 mail from the host it is running on. For example, if a POP server is
30408 available, then users will be able to check mail from school, work, or
30409 other remote locations but they still will not be able to send outgoing
30410 emails from outside locations. Typically, a few moments after the attempt,
30411 an email will be sent from MAILER-DAEMON with a ``5.7 Relaying Denied''
30414 There are several ways to get around this. The most straightforward
30415 solution is to put your ISP's address in a relay-domains file at
30416 /etc/mail/relay-domains. A quick way to do this would be:
30418 # echo "your.isp.example.com" > /etc/mail/relay-domains
30420 After creating or editing this file you must restart sendmail. This works
30421 great if you are a server administrator and do not wish to send mail
30422 locally, or would like to use a point and click client/system on another
30423 machine or even another ISP. It is also very useful if you only have one
30424 or two email accounts set up. If there is a large number of addresses to
30425 add, you can simply open this file in your favorite text editor and then
30426 add the domains, one per line:
30428 your.isp.example.com
30429 other.isp.example.net
30430 users-isp.example.org
30433 Now any mail sent through your system, by any host in this list (provided
30434 the user has an account on your system), will succeed. This is a very nice
30435 way to allow users to send mail from your system remotely without allowing
30436 people to send SPAM through your system.
30438 ----------------------------------------------------------------------
30440 20.6 Advanced Topics
30442 The following section covers more involved topics such as mail
30443 configuration and setting up mail for your entire domain.
30445 ----------------------------------------------------------------------
30447 20.6.1 Basic Configuration
30449 Out of the box, you should be able to send email to external hosts as long
30450 as you have set up /etc/resolv.conf or are running your own name server.
30451 If you would like to have mail for your host delivered to the MTA (e.g.,
30452 sendmail) on your own DragonFly host, there are two methods:
30454 * Run your own name server and have your own domain. For example,
30457 * Get mail delivered directly to your host. This is done by delivering
30458 mail directly to the current DNS name for your machine. For example,
30459 example.dragonflybsd.org.
30461 Regardless of which of the above you choose, in order to have mail
30462 delivered directly to your host, it must have a permanent static IP
30463 address (not a dynamic address, as with most PPP dial-up configurations).
30464 If you are behind a firewall, it must pass SMTP traffic on to you. If you
30465 want to receive mail directly at your host, you need to be sure of either
30468 * Make sure that the (lowest-numbered) MX record in your DNS points to
30469 your host's IP address.
30471 * Make sure there is no MX entry in your DNS for your host.
30473 Either of the above will allow you to receive mail directly at your host.
30478 example.dragonflybsd.org
30479 # host example.dragonflybsd.org
30480 example.dragonflybsd.org has address 204.216.27.XX
30482 If that is what you see, mail directly to
30483 <yourlogin@example.dragonflybsd.org> should work without problems
30484 (assuming sendmail is running correctly on example.dragonflybsd.org).
30486 If instead you see something like this:
30488 # host example.dragonflybsd.org
30489 example.dragonflybsd.org has address 204.216.27.XX
30490 example.dragonflybsd.org mail is handled (pri=10) by hub.dragonflybsd.org
30492 All mail sent to your host (example.dragonflybsd.org) will end up being
30493 collected on hub under the same username instead of being sent directly to
30496 The above information is handled by your DNS server. The DNS record that
30497 carries mail routing information is the Mail eXchange entry. If no MX
30498 record exists, mail will be delivered directly to the host by way of its
30501 The MX entry for freefall.FreeBSD.org at one time looked like this:
30503 freefall MX 30 mail.crl.net
30504 freefall MX 40 agora.rdrop.com
30505 freefall MX 10 freefall.FreeBSD.org
30506 freefall MX 20 who.cdrom.com
30508 As you can see, freefall had many MX entries. The lowest MX number is the
30509 host that receives mail directly if available; if it is not accessible for
30510 some reason, the others (sometimes called ``backup MXes'') accept messages
30511 temporarily, and pass it along when a lower-numbered host becomes
30512 available, eventually to the lowest-numbered host.
30514 Alternate MX sites should have separate Internet connections from your own
30515 in order to be most useful. Your ISP or another friendly site should have
30516 no problem providing this service for you.
30518 ----------------------------------------------------------------------
30520 20.6.2 Mail for Your Domain
30522 In order to set up a ``mailhost'' (a.k.a. mail server) you need to have
30523 any mail sent to various workstations directed to it. Basically, you want
30524 to ``claim'' any mail for any hostname in your domain (in this case
30525 *.dragonflybsd.org) and divert it to your mail server so your users can
30526 receive their mail on the master mail server.
30528 To make life easiest, a user account with the same username should exist
30529 on both machines. Use adduser(8) to do this.
30531 The mailhost you will be using must be the designated mail exchanger for
30532 each workstation on the network. This is done in your DNS configuration
30535 example.dragonflybsd.org A 204.216.27.XX ; Workstation
30536 MX 10 hub.dragonflybsd.org ; Mailhost
30538 This will redirect mail for the workstation to the mailhost no matter
30539 where the A record points. The mail is sent to the MX host.
30541 You cannot do this yourself unless you are running a DNS server. If you
30542 are not, or cannot run your own DNS server, talk to your ISP or whoever
30545 If you are doing virtual email hosting, the following information will
30546 come in handy. For this example, we will assume you have a customer with
30547 his own domain, in this case customer1.org, and you want all the mail for
30548 customer1.org sent to your mailhost, mail.myhost.com. The entry in your
30549 DNS should look like this:
30551 customer1.org MX 10 mail.myhost.com
30553 You do not need an A record for customer1.org if you only want to handle
30554 email for that domain.
30556 Note: Be aware that pinging customer1.org will not work unless an A
30557 record exists for it.
30559 The last thing that you must do is tell sendmail on your mailhost what
30560 domains and/or hostnames it should be accepting mail for. There are a few
30561 different ways this can be done. Either of the following will work:
30563 * Add the hosts to your /etc/mail/local-host-names file if you are using
30564 the FEATURE(use_cw_file).
30566 * Add a Cwyour.host.com line to your /etc/mail/sendmail.cf.
30568 ----------------------------------------------------------------------
30570 20.7 SMTP with UUCP
30572 The sendmail configuration that ships with DragonFly is designed for sites
30573 that connect directly to the Internet. Sites that wish to exchange their
30574 mail via UUCP must install another sendmail configuration file.
30576 Tweaking /etc/mail/sendmail.cf manually is an advanced topic. sendmail
30577 version 8 generates config files via m4(1) preprocessing, where the actual
30578 configuration occurs on a higher abstraction level. The m4(1)
30579 configuration files can be found under /usr/src/usr.sbin/sendmail/cf.
30581 If you did not install your system with full sources, the sendmail
30582 configuration set has been broken out into a separate source distribution
30583 tarball. Assuming you have your DragonFly source code CDROM mounted, do:
30586 # cat scontrib.?? | tar xzf - -C /usr/src/contrib/sendmail
30588 This extracts to only a few hundred kilobytes. The file README in the cf
30589 directory can serve as a basic introduction to m4(1) configuration.
30591 The best way to support UUCP delivery is to use the mailertable feature.
30592 This creates a database that sendmail can use to make routing decisions.
30594 First, you have to create your .mc file. The directory
30595 /usr/src/usr.sbin/sendmail/cf/cf contains a few examples. Assuming you
30596 have named your file foo.mc, all you need to do in order to convert it
30597 into a valid sendmail.cf is:
30599 # cd /usr/src/usr.sbin/sendmail/cf/cf
30601 # cp foo.cf /etc/mail/sendmail.cf
30603 A typical .mc file might look like:
30605 VERSIONID(`Your version number') OSTYPE(bsd4.4)
30607 FEATURE(accept_unresolvable_domains)
30608 FEATURE(nocanonify)
30609 FEATURE(mailertable, `hash -o /etc/mail/mailertable')
30611 define(`UUCP_RELAY', your.uucp.relay)
30612 define(`UUCP_MAX_SIZE', 200000)
30613 define(`confDONT_PROBE_INTERFACES')
30619 Cw your.alias.host.name
30620 Cw youruucpnodename.UUCP
30622 The lines containing accept_unresolvable_domains, nocanonify, and
30623 confDONT_PROBE_INTERFACES features will prevent any usage of the DNS
30624 during mail delivery. The UUCP_RELAY clause is needed to support UUCP
30625 delivery. Simply put an Internet hostname there that is able to handle
30626 .UUCP pseudo-domain addresses; most likely, you will enter the mail relay
30629 Once you have this, you need an /etc/mail/mailertable file. If you have
30630 only one link to the outside that is used for all your mails, the
30631 following file will suffice:
30634 # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable
30635 . uucp-dom:your.uucp.relay
30637 A more complex example might look like this:
30640 # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable
30642 horus.interface-business.de uucp-dom:horus
30643 .interface-business.de uucp-dom:if-bus
30644 interface-business.de uucp-dom:if-bus
30645 .heep.sax.de smtp8:%1
30646 horus.UUCP uucp-dom:horus
30647 if-bus.UUCP uucp-dom:if-bus
30650 The first three lines handle special cases where domain-addressed mail
30651 should not be sent out to the default route, but instead to some UUCP
30652 neighbor in order to ``shortcut'' the delivery path. The next line handles
30653 mail to the local Ethernet domain that can be delivered using SMTP.
30654 Finally, the UUCP neighbors are mentioned in the .UUCP pseudo-domain
30655 notation, to allow for a uucp-neighbor !recipient override of the default
30656 rules. The last line is always a single dot, matching everything else,
30657 with UUCP delivery to a UUCP neighbor that serves as your universal mail
30658 gateway to the world. All of the node names behind the uucp-dom: keyword
30659 must be valid UUCP neighbors, as you can verify using the command uuname.
30661 As a reminder that this file needs to be converted into a DBM database
30662 file before use. The command line to accomplish this is best placed as a
30663 comment at the top of the mailertable file. You always have to execute
30664 this command each time you change your mailertable file.
30666 Final hint: if you are uncertain whether some particular mail routing
30667 would work, remember the -bt option to sendmail. It starts sendmail in
30668 address test mode; simply enter 3,0, followed by the address you wish to
30669 test for the mail routing. The last line tells you the used internal mail
30670 agent, the destination host this agent will be called with, and the
30671 (possibly translated) address. Leave this mode by typing Ctrl+D.
30674 ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
30675 Enter <ruleset> <address>
30676 > 3,0 foo@example.com
30677 canonify input: foo @ example . com
30679 parse returns: $# uucp-dom $@ your.uucp.relay $: foo < @ example . com . >
30682 ----------------------------------------------------------------------
30684 20.8 Setting up to send only
30686 Contributed by Bill Moran.
30688 There are many instances where you may only want to send mail through a
30689 relay. Some examples are:
30691 * Your computer is a desktop machine, but you want to use programs from
30692 the command line that send mail. To do so, you should use your ISP's
30695 * The computer is a server that does not handle mail locally, but needs
30696 to pass off all mail to a relay for processing.
30698 Just about any MTA is capable of filling this particular niche.
30699 Unfortunately, it can be very difficult to properly configure a
30700 full-featured MTA just to handle offloading mail. Programs such as
30701 sendmail and postfix are largely overkill for this use.
30703 Additionally, if you are using a typical Internet access service, your
30704 agreement may forbid you from running a ``mail server''.
30706 The easiest way to fulfill those needs is to install the mail/ssmtp port.
30707 Execute the following commands as root:
30709 # cd /usr/ports/mail/ssmtp
30710 # make install replace clean
30712 Once installed, mail/ssmtp can be configured with a four-line file located
30713 at /usr/local/etc/ssmtp/ssmtp.conf:
30715 root=yourrealemail@example.com
30716 mailhub=mail.example.com
30717 rewriteDomain=example.com
30718 hostname=_HOSTNAME_
30720 Make sure you use your real email address for root. Enter your ISP's
30721 outgoing mail relay in place of mail.example.com (some ISPs call this the
30722 ``outgoing mail server'' or ``SMTP server'').
30724 Make sure you disable sendmail by setting sendmail_enable="NONE" in
30727 mail/ssmtp has some other options available. See the example configuration
30728 file in /usr/local/etc/ssmtp or the manual page of ssmtp for some examples
30729 and more information.
30731 Setting up ssmtp in this manner will allow any software on your computer
30732 that needs to send mail to function properly, while not violating your
30733 ISP's usage policy or allowing your computer to be hijacked for spamming.
30735 ----------------------------------------------------------------------
30737 20.9 Using Mail with a Dialup Connection
30739 If you have a static IP address, you should not need to adjust anything
30740 from the defaults. Set your host name to your assigned Internet name and
30741 sendmail will do the rest.
30743 If you have a dynamically assigned IP number and use a dialup PPP
30744 connection to the Internet, you will probably have a mailbox on your ISPs
30745 mail server. Let's assume your ISP's domain is example.net, and that your
30746 user name is user, you have called your machine bsd.home, and your ISP has
30747 told you that you may use relay.example.net as a mail relay.
30749 In order to retrieve mail from your mailbox, you must install a retrieval
30750 agent. The fetchmail utility is a good choice as it supports many
30751 different protocols. This program is available as a package or from the
30752 ports collection (mail/fetchmail). Usually, your ISP will provide POP. If
30753 you are using user PPP, you can automatically fetch your mail when an
30754 Internet connection is established with the following entry in
30755 /etc/ppp/ppp.linkup:
30758 !bg su user -c fetchmail
30760 If you are using sendmail (as shown below) to deliver mail to non-local
30761 accounts, you probably want to have sendmail process your mailqueue as
30762 soon as your Internet connection is established. To do this, put this
30763 command after the fetchmail command in /etc/ppp/ppp.linkup:
30765 !bg su user -c "sendmail -q"
30767 Assume that you have an account for user on bsd.home. In the home
30768 directory of user on bsd.home, create a .fetchmailrc file:
30770 poll example.net protocol pop3 fetchall pass MySecret
30772 This file should not be readable by anyone except user as it contains the
30775 In order to send mail with the correct from: header, you must tell
30776 sendmail to use user@example.net rather than user@bsd.home. You may also
30777 wish to tell sendmail to send all mail via relay.example.net, allowing
30778 quicker mail transmission.
30780 The following .mc file should suffice:
30782 VERSIONID(`bsd.home.mc version 1.0')
30789 MASQUERADE_AS(`example.net')dnl
30790 FEATURE(allmasquerade)dnl
30791 FEATURE(masquerade_envelope)dnl
30792 FEATURE(nocanonify)dnl
30794 define(`SMART_HOST', `relay.example.net')
30796 define(`confDOMAIN_NAME',`bsd.home')dnl
30797 define(`confDELIVERY_MODE',`deferred')dnl
30799 Refer to the previous section for details of how to turn this .mc file
30800 into a sendmail.cf file. Also, do not forget to restart sendmail after
30801 updating sendmail.cf.
30803 ----------------------------------------------------------------------
30805 20.10 SMTP Authentication
30807 Written by James Gorham.
30809 Having SMTP Authentication in place on your mail server has a number of
30810 benefits. SMTP Authentication can add another layer of security to
30811 sendmail, and has the benefit of giving mobile users who switch hosts the
30812 ability to use the same mail server without the need to reconfigure their
30813 mail client settings each time.
30815 1. Install security/cyrus-sasl from the ports. You can find this port in
30816 security/cyrus-sasl. security/cyrus-sasl has a number of compile time
30817 options to choose from and, for the method we will be using here, make
30818 sure to select the pwcheck option.
30820 2. After installing security/cyrus-sasl, edit
30821 /usr/local/lib/sasl/Sendmail.conf (or create it if it does not exist)
30822 and add the following line:
30824 pwcheck_method: passwd
30826 This method will enable sendmail to authenticate against your
30827 DragonFly passwd database. This saves the trouble of creating a new
30828 set of usernames and passwords for each user that needs to use SMTP
30829 authentication, and keeps the login and mail password the same.
30831 3. Now edit /etc/make.conf and add the following lines:
30833 SENDMAIL_CFLAGS=-I/usr/local/include/sasl1 -DSASL
30834 SENDMAIL_LDFLAGS=-L/usr/local/lib
30835 SENDMAIL_LDADD=-lsasl
30837 These lines will give sendmail the proper configuration options for
30838 linking to cyrus-sasl at compile time. Make sure that cyrus-sasl has
30839 been installed before recompiling sendmail.
30841 4. Recompile sendmail by executing the following commands:
30843 # cd /usr/src/usr.sbin/sendmail
30849 The compile of sendmail should not have any problems if /usr/src has
30850 not been changed extensively and the shared libraries it needs are
30853 5. After sendmail has been compiled and reinstalled, edit your
30854 /etc/mail/freebsd.mc file (or whichever file you use as your .mc file.
30855 Many administrators choose to use the output from hostname(1) as the
30856 .mc file for uniqueness). Add these lines to it:
30858 dnl set SASL options
30859 TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
30860 define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
30861 define(`confDEF_AUTH_INFO', `/etc/mail/auth-info')dnl
30863 These options configure the different methods available to sendmail
30864 for authenticating users. If you would like to use a method other than
30865 pwcheck, please see the included documentation.
30867 6. Finally, run make(1) while in /etc/mail. That will run your new .mc
30868 file and create a .cf file named freebsd.cf (or whatever name you have
30869 used for your .mc file). Then use the command make install restart,
30870 which will copy the file to sendmail.cf, and will properly restart
30871 sendmail. For more information about this process, you should refer to
30872 /etc/mail/Makefile.
30874 If all has gone correctly, you should be able to enter your login
30875 information into the mail client and send a test message. For further
30876 investigation, set the LogLevel of sendmail to 13 and watch
30877 /var/log/maillog for any errors.
30879 You may wish to add the following lines to /etc/rc.conf so this service
30880 will be available after every system boot:
30882 sasl_pwcheck_enable="YES"
30883 sasl_pwcheck_program="/usr/local/sbin/pwcheck"
30885 This will ensure the initialization of SMTP_AUTH upon system boot.
30887 For more information, please see the sendmail page regarding SMTP
30890 ----------------------------------------------------------------------
30892 20.11 Mail User Agents
30894 Contributed by Marc Silver.
30896 A Mail User Agent (MUA) is an application that is used to send and receive
30897 email. Furthermore, as email ``evolves'' and becomes more complex, MUA's
30898 are becoming increasingly powerful in the way they interact with email;
30899 this gives users increased functionality and flexibility. DragonFly
30900 contains support for numerous mail user agents, all of which can be easily
30901 installed using the pkgsrc collection. Users may choose between graphical
30902 email clients such as evolution or balsa, console based clients such as
30903 mutt, pine or mail, or the web interfaces used by some large
30906 ----------------------------------------------------------------------
30910 mail(1) is the default Mail User Agent (MUA) in DragonFly. It is a console
30911 based MUA that offers all the basic functionality required to send and
30912 receive text-based email, though it is limited in interaction abilities
30913 with attachments and can only support local mailboxes.
30915 Although mail does not natively support interaction with POP or IMAP
30916 servers, these mailboxes may be downloaded to a local mbox file using an
30917 application such as fetchmail, which will be discussed later in this
30918 chapter (Section 20.12).
30920 In order to send and receive email, simply invoke the mail command as per
30921 the following example:
30925 The contents of the user mailbox in /var/mail are automatically read by
30926 the mail utility. Should the mailbox be empty, the utility exits with a
30927 message indicating that no mails could be found. Once the mailbox has been
30928 read, the application interface is started, and a list of messages will be
30929 displayed. Messages are automatically numbered, as can be seen in the
30932 Mail version 8.1 6/6/93. Type ? for help.
30933 "/var/mail/marcs": 3 messages 3 new
30934 >N 1 root@localhost Mon Mar 8 14:05 14/510 "test"
30935 N 2 root@localhost Mon Mar 8 14:05 14/509 "user account"
30936 N 3 root@localhost Mon Mar 8 14:05 14/509 "sample"
30938 Messages can now be read by using the t mail command, suffixed by the
30939 message number that should be displayed. In this example, we will read the
30944 From root@localhost Mon Mar 8 14:05:52 2004
30945 X-Original-To: marcs@localhost
30946 Delivered-To: marcs@localhost
30947 To: marcs@localhost
30949 Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST)
30950 From: root@localhost (Charlie Root)
30952 This is a test message, please reply if you receive it.
30954 As can be seen in the example above, the t key will cause the message to
30955 be displayed with full headers. To display the list of messages again, the
30956 h key should be used.
30958 If the email requires a response, you may use mail to reply, by using
30959 either the R or r mail keys. The R key instructs mail to reply only to the
30960 sender of the email, while r replies not only to the sender, but also to
30961 other recipients of the message. You may also suffix these commands with
30962 the mail number which you would like make a reply to. Once this has been
30963 done, the response should be entered, and the end of the message should be
30964 marked by a single . on a new line. An example can be seen below:
30970 Thank you, I did get your email.
30974 In order to send new email, the m key should be used, followed by the
30975 recipient email address. Multiple recipients may also be specified by
30976 separating each address with the , delimiter. The subject of the message
30977 may then be entered, followed by the message contents. The end of the
30978 message should be specified by putting a single . on a new line.
30980 & mail root@localhost
30981 Subject: I mastered mail
30983 Now I can send and receive email using mail ... :)
30987 While inside the mail utility, the ? command may be used to display help
30988 at any time, the mail(1) manual page should also be consulted for more
30991 Note: As previously mentioned, the mail(1) command was not originally
30992 designed to handle attachments, and thus deals with them very poorly.
30993 Newer MUAs such as mutt handle attachments in a much more intelligent
30994 way. But should you still wish to use the mail command, the
30995 converters/mpack port may be of considerable use.
30997 ----------------------------------------------------------------------
31001 mutt is a small yet very powerful Mail User Agent, with excellent
31002 features, just some of which include:
31004 * The ability to thread messages;
31006 * PGP support for digital signing and encryption of email;
31012 * Highly customizable.
31014 All of these features help to make mutt one of the most advanced mail user
31015 agents available. See http://www.mutt.org for more information on mutt.
31017 The stable version of mutt may be installed using the mail/mutt port,
31018 while the current development version may be installed via the
31019 mail/mutt-devel port. After the port has been installed, mutt can be
31020 started by issuing the following command:
31024 mutt will automatically read the contents of the user mailbox in /var/mail
31025 and display the contents if applicable. If no mails are found in the user
31026 mailbox, then mutt will wait for commands from the user. The example below
31027 shows mutt displaying a list of messages:
31029 In order to read an email, simply select it using the cursor keys, and
31030 press the Enter key. An example of mutt displaying email can be seen
31033 As with the mail(1) command, mutt allows users to reply only to the sender
31034 of the message as well as to all recipients. To reply only to the sender
31035 of the email, use the r keyboard shortcut. To send a group reply, which
31036 will be sent to the original sender as well as all the message recipients,
31037 use the g shortcut.
31039 Note: mutt makes use of the vi(1) command as an editor for creating and
31040 replying to emails. This may be customized by the user by creating or
31041 editing their own .muttrc file in their home directory and setting the
31044 In order to compose a new mail message, press m. After a valid subject has
31045 been given, mutt will start vi(1) and the mail can be written. Once the
31046 contents of the mail are complete, save and quit from vi and mutt will
31047 resume, displaying a summary screen of the mail that is to be delivered.
31048 In order to send the mail, press y. An example of the summary screen can
31051 mutt also contains extensive help, which can be accessed from most of the
31052 menus by pressing the ? key. The top line also displays the keyboard
31053 shortcuts where appropriate.
31055 ----------------------------------------------------------------------
31059 pine is aimed at a beginner user, but also includes some advanced
31062 Warning: The pine software has had several remote vulnerabilities
31063 discovered in the past, which allowed remote attackers to execute
31064 arbitrary code as users on the local system, by the action of sending a
31065 specially-prepared email. All such known problems have been fixed, but
31066 the pine code is written in a very insecure style and the DragonFly
31067 Security Officer believes there are likely to be other undiscovered
31068 vulnerabilities. You install pine at your own risk.
31070 The current version of pine may be installed using the mail/pine4 port.
31071 Once the port has installed, pine can be started by issuing the following
31076 The first time that pine is run it displays a greeting page with a brief
31077 introduction, as well as a request from the pine development team to send
31078 an anonymous email message allowing them to judge how many users are using
31079 their client. To send this anonymous message, press Enter, or
31080 alternatively press E to exit the greeting without sending an anonymous
31081 message. An example of the greeting page can be seen below:
31083 Users are then presented with the main menu, which can be easily navigated
31084 using the cursor keys. This main menu provides shortcuts for the composing
31085 new mails, browsing of mail directories, and even the administration of
31086 address book entries. Below the main menu, relevant keyboard shortcuts to
31087 perform functions specific to the task at hand are shown.
31089 The default directory opened by pine is the inbox. To view the message
31090 index, press I, or select the MESSAGE INDEX option as seen below:
31092 The message index shows messages in the current directory, and can be
31093 navigated by using the cursor keys. Highlighted messages can be read by
31094 pressing the Enter key.
31096 In the screenshot below, a sample message is displayed by pine. Keyboard
31097 shortcuts are displayed as a reference at the bottom of the screen. An
31098 example of one of these shortcuts is the r key, which tells the MUA to
31099 reply to the current message being displayed.
31101 Replying to an email in pine is done using the pico editor, which is
31102 installed by default with pine. The pico utility makes it easy to navigate
31103 around the message and is slightly more forgiving on novice users than
31104 vi(1) or mail(1). Once the reply is complete, the message can be sent by
31105 pressing Ctrl+X. The pine application will ask for confirmation.
31107 The pine application can be customized using the SETUP option from the
31108 main menu. Consult http://www.washington.edu/pine/ for more information.
31110 ----------------------------------------------------------------------
31112 20.12 Using fetchmail
31114 Contributed by Marc Silver.
31116 fetchmail is a full-featured IMAP and POP client which allows users to
31117 automatically download mail from remote IMAP and POP servers and save it
31118 into local mailboxes; there it can be accessed more easily. fetchmail can
31119 be installed using the mail/fetchmail port, and offers various features,
31120 some of which include:
31122 * Support of POP3, APOP, KPOP, IMAP, ETRN and ODMR protocols.
31124 * Ability to forward mail using SMTP, which allows filtering,
31125 forwarding, and aliasing to function normally.
31127 * May be run in daemon mode to check periodically for new messages.
31129 * Can retrieve multiple mailboxes and forward them based on
31130 configuration, to different local users.
31132 While it is outside the scope of this document to explain all of
31133 fetchmail's features, some basic features will be explained. The fetchmail
31134 utility requires a configuration file known as .fetchmailrc, in order to
31135 run correctly. This file includes server information as well as login
31136 credentials. Due to the sensitive nature of the contents of this file, it
31137 is advisable to make it readable only by the owner, with the following
31140 % chmod 600 .fetchmailrc
31142 The following .fetchmailrc serves as an example for downloading a single
31143 user mailbox using POP. It tells fetchmail to connect to example.com using
31144 a username of joesoap and a password of XXX. This example assumes that the
31145 user joesoap is also a user on the local system.
31147 poll example.com protocol pop3 username "joesoap" password "XXX"
31149 The next example connects to multiple POP and IMAP servers and redirects
31150 to different local usernames where applicable:
31152 poll example.com proto pop3:
31153 user "joesoap", with password "XXX", is "jsoap" here;
31154 user "andrea", with password "XXXX";
31155 poll example2.net proto imap:
31156 user "john", with password "XXXXX", is "myth" here;
31158 The fetchmail utility can be run in daemon mode by running it with the -d
31159 flag, followed by the interval (in seconds) that fetchmail should poll
31160 servers listed in the .fetchmailrc file. The following example would cause
31161 fetchmail to poll every 60 seconds:
31165 More information on fetchmail can be found at
31166 http://www.catb.org/~esr/fetchmail/.
31168 ----------------------------------------------------------------------
31170 20.13 Using procmail
31172 Contributed by Marc Silver.
31174 The procmail utility is an incredibly powerful application used to filter
31175 incoming mail. It allows users to define ``rules'' which can be matched to
31176 incoming mails to perform specific functions or to reroute mail to
31177 alternative mailboxes and/or email addresses. procmail can be installed
31178 using the mail/procmail port. Once installed, it can be directly
31179 integrated into most MTAs; consult your MTA documentation for more
31180 information. Alternatively, procmail can be integrated by adding the
31181 following line to a .forward in the home directory of the user utilizing
31184 "|exec /usr/local/bin/procmail || exit 75"
31186 The following section will display some basic procmail rules, as well as
31187 brief descriptions on what they do. These rules, and others must be
31188 inserted into a .procmailrc file, which must reside in the user's home
31193 The majority of these rules can also be found in the procmailex(5) manual
31196 Forward all mail from user@example.com to an external address of
31197 goodmail@example2.com:
31200 * ^From.*user@example.com
31201 ! goodmail@example2.com
31203 Forward all mails shorter than 1000 bytes to an external address of
31204 goodmail@example2.com:
31208 ! goodmail@example2.com
31210 Send all mail sent to alternate@example.com into a mailbox called
31214 * ^TOalternate@example.com
31217 Send all mail with a subject of ``Spam'' to /dev/null:
31223 A useful recipe that parses incoming dragonflybsd.org mailing lists and
31224 places each list in its own mailbox:
31227 * ^List-Post: <mailto:\/[^@]+
31231 * LISTNAME??^\/[^-]+
31235 ----------------------------------------------------------------------
31237 Chapter 21 Updating DragonFly
31239 Written by Justin Sherrill.
31243 Updates to the DragonFly source code is performed using cvsup. cvsup
31244 compares your local system source or ports files to a remote repository,
31245 and downloads any changes. Only the differences in the files are
31246 downloaded, saving on bandwidth and time.
31248 cvsup exists as a port (net/cvsup) and traditionally had to be installed
31249 separately on FreeBSD. With DragonFly, the binary is installed as part of
31252 ----------------------------------------------------------------------
31256 cvsup is guided by a configuration file that describes what files to
31257 update, and the source from which to update them.
31259 Here is a basic DragonFly cvsup configuration file:
31261 *default host=cvsup.dragonflybsd.org
31263 *default prefix=/usr
31264 *default release=cvs
31265 *default release=cvs tag=.
31266 *default delete use-rel-suffix
31272 Alternately, the file /usr/share/examples/cvsup/DragonFly-src-supfile can
31273 be used as-is to update system source.
31275 Run cvsup using /usr/share/examples/cvsup/DragonFly-src-supfile as an
31276 argument or with a separate file containing the above example text. Your
31277 system source files will be updated.
31279 ----------------------------------------------------------------------
31281 21.3 Preparing to Update
31283 If you want to create a custom kernel, see Chapter 9. This is not needed
31284 to update your system unless there is a specific feature that needs to be
31285 added to the kernel.
31287 Check recent mail traffic on DragonFly Kernel mailing list and the file
31288 /usr/src/UPDATING. Any recent problems or changes should be described
31289 there. /usr/src/UPDATING also contains abbreviated build instructions in
31290 case these directions are not available.
31292 ----------------------------------------------------------------------
31294 21.4 Updating the System
31296 Updating the system is a relatively simple process. As root, in /usr/src:
31299 % make buildkernel KERNCONF=GENERIC
31300 % make installkernel KERNCONF=GENERIC
31301 % make installworld
31305 An explanation of each step follows.
31307 * make buildworld : This command rebuilds all userland programs. This is
31308 the most time-consuming step.
31310 * make buildkernel KERNCONF=GENERIC : This builds the kernel using the
31311 config file specified by KERNCONF. If you've created a different
31312 kernel configuration file as detailed in Chapter 9, use that instead
31313 of GENERIC. If KERNCONF isn't specified, the GENERIC configuration
31314 file (installed by default) is used.
31316 * make installkernel KERNCONF=GENERIC : This installs the kernel using
31317 the config file specified by KERNCONF. The value of KERNCONF must
31318 match what was specified in the make buildkernel command, so that
31319 files that match this configuration can be installed correctly. As
31320 with make buildkernel, KERNCONF will be set to GENERIC if not
31321 otherwise specified.
31323 * make installworld : This copies all the files built in the buildworld
31324 step (i.e. everything that is not the kernel) to the proper places in
31327 * make upgrade : This cleans out any files made unnecessary by this
31330 * (reboot) : Reboot the computer to load the new kernel and use the new
31331 files installed as part of this process.
31333 If your computer fails to reboot, check the Section 9.6 section of the
31336 ----------------------------------------------------------------------
31338 Chapter 22 Linux Binary Compatibility
31340 Restructured and parts updated by Jim Mock. Originally contributed by
31341 Brian N. Handy and Rich Murphey.
31345 DragonFly provides binary compatibility with several other UNIX like
31346 operating systems, including Linux. At this point, you may be asking
31347 yourself why exactly, does DragonFly need to be able to run Linux
31348 binaries? The answer to that question is quite simple. Many companies and
31349 developers develop only for Linux, since it is the latest ``hot thing'' in
31350 the computing world. That leaves the rest of us DragonFly users bugging
31351 these same companies and developers to put out native DragonFly versions
31352 of their applications. The problem is, that most of these companies do not
31353 really realize how many people would use their product if there were
31354 DragonFly versions too, and most continue to only develop for Linux. So
31355 what is a DragonFly user to do? This is where the Linux binary
31356 compatibility of DragonFly comes into play.
31358 In a nutshell, the compatibility allows DragonFly users to run about 90%
31359 of all Linux applications without modification. This includes applications
31360 such as StarOffice, the Linux version of Netscape, Adobe(R) Acrobat(R),
31361 RealPlayer(R) 5 and 7, VMware(TM), Oracle, WordPerfect(R), Doom, Quake,
31362 and more. It is also reported that in some situations, Linux binaries
31363 perform better on DragonFly than they do under Linux.
31365 There are, however, some Linux-specific operating system features that are
31366 not supported under DragonFly. Linux binaries will not work on DragonFly
31367 if they overly use the Linux /proc file system (which is different from
31368 DragonFly's /proc file system), or i386 specific calls, such as enabling
31371 After reading this chapter, you will know:
31373 * How to enable Linux binary compatibility on your system.
31375 * How to install additional Linux shared libraries.
31377 * How to install Linux applications on your DragonFly system.
31379 * The implementation details of Linux compatibility in DragonFly.
31381 Before reading this chapter, you should:
31383 * Know how to install additional third-party software (Chapter 4).
31385 ----------------------------------------------------------------------
31389 Linux binary compatibility is not turned on by default. The easiest way to
31390 enable this functionality is to load the linux KLD object (``Kernel
31391 Loadable Device''). You can load this module by simply typing linux at the
31394 If you would like Linux compatibility to always be enabled, then you
31395 should add the following line to /etc/rc.conf:
31399 The kldstat(8) command can be used to verify that the KLD is loaded:
31402 Id Refs Address Size Name
31403 1 2 0xc0100000 16bdb8 kernel
31404 7 1 0xc24db000 d000 linux.ko
31406 If for some reason you do not want to or cannot load the KLD, then you may
31407 statically link Linux binary compatibility into the kernel by adding
31408 options COMPAT_LINUX to your kernel configuration file. Then install your
31409 new kernel as described in Chapter 9.
31411 ----------------------------------------------------------------------
31413 22.2.1 Installing Linux Runtime Libraries
31415 This can be done one of two ways, either by using the suse package, or by
31416 installing them manually.
31418 ----------------------------------------------------------------------
31420 22.2.1.1 Installing Using suse Package
31422 This is by far the easiest method to use when installing the runtime
31423 libraries. It is just like installing any other package from the pkgsrc
31424 collection. Simply do the following:
31426 # cd /usr/pkgsrc/meta-pkgs/suse9
31427 # make install distclean
31428 # ln -s /usr/pkg/emul /compat
31430 You should now have working Linux binary compatibility. Some programs may
31431 complain about incorrect minor versions of the system libraries. In
31432 general, however, this does not seem to be a problem.
31434 Note: There may be multiple versions of the meta-pkgs/suse package
31435 available, corresponding to different versions of various Linux
31436 distributions. You should install the package most closely resembling
31437 the requirements of the Linux applications you would like to install.
31439 ----------------------------------------------------------------------
31441 22.2.1.2 Installing Libraries Manually
31443 If you do not have the ``pkgsrc'' collection installed, you can install
31444 the libraries by hand instead. You will need the Linux shared libraries
31445 that the program depends on and the runtime linker. Also, you will need to
31446 create a ``shadow root'' directory, /compat/linux, for Linux libraries on
31447 your DragonFly system. Any shared libraries opened by Linux programs run
31448 under DragonFly will look in this tree first. So, if a Linux program
31449 loads, for example, /lib/libc.so, DragonFly will first try to open
31450 /compat/linux/lib/libc.so, and if that does not exist, it will then try
31451 /lib/libc.so. Shared libraries should be installed in the shadow tree
31452 /compat/linux/lib rather than the paths that the Linux ld.so reports.
31454 Generally, you will need to look for the shared libraries that Linux
31455 binaries depend on only the first few times that you install a Linux
31456 program on your DragonFly system. After a while, you will have a
31457 sufficient set of Linux shared libraries on your system to be able to run
31458 newly imported Linux binaries without any extra work.
31460 ----------------------------------------------------------------------
31462 22.2.1.3 How to Install Additional Shared Libraries
31464 What if you install the suse package and your application still complains
31465 about missing shared libraries? How do you know which shared libraries
31466 Linux binaries need, and where to get them? Basically, there are 2
31467 possibilities (when following these instructions you will need to be root
31468 on your DragonFly system).
31470 If you have access to a Linux system, see what shared libraries the
31471 application needs, and copy them to your DragonFly system. Look at the
31474 Let us assume you used FTP to get the Linux binary of Doom, and put it on
31475 a Linux system you have access to. You then can check which shared
31476 libraries it needs by running ldd linuxdoom, like so:
31479 libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
31480 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
31481 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
31483 You would need to get all the files from the last column, and put them
31484 under /compat/linux, with the names in the first column as symbolic links
31485 pointing to them. This means you eventually have these files on your
31488 /compat/linux/usr/X11/lib/libXt.so.3.1.0
31489 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
31490 /compat/linux/usr/X11/lib/libX11.so.3.1.0
31491 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
31492 /compat/linux/lib/libc.so.4.6.29
31493 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
31495 Note: Note that if you already have a Linux shared library with a
31496 matching major revision number to the first column of the ldd output,
31497 you will not need to copy the file named in the last column to your
31498 system, the one you already have should work. It is advisable to copy
31499 the shared library anyway if it is a newer version, though. You can
31500 remove the old one, as long as you make the symbolic link point to the
31501 new one. So, if you have these libraries on your system:
31503 /compat/linux/lib/libc.so.4.6.27
31504 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27
31506 and you find a new binary that claims to require a later version
31507 according to the output of ldd:
31509 libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29
31511 If it is only one or two versions out of date in the in the trailing
31512 digit then do not worry about copying /lib/libc.so.4.6.29 too, because
31513 the program should work fine with the slightly older version. However,
31514 if you like, you can decide to replace the libc.so anyway, and that
31515 should leave you with:
31517 /compat/linux/lib/libc.so.4.6.29
31518 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
31520 Note: The symbolic link mechanism is only needed for Linux binaries.
31521 The DragonFly runtime linker takes care of looking for matching major
31522 revision numbers itself and you do not need to worry about it.
31524 ----------------------------------------------------------------------
31526 22.2.2 Installing Linux ELF Binaries
31528 ELF binaries sometimes require an extra step of ``branding''. If you
31529 attempt to run an unbranded ELF binary, you will get an error message like
31532 % ./my-linux-elf-binary
31533 ELF binary type not known
31536 To help the DragonFly kernel distinguish between a DragonFly ELF binary
31537 from a Linux binary, use the brandelf(1) utility.
31539 % brandelf -t Linux my-linux-elf-binary
31541 The GNU toolchain now places the appropriate branding information into ELF
31542 binaries automatically, so this step should only be needed for older,
31545 ----------------------------------------------------------------------
31547 22.2.3 Configuring the Hostname Resolver
31549 If DNS does not work or you get this message:
31551 resolv+: "bind" is an invalid keyword resolv+:
31552 "hosts" is an invalid keyword
31554 You will need to configure a /compat/linux/etc/host.conf file containing:
31559 The order here specifies that /etc/hosts is searched first and DNS is
31560 searched second. When /compat/linux/etc/host.conf is not installed, Linux
31561 applications find DragonFly's /etc/host.conf and complain about the
31562 incompatible DragonFly syntax. You should remove bind if you have not
31563 configured a name server using the /etc/resolv.conf file.
31565 ----------------------------------------------------------------------
31567 22.3 Installing Mathematica(R)
31569 Updated for Mathematica 4.X by Murray Stokely. Merged with work by Bojan
31572 This document describes the process of installing the Linux version of
31573 Mathematica 4.X onto a DragonFly system.
31575 Warning: This description applies to FreeBSD, for which it was
31576 originally written. This may or may not apply to DragonFly at this
31577 point; while FreeBSD 4.x features usually translate over to DragonFly
31578 well, your mileage may vary.
31580 The Linux version of Mathematica runs perfectly under DragonFly however
31581 the binaries shipped by Wolfram need to be branded so that DragonFly knows
31582 to use the Linux ABI to execute them.
31584 The Linux version of Mathematica or Mathematica for Students can be
31585 ordered directly from Wolfram at http://www.wolfram.com/.
31587 ----------------------------------------------------------------------
31589 22.3.1 Branding the Linux Binaries
31591 The Linux binaries are located in the Unix directory of the Mathematica
31592 CDROM distributed by Wolfram. You need to copy this directory tree to your
31593 local hard drive so that you can brand the Linux binaries with brandelf(1)
31594 before running the installer:
31597 # cp -rp /cdrom/Unix/ /localdir/
31598 # brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*
31599 # brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*
31600 # brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*
31601 # brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*
31602 # brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*
31603 # brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm
31604 # cd /localdir/Installers/Linux/
31607 Alternatively, you can simply set the default ELF brand to Linux for all
31608 unbranded binaries with the command:
31610 # sysctl kern.fallback_elf_brand=3
31612 This will make DragonFly assume that unbranded ELF binaries use the Linux
31613 ABI and so you should be able to run the installer straight from the
31616 ----------------------------------------------------------------------
31618 22.3.2 Obtaining Your Mathematica Password
31620 Before you can run Mathematica you will have to obtain a password from
31621 Wolfram that corresponds to your ``machine ID''.
31623 Once you have installed the Linux compatibility runtime libraries and
31624 unpacked Mathematica you can obtain the ``machine ID'' by running the
31625 program mathinfo in the installation directory. This machine ID is based
31626 solely on the MAC address of your first Ethernet card.
31628 # cd /localdir/Files/SystemFiles/Installation/Binaries/Linux
31630 disco.example.com 7115-70839-20412
31632 When you register with Wolfram, either by email, phone or fax, you will
31633 give them the ``machine ID'' and they will respond with a corresponding
31634 password consisting of groups of numbers. You can then enter this
31635 information when you attempt to run Mathematica for the first time exactly
31636 as you would for any other Mathematica platform.
31638 ----------------------------------------------------------------------
31640 22.3.3 Running the Mathematica Frontend over a Network
31642 Mathematica uses some special fonts to display characters not present in
31643 any of the standard font sets (integrals, sums, Greek letters, etc.). The
31644 X protocol requires these fonts to be install locally. This means you will
31645 have to copy these fonts from the CDROM or from a host with Mathematica
31646 installed to your local machine. These fonts are normally stored in
31647 /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or
31648 /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual
31649 fonts are in the subdirectories Type1 and X. There are several ways to use
31650 them, as described below.
31652 The first way is to copy them into one of the existing font directories in
31653 /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file,
31654 adding the font names to it, and changing the number of fonts on the first
31655 line. Alternatively, you should also just be able to run mkfontdir(1) in
31656 the directory you have copied them to.
31658 The second way to do this is to copy the directories to
31659 /usr/X11R6/lib/X11/fonts:
31661 # cd /usr/X11R6/lib/X11/fonts
31664 # cd /cdrom/Unix/Files/SystemFiles/Fonts
31665 # cp X/* /usr/X11R6/lib/X11/fonts/X
31666 # cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1
31667 # cd /usr/X11R6/lib/X11/fonts/X
31672 Now add the new font directories to your font path:
31674 # xset fp+ /usr/X11R6/lib/X11/fonts/X
31675 # xset fp+ /usr/X11R6/lib/X11/fonts/MathType1
31678 If you are using the XFree86 server, you can have these font directories
31679 loaded automatically by adding them to your XF86Config file.
31681 If you do not already have a directory called
31682 /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1
31683 directory in the example above to Type1.
31685 ----------------------------------------------------------------------
31687 22.4 Installing Maple(TM)
31689 Contributed by Aaron Kaplan. Thanks to Robert Getschmann.
31691 Maple(TM) is a commercial mathematics program similar to Mathematica. You
31692 must purchase this software from http://www.maplesoft.com/ and then
31693 register there for a license file. To install this software on DragonFly,
31694 please follow these simple steps.
31696 Warning: This description applies to FreeBSD, for which it was
31697 originally written. This may or may not apply to DragonFly at this
31698 point; while FreeBSD 4.x features usually translate over to DragonFly
31699 well, your mileage may vary.
31701 1. Execute the INSTALL shell script from the product distribution. Choose
31702 the ``RedHat'' option when prompted by the installation program. A
31703 typical installation directory might be /usr/local/maple.
31705 2. If you have not done so, order a license for Maple from Maple Waterloo
31706 Software (http://register.maplesoft.com/) and copy it to
31707 /usr/local/maple/license/license.dat.
31709 3. Install the FLEXlm license manager by running the INSTALL_LIC install
31710 shell script that comes with Maple. Specify the primary hostname for
31711 your machine for the license server.
31713 4. Patch the /usr/local/maple/bin/maple.system.type file with the
31716 ----- snip ------------------
31717 *** maple.system.type.orig Sun Jul 8 16:35:33 2001
31718 --- maple.system.type Sun Jul 8 16:35:51 2001
31722 # the IBM RS/6000 AIX case
31723 MAPLE_BIN="bin.IBM_RISC_UNIX"
31727 # the Linux/x86 case
31728 # We have two Linux implementations, one for Red Hat and
31729 ----- snip end of patch -----
31731 Please note that after the "DragonFly"|\ no other whitespace should be
31734 This patch instructs Maple to recognize ``DragonFly'' as a type of
31735 Linux system. The bin/maple shell script calls the
31736 bin/maple.system.type shell script which in turn calls uname -a to
31737 find out the operating system name. Depending on the OS name it will
31738 find out which binaries to use.
31740 5. Start the license server.
31742 The following script, installed as /usr/local/etc/rc.d/lmgrd.sh is a
31743 convenient way to start up lmgrd:
31745 ----- snip ------------
31748 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
31749 PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
31752 LICENSE_FILE=/usr/local/maple/license/license.dat
31753 LOG=/var/log/lmgrd.log
31757 lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
31761 lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
31764 echo "Usage: `basename $0` {start|stop}" 1>&2
31770 ----- snip ------------
31772 6. Test-start Maple:
31774 % cd /usr/local/maple/bin
31777 You should be up and running. Make sure to write Maplesoft to let them
31778 know you would like a native DragonFly version!
31780 ----------------------------------------------------------------------
31782 22.4.1 Common Pitfalls
31784 * The FLEXlm license manager can be a difficult tool to work with.
31785 Additional documentation on the subject can be found at
31786 http://www.globetrotter.com/.
31788 * lmgrd is known to be very picky about the license file and to core
31789 dump if there are any problems. A correct license file should look
31792 # =======================================================
31793 # License File for UNIX Installations ("Pointer File")
31794 # =======================================================
31799 FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
31800 PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
31801 ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
31804 Note: Serial number and key 'X''ed out. chillig is a hostname.
31806 Editing the license file works as long as you do not touch the
31807 ``FEATURE'' line (which is protected by the license key).
31809 ----------------------------------------------------------------------
31811 22.5 Installing MATLAB(R)
31813 Contributed by Dan Pelleg.
31815 This document describes the process of installing the Linux version of
31816 MATLAB(R) version 6.5 onto a DragonFly system. It works quite well, with
31817 the exception of the Java Virtual Machine(TM) (see Section 22.5.3).
31819 The Linux version of MATLAB can be ordered directly from The MathWorks at
31820 http://www.mathworks.com. Make sure you also get the license file or
31821 instructions how to create it. While you are there, let them know you
31822 would like a native DragonFly version of their software.
31824 ----------------------------------------------------------------------
31826 22.5.1 Installing MATLAB
31828 To install MATLAB, do the following:
31830 1. Insert the installation CD and mount it. Become root, as recommended
31831 by the installation script. To start the installation script type:
31833 # /compat/linux/bin/sh /cdrom/install
31835 Tip: The installer is graphical. If you get errors about not being
31836 able to open a display, type setenv HOME ~USER, where USER is the
31837 user you did a su(1) as.
31839 2. When asked for the MATLAB root directory, type:
31840 /compat/linux/usr/local/matlab.
31842 Tip: For easier typing on the rest of the installation process, type
31843 this at your shell prompt: set MATLAB=/compat/linux/usr/local/matlab
31845 3. Edit the license file as instructed when obtaining the MATLAB license.
31847 Tip: You can prepare this file in advance using your favorite
31848 editor, and copy it to $MATLAB/license.dat before the installer asks
31851 4. Complete the installation process.
31853 At this point your MATLAB installation is complete. The following steps
31854 apply ``glue'' to connect it to your DragonFly system.
31856 ----------------------------------------------------------------------
31858 22.5.2 License Manager Startup
31860 1. Create symlinks for the license manager scripts:
31862 # ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW
31863 # ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW
31865 2. Create a startup file at /usr/local/etc/rc.d/flexlm.sh. The example
31866 below is a modified version of the distributed
31867 $MATLAB/etc/rc.lm.glnx86. The changes are file locations, and startup
31868 of the license manager under Linux emulation.
31873 if [ -f /usr/local/etc/lmboot_TMW ]; then
31874 /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd'
31878 if [ -f /usr/local/etc/lmdown_TMW ]; then
31879 /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1
31883 echo "Usage: $0 {start|stop}"
31890 Important: The file must be made executable:
31892 # chmod +x /usr/local/etc/rc.d/flexlm.sh
31894 You must also replace username above with the name of a valid user
31895 on your system (and not root).
31897 3. Start the license manager with the command:
31899 # /usr/local/etc/rc.d/flexlm.sh start
31901 ----------------------------------------------------------------------
31903 22.5.3 Linking the Java Runtime Environment
31905 Change the Java Runtime Environment (JRE) link to one working under
31908 # cd $MATLAB/sys/java/jre/glnx86/
31909 # unlink jre; ln -s ./jre1.1.8 ./jre
31911 ----------------------------------------------------------------------
31913 22.5.4 Creating a MATLAB Startup Script
31915 1. Place the following startup script in /usr/local/bin/matlab:
31918 /compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"
31920 2. Then type the command chmod +x /usr/local/bin/matlab.
31922 Tip: Depending on your version of emulators/linux_base, you may run into
31923 errors when running this script. To avoid that, edit the file
31924 /compat/linux/usr/local/matlab/bin/matlab, and change the line that
31927 if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then
31929 (in version 13.0.1 it is on line 410) to this line:
31931 if test -L $newbase; then
31933 ----------------------------------------------------------------------
31935 22.5.5 Creating a MATLAB Shutdown Script
31937 The following is needed to solve a problem with MATLAB not exiting
31940 1. Create a file $MATLAB/toolbox/local/finish.m, and in it put the single
31943 ! $MATLAB/bin/finish.sh
31945 Note: The $MATLAB is literal.
31947 Tip: In the same directory, you will find the files finishsav.m and
31948 finishdlg.m, which let you save your workspace before quitting. If
31949 you use either of them, insert the line above immediately after the
31952 2. Create a file $MATLAB/bin/finish.sh, which will contain the following:
31954 #!/usr/compat/linux/bin/sh
31955 (sleep 5; killall -1 matlab_helper) &
31958 3. Make the file executable:
31960 # chmod +x $MATLAB/bin/finish.sh
31962 ----------------------------------------------------------------------
31964 22.5.6 Using MATLAB
31966 At this point you are ready to type matlab and start using it.
31968 ----------------------------------------------------------------------
31970 22.6 Installing Oracle(R)
31972 Contributed by Marcel Moolenaar.
31974 ----------------------------------------------------------------------
31978 This document describes the process of installing Oracle 8.0.5 and Oracle
31979 8.0.5.1 Enterprise Edition for Linux onto a DragonFly machine.
31981 Warning: This description applies to FreeBSD, for which it was
31982 originally written. This may or may not apply to DragonFly at this
31983 point; while FreeBSD 4.x features usually translate over to DragonFly
31984 well, your mileage may vary.
31986 ----------------------------------------------------------------------
31988 22.6.2 Installing the Linux Environment
31990 Make sure you have both emulators/linux_base and devel/linux_devtools from
31991 the ports collection installed. If you run into difficulties with these
31992 ports, you may have to use the packages or older versions available in the
31995 If you want to run the intelligent agent, you will also need to install
31996 the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for
31997 installing packages with the official RPM port (archivers/rpm) is:
31999 # rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package
32001 Installation of the package should not generate any errors.
32003 ----------------------------------------------------------------------
32005 22.6.3 Creating the Oracle Environment
32007 Before you can install Oracle, you need to set up a proper environment.
32008 This document only describes what to do specially to run Oracle for Linux
32009 on DragonFly, not what has been described in the Oracle installation
32012 ----------------------------------------------------------------------
32014 22.6.3.1 Kernel Tuning
32016 As described in the Oracle installation guide, you need to set the maximum
32017 size of shared memory. Do not use SHMMAX under DragonFly. SHMMAX is merely
32018 calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All
32019 other options can be used as described in the guide. For example:
32021 options SHMMAXPGS=10000
32028 Set these options to suit your intended use of Oracle.
32030 Also, make sure you have the following options in your kernel
32031 configuration file:
32033 options SYSVSHM #SysV shared memory
32034 options SYSVSEM #SysV semaphores
32035 options SYSVMSG #SysV interprocess communication
32037 ----------------------------------------------------------------------
32039 22.6.3.2 Oracle Account
32041 Create an oracle account just as you would create any other account. The
32042 oracle account is special only that you need to give it a Linux shell. Add
32043 /compat/linux/bin/bash to /etc/shells and set the shell for the oracle
32044 account to /compat/linux/bin/bash.
32046 ----------------------------------------------------------------------
32048 22.6.3.3 Environment
32050 Besides the normal Oracle variables, such as ORACLE_HOME and ORACLE_SID
32051 you must set the following environment variables:
32054 LD_LIBRARY_PATH $ORACLE_HOME/lib
32055 CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip
32056 /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin
32057 PATH /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin
32058 /usr/local/bin $ORACLE_HOME/bin
32060 It is advised to set all the environment variables in .profile. A complete
32063 ORACLE_BASE=/oracle; export ORACLE_BASE
32064 ORACLE_HOME=/oracle; export ORACLE_HOME
32065 LD_LIBRARY_PATH=$ORACLE_HOME/lib
32066 export LD_LIBRARY_PATH
32067 ORACLE_SID=ORCL; export ORACLE_SID
32068 ORACLE_TERM=386x; export ORACLE_TERM
32069 CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
32071 PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
32072 PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
32073 PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
32076 ----------------------------------------------------------------------
32078 22.6.4 Installing Oracle
32080 Due to a slight inconsistency in the Linux emulator, you need to create a
32081 directory named .oracle in /var/tmp before you start the installer. Either
32082 make it world writable or let it be owned by the oracle user. You should
32083 be able to install Oracle without any problems. If you have problems,
32084 check your Oracle distribution and/or configuration first! After you have
32085 installed Oracle, apply the patches described in the next two subsections.
32087 A frequent problem is that the TCP protocol adapter is not installed
32088 right. As a consequence, you cannot start any TCP listeners. The following
32089 actions help solve this problem:
32091 # cd $ORACLE_HOME/network/lib
32092 # make -f ins_network.mk ntcontab.o
32093 # cd $ORACLE_HOME/lib
32094 # ar r libnetwork.a ntcontab.o
32095 # cd $ORACLE_HOME/network/lib
32096 # make -f ins_network.mk install
32098 Do not forget to run root.sh again!
32100 ----------------------------------------------------------------------
32102 22.6.4.1 Patching root.sh
32104 When installing Oracle, some actions, which need to be performed as root,
32105 are recorded in a shell script called root.sh. This script is written in
32106 the orainst directory. Apply the following patch to root.sh, to have it
32107 use to proper location of chown or alternatively run the script under a
32108 Linux native shell.
32110 *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
32111 --- orainst/root.sh Mon Dec 28 15:58:53 1998
32114 # This is the default value for CHOWN
32115 # It will redefined later in this script for those ports
32116 # which have it conditionally defined in ss_install.h
32119 # Define variables to be used in this script
32121 # This is the default value for CHOWN
32122 # It will redefined later in this script for those ports
32123 # which have it conditionally defined in ss_install.h
32124 ! CHOWN=/usr/sbin/chown
32126 # Define variables to be used in this script
32128 When you do not install Oracle from CD, you can patch the source for
32129 root.sh. It is called rthd.sh and is located in the orainst directory in
32132 ----------------------------------------------------------------------
32134 22.6.4.2 Patching genclntsh
32136 The script genclntsh is used to create a single shared client library. It
32137 is used when building the demos. Apply the following patch to comment out
32138 the definition of PATH:
32140 *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
32141 --- bin/genclntsh Tue Dec 22 15:36:49 1998
32145 # Explicit path to ensure that we're using the correct commands
32146 #PATH=/usr/bin:/usr/ccs/bin export PATH
32147 ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
32149 # each product MUST provide a $PRODUCT/admin/shrept.lst
32152 # Explicit path to ensure that we're using the correct commands
32153 #PATH=/usr/bin:/usr/ccs/bin export PATH
32154 ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
32156 # each product MUST provide a $PRODUCT/admin/shrept.lst
32158 ----------------------------------------------------------------------
32160 22.6.5 Running Oracle
32162 When you have followed the instructions, you should be able to run Oracle
32163 as if it was run on Linux itself.
32165 ----------------------------------------------------------------------
32167 22.7 Installing SAP(R) R/3(R)
32169 Contributed by Holger Kipp. Original version converted to SGML by
32170 Valentino Vaschetto.
32172 Installations of SAP Systems using DragonFly will not be supported by the
32173 SAP support team -- they only offer support for certified platforms.
32175 Warning: This description applies to FreeBSD, for which it was
32176 originally written. This may or may not apply to DragonFly at this
32177 point; while FreeBSD 4.x features usually translate over to DragonFly
32178 well, your mileage may vary.
32180 ----------------------------------------------------------------------
32184 This document describes a possible way of installing a SAP R/3 System with
32185 Oracle Database for Linux onto a DragonFly machine, including the
32186 installation of DragonFly and Oracle. Two different configurations will be
32189 * SAP R/3 4.6B (IDES) with Oracle 8.0.5 on FreeBSD 4.3-STABLE
32191 * SAP R/3 4.6C with Oracle 8.1.7 on FreeBSD 4.5-STABLE
32193 Even though this document tries to describe all important steps in a
32194 greater detail, it is not intended as a replacement for the Oracle and
32195 SAP R/3 installation guides.
32197 Please see the documentation that comes with the SAP R/3 Linux edition for
32198 SAP and Oracle specific questions, as well as resources from Oracle and
32201 ----------------------------------------------------------------------
32205 The following CD-ROMs have been used for SAP installations:
32207 ----------------------------------------------------------------------
32209 22.7.2.1 SAP R/3 4.6B, Oracle 8.0.5
32211 +------------------------------------------------------------------------+
32212 | Name | Number | Description |
32213 |---------+----------+---------------------------------------------------|
32214 | KERNEL | 51009113 | SAP Kernel Oracle / Installation / AIX, Linux, |
32216 |---------+----------+---------------------------------------------------|
32217 | RDBMS | 51007558 | Oracle / RDBMS 8.0.5.X / Linux |
32218 |---------+----------+---------------------------------------------------|
32219 | EXPORT1 | 51010208 | IDES / DB-Export / Disc 1 of 6 |
32220 |---------+----------+---------------------------------------------------|
32221 | EXPORT2 | 51010209 | IDES / DB-Export / Disc 2 of 6 |
32222 |---------+----------+---------------------------------------------------|
32223 | EXPORT3 | 51010210 | IDES / DB-Export / Disc 3 of 6 |
32224 |---------+----------+---------------------------------------------------|
32225 | EXPORT4 | 51010211 | IDES / DB-Export / Disc 4 of 6 |
32226 |---------+----------+---------------------------------------------------|
32227 | EXPORT5 | 51010212 | IDES / DB-Export / Disc 5 of 6 |
32228 |---------+----------+---------------------------------------------------|
32229 | EXPORT6 | 51010213 | IDES / DB-Export / Disc 6 of 6 |
32230 +------------------------------------------------------------------------+
32232 Additionally, we used the Oracle 8 Server (Pre-production version 8.0.5
32233 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and
32234 FreeBSD 4.3-STABLE (it was only a few days past 4.3 RELEASE).
32236 ----------------------------------------------------------------------
32238 22.7.2.2 SAP R/3 4.6C SR2, Oracle 8.1.7
32240 +------------------------------------------------------------------------+
32241 | Name | Number | Description |
32242 |---------+----------+---------------------------------------------------|
32243 | KERNEL | 51014004 | SAP Kernel Oracle / SAP Kernel Version 4.6D / |
32245 |---------+----------+---------------------------------------------------|
32246 | RDBMS | 51012930 | Oracle 8.1.7/ RDBMS / Linux |
32247 |---------+----------+---------------------------------------------------|
32248 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 1 of 4 |
32249 |---------+----------+---------------------------------------------------|
32250 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 2 of 4 |
32251 |---------+----------+---------------------------------------------------|
32252 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 3 of 4 |
32253 |---------+----------+---------------------------------------------------|
32254 | EXPORT1 | 51013953 | Release 4.6C SR2 / Export / Disc 4 of 4 |
32255 |---------+----------+---------------------------------------------------|
32256 | LANG1 | 51013954 | Release 4.6C SR2 / Language / DE, EN, FR / Disc 1 |
32258 +------------------------------------------------------------------------+
32260 Depending on the languages you would like to install, additional language
32261 CDs might be necessary. Here we are just using DE and EN, so the first
32262 language CD is the only one needed. As a little note, the numbers for all
32263 four EXPORT CDs are identical. All three language CDs also have the same
32264 number (this is different from the 4.6B IDES release CD numbering). At the
32265 time of writing this installation is running on FreeBSD 4.5-STABLE
32268 ----------------------------------------------------------------------
32272 The following notes should be read before installing SAP R/3 and proved to
32273 be useful during installation:
32275 ----------------------------------------------------------------------
32277 22.7.3.1 SAP R/3 4.6B, Oracle 8.0.5
32279 +-----------------------------------------------------------------+
32281 |---------+-------------------------------------------------------|
32282 | 0171356 | SAP Software on Linux: Essential Comments |
32283 |---------+-------------------------------------------------------|
32284 | 0201147 | INST: 4.6C R/3 Inst. on UNIX - Oracle |
32285 |---------+-------------------------------------------------------|
32286 | 0373203 | Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX |
32287 |---------+-------------------------------------------------------|
32288 | 0072984 | Release of Digital UNIX 4.0B for Oracle |
32289 |---------+-------------------------------------------------------|
32290 | 0130581 | R3SETUP step DIPGNTAB terminates |
32291 |---------+-------------------------------------------------------|
32292 | 0144978 | Your system has not been installed correctly |
32293 |---------+-------------------------------------------------------|
32294 | 0162266 | Questions and tips for R3SETUP on Windows NT / W2K |
32295 +-----------------------------------------------------------------+
32297 ----------------------------------------------------------------------
32299 22.7.3.2 SAP R/3 4.6C, Oracle 8.1.7
32301 +----------------------------------------------------------+
32303 |---------+------------------------------------------------|
32304 | 0015023 | Initializing table TCPDB (RSXP0004) (EBCDIC) |
32305 |---------+------------------------------------------------|
32306 | 0045619 | R/3 with several languages or typefaces |
32307 |---------+------------------------------------------------|
32308 | 0171356 | SAP Software on Linux: Essential Comments |
32309 |---------+------------------------------------------------|
32310 | 0195603 | RedHat 6.1 Enterprise version: Known problems |
32311 |---------+------------------------------------------------|
32312 | 0212876 | The new archiving tool SAPCAR |
32313 |---------+------------------------------------------------|
32314 | 0300900 | Linux: Released DELL Hardware |
32315 |---------+------------------------------------------------|
32316 | 0377187 | RedHat 6.2: important remarks |
32317 |---------+------------------------------------------------|
32318 | 0387074 | INST: R/3 4.6C SR2 Installation on UNIX |
32319 |---------+------------------------------------------------|
32320 | 0387077 | INST: R/3 4.6C SR2 Inst. on UNIX - Oracle |
32321 |---------+------------------------------------------------|
32322 | 0387078 | SAP Software on UNIX: OS Dependencies 4.6C SR2 |
32323 +----------------------------------------------------------+
32325 ----------------------------------------------------------------------
32327 22.7.4 Hardware Requirements
32329 The following equipment is sufficient for the installation of a SAP R/3
32330 System. For production use, a more exact sizing is of course needed:
32332 +-------------------------------------------------------------------+
32333 | Component | 4.6B | 4.6C |
32334 |-----------------+------------------------+------------------------|
32335 | Processor | 2 x 800MHz Pentium III | 2 x 800MHz Pentium III |
32336 |-----------------+------------------------+------------------------|
32337 | Memory | 1GB ECC | 2GB ECC |
32338 |-----------------+------------------------+------------------------|
32339 | Hard Disk Space | 50-60GB (IDES) | 50-60GB (IDES) |
32340 +-------------------------------------------------------------------+
32342 For use in production, Xeon Processors with large cache, high-speed disk
32343 access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended.
32344 The large amount of hard disk space is due to the preconfigured IDES
32345 System, which creates 27 GB of database files during installation. This
32346 space is also sufficient for initial production systems and application
32349 ----------------------------------------------------------------------
32351 22.7.4.1 SAP R/3 4.6B, Oracle 8.0.5
32353 The following off-the-shelf hardware was used: a dual processor board with
32354 two 800 MHz Pentium III processors, Adaptec 29160 Ultra160 SCSI adapter
32355 (for accessing a 40/80 GB DLT tape drive and CDROM), Mylex AcceleRAID(TM)
32356 (2 channels, firmware 6.00-1-00 with 32 MB RAM). To the Mylex RAID
32357 controller are attached two 17 GB hard disks (mirrored) and four 36 GB
32358 hard disks (RAID level 5).
32360 ----------------------------------------------------------------------
32362 22.7.4.2 SAP R/3 4.6C, Oracle 8.1.7
32364 For this installation a Dell(TM) PowerEdge(TM) 2500 was used: a dual
32365 processor board with two 1000 MHz Pentium III processors (256 kB Cache),
32366 2 GB PC133 ECC SDRAM, PERC/3 DC PCI RAID Controller with 128 MB, and an
32367 EIDE DVD-ROM drive. To the RAID controller are attached two 18 GB hard
32368 disks (mirrored) and four 36 GB hard disks (RAID level 5).
32370 ----------------------------------------------------------------------
32372 22.7.5 Installation of FreeBSD
32374 First you have to install FreeBSD.
32376 ----------------------------------------------------------------------
32378 22.7.5.1 Disk Layout
32380 To keep it simple, the same disk layout both for the SAP R/3 46B and
32381 SAP R/3 46C SR2 installation was used. Only the device names changed, as
32382 the installations were on different hardware (/dev/da and /dev/amr
32383 respectively, so if using an AMI MegaRAID, one will see /dev/amr0s1a
32384 instead of /dev/da0s1a):
32386 +--------------------------------------------------------------------+
32387 | File system | Size (1k-blocks) | Size (GB) | Mounted on |
32388 |-------------+------------------+-----------+-----------------------|
32389 | /dev/da0s1a | 1.016.303 | 1 | / |
32390 |-------------+------------------+-----------+-----------------------|
32391 | /dev/da0s1b | | 6 | swap |
32392 |-------------+------------------+-----------+-----------------------|
32393 | /dev/da0s1e | 2.032.623 | 2 | /var |
32394 |-------------+------------------+-----------+-----------------------|
32395 | /dev/da0s1f | 8.205.339 | 8 | /usr |
32396 |-------------+------------------+-----------+-----------------------|
32397 | /dev/da1s1e | 45.734.361 | 45 | /compat/linux/oracle |
32398 |-------------+------------------+-----------+-----------------------|
32399 | /dev/da1s1f | 2.032.623 | 2 | /compat/linux/sapmnt |
32400 |-------------+------------------+-----------+-----------------------|
32401 | /dev/da1s1g | 2.032.623 | 2 | /compat/linux/usr/sap |
32402 +--------------------------------------------------------------------+
32404 Configure and initialize the two logical drives with the Mylex or PERC/3
32405 RAID software beforehand. The software can be started during the BIOS boot
32408 Please note that this disk layout differs slightly from the SAP
32409 recommendations, as SAP suggests mounting the Oracle subdirectories (and
32410 some others) separately -- we decided to just create them as real
32411 subdirectories for simplicity.
32413 ----------------------------------------------------------------------
32415 22.7.5.2 make world and a New Kernel
32417 Download the latest -STABLE sources. Rebuild world and your custom kernel
32418 after configuring your kernel configuration file. Here you should also
32419 include the kernel parameters which are required for both SAP R/3 and
32422 ----------------------------------------------------------------------
32424 22.7.6 Installing the Linux Environment
32426 22.7.6.1 Installing the Linux Base System
32428 First the linux_base port needs to be installed (as root):
32430 # cd /usr/ports/emulators/linux_base
32431 # make install distclean
32433 ----------------------------------------------------------------------
32435 22.7.6.2 Installing Linux Development Environment
32437 The Linux development environment is needed, if you want to install Oracle
32438 on FreeBSD according to the Section 22.6:
32440 # cd /usr/ports/devel/linux_devtools
32441 # make install distclean
32443 The Linux development environment has only been installed for the SAP R/3
32444 46B IDES installation. It is not needed, if the Oracle DB is not relinked
32445 on the FreeBSD system. This is the case if you are using the Oracle
32446 tarball from a Linux system.
32448 ----------------------------------------------------------------------
32450 22.7.6.3 Installing the Necessary RPMs
32452 To start the R3SETUP program, PAM support is needed. During the first SAP
32453 Installation on FreeBSD 4.3-STABLE we tried to install PAM with all the
32454 required packages and finally forced the installation of the PAM package,
32455 which worked. For SAP R/3 4.6C SR2 we directly forced the installation of
32456 the PAM RPM, which also works, so it seems the dependent packages are not
32459 # rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \
32460 pam-0.68-7.i386.rpm
32462 For Oracle 8.0.5 to run the intelligent agent, we also had to install the
32463 RedHat Tcl package tcl-8.0.5-30.i386.rpm (otherwise the relinking during
32464 Oracle installation will not work). There are some other issues regarding
32465 relinking of Oracle, but that is a Oracle Linux issue, not DragonFly
32468 ----------------------------------------------------------------------
32470 22.7.6.4 Some Additional Hints
32472 It might also be a good idea to add linprocfs to /etc/fstab, for more
32473 informations, see the linprocfs(5) manual page. Another parameter to set
32474 is kern.fallback_elf_brand=3 which is done in the file /etc/sysctl.conf.
32476 ----------------------------------------------------------------------
32478 22.7.7 Creating the SAP R/3 Environment
32480 22.7.7.1 Creating the Necessary File Systems and Mountpoints
32482 For a simple installation, it is sufficient to create the following file
32485 +------------------------------------+
32486 | mount point | size in GB |
32487 |-----------------------+------------|
32488 | /compat/linux/oracle | 45 GB |
32489 |-----------------------+------------|
32490 | /compat/linux/sapmnt | 2 GB |
32491 |-----------------------+------------|
32492 | /compat/linux/usr/sap | 2 GB |
32493 +------------------------------------+
32495 It is also necessary to created some links. Otherwise the SAP Installer
32496 will complain, as it is checking the created links:
32498 # ln -s /compat/linux/oracle /oracle
32499 # ln -s /compat/linux/sapmnt /sapmnt
32500 # ln -s /compat/linux/usr/sap /usr/sap
32502 Possible error message during installation (here with System PRD and the
32503 SAP R/3 4.6C SR2 installation):
32505 INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200
32506 Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to
32507 /sapmnt/PRD/exe. Creating if it does not exist...
32509 WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400
32510 Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file
32511 /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The
32512 program cannot go on as long as this link exists at this
32513 location. Move the link to another location.
32515 ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0
32516 can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content
32519 ----------------------------------------------------------------------
32521 22.7.7.2 Creating Users and Directories
32523 SAP R/3 needs two users and three groups. The user names depend on the SAP
32524 system ID (SID) which consists of three letters. Some of these SIDs are
32525 reserved by SAP (for example SAP and NIX. For a complete list please see
32526 the SAP documentation). For the IDES installation we used IDS, for the
32527 4.6C SR2 installation PRD, as that system is intended for production use.
32528 We have therefore the following groups (group IDs might differ, these are
32529 just the values we used with our installation):
32531 +-------------------------------------------------+
32532 | group ID | group name | description |
32533 |----------+------------+-------------------------|
32534 | 100 | dba | Data Base Administrator |
32535 |----------+------------+-------------------------|
32536 | 101 | sapsys | SAP System |
32537 |----------+------------+-------------------------|
32538 | 102 | oper | Data Base Operator |
32539 +-------------------------------------------------+
32541 For a default Oracle installation, only group dba is used. As oper group,
32542 one also uses group dba (see Oracle and SAP documentation for further
32545 We also need the following users:
32547 +------------------------------------------------------------------------+
32548 | user | user name | generic | group | additional | description |
32549 | ID | | name | | groups | |
32550 |------+---------------+---------+--------+------------+-----------------|
32551 | 1000 | idsadm/prdadm | sidadm | sapsys | oper | SAP |
32552 | | | | | | Administrator |
32553 |------+---------------+---------+--------+------------+-----------------|
32554 | 1002 | oraids/oraprd | orasid | dba | oper | Oracle |
32555 | | | | | | Administrator |
32556 +------------------------------------------------------------------------+
32558 Adding the users with adduser(8) requires the following (please note shell
32559 and home directory) entries for ``SAP Administrator'':
32563 Fullname: SAP Administrator SID
32569 Shell: bash (/compat/linux/bin/bash)
32571 and for ``Oracle Administrator'':
32575 Fullname: Oracle Administrator SID
32581 Shell: bash (/compat/linux/bin/bash)
32583 This should also include group oper in case you are using both groups dba
32586 ----------------------------------------------------------------------
32588 22.7.7.3 Creating Directories
32590 These directories are usually created as separate file systems. This
32591 depends entirely on your requirements. We choose to create them as simple
32592 directories, as they are all located on the same RAID 5 anyway:
32594 First we will set owners and rights of some directories (as user root):
32596 # chmod 775 /oracle
32597 # chmod 777 /sapmnt
32598 # chown root:dba /oracle
32599 # chown sidadm:sapsys /compat/linux/usr/sap
32600 # chmod 775 /compat/linux/usr/sap
32602 Second we will create directories as user orasid. These will all be
32603 subdirectories of /oracle/SID:
32607 # mkdir mirrlogA mirrlogB origlogA origlogB
32608 # mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6
32609 # mkdir saparch sapreorg
32612 For the Oracle 8.1.7 installation some additional directories are needed:
32617 # mkdir client stage
32618 # mkdir client/80x_32
32619 # mkdir stage/817_32
32623 Note: The directory client/80x_32 is used with exactly this name. Do not
32624 replace the x with some number or anything.
32626 In the third step we create directories as user sidadm:
32634 ----------------------------------------------------------------------
32636 22.7.7.4 Entries in /etc/services
32638 SAP R/3 requires some entries in file /etc/services, which will not be set
32639 correctly during installation under FreeBSD. Please add the following
32640 entries (you need at least those entries corresponding to the instance
32641 number -- in this case, 00. It will do no harm adding all entries from 00
32642 to 99 for dp, gw, sp and ms). If you are going to use a SAProuter or need
32643 to access SAP OSS, you also need 99, as port 3299 is usually used for the
32644 SAProuter process on the target system:
32646 sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number
32647 sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number
32648 sapsp00 3400/tcp # 3400 + Instance-Number
32649 sapms00 3500/tcp # 3500 + Instance-Number
32650 sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number
32651 sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number
32653 ----------------------------------------------------------------------
32655 22.7.7.5 Necessary Locales
32657 SAP requires at least two locales that are not part of the default RedHat
32658 installation. SAP offers the required RPMs as download from their FTP
32659 server (which is only accessible if you are a customer with OSS access).
32660 See note 0171356 for a list of RPMs you need.
32662 It is also possible to just create appropriate links (for example from
32663 de_DE and en_US ), but we would not recommend this for a production system
32664 (so far it worked with the IDES system without any problems, though). The
32665 following locales are needed:
32670 Create the links like this:
32672 # cd /compat/linux/usr/share/locale
32673 # ln -s de_DE de_DE.ISO-8859-1
32674 # ln -s en_US en_US.ISO-8859-1
32676 If they are not present, there will be some problems during the
32677 installation. If these are then subsequently ignored (by setting the
32678 STATUS of the offending steps to OK in file CENTRDB.R3S), it will be
32679 impossible to log onto the SAP system without some additional effort.
32681 ----------------------------------------------------------------------
32683 22.7.7.6 Kernel Tuning
32685 SAP R/3 systems need a lot of resources. We therefore added the following
32686 parameters to the kernel configuration file:
32688 # Set these for memory pigs (SAP and Oracle):
32689 options MAXDSIZ="(1024*1024*1024)"
32690 options DFLDSIZ="(1024*1024*1024)"
32691 # System V options needed.
32692 options SYSVSHM #SYSV-style shared memory
32693 options SHMMAXPGS=262144 #max amount of shared mem. pages
32694 #options SHMMAXPGS=393216 #use this for the 46C inst.parameters
32695 options SHMMNI=256 #max number of shared memory ident if.
32696 options SHMSEG=100 #max shared mem.segs per process
32697 options SYSVMSG #SYSV-style message queues
32698 options MSGSEG=32767 #max num. of mes.segments in system
32699 options MSGSSZ=32 #size of msg-seg. MUST be power of 2
32700 options MSGMNB=65535 #max char. per message queue
32701 options MSGTQL=2046 #max amount of msgs in system
32702 options SYSVSEM #SYSV-style semaphores
32703 options SEMMNU=256 #number of semaphore UNDO structures
32704 options SEMMNS=1024 #number of semaphores in system
32705 options SEMMNI=520 #number of semaphore identifiers
32706 options SEMUME=100 #number of UNDO keys
32708 The minimum values are specified in the documentation that comes from SAP.
32709 As there is no description for Linux, see the HP-UX section (32-bit) for
32710 further information. As the system for the 4.6C SR2 installation has more
32711 main memory, the shared segments can be larger both for SAP and Oracle,
32712 therefore choose a larger number of shared memory pages.
32714 Note: With the default installation of FreeBSD 4.5 on i386, leave
32715 MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange errors like
32716 ``ORA-27102: out of memory'' and ``Linux Error: 12: Cannot allocate
32717 memory'' might happen.
32719 ----------------------------------------------------------------------
32721 22.7.8 Installing SAP R/3
32723 22.7.8.1 Preparing SAP CDROMs
32725 There are many CDROMs to mount and unmount during the installation.
32726 Assuming you have enough CDROM drives, you can just mount them all. We
32727 decided to copy the CDROMs contents to corresponding directories:
32729 /oracle/SID/sapreorg/cd-name
32731 where cd-name was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3,
32732 EXPORT4, EXPORT5 and EXPORT6 for the 4.6B/IDES installation, and KERNEL,
32733 RDBMS, DISK1, DISK2, DISK3, DISK4 and LANG for the 4.6C SR2 installation.
32734 All the filenames on the mounted CDs should be in capital letters,
32735 otherwise use the -g option for mounting. So use the following commands:
32737 # mount_cd9660 -g /dev/cd0a /mnt
32738 # cp -R /mnt/* /oracle/SID/sapreorg/cd-name
32741 ----------------------------------------------------------------------
32743 22.7.8.2 Running the Installation Script
32745 First you have to prepare an install directory:
32747 # cd /oracle/SID/sapreorg
32751 Then the installation script is started, which will copy nearly all the
32752 relevant files into the install directory:
32754 # /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH
32756 The IDES installation (4.6B) comes with a fully customized SAP R/3
32757 demonstration system, so there are six instead of just three EXPORT CDs.
32758 At this point the installation template CENTRDB.R3S is for installing a
32759 standard central instance (R/3 and database), not the IDES central
32760 instance, so one needs to copy the corresponding CENTRDB.R3S from the
32761 EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT CDs.
32763 The newer SAP 4.6C SR2 release comes with four EXPORT CDs. The parameter
32764 file that controls the installation steps is CENTRAL.R3S. Contrary to
32765 earlier releases there are no separate installation templates for a
32766 central instance with or without database. SAP is using a separate
32767 template for database installation. To restart the installation later it
32768 is however sufficient to restart with the original file.
32770 During and after installation, SAP requires hostname to return the
32771 computer name only, not the fully qualified domain name. So either set the
32772 hostname accordingly, or set an alias with alias hostname='hostname -s'
32773 for both orasid and sidadm (and for root at least during installation
32774 steps performed as root). It is also possible to adjust the installed
32775 .profile and .login files of both users that are installed during SAP
32778 ----------------------------------------------------------------------
32780 22.7.8.3 Start R3SETUP 4.6B
32782 Make sure LD_LIBRARY_PATH is set correctly:
32784 # export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib
32786 Start R3SETUP as root from installation directory:
32788 # cd /oracle/IDS/sapreorg/install
32789 # ./R3SETUP -f CENTRDB.R3S
32791 The script then asks some questions (defaults in brackets, followed by
32794 +------------------------------------------------------------------------+
32795 | Question | Default | Input |
32796 |------------+------------------------------+----------------------------|
32797 |Enter SAP |[C11] |IDSEnter |
32799 |------------+------------------------------+----------------------------|
32801 |Instance |[00] |Enter |
32803 |------------+------------------------------+----------------------------|
32805 |SAPMOUNT |[/sapmnt] |Enter |
32807 |------------+------------------------------+----------------------------|
32809 |of SAP |[troubadix.domain.de] |Enter |
32811 |------------+------------------------------+----------------------------|
32813 |of SAP db |[troubadix] |Enter |
32815 |------------+------------------------------+----------------------------|
32817 |character |[1] (WE8DEC) |Enter |
32819 |------------+------------------------------+----------------------------|
32824 |8.0.5, (2) | |1Enter |
32830 |------------+------------------------------+----------------------------|
32832 |Oracle |[1] (Yes, extract) |Enter |
32835 |------------+------------------------------+----------------------------|
32836 |Enter path |[/sapcd] |/oracle/IDS/sapreorg/KERNEL |
32838 |------------+------------------------------+----------------------------|
32839 |Enter path |[/sapcd] |/oracle/IDS/sapreorg/RDBMS |
32841 |------------+------------------------------+----------------------------|
32843 |to EXPORT1 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT1|
32845 |------------+------------------------------+----------------------------|
32847 |copy EXPORT1|[/oracle/IDS/sapreorg/CD4_DIR]|Enter |
32849 |------------+------------------------------+----------------------------|
32851 |to EXPORT2 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT2|
32853 |------------+------------------------------+----------------------------|
32855 |copy EXPORT2|[/oracle/IDS/sapreorg/CD5_DIR]|Enter |
32857 |------------+------------------------------+----------------------------|
32859 |to EXPORT3 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT3|
32861 |------------+------------------------------+----------------------------|
32863 |copy EXPORT3|[/oracle/IDS/sapreorg/CD6_DIR]|Enter |
32865 |------------+------------------------------+----------------------------|
32867 |to EXPORT4 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT4|
32869 |------------+------------------------------+----------------------------|
32871 |copy EXPORT4|[/oracle/IDS/sapreorg/CD7_DIR]|Enter |
32873 |------------+------------------------------+----------------------------|
32875 |to EXPORT5 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT5|
32877 |------------+------------------------------+----------------------------|
32879 |copy EXPORT5|[/oracle/IDS/sapreorg/CD8_DIR]|Enter |
32881 |------------+------------------------------+----------------------------|
32883 |to EXPORT6 |[/sapcd] |/oracle/IDS/sapreorg/EXPORT6|
32885 |------------+------------------------------+----------------------------|
32887 |copy EXPORT6|[/oracle/IDS/sapreorg/CD9_DIR]|Enter |
32889 |------------+------------------------------+----------------------------|
32891 |of RAM for | |850Enter (in Megabytes) |
32893 |------------+------------------------------+----------------------------|
32895 |Entry |[3600] |Enter |
32898 |------------+------------------------------+----------------------------|
32900 |Group-ID of |[101] |Enter |
32902 |------------+------------------------------+----------------------------|
32904 |Group-ID of |[102] |Enter |
32906 |------------+------------------------------+----------------------------|
32908 |Group-ID of |[100] |Enter |
32910 |------------+------------------------------+----------------------------|
32912 |User-ID of |[1000] |Enter |
32914 |------------+------------------------------+----------------------------|
32916 |User-ID of |[1002] |Enter |
32918 |------------+------------------------------+----------------------------|
32920 |parallel |[2] |Enter |
32922 +------------------------------------------------------------------------+
32924 If you had not copied the CDs to the different locations, then the SAP
32925 installer cannot find the CD needed (identified by the LABEL.ASC file on
32926 the CD) and would then ask you to insert and mount the CD and confirm or
32927 enter the mount path.
32929 The CENTRDB.R3S might not be error free. In our case, it requested EXPORT4
32930 CD again but indicated the correct key (6_LOCATION, then 7_LOCATION etc.),
32931 so one can just continue with entering the correct values.
32933 Apart from some problems mentioned below, everything should go straight
32934 through up to the point where the Oracle database software needs to be
32937 ----------------------------------------------------------------------
32939 22.7.8.4 Start R3SETUP 4.6C SR2
32941 Make sure LD_LIBRARY_PATH is set correctly. This is a different value from
32942 the 4.6B installation with Oracle 8.0.5:
32944 # export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib
32946 Start R3SETUP as user root from installation directory:
32948 # cd /oracle/PRD/sapreorg/install
32949 # ./R3SETUP -f CENTRAL.R3S
32951 The script then asks some questions (defaults in brackets, followed by
32954 +------------------------------------------------------------------------+
32955 | Question | Default | Input |
32956 |-------------------------+----------------+-----------------------------|
32957 | Enter SAP System ID | [C11] | PRDEnter |
32958 |-------------------------+----------------+-----------------------------|
32959 | Enter SAP Instance | [00] | Enter |
32961 |-------------------------+----------------+-----------------------------|
32962 | Enter SAPMOUNT | [/sapmnt] | Enter |
32964 |-------------------------+----------------+-----------------------------|
32965 | Enter name of SAP | [majestix] | Enter |
32966 | central host | | |
32967 |-------------------------+----------------+-----------------------------|
32968 | Enter Database System | [PRD] | PRDEnter |
32970 |-------------------------+----------------+-----------------------------|
32971 | Enter name of SAP db | [majestix] | Enter |
32973 |-------------------------+----------------+-----------------------------|
32974 | Select character set | [1] (WE8DEC) | Enter |
32975 |-------------------------+----------------+-----------------------------|
32976 | Enter Oracle server | | |
32977 | version (2) Oracle | | 2Enter |
32979 |-------------------------+----------------+-----------------------------|
32980 | Extract Oracle Client | [1] (Yes, | Enter |
32981 | archive | extract) | |
32982 |-------------------------+----------------+-----------------------------|
32983 | Enter path to KERNEL CD | [/sapcd] | /oracle/PRD/sapreorg/KERNEL |
32984 |-------------------------+----------------+-----------------------------|
32985 | Enter amount of RAM for | 2044 | 1800Enter (in Megabytes) |
32987 |-------------------------+----------------+-----------------------------|
32988 | Service Entry Message | [3600] | Enter |
32990 |-------------------------+----------------+-----------------------------|
32991 | Enter Group-ID of | [100] | Enter |
32993 |-------------------------+----------------+-----------------------------|
32994 | Enter Group-ID of oper | [101] | Enter |
32995 |-------------------------+----------------+-----------------------------|
32996 | Enter Group-ID of dba | [102] | Enter |
32997 |-------------------------+----------------+-----------------------------|
32998 | Enter User-ID of oraprd | [1002] | Enter |
32999 |-------------------------+----------------+-----------------------------|
33000 | Enter User-ID of prdadm | [1000] | Enter |
33001 |-------------------------+----------------+-----------------------------|
33002 | LDAP support | | 3Enter (no support) |
33003 |-------------------------+----------------+-----------------------------|
33004 | Installation step | [1] (continue) | Enter |
33006 |-------------------------+----------------+-----------------------------|
33007 | Choose installation | [1] (DB | Enter |
33008 | service | inst,file) | |
33009 +------------------------------------------------------------------------+
33011 So far, creation of users gives an error during installation in phases
33012 OSUSERDBSID_IND_ORA (for creating user orasid) and OSUSERSIDADM_IND_ORA
33013 (creating user sidadm).
33015 Apart from some problems mentioned below, everything should go straight
33016 through up to the point where the Oracle database software needs to be
33019 ----------------------------------------------------------------------
33021 22.7.9 Installing Oracle 8.0.5
33023 Please see the corresponding SAP Notes and Oracle Readmes regarding Linux
33024 and Oracle DB for possible problems. Most if not all problems stem from
33025 incompatible libraries.
33027 For more information on installing Oracle, refer to the Installing Oracle
33030 ----------------------------------------------------------------------
33032 22.7.9.1 Installing the Oracle 8.0.5 with orainst
33034 If Oracle 8.0.5 is to be used, some additional libraries are needed for
33035 successfully relinking, as Oracle 8.0.5 was linked with an old glibc
33036 (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to
33037 install the following additional packages to ensure that linking will
33040 compat-libs-5.2-2.i386.rpm
33042 compat-glibc-5.2-2.0.7.2.i386.rpm
33044 compat-egcs-5.2-1.0.3a.1.i386.rpm
33046 compat-egcs-c++-5.2-1.0.3a.1.i386.rpm
33048 compat-binutils-5.2-2.9.1.0.23.1.i386.rpm
33050 See the corresponding SAP Notes or Oracle Readmes for further information.
33051 If this is no option (at the time of installation we did not have enough
33052 time to check this), one could use the original binaries, or use the
33053 relinked binaries from an original RedHat system.
33055 For compiling the intelligent agent, the RedHat Tcl package must be
33056 installed. If you cannot get tcl-8.0.3-20.i386.rpm, a newer one like
33057 tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do.
33059 Apart from relinking, the installation is straightforward:
33062 # export TERM=xterm
33063 # export ORACLE_TERM=xterm
33064 # export ORACLE_HOME=/oracle/IDS
33065 # cd /ORACLE_HOME/orainst_sap
33068 Confirm all screens with Enter until the software is installed, except
33069 that one has to deselect the Oracle On-Line Text Viewer, as this is not
33070 currently available for Linux. Oracle then wants to relink with
33071 i386-glibc20-linux-gcc instead of the available gcc, egcs or
33072 i386-redhat-linux-gcc .
33074 Due to time constrains we decided to use the binaries from an Oracle 8.0.5
33075 PreProduction release, after the first attempt at getting the version from
33076 the RDBMS CD working, failed, and finding and accessing the correct RPMs
33077 was a nightmare at that time.
33079 ----------------------------------------------------------------------
33081 22.7.9.2 Installing the Oracle 8.0.5 Pre-production Release for Linux
33084 This installation is quite easy. Mount the CD, start the installer. It
33085 will then ask for the location of the Oracle home directory, and copy all
33086 binaries there. We did not delete the remains of our previous RDBMS
33087 installation tries, though.
33089 Afterwards, Oracle Database could be started with no problems.
33091 ----------------------------------------------------------------------
33093 22.7.10 Installing the Oracle 8.1.7 Linux Tarball
33095 Take the tarball oracle81732.tgz you produced from the installation
33096 directory on a Linux system and untar it to /oracle/SID/817_32/.
33098 ----------------------------------------------------------------------
33100 22.7.11 Continue with SAP R/3 Installation
33102 First check the environment settings of users idsamd (sidadm) and oraids
33103 (orasid). They should now both have the files .profile, .login and .cshrc
33104 which are all using hostname. In case the system's hostname is the fully
33105 qualified name, you need to change hostname to hostname -s within all
33108 ----------------------------------------------------------------------
33110 22.7.11.1 Database Load
33112 Afterwards, R3SETUP can either be restarted or continued (depending on
33113 whether exit was chosen or not). R3SETUP then creates the tablespaces and
33114 loads the data (for 46B IDES, from EXPORT1 to EXPORT6, for 46C from DISK1
33115 to DISK4) with R3load into the database.
33117 When the database load is finished (might take a few hours), some
33118 passwords are requested. For test installations, one can use the well
33119 known default passwords (use different ones if security is an issue!):
33121 +------------------------------------------------------+
33122 | Question | Input |
33123 |-----------------------------+------------------------|
33124 | Enter Password for sapr3 | sapEnter |
33125 |-----------------------------+------------------------|
33126 | Confirum Password for sapr3 | sapEnter |
33127 |-----------------------------+------------------------|
33128 | Enter Password for sys | change_on_installEnter |
33129 |-----------------------------+------------------------|
33130 | Confirm Password for sys | change_on_installEnter |
33131 |-----------------------------+------------------------|
33132 | Enter Password for system | managerEnter |
33133 |-----------------------------+------------------------|
33134 | Confirm Password for system | managerEnter |
33135 +------------------------------------------------------+
33137 At this point We had a few problems with dipgntab during the 4.6B
33140 ----------------------------------------------------------------------
33144 Start the Oracle Listener as user orasid as follows:
33146 % umask 0; lsnrctl start
33148 Otherwise you might get the error ORA-12546 as the sockets will not have
33149 the correct permissions. See SAP Note 072984.
33151 ----------------------------------------------------------------------
33153 22.7.11.3 Updating MNLS Tables
33155 If you plan to import non-Latin-1 languages into the SAP system, you have
33156 to update the Multi National Language Support tables. This is described in
33157 the SAP OSS Notes 15023 and 45619. Otherwise, you can skip this question
33158 during SAP installation.
33160 Note: If you do not need MNLS, it is still necessary to check the table
33161 TCPDB and initializing it if this has not been done. See SAP note
33162 0015023 and 0045619 for further information.
33164 ----------------------------------------------------------------------
33166 22.7.12 Post-installation Steps
33168 22.7.12.1 Request SAP R/3 License Key
33170 You have to request your SAP R/3 License Key. This is needed, as the
33171 temporary license that was installed during installation is only valid for
33172 four weeks. First get the hardware key. Log on as user idsadm and call
33175 # /sapmnt/IDS/exe/saplicense -get
33177 Calling saplicense without parameters gives a list of options. Upon
33178 receiving the license key, it can be installed using:
33180 # /sapmnt/IDS/exe/saplicense -install
33182 You are then required to enter the following values:
33184 SAP SYSTEM ID = SID, 3 chars
33185 CUSTOMER KEY = hardware key, 11 chars
33186 INSTALLATION NO = installation, 10 digits
33187 EXPIRATION DATE = yyyymmdd, usually "99991231"
33188 LICENSE KEY = license key, 24 chars
33190 ----------------------------------------------------------------------
33192 22.7.12.2 Creating Users
33194 Create a user within client 000 (for some tasks required to be done within
33195 client 000, but with a user different from users sap* and ddic). As a user
33196 name, We usually choose wartung (or service in English). Profiles required
33197 are sap_new and sap_all. For additional safety the passwords of default
33198 users within all clients should be changed (this includes users sap* and
33201 ----------------------------------------------------------------------
33203 22.7.12.3 Configure Transport System, Profile, Operation Modes, Etc.
33205 Within client 000, user different from ddic and sap*, do at least the
33208 +------------------------------------------------------------------------+
33209 | Task | Transaction |
33210 |----------------------------------------------------------+-------------|
33211 | Configure Transport System, e.g. as Stand-Alone | STMS |
33212 | Transport Domain Entity | |
33213 |----------------------------------------------------------+-------------|
33214 | Create / Edit Profile for System | RZ10 |
33215 |----------------------------------------------------------+-------------|
33216 | Maintain Operation Modes and Instances | RZ04 |
33217 +------------------------------------------------------------------------+
33219 These and all the other post-installation steps are thoroughly described
33220 in SAP installation guides.
33222 ----------------------------------------------------------------------
33224 22.7.12.4 Edit initsid.sap (initIDS.sap)
33226 The file /oracle/IDS/dbs/initIDS.sap contains the SAP backup profile. Here
33227 the size of the tape to be used, type of compression and so on need to be
33228 defined. To get this running with sapdba / brbackup, we changed the
33231 compress = hardware
33232 archive_function = copy_delete_save
33233 cpio_flags = "-ov --format=newc --block-size=128 --quiet"
33234 cpio_in_flags = "-iuv --block-size=128 --quiet"
33236 tape_address = /dev/nsa0
33237 tape_address_rew = /dev/sa0
33241 compress: The tape we use is a HP DLT1 which does hardware compression.
33243 archive_function: This defines the default behavior for saving Oracle
33244 archive logs: new logfiles are saved to tape, already saved logfiles are
33245 saved again and are then deleted. This prevents lots of trouble if you
33246 need to recover the database, and one of the archive-tapes has gone bad.
33248 cpio_flags: Default is to use -B which sets block size to 5120 Bytes. For
33249 DLT Tapes, HP recommends at least 32 K block size, so we used
33250 --block-size=128 for 64 K. --format=newc is needed because we have inode
33251 numbers greater than 65535. The last option --quiet is needed as otherwise
33252 brbackup complains as soon as cpio outputs the numbers of blocks saved.
33254 cpio_in_flags: Flags needed for loading data back from tape. Format is
33255 recognized automatically.
33257 tape_size: This usually gives the raw storage capability of the tape. For
33258 security reason (we use hardware compression), the value is slightly lower
33259 than the actual value.
33261 tape_address: The non-rewindable device to be used with cpio.
33263 tape_address_rew: The rewindable device to be used with cpio.
33265 ----------------------------------------------------------------------
33267 22.7.12.5 Configuration Issues after Installation
33269 The following SAP parameters should be tuned after installation (examples
33270 for IDES 46B, 1 GB memory):
33273 ztta/roll_extension 250000000
33274 abap/heap_area_dia 300000000
33275 abap/heap_area_nondia 400000000
33276 em/initial_size_MB 256
33277 em/blocksize_kB 1024
33278 ipc/shm_psize_40 70000000
33283 ztta/dynpro_area 2500000
33288 rdisp/ROLL_MAXFS 16000
33289 rdisp/PG_MAXFS 30000
33291 Note: With the above parameters, on a system with 1 gigabyte of memory,
33292 one may find memory consumption similar to:
33294 Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free
33296 ----------------------------------------------------------------------
33298 22.7.13 Problems during Installation
33300 22.7.13.1 Restart R3SETUP after Fixing a Problem
33302 R3SETUP stops if it encounters an error. If you have looked at the
33303 corresponding logfiles and fixed the error, you have to start R3SETUP
33304 again, usually selecting REPEAT as option for the last step R3SETUP
33307 To restart R3SETUP, just start it with the corresponding R3S file:
33309 # ./R3SETUP -f CENTRDB.R3S
33313 # ./R3SETUP -f CENTRAL.R3S
33315 for 4.6C, no matter whether the error occurred with CENTRAL.R3S or
33318 Note: At some stages, R3SETUP assumes that both database and SAP
33319 processes are up and running (as those were steps it already completed).
33320 Should errors occur and for example the database could not be started,
33321 you have to start both database and SAP by hand after you fixed the
33322 errors and before starting R3SETUP again.
33324 Do not forget to also start the Oracle listener again (as orasid with
33325 umask 0; lsnrctl start) if it was also stopped (for example due to a
33326 necessary reboot of the system).
33328 ----------------------------------------------------------------------
33330 22.7.13.2 OSUSERSIDADM_IND_ORA during R3SETUP
33332 If R3SETUP complains at this stage, edit the template file R3SETUP used at
33333 that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S
33334 (4.6C)). Locate [OSUSERSIDADM_IND_ORA] or search for the only STATUS=ERROR
33335 entry and edit the following values:
33337 HOME=/home/sidadm (was empty)
33338 STATUS=OK (had status ERROR)
33341 Then you can restart R3SETUP again.
33343 ----------------------------------------------------------------------
33345 22.7.13.3 OSUSERDBSID_IND_ORA during R3SETUP
33347 Possibly R3SETUP also complains at this stage. The error here is similar
33348 to the one in phase OSUSERSIDADM_IND_ORA. Just edit the template file
33349 R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or
33350 DATABASE.R3S (4.6C)). Locate [OSUSERDBSID_IND_ORA] or search for the only
33351 STATUS=ERROR entry and edit the following value in that section:
33355 Then restart R3SETUP.
33357 ----------------------------------------------------------------------
33359 22.7.13.4 ``oraview.vrf FILE NOT FOUND'' during Oracle Installation
33361 You have not deselected Oracle On-Line Text Viewer before starting the
33362 installation. This is marked for installation even though this option is
33363 currently not available for Linux. Deselect this product inside the Oracle
33364 installation menu and restart installation.
33366 ----------------------------------------------------------------------
33368 22.7.13.5 ``TEXTENV_INVALID'' during R3SETUP, RFC or SAPgui Start
33370 If this error is encountered, the correct locale is missing. SAP Note
33371 0171356 lists the necessary RPMs that need be installed (e.g.
33372 saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored
33373 all the related errors and set the corresponding STATUS from ERROR to OK
33374 (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP,
33375 the SAP system will not be properly configured and you will then not be
33376 able to connect to the system with a SAPgui, even though the system can be
33377 started. Trying to connect with the old Linux SAPgui gave the following
33380 Sat May 5 14:23:14 2001
33381 *** ERROR => no valid userarea given [trgmsgo. 0401]
33382 Sat May 5 14:23:22 2001
33383 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
33384 *** ERROR => Error when generating text environment. [trgmsgi. 0435]
33385 *** ERROR => function failed [trgmsgi. 0447]
33386 *** ERROR => no socket operation allowed [trxio.c 3363]
33387 Speicherzugriffsfehler
33389 This behavior is due to SAP R/3 being unable to correctly assign a locale
33390 and also not being properly configured itself (missing entries in some
33391 database tables). To be able to connect to SAP, add the following entries
33392 to file DEFAULT.PFL (see Note 0043288):
33394 abap/set_etct_env_at_new_mode = 0
33395 install/collate/active = 0
33398 Restart the SAP system. Now you can connect to the system, even though
33399 country-specific language settings might not work as expected. After
33400 correcting country settings (and providing the correct locales), these
33401 entries can be removed from DEFAULT.PFL and the SAP system can be
33404 ----------------------------------------------------------------------
33406 22.7.13.6 ORA-00001
33408 This error only happened with Oracle 8.1.7 on FreeBSD 4.5. The reason was
33409 that the Oracle database could not initialize itself properly and crashed,
33410 leaving semaphores and shared memory on the system. The next try to start
33411 the database then returned ORA-00001.
33413 Find them with ipcs -a and remove them with ipcrm.
33415 ----------------------------------------------------------------------
33417 22.7.13.7 ORA-00445 (Background Process PMON Did Not Start)
33419 This error happened with Oracle 8.1.7. This error is reported if the
33420 database is started with the usual startsap script (for example
33421 startsap_majestix_00) as user prdadm.
33423 A possible workaround is to start the database as user oraprd instead with
33427 SVRMGR> connect internal;
33431 ----------------------------------------------------------------------
33433 22.7.13.8 ORA-12546 (Start Listener with Correct Permissions)
33435 Start the Oracle listener as user oraids with the following commands:
33437 # umask 0; lsnrctl start
33439 Otherwise you might get ORA-12546 as the sockets will not have the correct
33440 permissions. See SAP Note 0072984.
33442 ----------------------------------------------------------------------
33444 22.7.13.9 ORA-27102 (Out of Memory)
33446 This error happened whilst trying to use values for MAXDSIZ and DFLDSIZ
33447 greater than 1 GB (1024x1024x1024). Additionally, we got ``Linux Error 12:
33448 Cannot allocate memory''.
33450 ----------------------------------------------------------------------
33452 22.7.13.10 [DIPGNTAB_IND_IND] during R3SETUP
33454 In general, see SAP Note 0130581 (R3SETUP step DIPGNTAB terminates).
33455 During the IDES-specific installation, for some reasons the installation
33456 process was not using the proper SAP system name ``IDS'', but the empty
33457 string "" instead. This lead to some minor problems with accessing
33458 directories, as the paths are generated dynamically using SID (in this
33459 case IDS). So instead of accessing:
33461 /usr/sap/IDS/SYS/...
33462 /usr/sap/IDS/DVMGS00
33464 the following paths were used:
33469 To continue with the installation, we created a link and an additional
33473 /compat/linux/usr/sap
33476 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00
33477 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS
33478 lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS
33479 drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp
33480 drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans
33482 We also found SAP Notes (0029227 and 0008401) describing this behavior. We
33483 did not encounter any of these problems with the SAP 4.6C installation.
33485 ----------------------------------------------------------------------
33487 22.7.13.11 [RFCRSWBOINI_IND_IND] during R3SETUP
33489 During installation of SAP 4.6C, this error was just the result of another
33490 error happening earlier during installation. In this case, you have to
33491 look through the corresponding logfiles and correct the real problem.
33493 If after looking through the logfiles this error is indeed the correct one
33494 (check the SAP Notes), you can set STATUS of the offending step from ERROR
33495 to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have
33496 to execute the report RSWBOINS from transaction SE38. See SAP Note 0162266
33497 for additional information about phase RFCRSWBOINI and RFCRADDBDIF.
33499 ----------------------------------------------------------------------
33501 22.7.13.12 [RFCRADDBDIF_IND_IND] during R3SETUP
33503 Here the same restrictions apply: make sure by looking through the
33504 logfiles, that this error is not caused by some previous problems.
33506 If you can confirm that SAP Note 0162266 applies, just set STATUS of the
33507 offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP.
33508 After installation, you have to execute the report RADDBDIF from
33511 ----------------------------------------------------------------------
33513 22.7.13.13 sigaction sig31: File size limit exceeded
33515 This error occurred during start of SAP processes disp+work. If starting
33516 SAP with the startsap script, subprocesses are then started which detach
33517 and do the dirty work of starting all other SAP processes. As a result,
33518 the script itself will not notice if something goes wrong.
33520 To check whether the SAP processes did start properly, have a look at the
33521 process status with ps ax | grep SID, which will give you a list of all
33522 Oracle and SAP processes. If it looks like some processes are missing or
33523 if you cannot connect to the SAP system, look at the corresponding
33524 logfiles which can be found at /usr/sap/SID/DVEBMGSnr/work/. The files to
33525 look at are dev_ms and dev_disp.
33527 Signal 31 happens here if the amount of shared memory used by Oracle and
33528 SAP exceed the one defined within the kernel configuration file and could
33529 be resolved by using a larger value:
33531 # larger value for 46C production systems:
33532 options SHMMAXPGS=393216
33533 # smaller value sufficient for 46B:
33534 #options SHMMAXPGS=262144
33536 ----------------------------------------------------------------------
33538 22.7.13.14 Start of saposcol Failed
33540 There are some problems with the program saposcol (version 4.6D). The SAP
33541 system is using saposcol to collect data about the system performance.
33542 This program is not needed to use the SAP system, so this problem can be
33543 considered a minor one. The older versions (4.6B) does work, but does not
33544 collect all the data (many calls will just return 0, for example for CPU
33547 ----------------------------------------------------------------------
33549 22.8 Advanced Topics
33551 If you are curious as to how the Linux binary compatibility works, this is
33552 the section you want to read. Most of what follows is based heavily on an
33553 email written to FreeBSD chat mailing list by Terry Lambert
33554 <tlambert@primenet.com> (Message ID:
33555 <199906020108.SAA07001@usr09.primenet.com>).
33557 Warning: This description applies to FreeBSD, for which it was
33558 originally written. This may or may not apply to DragonFly at this
33559 point; while FreeBSD 4.x features usually translate over to DragonFly
33560 well, your mileage may vary.
33562 ----------------------------------------------------------------------
33564 22.8.1 How Does It Work?
33566 DragonFly has an abstraction called an ``execution class loader''. This is
33567 a wedge into the execve(2) system call.
33569 What happens is that DragonFly has a list of loaders, instead of a single
33570 loader with a fallback to the #! loader for running any shell interpreters
33573 Historically, the only loader on the UNIX platform examined the magic
33574 number (generally the first 4 or 8 bytes of the file) to see if it was a
33575 binary known to the system, and if so, invoked the binary loader.
33577 If it was not the binary type for the system, the execve(2) call returned
33578 a failure, and the shell attempted to start executing it as shell
33581 The assumption was a default of ``whatever the current shell is''.
33583 Later, a hack was made for sh(1) to examine the first two characters, and
33584 if they were :\n, then it invoked the csh(1) shell instead (we believe SCO
33585 first made this hack).
33587 What DragonFly does now is go through a list of loaders, with a generic #!
33588 loader that knows about interpreters as the characters which follow to the
33589 next whitespace next to last, followed by a fallback to /bin/sh.
33591 For the Linux ABI support, DragonFly sees the magic number as an ELF
33592 binary (it makes no distinction between FreeBSD, Solaris, Linux, or any
33593 other OS which has an ELF image type, at this point).
33595 The ELF loader looks for a specialized brand, which is a comment section
33596 in the ELF image, and which is not present on SVR4/Solaris ELF binaries.
33598 For Linux binaries to function, they must be branded as type Linux from
33601 # brandelf -t Linux file
33603 When this is done, the ELF loader will see the Linux brand on the file.
33605 When the ELF loader sees the Linux brand, the loader replaces a pointer in
33606 the proc structure. All system calls are indexed through this pointer (in
33607 a traditional UNIX system, this would be the sysent[] structure array,
33608 containing the system calls). In addition, the process is flagged for
33609 special handling of the trap vector for the signal trampoline code, and
33610 several other (minor) fix-ups that are handled by the Linux kernel module.
33612 The Linux system call vector contains, among other things, a list of
33613 sysent[] entries whose addresses reside in the kernel module.
33615 When a system call is called by the Linux binary, the trap code
33616 dereferences the system call function pointer off the proc structure, and
33617 gets the Linux, not the DragonFly, system call entry points.
33619 In addition, the Linux mode dynamically reroots lookups; this is, in
33620 effect, what the union option to file system mounts (not the unionfs file
33621 system type!) does. First, an attempt is made to lookup the file in the
33622 /compat/linux/original-path directory, then only if that fails, the lookup
33623 is done in the /original-path directory. This makes sure that binaries
33624 that require other binaries can run (e.g., the Linux toolchain can all run
33625 under Linux ABI support). It also means that the Linux binaries can load
33626 and execute DragonFly binaries, if there are no corresponding Linux
33627 binaries present, and that you could place a uname(1) command in the
33628 /compat/linux directory tree to ensure that the Linux binaries could not
33629 tell they were not running on Linux.
33631 In effect, there is a Linux kernel in the DragonFly kernel; the various
33632 underlying functions that implement all of the services provided by the
33633 kernel are identical to both the DragonFly system call table entries, and
33634 the Linux system call table entries: file system operations, virtual
33635 memory operations, signal delivery, System V IPC, etc... The only
33636 difference is that DragonFly binaries get the DragonFly glue functions,
33637 and Linux binaries get the Linux glue functions (most older OS's only had
33638 their own glue functions: addresses of functions in a static global
33639 sysent[] structure array, instead of addresses of functions dereferenced
33640 off a dynamically initialized pointer in the proc structure of the process
33643 Which one is the native DragonFly ABI? It does not matter. Basically the
33644 only difference is that (currently; this could easily be changed in a
33645 future release, and probably will be after this) the DragonFly glue
33646 functions are statically linked into the kernel, and the Linux glue
33647 functions can be statically linked, or they can be accessed via a kernel
33650 Yeah, but is this really emulation? No. It is an ABI implementation, not
33651 an emulation. There is no emulator (or simulator, to cut off the next
33652 question) involved.
33654 So why is it sometimes called ``Linux emulation''? To make it hard to sell
33655 DragonFly! Really, it is because the historical implementation was done at
33656 a time when there was really no word other than that to describe what was
33657 going on; saying that FreeBSD [14] ran Linux binaries was not true, if you
33658 did not compile the code in or load a module, and there needed to be a
33659 word to describe what was being loaded--hence ``the Linux emulator''.
33665 A. Obtaining DragonFly
33669 C. Resources on the Internet
33673 ----------------------------------------------------------------------
33675 Appendix A. Obtaining DragonFly
33677 A.1 CDROM and DVD Publishers
33679 A.1.1 Retail Products
33681 DragonFly is available as a purchasable CD:
33684 WWW: http://www.crescentanchor.com/
33687 ----------------------------------------------------------------------
33689 A.1.2 CD and DVD Sets
33691 DragonFly BSD CD and DVD sets are available from online retailers:
33694 560 South State Street, Suite A2
33697 Phone: +1 800 407-5170
33698 Fax: +1 1 801 765-0877
33699 Email: <sales@bsdmall.com>
33700 WWW: http://www.bsdmall.com/
33704 Email: <sales@bsd-systems.co.uk>
33705 WWW: http://www.bsd-systems.co.uk/
33708 ----------------------------------------------------------------------
33712 The official sources for DragonFly are available via anonymous FTP from a
33713 worldwide set of mirror sites. The site ftp://ftp.dragonflybsd.org/ is
33714 well connected and allows a large number of connections to it, but you are
33715 probably better off finding a ``closer'' mirror site (especially if you
33716 decide to set up some sort of mirror site).
33718 The DragonFly mirror sites list is the best, most up-to-date source.
33720 Additionally, DragonFly is available via anonymous FTP from the following
33721 mirror sites. If you choose to obtain DragonFly via anonymous FTP, please
33722 try to use a site near you. The mirror sites listed as ``Primary Mirror
33723 Sites'' typically have the entire DragonFly archive (all the currently
33724 available versions for each of the architectures) but you will probably
33725 have faster download times from a site that is in your country or region.
33726 The regional sites carry the most recent versions for the most popular
33727 architecture(s) but might not carry the entire DragonFly archive. All
33728 sites provide access via anonymous FTP but some sites also provide access
33729 via other methods. The access methods available for each site are provided
33730 in parentheses after the hostname.
33732 Central Servers, Primary Mirror Sites, Australia, USA.
33734 (as of 2005/06/27 23:37:47 UTC)
33738 * ftp://ftp.DragonFlyBSD.org/ (ftp)
33740 Primary Mirror Sites
33742 In case of problems, please contact <docs@DragonFlyBSD.org>.
33744 * ftp://chlamydia.fs.ei.tum.de/pub/DragonFly/ (ftp)
33746 * ftp://ftp.allbsd.org/pub/DragonFly/ (ftp)
33748 * ftp://ftp.esat.net/mirrors/chlamydia.fs.ei.tum.de/pub/DragonFly/
33751 * ftp://ftp.fortunaty.net/DragonFly/ (ftp)
33753 * ftp://ftp.univie.ac.at/systems/DragonFly/ (ftp)
33755 * ftp://cvsup.math.uic.edu/dragonflybsd/ (ftp)
33757 * ftp://ftp.starkast.net/pub/DragonFly/ (ftp)
33759 * ftp://mirror.bgp4.net/pub/DragonFly/ (ftp)
33761 * ftp://ftp.csie.chu.edu.tw/ (ftp)
33763 * ftp://dragonflybsd.cs.pu.edu.tw/DragonFLYBSD (ftp)
33765 * ftp://mirror.isp.net.au/pub/DragonFly/ (ftp)
33767 * ftp://ftp.theshell.com/pub/DragonFly/ (ftp)
33769 * ftp://mirror.macomnet.net/pub/DragonFlyBSD/ (ftp)
33771 * ftp://ftp.tu-clausthal.de/pub/DragonFly/ (ftp)
33775 In case of problems, please contact <docs@DragonFlyBSD.org>.
33777 * ftp://mirror.isp.net.au/pub/DragonFly/ (ftp / http / rsync)
33781 In case of problems, please contact <docs@DragonFlyBSD.org>.
33783 * ftp://ftp.theshell.com/pub/DragonFly/ (ftp / http / rsync)
33785 ----------------------------------------------------------------------
33791 CVSup is a software package for distributing and updating source trees
33792 from a master CVS repository on a remote server host. The DragonFly
33793 sources are maintained in a CVS repository on a central development
33794 machine in California. With CVSup, DragonFly users can easily keep their
33795 own source trees up to date.
33797 CVSup uses the so-called pull model of updating. Under the pull model,
33798 each client asks the server for updates, if and when they are wanted. The
33799 server waits passively for update requests from its clients. Thus all
33800 updates are instigated by the client. The server never sends unsolicited
33801 updates. Users must either run the CVSup client manually to get an update,
33802 or they must set up a cron job to run it automatically on a regular basis.
33804 The term CVSup, capitalized just so, refers to the entire software
33805 package. Its main components are the client cvsup which runs on each
33806 user's machine, and the server cvsupd which runs at each of the DragonFly
33807 mirror sites that use CVSup.
33809 ----------------------------------------------------------------------
33813 CVSup is installed by default on all DragonFly systems.
33815 ----------------------------------------------------------------------
33817 A.3.3 CVSup Configuration
33819 CVSup's operation is controlled by a configuration file called the
33820 supfile. There are some sample supfiles in the directory
33821 /usr/share/examples/cvsup/.
33823 The information in a supfile answers the following questions for CVSup:
33825 * Which files do you want to receive?
33827 * Which versions of them do you want?
33829 * Where do you want to get them from?
33831 * Where do you want to put them on your own machine?
33833 * Where do you want to put your status files?
33835 In the following sections, we will construct a typical supfile by
33836 answering each of these questions in turn. First, we describe the overall
33837 structure of a supfile.
33839 A supfile is a text file. Comments begin with # and extend to the end of
33840 the line. Lines that are blank and lines that contain only comments are
33843 Each remaining line describes a set of files that the user wishes to
33844 receive. The line begins with the name of a ``collection'', a logical
33845 grouping of files defined by the server. The name of the collection tells
33846 the server which files you want. After the collection name come zero or
33847 more fields, separated by white space. These fields answer the questions
33848 listed above. There are two types of fields: flag fields and value fields.
33849 A flag field consists of a keyword standing alone, e.g., delete or
33850 compress. A value field also begins with a keyword, but the keyword is
33851 followed without intervening white space by = and a second word. For
33852 example, release=cvs is a value field.
33854 A supfile typically specifies more than one collection to receive. One way
33855 to structure a supfile is to specify all of the relevant fields explicitly
33856 for each collection. However, that tends to make the supfile lines quite
33857 long, and it is inconvenient because most fields are the same for all of
33858 the collections in a supfile. CVSup provides a defaulting mechanism to
33859 avoid these problems. Lines beginning with the special pseudo-collection
33860 name *default can be used to set flags and values which will be used as
33861 defaults for the subsequent collections in the supfile. A default value
33862 can be overridden for an individual collection, by specifying a different
33863 value with the collection itself. Defaults can also be changed or
33864 augmented in mid-supfile by additional *default lines.
33866 With this background, we will now proceed to construct a supfile for
33867 receiving and updating the main source tree of DragonFly.
33869 * Which files do you want to receive?
33871 The files available via CVSup are organized into named groups called
33872 ``collections''. The collections that are available are described in
33873 the following section. In this example, we wish to receive the entire
33874 main source tree for the DragonFly system. There is a single large
33875 collection cvs-src which will give us all of that. As a first step
33876 toward constructing our supfile, we simply list the collections, one
33877 per line (in this case, only one line):
33881 * Which version(s) of them do you want?
33883 With CVSup, you can receive virtually any version of the sources that
33884 ever existed. That is possible because the cvsupd server works
33885 directly from the CVS repository, which contains all of the versions.
33886 You specify which one of them you want using the tag= and date= value
33889 Warning: Be very careful to specify any tag= fields correctly. Some
33890 tags are valid only for certain collections of files. If you specify
33891 an incorrect or misspelled tag, CVSup will delete files which you
33892 probably do not want deleted. In particular, use only tag=. for the
33893 ports-* collections.
33895 The tag= field names a symbolic tag in the repository. There are two
33896 kinds of tags, revision tags and branch tags. A revision tag refers to
33897 a specific revision. Its meaning stays the same from day to day. A
33898 branch tag, on the other hand, refers to the latest revision on a
33899 given line of development, at any given time. Because a branch tag
33900 does not refer to a specific revision, it may mean something different
33901 tomorrow than it means today.
33903 Section A.4 contains branch tags that users might be interested in.
33904 When specifying a tag in CVSup's configuration file, it must be
33905 preceded with tag= (RELENG_4 will become tag=RELENG_4). Keep in mind
33906 that only the tag=. is relevant for the ports collection.
33908 Warning: Be very careful to type the tag name exactly as shown.
33909 CVSup cannot distinguish between valid and invalid tags. If you
33910 misspell the tag, CVSup will behave as though you had specified a
33911 valid tag which happens to refer to no files at all. It will delete
33912 your existing sources in that case.
33914 When you specify a branch tag, you normally receive the latest
33915 versions of the files on that line of development. If you wish to
33916 receive some past version, you can do so by specifying a date with the
33917 date= value field. The cvsup(1) manual page explains how to do that.
33919 For our example, we wish to receive the current release of DragonFly.
33920 We add this line at the beginning of our supfile:
33924 There is an important special case that comes into play if you specify
33925 neither a tag= field nor a date= field. In that case, you receive the
33926 actual RCS files directly from the server's CVS repository, rather
33927 than receiving a particular version. Developers generally prefer this
33928 mode of operation. By maintaining a copy of the repository itself on
33929 their systems, they gain the ability to browse the revision histories
33930 and examine past versions of files. This gain is achieved at a large
33931 cost in terms of disk space, however.
33933 * Where do you want to get them from?
33935 We use the host= field to tell cvsup where to obtain its updates. Any
33936 of the CVSup mirror sites will do, though you should try to select one
33937 that is close to you in cyberspace. In this example we will use a
33938 fictional DragonFly distribution site, cvsup666.dragonflybsd.org:
33940 *default host=cvsup666.dragonflybsd.org
33942 You will need to change the host to one that actually exists before
33943 running CVSup. On any particular run of cvsup, you can override the
33944 host setting on the command line, with -h hostname.
33946 * Where do you want to put them on your own machine?
33948 The prefix= field tells cvsup where to put the files it receives. In
33949 this example, we will put the source files directly into our main
33950 source tree, /usr/src. The src directory is already implicit in the
33951 collections we have chosen to receive, so this is the correct
33954 *default prefix=/usr
33956 * Where should cvsup maintain its status files?
33958 The CVSup client maintains certain status files in what is called the
33959 ``base'' directory. These files help CVSup to work more efficiently,
33960 by keeping track of which updates you have already received. We will
33961 use the standard base directory, /usr/local/etc/cvsup:
33963 *default base=/usr/local/etc/cvsup
33965 This setting is used by default if it is not specified in the supfile,
33966 so we actually do not need the above line.
33968 If your base directory does not already exist, now would be a good
33969 time to create it. The cvsup client will refuse to run if the base
33970 directory does not exist.
33972 * Miscellaneous supfile settings:
33974 There is one more line of boiler plate that normally needs to be
33975 present in the supfile:
33977 *default release=cvs delete use-rel-suffix compress
33979 release=cvs indicates that the server should get its information out
33980 of the main DragonFly CVS repository. This is virtually always the
33981 case, but there are other possibilities which are beyond the scope of
33984 delete gives CVSup permission to delete files. You should always
33985 specify this, so that CVSup can keep your source tree fully
33986 up-to-date. CVSup is careful to delete only those files for which it
33987 is responsible. Any extra files you happen to have will be left
33990 use-rel-suffix is ... arcane. If you really want to know about it, see
33991 the cvsup(1) manual page. Otherwise, just specify it and do not worry
33994 compress enables the use of gzip-style compression on the
33995 communication channel. If your network link is T1 speed or faster, you
33996 probably should not use compression. Otherwise, it helps
33999 * Putting it all together:
34001 Here is the entire supfile for our example:
34004 *default host=cvsup666.dragonflybsd.org
34005 *default prefix=/usr
34006 *default base=/usr/local/etc/cvsup
34007 *default release=cvs delete use-rel-suffix compress
34011 ----------------------------------------------------------------------
34013 A.3.3.1 The refuse File
34015 As mentioned above, CVSup uses a pull method. Basically, this means that
34016 you connect to the CVSup server, and it says, ``Here is what you can
34017 download from me...'', and your client responds ``OK, I will take this,
34018 this, this, and this.'' In the default configuration, the CVSup client
34019 will take every file associated with the collection and tag you chose in
34020 the configuration file. However, this is not always what you want,
34021 especially if you are synching the doc, ports, or www trees -- most people
34022 cannot read four or five languages, and therefore they do not need to
34023 download the language-specific files. If you are CVSuping the ports
34024 collection, you can get around this by specifying each collection
34025 individually (e.g., ports-astrology, ports-biology, etc instead of simply
34026 saying ports-all). However, since the doc and www trees do not have
34027 language-specific collections, you must use one of CVSup's many nifty
34028 features: the refuse file.
34030 The refuse file essentially tells CVSup that it should not take every
34031 single file from a collection; in other words, it tells the client to
34032 refuse certain files from the server. The refuse file can be found (or, if
34033 you do not yet have one, should be placed) in base/sup/. base is defined
34034 in your supfile; by default, base is /usr/local/etc/cvsup, which means
34035 that by default the refuse file is /usr/local/etc/cvsup/sup/refuse.
34037 The refuse file has a very simple format; it simply contains the names of
34038 files or directories that you do not wish to download. For example, if you
34039 cannot speak any languages other than English and some German, and you do
34040 not feel the need to use the German applications (or applications for any
34041 other languages, except for English), you can put the following in your
34071 and so forth for the other languages (you can find the full list by
34072 browsing the FreeBSD CVS repository).
34074 With this very useful feature, those users who are on slow links or pay by
34075 the minute for their Internet connection will be able to save valuable
34076 time as they will no longer need to download files that they will never
34077 use. For more information on refuse files and other neat features of
34078 CVSup, please view its manual page.
34080 ----------------------------------------------------------------------
34082 A.3.4 Running CVSup
34084 You are now ready to try an update. The command line for doing this is
34089 where supfile is of course the name of the supfile you have just created.
34090 Assuming you are running under X11, cvsup will display a GUI window with
34091 some buttons to do the usual things. Press the go button, and watch it
34094 Since you are updating your actual /usr/src tree in this example, you will
34095 need to run the program as root so that cvsup has the permissions it needs
34096 to update your files. Having just created your configuration file, and
34097 having never used this program before, that might understandably make you
34098 nervous. There is an easy way to do a trial run without touching your
34099 precious files. Just create an empty directory somewhere convenient, and
34100 name it as an extra argument on the command line:
34102 # mkdir /var/tmp/dest
34103 # cvsup supfile /var/tmp/dest
34105 The directory you specify will be used as the destination directory for
34106 all file updates. CVSup will examine your usual files in /usr/src, but it
34107 will not modify or delete any of them. Any file updates will instead land
34108 in /var/tmp/dest/usr/src. CVSup will also leave its base directory status
34109 files untouched when run this way. The new versions of those files will be
34110 written into the specified directory. As long as you have read access to
34111 /usr/src, you do not even need to be root to perform this kind of trial
34114 If you are not running X11 or if you just do not like GUIs, you should add
34115 a couple of options to the command line when you run cvsup:
34117 # cvsup -g -L 2 supfile
34119 The -g tells CVSup not to use its GUI. This is automatic if you are not
34120 running X11, but otherwise you have to specify it.
34122 The -L 2 tells CVSup to print out the details of all the file updates it
34123 is doing. There are three levels of verbosity, from -L 0 to -L 2. The
34124 default is 0, which means total silence except for error messages.
34126 There are plenty of other options available. For a brief list of them,
34127 type cvsup -H. For more detailed descriptions, see the manual page.
34129 Once you are satisfied with the way updates are working, you can arrange
34130 for regular runs of CVSup using cron(8). Obviously, you should not let
34131 CVSup use its GUI when running it from cron(8).
34133 ----------------------------------------------------------------------
34135 A.3.5 CVSup File Collections
34137 The most commonly used collections are cvs-src, and cvs-dfports.
34141 The DragonFly source code.
34145 Documentation. This does not include the DragonFly website.
34149 Overrides for the FreeBSD Ports Collection.
34153 The DragonFly website code.
34157 Basic CVS data. This is only needed if you are pulling the RCS
34160 ----------------------------------------------------------------------
34162 A.3.6 For More Information
34164 For the CVSup FAQ and other information about CVSup, see The CVSup Home
34167 Questions and bug reports should be addressed to the author of the program
34168 at <cvsup-bugs@polstra.com>.
34170 ----------------------------------------------------------------------
34174 CVSup servers for DragonFly are running at the following sites:
34176 Primary Mirror Sites, Australia, USA.
34178 (as of 2005/06/27 23:37:47 UTC)
34180 Primary Mirror Sites
34182 * chlamydia.fs.ei.tum.de
34186 * grappa.unix-ag.uni-kl.de
34188 * mirror.isp.net.au
34192 * dragonflybsd.delphij.net
34194 * fred.acm.cs.rpi.edu
34198 * mirror.isp.net.au
34202 * fred.acm.cs.rpi.edu
34204 ----------------------------------------------------------------------
34208 When obtaining or updating sources from cvs and CVSup a revision tag
34209 (reference to a date in time) must be specified.
34211 A revision tag refers to either a particular line of DragonFly
34212 development, or a specific point in time. The first type are called
34213 ``branch tags'', the second type are called ``release tags''.
34215 ----------------------------------------------------------------------
34219 The DragonFly tree has no branch tags at the current time.
34221 ----------------------------------------------------------------------
34225 These tags correspond to the DragonFly src/ tree at a specific point in
34226 time, when a particular version was released.
34230 The latest bleeding-edge DragonFly code. Be warned that this is
34231 considered unstable and possibly may not build or compile at any
34236 A "preview" of the latest bleeding-edge DragonFly code. The main
34237 purpose of the Preview tag is to support those users who want a
34238 fairly recent snapshot at a "reasonably stable" point in
34239 development. Under normal conditions, one should consider syncing
34240 Preview at least once a month.
34242 DragonFly_RELEASE_1_2
34250 ----------------------------------------------------------------------
34252 Appendix B. Bibliography
34254 While the manual pages provide the definitive reference for individual
34255 pieces of the DragonFly operating system, they are notorious for not
34256 illustrating how to put the pieces together to make the whole operating
34257 system run smoothly. For this, there is no substitute for a good book on
34258 UNIX system administration and a good users' manual.
34260 ----------------------------------------------------------------------
34262 B.1 Books & Magazines Specific to BSD
34264 International books & Magazines:
34266 * Using FreeBSD (in Chinese).
34268 * FreeBSD for PC 98'ers (in Japanese), published by SHUWA System Co,
34269 LTD. ISBN 4-87966-468-5 C3055 P2900E.
34271 * FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 C3055
34274 * Complete Introduction to FreeBSD (in Japanese), published by Shoeisha
34275 Co., Ltd. ISBN 4-88135-473-6 P3600E.
34277 * Personal UNIX Starter Kit FreeBSD (in Japanese), published by ASCII.
34278 ISBN 4-7561-1733-3 P3000E.
34280 * FreeBSD Handbook (Japanese translation), published by ASCII. ISBN
34281 4-7561-1580-2 P3800E.
34283 * FreeBSD mit Methode (in German), published by Computer und Literatur
34284 Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.
34286 * FreeBSD 4 - Installieren, Konfigurieren, Administrieren (in German),
34287 published by Computer und Literatur Verlag, 2001. ISBN 3-932311-88-4.
34289 * FreeBSD 5 - Installieren, Konfigurieren, Administrieren (in German),
34290 published by Computer und Literatur Verlag, 2003. ISBN 3-936546-06-1.
34292 * FreeBSD de Luxe (in German), published by Verlag Modere Industrie,
34293 2003. ISBN 3-8266-1343-0.
34295 * FreeBSD Install and Utilization Manual (in Japanese), published by
34296 Mainichi Communications Inc..
34298 * Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil Widodo Building
34299 Internet Server with FreeBSD (in Indonesia Language), published by
34300 Elex Media Komputindo.
34302 English language books & Magazines:
34304 * Absolute BSD: The Ultimate Guide to FreeBSD, published by No Starch
34305 Press, 2002. ISBN: 1886411743
34307 * The Complete FreeBSD, published by O'Reilly, 2003. ISBN: 0596005164
34309 * The FreeBSD Corporate Networker's Guide, published by Addison-Wesley,
34310 2000. ISBN: 0201704811
34312 * FreeBSD: An Open-Source Operating System for Your Personal Computer,
34313 published by The Bit Tree Press, 2001. ISBN: 0971204500
34315 * Teach Yourself FreeBSD in 24 Hours, published by Sams, 2002. ISBN:
34318 * FreeBSD unleashed, published by Sams, 2002. ISBN: 0672324563
34320 * FreeBSD: The Complete Reference, published by McGrawHill, 2003. ISBN:
34323 ----------------------------------------------------------------------
34327 * Computer Systems Research Group, UC Berkeley. 4.4BSD User's Reference
34328 Manual. O'Reilly & Associates, Inc., 1994. ISBN 1-56592-075-9
34330 * Computer Systems Research Group, UC Berkeley. 4.4BSD User's
34331 Supplementary Documents. O'Reilly & Associates, Inc., 1994. ISBN
34334 * UNIX in a Nutshell. O'Reilly & Associates, Inc., 1990. ISBN 093717520X
34336 * Mui, Linda. What You Need To Know When You Can't Find Your UNIX System
34337 Administrator. O'Reilly & Associates, Inc., 1995. ISBN 1-56592-104-6
34339 * Ohio State University has written a UNIX Introductory Course which is
34340 available online in HTML and PostScript format.
34342 An Italian translation of this document is available as part of the
34343 FreeBSD Italian Documentation Project.
34345 * Jpman Project, Japan FreeBSD Users Group. FreeBSD User's Reference
34346 Manual (Japanese translation). Mainichi Communications Inc., 1998.
34347 ISBN4-8399-0088-4 P3800E.
34349 * Edinburgh University has written an Online Guide for newcomers to the
34352 ----------------------------------------------------------------------
34354 B.3 Administrators' Guides
34356 * Albitz, Paul and Liu, Cricket. DNS and BIND, 4th Ed. O'Reilly &
34357 Associates, Inc., 2001. ISBN 1-59600-158-4
34359 * Computer Systems Research Group, UC Berkeley. 4.4BSD System Manager's
34360 Manual. O'Reilly & Associates, Inc., 1994. ISBN 1-56592-080-5
34362 * Costales, Brian, et al. Sendmail, 2nd Ed. O'Reilly & Associates, Inc.,
34363 1997. ISBN 1-56592-222-0
34365 * Frisch, AEleen. Essential System Administration, 2nd Ed. O'Reilly &
34366 Associates, Inc., 1995. ISBN 1-56592-127-5
34368 * Hunt, Craig. TCP/IP Network Administration, 2nd Ed. O'Reilly &
34369 Associates, Inc., 1997. ISBN 1-56592-322-7
34371 * Nemeth, Evi. UNIX System Administration Handbook. 3rd Ed. Prentice
34372 Hall, 2000. ISBN 0-13-020601-6
34374 * Stern, Hal Managing NFS and NIS O'Reilly & Associates, Inc., 1991.
34377 * Jpman Project, Japan FreeBSD Users Group. FreeBSD System
34378 Administrator's Manual (Japanese translation). Mainichi Communications
34379 Inc., 1998. ISBN4-8399-0109-0 P3300E.
34381 * Dreyfus, Emmanuel. Cahiers de l'Admin: BSD (in French), Eyrolles,
34382 2003. ISBN 2-212-11244-0
34384 ----------------------------------------------------------------------
34386 B.4 Programmers' Guides
34388 * Asente, Paul, Converse, Diana, and Swick, Ralph. X Window System
34389 Toolkit. Digital Press, 1998. ISBN 1-55558-178-1
34391 * Computer Systems Research Group, UC Berkeley. 4.4BSD Programmer's
34392 Reference Manual. O'Reilly & Associates, Inc., 1994. ISBN
34395 * Computer Systems Research Group, UC Berkeley. 4.4BSD Programmer's
34396 Supplementary Documents. O'Reilly & Associates, Inc., 1994. ISBN
34399 * Harbison, Samuel P. and Steele, Guy L. Jr. C: A Reference Manual. 4rd
34400 ed. Prentice Hall, 1995. ISBN 0-13-326224-3
34402 * Kernighan, Brian and Dennis M. Ritchie. The C Programming Language..
34403 PTR Prentice Hall, 1988. ISBN 0-13-110362-9
34405 * Lehey, Greg. Porting UNIX Software. O'Reilly & Associates, Inc., 1995.
34408 * Plauger, P. J. The Standard C Library. Prentice Hall, 1992. ISBN
34411 * Spinellis, Diomidis. Code Reading: The Open Source Perspective.
34412 Addison-Wesley, 2003. ISBN 0-201-79940-5
34414 * Stevens, W. Richard. Advanced Programming in the UNIX Environment.
34415 Reading, Mass. : Addison-Wesley, 1992. ISBN 0-201-56317-7
34417 * Stevens, W. Richard. UNIX Network Programming. 2nd Ed, PTR Prentice
34418 Hall, 1998. ISBN 0-13-490012-X
34420 * Wells, Bill. ``Writing Serial Drivers for UNIX''. Dr. Dobb's Journal.
34421 19(15), December 1994. pp68-71, 97-99.
34423 ----------------------------------------------------------------------
34425 B.5 Operating System Internals
34427 * Andleigh, Prabhat K. UNIX System Architecture. Prentice-Hall, Inc.,
34428 1990. ISBN 0-13-949843-5
34430 * Jolitz, William. ``Porting UNIX to the 386''. Dr. Dobb's Journal.
34431 January 1991-July 1992.
34433 * Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and John
34434 Quarterman The Design and Implementation of the 4.3BSD UNIX Operating
34435 System. Reading, Mass. : Addison-Wesley, 1989. ISBN 0-201-06196-1
34437 * Leffler, Samuel J., Marshall Kirk McKusick, The Design and
34438 Implementation of the 4.3BSD UNIX Operating System: Answer Book.
34439 Reading, Mass. : Addison-Wesley, 1991. ISBN 0-201-54629-9
34441 * McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and John
34442 Quarterman. The Design and Implementation of the 4.4BSD Operating
34443 System. Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-54979-4
34445 (Chapter 2 of this book is available online as part of the FreeBSD
34446 Documentation Project, and chapter 9 here.)
34448 * Stevens, W. Richard. TCP/IP Illustrated, Volume 1: The Protocols.
34449 Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-63346-9
34451 * Schimmel, Curt. Unix Systems for Modern Architectures. Reading, Mass.
34452 : Addison-Wesley, 1994. ISBN 0-201-63338-8
34454 * Stevens, W. Richard. TCP/IP Illustrated, Volume 3: TCP for
34455 Transactions, HTTP, NNTP and the UNIX Domain Protocols. Reading, Mass.
34456 : Addison-Wesley, 1996. ISBN 0-201-63495-3
34458 * Vahalia, Uresh. UNIX Internals -- The New Frontiers. Prentice Hall,
34459 1996. ISBN 0-13-101908-2
34461 * Wright, Gary R. and W. Richard Stevens. TCP/IP Illustrated, Volume 2:
34462 The Implementation. Reading, Mass. : Addison-Wesley, 1995. ISBN
34465 ----------------------------------------------------------------------
34467 B.6 Security Reference
34469 * Cheswick, William R. and Steven M. Bellovin. Firewalls and Internet
34470 Security: Repelling the Wily Hacker. Reading, Mass. : Addison-Wesley,
34471 1995. ISBN 0-201-63357-4
34473 * Garfinkel, Simson and Gene Spafford. Practical UNIX & Internet
34474 Security. 2nd Ed. O'Reilly & Associates, Inc., 1996. ISBN
34477 * Garfinkel, Simson. PGP Pretty Good Privacy O'Reilly & Associates,
34478 Inc., 1995. ISBN 1-56592-098-8
34480 ----------------------------------------------------------------------
34482 B.7 Hardware Reference
34484 * Anderson, Don and Tom Shanley. Pentium Processor System Architecture.
34485 2nd Ed. Reading, Mass. : Addison-Wesley, 1995. ISBN 0-201-40992-5
34487 * Ferraro, Richard F. Programmer's Guide to the EGA, VGA, and Super VGA
34488 Cards. 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN
34491 * Intel Corporation publishes documentation on their CPUs, chipsets and
34492 standards on their developer web site, usually as PDF files.
34494 * Shanley, Tom. 80486 System Architecture. 3rd ed. Reading, Mass. :
34495 Addison-Wesley, 1995. ISBN 0-201-40994-1
34497 * Shanley, Tom. ISA System Architecture. 3rd ed. Reading, Mass. :
34498 Addison-Wesley, 1995. ISBN 0-201-40996-8
34500 * Shanley, Tom. PCI System Architecture. 4th ed. Reading, Mass. :
34501 Addison-Wesley, 1999. ISBN 0-201-30974-2
34503 * Van Gilluwe, Frank. The Undocumented PC, 2nd Ed. Reading, Mass:
34504 Addison-Wesley Pub. Co., 1996. ISBN 0-201-47950-8
34506 * Messmer, Hans-Peter. The Indispensable PC Hardware Book, 4th Ed.
34507 Reading, Mass: Addison-Wesley Pub. Co., 2002. ISBN 0-201-59616-4
34509 ----------------------------------------------------------------------
34513 * Lion, John Lion's Commentary on UNIX, 6th Ed. With Source Code. ITP
34514 Media Group, 1996. ISBN 1573980137
34516 * Raymond, Eric S. The New Hacker's Dictionary, 3rd edition. MIT Press,
34517 1996. ISBN 0-262-68092-0. Also known as the Jargon File
34519 * Salus, Peter H. A Quarter Century of UNIX. Addison-Wesley Publishing
34520 Company, Inc., 1994. ISBN 0-201-54777-5
34522 * Simon Garfinkel, Daniel Weise, Steven Strassmann. The UNIX-HATERS
34523 Handbook. IDG Books Worldwide, Inc., 1994. ISBN 1-56884-203-1
34525 * Don Libes, Sandy Ressler Life with UNIX -- special edition.
34526 Prentice-Hall, Inc., 1989. ISBN 0-13-536657-7
34528 * The BSD family tree.
34529 http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree
34530 or /usr/share/misc/bsd-family-tree on a modern FreeBSD machine.
34532 * The BSD Release Announcements collection. 1997.
34533 http://www.de.FreeBSD.org/de/ftp/releases/
34535 * Networked Computer Science Technical Reports Library.
34536 http://www.ncstrl.org/
34538 * Old BSD releases from the Computer Systems Research group (CSRG).
34539 http://www.mckusick.com/csrg/: The 4CD set covers all BSD versions
34540 from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately).
34541 As well, the last disk holds the final sources plus the SCCS files.
34543 ----------------------------------------------------------------------
34545 B.9 Magazines and Journals
34547 * The C/C++ Users Journal. R&D Publications Inc. ISSN 1075-2838
34549 * Sys Admin -- The Journal for UNIX System Administrators Miller
34550 Freeman, Inc., ISSN 1061-2688
34552 * freeX -- Das Magazin fu:r Linux - BSD - UNIX (in German) Computer- und
34553 Literaturverlag GmbH, ISSN 1436-7033
34555 ----------------------------------------------------------------------
34557 Appendix C. Resources on the Internet
34559 The rapid pace of DragonFly progress makes print media impractical as a
34560 means of following the latest developments. Electronic resources are the
34561 best, if not often the only, way stay informed of the latest advances.
34562 Since DragonFly is a volunteer effort, the user community itself also
34563 generally serves as a ``technical support department'' of sorts, with
34564 electronic mail and USENET news being the most effective way of reaching
34567 The most important points of contact with the DragonFly user community are
34568 outlined below. If you are aware of other resources not mentioned here,
34569 please send them to the DragonFly Documentation project mailing list so
34570 that they may also be included.
34572 ----------------------------------------------------------------------
34576 Though many of the DragonFly development members read USENET, we cannot
34577 always guarantee that we will get to your questions in a timely fashion
34578 (or at all) if you post them only to one of the comp.unix.bsd.* groups. By
34579 addressing your questions to the appropriate mailing list you will reach
34580 both us and a concentrated DragonFly audience, invariably assuring a
34581 better (or at least faster) response.
34583 The charters for the various lists are given at the bottom of this
34584 document. Please read the charter before joining or sending mail to any
34585 list. Most of our list subscribers now receive many hundreds of DragonFly
34586 related messages every day, and by setting down charters and rules for
34587 proper use we are striving to keep the signal-to-noise ratio of the lists
34588 high. To do less would see the mailing lists ultimately fail as an
34589 effective communications medium for the project.
34591 Archives are kept for all of the mailing lists and can be searched using
34592 the mail archives. The keyword searchable archive offers an excellent way
34593 of finding answers to frequently asked questions and should be consulted
34594 before posting a question.
34596 ----------------------------------------------------------------------
34600 General lists: The following are general lists which anyone is free (and
34601 encouraged) to join:
34605 commits Messages generated by code changes to DragonFly source,
34606 documentation, or the website.
34607 docs Discussion of DragonFly documentation
34608 kernel Ostensibly for discussion of kernel work, though this list also
34609 serves as a catch-all for any topic pertaining to DragonFly.
34610 submit Submission and discussion of new code or ideas for DragonFly.
34611 Test For testing your newsreader or mail software.
34612 users User related discussion about DragonFly.
34614 ----------------------------------------------------------------------
34616 C.1.2 How to Subscribe
34618 To subscribe to a list, click on the list name above or send an email to
34619 <listname-request@dragonflybsd.org> and put 'subscribe' in the body of the
34622 To actually post to a given list you simply send mail to
34623 <listname@dragonflybsd.org>. It will then be redistributed to mailing list
34624 members world-wide.
34626 To unsubscribe yourself from a list, email
34627 <listname-request@dragonflybsd.org> and put 'unsubscribe' in the body of
34630 ----------------------------------------------------------------------
34632 C.1.3 List Charters
34634 All DragonFly mailing lists have certain basic rules which must be adhered
34635 to by anyone using them. Failure to comply with these guidelines may
34636 result in from all DragonFly mailing lists and filtered from further
34637 posting to them. We regret that such rules and measures are necessary at
34638 all, but today's Internet is a pretty harsh environment, it would seem,
34639 and many fail to appreciate just how fragile some of its mechanisms are.
34643 * The topic of any posting should adhere to the basic charter of the
34644 list it is posted to, e.g. if the list is about technical issues then
34645 your posting should contain technical discussion. Ongoing irrelevant
34646 chatter or flaming only detracts from the value of the mailing list
34647 for everyone on it and will not be tolerated.
34649 * No posting should be made to more than two mailing lists, and only to
34650 two when a clear and obvious need to post to both lists exists. For
34651 most lists, there is already a great deal of subscriber overlap. If a
34652 message is sent to you in such a way that multiple mailing lists
34653 appear on the Cc line then the Cc line should also be trimmed before
34654 sending it out again. You are still responsible for your own
34655 cross-postings, no matter who the originator might have been.
34657 * Personal attacks and profanity (in the context of an argument) are not
34658 allowed, and that includes users and developers alike. Gross breaches
34659 of netiquette, like excerpting or reposting private mail when
34660 permission to do so was not and would not be forthcoming, are frowned
34661 upon but not specifically enforced. However, there are also very few
34662 cases where such content would fit within the charter of a list and it
34663 would therefore probably rate a warning (or ban) on that basis alone.
34665 * Advertising of non-DragonFly related products or services is strictly
34666 prohibited and will result in an immediate ban if it is clear that the
34667 offender is advertising by spam.
34669 ----------------------------------------------------------------------
34671 C.1.4 Filtering on the Mailing Lists
34673 The DragonFly mailing lists are filtered in multiple ways to avoid the
34674 distribution of spam, viruses, and other unwanted emails. The filtering
34675 actions described in this section do not include all those used to protect
34678 Only certain types of attachments are allowed on the mailing lists. All
34679 attachments with a MIME content type not found in the list below will be
34680 stripped before an email is distributed on the mailing lists.
34682 * application/octet-stream
34686 * application/pgp-signature
34688 * application/x-pkcs7-signature
34692 * multipart/alternative
34694 * multipart/related
34706 Note: Some of the mailing lists might allow attachments of other MIME
34707 content types, but the above list should be applicable for most of the
34710 If an email contains both an HTML and a plain text version, the HTML
34711 version will be removed. If an email contains only an HTML version, it
34712 will be converted to plain text.
34714 ----------------------------------------------------------------------
34716 C.2 Usenet Newsgroups
34718 All the DragonFly mailing lists are duplicated as newsgroups, served at
34719 nntp.dragonflybsd.org.
34721 In addition to these newsgroups, there are many others in which DragonFly
34722 is discussed or are otherwise relevant to DragonFly users. Keyword
34723 searchable archives are available for some of these newsgroups from
34724 courtesy of Warren Toomey <wkt@cs.adfa.edu.au>.
34726 ----------------------------------------------------------------------
34728 C.2.1 BSD Specific Newsgroups
34730 * comp.unix.bsd.freebsd.announce
34732 * de.comp.os.unix.bsd (German)
34734 * fr.comp.os.bsd (French)
34736 * it.comp.os.freebsd (Italian)
34738 ----------------------------------------------------------------------
34740 C.2.2 Other UNIX Newsgroups of Interest
34744 * comp.unix.questions
34748 * comp.unix.programmer
34752 * comp.unix.user-friendly
34754 * comp.security.unix
34756 * comp.sources.unix
34758 * comp.unix.advocacy
34764 * comp.bugs.4bsd.ucb-fixes
34768 ----------------------------------------------------------------------
34770 C.2.3 X Window System
34772 * comp.windows.x.i386unix
34776 * comp.windows.x.apps
34778 * comp.windows.x.announce
34780 * comp.windows.x.intrinsics
34782 * comp.windows.x.motif
34784 * comp.windows.x.pex
34786 * comp.emulators.ms-windows.wine
34788 ----------------------------------------------------------------------
34790 C.3 World Wide Web Servers
34794 (as of 2005/06/27 23:37:47 UTC)
34798 * http://www.DragonFlyBSD.org/
34800 ----------------------------------------------------------------------
34802 Appendix D. PGP Keys
34804 In case you need to verify a signature or send encrypted email to one of
34805 the developers, a number of keys are provided here for your convenience.
34807 ----------------------------------------------------------------------
34811 D.1.1 Hiten Pandya <hmp at dragonflybsd.org>
34813 pub 1024D/938CACA8 2004-02-13 Hiten Pandya (FreeBSD) <hmp@FreeBSD.org>
34814 Key fingerprint = 84EB C75E C75A 50ED 304E E446 D974 7842 938C ACA8
34815 uid Hiten Pandya <hmp@backplane.com>
34816 sub 2048g/783874B5 2004-02-13
34818 -----BEGIN PGP PUBLIC KEY BLOCK-----
34820 mQGiBEAscLQRBADERe+RX2eJpYLoaJ7d29B8YcTYzNlsfzghM1R1/Dx2RDy5poKa
34821 Jn9j+Iptq1qS9GkTHXFcQh8LT2K7wnE/MZTCxkZvg2ZkfQbJ4Z+0z3A1A6Kvg0tH
34822 X5aqmPUeLXvnps7nqZxkhl2ibcjhH/VYZK3mdRikd1wtJD1EhbbeqaR8BwCgkQAG
34823 vdJHN9gfjLLcM12EitkjoUcEALoo1bPoULWd4YhVH7W5L3Qp0dr1vf5pYC/V7FQ+
34824 8yPXZtGzMvIld8iX1sv/zsw4EoXXsaRzJo/ixdCS1WYBPowryu0G/LX5w0RTTGHc
34825 ihcHLm6ZmyNuIsTQ1ifLNASJoLkNBlQAuA0VG4evAujrmaWyEHbbIDSQKUJOjL9u
34826 jb2HA/9pycrr3+735Aa7B5jThN6p1XEC8GQg5MDx23QnTPj9QHXH4qs7s+hwxZq9
34827 3WkVFBcJtDBi8PeEVqfD/QPeU3ewbnNnfaF46miGV1iG1mzU4zMq4n5oBdijf5eL
34828 cRRdOJytYKTvlSCe8gf0MzfaB3RqD8+Cjcs3PtQOy1VT4aQiv7QgSGl0ZW4gUGFu
34829 ZHlhIDxobXBAYmFja3BsYW5lLmNvbT6IXgQTEQIAHgUCQCxw7AIbAwYLCQgHAwID
34830 FQIDAxYCAQIeAQIXgAAKCRDZdHhCk4ysqEPZAJ9ByMndfTtnnVIbsyHc2NjDp5F/
34831 vgCeP6o87Lw4aHuGo5guA9yeWwtwAla0KEhpdGVuIFBhbmR5YSAoRnJlZUJTRCkg
34832 PGhtcEBGcmVlQlNELm9yZz6IYQQTEQIAIQIbAwYLCQgHAwIDFQIDAxYCAQIeAQIX
34833 gAUCQCxxDgIZAQAKCRDZdHhCk4ysqLchAJ4+01/uQVdqdDeESGodcvgKsrieqACb
34834 BIW7HMvh85WqofTeAK5pJu7hCM25Ag0EQCxw2BAIAPXEkkg6lSxGRmVH1yzRnSKr
34835 /M48xyRXYDrRPaVVBFkC4Af3CR5MjncJtjbzm7xH82glC67cksRTfTZRs7kJsid+
34836 g62V53dAu1Uoj8ecSDhblb8yW3rTLKVqGcliGcTRFivcm+ZFm0kc0xCQE3rd1COX
34837 NLEomMV6xuZ9PVzDAbJwAoGdpCYsCl09eZrTErueQ7pEVsLx9/0zQSmC/uDFEVZ7
34838 23GsJg23+EUBT5KuTxQ4i0k++Ccr4HR/OiUy6KmyXSNsKsBsXwm3map3Debqqqx1
34839 ssrDXa+PHkKEUrONQBoYbZ17DpPZb+NKWibi0Vp1HKPP2vZl4NZQC0GBLXbEudMA
34840 AwYIAOYhwVTWKQSgeEZUNe4PwvHczx8/3VNjYZGY6/ZRjgmfO3+MagjonZqfxYha
34841 GpsEV17NXm4WIg6HWtI43JwIWfkUybsdxQVH4i5lWYuA26wD6UtNXw9laPHKXonR
34842 DvmKDC6K0iFbSxTqXRZVQ//wMxh58/Yw/fX+fYtmH6u6kPaL+CPRkhQLezTzZWHj
34843 2wF6v+frdglW1/LpwpCFndb1i5+36ogZ5ZudG/iz53QzlOF0IZSGHIb9tlQ+4gUn
34844 KfxpQloI+5vAyqpHDKIH9K26wTBzKsp5Mt4W6cLfgjXs7TNc8BVT8d4rmmbGpGnG
34845 pSjj7b1q6EhpIVBkAMLw7qanLlCISQQYEQIACQUCQCxw2AIbDAAKCRDZdHhCk4ys
34846 qAuZAJ0VNEtJSZOAGetxBJ/BMWahVD8xeQCfVKwTHdPh83Qcf28xx81icY5OKY0=
34848 -----END PGP PUBLIC KEY BLOCK-----
34850 ----------------------------------------------------------------------
34854 This book is the combined work of hundreds of contributors to ``The
34855 FreeBSD Documentation Project'' and the ``The DragonFly BSD Documentation
34856 Project''. The text is authored in SGML according to the DocBook DTD and
34857 is formatted from SGML into many different presentation formats using
34858 Jade, an open source DSSSL engine. Norm Walsh's DSSSL stylesheets were
34859 used with an additional customization layer to provide the presentation
34860 instructions for Jade. The printed version of this document would not be
34861 possible without Donald Knuth's TeX typesetting language, Leslie Lamport's
34862 LaTeX, or Sebastian Rahtz's JadeTeX macro package.
34866 [1] This is what i386 means. Note that even if you are not running
34867 DragonFly on an Intel 386 CPU, this is going to be i386. It is not
34868 the type of your processor, but the processor ``architecture'' that
34870 [2] Startup scripts are programs that are run automatically by DragonFly
34871 when booting. Their main function is to set things up for everything
34872 else to run, and start any services that you have configured to run
34873 in the background doing useful things.
34874 [3] A fairly technical and accurate description of all the details of the
34875 DragonFly console and keyboard drivers can be found in the manual
34876 pages of syscons(4), atkbd(4), vidcontrol(1) and kbdcontrol(1). We
34877 will not expand on the details here, but the interested reader can
34878 always consult the manual pages for a more detailed and thorough
34879 explanation of how things work.
34880 [4] Not quite true--there are a few things that can not be interrupted.
34881 For example, if the process is trying to read from a file that is on
34882 another computer on the network, and the other computer has gone away
34883 for some reason (been turned off, or the network has a fault), then
34884 the process is said to be ``uninterruptible''. Eventually the process
34885 will time out, typically after two minutes. As soon as this time out
34886 occurs the process will be killed.
34887 [5] Previously this was used to define *BSD dependent features.
34888 [6] Well, unless you hook up multiple terminals, but we will save that
34890 [7] It is possible to use UID/GIDs as large as 4294967295, but such IDs
34891 can cause serious problems with software that makes assumptions about
34893 [8] The -s makes adduser(8) default to quiet. We use -v later when we
34894 want to change defaults.
34895 [9] The auto-tuning algorithm sets maxuser equal to the amount of memory
34896 in the system, with a minimum of 32, and a maximum of 384.
34897 [10] Under DragonFly the standard login password may be up to 128
34898 characters in length.
34899 [11] RAID stands for Redundant Array of Inexpensive Disks and offers
34900 various forms of fault tolerance, though the latter term is somewhat
34901 misleading: it provides no redundancy.
34902 [12] A popular familiar graphics card with generally very good XFree86
34903 performance, nVidia, has yet to release the specifications on their
34904 XVideo support to the XFree86 team. It may be some time before
34905 XFree86 fully support XVideo for these cards.
34906 [13] Unauthorized DVD playback is a serious criminal act in some
34907 countries. Check local laws before enabling this option.
34908 [14] FreeBSD's original Linux compatibility code was committed in June
34909 1995. It fulfilled milestone number one: running DOOM.
34911 ----------------------------------------------------------------------
34913 Contact the Documentation mailing list for comments, suggestions and questions
34914 about this document.
projects / dragonfly.git / blob