DragonFly Handbook
The DragonFly Documentation Project
Copyright (c) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
2003, 2004 The FreeBSD Documentation Project
Copyright (c) 2004, 2005, 2006 The DragonFly Documentation Project
Welcome to DragonFly! This handbook covers the installation and
day to day use of the DragonFly operating system. This manual is a
work in progress and is the work of many individuals. Many
sections do not yet exist and some of those that do exist need to
be updated. If you are interested in helping with this project,
send email to the DragonFly Documentation project mailing list.
The latest version of this document is always available from the
DragonFly web site or mirror sites, in a variety of formats.
Portions of this document originally documented use of the FreeBSD
operating system. While many functions should be similar on
DragonFly, some differences should be expected. If you find
instructions here that no longer apply to DragonFly, please
contact the documentation mailing list at DragonFly Documentation
project mailing list .
Redistribution and use in source (SGML DocBook) and 'compiled'
forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or
without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code (SGML DocBook) must retain the
above copyright notice, this list of conditions and the
following disclaimer as the first lines of this file
unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must
reproduce the above copyright notice, this list of conditions
and the following disclaimer in the documentation and/or other
materials provided with the distribution.
Important: THIS DOCUMENTATION IS PROVIDED BY THE DRAGONFLYBSD
PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE DRAGONFLYBSD PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
DragonFlyBSD is a registered trademark of the DragonFlyBSD
Project.
FreeBSD is a registered trademark of Wind River Systems, Inc. This
is expected to change soon.
NetBSD is a registered trademark of The NetBSD Foundation, Inc.
3Com and HomeConnect are registered trademarks of 3Com
Corporation.
3ware and Escalade are registered trademarks of 3ware Inc.
ARM is a registered trademark of ARM Limited.
Adaptec is a registered trademark of Adaptec, Inc.
Adobe, Acrobat, Acrobat Reader, and PostScript are either
registered trademarks or trademarks of Adobe Systems Incorporated
in the United States and/or other countries.
Apple, FireWire, Mac, Macintosh, Mac OS, Quicktime, and TrueType
are trademarks of Apple Computer, Inc., registered in the United
States and other countries.
Corel and WordPerfect are trademarks or registered trademarks of
Corel Corporation and/or its subsidiaries in Canada, the United
States and/or other countries.
Sound Blaster is a trademark of Creative Technology Ltd. in the
United States and/or other countries.
CVSup is a registered trademark of John D. Polstra.
Heidelberg, Helvetica, Palatino, and Times Roman are either
registered trademarks or trademarks of Heidelberger Druckmaschinen
AG in the U.S. and other countries.
IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, and
ThinkPad are trademarks of International Business Machines
Corporation in the United States, other countries, or both.
IEEE, POSIX, and 802 are registered trademarks of Institute of
Electrical and Electronics Engineers, Inc. in the United States.
Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, and
Xeon are trademarks or registered trademarks of Intel Corporation
or its subsidiaries in the United States and other countries.
Intuit and Quicken are registered trademarks and/or registered
service marks of Intuit Inc., or one of its subsidiaries, in the
United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United
States.
LSI Logic, AcceleRAID, eXtremeRAID, MegaRAID and Mylex are
trademarks or registered trademarks of LSI Logic Corp.
M-Systems and DiskOnChip are trademarks or registered trademarks
of M-Systems Flash Disk Pioneers, Ltd.
Macromedia, Flash, and Shockwave are trademarks or registered
trademarks of Macromedia, Inc. in the United States and/or other
countries.
Microsoft, FrontPage, MS-DOS, Outlook, Windows, Windows Media, and
Windows NT are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
Netscape and the Netscape Navigator are registered trademarks of
Netscape Communications Corporation in the U.S. and other
countries.
GateD and NextHop are registered and unregistered trademarks of
NextHop in the U.S. and other countries.
Motif, OSF/1, and UNIX are registered trademarks and IT DialTone
and The Open Group are trademarks of The Open Group in the United
States and other countries.
Oracle is a registered trademark of Oracle Corporation.
pkgsrc is a registered trademark of The NetBSD Foundation, Inc.
PowerQuest and PartitionMagic are registered trademarks of
PowerQuest Corporation in the United States and/or other
countries.
RealNetworks, RealPlayer, and RealAudio are the registered
trademarks of RealNetworks, Inc.
Red Hat, RPM, are trademarks or registered trademarks of Red Hat,
Inc. in the United States and other countries.
SAP, R/3, and mySAP are trademarks or registered trademarks of SAP
AG in Germany and in several other countries all over the world.
Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer
Pages, JDK, JSP, JVM, Netra, Solaris, StarOffice, Sun Blade, Sun
Enterprise, Sun Fire, SunOS, and Ultra are trademarks or
registered trademarks of Sun Microsystems, Inc. in the United
States and other countries.
Symantec and Ghost are registered trademarks of Symantec
Corporation in the United States and other countries.
MATLAB is a registered trademark of The MathWorks, Inc.
SpeedTouch is a trademark of Thomson
U.S. Robotics and Sportster are registered trademarks of U.S.
Robotics Corporation.
VMware is a trademark of VMware, Inc.
Waterloo Maple and Maple are trademarks or registered trademarks
of Waterloo Maple Inc.
Mathematica is a registered trademark of Wolfram Research, Inc.
XFree86 is a trademark of The XFree86 Project, Inc.
Ogg Vorbis and Xiph.Org are trademarks of Xiph.Org.
Many of the designations used by manufacturers and sellers to
distinguish their products are claimed as trademarks. Where those
designations appear in this document, and the FreeBSD Project was
aware of the trademark claim, the designations have been followed
by the ``(TM)'' or the ``(R)'' symbol.
--------------------------------------------------------------
Table of Contents
Preface
I. Getting Started
1 Introduction
1.1 Synopsis
1.2 Welcome to DragonFly!
1.3 About the DragonFly Project
2 Installation from CD
2.1 CD Installation Overview
2.2 CD Installation - Making room
2.3 CD Installation - Disk setup
2.4 Installing to Disk from CD
2.5 CD Installation - Post-install
cleanup
2.6 CD Installation - New system setup
3 UNIX Basics
3.1 Synopsis
3.2 Virtual Consoles and Terminals
3.3 Permissions
3.4 Directory Structure
3.5 Disk Organization
3.6 Mounting and Unmounting File Systems
3.7 Processes
3.8 Daemons, Signals, and Killing
Processes
3.9 Shells
3.10 Text Editors
3.11 Devices and Device Nodes
3.12 Binary Formats
3.13 For More Information
4 Installing Applications using NetBSD's pkgsrc
framework
4.1 Synopsis
4.2 Overview of Software Installation
4.3 Finding Your Application
4.4 Using the Binary Packages System
4.5 Using the pkgsrc(R) Source Tree
4.6 Post-installation Activities
4.7 Dealing with Broken Packages
5 The X Window System
5.1 Synopsis
5.2 Understanding X
5.3 Installing X11
5.4 X11 Configuration
5.5 Using Fonts in X11
5.6 The X Display Manager
5.7 Desktop Environments
II. System Administration
6 Configuration and Tuning
6.1 Synopsis
6.2 Initial Configuration
6.3 Core Configuration
6.4 Application Configuration
6.5 Starting Services
6.6 Configuring the cron Utility
6.7 Using rc under DragonFly
6.8 Setting Up Network Interface Cards
6.9 Virtual Hosts
6.10 Configuration Files
6.11 Tuning with sysctl
6.12 Tuning Disks
6.13 Tuning Kernel Limits
6.14 Adding Swap Space
6.15 Power and Resource Management
6.16 Using and Debugging DragonFly ACPI
7 The DragonFly Booting Process
7.1 Synopsis
7.2 The Booting Problem
7.3 The Boot Manager and Boot Stages
7.4 Kernel Interaction During Boot
7.5 Init: Process Control Initialization
7.6 Shutdown Sequence
8 Users and Basic Account Management
8.1 Synopsis
8.2 Introduction
8.3 The Superuser Account
8.4 System Accounts
8.5 User Accounts
8.6 Modifying Accounts
8.7 Limiting Users
8.8 Personalizing Users
8.9 Groups
9 Configuring the DragonFly Kernel
9.1 Synopsis
9.2 Why Build a Custom Kernel?
9.3 Building and Installing a Custom
Kernel
9.4 The Configuration File
9.5 Making Device Nodes
9.6 If Something Goes Wrong
10 Security
10.1 Synopsis
10.2 Introduction
10.3 Securing DragonFly
10.4 DES, MD5, and Crypt
10.5 One-time Passwords
10.6 Kerberos5
10.7 Firewalls
10.8 OpenSSL
10.9 VPN over IPsec
10.10 OpenSSH
11 Printing
11.1 Synopsis
11.2 Introduction
11.3 Basic Setup
11.4 Advanced Printer Setup
11.5 Using Printers
11.6 Alternatives to the Standard
Spooler
11.7 Troubleshooting
12 Storage
12.1 Synopsis
12.2 Device Names
12.3 Adding Disks
12.4 RAID
12.5 Creating and Using Optical Media
(CDs)
12.6 Creating and Using Optical Media
(DVDs)
12.7 Creating and Using Floppy Disks
12.8 Creating and Using Data Tapes
12.9 Backups to Floppies
12.10 Backup Basics
12.11 Network, Memory, and File-Backed
File Systems
12.12 File System Quotas
13 The Vinum Volume Manager
13.1 Synopsis
13.2 Disks Are Too Small
13.3 Access Bottlenecks
13.4 Data Integrity
13.5 Vinum Objects
13.6 Some Examples
13.7 Object Naming
13.8 Configuring Vinum
13.9 Using Vinum for the Root Filesystem
14 Localization - I18N/L10N Usage and Setup
14.1 Synopsis
14.2 The Basics
14.3 Using Localization
14.4 Compiling I18N Programs
14.5 Localizing DragonFly to Specific
Languages
15 Desktop Applications
15.1 Synopsis
15.2 Browsers
15.3 Productivity
15.4 Document Viewers
15.5 Finance
15.6 Summary
16 Multimedia
16.1 Synopsis
16.2 Setting Up the Sound Card
16.3 MP3 Audio
16.4 Video Playback
16.5 Setting Up TV Cards
17 Serial Communications
17.1 Synopsis
17.2 Introduction
17.3 Terminals
17.4 Dial-in Service
17.5 Dial-out Service
17.6 Setting Up the Serial Console
18 PPP and SLIP
18.1 Synopsis
18.2 Using User PPP
18.3 Using Kernel PPP
18.4 Troubleshooting PPP Connections
18.5 Using PPP over Ethernet (PPPoE)
18.6 Using SLIP
19 Advanced Networking
19.1 Synopsis
19.2 Gateways and Routes
19.3 Wireless Networking
19.4 Bluetooth
19.5 Bridging
19.6 NFS
19.7 Diskless Operation
19.8 ISDN
19.9 NIS/YP
19.10 DHCP
19.11 DNS
19.12 NTP
19.13 Network Address Translation
19.14 The inetd ``Super-Server''
19.15 Parallel Line IP (PLIP)
19.16 IPv6
20 Electronic Mail
20.1 Synopsis
20.2 Using Electronic Mail
20.3 sendmail Configuration
20.4 Changing Your Mail Transfer Agent
20.5 Troubleshooting
20.6 Advanced Topics
20.7 SMTP with UUCP
20.8 Setting up to send only
20.9 Using Mail with a Dialup Connection
20.10 SMTP Authentication
20.11 Mail User Agents
20.12 Using fetchmail
20.13 Using procmail
21 Updating DragonFly
21.1 Initial Setup
21.2 Configuration
21.3 Preparing to Update
21.4 Updating the System
22 Linux Binary Compatibility
22.1 Synopsis
22.2 Installation
22.3 Installing Mathematica(R)
22.4 Installing Maple(TM)
22.5 Installing MATLAB(R)
22.6 Installing Oracle(R)
22.7 Installing SAP(R) R/3(R)
22.8 Advanced Topics
III. Appendices
A. Obtaining DragonFly
A.1 CDROM and DVD Publishers
A.2 FTP Sites
A.3 Using CVSup
A.4 CVS Tags
B. Bibliography
B.1 Books & Magazines Specific to BSD
B.2 Users' Guides
B.3 Administrators' Guides
B.4 Programmers' Guides
B.5 Operating System Internals
B.6 Security Reference
B.7 Hardware Reference
B.8 UNIX History
B.9 Magazines and Journals
C. Resources on the Internet
C.1 Mailing Lists
C.2 Usenet Newsgroups
C.3 World Wide Web Servers
D. PGP Keys
D.1 Developers
Colophon
List of Tables
3-1. Disk Device Codes
12-1. Physical Disk Naming Conventions
13-1. Vinum Plex Organizations
19-1. Wiring a Parallel Cable for Networking
19-2. Reserved IPv6 addresses
List of Figures
13-1. Concatenated Organization
13-2. Striped Organization
13-3. RAID-5 Organization
13-4. A Simple Vinum Volume
13-5. A Mirrored Vinum Volume
13-6. A Striped Vinum Volume
13-7. A Mirrored, Striped Vinum Volume
List of Examples
3-1. Sample Disk, Slice, and Partition Names
3-2. Conceptual Model of a Disk
4-1. Downloading a Package Manually and Installing It Locally
6-1. Creating a Swapfile
7-1. boot0 Screenshot
7-2. boot2 Screenshot
7-3. An Insecure Console in /etc/ttys
8-1. Configuring adduser and adding a user
8-2. rmuser Interactive Account Removal
8-3. Interactive chpass by Superuser
8-4. Interactive chpass by Normal User
8-5. Changing Your Password
8-6. Changing Another User's Password as the Superuser
8-7. Adding a Group Using pw(8)
8-8. Adding Somebody to a Group Using pw(8)
8-9. Using id(1) to Determine Group Membership
10-1. Using SSH to Create a Secure Tunnel for SMTP
12-1. Using dump over ssh
12-2. Using dump over ssh with RSH set
12-3. A Script for Creating a Bootable Floppy
12-4. Using vnconfig to Mount an Existing File System Image
12-5. Creating a New File-Backed Disk with vnconfig
12-6. md Memory Disk
17-1. Adding Terminal Entries to /etc/ttys
19-1. Mounting an Export with amd
19-2. Branch Office or Home Network
19-3. Head Office or Other LAN
19-4. Sending inetd a HangUP Signal
20-1. Configuring the sendmail Access Database
20-2. Mail Aliases
20-3. Example Virtual Domain Mail Map
--------------------------------------------------------------
Preface
Intended Audience
The DragonFly newcomer will find that the first section of this
book guides the user through the DragonFly installation process
and gently introduces the concepts and conventions that underpin
UNIX(R). Working through this section requires little more than
the desire to explore, and the ability to take on board new
concepts as they are introduced.
Once you have travelled this far, the second, far larger, section
of the Handbook is a comprehensive reference to all manner of
topics of interest to DragonFly system administrators. Some of
these chapters may recommend that you do some prior reading, and
this is noted in the synopsis at the beginning of each chapter.
For a list of additional sources of information, please see
Appendix B.
Organization of This Book
This book is split into three logically distinct sections. The
first section, Getting Started, covers the installation and basic
usage of DragonFly. It is expected that the reader will follow
these chapters in sequence, possibly skipping chapters covering
familiar topics. The second section, System Administration, covers
a broad collection of subjects that are of interest to more
advanced DragonFly users. Each section begins with a succinct
synopsis that describes what the chapter covers and what the
reader is expected to already know. This is meant to allow the
casual reader to skip around to find chapters of interest. The
third section contains appendices of reference information.
Chapter 1, Introduction
Introduces DragonFly to a new user. It describes the
history of the DragonFly Project, its goals and
development model.
Chapter 2, Installation
Walks a user through the entire installation process. Some
advanced installation topics, such as installing through a
serial console, are also covered.
Chapter 3, UNIX Basics
Covers the basic commands and functionality of the
DragonFly operating system. If you are familiar with Linux
or another flavor of UNIX then you can probably skip this
chapter.
Chapter 4, Installing Applications
Covers the installation of third-party software using
NetBSD(R)'s Packages Collection pkgsrc(R).
Chapter 5, The X Window System
Describes the X Window System in general and using
XFree86(TM) and X.org on DragonFly in particular. Also
describes common desktop environments such as KDE and
GNOME.
Chapter 6, Configuration and Tuning
Describes the parameters available for system
administrators to tune a DragonFly system for optimum
performance. Also describes the various configuration
files used in DragonFly and where to find them.
Chapter 7, Booting Process
Describes the DragonFly boot process and explains how to
control this process with configuration options.
Chapter 8, Users and Basic Account Management
Describes the creation and manipulation of user accounts.
Also discusses resource limitations that can be set on
users and other account management tasks.
Chapter 9, Configuring the DragonFly Kernel
Explains why you might need to configure a new kernel and
provides detailed instructions for configuring, building,
and installing a custom kernel.
Chapter 10, Security
Describes many different tools available to help keep your
DragonFly system secure, including Kerberos, IPsec,
OpenSSH, and network firewalls.
Chapter 11, Printing
Describes managing printers on DragonFly, including
information about banner pages, printer accounting, and
initial setup.
Chapter 12, Storage
Describes how to manage storage media and filesystems with
DragonFly. This includes physical disks, RAID arrays,
optical and tape media, memory-backed disks, and network
filesystems.
Chapter 13, Vinum
Describes how to use Vinum, a logical volume manager which
provides device-independent logical disks, and software
RAID-0, RAID-1 and RAID-5.
Chapter 14, Localization
Describes how to use DragonFly in languages other than
English. Covers both system and application level
localization.
Chapter 15, Desktop Applications
Lists some common desktop applications, such as web
browsers and productivity suites, and describes how to
install them on DragonFly.
Chapter 16, Multimedia
Shows how to set up sound and video playback support for
your system. Also describes some sample audio and video
applications.
Chapter 17, Serial Communications
Explains how to connect terminals and modems to your
DragonFly system for both dial in and dial out
connections.
Chapter 18, PPP and SLIP
Describes how to use PPP, SLIP, or PPP over Ethernet to
connect to remote systems with DragonFly.
Chapter 19, Advanced Networking
Describes many networking topics, including sharing an
Internet connection with other computers on your LAN,
using network filesystems, sharing account information via
NIS, setting up a name server, and much more.
Chapter 20, Electronic Mail
Explains the different components of an email server and
dives into simple configuration topics for the most
popular mail server software: sendmail.
Section 21.1, Updating DragonFly
Describes the development paths of DragonFly, and how to
stay up-to-date.
Chapter 22, Linux Binary Compatibility
Describes the Linux compatibility features of DragonFly.
Also provides detailed installation instructions for many
popular Linux applications such as Oracle(R),
SAP(R) R/3(R), and Mathematica(R).
Appendix A, Obtaining DragonFly
Lists different sources for obtaining DragonFly media on
CDROM or DVD as well as different sites on the Internet
that allow you to download and install DragonFly.
Appendix B, Bibliography
This book touches on many different subjects that may
leave you hungry for a more detailed explanation. The
bibliography lists many excellent books that are
referenced in the text.
Appendix C, Resources on the Internet
Describes the many forums available for DragonFly users to
post questions and engage in technical conversations about
DragonFly.
Appendix D, PGP Keys
Lists the PGP fingerprints of several DragonFly
Developers.
Conventions used in this book
To provide a consistent and easy to read text, several conventions
are followed throughout the book.
Typographic Conventions
Italic
An italic font is used for filenames, URLs, emphasized
text, and the first usage of technical terms.
Monospace
A monospaced font is used for error messages, commands,
environment variables, names of ports, hostnames, user
names, group names, device names, variables, and code
fragments.
Bold
A bold font is used for applications, commands, and keys.
User Input
Keys are shown in bold to stand out from other text. Key
combinations that are meant to be typed simultaneously are shown
with `+' between the keys, such as:
Ctrl+Alt+Del
Meaning the user should type the Ctrl, Alt,and Del keys at the
same time.
Keys that are meant to be typed in sequence will be separated with
commas, for example:
Ctrl+X, Ctrl+S
Would mean that the user is expected to type the Ctrl and X keys
simultaneously and then to type the Ctrl and S keys
simultaneously.
Examples
Examples starting with # indicate a command that must be invoked
as the superuser in DragonFly. You can login as root to type the
command, or login as your normal account and use su(1) to gain
superuser privileges.
# dd if=kern.flp of=/dev/fd0
Examples starting with % indicate a command that should be invoked
from a normal user account. Unless otherwise noted, C-shell syntax
is used for setting environment variables and other shell
commands.
% top
Examples starting with E:\> indicate a MS-DOS(R) command. Unless
otherwise noted, these commands may be executed from a ``Command
Prompt'' window in a modern Microsoft(R) Windows(R) environment.
E:\> tools\fdimage floppies\kern.flp A:
Acknowledgments
The book you are holding represents the efforts of many hundreds
of people around the world. Whether they sent in fixes for typos,
or submitted complete chapters, all the contributions have been
useful.
The DragonFly Handbook was originally built from an edition of the
FreeBSD Handbook. The FreeBSD Handbook was created by the
collective hard work of hundreds of people, and the DragonFly
Documentation Team appreciates all their labor. Included here is a
list of all individually identified people and corporations that
contributed resources to this handbook.
Eric Anderson, Satoshi Asami, Bojan Bistrovic, Neil Blakey-Milner,
Andrew Boothman, Harti Brandt, Jim Brown, BSDi, Andrey A. Chernov,
Peter Childs, Munish Chopra, Joe Marcus Clarke, Nik Clayton, Mark
Dapoz, Matt Dillon, Jean-Franc,ois Dockes, Alex Dupre, Josef
El-Rayes, Udo Erdelhoff, Marc Fonvieille, Dirk Fro:mberg, Robert
Getschmann, James Gorham, Lucky Green, Coranth Gryphon, Jake
Hamby, Brian N. Handy, Guy Helmer, Al Hoang, Tillman Hodgson,
Jordan Hubbard, Robert Huff, Tom Hukins, Christophe Juniet,
Poul-Henning Kamp, Aaron Kaplan, Martin Karlsson, Sean Kelly, Seth
Kingsley, Holger Kipp, Nate Lawson, Chern Lee, Greg Lehey, John
Lind, Ross Lippert, Bill Lloyd, Pav Lucistnik, Julio Merino, Mike
Meyer, Hellmuth Michaelis, Jim Mock, Marcel Moolenaar, Moses
Moore, Bill Moran, Rich Murphey, Mark Murray, Alex Nash, Gregory
Neil Shapiro, David O'Brien, Eric Ogren, Gary Palmer, Hiten M.
Pandya, Bill Paul, Dan Pelleg, Steve Peterson, John Polstra, Andy
Polyakov, Randy Pratt, Jeremy C. Reed, Tom Rhodes, Trev Roydhouse,
Peter Schultz, Piero Serini, Christopher Shumway, Marc Silver,
Mike Smith, Brian Somers, Gennady B. Sorokopud, Wylie Stilwell,
Murray Stokely, Greg Sutter, Bill Swingle, Valentino Vaschetto,
Robert Watson, Wind River Systems, Michael C. Wu, and Kazutaka
YOKOTA.
I. Getting Started
This part of the DragonFly Handbook is for users and
administrators who are new to DragonFly. These chapters:
* Introduce you to DragonFly.
* Guide you through the installation process.
* Teach you UNIX basics and fundamentals.
* Show you how to install the wealth of third party applications
available for DragonFly.
* Introduce you to X, the UNIX windowing system, and detail how
to configure a desktop environment that makes you more
productive.
We have tried to keep the number of forward references in the text
to a minimum so that you can read this section of the Handbook
from front to back with the minimum page flipping required.
Table of Contents
1 Introduction
2 Installation from CD
3 UNIX Basics
4 Installing Applications using NetBSD's pkgsrc framework
5 The X Window System
--------------------------------------------------------------
Chapter 1 Introduction
Restructured, reorganized, and parts rewritten by Jim Mock.
1.1 Synopsis
Thank you for your interest in DragonFly! The following chapter
covers various aspects of the DragonFly Project, such as its
history, goals, development model, and so on.
After reading this chapter, you will know:
* How DragonFly relates to other computer operating systems.
* The history of the DragonFly Project.
* The goals of the DragonFly Project.
* The basics of the DragonFly open-source development model.
* And of course: where the name ``DragonFly'' comes from.
--------------------------------------------------------------
1.2 Welcome to DragonFly!
DragonFly is a 4.4BSD-Lite based operating system for Intel (x86).
A port to AMD64 is in progress. You can also read about the
history of DragonFly, or the current release.
--------------------------------------------------------------
1.2.1 What Can DragonFly Do?
DragonFly has many noteworthy features. Some of these are:
* Preemptive multitasking with dynamic priority adjustment to
ensure smooth and fair sharing of the computer between
applications and users, even under the heaviest of loads.
* Multi-user facilities which allow many people to use a
DragonFly system simultaneously for a variety of things. This
means, for example, that system peripherals such as printers
and tape drives are properly shared between all users on the
system or the network and that individual resource limits can
be placed on users or groups of users, protecting critical
system resources from over-use.
* Strong TCP/IP networking with support for industry standards
such as SLIP, PPP, NFS, DHCP, and NIS. This means that your
DragonFly machine can interoperate easily with other systems
as well as act as an enterprise server, providing vital
functions such as NFS (remote file access) and email services
or putting your organization on the Internet with WWW, FTP,
routing and firewall (security) services.
* Memory protection ensures that applications (or users) cannot
interfere with each other. One application crashing will not
affect others in any way.
* DragonFly is a 32-bit operating system.
* The industry standard X Window System (X11R6) provides a
graphical user interface (GUI) for the cost of a common VGA
card and monitor and comes with full sources.
* Binary compatibility with many programs built for Linux, SCO,
SVR4, BSDI and NetBSD.
* Thousands of ready-to-run applications are available from the
pkgsrc packages collection. Why search the net when you can
find it all right here?
* Thousands of additional and easy-to-port applications are
available on the Internet. DragonFly is source code compatible
with most popular commercial UNIX systems and thus most
applications require few, if any, changes to compile.
* Demand paged virtual memory and ``merged VM/buffer cache''
design efficiently satisfies applications with large appetites
for memory while still maintaining interactive response to
other users.
* SMP support for machines with multiple CPUs.
* A full complement of C, C++, Fortran, and Perl development
tools. Many additional languages for advanced research and
development are also available in the ports and packages
collection.
* Source code for the entire system means you have the greatest
degree of control over your environment. Why be locked into a
proprietary solution at the mercy of your vendor when you can
have a truly open system?
* Extensive online documentation.
* And many more!
DragonFly is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, along with later development of FreeBSD by the FreeBSD
Project. It carries on the distinguished tradition of BSD systems
development. In addition to the fine work provided by CSRG, the
DragonFly Project has put in many thousands of hours in fine
tuning the system for maximum performance and reliability in
real-life load situations. As many of the commercial giants
struggle to field PC operating systems with such features,
performance and reliability, DragonFly can offer them now!
The applications to which DragonFly can be put are truly limited
only by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote
satellite antennae; if it can be done with a commercial UNIX
product then it is more than likely that you can do it with
DragonFly too! DragonFly also benefits significantly from
literally thousands of high quality applications developed by
research centers and universities around the world, often
available at little to no cost. Commercial applications are also
available and appearing in greater numbers every day.
Because the source code for DragonFly itself is generally
available, the system can also be customized to an almost unheard
of degree for special applications or projects, and in ways not
generally possible with operating systems from most major
commercial vendors. Here is just a sampling of some of the
applications in which people are currently using DragonFly:
* Internet Services: The robust TCP/IP networking built into
DragonFly makes it an ideal platform for a variety of Internet
services such as:
* FTP servers
* World Wide Web servers (standard or secure [SSL])
* Firewalls and NAT (``IP masquerading'') gateways
* Electronic Mail servers
* USENET News or Bulletin Board Systems
* And more...
With DragonFly, you can easily start out small with an
inexpensive 386 class PC and upgrade all the way up to a
quad-processor Xeon with RAID storage as your enterprise
grows.
* Education: Are you a student of computer science or a related
engineering field? There is no better way of learning about
operating systems, computer architecture and networking than
the hands on, under the hood experience that DragonFly can
provide. A number of freely available CAD, mathematical and
graphic design packages also make it highly useful to those
whose primary interest in a computer is to get other work
done!
* Research: With source code for the entire system available,
DragonFly is an excellent platform for research in operating
systems as well as other branches of computer science.
DragonFly's freely available nature also makes it possible for
remote groups to collaborate on ideas or shared development
without having to worry about special licensing agreements or
limitations on what may be discussed in open forums.
* Networking: Need a new router? A name server (DNS)? A firewall
to keep people out of your internal network? DragonFly can
easily turn that unused older PC sitting in the corner into an
advanced router with sophisticated packet-filtering
capabilities.
* X Window workstation: DragonFly is a fine choice for an
inexpensive X terminal solution, either using the freely
available XFree86 or X.org servers or one of the excellent
commercial servers provided by Xi Graphics. Unlike an X
terminal, DragonFly allows many applications to be run locally
if desired, thus relieving the burden on a central server.
DragonFly can even boot ``diskless'', making individual
workstations even cheaper and easier to administer.
* Software Development: The basic DragonFly system comes with a
full complement of development tools including the renowned
GNU C/C++ compiler and debugger.
DragonFly is available via anonymous FTP or CVS. Please see
Appendix A for more information about obtaining DragonFly.
--------------------------------------------------------------
1.3 About the DragonFly Project
The following section provides some background information on the
project, including a brief history, project goals, and the
development model of the project.
--------------------------------------------------------------
1.3.1 A Brief History of DragonFly
Matthew Dillon, one of the developers for FreeBSD, was growing
increasingly frustrated with the FreeBSD Project's direction for
release 5. The FreeBSD 5 release had been delayed multiple times,
and had performance problems compared to earlier releases of
FreeBSD.
DragonFly was announced in June of 2003. The code base was taken
from the 4.8 release of FreeBSD, which offered better performance
and more complete features.
Development has proceeded at a very quick rate since then, with
Matt Dillon and a small group of developers fixing longstanding
BSD bugs and modernizing the new DragonFly system.
--------------------------------------------------------------
1.3.2 DragonFly Project Goals
DragonFly is an effort to maintain the traditional BSD format --
lean, stable code -- along with modern features such as
lightweight threads, a workable packaging system, and a revised
VFS. Underpinning all this work is efficient support for multiple
processors, something rare among open source systems. Because
DragonFly is built on an existing very stable code base, it is
possible to make these radical changes as part of an incremental
process.
--------------------------------------------------------------
1.3.3 The DragonFly Development Model
Written by Justin Sherrill.
DragonFly is developed by many people around the world. There is
no qualification process; anyone may submit his or her code,
documentation, or designs, for use in the Project. Here is a
general description of the Project's organizational structure.
The CVS repository
Source for DragonFly is kept in CVS (Concurrent Versions
System), which is available with each DragonFly install.
The primary CVS repository resides on a machine in
California, USA. Documentation on obtaining the DragonFly
source is available elsewhere in this book.
Commit access
The best way of getting changes made to the DragonFly
source is to mail the submit mailing list. Including
desired source code changes (unified diff format is best)
is the most useful format. A certain number of developers
have access to commit changes to the DragonFly source, and
can do so after review on that list.
The DragonFly development model is loose; changes to the code are
generally peer-reviewed and added when any objections have been
corrected. There is no formal entry/rejection process, though
final say on all code submissions goes to Matt Dillon, as
originator of this project.
--------------------------------------------------------------
1.3.4 The Current DragonFly Release
DragonFly is a freely available, full source 4.4BSD-Lite based
release for Intel i386(TM), i486(TM), Pentium(R), Pentium Pro,
Celeron(R), Pentium II, Pentium III, Pentium 4 (or compatible),
and Xeon(TM) based computer systems. It is based primarily on
FreeBSD 4.8, and includes enhancements from U.C. Berkeley's CSRG
group, NetBSD, OpenBSD, 386BSD, and the Free Software Foundation.
A number of additional documents which you may find very helpful
in the process of installing and using DragonFly may now also be
found in the /usr/share/doc directory on any machine.
The most up-to-date documentation can be found at
http://www.dragonflybsd.org/.
--------------------------------------------------------------
1.3.5 "DragonFly" Origin
Matthew Dillon happened to take a picture of a dragonfly in his
garden while trying to come up with a name for this new branch of
BSD. Taking this as inspiration, "DragonFly" became the new name.
--------------------------------------------------------------
Chapter 2 Installation from CD
Written by Markus Schatzl and Justin Sherrill.
2.1 CD Installation Overview
This document describes the installation of DragonFly BSD on a
plain i386 machine. This process uses a bootable DragonFly CD,
usually referred to as a 'live CD'.
This CD is available at one of the current mirrors, which
distribute the images by various protocols. The authorative list
can be found at the DragonFly website.
This document may be superseded by the /README file located on the
live CD, which may reflect changes made after this document was
last updated. Check that README for any last-minute changes and
for an abbreviated version of this installation process.
The DragonFly development team is working on an automatic
installation tool, which simplifies the partitioning and
installation processes. Until this tool is in place, the manual
process here is required. Some experience with BSD-style tools is
recommended.
Caution: While this guide covers installing to a computer with
an existing non-DragonFly operating system, take no chances!
Back up any data on your disk drives that you want to save.
When installing to an old machine, it may not be possible to boot
from a CD. Use a bootmanager on a floppy in those cases, such as
Smart Bootmanager.
Caution: Always be sure of the target disk for any command.
Unless otherwise specified, each command here assumes the first
disk in the IDE chain is the target. (ad0) Adjust commands as
needed.
--------------------------------------------------------------
2.2 CD Installation - Making room
2.2.1 DragonFly as the only operating system
If DragonFly is to be the only operating system on the target
computer, preparing the disk is a short and simple process. Boot
with the live CD, and log in as root to reach a command prompt.
First, the master boot record (MBR) must be cleared of any old
information. This command clears all old data off your disk by
writing zeros (if=/dev/zero) onto the system's master ata drive
(of=/dev/ad0).
# dd if=/dev/zero of=/dev/ad0 bs=32k count=16
The now-empty disk must be formatted.
Important: This will destroy any existing data on a disk. Do
this only if you plan to dedicate this disk to DragonFly.
# fdisk -I ad0
# fdisk -B ad0
--------------------------------------------------------------
2.2.2 Multiple operating systems on one hard disk
This example assumes that the target computer for installation has
at least one operating system installed that needs to survive the
installation process. A new partition for DragonFly needs to be
created from the existing partition(s) that otherwise fill the
disk. There must be unused space within the existing partition in
order to resize it.
Important: The new partition is created from empty space in an
existing partition. For example, an 18 gigabyte disk that has 17
gigabytes of existing data in the existing partition will only
have 1 gigabyte available for the new partition.
Partition resizing needs to be accomplished with a third-party
tool. Commercial programs such as Partition Magic can accomplish
these tasks. Free tools exist that can be adapted to this task,
such as 'GNU parted', found on the Knoppix CD, or PAUD.
Create a new partition of at least 5-6 gigabytes. It is possible
to install within a smaller amount of disk space, but this will
create problems not covered by this document. The newly created
partition does not need to be formatted; the rest of the
installation process treats that new partiton as a new disk.
--------------------------------------------------------------
2.2.3 Multiple operating systems, multiple hard disks
Installing DragonFly to a separate disk removes the need for
partition resizing, and is generally safer when trying to preserve
an existing operating system installation.
This type of installation is very similar to installing DragonFly
as the only operating system. The only difference is the disk
named in each command.
--------------------------------------------------------------
2.3 CD Installation - Disk setup
2.3.1 Disk formatting
The slice layout on the newly formatted disk or partition needs to
be set up, using this command.
# fdisk -u
If there are multiple operating systems on the disk, pick the
correct partition judging by what partitions were created earlier
with a resizing tool.
--------------------------------------------------------------
2.3.2 Boot block installation
The 'ad0' here refers to the first disk on the first IDE bus of a
computer. Increment the number if the target disk is farther down
the chain. For example, the master disk on the second IDE
controller would be 'ad2'.
# boot0cfg -B ad0
# boot0cfg -v ad0
-s SLICE, where SLICE is a number, controls which slice on disk is
used by boot0cfg to start from. By default, this number is 1, and
will only need modification if a different slice contains
DragonFly.
Use -o packet as an option to boot0cfg if the DragonFly partition
is located beyond cylinder 1023 on the disk. This location problem
usually only happens when another operating system is taking up
more than the first 8 gigabytes of disk space. This problem cannot
happen if DragonFly is installed to a dedicated disk
--------------------------------------------------------------
2.3.3 Disklabel
If DragonFly is installed anywhere but the first partition of the
disk, the device entry for that partition will have to be created.
Otherwise, the device entry is automatically created. Refer to
this different partition instead of the 'ad0s1a' used in later
examples.
# cd /dev; ./MAKEDEV ad0s2
The partition needs to be created on the DragonFly disk.
# disklabel -B -r -w ad0s1 auto
Using /etc/disklabel.ad0s1 as an example, issue the following
command to edit the disklabel for the just-created partition.
# disklabel -e ad0s1
+----------------------------------------------------------------+
| Partition | Size | Mountpoint |
|-----------+-------------+--------------------------------------|
| ad0s2a | 256m | / |
|-----------+-------------+--------------------------------------|
| ad0s2b | 1024m | swap |
|-----------+-------------+--------------------------------------|
| ad0s2c | leave alone | This represents the whole slice. |
|-----------+-------------+--------------------------------------|
| ad0s2d | 256m | /var |
|-----------+-------------+--------------------------------------|
| ad0s2e | 256m | /tmp ! |
|-----------+-------------+--------------------------------------|
| ad0s2f | 8192m | /usr - This should be at least 4096m |
|-----------+-------------+--------------------------------------|
| ad0s2g | * | /home - This holds 'everything else' |
+----------------------------------------------------------------+
--------------------------------------------------------------
2.3.4 Partition Format
newfs will format each individual partition.
# newfs /dev/ad0s1a
# newfs -U /dev/ad0s1d
# newfs -U /dev/ad0s1e
# newfs -U /dev/ad0s1f
# newfs -U /dev/ad0s1g
Note: The -U option is not used for the root partition, since /
is usually relatively small. Softupdates can cause it to run out
of space while under a lot of disk activity, such as a
buildworld.
Note: The command listing skips directly from ad0s1a to ad0s1d.
This is because /dev/ad0s1b is used as swap and does not require
formatting; ad0s1c refers to the entire disk and should not be
formatted.
--------------------------------------------------------------
2.4 Installing to Disk from CD
Since the Live CD contains all needed data to create a running
DragonFly system, the simplest installation possible is to copy
the Live CD data to the newly formatted disk/partition created in
previous steps.
These commands mount the newly created disk space and create the
appropriate directories on it.
# mount /dev/ad0s1a /mnt
# mkdir /mnt/var
# mkdir /mnt/tmp
# mkdir /mnt/usr
# mkdir /mnt/home
# mount /dev/ad0s1d /mnt/var
# mount /dev/ad0s1e /mnt/tmp
# mount /dev/ad0s1f /mnt/usr
# mount /dev/ad0s1g /mnt/home
cpdup duplicates data from one volume to another. These commands
copy data from the Live CD to the newly created directories on the
mounted disk. Each step can take some time, depending on disk
speed.
# cpdup / /mnt
# cpdup /var /mnt/var
# cpdup /etc /mnt/etc
# cpdup /dev /mnt/dev
# cpdup /usr /mnt/usr
Note: Nothing is copied to the /tmp directory that was created
in the previous step. This is not an error, since /tmp is
intended only for temporary storage.
--------------------------------------------------------------
2.5 CD Installation - Post-install cleanup
/tmp and /var/tmp are both often used as temporary directories.
Since use is not consistent from application to application, it is
worthwhile to create /tmp as a link to /var/tmp so space is not
wasted in duplication.
# chmod 1777 /mnt/tmp
# rm -fr /mnt/var/tmp
# ln -s /tmp /mnt/var/tmp
Note: /tmp will not work until the computer is rebooted.
The file /etc/fstab describes the disk partition layout. However,
the version copied to the target disk only reflects the Live CD
layout. The installed /mnt/fstab.example can be used as a starting
point for creating a new /etc/fstab.
# vi /mnt/etc/fstab.example
# mv /mnt/etc/fstab.example /mnt/etc/fstab
A corrupted disklabel will render a disk useless. While this is
thankfully very rare, having a backup of the new install's
disklabel may stave off disaster at some point in the future. This
is optional. (Adjust the slice name to reflect the actual
installation.)
# disklabel ad0s1 > /mnt/etc/disklabel.backup
Note: Nothing is copied to the /tmp directory that was created
in the previous step. This is not an error, since /tmp is
intended only for temporary storage.
Remove some unnecessary files copied over from the Live CD.
# rm /mnt/boot/loader.conf
# rm /mnt/boot.catalog
# rm -r /mnt/rr_moved
The system can now be rebooted. Be sure to remove the Live CD from
the CDROM drive so that the computer can boot from the
newly-installed disk.
# reboot
Note: Use the reboot command so that the disk can be unmounted
cleanly. Hitting the power or reset buttons, while it won't hurt
the Live CD, can leave the mounted disk in a inconsistent state.
If the system refuses to boot, there are several options to try:
* Old bootblocks can interfere with the initialization-process.
To avoid this, zero-out the MBR. "of" should be changed to the
correct disk entry if ad0 is not the targeted installation
disk.
# dd if=/dev/zero of=/dev/ad0 bs=32 count=16
* It is possible that the DragonFly slice is beyond cylinder
1023 on the hard disk, and can't be detected. Packet mode can
fix this problem.
# boot0cfg -o packet ad0
* If you can select CHS or LBA mode in your BIOS, try changing
the mode to LBA.
After a successful boot from the newly installed hard drive, the
timezone should be set. Use the command tzsetup to set the
appropriate time zone.
# tzsetup
--------------------------------------------------------------
2.6 CD Installation - New system setup
Once the new DragonFly system is booting from disk, there are a
number of steps that may be useful before working further. The
file /etc/rc.conf controls a number of options for booting the
system.
--------------------------------------------------------------
2.6.1 Setting up rc.conf
Depending on location, a different keyboard map may be needed.
This is only necessary for computers outside of North America.
# kbdmap
Pick the appropriate keyboard map and remember the name. Place
this name in /etc/rc.conf. For example:
keymap="german.iso.kbd"
The file /etc/rc.conf matches the one on the Live CD. Since it is
now on an installed system are no longer running in a read-only
environment, some changes should be made. Changes to this file
will take effect after the next boot of the machine.
These lines can be removed.
syslogd_enable="NO"
xntpd_enable="NO"
cron_enable="NO"
For a system which uses USB, this line will need to be modified to
a value of "YES":
usbd_enable="NO"
inetd controls various small servers like telnet or ftp. By
default, all servers are off, and must be individually uncommented
in /etc/inetd.conf to start them. This is optional.
inetd_enable="YES" # Run the network daemon dispatcher (YES/NO).
inetd_program="/usr/sbin/inetd" # path to inetd, if you want a different one.
inetd_flags="-wW" # Optional flags to inetd
--------------------------------------------------------------
2.6.2 Network Setup
For acquiring an IP address through DHCP, place this entry in
/etc/rc.conf, using the appropriate card name. (ep0 is used as an
example here.)
ifconfig_ep0="DHCP"
For a fixed IP, /etc/rc.conf requires a few more lines of data.
(Again, ep0 is used as an example here.) Supply the correct local
values for IP, netmask, and default router. The hostname should
reflect what is entered in DNS for this computer.
ifconfig_ep0="inet 123.234.345.456 netmask 255.255.255.0"
hostname="myhostname"
defaultrouter="654.543.432.321"
--------------------------------------------------------------
Chapter 3 UNIX Basics
Rewritten by Chris Shumway.
3.1 Synopsis
The following chapter will cover the basic commands and
functionality of the DragonFly operating system. Much of this
material is relevant for any UNIX-like operating system. Feel free
to skim over this chapter if you are familiar with the material.
If you are new to DragonFly, then you will definitely want to read
through this chapter carefully.
After reading this chapter, you will know:
* How to use the ``virtual consoles'' of DragonFly.
* How UNIX file permissions work along with understanding file
flags in DragonFly.
* The default DragonFly file system layout.
* The DragonFly disk organization.
* How to mount and unmount file systems.
* What processes, daemons, and signals are.
* What a shell is, and how to change your default login
environment.
* How to use basic text editors.
* What devices and device nodes are.
* What binary format is used under DragonFly.
* How to read manual pages for more information.
--------------------------------------------------------------
3.2 Virtual Consoles and Terminals
DragonFly can be used in various ways. One of them is typing
commands to a text terminal. A lot of the flexibility and power of
a UNIX operating system is readily available at your hands when
using DragonFly this way. This section describes what
``terminals'' and ``consoles'' are, and how you can use them in
DragonFly.
--------------------------------------------------------------
3.2.1 The Console
If you have not configured DragonFly to automatically start a
graphical environment during startup, the system will present you
with a login prompt after it boots, right after the startup
scripts finish running. You will see something similar to:
Additional ABI support:.
Local package initialization:.
Additional TCP options:.
Fri Sep 20 13:01:06 EEST 2002
DragonFlyBSD/i386 (pc3.example.org) (ttyv0)
login:
The messages might be a bit different on your system, but you will
see something similar. The last two lines are what we are
interested in right now. The second last line reads:
DragonFlyBSD/i386 (pc3.example.org) (ttyv0)
This line contains some bits of information about the system you
have just booted. You are looking at a ``DragonFlyBSD'' console,
running on an Intel or compatible processor of the x86
architecture[1]. The name of this machine (every UNIX machine has
a name) is pc3.example.org, and you are now looking at its system
console--the ttyv0 terminal.
Finally, the last line is always:
login:
This is the part where you are supposed to type in your
``username'' to log into DragonFly. The next section describes how
you can do this.
--------------------------------------------------------------
3.2.2 Logging into DragonFly
DragonFly is a multiuser, multiprocessing system. This is the
formal description that is usually given to a system that can be
used by many different people, who simultaneously run a lot of
programs on a single machine.
Every multiuser system needs some way to distinguish one ``user''
from the rest. In DragonFly (and all the UNIX-like operating
systems), this is accomplished by requiring that every user must
``log into'' the system before being able to run programs. Every
user has a unique name (the ``username'') and a personal, secret
key (the ``password''). DragonFly will ask for these two before
allowing a user to run any programs.
Right after DragonFly boots and finishes running its startup
scripts[2], it will present you with a prompt and ask for a valid
username:
login:
For the sake of this example, let us assume that your username is
john. Type john at this prompt and press Enter. You should then be
presented with a prompt to enter a ``password'':
login: john
Password:
Type in john's password now, and press Enter. The password is not
echoed! You need not worry about this right now. Suffice it to say
that it is done for security reasons.
If you have typed your password correctly, you should by now be
logged into DragonFly and ready to try out all the available
commands.
You should see the MOTD or message of the day followed by a
command prompt (a #, $, or % character). This indicates you have
successfully logged into DragonFly.
--------------------------------------------------------------
3.2.3 Multiple Consoles
Running UNIX commands in one console is fine, but DragonFly can
run many programs at once. Having one console where commands can
be typed would be a bit of a waste when an operating system like
DragonFly can run dozens of programs at the same time. This is
where ``virtual consoles'' can be very helpful.
DragonFly can be configured to present you with many different
virtual consoles. You can switch from one of them to any other
virtual console by pressing a couple of keys on your keyboard.
Each console has its own different output channel, and DragonFly
takes care of properly redirecting keyboard input and monitor
output as you switch from one virtual console to the next.
Special key combinations have been reserved by DragonFly for
switching consoles[3]. You can use Alt-F1, Alt-F2, through Alt-F8
to switch to a different virtual console in DragonFly.
As you are switching from one console to the next, DragonFly takes
care of saving and restoring the screen output. The result is an
``illusion'' of having multiple ``virtual'' screens and keyboards
that you can use to type commands for DragonFly to run. The
programs that you launch on one virtual console do not stop
running when that console is not visible. They continue running
when you have switched to a different virtual console.
--------------------------------------------------------------
3.2.4 The /etc/ttys File
The default configuration of DragonFly will start up with eight
virtual consoles. This is not a hardwired setting though, and you
can easily customize your installation to boot with more or fewer
virtual consoles. The number and settings of the virtual consoles
are configured in the /etc/ttys file.
You can use the /etc/ttys file to configure the virtual consoles
of DragonFly. Each uncommented line in this file (lines that do
not start with a # character) contains settings for a single
terminal or virtual console. The default version of this file that
ships with DragonFly configures nine virtual consoles, and enables
eight of them. They are the lines that start with ttyv:
# name getty type status comments
#
ttyv0 "/usr/libexec/getty Pc" cons25 on secure
# Virtual terminals
ttyv1 "/usr/libexec/getty Pc" cons25 on secure
ttyv2 "/usr/libexec/getty Pc" cons25 on secure
ttyv3 "/usr/libexec/getty Pc" cons25 on secure
ttyv4 "/usr/libexec/getty Pc" cons25 on secure
ttyv5 "/usr/libexec/getty Pc" cons25 on secure
ttyv6 "/usr/libexec/getty Pc" cons25 on secure
ttyv7 "/usr/libexec/getty Pc" cons25 on secure
ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
For a detailed description of every column in this file and all
the options you can use to set things up for the virtual consoles,
consult the ttys(5) manual page.
--------------------------------------------------------------
3.2.5 Single User Mode Console
A detailed description of what ``single user mode'' is can be
found in Section 7.5.2. It is worth noting that there is only one
console when you are running DragonFly in single user mode. There
are no virtual consoles available. The settings of the single user
mode console can also be found in the /etc/ttys file. Look for the
line that starts with console:
# name getty type status comments
#
# If console is marked "insecure", then init will ask for the root password
# when going to single-user mode.
console none unknown off secure
Note: As the comments above the console line indicate, you can
edit this line and change secure to insecure. If you do that,
when DragonFly boots into single user mode, it will still ask
for the root password.
Be careful when changing this to insecure. If you ever forget
the root password, booting into single user mode is a bit
involved. It is still possible, but it might be a bit hard for
someone who is not very comfortable with the DragonFly booting
process and the programs involved.
--------------------------------------------------------------
3.3 Permissions
DragonFly, being a direct descendant of BSD UNIX, is based on
several key UNIX concepts. The first and most pronounced is that
DragonFly is a multi-user operating system. The system can handle
several users all working simultaneously on completely unrelated
tasks. The system is responsible for properly sharing and managing
requests for hardware devices, peripherals, memory, and CPU time
fairly to each user.
Because the system is capable of supporting multiple users,
everything the system manages has a set of permissions governing
who can read, write, and execute the resource. These permissions
are stored as three octets broken into three pieces, one for the
owner of the file, one for the group that the file belongs to, and
one for everyone else. This numerical representation works like
this:
Value Permission Directory Listing
0 No read, no write, no execute ---
1 No read, no write, execute --x
2 No read, write, no execute -w-
3 No read, write, execute -wx
4 Read, no write, no execute r--
5 Read, no write, execute r-x
6 Read, write, no execute rw-
7 Read, write, execute rwx
You can use the -l command line argument to ls(1) to view a long
directory listing that includes a column with information about a
file's permissions for the owner, group, and everyone else. For
example, a ls -l in an arbitrary directory may show:
% ls -l
total 530
-rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
-rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
-rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt
...
Here is how the first column of ls -l is broken up:
-rw-r--r--
The first (leftmost) character tells if this file is a regular
file, a directory, a special character device, a socket, or any
other special pseudo-file device. In this case, the - indicates a
regular file. The next three characters, rw- in this example, give
the permissions for the owner of the file. The next three
characters, r--, give the permissions for the group that the file
belongs to. The final three characters, r--, give the permissions
for the rest of the world. A dash means that the permission is
turned off. In the case of this file, the permissions are set so
the owner can read and write to the file, the group can read the
file, and the rest of the world can only read the file. According
to the table above, the permissions for this file would be 644,
where each digit represents the three parts of the file's
permission.
This is all well and good, but how does the system control
permissions on devices? DragonFly actually treats most hardware
devices as a file that programs can open, read, and write data to
just like any other file. These special device files are stored on
the /dev directory.
Directories are also treated as files. They have read, write, and
execute permissions. The executable bit for a directory has a
slightly different meaning than that of files. When a directory is
marked executable, it means it can be traversed into, that is, it
is possible to ``cd'' (change directory) into it. This also means
that within the directory it is possible to access files whose
names are known (subject, of course, to the permissions on the
files themselves).
In particular, in order to perform a directory listing, read
permission must be set on the directory, whilst to delete a file
that one knows the name of, it is necessary to have write and
execute permissions to the directory containing the file.
There are more permission bits, but they are primarily used in
special circumstances such as setuid binaries and sticky
directories. If you want more information on file permissions and
how to set them, be sure to look at the chmod(1) manual page.
--------------------------------------------------------------
3.3.1 Symbolic Permissions
Contributed by Tom Rhodes.
Symbolic permissions, sometimes referred to as symbolic
expressions, use characters in place of octal values to assign
permissions to files or directories. Symbolic expressions use the
syntax of (who) (action) (permissions), where the following values
are available:
Option Letter Represents
(who) u User
(who) g Group owner
(who) o Other
(who) a All (``world'')
(action) + Adding permissions
(action) - Removing permissions
(action) = Explicitly set permissions
(permissions) r Read
(permissions) w Write
(permissions) x Execute
(permissions) t Sticky bit
(permissions) s Set UID or GID
These values are used with the chmod(1) command just like before,
but with letters. For an example, you could use the following
command to block other users from accessing FILE:
% chmod go= FILE
A comma separated list can be provided when more than one set of
changes to a file must be made. For example the following command
will remove the groups and ``world'' write permission on FILE,
then it adds the execute permissions for everyone:
% chmod go-w,a+x FILE
--------------------------------------------------------------
3.3.2 DragonFly File Flags
Contributed by Tom Rhodes.
In addition to file permissions discussed previously, DragonFly
supports the use of ``file flags.'' These flags add an additional
level of security and control over files, but not directories.
These file flags add an additional level of control over files,
helping to ensure that in some cases not even the root can remove
or alter files.
File flags are altered by using the chflags(1) utility, using a
simple interface. For example, to enable the system undeletable
flag on the file file1, issue the following command:
# chflags sunlink
file1
And to disable the system undeletable flag, simply issue the
previous command with ``no'' in front of the sunlink. Observe:
# chflags nosunlink
file1
To view the flags of this file, use the ls(1) with the -lo flags:
# ls -lo file1
The output should look like the following:
-rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54
file1
Several flags may only added or removed to files by the root user.
In other cases, the file owner may set these flags. It is
recommended an administrator read over the chflags(1) and
chflags(2) manual pages for more information.
--------------------------------------------------------------
3.4 Directory Structure
The DragonFly directory hierarchy is fundamental to obtaining an
overall understanding of the system. The most important concept to
grasp is that of the root directory, ``/''. This directory is the
first one mounted at boot time and it contains the base system
necessary to prepare the operating system for multi-user
operation. The root directory also contains mount points for every
other file system that you may want to mount.
A mount point is a directory where additional file systems can be
grafted onto the root file system. This is further described in
Section 3.5. Standard mount points include /usr, /var, /tmp, /mnt,
and /cdrom. These directories are usually referenced to entries in
the file /etc/fstab. /etc/fstab is a table of various file systems
and mount points for reference by the system. Most of the file
systems in /etc/fstab are mounted automatically at boot time from
the script rc(8) unless they contain the noauto option. Details
can be found in Section 3.6.1.
A complete description of the file system hierarchy is available
in hier(7). For now, a brief overview of the most common
directories will suffice.
Directory Description
/ Root directory of the file system.
/bin/ User utilities fundamental to both single-user and
multi-user environments.
/boot/ Programs and configuration files used during
operating system bootstrap.
/boot/defaults/ Default bootstrapping configuration files; see
loader.conf(5).
/dev/ Device nodes; see intro(4).
/etc/ System configuration files and scripts.
/etc/defaults/ Default system configuration files; see rc(8).
/etc/mail/ Configuration files for mail transport agents such
as sendmail(8).
/etc/namedb/ named configuration files; see named(8).
/etc/periodic/ Scripts that are run daily, weekly, and monthly,
via cron(8); see periodic(8).
/etc/ppp/ ppp configuration files; see ppp(8).
/mnt/ Empty directory commonly used by system
administrators as a temporary mount point.
/proc/ Process file system; see procfs(5),
mount_procfs(8).
/root/ Home directory for the root account.
System programs and administration utilities
/sbin/ fundamental to both single-user and multi-user
environments.
Temporary files. The contents of /tmp are usually
NOT preserved across a system reboot. A
/tmp/ memory-based file system is often mounted at /tmp.
This can be automated with an entry in /etc/fstab;
see mfs(8).
/usr/ The majority of user utilities and applications.
/usr/bin/ Common utilities, programming tools, and
applications.
/usr/include/ Standard C include files.
/usr/lib/ Archive libraries.
/usr/libdata/ Miscellaneous utility data files.
/usr/libexec/ System daemons & system utilities (executed by
other programs).
Local executables, libraries, etc. Within
/usr/local, the general layout sketched out by
/usr/local/ hier(7) for /usr should be used. An exceptions is
the man directory, which is directly under
/usr/local rather than under /usr/local/share.
/usr/obj/ Architecture-specific target tree produced by
building the /usr/src tree.
Used as the default destination for the files
/usr/pkg installed via the pkgsrc tree or pkgsrc packages
(optional). The configuration directory is
tunable, but the default location is /usr/pkg/etc.
/usr/pkg/xorg/ X11R6 distribution executables, libraries, etc
(optional).
/usr/pkgsrc The pkgsrc tree for installing packages
(optional).
/usr/sbin/ System daemons & system utilities (executed by
users).
/usr/share/ Architecture-independent files.
/usr/src/ BSD and/or local source files.
Multi-purpose log, temporary, transient, and spool
/var/ files. A memory-based file system is sometimes
mounted at /var. This can be automated with an
entry in /etc/fstab; see mfs(8).
/var/log/ Miscellaneous system log files.
/var/mail/ User mailbox files.
/var/spool/ Miscellaneous printer and mail system spooling
directories.
Temporary files. The files are usually preserved
/var/tmp/ across a system reboot, unless /var is a
memory-based file system.
/var/yp NIS maps.
--------------------------------------------------------------
3.5 Disk Organization
The smallest unit of organization that DragonFly uses to find
files is the filename. Filenames are case-sensitive, which means
that readme.txt and README.TXT are two separate files. DragonFly
does not use the extension (.txt) of a file to determine whether
the file is a program, or a document, or some other form of data.
Files are stored in directories. A directory may contain no files,
or it may contain many hundreds of files. A directory can also
contain other directories, allowing you to build up a hierarchy of
directories within one another. This makes it much easier to
organize your data.
Files and directories are referenced by giving the file or
directory name, followed by a forward slash, /, followed by any
other directory names that are necessary. If you have directory
foo, which contains directory bar, which contains the file
readme.txt, then the full name, or path to the file is
foo/bar/readme.txt.
Directories and files are stored in a file system. Each file
system contains exactly one directory at the very top level,
called the root directory for that file system. This root
directory can then contain other directories.
So far this is probably similar to any other operating system you
may have used. There are a few differences; for example, MS-DOS
uses \ to separate file and directory names, while Mac OS(R) uses
:.
DragonFly does not use drive letters, or other drive names in the
path. You would not write c:/foo/bar/readme.txt on DragonFly.
Instead, one file system is designated the root file system. The
root file system's root directory is referred to as /. Every other
file system is then mounted under the root file system. No matter
how many disks you have on your DragonFly system, every directory
appears to be part of the same disk.
Suppose you have three file systems, called A, B, and C. Each file
system has one root directory, which contains two other
directories, called A1, A2 (and likewise B1, B2 and C1, C2).
Call A the root file system. If you used the ls command to view
the contents of this directory you would see two subdirectories,
A1 and A2. The directory tree looks like this:
/
|
+--- A1
|
`--- A2
A file system must be mounted on to a directory in another file
system. So now suppose that you mount file system B on to the
directory A1. The root directory of B replaces A1, and the
directories in B appear accordingly:
/
|
+--- A1
| |
| +--- B1
| |
| `--- B2
|
`--- A2
Any files that are in the B1 or B2 directories can be reached with
the path /A1/B1 or /A1/B2 as necessary. Any files that were in /A1
have been temporarily hidden. They will reappear if B is unmounted
from A.
If B had been mounted on A2 then the diagram would look like this:
/
|
+--- A1
|
`--- A2
|
+--- B1
|
`--- B2
and the paths would be /A2/B1 and /A2/B2 respectively.
File systems can be mounted on top of one another. Continuing the
last example, the C file system could be mounted on top of the B1
directory in the B file system, leading to this arrangement:
/
|
+--- A1
|
`--- A2
|
+--- B1
| |
| +--- C1
| |
| `--- C2
|
`--- B2
Or C could be mounted directly on to the A file system, under the
A1 directory:
/
|
+--- A1
| |
| +--- C1
| |
| `--- C2
|
`--- A2
|
+--- B1
|
`--- B2
If you are familiar with MS-DOS, this is similar, although not
identical, to the join command.
This is not normally something you need to concern yourself with.
Typically you create file systems when installing DragonFly and
decide where to mount them, and then never change them unless you
add a new disk.
It is entirely possible to have one large root file system, and
not need to create any others. There are some drawbacks to this
approach, and one advantage.
Benefits of Multiple File Systems
* Different file systems can have different mount options. For
example, with careful planning, the root file system can be
mounted read-only, making it impossible for you to
inadvertently delete or edit a critical file. Separating
user-writable file systems, such as /home, from other file
systems also allows them to be mounted nosuid; this option
prevents the suid/guid bits on executables stored on the file
system from taking effect, possibly improving security.
* DragonFly automatically optimizes the layout of files on a
file system, depending on how the file system is being used.
So a file system that contains many small files that are
written frequently will have a different optimization to one
that contains fewer, larger files. By having one big file
system this optimization breaks down.
* DragonFly's file systems are very robust should you lose
power. However, a power loss at a critical point could still
damage the structure of the file system. By splitting your
data over multiple file systems it is more likely that the
system will still come up, making it easier for you to restore
from backup as necessary.
Benefit of a Single File System
* File systems are a fixed size. If you create a file system
when you install DragonFly and give it a specific size, you
may later discover that you need to make the partition bigger.
The growfs(8) command makes it possible to increase the size
of a file system on the fly.
File systems are contained in partitions. This does not have the
same meaning as the common usage of the term partition (for
example, MS-DOS partition), because of DragonFly's UNIX heritage.
Each partition is identified by a letter from a through to h. Each
partition can contain only one file system, which means that file
systems are often described by either their typical mount point in
the file system hierarchy, or the letter of the partition they are
contained in.
DragonFly also uses disk space for swap space. Swap space provides
DragonFly with virtual memory. This allows your computer to behave
as though it has much more memory than it actually does. When
DragonFly runs out of memory it moves some of the data that is not
currently being used to the swap space, and moves it back in
(moving something else out) when it needs it.
Some partitions have certain conventions associated with them.
Partition Convention
a Normally contains the root file system
b Normally contains swap space
Normally the same size as the enclosing slice. This
allows utilities that need to work on the entire slice
c (for example, a bad block scanner) to work on the c
partition. You would not normally create a file system
on this partition.
Partition d used to have a special meaning associated
d with it, although that is now gone. To this day, some
tools may operate oddly if told to work on partition d.
Each partition-that-contains-a-file-system is stored in what
DragonFly calls a slice. Slice is DragonFly's term for what the
common call partitions, and again, this is because of DragonFly's
UNIX background. Slices are numbered, starting at 1, through to 4.
Slice numbers follow the device name, prefixed with an s, starting
at 1. So ``da0s1'' is the first slice on the first SCSI drive.
There can only be four physical slices on a disk, but you can have
logical slices inside physical slices of the appropriate type.
These extended slices are numbered starting at 5, so ``ad0s5'' is
the first extended slice on the first IDE disk. These devices are
used by file systems that expect to occupy a slice.
Slices, ``dangerously dedicated'' physical drives, and other
drives contain partitions, which are represented as letters from a
to h. This letter is appended to the device name, so ``da0a'' is
the a partition on the first da drive, which is ``dangerously
dedicated''. ``ad1s3e'' is the fifth partition in the third slice
of the second IDE disk drive.
Finally, each disk on the system is identified. A disk name starts
with a code that indicates the type of disk, and then a number,
indicating which disk it is. Unlike slices, disk numbering starts
at 0. Common codes that you will see are listed in Table 3-1.
When referring to a partition DragonFly requires that you also
name the slice and disk that contains the partition, and when
referring to a slice you should also refer to the disk name. Do
this by listing the disk name, s, the slice number, and then the
partition letter. Examples are shown in Example 3-1.
Example 3-2 shows a conceptual model of the disk layout that
should help make things clearer.
In order to install DragonFly you must first configure the disk
slices, then create partitions within the slice you will use for
DragonFly, and then create a file system (or swap space) in each
partition, and decide where that file system will be mounted.
Table 3-1. Disk Device Codes
Code Meaning
ad ATAPI (IDE) disk
da SCSI direct access disk
acd ATAPI (IDE) CDROM
cd SCSI CDROM
fd Floppy disk
Example 3-1. Sample Disk, Slice, and Partition Names
Name Meaning
ad0s1a The first partition (a) on the first slice (s1) on the
first IDE disk (ad0).
da1s2e The fifth partition (e) on the second slice (s2) on the
second SCSI disk (da1).
Example 3-2. Conceptual Model of a Disk
This diagram shows DragonFly's view of the first IDE disk attached
to the system. Assume that the disk is 4 GB in size, and contains
two 2 GB slices (MS-DOS partitions). The first slice contains a
MS-DOS disk, C:, and the second slice contains a DragonFly
installation. This example DragonFly installation has three
partitions, and a swap partition.
The three partitions will each hold a file system. Partition a
will be used for the root file system, e for the /var directory
hierarchy, and f for the /usr directory hierarchy.
.-----------------. --.
| | |
| DOS / Windows | |
: : > First slice, ad0s1
: : |
| | |
:=================: ==: --.
| | | Partition a, mounted as / |
| | > referred to as ad0s2a |
| | | |
:-----------------: ==: |
| | | Partition b, used as swap |
| | > referred to as ad0s2b |
| | | |
:-----------------: ==: | Partition c, no
| | | Partition e, used as /var > file system, all
| | > referred to as ad0s2e | of DragonFly slice,
| | | | ad0s2c
:-----------------: ==: |
| | | |
: : | Partition f, used as /usr |
: : > referred to as ad0s2f |
: : | |
| | | |
| | --' |
`-----------------' --'
--------------------------------------------------------------
3.6 Mounting and Unmounting File Systems
The file system is best visualized as a tree, rooted, as it were,
at /. /dev, /usr, and the other directories in the root directory
are branches, which may have their own branches, such as
/usr/local, and so on.
There are various reasons to house some of these directories on
separate file systems. /var contains the directories log/, spool/,
and various types of temporary files, and as such, may get filled
up. Filling up the root file system is not a good idea, so
splitting /var from / is often favorable.
Another common reason to contain certain directory trees on other
file systems is if they are to be housed on separate physical
disks, or are separate virtual disks, such as Network File System
mounts, or CDROM drives.
--------------------------------------------------------------
3.6.1 The fstab File
During the boot process, file systems listed in /etc/fstab are
automatically mounted (unless they are listed with the noauto
option).
The /etc/fstab file contains a list of lines of the following
format:
device /mount-point fstype options dumpfreq passno
device
A device name (which should exist), as explained in
Section 12.2.
mount-point
A directory (which should exist), on which to mount the
file system.
fstype
The file system type to pass to mount(8). The default
DragonFly file system is ufs.
options
Either rw for read-write file systems, or ro for read-only
file systems, followed by any other options that may be
needed. A common option is noauto for file systems not
normally mounted during the boot sequence. Other options
are listed in the mount(8) manual page.
dumpfreq
This is used by dump(8) to determine which file systems
require dumping. If the field is missing, a value of zero
is assumed.
passno
This determines the order in which file systems should be
checked. File systems that should be skipped should have
their passno set to zero. The root file system (which
needs to be checked before everything else) should have
its passno set to one, and other file systems' passno
should be set to values greater than one. If more than one
file systems have the same passno then fsck(8) will
attempt to check file systems in parallel if possible.
Consult the fstab(5) manual page for more information on the
format of the /etc/fstab file and the options it contains.
--------------------------------------------------------------
3.6.2 The mount Command
The mount(8) command is what is ultimately used to mount file
systems.
In its most basic form, you use:
# mount device mountpoint
There are plenty of options, as mentioned in the mount(8) manual
page, but the most common are:
Mount Options
-a
Mount all the file systems listed in /etc/fstab. Except
those marked as ``noauto'', excluded by the -t flag, or
those that are already mounted.
-d
Do everything except for the actual mount system call.
This option is useful in conjunction with the -v flag to
determine what mount(8) is actually trying to do.
-f
Force the mount of an unclean file system (dangerous), or
forces the revocation of write access when downgrading a
file system's mount status from read-write to read-only.
-r
Mount the file system read-only. This is identical to
using the rdonly argument to the -o option.
-t fstype
Mount the given file system as the given file system type,
or mount only file systems of the given type, if given the
-a option.
``ufs'' is the default file system type.
-u
Update mount options on the file system.
-v
Be verbose.
-w
Mount the file system read-write.
The -o option takes a comma-separated list of the options,
including the following:
nodev
Do not interpret special devices on the file system. This
is a useful security option.
noexec
Do not allow execution of binaries on this file system.
This is also a useful security option.
nosuid
Do not interpret setuid or setgid flags on the file
system. This is also a useful security option.
--------------------------------------------------------------
3.6.3 The umount Command
The umount(8) command takes, as a parameter, one of a mountpoint,
a device name, or the -a or -A option.
All forms take -f to force unmounting, and -v for verbosity. Be
warned that -f is not generally a good idea. Forcibly unmounting
file systems might crash the computer or damage data on the file
system.
-a and -A are used to unmount all mounted file systems, possibly
modified by the file system types listed after -t. -A, however,
does not attempt to unmount the root file system.
--------------------------------------------------------------
3.7 Processes
DragonFly is a multi-tasking operating system. This means that it
seems as though more than one program is running at once. Each
program running at any one time is called a process. Every command
you run will start at least one new process, and there are a
number of system processes that run all the time, keeping the
system functional.
Each process is uniquely identified by a number called a process
ID, or PID, and, like files, each process also has one owner and
group. The owner and group information is used to determine what
files and devices the process can open, using the file permissions
discussed earlier. Most processes also have a parent process. The
parent process is the process that started them. For example, if
you are typing commands to the shell then the shell is a process,
and any commands you run are also processes. Each process you run
in this way will have your shell as its parent process. The
exception to this is a special process called init(8). init is
always the first process, so its PID is always 1. init is started
automatically by the kernel when DragonFly starts.
Two commands are particularly useful to see the processes on the
system, ps(1) and top(1). The ps command is used to show a static
list of the currently running processes, and can show their PID,
how much memory they are using, the command line they were started
with, and so on. The top command displays all the running
processes, and updates the display every few seconds, so that you
can interactively see what your computer is doing.
By default, ps only shows you the commands that are running and
are owned by you. For example:
% ps
PID TT STAT TIME COMMAND
298 p0 Ss 0:01.10 tcsh
7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
72210 p0 R+ 0:00.00 ps
390 p1 Is 0:01.14 tcsh
7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
6688 p3 IWs 0:00.00 tcsh
10735 p4 IWs 0:00.00 tcsh
20256 p5 IWs 0:00.00 tcsh
262 v0 IWs 0:00.00 -tcsh (tcsh)
270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
285 v0 S 0:38.45 /usr/X11R6/bin/sawfish
As you can see in this example, the output from ps(1) is organized
into a number of columns. PID is the process ID discussed earlier.
PIDs are assigned starting from 1, go up to 99999, and wrap around
back to the beginning when you run out. The TT column shows the
tty the program is running on, and can safely be ignored for the
moment. STAT shows the program's state, and again, can be safely
ignored. TIME is the amount of time the program has been running
on the CPU--this is usually not the elapsed time since you started
the program, as most programs spend a lot of time waiting for
things to happen before they need to spend time on the CPU.
Finally, COMMAND is the command line that was used to run the
program.
ps(1) supports a number of different options to change the
information that is displayed. One of the most useful sets is
auxww. a displays information about all the running processes, not
just your own. u displays the username of the process' owner, as
well as memory usage. x displays information about daemon
processes, and ww causes ps(1) to display the full command line,
rather than truncating it once it gets too long to fit on the
screen.
The output from top(1) is similar. A sample session looks like
this:
% top
last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
47 processes: 1 running, 46 sleeping
CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
...
The output is split into two sections. The header (the first five
lines) shows the PID of the last process to run, the system load
averages (which are a measure of how busy the system is), the
system uptime (time since the last reboot) and the current time.
The other figures in the header relate to how many processes are
running (47 in this case), how much memory and swap space has been
taken up, and how much time the system is spending in different
CPU states.
Below that are a series of columns containing similar information
to the output from ps(1). As before you can see the PID, the
username, the amount of CPU time taken, and the command that was
run. top(1) also defaults to showing you the amount of memory
space taken by the process. This is split into two columns, one
for total size, and one for resident size--total size is how much
memory the application has needed, and the resident size is how
much it is actually using at the moment. In this example you can
see that Netscape(R) has required almost 30 MB of RAM, but is
currently only using 9 MB.
top(1) automatically updates this display every two seconds; this
can be changed with the s option.
--------------------------------------------------------------
3.8 Daemons, Signals, and Killing Processes
When you run an editor it is easy to control the editor, tell it
to load files, and so on. You can do this because the editor
provides facilities to do so, and because the editor is attached
to a terminal. Some programs are not designed to be run with
continuous user input, and so they disconnect from the terminal at
the first opportunity. For example, a web server spends all day
responding to web requests, it normally does not need any input
from you. Programs that transport email from site to site are
another example of this class of application.
We call these programs daemons. Daemons were characters in Greek
mythology; neither good or evil, they were little attendant
spirits that, by and large, did useful things for mankind. Much
like the web servers and mail servers of today do useful things.
This is why the mascot for a number of BSD-based operating systems
has, for a long time, been a cheerful looking daemon with sneakers
and a pitchfork.
There is a convention to name programs that normally run as
daemons with a trailing ``d''. BIND is the Berkeley Internet Name
Daemon (and the actual program that executes is called named), the
Apache web server program is called httpd, the line printer
spooling daemon is lpd and so on. This is a convention, not a hard
and fast rule; for example, the main mail daemon for the Sendmail
application is called sendmail, and not maild, as you might
imagine.
Sometimes you will need to communicate with a daemon process.
These communications are called signals, and you can communicate
with a daemon (or with any other running process) by sending it a
signal. There are a number of different signals that you can
send--some of them have a specific meaning, others are interpreted
by the application, and the application's documentation will tell
you how that application interprets signals. You can only send a
signal to a process that you own. If you send a signal to someone
else's process with kill(1) or kill(2) permission will be denied.
The exception to this is the root user, who can send signals to
everyone's processes.
DragonFly will also send applications signals in some cases. If an
application is badly written, and tries to access memory that it
is not supposed to, DragonFly sends the process the Segmentation
Violation signal (SIGSEGV). If an application has used the
alarm(3) system call to be alerted after a period of time has
elapsed then it will be sent the Alarm signal (SIGALRM), and so
on.
Two signals can be used to stop a process, SIGTERM and SIGKILL.
SIGTERM is the polite way to kill a process; the process can catch
the signal, realize that you want it to shut down, close any log
files it may have open, and generally finish whatever it is doing
at the time before shutting down. In some cases a process may even
ignore SIGTERM if it is in the middle of some task that can not be
interrupted.
SIGKILL can not be ignored by a process. This is the ``I do not
care what you are doing, stop right now'' signal. If you send
SIGKILL to a process then DragonFly will stop that process there
and then[4].
The other signals you might want to use are SIGHUP, SIGUSR1, and
SIGUSR2. These are general purpose signals, and different
applications will do different things when they are sent.
Suppose that you have changed your web server's configuration
file--you would like to tell the web server to re-read its
configuration. You could stop and restart httpd, but this would
result in a brief outage period on your web server, which may be
undesirable. Most daemons are written to respond to the SIGHUP
signal by re-reading their configuration file. So instead of
killing and restarting httpd you would send it the SIGHUP signal.
Because there is no standard way to respond to these signals,
different daemons will have different behavior, so be sure and
read the documentation for the daemon in question.
Signals are sent using the kill(1) command, as this example shows.
Sending a Signal to a Process
This example shows how to send a signal to inetd(8). The inetd
configuration file is /etc/inetd.conf, and inetd will re-read this
configuration file when it is sent SIGHUP.
1. Find the process ID of the process you want to send the signal
to. Do this using ps(1) and grep(1). The grep(1) command is
used to search through output, looking for the string you
specify. This command is run as a normal user, and inetd(8) is
run as root, so the ax options must be given to ps(1).
% ps -ax | grep inetd
198 ?? IWs 0:00.00 inetd -wW
So the inetd(8) PID is 198. In some cases the grep inetd
command might also occur in this output. This is because of
the way ps(1) has to find the list of running processes.
2. Use kill(1) to send the signal. Because inetd(8) is being run
by root you must use su(1) to become root first.
% su
Password:
# /bin/kill -s HUP 198
In common with most UNIX commands, kill(1) will not print any
output if it is successful. If you send a signal to a process
that you do not own then you will see ``kill: PID: Operation
not permitted''. If you mistype the PID you will either send
the signal to the wrong process, which could be bad, or, if
you are lucky, you will have sent the signal to a PID that is
not currently in use, and you will see ``kill: PID: No such
process''.
Why Use /bin/kill?: Many shells provide the kill command as
a built in command; that is, the shell will send the signal
directly, rather than running /bin/kill. This can be very
useful, but different shells have a different syntax for
specifying the name of the signal to send. Rather than try
to learn all of them, it can be simpler just to use the
/bin/kill ... command directly.
Sending other signals is very similar, just substitute TERM or
KILL in the command line as necessary.
Important: Killing random process on the system can be a bad
idea. In particular, init(8), process ID 1, is very special.
Running /bin/kill -s KILL 1 is a quick way to shutdown your
system. Always double check the arguments you run kill(1) with
before you press Return.
--------------------------------------------------------------
3.9 Shells
In DragonFly, a lot of everyday work is done in a command line
interface called a shell. A shell's main job is to take commands
from the input channel and execute them. A lot of shells also have
built in functions to help everyday tasks such as file management,
file globbing, command line editing, command macros, and
environment variables. DragonFly comes with a set of shells, such
as sh, the Bourne Shell, and tcsh, the improved C-shell. Many
other shells are available from pkgsrc, such as zsh and bash.
Which shell do you use? It is really a matter of taste. If you are
a C programmer you might feel more comfortable with a C-like shell
such as tcsh. If you have come from Linux or are new to a UNIX
command line interface you might try bash. The point is that each
shell has unique properties that may or may not work with your
preferred working environment, and that you have a choice of what
shell to use.
One common feature in a shell is filename completion. Given the
typing of the first few letters of a command or filename, you can
usually have the shell automatically complete the rest of the
command or filename by hitting the Tab key on the keyboard. Here
is an example. Suppose you have two files called foobar and
foo.bar. You want to delete foo.bar. So what you would type on the
keyboard is: rm fo[Tab].[Tab].
The shell would print out rm foo[BEEP].bar.
The [BEEP] is the console bell, which is the shell telling me it
was unable to totally complete the filename because there is more
than one match. Both foobar and foo.bar start with fo, but it was
able to complete to foo. If you type in ., then hit Tab again, the
shell would be able to fill in the rest of the filename for you.
Another feature of the shell is the use of environment variables.
Environment variables are a variable key pair stored in the
shell's environment space. This space can be read by any program
invoked by the shell, and thus contains a lot of program
configuration. Here is a list of common environment variables and
what they mean:
Variable Description
USER Current logged in user's name.
PATH Colon separated list of directories to search for
binaries.
DISPLAY Network name of the X11 display to connect to, if
available.
SHELL The current shell.
TERM The name of the user's terminal. Used to determine the
capabilities of the terminal.
TERMCAP Database entry of the terminal escape codes to perform
various terminal functions.
OSTYPE Type of operating system. e.g., DragonFly.
MACHTYPE The CPU architecture that the system is running on.
EDITOR The user's preferred text editor.
PAGER The user's preferred text pager.
MANPATH Colon separated list of directories to search for manual
pages.
Setting an environment variable differs somewhat from shell to
shell. For example, in the C-Style shells such as tcsh and csh,
you would use setenv to set environment variables. Under Bourne
shells such as sh and bash, you would use export to set your
current environment variables. For example, to set or modify the
EDITOR environment variable, under csh or tcsh a command like this
would set EDITOR to /usr/pkg/bin/emacs:
% setenv EDITOR /usr/pkg/bin/emacs
Under Bourne shells:
% export EDITOR="/usr/pkg/bin/emacs"
You can also make most shells expand the environment variable by
placing a $ character in front of it on the command line. For
example, echo $TERM would print out whatever $TERM is set to,
because the shell expands $TERM and passes it on to echo.
Shells treat a lot of special characters, called meta-characters
as special representations of data. The most common one is the *
character, which represents any number of characters in a
filename. These special meta-characters can be used to do filename
globbing. For example, typing in echo * is almost the same as
typing in ls because the shell takes all the files that match *
and puts them on the command line for echo to see.
To prevent the shell from interpreting these special characters,
they can be escaped from the shell by putting a backslash (\)
character in front of them. echo $TERM prints whatever your
terminal is set to. echo \$TERM prints $TERM as is.
--------------------------------------------------------------
3.9.1 Changing Your Shell
The easiest way to change your shell is to use the chsh command.
Running chsh will place you into the editor that is in your EDITOR
environment variable; if it is not set, you will be placed in vi.
Change the ``Shell:'' line accordingly.
You can also give chsh the -s option; this will set your shell for
you, without requiring you to enter an editor. For example, if you
wanted to change your shell to bash, the following should do the
trick:
% chsh -s /usr/pkg/bin/bash
Note: The shell that you wish to use must be present in the
/etc/shells file. If you have installed a shell from the pkgsrc
tree , then this should have been done for you already. If you
installed the shell by hand, you must do this.
For example, if you installed bash by hand and placed it into
/usr/local/bin, you would want to:
# echo "/usr/local/bin/bash" >> /etc/shells
Then rerun chsh.
--------------------------------------------------------------
3.10 Text Editors
A lot of configuration in DragonFly is done by editing text files.
Because of this, it would be a good idea to become familiar with a
text editor. DragonFly comes with a few as part of the base
system, and many more are available in the pkgsrc tree.
The easiest and simplest editor to learn is an editor called ee,
which stands for easy editor. To start ee, one would type at the
command line ee filename where filename is the name of the file to
be edited. For example, to edit /etc/rc.conf, type in ee
/etc/rc.conf. Once inside of ee, all of the commands for
manipulating the editor's functions are listed at the top of the
display. The caret ^ character represents the Ctrl key on the
keyboard, so ^e expands to the key combination Ctrl+e. To leave
ee, hit the Esc key, then choose leave editor. The editor will
prompt you to save any changes if the file has been modified.
DragonFly also comes with more powerful text editors such as vi as
part of the base system, while other editors, like emacs and vim,
are part of the pkgsrc tree. These editors offer much more
functionality and power at the expense of being a little more
complicated to learn. However if you plan on doing a lot of text
editing, learning a more powerful editor such as vim or emacs will
save you much more time in the long run.
--------------------------------------------------------------
3.11 Devices and Device Nodes
A device is a term used mostly for hardware-related activities in
a system, including disks, printers, graphics cards, and
keyboards. When DragonFly boots, the majority of what DragonFly
displays are devices being detected. You can look through the boot
messages again by viewing /var/run/dmesg.boot.
For example, acd0 is the first IDE CDROM drive, while kbd0
represents the keyboard.
Most of these devices in a UNIX operating system must be accessed
through special files called device nodes, which are located in
the /dev directory.
--------------------------------------------------------------
3.11.1 Creating Device Nodes with MAKEDEV
When adding a new device to your system, or compiling in support
for additional devices, you may need to create one or more device
nodes for the new devices.
Device nodes are created using the MAKEDEV(8) script as shown
below:
# cd /dev
# sh MAKEDEV ad1
This example would make the proper device nodes for the second IDE
drive when installed.
--------------------------------------------------------------
3.12 Binary Formats
To understand why DragonFly uses the elf(5) format, you must first
know a little about the three currently ``dominant'' executable
formats for UNIX:
* a.out(5)
The oldest and ``classic'' UNIX object format. It uses a short
and compact header with a magic number at the beginning that
is often used to characterize the format (see a.out(5) for
more details). It contains three loaded segments: .text,
.data, and .bss plus a symbol table and a string table.
* COFF
The SVR3 object format. The header now comprises a section
table, so you can have more than just .text, .data, and .bss
sections.
* elf(5)
The successor to COFF, featuring multiple sections and 32-bit
or 64-bit possible values. One major drawback: ELF was also
designed with the assumption that there would be only one ABI
per system architecture. That assumption is actually quite
incorrect, and not even in the commercial SYSV world (which
has at least three ABIs: SVR4, Solaris, SCO) does it hold
true.
DragonFly tries to work around this problem somewhat by
providing a utility for branding a known ELF executable with
information about the ABI it is compliant with. See the manual
page for brandelf(1) for more information. DragonFly runs ELF.
So, why are there so many different formats?
Back in the dim, dark past, there was simple hardware. This simple
hardware supported a simple, small system. a.out was completely
adequate for the job of representing binaries on this simple
system (a PDP-11). As people ported UNIX from this simple system,
they retained the a.out format because it was sufficient for the
early ports of UNIX to architectures like the Motorola 68k, VAXen,
etc.
Then some bright hardware engineer decided that if he could force
software to do some sleazy tricks, then he would be able to shave
a few gates off the design and allow his CPU core to run faster.
While it was made to work with this new kind of hardware (known
these days as RISC), a.out was ill-suited for this hardware, so
many formats were developed to get to a better performance from
this hardware than the limited, simple a.out format could offer.
Things like COFF, ECOFF, and a few obscure others were invented
and their limitations explored before things seemed to settle on
ELF.
In addition, program sizes were getting huge and disks (and
physical memory) were still relatively small so the concept of a
shared library was born. The VM system also became more
sophisticated. While each one of these advancements was done using
the a.out format, its usefulness was stretched more and more with
each new feature. In addition, people wanted to dynamically load
things at run time, or to junk parts of their program after the
init code had run to save in core memory and swap space. Languages
became more sophisticated and people wanted code called before
main automatically. Lots of hacks were done to the a.out format to
allow all of these things to happen, and they basically worked for
a time. In time, a.out was not up to handling all these problems
without an ever increasing overhead in code and complexity. While
ELF solved many of these problems, it would be painful to switch
from the system that basically worked. So ELF had to wait until it
was more painful to remain with a.out than it was to migrate to
ELF.
ELF is more expressive than a.out and allows more extensibility in
the base system. The ELF tools are better maintained, and offer
cross compilation support, which is important to many people. ELF
may be a little slower than a.out, but trying to measure it can be
difficult. There are also numerous details that are different
between the two in how they map pages, handle init code, etc. None
of these are very important, but they are differences.
--------------------------------------------------------------
3.13 For More Information
3.13.1 Manual Pages
The most comprehensive documentation on DragonFly is in the form
of manual pages. Nearly every program on the system comes with a
short reference manual explaining the basic operation and various
arguments. These manuals can be viewed with the man command. Use
of the man command is simple:
% man command
command is the name of the command you wish to learn about. For
example, to learn more about ls command type:
% man ls
The online manual is divided up into numbered sections:
1. User commands.
2. System calls and error numbers.
3. Functions in the C libraries.
4. Device drivers.
5. File formats.
6. Games and other diversions.
7. Miscellaneous information.
8. System maintenance and operation commands.
9. Kernel internals.
In some cases, the same topic may appear in more than one section
of the online manual. For example, there is a chmod user command
and a chmod() system call. In this case, you can tell the man
command which one you want by specifying the section:
% man 1 chmod
This will display the manual page for the user command chmod.
References to a particular section of the online manual are
traditionally placed in parenthesis in written documentation, so
chmod(1) refers to the chmod user command and chmod(2) refers to
the system call.
This is fine if you know the name of the command and simply wish
to know how to use it, but what if you cannot recall the command
name? You can use man to search for keywords in the command
descriptions by using the -k switch:
% man -k mail
With this command you will be presented with a list of commands
that have the keyword ``mail'' in their descriptions. This is
actually functionally equivalent to using the apropos command.
So, you are looking at all those fancy commands in /usr/bin but do
not have the faintest idea what most of them actually do? Simply
do:
% cd /usr/bin
% man -f *
or
% cd /usr/bin
% whatis *
which does the same thing.
--------------------------------------------------------------
3.13.2 GNU Info Files
DragonFly includes many applications and utilities produced by the
Free Software Foundation (FSF). In addition to manual pages, these
programs come with more extensive hypertext documents called info
files which can be viewed with the info command or, if you
installed emacs, the info mode of emacs.
To use the info(1) command, simply type:
% info
For a brief introduction, type h. For a quick command reference,
type ?.
--------------------------------------------------------------
Chapter 4 Installing Applications using NetBSD's pkgsrc framework
4.1 Synopsis
DragonFly is bundled with a rich collection of system tools as
part of the base system. However, there is only so much one can do
before needing to install an additional third-party application to
get real work done. DragonFly utilizes NetBSD's pkgsrc framework
(pkgsrc.org) for installing third party software on your system.
This system may be used to install the newest version of your
favorite applications from local media or straight off the
network.
After reading this chapter, you will know:
* How to install third-party binary software packages from the
pkgsrc collection.
* How to build third-party software from the pkgsrc collection.
* Where to find DragonFly-specific changes to packages.
* How to remove previously installed packages.
* How to override the default values that the pkgsrc collection
uses.
* How to upgrade your packages.
--------------------------------------------------------------
4.2 Overview of Software Installation
If you have used a UNIX system before you will know that the
typical procedure for installing third party software goes
something like this:
1. Download the software, which might be distributed in source
code format, or as a binary.
2. Unpack the software from its distribution format (typically a
tarball compressed with compress(1), gzip(1), or bzip2(1)).
3. Locate the documentation (perhaps an INSTALL or README file,
or some files in a doc/ subdirectory) and read up on how to
install the software.
4. If the software was distributed in source format, compile it.
This may involve editing a Makefile, or running a configure
script, and other work.
5. Test and install the software.
And that is only if everything goes well. If you are installing a
software package that was not deliberately ported to DragonFly you
may even have to go in and edit the code to make it work properly.
Should you want to, you can continue to install software the
``traditional'' way with DragonFly. However, DragonFly provides
technology from NetBSD, which can save you a lot of effort:
pkgsrc. At the time of writing, over 6,000 third party
applications have been made available in this way.
For any given application, the DragonFly Binary package for that
application is a single file which you must download. The package
contains pre-compiled copies of all the commands for the
application, as well as any configuration files or documentation.
A downloaded package file can be manipulated with DragonFly
package management commands, such as pkg_add(1), pkg_delete(1),
pkg_info(1), and so on. Installing a new application can be
carried out with a single command.
In addition the pkgsrc collection supplies a collection of files
designed to automate the process of compiling an application from
source code.
Remember that there are a number of steps you would normally carry
out if you compiled a program yourself (downloading, unpacking,
patching, compiling, installing). The files that make up a pkgsrc
source collection contain all the necessary information to allow
the system to do this for you. You run a handful of simple
commands and the source code for the application is automatically
downloaded, extracted, patched, compiled, and installed for you.
In fact, the pkgsrc source subsystem can also be used to generate
packages which can later be manipulated with pkg_add and the other
package management commands that will be introduced shortly.
Pkgsrc understands dependencies. Suppose you want to install an
application that depends on a specific library being installed.
Both the application and the library have been made available
through the pkgsrc collection. If you use the pkg_add command or
the pkgsrc subsystem to add the application, both will notice that
the library has not been installed, and automatically install the
library first.
You might be wondering why pkgsrc bothers with both. Binary
packages and the source tree both have their own strengths, and
which one you use will depend on your own preference.
Binary Package Benefits
* A compressed package tarball is typically smaller than the
compressed tarball containing the source code for the
application.
* Packages do not require any additional compilation. For large
applications, such as Mozilla, KDE, or GNOME this can be
important, particularly if you are on a slow system.
* Packages do not require any understanding of the process
involved in compiling software on DragonFly.
Pkgsrc source Benefits
* Binary packages are normally compiled with conservative
options, because they have to run on the maximum number of
systems. By installing from the source, you can tweak the
compilation options to (for example) generate code that is
specific to a Pentium IV or Athlon processor.
* Some applications have compile time options relating to what
they can and cannot do. For example, Apache can be configured
with a wide variety of different built-in options. By building
from the source you do not have to accept the default options,
and can set them yourself.
In some cases, multiple packages will exist for the same
application to specify certain settings. For example, vim is
available as a vim package and a vim-gtk package, depending on
whether you have installed an X11 server. This sort of rough
tweaking is possible with packages, but rapidly becomes
impossible if an application has more than one or two
different compile time options.
* The licensing conditions of some software distributions forbid
binary distribution. They must be distributed as source code.
* Some people do not trust binary distributions. With source
code, it is possible to check for any vulnerabilities built
into the program before installing it to an otherwise secure
system. Few people perform this much review, however.
* If you have local patches, you will need the source in order
to apply them.
* Some people like having code around, so they can read it if
they get bored, hack it, borrow from it (license permitting,
of course), and so on.
To keep track of updated pkgsrc releases subscribe to the NetBSD
pkgsrc users mailing list and the NetBSD pkgsrc users mailing
list. It's also useful to watch the DragonFly User related mailing
list as errors with pkgsrc on DragonFly should be reported there.
Warning: Before installing any application, you should check
http://www.pkgsrc.org/ for security issues related to your
application.
You can also install security/audit-packages which will
automatically check all installed applications for known
vulnerabilities, a check will be also performed before any
application build. Meanwhile, you can use the command
audit-packages -d after you have installed some packages.
The remainder of this chapter will explain how to use the pkgsrc
system to install and manage third party software on DragonFly.
--------------------------------------------------------------
4.3 Finding Your Application
Before you can install any applications you need to know what you
want, and what the application is called.
DragonFly's list of available applications is growing all the
time. Fortunately, there are a number of ways to find what you
want:
* There is a pkgsrc related web site that maintains an
up-to-date searchable list of all the available applications,
at http://pkgsrc.se. The packages and the corresponding source
tree are divided into categories, and you may either search
for an application by name (if you know it), or see all the
applications available in a category.
--------------------------------------------------------------
4.4 Using the Binary Packages System
Original FreeBSD documentation contributed by DragonFly BSD
customizations contributed by Chern Lee and Adrian Nida.
4.4.1 Installing a Binary Package
You can use the pkg_add(1) utility to install a pkgsrc software
package from a local file or from a server on the network.
Example 4-1. Downloading a Package Manually and Installing It
Locally
# ftp -a packages.stura.uni-rostock.de
Connected to fsr.uni-rostock.de.
220 packages.stura.uni-rostock.de FTP server (Version 6.00LS) ready.
331 Guest login ok, send your email address as password.
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> cd /pkgsrc-current/DragonFly/RELEASE/i386/All/
250 CWD command successful.
ftp> get 0verkill-0.15.tgz
local: 0verkill-0.15.tgz remote: 0verkill-0.15.tgz
229 Entering Extended Passive Mode (|||61652|)
150 Opening BINARY mode data connection for '0verkill-0.15.tgz' (174638 bytes).
100% |*************************************| 170 KB 159.37 KB/s 00:00 ETA
226 Transfer complete.
174638 bytes received in 00:01 (159.30 KB/s)
ftp> exit
221 Goodbye.
# pkg_add 0verkill-0.15.tgz
Note: It should be noted that simply issuing:
# pkg_add ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/RELEASE/i386/All/0verkill-0.15.tgz
will yield the same result as the above example.
Unlike the FreeBSD version, the Pkgsrc pkg_add(1) does not need to
be passed the -r option. As can be seen from the second example,
you just need to pass in the URL of the package. The utility will
also always automatically fetch and install all dependencies.
The example above would download the correct package and add it
without any further user intervention. If you want to specify an
alternative DragonFly Packages Mirror, instead of the main
distribution site, you have to set PACKAGESITE accordingly, to
override the default settings. pkg_add(1) uses fetch(3) to
download the files, which honors various environment variables,
including FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD. You may
need to set one or more of these if you are behind a firewall, or
need to use an FTP/HTTP proxy. See fetch(3) for the complete list.
Binary package files are distributed in .tgz formats. You can find
them at the default location ftp://goBSD.com//packages/, among
other sites. The layout of the packages is similar to that of the
/usr/pkgsrc tree. Each category has its own directory, and every
package can be found within the All directory.
The directory structure of the binary package system matches the
source tree layout; they work with each other to form the entire
package system.
--------------------------------------------------------------
4.4.2 Managing Packages
pkg_info(1) is a utility that lists and describes the various
packages installed.
# pkg_info
digest-20050731 Message digest wrapper utility
screen-4.0.2nb4 Multi-screen window manager
...
pkg_version(1) is a utility that summarizes the versions of all
installed packages. It compares the package version to the current
version found in the ports tree.
--------------------------------------------------------------
4.4.3 Deleting a Package
To remove a previously installed software package, use the
pkg_delete(1) utility.
# pkg_delete xchat-1.7.1
--------------------------------------------------------------
4.4.4 Miscellaneous
All package information is stored within the /var/db/pkg
directory. The installed file list and descriptions of each
package can be found within subdirectories of this directory.
--------------------------------------------------------------
4.5 Using the pkgsrc(R) Source Tree
The following sections provide basic instructions on using the
pkgsrc source tree to install or remove programs from your system.
--------------------------------------------------------------
4.5.1 Obtaining the pkgsrc Source Tree
Before you can install pkgsrc packages from source, you must first
obtain the pkgsrc source tree--which is essentially a set of
Makefiles, patches, and description files placed in /usr/pkgsrc.
The primary method to obtain and keep your pkgsrc collection up to
date is by using CVS
CVS
This is a quick method for getting the pkgsrc collection using
CVS.
1. Run cvs:
# cd /usr/
# cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
2. Running the following command later will download and apply
all the recent changes to your source tree.
# cd /usr/pkgsrc
# cvs up
--------------------------------------------------------------
4.5.2 Installing Packages from Source
The first thing that should be explained when it comes to the
source tree is what is actually meant by a ``skeleton''. In a
nutshell, a source skeleton is a minimal set of files that tell
your DragonFly system how to cleanly compile and install a
program. Each source skeleton should include:
* A Makefile. The Makefile contains various statements that
specify how the application should be compiled and where it
should be installed on your system.
* A distinfo file. This file contains information about the
files that must be downloaded to build the port and their
checksums, to verify that files have not been corrupted during
the download using md5(1).
* A files directory. This directory contains the application
specific files that are needed for the programs appropriate
run-time configuration.
This directory may also contain other files used to build the
port.
* A patches directory. This directory contains patches to make
the program compile and install on your DragonFly system.
Patches are basically small files that specify changes to
particular files. They are in plain text format, and basically
say ``Remove line 10'' or ``Change line 26 to this ...''.
Patches are also known as ``diffs'' because they are generated
by the diff(1) program.
* A DESCR file. This is a more detailed, often multiple-line,
description of the program.
* A PLIST file. This is a list of all the files that will be
installed by the port. It also tells the pkgsrc system what
files to remove upon deinstallation.
Some pkgsrc source skeletons have other files, such as MESSAGE.
The pkgsrc system uses these files to handle special situations.
If you want more details on these files, and on pkgsrc in general,
check out The pkgsrc guide, available at the NetBSD website.
Now that you have enough background information to know what the
pkgsrc source tree is used for, you are ready to install your
first compiled package. There are two ways this can be done, and
each is explained below.
Before we get into that, however, you will need to choose an
application to install. There are a few ways to do this, with the
easiest method being the pkgsrc listing on Joerg Sonnenberger's
web site. You can browse through the packages listed there.
Another way to find a particular source tree is by using the
pkgsrc collection's built-in search mechanism. To use the search
feature, you will need to be in the /usr/pkgsrc directory. Once in
that directory, run bmake search key="program-name" where
program-name is the name of the program you want to find. This
searches packages names, comments, descriptions and dependencies
and can be used to find packages which relate to a particular
subject if you don't know the name of the program you are looking
for. For example, if you were looking for apache2:
# cd /usr/pkgsrc
# bmake search key="apache2"
Extracting complete dependency database. This may take a while...
....................................................................................................
100
....................................................................................................
200
5800
....................................................................................................
5900
.................................................................................................Reading database file
Flattening dependencies
Flattening build dependencies
Generating INDEX file
Indexed 5999 packages
Pkg: apache-2.0.55nb7
Path: www/apache2
Info: Apache HTTP (Web) server, version 2
Maint: tron@NetBSD.org
Index: www
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
R-deps: perl>=5.0 apr>=0.9.7.2.0.55nb2 expat>=2.0.0nb1
Arch: any
The part of the output you want to pay particular attention to is
the ``Path:'' line, since that tells you where to find the source
tree for the requested application. The other information provided
is not needed in order to install the package, so it will not be
covered here.
The search string is case-insensitive. Searching for ``APACHE''
will yield the same results as searching for ``apache''.
Note: It should be noted that ``Extracting [the] complete
dependency database'' does indeed take a while.
Note: You must be logged in as root to install packages.
Now that you have found an application you would like to install,
you are ready to do the actual installation. The source package
includes instructions on how to build source code, but does not
include the actual source code. You can get the source code from a
CD-ROM or from the Internet. Source code is distributed in
whatever manner the software author desires. Frequently this is a
tarred and gzipped file, but it might be compressed with some
other tool or even uncompressed. The program source code, whatever
form it comes in, is called a ``distfile''. You can get the
distfile from a CD-ROM or from the Internet.
Warning: Before installing any application, you should be sure
to have an up-to-date source tree and you should check
http://www.pkgsrc.org/ for security issues related to your port.
A security vulnerabilities check can be automatically done by
audit-packages before any new application installation. This
tool can be found in the pkgsrc collection
(security/audit-packages). Consider running auditpackages -d
before installing a new package, to fetch the current
vulnerabilities database. A security audit and an update of the
database will be performed during the daily security system
check. For more informations read the audit-packages and
periodic(8) manual pages.
Note: It should be noted that the current setup of DragonFly
requires the use of bmake instead of make. This is because the
current version of make on DragonFly does not support all the
parameters that NetBSD's does.
Note: You can save an extra step by just running bmake install
instead of bmake and bmake install as two separate steps.
Note: Some shells keep a cache of the commands that are
available in the directories listed in the PATH environment
variable, to speed up lookup operations for the executable file
of these commands. If you are using one of these shells, you
might have to use the rehash command after installing a package,
before the newly installed commands can be used. This is true
for both shells that are part of the base-system (such as tcsh)
and shells that are available as packages (for instance,
shells/zsh).
--------------------------------------------------------------
4.5.2.1 Installing Packages from the Internet
As with the last section, this section makes an assumption that
you have a working Internet connection. If you do not, you will
need to put a copy of the distfile into /usr/pkgsrc/distfiles
manually.
Installing a package from the Internet is done exactly the same
way as it would be if you already had the distfile. The only
difference between the two is that the distfile is downloaded from
the Internet on demand.
Here are the steps involved:
# cd /usr/pkgsrc/chat/ircII
# bmake install clean
=> ircii-20040820.tar.bz2 doesn't seem to exist on this system.
=> Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
=> [559843 bytes]
Connected to ircii.warped.com.
220 bungi.sjc.warped.net FTP server (tnftpd 20040810) ready.
331 Guest login ok, type your name as password.
230-
A SERVICE OF WARPED.COM - FOR MORE INFORMATION: http://www.warped.com
230-
Please read the file README
it was last modified on Mon Feb 9 18:43:17 2004 - 794 days ago
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
200 Type set to I.
250 CWD command successful.
250 CWD command successful.
local: ircii-20040820.tar.bz2 remote: ircii-20040820.tar.bz2
229 Entering Extended Passive Mode (|||60090|)
150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
100% |***************************************| 550 KB 110.34 KB/s 00:00 ETA
226 Transfer complete.
559843 bytes received in 00:04 (110.34 KB/s)
221-
Data traffic for this session was 559843 bytes in 1 file.
Total traffic for this session was 560993 bytes in 1 transfer.
221 Thank you for using the FTP service on bungi.sjc.warped.net.
=> Checksum SHA1 OK for ircii-20040820.tar.bz2.
=> Checksum RMD160 OK for ircii-20040820.tar.bz2.
work -> /usr/obj/pkgsrc/chat/ircII/work
===> Extracting for ircII-20040820
==========================================================================
The supported build options for this package are:
socks4 socks5
You can select which build options to use by setting PKG_DEFAULT_OPTIONS
or the following variable. Its current value is shown:
PKG_OPTIONS.ircII (not defined)
==========================================================================
==========================================================================
The following variables will affect the build process of this package,
ircII-20040820. Their current value is shown below:
* USE_INET6 = YES
You may want to abort the process now with CTRL-C and change their value
before continuing. Be sure to run `/usr/pkg/bin/bmake clean' after
the changes.
==========================================================================
===> Patching for ircII-20040820
===> Applying pkgsrc patches for ircII-20040820
===> Overriding tools for ircII-20040820
===> Creating toolchain wrappers for ircII-20040820
===> Configuring for ircII-20040820
...
[configure output snipped]
...
===> Building for ircII-20040820
...
[compilation output snipped]
...
===> Installing for ircII-20040820
...
[installation output snipped]
...
===> [Automatic manual page handling]
===> Registering installation for ircII-20040820
===> Cleaning for ircII-20040820
#
As you can see, the only difference are the lines that tell you
where the system is fetching the package's distfile from.
The pkgsrc system uses ftp(1) to download the files, which honors
various environment variables, including FTP_PASSIVE_MODE,
FTP_PROXY, and FTP_PASSWORD. You may need to set one or more of
these if you are behind a firewall, or need to use an FTP/HTTP
proxy. See ftp(1) for the complete list.
For users which cannot be connected all the time, the bmake fetch
option is provided. Just run this command at the top level
directory (/usr/pkgsrc) and the required files will be downloaded
for you. This command will also work in the lower level
categories, for example: /usr/pkgsrc/net. Note that if a package
depends on libraries or other packages this will not fetch the
distfiles of those packages as well.
Note: You can build all the packages in a category or as a whole
by running bmake in the top level directory, just like the
aforementioned bmake fetch method. This is dangerous, however,
as some applications cannot co-exist. In other cases, some
packages can install two different files with the same filename.
In some rare cases, users may need to acquire the tarballs from a
site other than the MASTER_SITES (the location where files are
downloaded from). You can override the MASTER_SORT,
MASTER_SORT_REGEX and INET_COUNTRY options either within the
/etc/mk.conf.
Note: Some packages allow (or even require) you to provide build
options which can enable/disable parts of the application which
are unneeded, certain security options, and other
customizations. A few which come to mind are www/mozilla,
security/gpgme, and mail/sylpheed-claws. To find out what build
options the application you are installing requires type:
# bmake show-options
To change the build process, either change the values of
PKG_DEFAULT_OPTIONS or PKG_OPTIONS.PackageName in /etc/mk.conf
or on the commandline as so:
# bmake PKG_OPTIONS.ircII="-ssl"
An option is enabled if listed. It is disabled if it is prefixed
by a minus sign.
--------------------------------------------------------------
4.5.2.2 Dealing with imake
Some applications that use imake (a part of the X Window System)
do not work well with PREFIX, and will insist on installing under
/usr/X11R6. Similarly, some Perl ports ignore PREFIX and install
in the Perl tree. Making these applications respect PREFIX is a
difficult or impossible job.
--------------------------------------------------------------
4.5.3 Removing Installed Packages
Now that you know how to install packages, you are probably
wondering how to remove them, just in case you install one and
later on decide that you installed the wrong program. We will
remove our previous example (which was ircII for those of you not
paying attention). As with installing packages, the first thing
you must do is change to the package directory,
/usr/pkgsrc/chat/ircII. After you change directories, you are
ready to uninstall ircII. This is done with the bmake deinstall
command:
# cd /usr/pkgsrc/chat/ircII
# make deinstall
===> Deinstalling for ircII-20040820
That was easy enough. You have removed ircII from your system. If
you would like to reinstall it, you can do so by running bmake
reinstall from the /usr/pkgsrc/chat/ircII directory.
The bmake deinstall and bmake reinstall sequence does not work
once you have run bmake clean. If you want to deinstall a package
after cleaning, use pkg_delete(1) as discussed in the Pkgsrc
section of the Handbook.
--------------------------------------------------------------
4.5.4 Packages and Disk Space
Using the pkgsrc collection can definitely eat up your disk space.
For this reason you should always remember to clean up the work
directories using the bmake clean option. This will remove the
work directory after a package has been built, and installed. You
can also remove the tar files from the distfiles directory, and
remove the installed package when their use has delimited.
--------------------------------------------------------------
4.5.5 Upgrading Packages
Note: Once you have updated your pkgsrc collection, before
attempting a package upgrade, you should check the
/usr/pkgsrc/UPDATING file. This file describes various issues
and additional steps users may encounter and need to perform
when updating a port.
Keeping your packages up to date can be a tedious job. For
instance, to upgrade a package you would go to the package
directory, build the package, deinstall the old package , install
the new package, and then clean up after the build. Imagine doing
that for five packages, tedious right? This was a large problem
for system administrators to deal with, and now we have utilities
which do this for us. For instance the pkg_chk utility will do
everything for you!
pkg_chk requires a few steps in order to work correctly. They are
listed here.
# pkg_chk -g # make initial list of installed packages
# pkg_chk -r # remove all packages that are not up to date and packages that depend on them
# pkg_chk -a # install all missing packages (use binary packages, this is the default)
# pkg_chk -as # install all missing packages (build from source)
--------------------------------------------------------------
4.6 Post-installation Activities
After installing a new application you will normally want to read
any documentation it may have included, edit any configuration
files that are required, ensure that the application starts at
boot time (if it is a daemon), and so on.
The exact steps you need to take to configure each application
will obviously be different. However, if you have just installed a
new application and are wondering ``What now?'' these tips might
help:
* Use pkg_info(1) to find out which files were installed, and
where. For example, if you have just installed FooPackage
version 1.0.0, then this command
# pkg_info -L foopackage-1.0.0 | less
will show all the files installed by the package. Pay special
attention to files in man/ directories, which will be manual
pages, etc/ directories, which will be configuration files,
and doc/, which will be more comprehensive documentation.
If you are not sure which version of the application was just
installed, a command like this
# pkg_info | grep -i foopackage
will find all the installed packages that have foopackage in
the package name. Replace foopackage in your command line as
necessary.
* Once you have identified where the application's manual pages
have been installed, review them using man(1). Similarly, look
over the sample configuration files, and any additional
documentation that may have been provided.
* If the application has a web site, check it for additional
documentation, frequently asked questions, and so forth. If
you are not sure of the web site address it may be listed in
the output from
# pkg_info foopackage-1.0.0
A WWW: line, if present, should provide a URL for the
application's web site.
* Packages that should start at boot (such as Internet servers)
will usually install a sample script in /usr/pkg/etc/rc.d. You
should review this script for correctness and edit or rename
it if needed. See Starting Services for more information.
--------------------------------------------------------------
4.7 Dealing with Broken Packages
If you come across a package that does not work for you, there are
a few things you can do, including:
1. Fix it! The pkgsrc Guide includes detailed information on the
``pkgsrc'' infrastructure so that you can fix the occasional
broken package or even submit your own!
2. Gripe--by email only! Send email to the maintainer of the
package first. Type bmake maintainer or read the Makefile to
find the maintainer's email address. Remember to include the
name and version of the port (send the $NetBSD: line from the
Makefile) and the output leading up to the error when you
email the maintainer. If you do not get a response from the
maintainer, you can try users .
3. Grab the package from an FTP site near you. The ``master''
package collection is on packages.stura.uni-rostock.de in the
All directory. These are more likely to work than trying to
compile from source and are a lot faster as well. Use the
pkg_add(1) program to install the package on your system.
--------------------------------------------------------------
Chapter 5 The X Window System
Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille.
Updated for DragonFly by Victor Balada Diaz.
5.1 Synopsis
DragonFly uses X11 to provide users with a powerful graphical user
interface. X11 is an open-source implementation of the X Window
System that includes both X.org and XFree86. DragonFly default
official flavor is X.org, the X11 server developed by the X.Org
Foundation.
This chapter will cover the installation and configuration of X11
with emphasis on X.org.
For more information on the video hardware that X11 supports,
check either the X.org or XFree86 web sites.
After reading this chapter, you will know:
* The various components of the X Window System, and how they
interoperate.
* How to install and configure X11.
* How to install and use different window managers.
* How to use TrueType(R) fonts in X11.
* How to set up your system for graphical logins (XDM).
Before reading this chapter, you should:
* Know how to install additional third-party software (Chapter
4).
Note: This chapter covers the installation and the configuration
of both X.org and XFree86 X11 servers. For the most part,
configuration files, commands and syntaxes are identical. In the
case where there are differences, both X.org and XFree86
syntaxes will be shown.
--------------------------------------------------------------
5.2 Understanding X
Using X for the first time can be somewhat of a shock to someone
familiar with other graphical environments, such as
Microsoft Windows or Mac OS.
While it is not necessary to understand all of the details of
various X components and how they interact, some basic knowledge
makes it possible to take advantage of X's strengths.
--------------------------------------------------------------
5.2.1 Why X?
X is not the first window system written for UNIX, but it is the
most popular of them. X's original development team had worked on
another window system prior to writing X. That system's name was
``W'' (for ``Window''). X was just the next letter in the Roman
alphabet.
X can be called ``X'', ``X Window System'', ``X11'', and a number
of other terms. You may find that using the term ``X Windows'' to
describe X11 can be offensive to some people; for a bit more
insight on this, see X(7).
--------------------------------------------------------------
5.2.2 The X Client/Server Model
X was designed from the beginning to be network-centric, and
adopts a ``client-server'' model.
In the X model, the ``X server'' runs on the computer that has the
keyboard, monitor, and mouse attached. The server's responsibility
includes tasks such as managing the display, handling input from
the keyboard and mouse, and so on. Each X application (such as
XTerm, or Netscape) is a ``client''. A client sends messages to
the server such as ``Please draw a window at these coordinates'',
and the server sends back messages such as ``The user just clicked
on the OK button''.
In a home or small office environment, the X server and the X
clients commonly run on the same computer. However, it is
perfectly possible to run the X server on a less powerful desktop
computer, and run X applications (the clients) on, say, the
powerful and expensive machine that serves the office. In this
scenario the communication between the X client and server takes
place over the network.
This confuses some people, because the X terminology is exactly
backward to what they expect. They expect the ``X server'' to be
the big powerful machine down the hall, and the ``X client'' to be
the machine on their desk.
It is important to remember that the X server is the machine with
the monitor and keyboard, and the X clients are the programs that
display the windows.
There is nothing in the protocol that forces the client and server
machines to be running the same operating system, or even to be
running on the same type of computer. It is certainly possible to
run an X server on Microsoft Windows or Apple's Mac OS, and there
are various free and commercial applications available that do
exactly that.
DragonFly will use by default X.org server. X.org is available for
free, under a license very similar to the DragonFly license.
--------------------------------------------------------------
5.2.3 The Window Manager
The X design philosophy is much like the UNIX design philosophy,
``tools, not policy''. This means that X does not try to dictate
how a task is to be accomplished. Instead, tools are provided to
the user, and it is the user's responsibility to decide how to use
those tools.
This philosophy extends to X not dictating what windows should
look like on screen, how to move them around with the mouse, what
keystrokes should be used to move between windows (i.e., Alt+Tab,
in the case of Microsoft Windows), what the title bars on each
window should look like, whether or not they have close buttons on
them, and so on.
Instead, X delegates this responsibility to an application called
a ``Window Manager''. There are dozens of window managers
available for X: AfterStep, Blackbox, ctwm, Enlightenment, fvwm,
Sawfish, twm, Window Maker, and more. Each of these window
managers provides a different look and feel; some of them support
``virtual desktops''; some of them allow customized keystrokes to
manage the desktop; some have a ``Start'' button or similar
device; some are ``themeable'', allowing a complete change of
look-and-feel by applying a new theme. These window managers, and
many more, are available in the x11-wm category of the Ports
Collection.
In addition, the KDE and GNOME desktop environments both have
their own window managers which integrate with the desktop.
Each window manager also has a different configuration mechanism;
some expect configuration file written by hand, others feature GUI
tools for most of the configuration tasks; at least one (Sawfish)
has a configuration file written in a dialect of the Lisp
language.
Focus Policy: Another feature the window manager is responsible
for is the mouse ``focus policy''. Every windowing system needs
some means of choosing a window to be actively receiving
keystrokes, and should visibly indicate which window is active
as well.
A familiar focus policy is called ``click-to-focus''. This is
the model utilized by Microsoft Windows, in which a window
becomes active upon receiving a mouse click.
X does not support any particular focus policy. Instead, the
window manager controls which window has the focus at any one
time. Different window managers will support different focus
methods. All of them support click to focus, and the majority of
them support several others.
The most popular focus policies are:
focus-follows-mouse
The window that is under the mouse pointer is the window
that has the focus. This may not necessarily be the
window that is on top of all the other windows. The
focus is changed by pointing at another window, there is
no need to click in it as well.
sloppy-focus
This policy is a small extension to focus-follows-mouse.
With focus-follows-mouse, if the mouse is moved over the
root window (or background) then no window has the
focus, and keystrokes are simply lost. With
sloppy-focus, focus is only changed when the cursor
enters a new window, and not when exiting the current
window.
click-to-focus
The active window is selected by mouse click. The window
may then be ``raised'', and appear in front of all other
windows. All keystrokes will now be directed to this
window, even if the cursor is moved to another window.
Many window managers support other policies, as well as
variations on these. Be sure to consult the documentation for
the window manager itself.
--------------------------------------------------------------
5.2.4 Widgets
The X approach of providing tools and not policy extends to the
widgets seen on screen in each application.
``Widget'' is a term for all the items in the user interface that
can be clicked or manipulated in some way; buttons, check boxes,
radio buttons, icons, lists, and so on. Microsoft Windows calls
these ``controls''.
Microsoft Windows and Apple's Mac OS both have a very rigid widget
policy. Application developers are supposed to ensure that their
applications share a common look and feel. With X, it was not
considered sensible to mandate a particular graphical style, or
set of widgets to adhere to.
As a result, do not expect X applications to have a common look
and feel. There are several popular widget sets and variations,
including the original Athena widget set from MIT, Motif(R) (on
which the widget set in Microsoft Windows was modeled, all
bevelled edges and three shades of grey), OpenLook, and others.
Most newer X applications today will use a modern-looking widget
set, either Qt, used by KDE, or GTK+, used by the GNOME project.
In this respect, there is some convergence in look-and-feel of the
UNIX desktop, which certainly makes things easier for the novice
user.
--------------------------------------------------------------
5.3 Installing X11
X.org or XFree86 may be installed on DragonFly. DragonFly doesn't
force a default implementation, but recommends X.org. X.org is the
X server of the open source X Window System implementation
released by the X.Org Foundation. X.org is based on the code of
XFree86 4.4RC2 and X11R6.6. The X.Org Foundation released X11R6.7
in April 2004 and X11R6.8.2 in February 2005, this latter is the
version currently available in the DragonFly pkgsrc framework.
To build and install X.org from the Ports Collection:
# cd /usr/pkgsrc/meta-pkgs/xorg
# bmake install clean
Note: To build X.org in its entirety, be sure to have at least
4 GB of free space available.
To build and install XFree86 from the pkgsrc framework:
# echo "X11_TYPE=XFree86" >> /etc/mk.conf
# cd /usr/pkgsrc/meta-pkgs/XFree86
# bmake install clean
Alternatively, X11 can be installed directly from packages. Binary
packages to use with pkg_add(1) tool are also available for X11.
If you have configured PKG_PATH the remote fetching feature of
pkg_add(1) is used, the version number of the package is not
required. pkg_add(1) will automatically fetch the latest version
of the application.
So to fetch and install the package of X.org, simply type:
# pkg_add xorg
The XFree86 4.X package can be installed by typing:
# pkg_add XFree86
Note: The examples above will install the complete X11
distribution including the servers, clients, fonts etc. Separate
packages and ports of X11 are also available.
The rest of this chapter will explain how to configure X11, and
how to set up a productive desktop environment.
--------------------------------------------------------------
5.4 X11 Configuration
Contributed by Christopher Shumway.
--------------------------------------------------------------
5.4.1 Before Starting
Before configuration of X11 the following information about the
target system is needed:
* Monitor specifications
* Video Adapter chipset
* Video Adapter memory
The specifications for the monitor are used by X11 to determine
the resolution and refresh rate to run at. These specifications
can usually be obtained from the documentation that came with the
monitor or from the manufacturer's website. There are two ranges
of numbers that are needed, the horizontal scan rate and the
vertical synchronization rate.
The video adapter's chipset defines what driver module X11 uses to
talk to the graphics hardware. With most chipsets, this can be
automatically determined, but it is still useful to know in case
the automatic detection does not work correctly.
Video memory on the graphic adapter determines the resolution and
color depth which the system can run at. This is important to know
so the user knows the limitations of the system.
--------------------------------------------------------------
5.4.2 Configuring X11
Configuration of X11 is a multi-step process. The first step is to
build an initial configuration file. As the super user, simply
run:
# Xorg -configure
In the case of XFree86 type:
# XFree86 -configure
This will generate an X11 configuration skeleton file in the /root
directory called xorg.conf.new (whether you su(1) or do a direct
login affects the inherited supervisor $HOME directory variable).
For XFree86, this configuration file is called XF86Config.new. The
X11 program will attempt to probe the graphics hardware on the
system and write a configuration file to load the proper drivers
for the detected hardware on the target system.
The next step is to test the existing configuration to verify that
X.org can work with the graphics hardware on the target system. To
perform this task, type:
# Xorg -config xorg.conf.new
XFree86 users will type:
# XFree86 -xf86config XF86Config.new
If a black and grey grid and an X mouse cursor appear, the
configuration was successful. To exit the test, just press
Ctrl+Alt+Backspace simultaneously.
Note: If the mouse does not work, you will need to first
configure it before proceeding.
Next, tune the xorg.conf.new (or XF86Config.new if you are running
XFree86) configuration file to taste. Open the file in a text
editor such as emacs(1) or ee(1). First, add the frequencies for
the target system's monitor. These are usually expressed as a
horizontal and vertical synchronization rate. These values are
added to the xorg.conf.new file under the "Monitor" section:
Section "Monitor"
Identifier "Monitor0"
VendorName "Monitor Vendor"
ModelName "Monitor Model"
HorizSync 30-107
VertRefresh 48-120
EndSection
The HorizSync and VertRefresh keywords may be missing in the
configuration file. If they are, they need to be added, with the
correct horizontal synchronization rate placed after the HorizSync
keyword and the vertical synchronization rate after the
VertRefresh keyword. In the example above the target monitor's
rates were entered.
X allows DPMS (Energy Star) features to be used with capable
monitors. The xset(1) program controls the time-outs and can force
standby, suspend, or off modes. If you wish to enable DPMS
features for your monitor, you must add the following line to the
monitor section:
Option "DPMS"
While the xorg.conf.new (or XF86Config.new) configuration file is
still open in an editor, select the default resolution and color
depth desired. This is defined in the "Screen" section:
Section "Screen"
Identifier "Screen0"
Device "Card0"
Monitor "Monitor0"
DefaultDepth 24
SubSection "Display"
Viewport 0 0
Depth 24
Modes "1024x768"
EndSubSection
EndSection
The DefaultDepth keyword describes the color depth to run at by
default. This can be overridden with the -depth command line
switch to Xorg(1) (or XFree86(1)). The Modes keyword describes the
resolution to run at for the given color depth. Note that only
VESA standard modes are supported as defined by the target
system's graphics hardware. In the example above, the default
color depth is twenty-four bits per pixel. At this color depth,
the accepted resolution is 1024 by 768 pixels.
Finally, write the configuration file and test it using the test
mode given above.
Note: One of the tools available to assist you during
troubleshooting process are the X11 log files, which contain
information on each device that the X11 server attaches to.
X.org log file names are in the format of /var/log/Xorg.0.log
(XFree86 log file names follow the format of XFree86.0.log). The
exact name of the log can vary from Xorg.0.log to Xorg.8.log and
so forth.
If all is well, the configuration file needs to be installed in a
common location where Xorg(1) (or XFree86(1)) can find it. This is
typically /etc/X11/xorg.conf or /usr/pkg/xorg/lib/X11/xorg.conf
(for XFree86 it is called /etc/X11/XF86Config or
/usr/pkg/XFree86/lib/X11/XF86Config).
# cp xorg.conf.new /etc/X11/xorg.conf
For XFree86:
# cp XF86Config.new /etc/X11/XF86Config
The X11 configuration process is now complete. You can start
XFree86 4.X or X.org with startx(1). The X11 server may also be
started with the use of xdm(1).
Note: There is also a graphical configuration tool, xorgcfg(1)
(xf86cfg(1) for XFree86), that comes with the X11 distribution.
It allows you to interactively define your configuration by
choosing the appropriate drivers and settings. This program can
be invoked from the console, by typing the command xorgcfg
-textmode. For more details, refer to the xorgcfg(1) and
xf86cfg(1) manual pages.
Alternatively, there is also a tool called xorgconfig(1)
(xf86config(1) for XFree86), this program is a console utility
that is less user friendly, but it may work in situations where
the other tools do not.
--------------------------------------------------------------
5.4.3 Advanced Configuration Topics
5.4.3.1 Configuration with Intel(R) i810 Graphics Chipsets
Configuration with Intel(R) i810 integrated chipsets requires the
agpgart AGP programming interface for X11 to drive the card. See
the agp(4) driver manual page for more information.
This will allow configuration of the hardware as any other
graphics board. Note on systems without the agp(4) driver compiled
in the kernel, trying to load the module with kldload(8) will not
work. This driver has to be in the kernel at boot time through
being compiled in or using /boot/loader.conf.
If you are using XFree86 4.1.0 (or later) and messages about
unresolved symbols like fbPictureInit appear, try adding the
following line after Driver "i810" in the X11 configuration file:
Option "NoDDC"
--------------------------------------------------------------
5.5 Using Fonts in X11
Contributed by Murray Stokely.
5.5.1 Type1 Fonts
The default fonts that ship with X11 are less than ideal for
typical desktop publishing applications. Large presentation fonts
show up jagged and unprofessional looking, and small fonts in
Netscape are almost completely unintelligible. However, there are
several free, high quality Type1 (PostScript(R)) fonts available
which can be readily used with X11. For instance, the Freefonts
collection (fonts/freefonts) includes a lot of fonts, but most of
them are intended for use in graphics software such as the Gimp,
and are not complete enough to serve as screen fonts. In addition,
X11 can be configured to use TrueType fonts with a minimum of
effort. For more details on this, see the X(7) manual page or the
section on TrueType fonts.
To install the Freefonts font collection from the pkgsrc
framework, run the following commands:
# cd /usr/pkgsrc/fonts/freefonts
# bmake install clean
And likewise with the other collections. To have the X server
detect these fonts, add an appropriate line to the X server
configuration file in /etc/X11/ (xorg.conf for X.org and
XF86Config for XFree86), which reads:
FontPath "/usr/pkg/lib/X11/fonts/freefont/"
Alternatively, at the command line in the X session run:
% xset fp+ /usr/pkg/lib/X11/fonts/freefont/
% xset fp rehash
This will work but will be lost when the X session is closed,
unless it is added to the startup file (~/.xinitrc for a normal
startx session, or ~/.xsession when logging in through a graphical
login manager like XDM). A third way is to use the new
/usr/pkg/xorg/etc/fonts/local.conf file: see the section on
anti-aliasing.
--------------------------------------------------------------
5.5.2 TrueType(R) Fonts
Both XFree86 4.X and X.org have built in support for rendering
TrueType fonts. There are two different modules that can enable
this functionality. The freetype module is used in this example
because it is more consistent with the other font rendering
back-ends. To enable the freetype module just add the following
line to the "Module" section of the /etc/X11/xorg.conf or
/etc/X11/XF86Config file.
Load "freetype"
For XFree86 3.3.X, a separate TrueType font server is needed.
Xfstt is commonly used for this purpose. To install Xfstt, simply
install the port x11/xfstt.
Now make a directory for the TrueType fonts (for example,
/usr/pkg/xorg/lib/X11/fonts/TrueType) and copy all of the TrueType
fonts into this directory. Keep in mind that TrueType fonts cannot
be directly taken from a Macintosh(R); they must be in
UNIX/MS-DOS/Windows format for use by X11. Once the files have
been copied into this directory, use ttmkfdir to create a
fonts.dir file, so that the X font renderer knows that these new
files have been installed. ttmkfdir is available from the pkgsrc
framework as fonts/ttmkfdir2.
# cd /usr/pkg/xorg/lib/X11/fonts/TrueType
# ttmkfdir > fonts.dir
Now add the TrueType directory to the font path. This is just the
same as described above for Type1 fonts, that is, use
% xset fp+ /usr/pkg/xorg/lib/X11/fonts/TrueType
% xset fp rehash
or add a FontPath line to the xorg.conf (or XF86Config) file.
That's it. Now Netscape, Gimp, StarOffice(TM), and all of the
other X applications should now recognize the installed TrueType
fonts. Extremely small fonts (as with text in a high resolution
display on a web page) and extremely large fonts (within
StarOffice) will look much better now.
--------------------------------------------------------------
5.5.3 Anti-Aliased Fonts
Updated by Joe Marcus Clarke.
Anti-aliasing has been available in X11 since XFree86 4.0.2.
However, font configuration was cumbersome before the introduction
of XFree86 4.3.0. Beginning with XFree86 4.3.0, all fonts in X11
that are found in /usr/pkg/xorg/lib/X11/fonts/ and ~/.fonts/ are
automatically made available for anti-aliasing to Xft-aware
applications. Not all applications are Xft-aware, but many have
received Xft support. Examples of Xft-aware applications include
Qt 2.3 and higher (the toolkit for the KDE desktop), GTK+ 2.0 and
higher (the toolkit for the GNOME desktop), and Mozilla 1.2 and
higher.
In order to control which fonts are anti-aliased, or to configure
anti-aliasing properties, create (or edit, if it already exists)
the file /usr/pkg/xorg/lib/etc/fonts/local.conf. Several advanced
features of the Xft font system can be tuned using this file; this
section describes only some simple possibilities. For more
details, please see fonts-conf(5).
This file must be in XML format. Pay careful attention to case,
and make sure all tags are properly closed. The file begins with
the usual XML header followed by a DOCTYPE definition, and then
the tag:
As previously stated, all fonts in /usr/pkg/xorg/lib/X11/fonts/ as
well as ~/.fonts/ are already made available to Xft-aware
applications. If you wish to add another directory outside of
these two directory trees, add a line similar to the following to
/usr/pkg/lib/etc/fonts/local.conf:
/path/to/my/fonts
After adding new fonts, and especially new font directories, you
should run the following command to rebuild the font caches:
# fc-cache -f
Anti-aliasing makes borders slightly fuzzy, which makes very small
text more readable and removes ``staircases'' from large text, but
can cause eyestrain if applied to normal text. To exclude font
sizes smaller than 14 point from anti-aliasing, include these
lines:
14
false
14
false
Spacing for some monospaced fonts may also be inappropriate with
anti-aliasing. This seems to be an issue with KDE, in particular.
One possible fix for this is to force the spacing for such fonts
to be 100. Add the following lines:
fixed
mono
console
mono
(this aliases the other common names for fixed fonts as "mono"),
and then add:
mono
100
Certain fonts, such as Helvetica, may have a problem when
anti-aliased. Usually this manifests itself as a font that seems
cut in half vertically. At worst, it may cause applications such
as Mozilla to crash. To avoid this, consider adding the following
to local.conf:
Helvetica
sans-serif
Once you have finished editing local.conf make sure you end the
file with the tag. Not doing this will cause your
changes to be ignored.
The default font set that comes with X11 is not very desirable
when it comes to anti-aliasing. A much better set of default fonts
can be found in the fonts/vera-ttf port. This port will install a
/usr/pkg/lib/etc/fonts/local.conf file if one does not exist
already. If the file does exist, the port will create a
/usr/pkg/lib/etc/fonts/local.conf-vera file. Merge the contents of
this file into /usr/pkg/lib/etc/fonts/local.conf, and the
Bitstream fonts will automatically replace the default X11 Serif,
Sans Serif, and Monospaced fonts.
Finally, users can add their own settings via their personal
.fonts.conf files. To do this, each user should simply create a
~/.fonts.conf. This file must also be in XML format.
One last point: with an LCD screen, sub-pixel sampling may be
desired. This basically treats the (horizontally separated) red,
green and blue components separately to improve the horizontal
resolution; the results can be dramatic. To enable this, add the
line somewhere in the local.conf file:
unknown
rgb
Note: Depending on the sort of display, rgb may need to be
changed to bgr, vrgb or vbgr: experiment and see which works
best.
Anti-aliasing should be enabled the next time the X server is
started. However, programs must know how to take advantage of it.
At present, the Qt toolkit does, so the entire KDE environment can
use anti-aliased fonts. GTK+ and GNOME can also be made to use
anti-aliasing via the ``Font'' capplet (see Section 5.7.1.3 for
details). By default, Mozilla 1.2 and greater will automatically
use anti-aliasing. To disable this, rebuild Mozilla with the
-DWITHOUT_XFT flag.
--------------------------------------------------------------
5.6 The X Display Manager
Contributed by Seth Kingsley.
5.6.1 Overview
The X Display Manager (XDM) is an optional part of the X Window
System that is used for login session management. This is useful
for several types of situations, including minimal ``X
Terminals'', desktops, and large network display servers. Since
the X Window System is network and protocol independent, there are
a wide variety of possible configurations for running X clients
and servers on different machines connected by a network. XDM
provides a graphical interface for choosing which display server
to connect to, and entering authorization information such as a
login and password combination.
Think of XDM as providing the same functionality to the user as
the getty(8) utility (see Section 17.3.2 for details). That is, it
performs system logins to the display being connected to and then
runs a session manager on behalf of the user (usually an X window
manager). XDM then waits for this program to exit, signaling that
the user is done and should be logged out of the display. At this
point, XDM can display the login and display chooser screens for
the next user to login.
--------------------------------------------------------------
5.6.2 Using XDM
The XDM daemon program is located in /usr/pkg/xorg/bin/xdm. This
program can be run at any time as root and it will start managing
the X display on the local machine. If XDM is to be run every time
the machine boots up, a convenient way to do this is by adding an
entry to /etc/ttys. For more information about the format and
usage of this file, see Section 17.3.2.1. There is a line in the
default /etc/ttys file for running the XDM daemon on a virtual
terminal:
ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
By default this entry is disabled; in order to enable it change
field 5 from off to on and restart init(8) using the directions in
Section 17.3.2.2. The first field, the name of the terminal this
program will manage, is ttyv8. This means that XDM will start
running on the 9th virtual terminal.
--------------------------------------------------------------
5.6.3 Configuring XDM
The XDM configuration directory is located in /var/lib/xdm. The
sample configuration files are in
/usr/pkg/share/examples/xorg/xdm/, in this directory there are
several files used to change the behavior and appearance of XDM.
Typically these files will be found:
File Description
Xaccess Client authorization ruleset.
Xresources Default X resource values.
Xservers List of remote and local displays to manage.
Xsession Default session script for logins.
Xsetup_* Script to launch applications before the login
interface.
xdm-config Global configuration for all displays running on this
machine.
xdm-errors Errors generated by the server program.
xdm-pid The process ID of the currently running XDM.
Also in this directory are a few scripts and programs used to set
up the desktop when XDM is running. The purpose of each of these
files will be briefly described. The exact syntax and usage of all
of these files is described in xdm(1).
The default configuration is a simple rectangular login window
with the hostname of the machine displayed at the top in a large
font and ``Login:'' and ``Password:'' prompts below. This is a
good starting point for changing the look and feel of XDM screens.
--------------------------------------------------------------
5.6.3.1 Xaccess
The protocol for connecting to XDM controlled displays is called
the X Display Manager Connection Protocol (XDMCP). This file is a
ruleset for controlling XDMCP connections from remote machines. It
is ignored unless the xdm-config is changed to listen for remote
connections. By default, it does not allow any clients to connect.
--------------------------------------------------------------
5.6.3.2 Xresources
This is an application-defaults file for the display chooser and
the login screens. This is where the appearance of the login
program can be modified. The format is identical to the
app-defaults file described in the X11 documentation.
--------------------------------------------------------------
5.6.3.3 Xservers
This is a list of the remote displays the chooser should provide
as choices.
--------------------------------------------------------------
5.6.3.4 Xsession
This is the default session script for XDM to run after a user has
logged in. Normally each user will have a customized session
script in ~/.xsession that overrides this script.
--------------------------------------------------------------
5.6.3.5 Xsetup_*
These will be run automatically before displaying the chooser or
login interfaces. There is a script for each display being used,
named Xsetup_ followed by the local display number (for instance
Xsetup_0). Typically these scripts will run one or two programs in
the background such as xconsole.
--------------------------------------------------------------
5.6.3.6 xdm-config
This contains settings in the form of app-defaults that are
applicable to every display that this installation manages.
--------------------------------------------------------------
5.6.3.7 xdm-errors
This contains the output of the X servers that XDM is trying to
run. If a display that XDM is trying to start hangs for some
reason, this is a good place to look for error messages. These
messages are also written to the user's ~/.xsession-errors file on
a per-session basis.
--------------------------------------------------------------
5.6.4 Running a Network Display Server
In order for other clients to connect to the display server, edit
the access control rules, and enable the connection listener. By
default these are set to conservative values. To make XDM listen
for connections, first comment out a line in the xdm-config file:
! SECURITY: do not listen for XDMCP or Chooser requests
! Comment out this line if you want to manage X terminals with xdm
DisplayManager.requestPort: 0
and then restart XDM. Remember that comments in app-defaults files
begin with a ``!'' character, not the usual ``#''. More strict
access controls may be desired. Look at the example entries in
Xaccess, and refer to the xdm(1) manual page.
--------------------------------------------------------------
5.6.5 Replacements for XDM
Several replacements for the default XDM program exist. One of
them, kdm (bundled with KDE) is described later in this chapter.
The kdm display manager offers many visual improvements and
cosmetic frills, as well as the functionality to allow users to
choose their window manager of choice at login time.
--------------------------------------------------------------
5.7 Desktop Environments
Contributed by Valentino Vaschetto.
This section describes the different desktop environments
available for X on FreeBSD. A ``desktop environment'' can mean
anything ranging from a simple window manager to a complete suite
of desktop applications, such as KDE or GNOME.
--------------------------------------------------------------
5.7.1 GNOME
5.7.1.1 About GNOME
GNOME is a user-friendly desktop environment that enables users to
easily use and configure their computers. GNOME includes a panel
(for starting applications and displaying status), a desktop
(where data and applications can be placed), a set of standard
desktop tools and applications, and a set of conventions that make
it easy for applications to cooperate and be consistent with each
other. Users of other operating systems or environments should
feel right at home using the powerful graphics-driven environment
that GNOME provides.
--------------------------------------------------------------
5.7.1.2 Installing GNOME
GNOME can be easily installed from a package or from the pkgsrc
framework:
To install the GNOME package from the network, simply type:
# pkg_add gnome
To build GNOME from source, use the ports tree:
# cd /usr/pkgsrc/meta-pkgs/gnome
# bmake install clean
Once GNOME is installed, the X server must be told to start GNOME
instead of a default window manager.
The easiest way to start GNOME is with GDM, the GNOME Display
Manager. GDM, which is installed as a part of the GNOME desktop
(but is disabled by default), can be enabled by adding
gdm_enable="YES" to /etc/rc.conf. Once you have rebooted, GNOME
will start automatically once you log in -- no further
configuration is necessary.
GNOME may also be started from the command-line by properly
configuring a file named .xinitrc. If a custom .xinitrc is already
in place, simply replace the line that starts the current window
manager with one that starts /usr/pkg/bin/gnome-session instead.
If nothing special has been done to the configuration file, then
it is enough simply to type:
% echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
Next, type startx, and the GNOME desktop environment will be
started.
Note: If an older display manager, like XDM, is being used, this
will not work. Instead, create an executable .xsession file with
the same command in it. To do this, edit the file and replace
the existing window manager command with
/usr/pkg/bin/gnome-session:
% echo "#!/bin/sh" > ~/.xsession
% echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
% chmod +x ~/.xsession
Yet another option is to configure the display manager to allow
choosing the window manager at login time; the section on KDE
details explains how to do this for kdm, the display manager of
KDE.
--------------------------------------------------------------
5.7.1.3 Anti-aliased Fonts with GNOME
X11 supports anti-aliasing via its ``RENDER'' extension. GTK+ 2.0
and greater (the toolkit used by GNOME) can make use of this
functionality. Configuring anti-aliasing is described in Section
5.5.3. So, with up-to-date software, anti-aliasing is possible
within the GNOME desktop. Just go to Applications->Desktop
Preferences->Font, and select either Best shapes, Best contrast,
or Subpixel smoothing (LCDs). For a GTK+ application that is not
part of the GNOME desktop, set the environment variable
GDK_USE_XFT to 1 before launching the program.
--------------------------------------------------------------
5.7.2 KDE
--------------------------------------------------------------
5.7.2.1 About KDE
KDE is an easy to use contemporary desktop environment. Some of
the things that KDE brings to the user are:
* A beautiful contemporary desktop
* A desktop exhibiting complete network transparency
* An integrated help system allowing for convenient, consistent
access to help on the use of the KDE desktop and its
applications
* Consistent look and feel of all KDE applications
* Standardized menu and toolbars, keybindings, color-schemes,
etc.
* Internationalization: KDE is available in more than 40
languages
* Centralized consisted dialog driven desktop configuration
* A great number of useful KDE applications
KDE comes with a web browser called Konqueror, which represents a
solid competitor to other existing web browsers on UNIX systems.
More information on KDE can be found on the KDE website.
--------------------------------------------------------------
5.7.2.2 Installing KDE
Just as with GNOME or any other desktop environment, the easiest
way to install KDE is through the pkgsrc framework or from a
package:
To install the KDE package from the network, simply type:
# pkg_add kde
pkg_add(1) will automatically fetch the latest version of the
application.
To build KDE from source, use the ports tree:
# cd /usr/pkgsrc/meta-pkgs/kde3
# bmake install clean
After KDE has been installed, the X server must be told to launch
this application instead of the default window manager. This is
accomplished by editing the .xinitrc file:
% echo "exec startkde" > ~/.xinitrc
Now, whenever the X Window System is invoked with startx, KDE will
be the desktop.
If a display manager such as XDM is being used, the configuration
is slightly different. Edit the .xsession file instead.
Instructions for kdm are described later in this chapter.
--------------------------------------------------------------
5.7.3 More Details on KDE
Now that KDE is installed on the system, most things can be
discovered through the help pages, or just by pointing and
clicking at various menus. Windows or Mac(R) users will feel quite
at home.
The best reference for KDE is the on-line documentation. KDE comes
with its own web browser, Konqueror, dozens of useful
applications, and extensive documentation. The remainder of this
section discusses the technical items that are difficult to learn
by random exploration.
--------------------------------------------------------------
5.7.3.1 The KDE Display Manager
An administrator of a multi-user system may wish to have a
graphical login screen to welcome users. XDM can be used, as
described earlier. However, KDE includes an alternative, kdm,
which is designed to look more attractive and include more
login-time options. In particular, users can easily choose (via a
menu) which desktop environment (KDE, GNOME, or something else) to
run after logging on.
To enable kdm, the ttyv8 entry in /etc/ttys has to be adapted. The
line should look as follows:
ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
--------------------------------------------------------------
5.7.4 XFce
5.7.4.1 About XFce
XFce is a desktop environment based on the GTK+ toolkit used by
GNOME, but is much more lightweight and meant for those who want a
simple, efficient desktop which is nevertheless easy to use and
configure. Visually, it looks very much like CDE, found on
commercial UNIX systems. Some of XFce's features are:
* A simple, easy-to-handle desktop
* Fully configurable via mouse, with drag and drop, etc
* Main panel similar to CDE, with menus, applets and
applications launchers
* Integrated window manager, file manager, sound manager, GNOME
compliance module, and other things
* Themeable (since it uses GTK+)
* Fast, light and efficient: ideal for older/slower machines or
machines with memory limitations
More information on XFce can be found on the XFce website.
--------------------------------------------------------------
5.7.4.2 Installing XFce
A binary package for XFce exists (at the time of writing). To
install, simply type:
# pkg_add -r xfce4
Alternatively, to build from source, use the pkgsrc framework:
# cd /usr/pkgsrc/meta-pkgs/xfce4
# make install clean
Now, tell the X server to launch XFce the next time X is started.
Simply type this:
% echo "/usr/pkgsrc/bin/startxfce4" > ~/.xinitrc
The next time X is started, XFce will be the desktop. As before,
if a display manager like XDM is being used, create an .xsession,
as described in the section on GNOME, but with the
/usr/pkg/bin/startxfce4 command; or, configure the display manager
to allow choosing a desktop at login time, as explained in the
section on kdm.
II. System Administration
The remaining chapters of the DragonFly Handbook cover all aspects
of DragonFly system administration. Each chapter starts by
describing what you will learn as a result of reading the chapter,
and also details what you are expected to know before tackling the
material.
These chapters are designed to be read when you need the
information. You do not have to read them in any particular order,
nor do you need to read all of them before you can begin using
DragonFly.
Table of Contents
6 Configuration and Tuning
7 The DragonFly Booting Process
8 Users and Basic Account Management
9 Configuring the DragonFly Kernel
10 Security
11 Printing
12 Storage
13 The Vinum Volume Manager
14 Localization - I18N/L10N Usage and Setup
15 Desktop Applications
16 Multimedia
17 Serial Communications
18 PPP and SLIP
19 Advanced Networking
20 Electronic Mail
21 Updating DragonFly
22 Linux Binary Compatibility
--------------------------------------------------------------
Chapter 6 Configuration and Tuning
Written by Chern Lee. Based on a tutorial written by Mike Smith.
Also based on tuning(7) written by Matt Dillon.
6.1 Synopsis
One of the important aspects of DragonFly is system configuration.
Correct system configuration will help prevent headaches during
future upgrades. This chapter will explain much of the DragonFly
configuration process, including some of the parameters which can
be set to tune a DragonFly system.
After reading this chapter, you will know:
* How to efficiently work with file systems and swap partitions.
* The basics of rc.conf configuration and rc.d startup systems.
* How to configure and test a network card.
* How to configure virtual hosts on your network devices.
* How to use the various configuration files in /etc.
* How to tune DragonFly using sysctl variables.
* How to tune disk performance and modify kernel limitations.
Before reading this chapter, you should:
* Understand UNIX and DragonFly basics (Chapter 3).
* Be familiar with the basics of kernel
configuration/compilation (Chapter 9).
--------------------------------------------------------------
6.2 Initial Configuration
6.2.1 Partition Layout
--------------------------------------------------------------
6.2.1.1 Base Partitions
When laying out file systems with disklabel(8) remember that hard
drives transfer data faster from the outer tracks to the inner.
Thus smaller and heavier-accessed file systems should be closer to
the outside of the drive, while larger partitions like /usr should
be placed toward the inner. It is a good idea to create partitions
in a similar order to: root, swap, /var, /usr.
The size of /var reflects the intended machine usage. /var is used
to hold mailboxes, log files, and printer spools. Mailboxes and
log files can grow to unexpected sizes depending on how many users
exist and how long log files are kept. Most users would never
require a gigabyte, but remember that /var/tmp must be large
enough to contain packages.
The /usr partition holds much of the files required to support the
system, the pkgsrc collection (recommended) and the source code
(optional). At least 2 gigabytes would be recommended for this
partition.
When selecting partition sizes, keep the space requirements in
mind. Running out of space in one partition while barely using
another can be a hassle.
--------------------------------------------------------------
6.2.1.2 Swap Partition
As a rule of thumb, the swap partition should be about double the
size of system memory (RAM). For example, if the machine has
128 megabytes of memory, the swap file should be 256 megabytes.
Systems with less memory may perform better with more swap. Less
than 256 megabytes of swap is not recommended and memory expansion
should be considered. The kernel's VM paging algorithms are tuned
to perform best when the swap partition is at least two times the
size of main memory. Configuring too little swap can lead to
inefficiencies in the VM page scanning code and might create
issues later if more memory is added.
On larger systems with multiple SCSI disks (or multiple IDE disks
operating on different controllers), it is recommend that a swap
is configured on each drive (up to four drives). The swap
partitions should be approximately the same size. The kernel can
handle arbitrary sizes but internal data structures scale to 4
times the largest swap partition. Keeping the swap partitions near
the same size will allow the kernel to optimally stripe swap space
across disks. Large swap sizes are fine, even if swap is not used
much. It might be easier to recover from a runaway program before
being forced to reboot.
--------------------------------------------------------------
6.2.1.3 Why Partition?
Several users think a single large partition will be fine, but
there are several reasons why this is a bad idea. First, each
partition has different operational characteristics and separating
them allows the file system to tune accordingly. For example, the
root and /usr partitions are read-mostly, without much writing.
While a lot of reading and writing could occur in /var and
/var/tmp.
By properly partitioning a system, fragmentation introduced in the
smaller write heavy partitions will not bleed over into the
mostly-read partitions. Keeping the write-loaded partitions closer
to the disk's edge, will increase I/O performance in the
partitions where it occurs the most. Now while I/O performance in
the larger partitions may be needed, shifting them more toward the
edge of the disk will not lead to a significant performance
improvement over moving /var to the edge. Finally, there are
safety concerns. A smaller, neater root partition which is mostly
read-only has a greater chance of surviving a bad crash.
--------------------------------------------------------------
6.3 Core Configuration
The principal location for system configuration information is
within /etc/rc.conf. This file contains a wide range of
configuration information, principally used at system startup to
configure the system. Its name directly implies this; it is
configuration information for the rc* files.
An administrator should make entries in the rc.conf file to
override the default settings from /etc/defaults/rc.conf. The
defaults file should not be copied verbatim to /etc - it contains
default values, not examples. All system-specific changes should
be made in the rc.conf file itself.
A number of strategies may be applied in clustered applications to
separate site-wide configuration from system-specific
configuration in order to keep administration overhead down. The
recommended approach is to place site-wide configuration into
another file, such as /etc/rc.conf.site, and then include this
file into /etc/rc.conf, which will contain only system-specific
information.
As rc.conf is read by sh(1) it is trivial to achieve this. For
example:
* rc.conf:
. rc.conf.site
hostname="node15.example.com"
network_interfaces="fxp0 lo0"
ifconfig_fxp0="inet 10.1.1.1"
* rc.conf.site:
defaultrouter="10.1.1.254"
saver="daemon"
blanktime="100"
The rc.conf.site file can then be distributed to every system
using rsync or a similar program, while the rc.conf file remains
unique.
Upgrading the system using make world will not overwrite the
rc.conf file, so system configuration information will not be
lost.
--------------------------------------------------------------
6.4 Application Configuration
Typically, installed applications have their own configuration
files, with their own syntax, etc. It is important that these
files be kept separate from the base system, so that they may be
easily located and managed by the package management tools.
Typically, these files are installed in /usr/local/etc. In the
case where an application has a large number of configuration
files, a subdirectory will be created to hold them.
Normally, when a port or package is installed, sample
configuration files are also installed. These are usually
identified with a .default suffix. If there are no existing
configuration files for the application, they will be created by
copying the .default files.
For example, consider the contents of the directory
/usr/local/etc/apache:
-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf
-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default
-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf
-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default
-rw-r--r-- 1 root wheel 12205 May 20 1998 magic
-rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default
-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types
-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default
-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default
The file sizes show that only the srm.conf file has been changed.
A later update of the Apache port would not overwrite this changed
file.
--------------------------------------------------------------
6.5 Starting Services
It is common for a system to host a number of services. These may
be started in several different fashions, each having different
advantages.
Software installed from a port or the packages collection will
often place a script in /usr/local/etc/rc.d which is invoked at
system startup with a start argument, and at system shutdown with
a stop argument. This is the recommended way for starting
system-wide services that are to be run as root, or that expect to
be started as root. These scripts are registered as part of the
installation of the package, and will be removed when the package
is removed.
A generic startup script in /usr/local/etc/rc.d looks like:
#!/bin/sh
echo -n ' FooBar'
case "$1" in
start)
/usr/local/bin/foobar
;;
stop)
kill -9 `cat /var/run/foobar.pid`
;;
*)
echo "Usage: `basename $0` {start|stop}" >&2
exit 64
;;
esac
exit 0
The startup scripts of DragonFly will look in /usr/local/etc/rc.d
for scripts that have an .sh extension and are executable by root.
Those scripts that are found are called with an option start at
startup, and stop at shutdown to allow them to carry out their
purpose. So if you wanted the above sample script to be picked up
and run at the proper time during system startup, you should save
it to a file called FooBar.sh in /usr/local/etc/rc.d and make sure
it is executable. You can make a shell script executable with
chmod(1) as shown below:
# chmod 755 FooBar.sh
Some services expect to be invoked by inetd(8) when a connection
is received on a suitable port. This is common for mail reader
servers (POP and IMAP, etc.). These services are enabled by
editing the file /etc/inetd.conf. See inetd(8) for details on
editing this file.
Some additional system services may not be covered by the toggles
in /etc/rc.conf. These are traditionally enabled by placing the
command(s) to invoke them in /etc/rc.local (which does not exist
by default). Note that rc.local is generally regarded as the
location of last resort; if there is a better place to start a
service, do it there.
Note: Do not place any commands in /etc/rc.conf. To start
daemons, or run any commands at boot time, place a script in
/usr/local/etc/rc.d instead.
It is also possible to use the cron(8) daemon to start system
services. This approach has a number of advantages, not least
being that because cron(8) runs these processes as the owner of
the crontab, services may be started and maintained by non-root
users.
This takes advantage of a feature of cron(8): the time
specification may be replaced by @reboot, which will cause the job
to be run when cron(8) is started shortly after system boot.
--------------------------------------------------------------
6.6 Configuring the cron Utility
Contributed by Tom Rhodes.
One of the most useful utilities in DragonFly is cron(8). The cron
utility runs in the background and constantly checks the
/etc/crontab file. The cron utility also checks the /var/cron/tabs
directory, in search of new crontab files. These crontab files
store information about specific functions which cron is supposed
to perform at certain times.
The cron utility uses two different types of configuration files,
the system crontab and user crontabs. The only difference between
these two formats is the sixth field. In the system crontab, the
sixth field is the name of a user for the command to run as. This
gives the system crontab the ability to run commands as any user.
In a user crontab, the sixth field is the command to run, and all
commands run as the user who created the crontab; this is an
important security feature.
Note: User crontabs allow individual users to schedule tasks
without the need for root privileges. Commands in a user's
crontab run with the permissions of the user who owns the
crontab.
The root user can have a user crontab just like any other user.
This one is different from /etc/crontab (the system crontab).
Because of the system crontab, there's usually no need to create
a user crontab for root.
Let us take a look at the /etc/crontab file (the system crontab):
# /etc/crontab - root's crontab for DragonFly
#
# (1)
#
SHELL=/bin/sh
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin (2)
HOME=/var/log
#
#
#minute hour mday month wday who command (3)
#
#
*/5 * * * * root /usr/libexec/atrun (4)
(1)
Like most DragonFly configuration files, the # character
represents a comment. A comment can be placed in the file
as a reminder of what and why a desired action is
performed. Comments cannot be on the same line as a
command or else they will be interpreted as part of the
command; they must be on a new line. Blank lines are
ignored.
(2)
First, the environment must be defined. The equals (=)
character is used to define any environment settings, as
with this example where it is used for the SHELL, PATH,
and HOME options. If the shell line is omitted, cron will
use the default, which is sh. If the PATH variable is
omitted, no default will be used and file locations will
need to be absolute. If HOME is omitted, cron will use the
invoking users home directory.
(3)
This line defines a total of seven fields. Listed here are
the values minute, hour, mday, month, wday, who, and
command. These are almost all self explanatory. minute is
the time in minutes the command will be run. hour is
similar to the minute option, just in hours. mday stands
for day of the month. month is similar to hour and minute,
as it designates the month. The wday option stands for day
of the week. All these fields must be numeric values, and
follow the twenty-four hour clock. The who field is
special, and only exists in the /etc/crontab file. This
field specifies which user the command should be run as.
When a user installs his or her crontab file, they will
not have this option. Finally, the command option is
listed. This is the last field, so naturally it should
designate the command to be executed.
(4)
This last line will define the values discussed above.
Notice here we have a */5 listing, followed by several
more * characters. These * characters mean ``first-last'',
and can be interpreted as every time. So, judging by this
line, it is apparent that the atrun command is to be
invoked by root every five minutes regardless of what day
or month it is. For more information on the atrun command,
see the atrun(8) manual page.
Commands can have any number of flags passed to them;
however, commands which extend to multiple lines need to
be broken with the backslash ``\'' continuation character.
This is the basic set up for every crontab file, although there is
one thing different about this one. Field number six, where we
specified the username, only exists in the system /etc/crontab
file. This field should be omitted for individual user crontab
files.
--------------------------------------------------------------
6.6.1 Installing a Crontab
Important: You must not use the procedure described here to
edit/install the system crontab. Simply use your favorite
editor: the cron utility will notice that the file has changed
and immediately begin using the updated version. If you use
crontab to load the /etc/crontab file you may get an error like
``root: not found'' because of the system crontab's additional
user field.
To install a freshly written user crontab, first use your favorite
editor to create a file in the proper format, and then use the
crontab utility. The most common usage is:
% crontab crontab-file
In this example, crontab-file is the filename of a crontab that
was previously created.
There is also an option to list installed crontab files: just pass
the -l option to crontab and look over the output.
For users who wish to begin their own crontab file from scratch,
without the use of a template, the crontab -e option is available.
This will invoke the selected editor with an empty file. When the
file is saved, it will be automatically installed by the crontab
command.
If you later want to remove your user crontab completely, use
crontab with the -r option.
--------------------------------------------------------------
6.7 Using rc under DragonFly
Contributed by Tom Rhodes.
DragonFly uses the NetBSD rc.d system for system initialization.
Users should notice the files listed in the /etc/rc.d directory.
Many of these files are for basic services which can be controlled
with the start, stop, and restart options. For instance, sshd(8)
can be restarted with the following command:
# /etc/rc.d/sshd restart
This procedure is similar for other services. Of course, services
are usually started automatically as specified in rc.conf(5). For
example, enabling the Network Address Translation daemon at
startup is as simple as adding the following line to /etc/rc.conf:
natd_enable="YES"
If a natd_enable="NO" line is already present, then simply change
the NO to YES. The rc scripts will automatically load any other
dependent services during the next reboot, as described below.
Since the rc.d system is primarily intended to start/stop services
at system startup/shutdown time, the standard start, stop and
restart options will only perform their action if the appropriate
/etc/rc.conf variables are set. For instance the above sshd
restart command will only work if sshd_enable is set to YES in
/etc/rc.conf. To start, stop or restart a service regardless of
the settings in /etc/rc.conf, the commands should be prefixed with
``force''. For instance to restart sshd regardless of the current
/etc/rc.conf setting, execute the following command:
# /etc/rc.d/sshd forcerestart
It is easy to check if a service is enabled in /etc/rc.conf by
running the appropriate rc.d script with the option rcvar. Thus,
an administrator can check that sshd is in fact enabled in
/etc/rc.conf by running:
# /etc/rc.d/sshd rcvar
# sshd
$sshd_enable=YES
Note: The second line (# sshd) is the output from the rc.d
script, not a root prompt.
To determine if a service is running, a status option is
available. For instance to verify that sshd is actually started:
# /etc/rc.d/sshd status
sshd is running as pid 433.
It is also possible to reload a service. This will attempt to send
a signal to an individual service, forcing the service to reload
its configuration files. In most cases this means sending the
service a SIGHUP signal.
The rcNG structure is used both for network services and system
initialization. Some services are run only at boot; and the RCNG
system is what triggers them.
Many system services depend on other services to function
properly. For example, NIS and other RPC-based services may fail
to start until after the rpcbind (portmapper) service has started.
To resolve this issue, information about dependencies and other
meta-data is included in the comments at the top of each startup
script. The rcorder(8) program is then used to parse these
comments during system initialization to determine the order in
which system services should be invoked to satisfy the
dependencies. The following words may be included at the top of
each startup file:
* PROVIDE: Specifies the services this file provides.
* REQUIRE: Lists services which are required for this service.
This file will run after the specified services.
* BEFORE: Lists services which depend on this service. This file
will run before the specified services.
* KEYWORD: When rcorder(8) uses the -k option, then only the
rc.d files matching this keyword are used. [5] For example,
when using -k shutdown, only the rc.d scripts defining the
shutdown keyword are used.
With the -s option, rcorder(8) will skip any rc.d script
defining the corresponding keyword to skip. For example,
scripts defining the nostart keyword are skipped at boot time.
By using this method, an administrator can easily control system
services without the hassle of ``runlevels'' like some other UNIX
operating systems.
Additional information about the DragonFly rc.d system can be
found in the rc(8), rc.conf(5), and rc.subr(8) manual pages.
--------------------------------------------------------------
6.8 Setting Up Network Interface Cards
Contributed by Marc Fonvieille.
Nowadays we can not think about a computer without thinking about
a network connection. Adding and configuring a network card is a
common task for any DragonFly administrator.
--------------------------------------------------------------
6.8.1 Locating the Correct Driver
Before you begin, you should know the model of the card you have,
the chip it uses, and whether it is a PCI or ISA card. DragonFly
supports a wide variety of both PCI and ISA cards. Check the
Hardware Compatibility List for your release to see if your card
is supported.
Once you are sure your card is supported, you need to determine
the proper driver for the card. The file
/usr/src/sys/i386/conf/LINT will give you the list of network
interfaces drivers with some information about the supported
chipsets/cards. If you have doubts about which driver is the
correct one, read the manual page of the driver. The manual page
will give you more information about the supported hardware and
even the possible problems that could occur.
If you own a common card, most of the time you will not have to
look very hard for a driver. Drivers for common network cards are
present in the GENERIC kernel, so your card should show up during
boot, like so:
dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
000ff irq 15 at device 11.0 on pci0
dc0: Ethernet address: 00:a0:cc:da:da:da
miibus0: on dc0
ukphy0: on miibus0
ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
000ff irq 11 at device 12.0 on pci0
dc1: Ethernet address: 00:a0:cc:da:da:db
miibus1: on dc1
ukphy1: on miibus1
ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
In this example, we see that two cards using the dc(4) driver are
present on the system.
To use your network card, you will need to load the proper driver.
This may be accomplished in one of two ways. The easiest way is to
simply load a kernel module for your network card with kldload(8).
A module is not available for all network card drivers (ISA cards
and cards using the ed(4) driver, for example). Alternatively, you
may statically compile the support for your card into your kernel.
Check /usr/src/sys/i386/conf/LINT and the manual page of the
driver to know what to add in your kernel configuration file. For
more information about recompiling your kernel, please see Chapter
9. If your card was detected at boot by your kernel (GENERIC) you
do not have to build a new kernel.
--------------------------------------------------------------
6.8.2 Configuring the Network Card
Once the right driver is loaded for the network card, the card
needs to be configured. As with many other things, the network
card may have been configured at installation time.
To display the configuration for the network interfaces on your
system, enter the following command:
% ifconfig
dc0: flags=8843 mtu 1500
inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
ether 00:a0:cc:da:da:da
media: Ethernet autoselect (100baseTX )
status: active
dc1: flags=8843 mtu 1500
inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
ether 00:a0:cc:da:da:db
media: Ethernet 10baseT/UTP
status: no carrier
lp0: flags=8810 mtu 1500
lo0: flags=8049 mtu 16384
inet 127.0.0.1 netmask 0xff000000
tun0: flags=8010 mtu 1500
Note: Note that entries concerning IPv6 (inet6 etc.) were
omitted in this example.
In this example, the following devices were displayed:
* dc0: The first Ethernet interface
* dc1: The second Ethernet interface
* lp0: The parallel port interface
* lo0: The loopback device
* tun0: The tunnel device used by ppp
DragonFly uses the driver name followed by the order in which one
the card is detected at the kernel boot to name the network card,
starting the count at zero. For example, sis2 would be the third
network card on the system using the sis(4) driver.
In this example, the dc0 device is up and running. The key
indicators are:
1. UP means that the card is configured and ready.
2. The card has an Internet (inet) address (in this case
192.168.1.3).
3. It has a valid subnet mask (netmask; 0xffffff00 is the same as
255.255.255.0).
4. It has a valid broadcast address (in this case,
192.168.1.255).
5. The MAC address of the card (ether) is 00:a0:cc:da:da:da
6. The physical media selection is on autoselection mode (media:
Ethernet autoselect (100baseTX )). We see that
dc1 was configured to run with 10baseT/UTP media. For more
information on available media types for a driver, please
refer to its manual page.
7. The status of the link (status) is active, i.e. the carrier is
detected. For dc1, we see status: no carrier. This is normal
when an Ethernet cable is not plugged into the card.
If the ifconfig(8) output had shown something similar to:
dc0: flags=8843 mtu 1500
ether 00:a0:cc:da:da:da
it would indicate the card has not been configured.
To configure your card, you need root privileges. The network card
configuration can be done from the command line with ifconfig(8)
as root.
# ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
Manually configuring the care has the disadvantage that you would
have to do it after each reboot of the system. The file
/etc/rc.conf is where to add the network card's configuration.
Open /etc/rc.conf in your favorite editor. You need to add a line
for each network card present on the system, for example in our
case, we added these lines:
ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
You have to replace dc0, dc1, and so on, with the correct device
for your cards, and the addresses with the proper ones. You should
read the card driver and ifconfig(8) manual pages for more details
about the allowed options and also rc.conf(5) manual page for more
information on the syntax of /etc/rc.conf.
If you configured the network during installation, some lines
about the network card(s) may be already present. Double check
/etc/rc.conf before adding any lines.
You will also have to edit the file /etc/hosts to add the names
and the IP addresses of various machines of the LAN, if they are
not already there. For more information please refer to hosts(5)
and to /usr/share/examples/etc/hosts.
--------------------------------------------------------------
6.8.3 Testing and Troubleshooting
Once you have made the necessary changes in /etc/rc.conf, you
should reboot your system. This will allow the change(s) to the
interface(s) to be applied, and verify that the system restarts
without any configuration errors.
Once the system has been rebooted, you should test the network
interfaces.
--------------------------------------------------------------
6.8.3.1 Testing the Ethernet Card
To verify that an Ethernet card is configured correctly, you have
to try two things. First, ping the interface itself, and then ping
another machine on the LAN.
First test the local interface:
% ping -c5 192.168.1.3
PING 192.168.1.3 (192.168.1.3): 56 data bytes
64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
--- 192.168.1.3 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
Now we have to ping another machine on the LAN:
% ping -c5 192.168.1.2
PING 192.168.1.2 (192.168.1.2): 56 data bytes
64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
--- 192.168.1.2 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
You could also use the machine name instead of 192.168.1.2 if you
have set up the /etc/hosts file.
--------------------------------------------------------------
6.8.3.2 Troubleshooting
Troubleshooting hardware and software configurations is always a
pain, and a pain which can be alleviated by checking the simple
things first. Is your network cable plugged in? Have you properly
configured the network services? Did you configure the firewall
correctly? Is the card you are using supported by DragonFly?
Always check the hardware notes before sending off a bug report.
Update your version of DragonFly to the latest PREVIEW version.
Check the mailing list archives, or perhaps search the Internet.
If the card works, yet performance is poor, it would be worthwhile
to read over the tuning(7) manual page. You can also check the
network configuration as incorrect network settings can cause slow
connections.
Some users experience one or two ``device timeouts'', which is
normal for some cards. If they continue, or are bothersome, you
may wish to be sure the device is not conflicting with another
device. Double check the cable connections. Perhaps you may just
need to get another card.
At times, users see a few ``watchdog timeout'' errors. The first
thing to do here is to check your network cable. Many cards
require a PCI slot which supports Bus Mastering. On some old
motherboards, only one PCI slot allows it (usually slot 0). Check
the network card and the motherboard documentation to determine if
that may be the problem.
``No route to host'' messages occur if the system is unable to
route a packet to the destination host. This can happen if no
default route is specified, or if a cable is unplugged. Check the
output of netstat -rn and make sure there is a valid route to the
host you are trying to reach. If there is not, read on to Chapter
19.
``ping: sendto: Permission denied'' error messages are often
caused by a misconfigured firewall. If ipfw is enabled in the
kernel but no rules have been defined, then the default policy is
to deny all traffic, even ping requests! Read on to Section 10.7
for more information.
Sometimes performance of the card is poor, or below average. In
these cases it is best to set the media selection mode from
autoselect to the correct media selection. While this usually
works for most hardware, it may not resolve this issue for
everyone. Again, check all the network settings, and read over the
tuning(7) manual page.
--------------------------------------------------------------
6.9 Virtual Hosts
A very common use of DragonFly is virtual site hosting, where one
server appears to the network as many servers. This is achieved by
assigning multiple network addresses to a single interface.
A given network interface has one ``real'' address, and may have
any number of ``alias'' addresses. These aliases are normally
added by placing alias entries in /etc/rc.conf.
An alias entry for the interface fxp0 looks like:
ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
Note that alias entries must start with alias0 and proceed upwards
in order, (for example, _alias1, _alias2, and so on). The
configuration process will stop at the first missing number.
The calculation of alias netmasks is important, but fortunately
quite simple. For a given interface, there must be one address
which correctly represents the network's netmask. Any other
addresses which fall within this network must have a netmask of
all 1s (expressed as either 255.255.255.255 or 0xffffffff).
For example, consider the case where the fxp0 interface is
connected to two networks, the 10.1.1.0 network with a netmask of
255.255.255.0 and the 202.0.75.16 network with a netmask of
255.255.255.240. We want the system to appear at 10.1.1.1 through
10.1.1.5 and at 202.0.75.17 through 202.0.75.20. As noted above,
only the first address in a given network range (in this case,
10.0.1.1 and 202.0.75.17) should have a real netmask; all the rest
(10.1.1.2 through 10.1.1.5 and 202.0.75.18 through 202.0.75.20)
must be configured with a netmask of 255.255.255.255.
The following entries configure the adapter correctly for this
arrangement:
ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
--------------------------------------------------------------
6.10 Configuration Files
6.10.1 /etc Layout
There are a number of directories in which configuration
information is kept. These include:
/etc Generic system configuration information; data
here is system-specific.
/etc/defaults Default versions of system configuration
files.
/etc/mail Extra sendmail(8) configuration, other MTA
configuration files.
/etc/ppp Configuration for both user- and kernel-ppp
programs.
/etc/namedb Default location for named(8) data. Normally
named.conf and zone files are stored here.
Configuration files for installed
/usr/local/etc applications. May contain per-application
subdirectories.
/usr/local/etc/rc.d Start/stop scripts for installed applications.
Automatically generated system-specific
/var/db database files, such as the package database,
the locate database, and so on
--------------------------------------------------------------
6.10.2 Hostnames
--------------------------------------------------------------
6.10.2.1 /etc/resolv.conf
/etc/resolv.conf dictates how DragonFly's resolver accesses the
Internet Domain Name System (DNS).
The most common entries to resolv.conf are:
The IP address of a name server the resolver should
nameserver query. The servers are queried in the order listed with
a maximum of three.
search Search list for hostname lookup. This is normally
determined by the domain of the local hostname.
domain The local domain name.
A typical resolv.conf:
search example.com
nameserver 147.11.1.11
nameserver 147.11.100.30
Note: Only one of the search and domain options should be used.
If you are using DHCP, dhclient(8) usually rewrites resolv.conf
with information received from the DHCP server.
--------------------------------------------------------------
6.10.2.2 /etc/hosts
/etc/hosts is a simple text database reminiscent of the old
Internet. It works in conjunction with DNS and NIS providing name
to IP address mappings. Local computers connected via a LAN can be
placed in here for simplistic naming purposes instead of setting
up a named(8) server. Additionally, /etc/hosts can be used to
provide a local record of Internet names, reducing the need to
query externally for commonly accessed names.
#
#
# Host Database
# This file should contain the addresses and aliases
# for local hosts that share this file.
# In the presence of the domain name service or NIS, this file may
# not be consulted at all; see /etc/nsswitch.conf for the resolution order.
#
#
::1 localhost localhost.my.domain myname.my.domain
127.0.0.1 localhost localhost.my.domain myname.my.domain
#
# Imaginary network.
#10.0.0.2 myname.my.domain myname
#10.0.0.3 myfriend.my.domain myfriend
#
# According to RFC 1918, you can use the following IP networks for
# private nets which will never be connected to the Internet:
#
# 10.0.0.0 - 10.255.255.255
# 172.16.0.0 - 172.31.255.255
# 192.168.0.0 - 192.168.255.255
#
# In case you want to be able to connect to the Internet, you need
# real official assigned numbers. PLEASE PLEASE PLEASE do not try
# to invent your own network numbers but instead get one from your
# network provider (if any) or from the Internet Registry (ftp to
# rs.internic.net, directory `/templates').
#
/etc/hosts takes on the simple format of:
[Internet address] [official hostname] [alias1] [alias2] ...
For example:
10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
Consult hosts(5) for more information.
--------------------------------------------------------------
6.10.3 Log File Configuration
--------------------------------------------------------------
6.10.3.1 syslog.conf
syslog.conf is the configuration file for the syslogd(8) program.
It indicates which types of syslog messages are logged to
particular log files.
#
#
# Spaces ARE valid field separators in this file. However,
# other *nix-like systems still insist on using tabs as field
# separators. If you are sharing this file between systems, you
# may want to use only tabs as field separators here.
# Consult the syslog.conf(5) manual page.
*.err;kern.debug;auth.notice;mail.crit /dev/console
*.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
security.* /var/log/security
mail.info /var/log/maillog
lpr.info /var/log/lpd-errs
cron.* /var/log/cron
*.err root
*.notice;news.err root
*.alert root
*.emerg *
# uncomment this to log all writes to /dev/console to /var/log/console.log
#console.info /var/log/console.log
# uncomment this to enable logging of all log messages to /var/log/all.log
#*.* /var/log/all.log
# uncomment this to enable logging to a remote log host named loghost
#*.* @loghost
# uncomment these if you're running inn
# news.crit /var/log/news/news.crit
# news.err /var/log/news/news.err
# news.notice /var/log/news/news.notice
!startslip
*.* /var/log/slip.log
!ppp
*.* /var/log/ppp.log
Consult the syslog.conf(5) manual page for more information.
--------------------------------------------------------------
6.10.3.2 newsyslog.conf
newsyslog.conf is the configuration file for newsyslog(8), a
program that is normally scheduled to run by cron(8). newsyslog(8)
determines when log files require archiving or rearranging.
logfile is moved to logfile.0, logfile.0 is moved to logfile.1,
and so on. Alternatively, the log files may be archived in gzip(1)
format causing them to be named: logfile.0.gz, logfile.1.gz, and
so on.
newsyslog.conf indicates which log files are to be managed, how
many are to be kept, and when they are to be touched. Log files
can be rearranged and/or archived when they have either reached a
certain size, or at a certain periodic time/date.
# configuration file for newsyslog
#
#
# filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
/var/log/cron 600 3 100 * Z
/var/log/amd.log 644 7 100 * Z
/var/log/kerberos.log 644 7 100 * Z
/var/log/lpd-errs 644 7 100 * Z
/var/log/maillog 644 7 * @T00 Z
/var/log/sendmail.st 644 10 * 168 B
/var/log/messages 644 5 100 * Z
/var/log/all.log 600 7 * @T00 Z
/var/log/slip.log 600 3 100 * Z
/var/log/ppp.log 600 3 100 * Z
/var/log/security 600 10 100 * Z
/var/log/wtmp 644 3 * @01T05 B
/var/log/daily.log 640 7 * @T00 Z
/var/log/weekly.log 640 5 1 $W6D0 Z
/var/log/monthly.log 640 12 * $M1D0 Z
/var/log/console.log 640 5 100 * Z
Consult the newsyslog(8) manual page for more information.
--------------------------------------------------------------
6.10.4 sysctl.conf
sysctl.conf looks much like rc.conf. Values are set in a
variable=value form. The specified values are set after the system
goes into multi-user mode. Not all variables are settable in this
mode.
A sample sysctl.conf turning off logging of fatal signal exits and
letting Linux programs know they are really running under
DragonFly:
kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
compat.linux.osname=DragonFly
compat.linux.osrelease=4.3-STABLE
--------------------------------------------------------------
6.11 Tuning with sysctl
sysctl(8) is an interface that allows you to make changes to a
running DragonFly system. This includes many advanced options of
the TCP/IP stack and virtual memory system that can dramatically
improve performance for an experienced system administrator. Over
five hundred system variables can be read and set using sysctl(8).
At its core, sysctl(8) serves two functions: to read and to modify
system settings.
To view all readable variables:
% sysctl -a
To read a particular variable, for example, kern.maxproc:
% sysctl kern.maxproc
kern.maxproc: 1044
To set a particular variable, use the intuitive variable=value
syntax:
# sysctl kern.maxfiles=5000
kern.maxfiles: 2088 -> 5000
Settings of sysctl variables are usually either strings, numbers,
or booleans (a boolean being 1 for yes or a 0 for no).
If you want to set automatically some variables each time the
machine boots, add them to the /etc/sysctl.conf file. For more
information see the sysctl.conf(5) manual page and the Section
6.10.4.
--------------------------------------------------------------
6.11.1 sysctl(8) Read-only
Contributed by Tom Rhodes.
In some cases it may be desirable to modify read-only sysctl(8)
values. While this is not recommended, it is also sometimes
unavoidable.
For instance on some laptop models the cardbus(4) device will not
probe memory ranges, and fail with errors which look similar to:
cbb0: Could not map register memory
device_probe_and_attach: cbb0 attach returned 12
Cases like the one above usually require the modification of some
default sysctl(8) settings which are set read only. To overcome
these situations a user can put sysctl(8) ``OIDs'' in their local
/boot/loader.conf. Default settings are located in the
/boot/defaults/loader.conf file.
Fixing the problem mentioned above would require a user to set
hw.pci.allow_unsupported_io_range=1 in the aforementioned file.
Now cardbus(4) will work properly.
--------------------------------------------------------------
6.12 Tuning Disks
6.12.1 Sysctl Variables
6.12.1.1 vfs.vmiodirenable
The vfs.vmiodirenable sysctl variable may be set to either 0 (off)
or 1 (on); it is 1 by default. This variable controls how
directories are cached by the system. Most directories are small,
using just a single fragment (typically 1 K) in the file system
and less (typically 512 bytes) in the buffer cache. With this
variable turned off (to 0), the buffer cache will only cache a
fixed number of directories even if ou have a huge amount of
memory. When turned on (to 1), this sysctl allows the buffer cache
to use the VM Page Cache to cache the directories, making all the
memory available for caching directories. However, the minimum
in-core memory used to cache a directory is the physical page size
(typically 4 K) rather than 512 bytes. We recommend keeping this
option on if you are running any services which manipulate large
numbers of files. Such services can include web caches, large mail
systems, and news systems. Keeping this option on will generally
not reduce performance even with the wasted memory but you should
experiment to find out.
--------------------------------------------------------------
6.12.1.2 vfs.write_behind
The vfs.write_behind sysctl variable defaults to 1 (on). This
tells the file system to issue media writes as full clusters are
collected, which typically occurs when writing large sequential
files. The idea is to avoid saturating the buffer cache with dirty
buffers when it would not benefit I/O performance. However, this
may stall processes and under certain circumstances you may wish
to turn it off.
--------------------------------------------------------------
6.12.1.3 vfs.hirunningspace
The vfs.hirunningspace sysctl variable determines how much
outstanding write I/O may be queued to disk controllers
system-wide at any given instance. The default is usually
sufficient but on machines with lots of disks you may want to bump
it up to four or five megabytes. Note that setting too high a
value (exceeding the buffer cache's write threshold) can lead to
extremely bad clustering performance. Do not set this value
arbitrarily high! Higher write values may add latency to reads
occurring at the same time.
There are various other buffer-cache and VM page cache related
sysctls. We do not recommend modifying these values. The VM system
does an extremely good job of automatically tuning itself.
--------------------------------------------------------------
6.12.1.4 vm.swap_idle_enabled
The vm.swap_idle_enabled sysctl variable is useful in large
multi-user systems where you have lots of users entering and
leaving the system and lots of idle processes. Such systems tend
to generate a great deal of continuous pressure on free memory
reserves. Turning this feature on and tweaking the swapout
hysteresis (in idle seconds) via vm.swap_idle_threshold1 and
vm.swap_idle_threshold2 allows you to depress the priority of
memory pages associated with idle processes more quickly then the
normal pageout algorithm. This gives a helping hand to the pageout
daemon. Do not turn this option on unless you need it, because the
tradeoff you are making is essentially pre-page memory sooner
rather than later; thus eating more swap and disk bandwidth. In a
small system this option will have a determinable effect but in a
large system that is already doing moderate paging this option
allows the VM system to stage whole processes into and out of
memory easily.
--------------------------------------------------------------
6.12.1.5 hw.ata.wc
IDE drives lie about when a write completes. With IDE write
caching turned on, IDE hard drives not only write data to disk out
of order, but will sometimes delay writing some blocks
indefinitely when under heavy disk loads. A crash or power failure
may cause serious file system corruption. Turning off write
caching will remove the danger of this data loss, but will also
cause disk operations to proceed very slowly. Change this only if
prepared to suffer with the disk slowdown.
Changing this variable must be done from the boot loader at boot
time. Attempting to do it after the kernel boots will have no
effect.
For more information, please see ata(4) manual page.
--------------------------------------------------------------
6.12.2 Soft Updates
The tunefs(8) program can be used to fine-tune a file system. This
program has many different options, but for now we are only
concerned with toggling Soft Updates on and off, which is done by:
# tunefs -n enable /filesystem
# tunefs -n disable /filesystem
A filesystem cannot be modified with tunefs(8) while it is
mounted. A good time to enable Soft Updates is before any
partitions have been mounted, in single-user mode.
Note: It is possible to enable Soft Updates at filesystem
creation time, through use of the -U option to newfs(8).
Soft Updates drastically improves meta-data performance, mainly
file creation and deletion, through the use of a memory cache. We
recommend to use Soft Updates on all of your file systems. There
are two downsides to Soft Updates that you should be aware of:
First, Soft Updates guarantees filesystem consistency in the case
of a crash but could very easily be several seconds (even a
minute!) behind updating the physical disk. If your system crashes
you may lose more work than otherwise. Secondly, Soft Updates
delays the freeing of filesystem blocks. If you have a filesystem
(such as the root filesystem) which is almost full, performing a
major update, such as make installworld, can cause the filesystem
to run out of space and the update to fail.
--------------------------------------------------------------
6.12.2.1 More Details about Soft Updates
There are two traditional approaches to writing a file systems
meta-data back to disk. (Meta-data updates are updates to
non-content data like inodes or directories.)
Historically, the default behavior was to write out meta-data
updates synchronously. If a directory had been changed, the system
waited until the change was actually written to disk. The file
data buffers (file contents) were passed through the buffer cache
and backed up to disk later on asynchronously. The advantage of
this implementation is that it operates safely. If there is a
failure during an update, the meta-data are always in a consistent
state. A file is either created completely or not at all. If the
data blocks of a file did not find their way out of the buffer
cache onto the disk by the time of the crash, fsck(8) is able to
recognize this and repair the filesystem by setting the file
length to 0. Additionally, the implementation is clear and simple.
The disadvantage is that meta-data changes are slow. An rm -r, for
instance, touches all the files in a directory sequentially, but
each directory change (deletion of a file) will be written
synchronously to the disk. This includes updates to the directory
itself, to the inode table, and possibly to indirect blocks
allocated by the file. Similar considerations apply for unrolling
large hierarchies (tar -x).
The second case is asynchronous meta-data updates. This is the
default for Linux/ext2fs and mount -o async for *BSD ufs. All
meta-data updates are simply being passed through the buffer cache
too, that is, they will be intermixed with the updates of the file
content data. The advantage of this implementation is there is no
need to wait until each meta-data update has been written to disk,
so all operations which cause huge amounts of meta-data updates
work much faster than in the synchronous case. Also, the
implementation is still clear and simple, so there is a low risk
for bugs creeping into the code. The disadvantage is that there is
no guarantee at all for a consistent state of the filesystem. If
there is a failure during an operation that updated large amounts
of meta-data (like a power failure, or someone pressing the reset
button), the filesystem will be left in an unpredictable state.
There is no opportunity to examine the state of the filesystem
when the system comes up again; the data blocks of a file could
already have been written to the disk while the updates of the
inode table or the associated directory were not. It is actually
impossible to implement a fsck which is able to clean up the
resulting chaos (because the necessary information is not
available on the disk). If the filesystem has been damaged beyond
repair, the only choice is to use newfs(8) on it and restore it
from backup.
The usual solution for this problem was to implement dirty region
logging, which is also referred to as journaling, although that
term is not used consistently and is occasionally applied to other
forms of transaction logging as well. Meta-data updates are still
written synchronously, but only into a small region of the disk.
Later on they will be moved to their proper location. Because the
logging area is a small, contiguous region on the disk, there are
no long distances for the disk heads to move, even during heavy
operations, so these operations are quicker than synchronous
updates. Additionally the complexity of the implementation is
fairly limited, so the risk of bugs being present is low. A
disadvantage is that all meta-data are written twice (once into
the logging region and once to the proper location) so for normal
work, a performance ``pessimization'' might result. On the other
hand, in case of a crash, all pending meta-data operations can be
quickly either rolled-back or completed from the logging area
after the system comes up again, resulting in a fast filesystem
startup.
Kirk McKusick, the developer of Berkeley FFS, solved this problem
with Soft Updates: all pending meta-data updates are kept in
memory and written out to disk in a sorted sequence (``ordered
meta-data updates''). This has the effect that, in case of heavy
meta-data operations, later updates to an item ``catch'' the
earlier ones if the earlier ones are still in memory and have not
already been written to disk. So all operations on, say, a
directory are generally performed in memory before the update is
written to disk (the data blocks are sorted according to their
position so that they will not be on the disk ahead of their
meta-data). If the system crashes, this causes an implicit ``log
rewind'': all operations which did not find their way to the disk
appear as if they had never happened. A consistent filesystem
state is maintained that appears to be the one of 30 to 60 seconds
earlier. The algorithm used guarantees that all resources in use
are marked as such in their appropriate bitmaps: blocks and
inodes. After a crash, the only resource allocation error that
occurs is that resources are marked as ``used'' which are actually
``free''. fsck(8) recognizes this situation, and frees the
resources that are no longer used. It is safe to ignore the dirty
state of the filesystem after a crash by forcibly mounting it with
mount -f. In order to free resources that may be unused, fsck(8)
needs to be run at a later time.
The advantage is that meta-data operations are nearly as fast as
asynchronous updates (i.e. faster than with logging, which has to
write the meta-data twice). The disadvantages are the complexity
of the code (implying a higher risk for bugs in an area that is
highly sensitive regarding loss of user data), and a higher memory
consumption. Additionally there are some idiosyncrasies one has to
get used to. After a crash, the state of the filesystem appears to
be somewhat ``older''. In situations where the standard
synchronous approach would have caused some zero-length files to
remain after the fsck, these files do not exist at all with a Soft
Updates filesystem because neither the meta-data nor the file
contents have ever been written to disk. Disk space is not
released until the updates have been written to disk, which may
take place some time after running rm. This may cause problems
when installing large amounts of data on a filesystem that does
not have enough free space to hold all the files twice.
--------------------------------------------------------------
6.13 Tuning Kernel Limits
--------------------------------------------------------------
6.13.1 File/Process Limits
6.13.1.1 kern.maxfiles
kern.maxfiles can be raised or lowered based upon your system
requirements. This variable indicates the maximum number of file
descriptors on your system. When the file descriptor table is
full, ``file: table is full'' will show up repeatedly in the
system message buffer, which can be viewed with the dmesg command.
Each open file, socket, or fifo uses one file descriptor. A
large-scale production server may easily require many thousands of
file descriptors, depending on the kind and number of services
running concurrently.
kern.maxfile's default value is dictated by the MAXUSERS option in
your kernel configuration file. kern.maxfiles grows proportionally
to the value of MAXUSERS. When compiling a custom kernel, it is a
good idea to set this kernel configuration option according to the
uses of your system. From this number, the kernel is given most of
its pre-defined limits. Even though a production machine may not
actually have 256 users connected at once, the resources needed
may be similar to a high-scale web server.
Note: Setting MAXUSERS to 0 in your kernel configuration file
will choose a reasonable default value based on the amount of
RAM present in your system. It is set to 0 in the default
GENERIC kernel.
--------------------------------------------------------------
6.13.1.2 kern.ipc.somaxconn
The kern.ipc.somaxconn sysctl variable limits the size of the
listen queue for accepting new TCP connections. The default value
of 128 is typically too low for robust handling of new connections
in a heavily loaded web server environment. For such environments,
it is recommended to increase this value to 1024 or higher. The
service daemon may itself limit the listen queue size (e.g.
sendmail(8), or Apache) but will often have a directive in its
configuration file to adjust the queue size. Large listen queues
also do a better job of avoiding Denial of Service (DoS) attacks.
--------------------------------------------------------------
6.13.2 Network Limits
The NMBCLUSTERS kernel configuration option dictates the amount of
network Mbufs available to the system. A heavily-trafficked server
with a low number of Mbufs will hinder DragonFly's ability. Each
cluster represents approximately 2 K of memory, so a value of 1024
represents 2 megabytes of kernel memory reserved for network
buffers. A simple calculation can be done to figure out how many
are needed. If you have a web server which maxes out at 1000
simultaneous connections, and each connection eats a 16 K receive
and 16 K send buffer, you need approximately 32 MB worth of
network buffers to cover the web server. A good rule of thumb is
to multiply by 2, so 2x32 MB / 2 KB = 64 MB / 2 kB = 32768. We
recommend values between 4096 and 32768 for machines with greater
amounts of memory. Under no circumstances should you specify an
arbitrarily high value for this parameter as it could lead to a
boot time crash. The -m option to netstat(1) may be used to
observe network cluster use. kern.ipc.nmbclusters loader tunable
should be used to tune this at boot time.
For busy servers that make extensive use of the sendfile(2) system
call, it may be necessary to increase the number of sendfile(2)
buffers via the NSFBUFS kernel configuration option or by setting
its value in /boot/loader.conf (see loader(8) for details). A
common indicator that this parameter needs to be adjusted is when
processes are seen in the sfbufa state. The sysctl variable
kern.ipc.nsfbufs is a read-only glimpse at the kernel configured
variable. This parameter nominally scales with kern.maxusers,
however it may be necessary to tune accordingly.
Important: Even though a socket has been marked as non-blocking,
calling sendfile(2) on the non-blocking socket may result in the
sendfile(2) call blocking until enough struct sf_buf's are made
available.
--------------------------------------------------------------
6.13.2.1 net.inet.ip.portrange.*
The net.inet.ip.portrange.* sysctl variables control the port
number ranges automatically bound to TCP and UDP sockets. There
are three ranges: a low range, a default range, and a high range.
Most network programs use the default range which is controlled by
the net.inet.ip.portrange.first and net.inet.ip.portrange.last,
which default to 1024 and 5000, respectively. Bound port ranges
are used for outgoing connections, and it is possible to run the
system out of ports under certain circumstances. This most
commonly occurs when you are running a heavily loaded web proxy.
The port range is not an issue when running servers which handle
mainly incoming connections, such as a normal web server, or has a
limited number of outgoing connections, such as a mail relay. For
situations where you may run yourself out of ports, it is
recommended to increase net.inet.ip.portrange.last modestly. A
value of 10000, 20000 or 30000 may be reasonable. You should also
consider firewall effects when changing the port range. Some
firewalls may block large ranges of ports (usually low-numbered
ports) and expect systems to use higher ranges of ports for
outgoing connections -- for this reason it is recommended that
net.inet.ip.portrange.first be lowered.
--------------------------------------------------------------
6.13.2.2 TCP Bandwidth Delay Product
The TCP Bandwidth Delay Product Limiting is similar to TCP/Vegas
in NetBSD. It can be enabled by setting
net.inet.tcp.inflight_enable sysctl variable to 1. The system will
attempt to calculate the bandwidth delay product for each
connection and limit the amount of data queued to the network to
just the amount required to maintain optimum throughput.
This feature is useful if you are serving data over modems,
Gigabit Ethernet, or even high speed WAN links (or any other link
with a high bandwidth delay product), especially if you are also
using window scaling or have configured a large send window. If
you enable this option, you should also be sure to set
net.inet.tcp.inflight_debug to 0 (disable debugging), and for
production use setting net.inet.tcp.inflight_min to at least 6144
may be beneficial. However, note that setting high minimums may
effectively disable bandwidth limiting depending on the link. The
limiting feature reduces the amount of data built up in
intermediate route and switch packet queues as well as reduces the
amount of data built up in the local host's interface queue. With
fewer packets queued up, interactive connections, especially over
slow modems, will also be able to operate with lower Round Trip
Times. However, note that this feature only effects data
transmission (uploading / server side). It has no effect on data
reception (downloading).
Adjusting net.inet.tcp.inflight_stab is not recommended. This
parameter defaults to 20, representing 2 maximal packets added to
the bandwidth delay product window calculation. The additional
window is required to stabilize the algorithm and improve
responsiveness to changing conditions, but it can also result in
higher ping times over slow links (though still much lower than
you would get without the inflight algorithm). In such cases, you
may wish to try reducing this parameter to 15, 10, or 5; and may
also have to reduce net.inet.tcp.inflight_min (for example, to
3500) to get the desired effect. Reducing these parameters should
be done as a last resort only.
--------------------------------------------------------------
6.14 Adding Swap Space
No matter how well you plan, sometimes a system does not run as
you expect. If you find you need more swap space, it is simple
enough to add. You have three ways to increase swap space: adding
a new hard drive, enabling swap over NFS, and creating a swap file
on an existing partition.
--------------------------------------------------------------
6.14.1 Swap on a New Hard Drive
The best way to add swap, of course, is to use this as an excuse
to add another hard drive. You can always use another hard drive,
after all. If you can do this, go reread the discussion about swap
space in Section 6.2 for some suggestions on how to best arrange
your swap.
--------------------------------------------------------------
6.14.2 Swapping over NFS
Swapping over NFS is only recommended if you do not have a local
hard disk to swap to. Even though DragonFly has an excellent NFS
implementation, NFS swapping will be limited by the available
network bandwidth and puts an additional burden on the NFS server.
--------------------------------------------------------------
6.14.3 Swapfiles
You can create a file of a specified size to use as a swap file.
In our example here we will use a 64MB file called /usr/swap0. You
can use any name you want, of course.
Example 6-1. Creating a Swapfile
1. Be certain that your kernel configuration includes the vnode
driver. It is not in recent versions of GENERIC.
pseudo-device vn 1 #Vnode driver (turns a file into a device)
2. Create a vn-device:
# cd /dev
# sh MAKEDEV vn0
3. Create a swapfile (/usr/swap0):
# dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
4. Set proper permissions on (/usr/swap0):
# chmod 0600 /usr/swap0
5. Enable the swap file in /etc/rc.conf:
swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.
6. Reboot the machine or to enable the swap file immediately,
type:
# vnconfig -e /dev/vn0b /usr/swap0 swap
--------------------------------------------------------------
6.15 Power and Resource Management
Written by Hiten Pandya and Tom Rhodes.
It is very important to utilize hardware resources in an efficient
manner. Before ACPI was introduced, it was very difficult and
inflexible for operating systems to manage the power usage and
thermal properties of a system. The hardware was controlled by
some sort of BIOS embedded interface, such as Plug and Play BIOS
(PNPBIOS), or Advanced Power Management (APM) and so on. Power and
Resource Management is one of the key components of a modern
operating system. For example, you may want an operating system to
monitor system limits (and possibly alert you) in case your system
temperature increased unexpectedly.
In this section, we will provide comprehensive information about
ACPI. References will be provided for further reading at the end.
Please be aware that ACPI is available on DragonFly systems as a
default kernel module.
--------------------------------------------------------------
6.15.1 What Is ACPI?
Advanced Configuration and Power Interface (ACPI) is a standard
written by an alliance of vendors to provide a standard interface
for hardware resources and power management (hence the name). It
is a key element in Operating System-directed configuration and
Power Management, i.e.: it provides more control and flexibility
to the operating system (OS). Modern systems ``stretched'' the
limits of the current Plug and Play interfaces (such as APM),
prior to the introduction of ACPI. ACPI is the direct successor to
APM (Advanced Power Management).
--------------------------------------------------------------
6.15.2 Shortcomings of Advanced Power Management (APM)
The Advanced Power Management (APM) facility control's the power
usage of a system based on its activity. The APM BIOS is supplied
by the (system) vendor and it is specific to the hardware
platform. An APM driver in the OS mediates access to the APM
Software Interface, which allows management of power levels.
There are four major problems in APM. Firstly, power management is
done by the (vendor-specific) BIOS, and the OS does not have any
knowledge of it. One example of this, is when the user sets
idle-time values for a hard drive in the APM BIOS, that when
exceeded, it (BIOS) would spin down the hard drive, without the
consent of the OS. Secondly, the APM logic is embedded in the
BIOS, and it operates outside the scope of the OS. This means
users can only fix problems in their APM BIOS by flashing a new
one into the ROM; which, is a very dangerous procedure, and if it
fails, it could leave the system in an unrecoverable state.
Thirdly, APM is a vendor-specific technology, which, means that
there is a lot or parity (duplication of efforts) and bugs found
in one vendor's BIOS, may not be solved in others. Last but not
the least, the APM BIOS did not have enough room to implement a
sophisticated power policy, or one that can adapt very well to the
purpose of the machine.
Plug and Play BIOS (PNPBIOS) was unreliable in many situations.
PNPBIOS is 16-bit technology, so the OS has to use 16-bit
emulation in order to ``interface'' with PNPBIOS methods.
The DragonFly APM driver is documented in the apm(4) manual page.
--------------------------------------------------------------
6.15.3 Configuring ACPI
The acpi.ko driver is loaded by default at start up by the
loader(8) and should not be compiled into the kernel. The
reasoning behind this is that modules are easier to work with, say
if switching to another acpi.ko without doing a kernel rebuild.
This has the advantage of making testing easier. Another reason is
that starting ACPI after a system has been brought up is not too
useful, and in some cases can be fatal. In doubt, just disable
ACPI all together. This driver should not and can not be unloaded
because the system bus uses it for various hardware interactions.
ACPI can be disabled with the acpiconf(8) utility. In fact most of
the interaction with ACPI can be done via acpiconf(8). Basically
this means, if anything about ACPI is in the dmesg(8) output, then
most likely it is already running.
Note: ACPI and APM cannot coexist and should be used separately.
The last one to load will terminate if the driver notices the
other running.
In the simplest form, ACPI can be used to put the system into a
sleep mode with acpiconf(8), the -s flag, and a 1-5 option. Most
users will only need 1. Option 5 will do a soft-off which is the
same action as:
# halt -p
The other options are available. Check out the acpiconf(8) manual
page for more information.
--------------------------------------------------------------
6.16 Using and Debugging DragonFly ACPI
Written by Nate Lawson. With contributions from Peter Schultz and
Tom Rhodes.
ACPI is a fundamentally new way of discovering devices, managing
power usage, and providing standardized access to various hardware
previously managed by the BIOS. Progress is being made toward ACPI
working on all systems, but bugs in some motherboards' ACPI
Machine Language (AML) bytecode, incompleteness in DragonFly's
kernel subsystems, and bugs in the Intel ACPI-CA interpreter
continue to appear.
This document is intended to help you assist the DragonFly ACPI
maintainers in identifying the root cause of problems you observe
and debugging and developing a solution. Thanks for reading this
and we hope we can solve your system's problems.
--------------------------------------------------------------
6.16.1 Submitting Debugging Information
Note: Before submitting a problem, be sure you are running the
latest BIOS version and, if available, embedded controller
firmware version.
For those of you that want to submit a problem right away, please
send the following information to bugs
* Description of the buggy behavior, including system type and
model and anything that causes the bug to appear. Also, please
note as accurately as possible when the bug began occurring if
it is new for you.
* The dmesg output after ``boot -v'', including any error
messages generated by you exercising the bug.
* dmesg output from ``boot -v'' with ACPI disabled, if disabling
it helps fix the problem.
* Output from ``sysctl hw.acpi''. This is also a good way of
figuring out what features your system offers.
* URL where your ACPI Source Language (ASL) can be found. Do not
send the ASL directly to the list as it can be very large.
Generate a copy of your ASL by running this command:
# acpidump -t -d > name-system.asl
(Substitute your login name for name and manufacturer/model
for system. Example: njl-FooCo6000.asl)
--------------------------------------------------------------
6.16.2 Background
ACPI is present in all modern computers that conform to the ia32
(x86), ia64 (Itanium), and amd64 (AMD) architectures. The full
standard has many features including CPU performance management,
power planes control, thermal zones, various battery systems,
embedded controllers, and bus enumeration. Most systems implement
less than the full standard. For instance, a desktop system
usually only implements the bus enumeration parts while a laptop
might have cooling and battery management support as well. Laptops
also have suspend and resume, with their own associated
complexity.
An ACPI-compliant system has various components. The BIOS and
chipset vendors provide various fixed tables (e.g., FADT) in
memory that specify things like the APIC map (used for SMP),
config registers, and simple configuration values. Additionally, a
table of bytecode (the Differentiated System Description Table
DSDT) is provided that specifies a tree-like name space of devices
and methods.
The ACPI driver must parse the fixed tables, implement an
interpreter for the bytecode, and modify device drivers and the
kernel to accept information from the ACPI subsystem. For
DragonFly, Intel has provided an interpreter (ACPI-CA) that is
shared with Linux and NetBSD. The path to the ACPI-CA source code
is src/sys/contrib/dev/acpica-unix-YYYYMMDD, where YYYYMMDD is the
release date of the ACPI-CA source code. The glue code that allows
ACPI-CA to work on DragonFly is in src/sys/dev/acpica5/Osd.
Finally, drivers that implement various ACPI devices are found in
src/sys/dev/acpica5, and architecture-dependent code resides in
/sys/arch/acpica5.
--------------------------------------------------------------
6.16.3 Common Problems
For ACPI to work correctly, all the parts have to work correctly.
Here are some common problems, in order of frequency of
appearance, and some possible workarounds or fixes.
--------------------------------------------------------------
6.16.3.1 Suspend/Resume
ACPI has three suspend to RAM (STR) states, S1-S3, and one suspend
to disk state (STD), called S4. S5 is ``soft off'' and is the
normal state your system is in when plugged in but not powered up.
S4 can actually be implemented two separate ways. S4BIOS is a
BIOS-assisted suspend to disk. S4OS is implemented entirely by the
operating system.
Start by checking sysctl hw.acpi for the suspend-related items.
Here are the results for my Thinkpad:
hw.acpi.supported_sleep_state: S3 S4 S5
hw.acpi.s4bios: 0
This means that I can use acpiconf -s to test S3, S4OS, and S5. If
s4bios was one (1), I would have S4BIOS support instead of S4 OS.
When testing suspend/resume, start with S1, if supported. This
state is most likely to work since it doesn't require much driver
support. No one has implemented S2 but if you have it, it's
similar to S1. The next thing to try is S3. This is the deepest
STR state and requires a lot of driver support to properly
reinitialize your hardware. If you have problems resuming, feel
free to email the bugs list but do not expect the problem to be
resolved since there are a lot of drivers/hardware that need more
testing and work.
To help isolate the problem, remove as many drivers from your
kernel as possible. If it works, you can narrow down which driver
is the problem by loading drivers until it fails again. Typically
binary drivers like nvidia.ko, X11 display drivers, and USB will
have the most problems while Ethernet interfaces usually work
fine. If you can load/unload the drivers ok, you can automate this
by putting the appropriate commands in /etc/rc.suspend and
/etc/rc.resume. There is a commented-out example for unloading and
loading a driver. Try setting hw.acpi.reset_video to zero (0) if
your display is messed up after resume. Try setting longer or
shorter values for hw.acpi.sleep_delay to see if that helps.
Another thing to try is load a recent Linux distribution with ACPI
support and test their suspend/resume support on the same
hardware. If it works on Linux, it's likely a DragonFly driver
problem and narrowing down which driver causes the problems will
help us fix the problem. Note that the ACPI maintainers do not
usually maintain other drivers (e.g sound, ATA, etc.) so any work
done on tracking down a driver problem should probably eventually
be posted to the bugs list and mailed to the driver maintainer. If
you are feeling adventurous, go ahead and start putting some
debugging printf(3)s in a problematic driver to track down where
in its resume function it hangs.
Finally, try disabling ACPI and enabling APM instead. If
suspend/resume works with APM, you may be better off sticking with
APM, especially on older hardware (pre-2000). It took vendors a
while to get ACPI support correct and older hardware is more
likely to have BIOS problems with ACPI.
--------------------------------------------------------------
6.16.3.2 System Hangs (temporary or permanent)
Most system hangs are a result of lost interrupts or an interrupt
storm. Chipsets have a lot of problems based on how the BIOS
configures interrupts before boot, correctness of the APIC (MADT)
table, and routing of the System Control Interrupt (SCI).
Interrupt storms can be distinguished from lost interrupts by
checking the output of vmstat -i and looking at the line that has
acpi0. If the counter is increasing at more than a couple per
second, you have an interrupt storm. If the system appears hung,
try breaking to DDB (CTRL+ALT+ESC on console) and type show
interrupts.
Your best hope when dealing with interrupt problems is to try
disabling APIC support with hint.apic.0.disabled="1" in
loader.conf.
--------------------------------------------------------------
6.16.3.3 Panics
Panics are relatively rare for ACPI and are the top priority to be
fixed. The first step is to isolate the steps to reproduce the
panic (if possible) and get a backtrace. Follow the advice for
enabling options DDB and setting up a serial console (see Section
17.6.5.3) or setting up a dump(8) partition. You can get a
backtrace in DDB with tr. If you have to handwrite the backtrace,
be sure to at least get the lowest five (5) and top five (5) lines
in the trace.
Then, try to isolate the problem by booting with ACPI disabled. If
that works, you can isolate the ACPI subsystem by using various
values of debug.acpi.disable. See the acpi(4) manual page for some
examples.
--------------------------------------------------------------
6.16.3.4 System Powers Up After Suspend or Shutdown
First, try setting hw.acpi.disable_on_poweroff=``0'' in
loader.conf(5). This keeps ACPI from disabling various events
during the shutdown process. Some systems need this value set to
``1'' (the default) for the same reason. This usually fixes the
problem of a system powering up spontaneously after a suspend or
poweroff.
--------------------------------------------------------------
6.16.3.5 Other Problems
If you have other problems with ACPI (working with a docking
station, devices not detected, etc.), please email a description
to the mailing list as well; however, some of these issues may be
related to unfinished parts of the ACPI subsystem so they might
take a while to be implemented. Please be patient and prepared to
test patches we may send you.
--------------------------------------------------------------
6.16.4 ASL, acpidump, and IASL
The most common problem is the BIOS vendors providing incorrect
(or outright buggy!) bytecode. This is usually manifested by
kernel console messages like this:
ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
(Node 0xc3f6d160), AE_NOT_FOUND
Often, you can resolve these problems by updating your BIOS to the
latest revision. Most console messages are harmless but if you
have other problems like battery status not working, they're a
good place to start looking for problems in the AML. The bytecode,
known as AML, is compiled from a source language called ASL. The
AML is found in the table known as the DSDT. To get a copy of your
ASL, use acpidump(8). You should use both the -t (show contents of
the fixed tables) and -d (disassemble AML to ASL) options. See the
Submitting Debugging Information section for an example syntax.
The simplest first check you can do is to recompile your ASL to
check for errors. Warnings can usually be ignored but errors are
bugs that will usually prevent ACPI from working correctly. To
recompile your ASL, issue the following command:
# iasl your.asl
--------------------------------------------------------------
6.16.5 Fixing Your ASL
In the long run, our goal is for almost everyone to have ACPI work
without any user intervention. At this point, however, we are
still developing workarounds for common mistakes made by the BIOS
vendors. The Microsoft interpreter (acpi.sys and acpiec.sys) does
not strictly check for adherence to the standard, and thus many
BIOS vendors who only test ACPI under Windows never fix their ASL.
We hope to continue to identify and document exactly what
non-standard behavior is allowed by Microsoft's interpreter and
replicate it so DragonFly can work without forcing users to fix
the ASL. As a workaround and to help us identify behavior, you can
fix the ASL manually. If this works for you, please send a diff(1)
of the old and new ASL so we can possibly work around the buggy
behavior in ACPI-CA and thus make your fix unnecessary.
Here is a list of common error messages, their cause, and how to
fix them:
--------------------------------------------------------------
6.16.5.1 _OS dependencies
Some AML assumes the world consists of various Windows versions.
You can tell DragonFly to claim it is any OS to see if this fixes
problems you may have. An easy way to override this is to set
hw.acpi.osname=``Windows 2001'' in /boot/loader.conf or other
similar strings you find in the ASL.
--------------------------------------------------------------
6.16.5.2 Missing Return statements
Some methods do not explicitly return a value as the standard
requires. While ACPI-CA does not handle this, DragonFly has a
workaround that allows it to return the value implicitly. You can
also add explicit Return statements where required if you know
what value should be returned. To force iasl to compile the ASL,
use the -f flag.
--------------------------------------------------------------
6.16.5.3 Overriding the Default AML
After you customize your.asl, you will want to compile it, run:
# iasl your.asl
You can add the -f flag to force creation of the AML, even if
there are errors during compilation. Remember that some errors
(e.g., missing Return statements) are automatically worked around
by the interpreter.
DSDT.aml is the default output filename for iasl. You can load
this instead of your BIOS's buggy copy (which is still present in
flash memory) by editing /boot/loader.conf as follows:
acpi_dsdt_load="YES"
acpi_dsdt_name="/boot/DSDT.aml"
Be sure to copy your DSDT.aml to the /boot directory.
--------------------------------------------------------------
6.16.6 Getting Debugging Output From ACPI
The ACPI driver has a very flexible debugging facility. It allows
you to specify a set of subsystems as well as the level of
verbosity. The subsystems you wish to debug are specified as
``layers'' and are broken down into ACPI-CA components
(ACPI_ALL_COMPONENTS) and ACPI hardware support
(ACPI_ALL_DRIVERS). The verbosity of debugging output is specified
as the ``level'' and ranges from ACPI_LV_ERROR (just report
errors) to ACPI_LV_VERBOSE (everything). The ``level'' is a
bitmask so multiple options can be set at once, separated by
spaces. In practice, you will want to use a serial console to log
the output if it is so long it flushes the console message buffer.
Debugging output is not enabled by default. To enable it, add
options ACPI_DEBUG to your kernel config if ACPI is compiled into
the kernel. You can add ACPI_DEBUG=1 to your /etc/make.conf to
enable it globally. If it is a module, you can recompile just your
acpi.ko module as follows:
# cd /sys/dev/acpica5
&& make clean &&
make ACPI_DEBUG=1
Install acpi.ko in /boot/kernel and add your desired level and
layer to loader.conf. This example enables debug messages for all
ACPI-CA components and all ACPI hardware drivers (CPU, LID, etc.)
It will only output error messages, the least verbose level.
debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
debug.acpi.level="ACPI_LV_ERROR"
If the information you want is triggered by a specific event (say,
a suspend and then resume), you can leave out changes to
loader.conf and instead use sysctl to specify the layer and level
after booting and preparing your system for the specific event.
The sysctls are named the same as the tunables in loader.conf.
--------------------------------------------------------------
6.16.7 References
More information about ACPI may be found in the following
locations:
* The FreeBSD ACPI mailing list (This is FreeBSD-specific;
posting DragonFly questions here may not generate much of an
answer.)
* The ACPI Mailing List Archives (FreeBSD)
http://lists.freebsd.org/pipermail/freebsd-acpi/
* The old ACPI Mailing List Archives (FreeBSD)
http://home.jp.FreeBSD.org/mail-list/acpi-jp/
* The ACPI 2.0 Specification http://acpi.info/spec.htm
* DragonFly Manual pages: acpidump(8), acpiconf(8), acpidb(8)
* DSDT debugging resource. (Uses Compaq as an example but
generally useful.)
--------------------------------------------------------------
Chapter 7 The DragonFly Booting Process
7.1 Synopsis
The process of starting a computer and loading the operating
system is referred to as ``the bootstrap process'', or simply
``booting''. DragonFly's boot process provides a great deal of
flexibility in customizing what happens when you start the system,
allowing you to select from different operating systems installed
on the same computer, or even different versions of the same
operating system or installed kernel.
This chapter details the configuration options you can set and how
to customize the DragonFly boot process. This includes everything
that happens until the DragonFly kernel has started, probed for
devices, and started init(8). If you are not quite sure when this
happens, it occurs when the text color changes from bright white
to grey.
After reading this chapter, you will know:
* What the components of the DragonFly bootstrap system are, and
how they interact.
* The options you can give to the components in the DragonFly
bootstrap to control the boot process.
* The basics of device.hints(5).
x86 Only: This chapter only describes the boot process for
DragonFly running on x86 systems.
--------------------------------------------------------------
7.2 The Booting Problem
Turning on a computer and starting the operating system poses an
interesting dilemma. By definition, the computer does not know how
to do anything until the operating system is started. This
includes running programs from the disk. So if the computer can
not run a program from the disk without the operating system, and
the operating system programs are on the disk, how is the
operating system started?
This problem parallels one in the book The Adventures of Baron
Munchausen. A character had fallen part way down a manhole, and
pulled himself out by grabbing his bootstraps, and lifting. In the
early days of computing the term bootstrap was applied to the
mechanism used to load the operating system, which has become
shortened to ``booting''.
On x86 hardware the Basic Input/Output System (BIOS) is
responsible for loading the operating system. To do this, the BIOS
looks on the hard disk for the Master Boot Record (MBR), which
must be located on a specific place on the disk. The BIOS has
enough knowledge to load and run the MBR, and assumes that the MBR
can then carry out the rest of the tasks involved in loading the
operating system possibly with the help of the BIOS.
The code within the MBR is usually referred to as a boot manager,
especially when it interacts with the user. In this case the boot
manager usually has more code in the first track of the disk or
within some OS's file system. (A boot manager is sometimes also
called a boot loader, but FreeBSD uses that term for a later stage
of booting.) Popular boot managers include boot0 (a.k.a. Boot
Easy, the standard DragonFly boot manager), Grub, GAG, and LILO.
(Only boot0 fits within the MBR.)
If you have only one operating system installed on your disks then
a standard PC MBR will suffice. This MBR searches for the first
bootable (a.k.a. active) slice on the disk, and then runs the code
on that slice to load the remainder of the operating system. The
MBR installed by fdisk(8), by default, is such an MBR. It is based
on /boot/mbr.
If you have installed multiple operating systems on your disks
then you can install a different boot manager, one that can
display a list of different operating systems, and allows you to
choose the one to boot from. Two of these are discussed in the
next subsection.
The remainder of the DragonFly bootstrap system is divided into
three stages. The first stage is run by the MBR, which knows just
enough to get the computer into a specific state and run the
second stage. The second stage can do a little bit more, before
running the third stage. The third stage finishes the task of
loading the operating system. The work is split into these three
stages because the PC standards put limits on the size of the
programs that can be run at stages one and two. Chaining the tasks
together allows DragonFly to provide a more flexible loader.
The kernel is then started and it begins to probe for devices and
initialize them for use. Once the kernel boot process is finished,
the kernel passes control to the user process init(8), which then
makes sure the disks are in a usable state. init(8) then starts
the user-level resource configuration which mounts file systems,
sets up network cards to communicate on the network, and generally
starts all the processes that usually are run on a DragonFly
system at startup.
--------------------------------------------------------------
7.3 The Boot Manager and Boot Stages
--------------------------------------------------------------
7.3.1 The Boot Manager
The code in the MBR or boot manager is sometimes referred to as
stage zero of the boot process. This subsection discusses two of
the boot managers previously mentioned: boot0 and LILO.
The boot0 Boot Manager: The MBR installed by FreeBSD's installer
or boot0cfg(8), by default, is based on /boot/boot0. (The boot0
program is very simple, since the program in the MBR can only be
446 bytes long because of the slice table and 0x55AA identifier at
the end of the MBR.) If you have installed boot0 and multiple
operating systems on your hard disks, then you will see a display
similar to this one at boot time:
Example 7-1. boot0 Screenshot
F1 DOS
F2 FreeBSD
F3 Linux
F4 ??
F5 Drive 1
Default: F2
Other operating systems, in particular Windows, have been known to
overwrite an existing MBR with their own. If this happens to you,
or you want to replace your existing MBR with the DragonFly MBR
then use the following command:
# fdisk -B -b /boot/boot0 device
where device is the device that you boot from, such as ad0 for the
first IDE disk, ad2 for the first IDE disk on a second IDE
controller, da0 for the first SCSI disk, and so on. Or, if you
want a custom configuration of the MBR, use boot0cfg(8).
The LILO Boot Manager: To install this boot manager so it will
also boot DragonFly, first start Linux and add the following to
your existing /etc/lilo.conf configuration file:
other=/dev/hdXY
table=/dev/hdX
loader=/boot/chain.b
label=DragonFly
In the above, specify DragonFly's primary partition and drive
using Linux specifiers, replacing X with the Linux drive letter
and Y with the Linux primary partition number. If you are using a
SCSI drive, you will need to change /dev/hd to read something
similar to /dev/sd. The loader=/boot/chain.b line can be omitted
if you have both operating systems on the same drive. Now run
/sbin/lilo -v to commit your new changes to the system; this
should be verified by checking its screen messages.
--------------------------------------------------------------
7.3.2 Stage One, /boot/boot1, and Stage Two, /boot/boot2
Conceptually the first and second stages are part of the same
program, on the same area of the disk. Because of space
constraints they have been split into two, but you would always
install them together. They are copied from the combined file
/boot/boot by the installer or disklabel (see below).
They are located outside file systems, in the first track of the
boot slice, starting with the first sector. This is where boot0,
or any other boot manager, expects to find a program to run which
will continue the boot process. The number of sectors used is
easily determined from the size of /boot/boot.
They are found on the boot sector of the boot slice, which is
where boot0, or any other program on the MBR expects to find the
program to run to continue the boot process. The files in the
/boot directory are copies of the real files, which are stored
outside of the DragonFly file system.
boot1 is very simple, since it can only be 512 bytes in size, and
knows just enough about the DragonFly disklabel, which stores
information about the slice, to find and execute boot2.
boot2 is slightly more sophisticated, and understands the
DragonFly file system enough to find files on it, and can provide
a simple interface to choose the kernel or loader to run.
Since the loader is much more sophisticated, and provides a nice
easy-to-use boot configuration, boot2 usually runs it, but
previously it was tasked to run the kernel directly.
Example 7-2. boot2 Screenshot
>> DragonFly/i386 BOOT
Default: 0:ad(0,a)/boot/loader
boot:
If you ever need to replace the installed boot1 and boot2 use
disklabel(8):
# disklabel -B diskslice
where diskslice is the disk and slice you boot from, such as ad0s1
for the first slice on the first IDE disk.
--------------------------------------------------------------
7.3.3 Stage Three, /boot/loader
The loader is the final stage of the three-stage bootstrap, and is
located on the file system, usually as /boot/loader.
The loader is intended as a user-friendly method for
configuration, using an easy-to-use built-in command set, backed
up by a more powerful interpreter, with a more complex command
set.
--------------------------------------------------------------
7.3.3.1 Loader Program Flow
During initialization, the loader will probe for a console and for
disks, and figure out what disk it is booting from. It will set
variables accordingly, and an interpreter is started where user
commands can be passed from a script or interactively.
The loader will then read /boot/loader.rc, which by default reads
in /boot/defaults/loader.conf which sets reasonable defaults for
variables and reads /boot/loader.conf for local changes to those
variables. loader.rc then acts on these variables, loading
whichever modules and kernel are selected.
Finally, by default, the loader issues a 10 second wait for key
presses, and boots the kernel if it is not interrupted. If
interrupted, the user is presented with a prompt which understands
the easy-to-use command set, where the user may adjust variables,
unload all modules, load modules, and then finally boot or reboot.
--------------------------------------------------------------
7.3.3.2 Loader Built-In Commands
These are the most commonly used loader commands. For a complete
discussion of all available commands, please see loader(8).
autoboot seconds
Proceeds to boot the kernel if not interrupted within the
time span given, in seconds. It displays a countdown, and
the default time span is 10 seconds.
boot [-options] [kernelname]
Immediately proceeds to boot the kernel, with the given
options, if any, and with the kernel name given, if it is.
boot-conf
Goes through the same automatic configuration of modules
based on variables as what happens at boot. This only
makes sense if you use unload first, and change some
variables, most commonly kernel.
help [topic]
Shows help messages read from /boot/loader.help. If the
topic given is index, then the list of available topics is
given.
include filename ...
Processes the file with the given filename. The file is
read in, and interpreted line by line. An error
immediately stops the include command.
load [-t type] filename
Loads the kernel, kernel module, or file of the type
given, with the filename given. Any arguments after
filename are passed to the file.
ls [-l] [path]
Displays a listing of files in the given path, or the root
directory, if the path is not specified. If -l is
specified, file sizes will be shown too.
lsdev [-v]
Lists all of the devices from which it may be possible to
load modules. If -v is specified, more details are
printed.
lsmod [-v]
Displays loaded modules. If -v is specified, more details
are shown.
more filename
Displays the files specified, with a pause at each LINES
displayed.
reboot
Immediately reboots the system.
set variable, set variable=value
Sets the loader's environment variables.
unload
Removes all loaded modules.
--------------------------------------------------------------
7.3.3.3 Loader Examples
Here are some practical examples of loader usage:
* To simply boot your usual kernel, but in single-user mode:
boot -s
* To unload your usual kernel and modules, and then load just
your old (or another) kernel:
unload
load kernel.old
You can use kernel.GENERIC to refer to the generic kernel that
comes on the install disk, or kernel.old to refer to your
previously installed kernel (when you have upgraded or
configured your own kernel, for example).
Note: Use the following to load your usual modules with
another kernel:
unload
set kernel="kernel.old"
boot-conf
* To load a kernel configuration script (an automated script
which does the things you would normally do in the kernel
boot-time configurator):
load -t userconfig_script /boot/kernel.conf
--------------------------------------------------------------
7.4 Kernel Interaction During Boot
Once the kernel is loaded by either loader (as usual) or boot2
(bypassing the loader), it examines its boot flags, if any, and
adjusts its behavior as necessary.
--------------------------------------------------------------
7.4.1 Kernel Boot Flags
Here are the more common boot flags:
-a
during kernel initialization, ask for the device to mount
as the root file system.
-C
boot from CDROM.
-c
run UserConfig, the boot-time kernel configurator
-s
boot into single-user mode
-v
be more verbose during kernel startup
Note: There are other boot flags; read boot(8) for more
information on them.
--------------------------------------------------------------
7.5 Init: Process Control Initialization
Once the kernel has finished booting, it passes control to the
user process init(8), which is located at /sbin/init, or the
program path specified in the init_path variable in loader.
--------------------------------------------------------------
7.5.1 Automatic Reboot Sequence
The automatic reboot sequence makes sure that the file systems
available on the system are consistent. If they are not, and
fsck(8) cannot fix the inconsistencies, init(8) drops the system
into single-user mode for the system administrator to take care of
the problems directly.
--------------------------------------------------------------
7.5.2 Single-User Mode
This mode can be reached through the automatic reboot sequence, or
by the user booting with the -s option or setting the boot_single
variable in loader.
It can also be reached by calling shutdown(8) without the reboot
(-r) or halt (-h) options, from multi-user mode.
If the system console is set to insecure in /etc/ttys, then the
system prompts for the root password before initiating single-user
mode.
Example 7-3. An Insecure Console in /etc/ttys
# name getty type status comments
#
# If console is marked "insecure", then init will ask for the root password
# when going to single-user mode.
console none unknown off insecure
Note: An insecure console means that you consider your physical
security to the console to be insecure, and want to make sure
only someone who knows the root password may use single-user
mode, and it does not mean that you want to run your console
insecurely. Thus, if you want security, choose insecure, not
secure.
--------------------------------------------------------------
7.5.3 Multi-User Mode
If init(8) finds your file systems to be in order, or once the
user has finished in single-user mode, the system enters
multi-user mode, in which it starts the resource configuration of
the system.
--------------------------------------------------------------
7.5.3.1 Resource Configuration (rc)
The resource configuration system reads in configuration defaults
from /etc/defaults/rc.conf, and system-specific details from
/etc/rc.conf, and then proceeds to mount the system file systems
mentioned in /etc/fstab, start up networking services, start up
miscellaneous system daemons, and finally runs the startup scripts
of locally installed packages.
The rc(8) manual page is a good reference to the resource
configuration system, as is examining the scripts themselves.
--------------------------------------------------------------
7.6 Shutdown Sequence
Upon controlled shutdown, via shutdown(8), init(8) will attempt to
run the script /etc/rc.shutdown, and then proceed to send all
processes the TERM signal, and subsequently the KILL signal to any
that do not terminate timely.
To power down a DragonFly machine on architectures and systems
that support power management, simply use the command shutdown -p
now to turn the power off immediately. To just reboot a DragonFly
system, just use shutdown -r now. You need to be root or a member
of operator group to run shutdown(8). The halt(8) and reboot(8)
commands can also be used, please refer to their manual pages and
to shutdown(8)'s one for more information.
Note: Power management requires acpi(4) support in the kernel or
loaded as a module, or apm(4) support.
--------------------------------------------------------------
Chapter 8 Users and Basic Account Management
Contributed by Neil Blakey-Milner.
8.1 Synopsis
DragonFly allows multiple users to use the computer at the same
time. Obviously, only one of those users can be sitting in front
of the screen and keyboard at any one time [6], but any number of
users can log in through the network to get their work done. To
use the system every user must have an account.
After reading this chapter, you will know:
* The differences between the various user accounts on a
DragonFly system.
* How to add user accounts.
* How to remove user accounts.
* How to change account details, such as the user's full name,
or preferred shell.
* How to set limits on a per-account basis, to control the
resources such as memory and CPU time that accounts and groups
of accounts are allowed to access.
* How to use groups to make account management easier.
Before reading this chapter, you should:
* Understand the basics of UNIX and DragonFly (Chapter 3).
--------------------------------------------------------------
8.2 Introduction
All access to the system is achieved via accounts, and all
processes are run by users, so user and account management are of
integral importance on DragonFly systems.
Every account on a DragonFly system has certain information
associated with it to identify the account.
User name
The user name as it would be typed at the login: prompt.
User names must be unique across the computer; you may not
have two users with the same user name. There are a number
of rules for creating valid user names, documented in
passwd(5); you would typically use user names that consist
of eight or fewer all lower case characters.
Password
Each account has a password associated with it. The
password may be blank, in which case no password will be
required to access the system. This is normally a very bad
idea; every account should have a password.
User ID (UID)
The UID is a number, traditionally from 0 to 65535[7],
used to uniquely identify the user to the system.
Internally, DragonFly uses the UID to identify users--any
DragonFly commands that allow you to specify a user name
will convert it to the UID before working with it. This
means that you can have several accounts with different
user names but the same UID. As far as DragonFly is
concerned, these accounts are one user. It is unlikely you
will ever need to do this.
Group ID (GID)
The GID is a number, traditionally from 0 to 65535[7],
used to uniquely identify the primary group that the user
belongs to. Groups are a mechanism for controlling access
to resources based on a user's GID rather than their UID.
This can significantly reduce the size of some
configuration files. A user may also be in more than one
group.
Login class
Login classes are an extension to the group mechanism that
provide additional flexibility when tailoring the system
to different users.
Password change time
By default DragonFly does not force users to change their
passwords periodically. You can enforce this on a per-user
basis, forcing some or all of your users to change their
passwords after a certain amount of time has elapsed.
Account expiry time
By default DragonFly does not expire accounts. If you are
creating accounts that you know have a limited lifespan,
for example, in a school where you have accounts for the
students, then you can specify when the account expires.
After the expiry time has elapsed the account cannot be
used to log in to the system, although the account's
directories and files will remain.
User's full name
The user name uniquely identifies the account to
DragonFly, but does not necessarily reflect the user's
real name. This information can be associated with the
account.
Home directory
The home directory is the full path to a directory on the
system in which the user will start when logging on to the
system. A common convention is to put all user home
directories under /home/username or /usr/home/username.
The user would store their personal files in their home
directory, and any directories they may create in there.
User shell
The shell provides the default environment users use to
interact with the system. There are many different kinds
of shells, and experienced users will have their own
preferences, which can be reflected in their account
settings.
There are three main types of accounts: the Superuser, system
users, and user accounts. The Superuser account, usually called
root, is used to manage the system with no limitations on
privileges. System users run services. Finally, user accounts are
used by real people, who log on, read mail, and so forth.
--------------------------------------------------------------
8.3 The Superuser Account
The superuser account, usually called root, comes preconfigured to
facilitate system administration, and should not be used for
day-to-day tasks like sending and receiving mail, general
exploration of the system, or programming.
This is because the superuser, unlike normal user accounts, can
operate without limits, and misuse of the superuser account may
result in spectacular disasters. User accounts are unable to
destroy the system by mistake, so it is generally best to use
normal user accounts whenever possible, unless you especially need
the extra privilege.
You should always double and triple-check commands you issue as
the superuser, since an extra space or missing character can mean
irreparable data loss.
So, the first thing you should do after reading this chapter is to
create an unprivileged user account for yourself for general usage
if you have not already. This applies equally whether you are
running a multi-user or single-user machine. Later in this
chapter, we discuss how to create additional accounts, and how to
change between the normal user and superuser.
--------------------------------------------------------------
8.4 System Accounts
System users are those used to run services such as DNS, mail, web
servers, and so forth. The reason for this is security; if all
services ran as the superuser, they could act without restriction.
Examples of system users are daemon, operator, bind (for the
Domain Name Service), and news. Often sysadmins create httpd to
run web servers they install.
nobody is the generic unprivileged system user. However, it is
important to keep in mind that the more services that use nobody,
the more files and processes that user will become associated
with, and hence the more privileged that user becomes.
--------------------------------------------------------------
8.5 User Accounts
User accounts are the primary means of access for real people to
the system, and these accounts insulate the user and the
environment, preventing the users from damaging the system or
other users, and allowing users to customize their environment
without affecting others.
Every person accessing your system should have a unique user
account. This allows you to find out who is doing what, prevent
people from clobbering each others' settings or reading each
others' mail, and so forth.
Each user can set up their own environment to accommodate their
use of the system, by using alternate shells, editors, key
bindings, and language.
--------------------------------------------------------------
8.6 Modifying Accounts
There are a variety of different commands available in the UNIX
environment to manipulate user accounts. The most common commands
are summarized below, followed by more detailed examples of their
usage.
+----------------------------------------------------------------+
| Command | Summary |
|------------+---------------------------------------------------|
| adduser(8) | The recommended command-line application for |
| | adding new users. |
|------------+---------------------------------------------------|
| rmuser(8) | The recommended command-line application for |
| | removing users. |
|------------+---------------------------------------------------|
| chpass(1) | A flexible tool to change user database |
| | information. |
|------------+---------------------------------------------------|
| passwd(1) | The simple command-line tool to change user |
| | passwords. |
|------------+---------------------------------------------------|
| pw(8) | A powerful and flexible tool to modify all |
| | aspects of user accounts. |
+----------------------------------------------------------------+
--------------------------------------------------------------
8.6.1 adduser
adduser(8) is a simple program for adding new users. It creates
entries in the system passwd and group files. It will also create
a home directory for the new user, copy in the default
configuration files (``dotfiles'') from /usr/share/skel, and can
optionally mail the new user a welcome message.
To create the initial configuration file, use adduser -s
-config_create. [8] Next, we configure adduser(8) defaults, and
create our first user account, since using root for normal usage
is evil and nasty.
Example 8-1. Configuring adduser and adding a user
# adduser -v
Use option ``-silent'' if you don't want to see all warnings and questions.
Check /etc/shells
Check /etc/master.passwd
Check /etc/group
Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
Your default shell is: zsh -> /usr/local/bin/zsh
Enter your default HOME partition: [/home]:
Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
Send message from file: /etc/adduser.message no
[/etc/adduser.message]: no
Do not send message
Use passwords (y/n) [y]: y
Write your changes to /etc/adduser.conf? (y/n) [n]: y
Ok, let's go.
Don't worry about mistakes. I will give you the chance later to correct any input.
Enter username [a-z0-9_-]: jru
Enter full name []: J. Random User
Enter shell csh date no sh tcsh zsh [zsh]:
Enter home directory (full path) [/home/jru]:
Uid [1001]:
Enter login class: default []:
Login group jru [jru]:
Login group is ``jru''. Invite jru into other groups: guest no
[no]: wheel
Enter password []:
Enter password again []:
Name: jru
Password: ****
Fullname: J. Random User
Uid: 1001
Gid: 1001 (jru)
Class:
Groups: jru wheel
HOME: /home/jru
Shell: /usr/local/bin/zsh
OK? (y/n) [y]: y
Added user ``jru''
Copy files from /usr/share/skel to /home/jru
Add another user? (y/n) [y]: n
Goodbye!
#
In summary, we changed the default shell to zsh (an additional
shell found in pkgsrc), and turned off the sending of a welcome
mail to added users. We then saved the configuration, created an
account for jru, and made sure jru is in wheel group (so that she
may assume the role of root with the su(1) command.)
Note: The password you type in is not echoed, nor are asterisks
displayed. Make sure you do not mistype the password twice.
Note: Just use adduser(8) without arguments from now on, and you
will not have to go through changing the defaults. If the
program asks you to change the defaults, exit the program, and
try the -s option.
--------------------------------------------------------------
8.6.2 rmuser
You can use rmuser(8) to completely remove a user from the system.
rmuser(8) performs the following steps:
1. Removes the user's crontab(1) entry (if any).
2. Removes any at(1) jobs belonging to the user.
3. Kills all processes owned by the user.
4. Removes the user from the system's local password file.
5. Removes the user's home directory (if it is owned by the
user).
6. Removes the incoming mail files belonging to the user from
/var/mail.
7. Removes all files owned by the user from temporary file
storage areas such as /tmp.
8. Finally, removes the username from all groups to which it
belongs in /etc/group.
Note: If a group becomes empty and the group name is the
same as the username, the group is removed; this complements
the per-user unique groups created by adduser(8).
rmuser(8) cannot be used to remove superuser accounts, since that
is almost always an indication of massive destruction.
By default, an interactive mode is used, which attempts to make
sure you know what you are doing.
Example 8-2. rmuser Interactive Account Removal
# rmuser jru
Matching password entry:
jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
Is this the entry you wish to remove? y
Remove user's home directory (/home/jru)? y
Updating password file, updating databases, done.
Updating group file: trusted (removing group jru -- personal group is empty) done.
Removing user's incoming mail file /var/mail/jru: done.
Removing files belonging to jru from /tmp: done.
Removing files belonging to jru from /var/tmp: done.
Removing files belonging to jru from /var/tmp/vi.recover: done.
#
--------------------------------------------------------------
8.6.3 chpass
chpass(1) changes user database information such as passwords,
shells, and personal information.
Only system administrators, as the superuser, may change other
users' information and passwords with chpass(1).
When passed no options, aside from an optional username, chpass(1)
displays an editor containing user information. When the user
exists from the editor, the user database is updated with the new
information.
Example 8-3. Interactive chpass by Superuser
#Changing user database information for jru.
Login: jru
Password: *
Uid [#]: 1001
Gid [# or name]: 1001
Change [month day year]:
Expire [month day year]:
Class:
Home directory: /home/jru
Shell: /usr/local/bin/zsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:
The normal user can change only a small subset of this
information, and only for themselves.
Example 8-4. Interactive chpass by Normal User
#Changing user database information for jru.
Shell: /usr/local/bin/zsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:
Note: chfn(1) and chsh(1) are just links to chpass(1), as are
ypchpass(1), ypchfn(1), and ypchsh(1). NIS support is automatic,
so specifying the yp before the command is not necessary. If
this is confusing to you, do not worry, NIS will be covered in
Chapter 19.
--------------------------------------------------------------
8.6.4 passwd
passwd(1) is the usual way to change your own password as a user,
or another user's password as the superuser.
Note: To prevent accidental or unauthorized changes, the
original password must be entered before a new password can be
set.
Example 8-5. Changing Your Password
% passwd
Changing local password for jru.
Old password:
New password:
Retype new password:
passwd: updating the database...
passwd: done
Example 8-6. Changing Another User's Password as the Superuser
# passwd jru
Changing local password for jru.
New password:
Retype new password:
passwd: updating the database...
passwd: done
Note: As with chpass(1), yppasswd(1) is just a link to
passwd(1), so NIS works with either command.
--------------------------------------------------------------
8.6.5 pw
pw(8) is a command line utility to create, remove, modify, and
display users and groups. It functions as a front end to the
system user and group files. pw(8) has a very powerful set of
command line options that make it suitable for use in shell
scripts, but new users may find it more complicated than the other
commands presented here.
--------------------------------------------------------------
8.7 Limiting Users
If you have users, the ability to limit their system use may have
come to mind. DragonFly provides several ways an administrator can
limit the amount of system resources an individual may use. These
limits are divided into two sections: disk quotas, and other
resource limits.
Disk quotas limit disk usage to users, and they provide a way to
quickly check that usage without calculating it every time. Quotas
are discussed in Section 12.12.
The other resource limits include ways to limit the amount of CPU,
memory, and other resources a user may consume. These are defined
using login classes and are discussed here.
Login classes are defined in /etc/login.conf. The precise
semantics are beyond the scope of this section, but are described
in detail in the login.conf(5) manual page. It is sufficient to
say that each user is assigned to a login class (default by
default), and that each login class has a set of login
capabilities associated with it. A login capability is a
name=value pair, where name is a well-known identifier and value
is an arbitrary string processed accordingly depending on the
name. Setting up login classes and capabilities is rather
straight-forward and is also described in login.conf(5).
Resource limits are different from plain vanilla login
capabilities in two ways. First, for every limit, there is a soft
(current) and hard limit. A soft limit may be adjusted by the user
or application, but may be no higher than the hard limit. The
latter may be lowered by the user, but never raised. Second, most
resource limits apply per process to a specific user, not the user
as a whole. Note, however, that these differences are mandated by
the specific handling of the limits, not by the implementation of
the login capability framework (i.e., they are not really a
special case of login capabilities).
And so, without further ado, below are the most commonly used
resource limits (the rest, along with all the other login
capabilities, may be found in login.conf(5)).
coredumpsize
The limit on the size of a core file generated by a
program is, for obvious reasons, subordinate to other
limits on disk usage (e.g., filesize, or disk quotas).
Nevertheless, it is often used as a less-severe method of
controlling disk space consumption: since users do not
generate core files themselves, and often do not delete
them, setting this may save them from running out of disk
space should a large program (e.g., emacs) crash.
cputime
This is the maximum amount of CPU time a user's process
may consume. Offending processes will be killed by the
kernel.
Note: This is a limit on CPU time consumed, not
percentage of the CPU as displayed in some fields by
top(1) and ps(1). A limit on the latter is, at the time
of this writing, not possible, and would be rather
useless: legitimate use of a compiler, for instance, can
easily use almost 100% of a CPU for some time.
filesize
This is the maximum size of a file the user may possess.
Unlike disk quotas, this limit is enforced on individual
files, not the set of all files a user owns.
maxproc
This is the maximum number of processes a user may be
running. This includes foreground and background processes
alike. For obvious reasons, this may not be larger than
the system limit specified by the kern.maxproc sysctl(8).
Also note that setting this too small may hinder a user's
productivity: it is often useful to be logged in multiple
times or execute pipelines. Some tasks, such as compiling
a large program, also spawn multiple processes (e.g.,
make(1), cc(1), and other intermediate preprocessors).
memorylocked
This is the maximum amount a memory a process may have
requested to be locked into main memory (e.g., see
mlock(2)). Some system-critical programs, such as amd(8),
lock into main memory such that in the event of being
swapped out, they do not contribute to a system's trashing
in time of trouble.
memoryuse
This is the maximum amount of memory a process may consume
at any given time. It includes both core memory and swap
usage. This is not a catch-all limit for restricting
memory consumption, but it is a good start.
openfiles
This is the maximum amount of files a process may have
open. In DragonFly, files are also used to represent
sockets and IPC channels; thus, be careful not to set this
too low. The system-wide limit for this is defined by the
kern.maxfiles sysctl(8).
sbsize
This is the limit on the amount of network memory, and
thus mbufs, a user may consume. This originated as a
response to an old DoS attack by creating a lot of
sockets, but can be generally used to limit network
communications.
stacksize
This is the maximum size a process' stack may grow to.
This alone is not sufficient to limit the amount of memory
a program may use; consequently, it should be used in
conjunction with other limits.
There are a few other things to remember when setting resource
limits. Following are some general tips, suggestions, and
miscellaneous comments.
* Processes started at system startup by /etc/rc are assigned to
the daemon login class.
* Although the /etc/login.conf that comes with the system is a
good source of reasonable values for most limits, only you,
the administrator, can know what is appropriate for your
system. Setting a limit too high may open your system up to
abuse, while setting it too low may put a strain on
productivity.
* Users of the X Window System (X11) should probably be granted
more resources than other users. X11 by itself takes a lot of
resources, but it also encourages users to run more programs
simultaneously.
* Remember that many limits apply to individual processes, not
the user as a whole. For example, setting openfiles to 50
means that each process the user runs may open up to 50 files.
Thus, the gross amount of files a user may open is the value
of openfiles multiplied by the value of maxproc. This also
applies to memory consumption.
For further information on resource limits and login classes and
capabilities in general, please consult the relevant manual pages:
cap_mkdb(1), getrlimit(2), login.conf(5).
--------------------------------------------------------------
8.8 Personalizing Users
Localization is an environment set up by the system administrator
or user to accommodate different languages, character sets, date
and time standards, and so on. This is discussed in the
localization chapter.
--------------------------------------------------------------
8.9 Groups
A group is simply a list of users. Groups are identified by their
group name and GID (Group ID). In DragonFly (and most other UNIX
like systems), the two factors the kernel uses to decide whether a
process is allowed to do something is its user ID and list of
groups it belongs to. Unlike a user ID, a process has a list of
groups associated with it. You may hear some things refer to the
``group ID'' of a user or process; most of the time, this just
means the first group in the list.
The group name to group ID map is in /etc/group. This is a plain
text file with four colon-delimited fields. The first field is the
group name, the second is the encrypted password, the third the
group ID, and the fourth the comma-delimited list of members. It
can safely be edited by hand (assuming, of course, that you do not
make any syntax errors!). For a more complete description of the
syntax, see the group(5) manual page.
If you do not want to edit /etc/group manually, you can use the
pw(8) command to add and edit groups. For example, to add a group
called teamtwo and then confirm that it exists you can use:
Example 8-7. Adding a Group Using pw(8)
# pw groupadd teamtwo
# pw groupshow teamtwo
teamtwo:*:1100:
The number 1100 above is the group ID of the group teamtwo. Right
now, teamtwo has no members, and is thus rather useless. Let's
change that by inviting jru to the teamtwo group.
Example 8-8. Adding Somebody to a Group Using pw(8)
# pw groupmod teamtwo -M jru
# pw groupshow teamtwo
teamtwo:*:1100:jru
The argument to the -M option is a comma-delimited list of users
who are members of the group. From the preceding sections, we know
that the password file also contains a group for each user. The
latter (the user) is automatically added to the group list by the
system; the user will not show up as a member when using the
groupshow command to pw(8), but will show up when the information
is queried via id(1) or similar tool. In other words, pw(8) only
manipulates the /etc/group file; it will never attempt to read
additionally data from /etc/passwd.
Example 8-9. Using id(1) to Determine Group Membership
% id jru
uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)
As you can see, jru is a member of the groups jru and teamtwo.
For more information about pw(8), see its manual page, and for
more information on the format of /etc/group, consult the group(5)
manual page.
--------------------------------------------------------------
Chapter 9 Configuring the DragonFly Kernel
Updated and restructured by Jim Mock. Originally contributed by
Jake Hamby.
9.1 Synopsis
The kernel is the core of the DragonFly operating system. It is
responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While more and more of
DragonFly becomes dynamically configurable it is still
occasionally necessary to reconfigure and recompile your kernel.
After reading this chapter, you will know:
* Why you might need to build a custom kernel.
* How to write a kernel configuration file, or alter an existing
configuration file.
* How to use the kernel configuration file to create and build a
new kernel.
* How to install the new kernel.
* How to create any entries in /dev that may be required.
* How to troubleshoot if things go wrong.
--------------------------------------------------------------
9.2 Why Build a Custom Kernel?
Traditionally, DragonFly has had what is called a ``monolithic''
kernel. This means that the kernel was one large program,
supported a fixed list of devices, and if you wanted to change the
kernel's behavior then you had to compile a new kernel, and then
reboot your computer with the new kernel.
Today, DragonFly is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be
dynamically loaded and unloaded from the kernel as necessary. This
allows the kernel to adapt to new hardware suddenly becoming
available (such as PCMCIA cards in a laptop), or for new
functionality to be brought into the kernel that was not necessary
when the kernel was originally compiled. This is known as a
modular kernel. Colloquially these are called KLDs.
Despite this, it is still necessary to carry out some static
kernel configuration. In some cases this is because the
functionality is so tied to the kernel that it can not be made
dynamically loadable. In others it may simply be because no one
has yet taken the time to write a dynamic loadable kernel module
for that functionality yet.
Building a custom kernel is one of the most important rites of
passage nearly every UNIX user must endure. This process, while
time consuming, will provide many benefits to your DragonFly
system. Unlike the GENERIC kernel, which must support a wide range
of hardware, a custom kernel only contains support for your PC's
hardware. This has a number of benefits, such as:
* Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your
system to boot will decrease dramatically.
* Less memory usage. A custom kernel often uses less memory than
the GENERIC kernel, which is important because the kernel must
always be present in real memory. For this reason, a custom
kernel is especially useful on a system with a small amount of
RAM.
* Additional hardware support. A custom kernel allows you to add
in support for devices such as sound cards, which are not
present in the GENERIC kernel.
--------------------------------------------------------------
9.3 Building and Installing a Custom Kernel
First, let us take a quick tour of the kernel build directory. All
directories mentioned will be relative to the main /usr/src/sys
directory, which is also accessible through /sys. There are a
number of subdirectories here representing different parts of the
kernel, but the most important, for our purposes, are arch/conf,
where you will edit your custom kernel configuration, and compile,
which is the staging area where your kernel will be built. arch
represents either i386 or amd64, at this point in development.
Everything inside a particular architecture's directory deals with
that architecture only; the rest of the code is common to all
platforms to which DragonFly could potentially be ported. Notice
the logical organization of the directory structure, with each
supported device, file system, and option in its own subdirectory.
Note: If there is not a /usr/src/sys directory on your system,
then the kernel source has not been installed. The easiest way
to do this is via cvsup.
Next, move to the arch/conf directory and copy the GENERIC
configuration file to the name you want to give your kernel. For
example:
# cd /usr/src/sys/i386/conf
# cp GENERIC MYKERNEL
Traditionally, this name is in all capital letters and, if you are
maintaining multiple DragonFly machines with different hardware,
it is a good idea to name it after your machine's hostname. We
will call it MYKERNEL for the purpose of this example.
Tip: Storing your kernel config file directly under /usr/src can
be a bad idea. If you are experiencing problems it can be
tempting to just delete /usr/src and start again. Five seconds
after you do that you realize that you have deleted your custom
kernel config file. Do not edit GENERIC directly, as it may get
overwritten the next time you update your source tree, and your
kernel modifications will be lost.
You might want to keep your kernel config file elsewhere, and
then create a symbolic link to the file in the i386 directory.
For example:
# cd /usr/src/sys/i386/conf
# mkdir /root/kernels
# cp GENERIC /root/kernels/MYKERNEL
# ln -s /root/kernels/MYKERNEL
Note: You must execute these and all of the following commands
under the root account or you will get permission denied errors.
Now, edit MYKERNEL with your favorite text editor. If you are just
starting out, the only editor available will probably be vi, which
is too complex to explain here, but is covered well in many books
in the bibliography. However, DragonFly does offer an easier
editor called ee which, if you are a beginner, should be your
editor of choice. Feel free to change the comment lines at the top
to reflect your configuration or the changes you have made to
differentiate it from GENERIC.
If you have built a kernel under SunOS(TM) or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the GENERIC configuration file might seem
overwhelming to you, so follow the descriptions in the
Configuration File section slowly and carefully.
Note: Be sure to always check the file /usr/src/UPDATING, before
you perform any update steps, in the case you sync your source
tree with the latest sources of the DragonFly project. In this
file all important issues with updating DragonFly are typed out.
/usr/src/UPDATING always fits your version of the DragonFly
source, and is therefore more accurate for new information than
the handbook.
Building a Kernel
1. Change to the /usr/src directory.
# cd /usr/src
2. Compile the kernel.
# make buildkernel KERNCONF=MYKERNEL
3. Install the new kernel.
# make installkernel KERNCONF=MYKERNEL
If you have not upgraded your source tree in any way since the
last time you successfully completed a buildworld-installworld
cycle (you have not run CVSup), then it is safe to use the
quickworld and quickkernel, buildworld, buildkernel sequence.
The new kernel will be copied to the root directory as /kernel and
the old kernel will be moved to /kernel.old. Now, shutdown the
system and reboot to use your new kernel. In case something goes
wrong, there are some troubleshooting instructions at the end of
this chapter. Be sure to read the section which explains how to
recover in case your new kernel does not boot.
Note: If you have added any new devices (such as sound cards),
you may have to add some device nodes to your /dev directory
before you can use them. For more information, take a look at
Making Device Nodes section later on in this chapter.
--------------------------------------------------------------
9.4 The Configuration File
The general format of a configuration file is quite simple. Each
line contains a keyword and one or more arguments. For simplicity,
most lines only contain one argument. Anything following a # is
considered a comment and ignored. The following sections describe
each keyword, generally in the order they are listed in GENERIC,
although some related keywords have been grouped together in a
single section (such as Networking) even though they are actually
scattered throughout the GENERIC file. An exhaustive list of
options and more detailed explanations of the device lines is
present in the LINT configuration file, located in the same
directory as GENERIC. If you are in doubt as to the purpose or
necessity of a line, check first in LINT.
The following is an example GENERIC kernel configuration file with
various additional comments where needed for clarity. This example
should match your copy in /usr/src/sys/i386/conf/GENERIC fairly
closely. For details of all the possible kernel options, see
/usr/src/sys/i386/conf/LINT.
#
#
# GENERIC -- Generic kernel configuration file for DragonFly/i386
#
# Check the LINT configuration file in sys/i386/conf, for an
# exhaustive list of options.
#
# $DragonFly: src/sys/i386/conf/GENERIC,v 1.17 2004/06/25 05:09:38 hmp Exp $
The following are the mandatory keywords required in every kernel
you build:
machine i386
This is the machine architecture. It must be either i386, or
amd64.
cpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPU
The above option specifies the type of CPU you have in your
system. You may have multiple instances of the CPU line (i.e., you
are not sure whether you should use I586_CPU or I686_CPU),
however, for a custom kernel, it is best to specify only the CPU
you have. If you are unsure of your CPU type, you can check the
/var/run/dmesg.boot file to view your boot up messages.
ident GENERIC
This is the identification of the kernel. You should change this
to whatever you named your kernel, i.e. MYKERNEL if you have
followed the instructions of the previous examples. The value you
put in the ident string will print when you boot up the kernel, so
it is useful to give the new kernel a different name if you want
to keep it separate from your usual kernel (i.e. you want to build
an experimental kernel).
maxusers n
The maxusers option sets the size of a number of important system
tables. This number is supposed to be roughly equal to the number
of simultaneous users you expect to have on your machine.
(Recommended) The system will auto-tune this setting for you if
you explicitly set it to 0[9]. If you want to manage it yourself
you will want to set maxusers to at least 4, especially if you are
using the X Window System or compiling software. The reason is
that the most important table set by maxusers is the maximum
number of processes, which is set to 20 + 16 * maxusers, so if you
set maxusers to 1, then you can only have 36 simultaneous
processes, including the 18 or so that the system starts up at
boot time, and the 15 or so you will probably create when you
start the X Window System. Even a simple task like reading a
manual page will start up nine processes to filter, decompress,
and view it. Setting maxusers to 64 will allow you to have up to
1044 simultaneous processes, which should be enough for nearly all
uses. If, however, you see the dreaded proc table full error when
trying to start another program, or are running a server with a
large number of simultaneous users, you can always increase the
number and rebuild.
Note: maxusers does not limit the number of users which can log
into your machine. It simply sets various table sizes to
reasonable values considering the maximum number of users you
will likely have on your system and how many processes each of
them will be running. One keyword which does limit the number of
simultaneous remote logins and X terminal windows is
pseudo-device pty 16.
# Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13
npx0 is the interface to the floating point math unit in
DragonFly, which is either the hardware co-processor or the
software math emulator. This is not optional.
# Pseudo devices - the number indicates how many units to allocate.
pseudo-device loop # Network loopback
This is the generic loopback device for TCP/IP. If you telnet or
FTP to localhost (a.k.a., 127.0.0.1) it will come back at you
through this device. This is mandatory.
Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.
#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
The normal build process of the DragonFly does not include
debugging information when building the kernel and strips most
symbols after the resulting kernel is linked, to save some space
at the install location. If you are going to do tests of kernels
in the DEVELOPMENT branch or develop changes of your own for the
DragonFly kernel, you might want to uncomment this line. It will
enable the use of the -g option which enables debugging
information when passed to gcc(1).
options MATH_EMULATE #Support for x87 emulation
This line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line out.
Note: The normal math co-processor emulation routines that come
with DragonFly are not very accurate. If you do not have a math
co-processor, and you need the best accuracy, it is recommended
that you change this option to GPL_MATH_EMULATE to use the GNU
math support, which is not included by default for licensing
reasons.
options INET #InterNETworking
Networking support. Leave this in, even if you do not plan to be
connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.
options INET6 #IPv6 communications protocols
This enables the IPv6 communication protocols.
options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]
This is the basic hard drive Filesystem. Leave it in if you boot
from the hard disk.
options UFS_DIRHASH #Improve performance on big directories
This option includes functionality to speed up disk operations on
large directories, at the expense of using additional memory. You
would normally keep this for a large server, or interactive
workstation, and remove it if you are using DragonFly on a smaller
system where memory is at a premium and disk access speed is less
important, such as a firewall.
options SOFTUPDATES #Enable FFS Soft Updates support
This option enables Soft Updates in the kernel, this will help
speed up write access on the disks. Even when this functionality
is provided by the kernel, it must be turned on for specific
disks. Review the output from mount(8) to see if Soft Updates is
enabled for your system disks. If you do not see the soft-updates
option then you will need to activate it using the tunefs(8) (for
existing filesystems) or newfs(8) (for new filesystems) commands.
options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root device
This is the memory-mapped filesystem. This is basically a RAM disk
for fast storage of temporary files, useful if you have a lot of
swap space that you want to take advantage of. A perfect place to
mount an MFS partition is on the /tmp directory, since many
programs store temporary data here. To mount an MFS RAM disk on
/tmp, add the following line to /etc/fstab:
/dev/ad1s2b /tmp mfs rw 0 0
Now you simply need to either reboot, or run the command mount
/tmp.
options NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS required
The network Filesystem. Unless you plan to mount partitions from a
UNIX file server over TCP/IP, you can comment these out.
options MSDOSFS #MSDOS Filesystem
The MS-DOS Filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this
out. It will be automatically loaded the first time you mount a
DOS partition, as described above. Also, the excellent mtools
software (in pkgsrc) allows you to access DOS floppies without
having to mount and unmount them (and does not require MSDOSFS at
all).
options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 required
The ISO 9660 Filesystem for CDROMs. Comment it out if you do not
have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this Filesystem.
options PROCFS #Process filesystem
The process filesystem. This is a ``pretend'' filesystem mounted
on /proc which allows programs like ps(1) to give you more
information on what processes are running.
options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]
Compatibility with 4.3BSD. Leave this in; some programs will act
strangely if you comment this out.
options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI
This causes the kernel to pause for 15 seconds before probing each
SCSI device in your system. If you only have IDE hard drives, you
can ignore this, otherwise you will probably want to lower this
number, perhaps to five seconds (5000 ms), to speed up booting. Of
course, if you do this, and DragonFly has trouble recognizing your
SCSI devices, you will have to raise it back up.
options UCONSOLE #Allow users to grab the console
Allow users to grab the console, which is useful for X users. For
example, you can create a console xterm by typing xterm -C, which
will display any write(1), talk(1), and any other messages you
receive, as well as any console messages sent by the kernel.
options USERCONFIG #boot -c editor
This option allows you to boot the configuration editor from the
boot menu.
options VISUAL_USERCONFIG #visual boot -c editor
This option allows you to boot the visual configuration editor
from the boot menu.
options KTRACE #ktrace(1) support
This enables kernel process tracing, which is useful in debugging.
options SYSVSHM #SYSV-style shared memory
This option provides for System V shared memory. The most common
use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of
for extra speed. If you use X, you will definitely want to include
this.
options SYSVSEM #SYSV-style semaphores
Support for System V semaphores. Less commonly used but only adds
a few hundred bytes to the kernel.
options SYSVMSG #SYSV-style message queues
Support for System V messages. Again, only adds a few hundred
bytes to the kernel.
Note: The ipcs(1) command will list any processes using each of
these System V facilities.
options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULING
Real-time extensions added in the 1993 POSIX(R). Certain
applications in the ports collection use these (such as
StarOffice).
options ICMP_BANDLIM #Rate limit bad replies
This option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine
from denial of service packet attacks.
# To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/O
The above are both required for SMP support.
device isa
All PCs supported by DragonFly have one of these. Do not remove,
even if you have no ISA slots. If you have an IBM PS/2 (Micro
Channel Architecture), DragonFly provides some limited support at
this time. For more information about the MCA support, see
/usr/src/sys/i386/conf/LINT.
device eisa
Include this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the
EISA bus.
device pci
Include this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.
device agp
Include this if you have an AGP card in the system. This will
enable support for AGP, and AGP GART for boards which have these
features.
# Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1
This is the floppy drive controller. fd0 is the A: floppy drive,
and fd1 is the B: drive.
device ata
This driver supports all ATA and ATAPI devices. You only need one
device ata line for the kernel to detect all PCI ATA/ATAPI devices
on modern machines.
device atadisk # ATA disk drives
This is needed along with device ata for ATA disk drives.
device atapicd # ATAPI CDROM drives
This is needed along with device ata for ATAPI CDROM drives.
device atapifd # ATAPI floppy drives
This is needed along with device ata for ATAPI floppy drives.
device atapist # ATAPI tape drives
This is needed along with device ata for ATAPI tape drives.
options ATA_STATIC_ID #Static device numbering
This makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.
# ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15
Use the above for older, non-PCI systems.
# SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?
SCSI controllers. Comment out any you do not have in your system.
If you have an IDE only system, you can remove these altogether.
# SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)
SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.
Note: The USB umass(4) driver (and a few other drivers) use the
SCSI subsystem even though they are not real SCSI devices.
Therefore make sure not to remove SCSI support, if any such
drivers are included in the kernel configuration.
# RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 family
Supported RAID controllers. If you do not have any of these, you
can comment them out or remove them.
# atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBD
The keyboard controller (atkbdc) provides I/O services for the AT
keyboard and PS/2 style pointing devices. This controller is
required by the keyboard driver (atkbd) and the PS/2 pointing
device driver (psm).
device atkbd0 at atkbdc? irq 1
The atkbd driver, together with atkbdc controller, provides access
to the AT 84 keyboard or the AT enhanced keyboard which is
connected to the AT keyboard controller.
device psm0 at atkbdc? irq 12
Use this device if your mouse plugs into the PS/2 mouse port.
device vga0 at isa?
The video card driver.
# splash screen/screen saver
pseudo-device splash
Splash screen at start up! Screen savers require this too.
# syscons is the default console driver, resembling an SCO console
device sc0 at isa?
sc0 is the default console driver, which resembles a SCO console.
Since most full-screen programs access the console through a
terminal database library like termcap, it should not matter
whether you use this or vt0, the VT220 compatible console driver.
When you log in, set your TERM variable to scoansi if full-screen
programs have trouble running under this console.
# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-std
This is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with sc0. Also set your TERM variable to vt100
or vt220 when you log in. This driver might also prove useful when
connecting to a large number of different machines over the
network, where termcap or terminfo entries for the sc0 device are
often not available -- vt100 should be available on virtually any
platform.
# Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power Management
Advanced Power Management support. Useful for laptops.
# PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
PCMCIA support. You want this if you are using a laptop.
# Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9
These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.
Note: If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from DragonFly. If you have a multiport serial card, check the
manual page for sio(4) for more information on the proper values
for these lines. Some video cards (notably those based on S3
chips) use IO addresses in the form of 0x*2e8, and since many
cheap serial cards do not fully decode the 16-bit IO address
space, they clash with these cards making the COM4 port
practically unavailable.
Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.
# Parallel port
device ppc0 at isa? irq 7
This is the ISA-bus parallel port interface.
device ppbus # Parallel port bus (required)
Provides support for the parallel port bus.
device lpt # Printer
Support for parallel port printers.
Note: All three of the above are required to enable parallel
printer support.
device plip # TCP/IP over parallel
This is the driver for the parallel network interface.
device ppi # Parallel port interface device
The general-purpose I/O (``geek port'') + IEEE1284 I/O.
#device vpo # Requires scbus and da
This is for an Iomega Zip drive. It requires scbus and da support.
Best performance is achieved with ports in EPP 1.9 mode.
# PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (``Tulip'')
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 ``EPIC'')
device vx # 3Com 3c590, 3c595 (``Vortex'')
device wx # Intel Gigabit Ethernet Card (``Wiseman'')
Various PCI network card drivers. Comment out or remove any of
these not present in your system.
# PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus support
MII bus support is required for some PCI 10/100 Ethernet NICs,
namely those which use MII-compliant transceivers or implement
transceiver control interfaces that operate like an MII. Adding
device miibus to the kernel config pulls in support for the
generic miibus API and all of the PHY drivers, including a generic
one for PHYs that are not specifically handled by an individual
driver.
device dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (``Starfire'')
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (``Boomerang'', ``Cyclone'')
Drivers that use the MII bus controller code.
# ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?
ISA Ethernet drivers. See /usr/src/sys/i386/conf/LINT for which
cards are supported by which driver.
pseudo-device ether # Ethernet support
ether is only needed if you have an Ethernet card. It includes
generic Ethernet protocol code.
pseudo-device sl 1 # Kernel SLIP
sl is for SLIP support. This has been almost entirely supplanted
by PPP, which is easier to set up, better suited for
modem-to-modem connection, and more powerful. The number after sl
specifies how many simultaneous SLIP sessions to support.
pseudo-device ppp 1 # Kernel PPP
This is for kernel PPP support for dial-up connections. There is
also a version of PPP implemented as a userland application that
uses tun and offers more flexibility and features such as demand
dialing. The number after ppp specifies how many simultaneous PPP
connections to support. .
device tun # Packet tunnel.
This is used by the userland PPP software. A number after tun
specifies the number of simultaneous PPP sessions to support. See
the PPP section of this book for more information.
pseudo-device pty # Pseudo-ttys (telnet etc)
This is a ``pseudo-terminal'' or simulated login port. It is used
by incoming telnet and rlogin sessions, xterm, and some other
applications such as Emacs. The number after pty indicates the
number of ptys to create. If you need more than the default of 16
simultaneous xterm windows and/or remote logins, be sure to
increase this number accordingly, up to a maximum of 256.
pseudo-device md # Memory ``disks''
Memory disk pseudo-devices.
pseudo-device gif # IPv6 and IPv4 tunneling
This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
pseudo-device faith # IPv6-to-IPv4 relaying (translation)
This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.
# The `bpf' device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filter
This is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing
every packet on a broadcast network (e.g., an Ethernet). These
packets can be captured to disk and or examined with the
tcpdump(1) program.
Note: The bpf(4) device is also used by dhclient(8) to obtain
the IP address of the default router (gateway) and so on. If you
use DHCP, leave this uncommented.
# USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # ``Human Interface Devices''
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernet
Support for various USB devices.
For more information and additional devices supported by
DragonFly, see /usr/src/sys/i386/conf/LINT.
--------------------------------------------------------------
9.5 Making Device Nodes
Almost every device in the kernel has a corresponding ``node''
entry in the /dev directory. These nodes look like regular files,
but are actually special entries into the kernel which programs
use to access the device. The shell script /dev/MAKEDEV, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create all of them, so when you add support for a new device, it
pays to make sure that the appropriate entries are in this
directory, and if not, add them. Here is a simple example:
Suppose you add the IDE CD-ROM support to the kernel. The line to
add is:
device acd0
This means that you should look for some entries that start with
acd0 in the /dev directory, possibly followed by a letter, such as
c, or preceded by the letter r, which means a ``raw'' device. It
turns out that those files are not there, so you must change to
the /dev directory and type:
# sh MAKEDEV acd0
When this script finishes, you will find that there are now acd0c
and racd0c entries in /dev so you know that it executed correctly.
For sound cards, the following command creates the appropriate
entries:
# sh MAKEDEV snd0
Note: When creating device nodes for devices such as sound
cards, if other people have access to your machine, it may be
desirable to protect the devices from outside access by adding
them to the /etc/fbtab file. See fbtab(5) for more information.
Follow this simple procedure for any other non-GENERIC devices
which do not have entries.
Note: All SCSI controllers use the same set of /dev entries, so
you do not need to create these. Also, network cards and
SLIP/PPP pseudo-devices do not have entries in /dev at all, so
you do not have to worry about these either.
--------------------------------------------------------------
9.6 If Something Goes Wrong
There are five categories of trouble that can occur when building
a custom kernel. They are:
config fails:
If the config(8) command fails when you give it your
kernel description, you have probably made a simple error
somewhere. Fortunately, config(8) will print the line
number that it had trouble with, so you can quickly skip
to it with vi. For example, if you see:
config: line 17: syntax error
You can skip to the problem in vi by typing 17G in command
mode. Make sure the keyword is typed correctly, by
comparing it to the GENERIC kernel or another reference.
make fails:
If the make command fails, it usually signals an error in
your kernel description, but not severe enough for
config(8) to catch it. Again, look over your
configuration, and if you still cannot resolve the
problem, send mail to the DragonFly Bugs mailing list with
your kernel configuration, and it should be diagnosed very
quickly.
Installing the new kernel fails:
If the kernel compiled fine, but failed to install (the
make install or make installkernel command failed), the
first thing to check is if your system is running at
securelevel 1 or higher (see init(8)). The kernel
installation tries to remove the immutable flag from your
kernel and set the immutable flag on the new one. Since
securelevel 1 or higher prevents unsetting the immutable
flag for any files on the system, the kernel installation
needs to be performed at securelevel 0 or lower.
The kernel does not boot:
If your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, DragonFly has an
excellent mechanism for recovering from incompatible
kernels. Simply choose the kernel you want to boot from at
the DragonFly boot loader. You can access this when the
system counts down from 10. Hit any key except for the
Enter key, type unload and then type boot kernel.old, or
the filename of any other kernel that will boot properly.
When reconfiguring a kernel, it is always a good idea to
keep a kernel that is known to work on hand.
After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the /var/log/messages file which records,
among other things, all of the kernel messages from every
successful boot. Also, the dmesg(8) command will print the
kernel messages from the current boot.
Note: If you are having trouble building a kernel, make
sure to keep a GENERIC, or some other kernel that is
known to work on hand as a different name that will not
get erased on the next build. You cannot rely on
kernel.old because when installing a new kernel,
kernel.old is overwritten with the last installed kernel
which may be non-functional. Also, as soon as possible,
move the working kernel to the proper kernel location or
commands such as ps(1) will not work properly. The
proper command to ``unlock'' the kernel file that make
installs (in order to move another kernel back
permanently) is:
# chflags noschg /kernel
If you find you cannot do this, you are probably running
at a securelevel(8) greater than zero. Edit
kern_securelevel in /etc/rc.conf and set it to -1, then
reboot. You can change it back to its previous setting
when you are happy with your new kernel.
And, if you want to ``lock'' your new kernel into place,
or any file for that matter, so that it cannot be moved
or tampered with:
# chflags schg /kernel
The kernel works, but ps(1) does not work any more:
If you have installed a different version of the kernel
from the one that the system utilities have been built
with, many system-status commands like ps(1) and vmstat(8)
will not work any more. You must recompile the libkvm
library as well as these utilities. This is one reason it
is not normally a good idea to use a different version of
the kernel from the rest of the operating system.
--------------------------------------------------------------
Chapter 10 Security
Much of this chapter has been taken from the security(7) manual
page by Matthew Dillon.
--------------------------------------------------------------
10.1 Synopsis
This chapter will provide a basic introduction to system security
concepts, some general good rules of thumb, and some advanced
topics under DragonFly. A lot of the topics covered here can be
applied to system and Internet security in general as well. The
Internet is no longer a ``friendly'' place in which everyone wants
to be your kind neighbor. Securing your system is imperative to
protect your data, intellectual property, time, and much more from
the hands of hackers and the like.
DragonFly provides an array of utilities and mechanisms to ensure
the integrity and security of your system and network.
After reading this chapter, you will know:
* Basic system security concepts, in respect to DragonFly.
* About the various crypt mechanisms available in DragonFly,
such as DES and MD5.
* How to set up one-time password authentication.
* How to set up KerberosIV.
* How to set up Kerberos5.
* How to create firewalls using IPFW.
* How to configure IPsec and create a VPN between
DragonFly/Windows machines.
* How to configure and use OpenSSH, DragonFly's SSH
implementation.
Before reading this chapter, you should:
* Understand basic DragonFly and Internet concepts.
--------------------------------------------------------------
10.2 Introduction
Security is a function that begins and ends with the system
administrator. While all BSD UNIX multi-user systems have some
inherent security, the job of building and maintaining additional
security mechanisms to keep those users ``honest'' is probably one
of the single largest undertakings of the sysadmin. Machines are
only as secure as you make them, and security concerns are ever
competing with the human necessity for convenience. UNIX systems,
in general, are capable of running a huge number of simultaneous
processes and many of these processes operate as servers --
meaning that external entities can connect and talk to them. As
yesterday's mini-computers and mainframes become today's desktops,
and as computers become networked and internetworked, security
becomes an even bigger issue.
Security is best implemented through a layered ``onion'' approach.
In a nutshell, what you want to do is to create as many layers of
security as are convenient and then carefully monitor the system
for intrusions. You do not want to overbuild your security or you
will interfere with the detection side, and detection is one of
the single most important aspects of any security mechanism. For
example, it makes little sense to set the schg flags (see
chflags(1)) on every system binary because while this may
temporarily protect the binaries, it prevents an attacker who has
broken in from making an easily detectable change that may result
in your security mechanisms not detecting the attacker at all.
System security also pertains to dealing with various forms of
attack, including attacks that attempt to crash, or otherwise make
a system unusable, but do not attempt to compromise the root
account (``break root''). Security concerns can be split up into
several categories:
1. Denial of service attacks.
2. User account compromises.
3. Root compromise through accessible servers.
4. Root compromise via user accounts.
5. Backdoor creation.
A denial of service attack is an action that deprives the machine
of needed resources. Typically, DoS attacks are brute-force
mechanisms that attempt to crash or otherwise make a machine
unusable by overwhelming its servers or network stack. Some DoS
attacks try to take advantage of bugs in the networking stack to
crash a machine with a single packet. The latter can only be fixed
by applying a bug fix to the kernel. Attacks on servers can often
be fixed by properly specifying options to limit the load the
servers incur on the system under adverse conditions. Brute-force
network attacks are harder to deal with. A spoofed-packet attack,
for example, is nearly impossible to stop, short of cutting your
system off from the Internet. It may not be able to take your
machine down, but it can saturate your Internet connection.
A user account compromise is even more common than a DoS attack.
Many sysadmins still run standard telnetd, rlogind, rshd, and ftpd
servers on their machines. These servers, by default, do not
operate over encrypted connections. The result is that if you have
any moderate-sized user base, one or more of your users logging
into your system from a remote location (which is the most common
and convenient way to login to a system) will have his or her
password sniffed. The attentive system admin will analyze his
remote access logs looking for suspicious source addresses even
for successful logins.
One must always assume that once an attacker has access to a user
account, the attacker can break root. However, the reality is that
in a well secured and maintained system, access to a user account
does not necessarily give the attacker access to root. The
distinction is important because without access to root the
attacker cannot generally hide his tracks and may, at best, be
able to do nothing more than mess with the user's files, or crash
the machine. User account compromises are very common because
users tend not to take the precautions that sysadmins take.
System administrators must keep in mind that there are potentially
many ways to break root on a machine. The attacker may know the
root password, the attacker may find a bug in a root-run server
and be able to break root over a network connection to that
server, or the attacker may know of a bug in a suid-root program
that allows the attacker to break root once he has broken into a
user's account. If an attacker has found a way to break root on a
machine, the attacker may not have a need to install a backdoor.
Many of the root holes found and closed to date involve a
considerable amount of work by the attacker to cleanup after
himself, so most attackers install backdoors. A backdoor provides
the attacker with a way to easily regain root access to the
system, but it also gives the smart system administrator a
convenient way to detect the intrusion. Making it impossible for
an attacker to install a backdoor may actually be detrimental to
your security, because it will not close off the hole the attacker
found to break in the first place.
Security remedies should always be implemented with a
multi-layered ``onion peel'' approach and can be categorized as
follows:
1. Securing root and staff accounts.
2. Securing root -- root-run servers and suid/sgid binaries.
3. Securing user accounts.
4. Securing the password file.
5. Securing the kernel core, raw devices, and filesystems.
6. Quick detection of inappropriate changes made to the system.
7. Paranoia.
The next section of this chapter will cover the above bullet items
in greater depth.
--------------------------------------------------------------
10.3 Securing DragonFly
Command vs. Protocol: Throughout this document, we will use bold
text to refer to a command or application. This is used for
instances such as ssh, since it is a protocol as well as
command.
The sections that follow will cover the methods of securing your
DragonFly system that were mentioned in the last section of this
chapter.
--------------------------------------------------------------
10.3.1 Securing the root Account and Staff Accounts
First off, do not bother securing staff accounts if you have not
secured the root account. Most systems have a password assigned to
the root account. The first thing you do is assume that the
password is always compromised. This does not mean that you should
remove the password. The password is almost always necessary for
console access to the machine. What it does mean is that you
should not make it possible to use the password outside of the
console or possibly even with the su(1) command. For example, make
sure that your pty's are specified as being insecure in the
/etc/ttys file so that direct root logins via telnet or rlogin are
disallowed. If using other login services such as sshd, make sure
that direct root logins are disabled there as well. You can do
this by editing your /etc/ssh/sshd_config file, and making sure
that PermitRootLogin is set to NO. Consider every access method --
services such as FTP often fall through the cracks. Direct root
logins should only be allowed via the system console.
Of course, as a sysadmin you have to be able to get to root, so we
open up a few holes. But we make sure these holes require
additional password verification to operate. One way to make root
accessible is to add appropriate staff accounts to the wheel group
(in /etc/group). The staff members placed in the wheel group are
allowed to su to root. You should never give staff members native
wheel access by putting them in the wheel group in their password
entry. Staff accounts should be placed in a staff group, and then
added to the wheel group via the /etc/group file. Only those staff
members who actually need to have root access should be placed in
the wheel group. It is also possible, when using an authentication
method such as Kerberos, to use Kerberos' .k5login file in the
root account to allow a ksu(1) to root without having to place
anyone at all in the wheel group. This may be the better solution
since the wheel mechanism still allows an intruder to break root
if the intruder has gotten hold of your password file and can
break into a staff account. While having the wheel mechanism is
better than having nothing at all, it is not necessarily the
safest option.
An indirect way to secure staff accounts, and ultimately root
access is to use an alternative login access method and do what is
known as ``starring'' out the encrypted password for the staff
accounts. Using the vipw(8) command, one can replace each instance
of an encrypted password with a single ``*'' character. This
command will update the /etc/master.passwd file and user/password
database to disable password-authenticated logins.
A staff account entry such as:
foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
Should be changed to this:
foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
This change will prevent normal logins from occurring, since the
encrypted password will never match ``*''. With this done, staff
members must use another mechanism to authenticate themselves such
as kerberos(1) or ssh(1) using a public/private key pair. When
using something like Kerberos, one generally must secure the
machines which run the Kerberos servers and your desktop
workstation. When using a public/private key pair with ssh, one
must generally secure the machine used to login from (typically
one's workstation). An additional layer of protection can be added
to the key pair by password protecting the key pair when creating
it with ssh-keygen(1). Being able to ``star'' out the passwords
for staff accounts also guarantees that staff members can only
login through secure access methods that you have set up. This
forces all staff members to use secure, encrypted connections for
all of their sessions, which closes an important hole used by many
intruders: sniffing the network from an unrelated, less secure
machine.
The more indirect security mechanisms also assume that you are
logging in from a more restrictive server to a less restrictive
server. For example, if your main box is running all sorts of
servers, your workstation should not be running any. In order for
your workstation to be reasonably secure you should run as few
servers as possible, up to and including no servers at all, and
you should run a password-protected screen blanker. Of course,
given physical access to a workstation an attacker can break any
sort of security you put on it. This is definitely a problem that
you should consider, but you should also consider the fact that
the vast majority of break-ins occur remotely, over a network,
from people who do not have physical access to your workstation or
servers.
Using something like Kerberos also gives you the ability to
disable or change the password for a staff account in one place,
and have it immediately affect all the machines on which the staff
member may have an account. If a staff member's account gets
compromised, the ability to instantly change his password on all
machines should not be underrated. With discrete passwords,
changing a password on N machines can be a mess. You can also
impose re-passwording restrictions with Kerberos: not only can a
Kerberos ticket be made to timeout after a while, but the Kerberos
system can require that the user choose a new password after a
certain period of time (say, once a month).
--------------------------------------------------------------
10.3.2 Securing Root-run Servers and SUID/SGID Binaries
The prudent sysadmin only runs the servers he needs to, no more,
no less. Be aware that third party servers are often the most
bug-prone. For example, running an old version of imapd or popper
is like giving a universal root ticket out to the entire world.
Never run a server that you have not checked out carefully. Many
servers do not need to be run as root. For example, the ntalk,
comsat, and finger daemons can be run in special user sandboxes. A
sandbox is not perfect, unless you go through a large amount of
trouble, but the onion approach to security still stands: If
someone is able to break in through a server running in a sandbox,
they still have to break out of the sandbox. The more layers the
attacker must break through, the lower the likelihood of his
success. Root holes have historically been found in virtually
every server ever run as root, including basic system servers. If
you are running a machine through which people only login via sshd
and never login via telnetd or rshd or rlogind, then turn off
those services!
DragonFly now defaults to running ntalkd, comsat, and finger in a
sandbox. Another program which may be a candidate for running in a
sandbox is named(8). /etc/defaults/rc.conf includes the arguments
necessary to run named in a sandbox in a commented-out form.
Depending on whether you are installing a new system or upgrading
an existing system, the special user accounts used by these
sandboxes may not be installed. The prudent sysadmin would
research and implement sandboxes for servers whenever possible.
There are a number of other servers that typically do not run in
sandboxes: sendmail, popper, imapd, ftpd, and others. There are
alternatives to some of these, but installing them may require
more work than you are willing to perform (the convenience factor
strikes again). You may have to run these servers as root and rely
on other mechanisms to detect break-ins that might occur through
them.
The other big potential root holes in a system are the suid-root
and sgid binaries installed on the system. Most of these binaries,
such as rlogin, reside in /bin, /sbin, /usr/bin, or /usr/sbin.
While nothing is 100% safe, the system-default suid and sgid
binaries can be considered reasonably safe. Still, root holes are
occasionally found in these binaries. A root hole was found in
Xlib in 1998 that made xterm (which is typically suid) vulnerable.
It is better to be safe than sorry and the prudent sysadmin will
restrict suid binaries, that only staff should run, to a special
group that only staff can access, and get rid of (chmod 000) any
suid binaries that nobody uses. A server with no display generally
does not need an xterm binary. Sgid binaries can be almost as
dangerous. If an intruder can break an sgid-kmem binary, the
intruder might be able to read /dev/kmem and thus read the
encrypted password file, potentially compromising any passworded
account. Alternatively an intruder who breaks group kmem can
monitor keystrokes sent through pty's, including pty's used by
users who login through secure methods. An intruder that breaks
the tty group can write to almost any user's tty. If a user is
running a terminal program or emulator with a keyboard-simulation
feature, the intruder can potentially generate a data stream that
causes the user's terminal to echo a command, which is then run as
that user.
--------------------------------------------------------------
10.3.3 Securing User Accounts
User accounts are usually the most difficult to secure. While you
can impose Draconian access restrictions on your staff and
``star'' out their passwords, you may not be able to do so with
any general user accounts you might have. If you do have
sufficient control, then you may win out and be able to secure the
user accounts properly. If not, you simply have to be more
vigilant in your monitoring of those accounts. Use of ssh and
Kerberos for user accounts is more problematic, due to the extra
administration and technical support required, but still a very
good solution compared to a crypted password file.
--------------------------------------------------------------
10.3.4 Securing the Password File
The only sure fire way is to * out as many passwords as you can
and use ssh or Kerberos for access to those accounts. Even though
the encrypted password file (/etc/spwd.db) can only be read by
root, it may be possible for an intruder to obtain read access to
that file even if the attacker cannot obtain root-write access.
Your security scripts should always check for and report changes
to the password file (see the Checking file integrity section
below).
--------------------------------------------------------------
10.3.5 Securing the Kernel Core, Raw Devices, and Filesystems
If an attacker breaks root he can do just about anything, but
there are certain conveniences. For example, most modern kernels
have a packet sniffing device driver built in. Under DragonFly it
is called the bpf device. An intruder will commonly attempt to run
a packet sniffer on a compromised machine. You do not need to give
the intruder the capability and most systems do not have the need
for the bpf device compiled in.
But even if you turn off the bpf device, you still have /dev/mem
and /dev/kmem to worry about. For that matter, the intruder can
still write to raw disk devices. Also, there is another kernel
feature called the module loader, kldload(8). An enterprising
intruder can use a KLD module to install his own bpf device, or
other sniffing device, on a running kernel. To avoid these
problems you have to run the kernel at a higher secure level, at
least securelevel 1. The securelevel can be set with a sysctl on
the kern.securelevel variable. Once you have set the securelevel
to 1, write access to raw devices will be denied and special
chflags flags, such as schg, will be enforced. You must also
ensure that the schg flag is set on critical startup binaries,
directories, and script files -- everything that gets run up to
the point where the securelevel is set. This might be overdoing
it, and upgrading the system is much more difficult when you
operate at a higher secure level. You may compromise and run the
system at a higher secure level but not set the schg flag for
every system file and directory under the sun. Another possibility
is to simply mount / and /usr read-only. It should be noted that
being too Draconian in what you attempt to protect may prevent the
all-important detection of an intrusion.
--------------------------------------------------------------
10.3.6 Checking File Integrity: Binaries, Configuration Files, Etc.
When it comes right down to it, you can only protect your core
system configuration and control files so much before the
convenience factor rears its ugly head. For example, using chflags
to set the schg bit on most of the files in / and /usr is probably
counterproductive, because while it may protect the files, it also
closes a detection window. The last layer of your security onion
is perhaps the most important -- detection. The rest of your
security is pretty much useless (or, worse, presents you with a
false sense of safety) if you cannot detect potential incursions.
Half the job of the onion is to slow down the attacker, rather
than stop him, in order to give the detection side of the equation
a chance to catch him in the act.
The best way to detect an incursion is to look for modified,
missing, or unexpected files. The best way to look for modified
files is from another (often centralized) limited-access system.
Writing your security scripts on the extra-secure limited-access
system makes them mostly invisible to potential attackers, and
this is important. In order to take maximum advantage you
generally have to give the limited-access box significant access
to the other machines in the business, usually either by doing a
read-only NFS export of the other machines to the limited-access
box, or by setting up ssh key-pairs to allow the limited-access
box to ssh to the other machines. Except for its network traffic,
NFS is the least visible method -- allowing you to monitor the
filesystems on each client box virtually undetected. If your
limited-access server is connected to the client boxes through a
switch, the NFS method is often the better choice. If your
limited-access server is connected to the client boxes through a
hub, or through several layers of routing, the NFS method may be
too insecure (network-wise) and using ssh may be the better choice
even with the audit-trail tracks that ssh lays.
Once you give a limited-access box, at least read access to the
client systems it is supposed to monitor, you must write scripts
to do the actual monitoring. Given an NFS mount, you can write
scripts out of simple system utilities such as find(1) and md5(1).
It is best to physically md5 the client-box files at least once a
day, and to test control files such as those found in /etc and
/usr/local/etc even more often. When mismatches are found,
relative to the base md5 information the limited-access machine
knows is valid, it should scream at a sysadmin to go check it out.
A good security script will also check for inappropriate suid
binaries and for new or deleted files on system partitions such as
/ and /usr.
When using ssh rather than NFS, writing the security script is
much more difficult. You essentially have to scp the scripts to
the client box in order to run them, making them visible, and for
safety you also need to scp the binaries (such as find) that those
scripts use. The ssh client on the client box may already be
compromised. All in all, using ssh may be necessary when running
over insecure links, but it is also a lot harder to deal with.
A good security script will also check for changes to user and
staff members access configuration files: .rhosts, .shosts,
.ssh/authorized_keys and so forth... files that might fall outside
the purview of the MD5 check.
If you have a huge amount of user disk space, it may take too long
to run through every file on those partitions. In this case,
setting mount flags to disallow suid binaries and devices on those
partitions is a good idea. The nodev and nosuid options (see
mount(8)) are what you want to look into. You should probably scan
them anyway, at least once a week, since the object of this layer
is to detect a break-in whether or not the break-in is effective.
Process accounting (see accton(8)) is a relatively low-overhead
feature of the operating system which might help as a
post-break-in evaluation mechanism. It is especially useful in
tracking down how an intruder has actually broken into a system,
assuming the file is still intact after the break-in occurs.
Finally, security scripts should process the log files, and the
logs themselves should be generated in as secure a manner as
possible -- remote syslog can be very useful. An intruder tries to
cover his tracks, and log files are critical to the sysadmin
trying to track down the time and method of the initial break-in.
One way to keep a permanent record of the log files is to run the
system console to a serial port and collect the information on a
continuing basis through a secure machine monitoring the consoles.
--------------------------------------------------------------
10.3.7 Paranoia
A little paranoia never hurts. As a rule, a sysadmin can add any
number of security features, as long as they do not affect
convenience, and can add security features that do affect
convenience with some added thought. Even more importantly, a
security administrator should mix it up a bit -- if you use
recommendations such as those given by this document verbatim, you
give away your methodologies to the prospective attacker who also
has access to this document.
--------------------------------------------------------------
10.3.8 Denial of Service Attacks
This section covers Denial of Service attacks. A DoS attack is
typically a packet attack. While there is not much you can do
about modern spoofed packet attacks that saturate your network,
you can generally limit the damage by ensuring that the attacks
cannot take down your servers.
1. Limiting server forks.
2. Limiting springboard attacks (ICMP response attacks, ping
broadcast, etc.).
3. Kernel Route Cache.
A common DoS attack is against a forking server that attempts to
cause the server to eat processes, file descriptors, and memory,
until the machine dies. inetd (see inetd(8)) has several options
to limit this sort of attack. It should be noted that while it is
possible to prevent a machine from going down, it is not generally
possible to prevent a service from being disrupted by the attack.
Read the inetd manual page carefully and pay specific attention to
the -c, -C, and -R options. Note that spoofed-IP attacks will
circumvent the -C option to inetd, so typically a combination of
options must be used. Some standalone servers have
self-fork-limitation parameters.
Sendmail has its -OMaxDaemonChildren option, which tends to work
much better than trying to use sendmail's load limiting options
due to the load lag. You should specify a MaxDaemonChildren
parameter, when you start sendmail, high enough to handle your
expected load, but not so high that the computer cannot handle
that number of sendmails without falling on its face. It is also
prudent to run sendmail in queued mode (-ODeliveryMode=queued) and
to run the daemon (sendmail -bd) separate from the queue-runs
(sendmail -q15m). If you still want real-time delivery you can run
the queue at a much lower interval, such as -q1m, but be sure to
specify a reasonable MaxDaemonChildren option for that sendmail to
prevent cascade failures.
Syslogd can be attacked directly and it is strongly recommended
that you use the -s option whenever possible, and the -a option
otherwise.
You should also be fairly careful with connect-back services such
as tcpwrapper's reverse-identd, which can be attacked directly.
You generally do not want to use the reverse-ident feature of
tcpwrappers for this reason.
It is a very good idea to protect internal services from external
access by firewalling them off at your border routers. The idea
here is to prevent saturation attacks from outside your LAN, not
so much to protect internal services from network-based root
compromise. Always configure an exclusive firewall, i.e.,
``firewall everything except ports A, B, C, D, and M-Z''. This way
you can firewall off all of your low ports except for certain
specific services such as named (if you are primary for a zone),
ntalkd, sendmail, and other Internet-accessible services. If you
try to configure the firewall the other way -- as an inclusive or
permissive firewall, there is a good chance that you will forget
to ``close'' a couple of services, or that you will add a new
internal service and forget to update the firewall. You can still
open up the high-numbered port range on the firewall, to allow
permissive-like operation, without compromising your low ports.
Also take note that DragonFly allows you to control the range of
port numbers used for dynamic binding, via the various
net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange),
which can also ease the complexity of your firewall's
configuration. For example, you might use a normal first/last
range of 4000 to 5000, and a hiport range of 49152 to 65535, then
block off everything under 4000 in your firewall (except for
certain specific Internet-accessible ports, of course).
Another common DoS attack is called a springboard attack -- to
attack a server in a manner that causes the server to generate
responses which overloads the server, the local network, or some
other machine. The most common attack of this nature is the ICMP
ping broadcast attack. The attacker spoofs ping packets sent to
your LAN's broadcast address with the source IP address set to the
actual machine they wish to attack. If your border routers are not
configured to stomp on ping's to broadcast addresses, your LAN
winds up generating sufficient responses to the spoofed source
address to saturate the victim, especially when the attacker uses
the same trick on several dozen broadcast addresses over several
dozen different networks at once. Broadcast attacks of over a
hundred and twenty megabits have been measured. A second common
springboard attack is against the ICMP error reporting system. By
constructing packets that generate ICMP error responses, an
attacker can saturate a server's incoming network and cause the
server to saturate its outgoing network with ICMP responses. This
type of attack can also crash the server by running it out of
mbuf's, especially if the server cannot drain the ICMP responses
it generates fast enough. The DragonFly kernel has a new kernel
compile option called ICMP_BANDLIM which limits the effectiveness
of these sorts of attacks. The last major class of springboard
attacks is related to certain internal inetd services such as the
udp echo service. An attacker simply spoofs a UDP packet with the
source address being server A's echo port, and the destination
address being server B's echo port, where server A and B are both
on your LAN. The two servers then bounce this one packet back and
forth between each other. The attacker can overload both servers
and their LANs simply by injecting a few packets in this manner.
Similar problems exist with the internal chargen port. A competent
sysadmin will turn off all of these inetd-internal test services.
Spoofed packet attacks may also be used to overload the kernel
route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and
rtmaxcache sysctl parameters. A spoofed packet attack that uses a
random source IP will cause the kernel to generate a temporary
cached route in the route table, viewable with netstat -rna |
fgrep W3. These routes typically timeout in 1600 seconds or so. If
the kernel detects that the cached route table has gotten too big
it will dynamically reduce the rtexpire but will never decrease it
to less than rtminexpire. There are two problems:
1. The kernel does not react quickly enough when a lightly loaded
server is suddenly attacked.
2. The rtminexpire is not low enough for the kernel to survive a
sustained attack.
If your servers are connected to the Internet via a T3 or better,
it may be prudent to manually override both rtexpire and
rtminexpire via sysctl(8). Never set either parameter to zero
(unless you want to crash the machine). Setting both parameters to
two seconds should be sufficient to protect the route table from
attack.
--------------------------------------------------------------
10.3.9 Access Issues with Kerberos and SSH
There are a few issues with both Kerberos and ssh that need to be
addressed if you intend to use them. Kerberos V is an excellent
authentication protocol, but there are bugs in the kerberized
telnet and rlogin applications that make them unsuitable for
dealing with binary streams. Also, by default Kerberos does not
encrypt a session unless you use the -x option. ssh encrypts
everything by default.
ssh works quite well in every respect except that it forwards
encryption keys by default. What this means is that if you have a
secure workstation holding keys that give you access to the rest
of the system, and you ssh to an insecure machine, your keys are
usable. The actual keys themselves are not exposed, but ssh
installs a forwarding port for the duration of your login, and if
an attacker has broken root on the insecure machine he can utilize
that port to use your keys to gain access to any other machine
that your keys unlock.
We recommend that you use ssh in combination with Kerberos
whenever possible for staff logins. ssh can be compiled with
Kerberos support. This reduces your reliance on potentially
exposable ssh keys while at the same time protecting passwords via
Kerberos. ssh keys should only be used for automated tasks from
secure machines (something that Kerberos is unsuited to do). We
also recommend that you either turn off key-forwarding in the ssh
configuration, or that you make use of the from=IP/DOMAIN option
that ssh allows in its authorized_keys file to make the key only
usable to entities logging in from specific machines.
--------------------------------------------------------------
10.4 DES, MD5, and Crypt
Parts rewritten and updated by Bill Swingle.
Every user on a UNIX system has a password associated with their
account. It seems obvious that these passwords need to be known
only to the user and the actual operating system. In order to keep
these passwords secret, they are encrypted with what is known as a
``one-way hash'', that is, they can only be easily encrypted but
not decrypted. In other words, what we told you a moment ago was
obvious is not even true: the operating system itself does not
really know the password. It only knows the encrypted form of the
password. The only way to get the ``plain-text'' password is by a
brute force search of the space of possible passwords.
Unfortunately the only secure way to encrypt passwords when UNIX
came into being was based on DES, the Data Encryption Standard.
This was not such a problem for users resident in the US, but
since the source code for DES could not be exported outside the
US, DragonFly had to find a way to both comply with US law and
retain compatibility with all the other UNIX variants that still
used DES.
The solution was to divide up the encryption libraries so that US
users could install the DES libraries and use DES but
international users still had an encryption method that could be
exported abroad. This is how DragonFly came to use MD5 as its
default encryption method. MD5 is believed to be more secure than
DES, so installing DES is offered primarily for compatibility
reasons.
--------------------------------------------------------------
10.4.1 Recognizing Your Crypt Mechanism
libcrypt.a provides a configurable password authentication hash
library. Currently the library supports DES, MD5 and Blowfish hash
functions. By default DragonFly uses MD5 to encrypt passwords.
It is pretty easy to identify which encryption method DragonFly is
set up to use. Examining the encrypted passwords in the
/etc/master.passwd file is one way. Passwords encrypted with the
MD5 hash are longer than those encrypted with the DES hash and
also begin with the characters $1$. Passwords starting with $2a$
are encrypted with the Blowfish hash function. DES password
strings do not have any particular identifying characteristics,
but they are shorter than MD5 passwords, and are coded in a
64-character alphabet which does not include the $ character, so a
relatively short string which does not begin with a dollar sign is
very likely a DES password.
The password format used for new passwords is controlled by the
passwd_format login capability in /etc/login.conf, which takes
values of des, md5 or blf. See the login.conf(5) manual page for
more information about login capabilities.
--------------------------------------------------------------
10.5 One-time Passwords
S/Key is a one-time password scheme based on a one-way hash
function. DragonFly uses the MD4 hash for compatibility but other
systems have used MD5 and DES-MAC. S/Key ia part of the FreeBSD
base system, and is also used on a growing number of other
operating systems. S/Key is a registered trademark of Bell
Communications Research, Inc.
There are three different sorts of passwords which we will discuss
below. The first is your usual UNIX style or Kerberos password; we
will call this a ``UNIX password''. The second sort is the
one-time password which is generated by the S/Key key program or
the OPIE opiekey(1) program and accepted by the keyinit or
opiepasswd(1) programs and the login prompt; we will call this a
``one-time password''. The final sort of password is the secret
password which you give to the key/opiekey programs (and sometimes
the keyinit/opiepasswd programs) which it uses to generate
one-time passwords; we will call it a ``secret password'' or just
unqualified ``password''.
The secret password does not have anything to do with your UNIX
password; they can be the same but this is not recommended. S/Key
and OPIE secret passwords are not limited to eight characters like
old UNIX passwords[10], they can be as long as you like. Passwords
of six or seven word long phrases are fairly common. For the most
part, the S/Key or OPIE system operates completely independently
of the UNIX password system.
Besides the password, there are two other pieces of data that are
important to S/Key and OPIE. One is what is known as the ``seed''
or ``key'', consisting of two letters and five digits. The other
is what is called the ``iteration count'', a number between 1 and
100. S/Key creates the one-time password by concatenating the seed
and the secret password, then applying the MD4/MD5 hash as many
times as specified by the iteration count and turning the result
into six short English words. These six English words are your
one-time password. The authentication system (primarily PAM) keeps
track of the last one-time password used, and the user is
authenticated if the hash of the user-provided password is equal
to the previous password. Because a one-way hash is used it is
impossible to generate future one-time passwords if a successfully
used password is captured; the iteration count is decremented
after each successful login to keep the user and the login program
in sync. When the iteration count gets down to 1, S/Key and OPIE
must be reinitialized.
There are three programs involved in each system which we will
discuss below. The key and opiekey programs accept an iteration
count, a seed, and a secret password, and generate a one-time
password or a consecutive list of one-time passwords. The keyinit
and opiepasswd programs are used to initialize S/Key and OPIE
respectively, and to change passwords, iteration counts, or seeds;
they take either a secret passphrase, or an iteration count, seed,
and one-time password. The keyinfo and opieinfo programs examine
the relevant credentials files (/etc/skeykeys or /etc/opiekeys)
and print out the invoking user's current iteration count and
seed.
There are four different sorts of operations we will cover. The
first is using keyinit or opiepasswd over a secure connection to
set up one-time-passwords for the first time, or to change your
password or seed. The second operation is using keyinit or
opiepasswd over an insecure connection, in conjunction with key or
opiekey over a secure connection, to do the same. The third is
using key/opiekey to log in over an insecure connection. The
fourth is using key or opiekey to generate a number of keys which
can be written down or printed out to carry with you when going to
some location without secure connections to anywhere.
--------------------------------------------------------------
10.5.1 Secure Connection Initialization
To initialize S/Key for the first time, change your password, or
change your seed while logged in over a secure connection (e.g.,
on the console of a machine or via ssh), use the keyinit command
without any parameters while logged in as yourself:
% keyinit
Adding unfurl:
Reminder - Only use this method if you are directly connected.
If you are using telnet or rlogin exit with no password and use keyinit -s.
Enter secret password:
Again secret password:
ID unfurl s/key is 99 to17757
DEFY CLUB PRO NASH LACE SOFT
For OPIE, opiepasswd is used instead:
% opiepasswd -c
[grimreaper] ~ $ opiepasswd -f -c
Adding unfurl:
Only use this method from the console; NEVER from remote. If you are using
telnet, xterm, or a dial-in, type ^C now or exit with no password.
Then run opiepasswd without the -c parameter.
Using MD5 to compute responses.
Enter new secret pass phrase:
Again new secret pass phrase:
ID unfurl OTP key is 499 to4268
MOS MALL GOAT ARM AVID COED
At the Enter new secret pass phrase: or Enter secret password:
prompts, you should enter a password or phrase. Remember, this is
not the password that you will use to login with, this is used to
generate your one-time login keys. The ``ID'' line gives the
parameters of your particular instance: your login name, the
iteration count, and seed. When logging in the system will
remember these parameters and present them back to you so you do
not have to remember them. The last line gives the particular
one-time password which corresponds to those parameters and your
secret password; if you were to re-login immediately, this
one-time password is the one you would use.
--------------------------------------------------------------
10.5.2 Insecure Connection Initialization
To initialize or change your secret password over an insecure
connection, you will need to already have a secure connection to
some place where you can run key or opiekey; this might be in the
form of a desk accessory on a Macintosh, or a shell prompt on a
machine you trust. You will also need to make up an iteration
count (100 is probably a good value), and you may make up your own
seed or use a randomly-generated one. Over on the insecure
connection (to the machine you are initializing), use the keyinit
-s command:
% keyinit -s
Updating unfurl:
Old key: to17758
Reminder you need the 6 English words from the key command.
Enter sequence count from 1 to 9999: 100
Enter new key [default to17759]:
s/key 100 to 17759
s/key access password:
s/key access password:CURE MIKE BANE HIM RACY GORE
For OPIE, you need to use opiepasswd:
% opiepasswd
Updating unfurl:
You need the response from an OTP generator.
Old secret pass phrase:
otp-md5 498 to4268 ext
Response: GAME GAG WELT OUT DOWN CHAT
New secret pass phrase:
otp-md5 499 to4269
Response: LINE PAP MILK NELL BUOY TROY
ID mark OTP key is 499 gr4269
LINE PAP MILK NELL BUOY TROY
To accept the default seed (which the keyinit program confusingly
calls a key), press Return. Then before entering an access
password, move over to your secure connection or S/Key desk
accessory, and give it the same parameters:
% key 100 to17759
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password:
CURE MIKE BANE HIM RACY GORE
Or for OPIE:
% opiekey 498 to4268
Using the MD5 algorithm to compute response.
Reminder: Don't use opiekey from telnet or dial-in sessions.
Enter secret pass phrase:
GAME GAG WELT OUT DOWN CHAT
Now switch back over to the insecure connection, and copy the
one-time password generated over to the relevant program.
--------------------------------------------------------------
10.5.3 Generating a Single One-time Password
Once you have initialized S/Key, when you login you will be
presented with a prompt like this:
% telnet example.com
Trying 10.0.0.1...
Connected to example.com
Escape character is '^]'.
DragonFly/i386 (example.com) (ttypa)
login:
s/key 97 fw13894
Password:
Or for OPIE:
% telnet example.com
Trying 10.0.0.1...
Connected to example.com
Escape character is '^]'.
DragonFly/i386 (example.com) (ttypa)
login:
otp-md5 498 gr4269 ext
Password:
As a side note, the S/Key and OPIE prompts have a useful feature
(not shown here): if you press Return at the password prompt, the
prompter will turn echo on, so you can see what you are typing.
This can be extremely useful if you are attempting to type in a
password by hand, such as from a printout.
At this point you need to generate your one-time password to
answer this login prompt. This must be done on a trusted system
that you can run key or opiekey on. (There are versions of these
for DOS, Windows and Mac OS as well.) They need both the iteration
count and the seed as command line options. You can cut-and-paste
these right from the login prompt on the machine that you are
logging in to.
On the trusted system:
% key 97 fw13894
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password:
WELD LIP ACTS ENDS ME HAAG
For OPIE:
% opiekey 498 to4268
Using the MD5 algorithm to compute response.
Reminder: Don't use opiekey from telnet or dial-in sessions.
Enter secret pass phrase:
GAME GAG WELT OUT DOWN CHAT
Now that you have your one-time password you can continue logging
in:
login:
s/key 97 fw13894
Password:
s/key 97 fw13894
Password [echo on]: WELD LIP ACTS ENDS ME HAAG
Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ...
--------------------------------------------------------------
10.5.4 Generating Multiple One-time Passwords
Sometimes you have to go places where you do not have access to a
trusted machine or secure connection. In this case, it is possible
to use the key and opiekey commands to generate a number of
one-time passwords beforehand to be printed out and taken with
you. For example:
% key -n 5 30 zz99999
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password:
26: SODA RUDE LEA LIND BUDD SILT
27: JILT SPY DUTY GLOW COWL ROT
28: THEM OW COLA RUNT BONG SCOT
29: COT MASH BARR BRIM NAN FLAG
30: CAN KNEE CAST NAME FOLK BILK
Or for OPIE:
% opiekey -n 5 30 zz99999
Using the MD5 algorithm to compute response.
Reminder: Don't use opiekey from telnet or dial-in sessions.
Enter secret pass phrase:
26: JOAN BORE FOSS DES NAY QUIT
27: LATE BIAS SLAY FOLK MUCH TRIG
28: SALT TIN ANTI LOON NEAL USE
29: RIO ODIN GO BYE FURY TIC
30: GREW JIVE SAN GIRD BOIL PHI
The -n 5 requests five keys in sequence, the 30 specifies what the
last iteration number should be. Note that these are printed out
in reverse order of eventual use. If you are really paranoid, you
might want to write the results down by hand; otherwise you can
cut-and-paste into lpr. Note that each line shows both the
iteration count and the one-time password; you may still find it
handy to scratch off passwords as you use them.
--------------------------------------------------------------
10.5.5 Restricting Use of UNIX(R) Passwords
S/Key can place restrictions on the use of UNIX passwords based on
the host name, user name, terminal port, or IP address of a login
session. These restrictions can be found in the configuration file
/etc/skey.access. The skey.access(5) manual page has more
information on the complete format of the file and also details
some security cautions to be aware of before depending on this
file for security.
If there is no /etc/skey.access file (this is the default), then
all users will be allowed to use UNIX passwords. If the file
exists, however, then all users will be required to use S/Key
unless explicitly permitted to do otherwise by configuration
statements in the skey.access file. In all cases, UNIX passwords
are permitted on the console.
Here is a sample skey.access configuration file which illustrates
the three most common sorts of configuration statements:
permit internet 192.168.0.0 255.255.0.0
permit user fnord
permit port ttyd0
The first line (permit internet) allows users whose IP source
address (which is vulnerable to spoofing) matches the specified
value and mask, to use UNIX passwords. This should not be
considered a security mechanism, but rather, a means to remind
authorized users that they are using an insecure network and need
to use S/Key for authentication.
The second line (permit user) allows the specified username, in
this case fnord, to use UNIX passwords at any time. Generally
speaking, this should only be used for people who are either
unable to use the key program, like those with dumb terminals, or
those who are uneducable.
The third line (permit port) allows all users logging in on the
specified terminal line to use UNIX passwords; this would be used
for dial-ups.
Here is a sample opieaccess file:
permit 192.168.0.0 255.255.0.0
This line allows users whose IP source address (which is
vulnerable to spoofing) matches the specified value and mask, to
use UNIX passwords at any time.
If no rules in opieaccess are matched, the default is to deny
non-OPIE logins.
--------------------------------------------------------------
10.6 Kerberos5
Contributed by Tillman Hodgson. Based on a contribution by Mark
Murray.
The following information only applies to Kerberos5. Users who
wish to use the KerberosIV package may install the security/krb4
port.
Kerberos is a network add-on system/protocol that allows users to
authenticate themselves through the services of a secure server.
Services such as remote login, remote copy, secure inter-system
file copying and other high-risk tasks are made considerably safer
and more controllable.
Kerberos can be described as an identity-verifying proxy system.
It can also be described as a trusted third-party authentication
system. Kerberos provides only one function -- the secure
authentication of users on the network. It does not provide
authorization functions (what users are allowed to do) or auditing
functions (what those users did). After a client and server have
used Kerberos to prove their identity, they can also encrypt all
of their communications to assure privacy and data integrity as
they go about their business.
Therefore it is highly recommended that Kerberos be used with
other security methods which provide authorization and audit
services.
The following instructions can be used as a guide on how to set up
Kerberos as distributed for DragonFly. However, you should refer
to the relevant manual pages for a complete description.
For purposes of demonstrating a Kerberos installation, the various
namespaces will be handled as follows:
* The DNS domain (``zone'') will be example.org.
* The Kerberos realm will be EXAMPLE.ORG.
Note: Please use real domain names when setting up Kerberos even
if you intend to run it internally. This avoids DNS problems and
assures inter-operation with other Kerberos realms.
--------------------------------------------------------------
10.6.1 History
Kerberos was created by MIT as a solution to network security
problems. The Kerberos protocol uses strong cryptography so that a
client can prove its identity to a server (and vice versa) across
an insecure network connection.
Kerberos is both the name of a network authentication protocol and
an adjective to describe programs that implement the program
(Kerberos telnet, for example). The current version of the
protocol is version 5, described in RFC 1510.
Several free implementations of this protocol are available,
covering a wide range of operating systems. The Massachusetts
Institute of Technology (MIT), where Kerberos was originally
developed, continues to develop their Kerberos package. It is
commonly used in the US as a cryptography product, as such it has
historically been affected by US export regulations. The MIT
Kerberos is available as a port (security/krb5). Heimdal Kerberos
is another version 5 implementation, and was explicitly developed
outside of the US to avoid export regulations (and is thus often
included in non-commercial UNIX variants). The Heimdal Kerberos
distribution is available as a port (security/heimdal), and a
minimal installation of it is included in the base DragonFly
install.
In order to reach the widest audience, these instructions assume
the use of the Heimdal distribution included in DragonFly.
--------------------------------------------------------------
10.6.2 Setting up a Heimdal KDC
The Key Distribution Center (KDC) is the centralized
authentication service that Kerberos provides -- it is the
computer that issues Kerberos tickets. The KDC is considered
``trusted'' by all other computers in the Kerberos realm, and thus
has heightened security concerns.
Note that while running the Kerberos server requires very few
computing resources, a dedicated machine acting only as a KDC is
recommended for security reasons.
To begin setting up a KDC, ensure that your /etc/rc.conf file
contains the correct settings to act as a KDC (you may need to
adjust paths to reflect your own system):
kerberos5_server_enable="YES"
kadmind5_server_enable="YES"
kerberos_stash="YES"
Next we will set up your Kerberos config file, /etc/krb5.conf:
[libdefaults]
default_realm = EXAMPLE.ORG
[realms]
EXAMPLE.ORG = {
kdc = kerberos.example.org
}
[domain_realm]
.example.org = EXAMPLE.ORG
Note that this /etc/krb5.conf file implies that your KDC will have
the fully-qualified hostname of kerberos.example.org. You will
need to add a CNAME (alias) entry to your zone file to accomplish
this if your KDC has a different hostname.
Note: For large networks with a properly configured BIND DNS
server, the above example could be trimmed to:
[libdefaults]
default_realm = EXAMPLE.ORG
With the following lines being appended to the example.org
zonefile:
_kerberos._udp IN SRV 01 00 88 kerberos.example.org.
_kerberos._tcp IN SRV 01 00 88 kerberos.example.org.
_kpasswd._udp IN SRV 01 00 464 kerberos.example.org.
_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org.
_kerberos IN TXT EXAMPLE.ORG.
Next we will create the Kerberos database. This database contains
the keys of all principals encrypted with a master password. You
are not required to remember this password, it will be stored in a
file (/var/heimdal/m-key). To create the master key, run kstash
and enter a password.
Once the master key has been created, you can initialize the
database using the kadmin program with the -l option (standing for
``local''). This option instructs kadmin to modify the database
files directly rather than going through the kadmind network
service. This handles the chicken-and-egg problem of trying to
connect to the database before it is created. Once you have the
kadmin prompt, use the init command to create your realms initial
database.
Lastly, while still in kadmin, create your first principal using
the add command. Stick to the defaults options for the principal
for now, you can always change them later with the modify command.
Note that you can use the ? command at any prompt to see the
available options.
A sample database creation session is shown below:
# kstash
Master key: xxxxxxxx
Verifying password - Master key: xxxxxxxx
# kadmin -l
kadmin> init EXAMPLE.ORG
Realm max ticket life [unlimited]:
kadmin> add tillman
Max ticket life [unlimited]:
Max renewable life [unlimited]:
Attributes []:
Password: xxxxxxxx
Verifying password - Password: xxxxxxxx
Now it is time to start up the KDC services. Run
/etc/rc.d/kerberos start and /etc/rc.d/kadmind start to bring up
the services. Note that you won't have any kerberized daemons
running at this point but you should be able to confirm the that
the KDC is functioning by obtaining and listing a ticket for the
principal (user) that you just created from the command-line of
the KDC itself:
% k5init tillman
tillman@EXAMPLE.ORG's Password:
% k5list
Credentials cache: FILE:/tmp/krb5cc_500
Principal: tillman@EXAMPLE.ORG
Issued Expires Principal
Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
--------------------------------------------------------------
10.6.3 Kerberos enabling a server with Heimdal services
First, we need a copy of the Kerberos configuration file,
/etc/krb5.conf. To do so, simply copy it over to the client
computer from the KDC in a secure fashion (using network
utilities, such as scp(1), or physically via a floppy disk).
Next you need a /etc/krb5.keytab file. This is the major
difference between a server providing Kerberos enabled daemons and
a workstation -- the server must have a keytab file. This file
contains the servers host key, which allows it and the KDC to
verify each others identity. It must be transmitted to the server
in a secure fashion, as the security of the server can be broken
if the key is made public. This explicitly means that transferring
it via a clear text channel, such as FTP, is a very bad idea.
Typically, you transfer to the keytab to the server using the
kadmin program. This is handy because you also need to create the
host principal (the KDC end of the krb5.keytab) using kadmin.
Note that you must have already obtained a ticket and that this
ticket must be allowed to use the kadmin interface in the
kadmind.acl. See the section titled ``Remote administration'' in
the Heimdal info pages (info heimdal) for details on designing
access control lists. If you do not want to enable remote kadmin
access, you can simply securely connect to the KDC (via local
console, ssh(1) or Kerberos telnet(1)) and perform administration
locally using kadmin -l.
After installing the /etc/krb5.conf file, you can use kadmin from
the Kerberos server. The add --random-key command will let you add
the servers host principal, and the ext command will allow you to
extract the servers host principal to its own keytab. For example:
# kadmin
kadmin> add --random-key host/myserver.example.org
Max ticket life [unlimited]:
Max renewable life [unlimited]:
Attributes []:
kadmin> ext host/myserver.example.org
kadmin> exit
Note that the ext command (short for ``extract'') stores the
extracted key in /etc/krb5.keytab by default.
If you do not have kadmind running on the KDC (possibly for
security reasons) and thus do not have access to kadmin remotely,
you can add the host principal (host/myserver.EXAMPLE.ORG)
directly on the KDC and then extract it to a temporary file (to
avoid over-writing the /etc/krb5.keytab on the KDC) using
something like this:
# kadmin
kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org
kadmin> exit
You can then securely copy the keytab to the server computer
(using scp or a floppy, for example). Be sure to specify a
non-default keytab name to avoid over-writing the keytab on the
KDC.
At this point your server can communicate with the KDC (due to its
krb5.conf file) and it can prove its own identity (due to the
krb5.keytab file). It is now ready for you to enable some Kerberos
services. For this example we will enable the telnet service by
putting a line like this into your /etc/inetd.conf and then
restarting the inetd(8) service with /etc/rc.d/inetd restart:
telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user
The critical bit is that the -a (for authentication) type is set
to user. Consult the telnetd(8) manual page for more details.
--------------------------------------------------------------
10.6.4 Kerberos enabling a client with Heimdal
Setting up a client computer is almost trivially easy. As far as
Kerberos configuration goes, you only need the Kerberos
configuration file, located at /etc/krb5.conf. Simply securely
copy it over to the client computer from the KDC.
Test your client computer by attempting to use kinit, klist, and
kdestroy from the client to obtain, show, and then delete a ticket
for the principal you created above. You should also be able to
use Kerberos applications to connect to Kerberos enabled servers,
though if that does not work and obtaining a ticket does the
problem is likely with the server and not with the client or the
KDC.
When testing an application like telnet, try using a packet
sniffer (such as tcpdump(1)) to confirm that your password is not
sent in the clear. Try using telnet with the -x option, which
encrypts the entire data stream (similar to ssh).
The core Kerberos client applications (traditionally named kinit,
klist, kdestroy, and kpasswd) are installed in the base DragonFly
install. Note that DragonFly versions prior to 5.0 renamed them to
k5init, k5list, k5destroy, k5passwd, and k5stash (though it is
typically only used once).
Various non-core Kerberos client applications are also installed
by default. This is where the ``minimal'' nature of the base
Heimdal installation is felt: telnet is the only Kerberos enabled
service.
The Heimdal port adds some of the missing client applications:
Kerberos enabled versions of ftp, rsh, rcp, rlogin, and a few
other less common programs. The MIT port also contains a full
suite of Kerberos client applications.
--------------------------------------------------------------
10.6.5 User configuration files: .k5login and .k5users
Users within a realm typically have their Kerberos principal (such
as tillman@EXAMPLE.ORG) mapped to a local user account (such as a
local account named tillman). Client applications such as telnet
usually do not require a user name or a principal.
Occasionally, however, you want to grant access to a local user
account to someone who does not have a matching Kerberos
principal. For example, tillman@EXAMPLE.ORG may need access to the
local user account webdevelopers. Other principals may also need
access to that local account.
The .k5login and .k5users files, placed in a users home directory,
can be used similar to a powerful combination of .hosts and
.rhosts, solving this problem. For example, if a .k5login with the
following contents:
tillman@example.org
jdoe@example.org
Were to be placed into the home directory of the local user
webdevelopers then both principals listed would have access to
that account without requiring a shared password.
Reading the manual pages for these commands is recommended. Note
that the ksu manual page covers .k5users.
--------------------------------------------------------------
10.6.6 Kerberos Tips, Tricks, and Troubleshooting
* When using either the Heimdal or MIT Kerberos ports ensure
that your PATH environment variable lists the Kerberos
versions of the client applications before the system
versions.
* Is your time in sync? Are you sure? If the time is not in sync
(typically within five minutes) authentication will fail.
* MIT and Heimdal inter-operate nicely. Except for kadmin, the
protocol for which is not standardized.
* If you change your hostname, you also need to change your
host/ principal and update your keytab. This also applies to
special keytab entries like the www/ principal used for
Apache's www/mod_auth_kerb.
* All hosts in your realm must be resolvable (both forwards and
reverse) in DNS (or /etc/hosts as a minimum). CNAMEs will
work, but the A and PTR records must be correct and in place.
The error message isn't very intuitive: ``Kerberos5 refuses
authentication because Read req failed: Key table entry not
found''.
* Some operating systems that may being acting as clients to
your KDC do not set the permissions for ksu to be setuid root.
This means that ksu does not work, which is a good security
idea but annoying. This is not a KDC error.
* With MIT Kerberos, if you want to allow a principal to have a
ticket life longer than the default ten hours, you must use
modify_principal in kadmin to change the maxlife of both the
principal in question and the krbtgt principal. Then the
principal can use the -l option with kinit to request a ticket
with a longer lifetime.
* Note: If you run a packet sniffer on your KDC to add in
troubleshooting and then run kinit from a workstation, you
will notice that your TGT is sent immediately upon running
kinit -- even before you type your password! The explanation
is that the Kerberos server freely transmits a TGT (Ticket
Granting Ticket) to any unauthorized request; however, every
TGT is encrypted in a key derived from the user's password.
Therefore, when a user types their password it is not being
sent to the KDC, it is being used to decrypt the TGT that
kinit already obtained. If the decryption process results in
a valid ticket with a valid time stamp, the user has valid
Kerberos credentials. These credentials include a session
key for establishing secure communications with the Kerberos
server in the future, as well as the actual ticket-granting
ticket, which is actually encrypted with the Kerberos
server's own key. This second layer of encryption is unknown
to the user, but it is what allows the Kerberos server to
verify the authenticity of each TGT.
* You have to keep the time in sync between all the computers in
your realm. NTP is perfect for this. For more information on
NTP, see Section 19.12.
* If you want to use long ticket lifetimes (a week, for example)
and you are using OpenSSH to connect to the machine where your
ticket is stored, make sure that Kerberos TicketCleanup is set
to no in your sshd_config or else your tickets will be deleted
when you log out.
* Remember that host principals can have a longer ticket
lifetime as well. If your user principal has a lifetime of a
week but the host you are connecting to has a lifetime of nine
hours, you will have an expired host principal in your cache
and the ticket cache will not work as expected.
* When setting up a krb5.dict file to prevent specific bad
passwords from being used (the manual page for kadmind covers
this briefly), remember that it only applies to principals
that have a password policy assigned to them. The krb5.dict
files format is simple: one string per line. Creating a
symbolic link to /usr/share/dict/words might be useful.
--------------------------------------------------------------
10.6.7 Differences with the MIT port
The major difference between the MIT and Heimdal installs relates
to the kadmin program which has a different (but equivalent) set
of commands and uses a different protocol. This has a large
implications if your KDC is MIT as you will not be able to use the
Heimdal kadmin program to administer your KDC remotely (or vice
versa, for that matter).
The client applications may also take slightly different command
line options to accomplish the same tasks. Following the
instructions on the MIT Kerberos web site
(http://web.mit.edu/Kerberos/www/) is recommended. Be careful of
path issues: the MIT port installs into /usr/local/ by default,
and the ``normal'' system applications may be run instead of MIT
if your PATH environment variable lists the system directories
first.
Note: With the MIT security/krb5 port that is provided by
DragonFly, be sure to read the
/usr/local/share/doc/krb5/README.FreeBSD file installed by the
port if you want to understand why logins via telnetd and
klogind behave somewhat oddly. Most importantly, correcting the
``incorrect permissions on cache file'' behavior requires that
the login.krb5 binary be used for authentication so that it can
properly change ownership for the forwarded credentials.
--------------------------------------------------------------
10.6.8 Mitigating limitations found in Kerberos
--------------------------------------------------------------
10.6.8.1 Kerberos is an all-or-nothing approach
Every service enabled on the network must be modified to work with
Kerberos (or be otherwise secured against network attacks) or else
the users credentials could be stolen and re-used. An example of
this would be Kerberos enabling all remote shells (via rsh and
telnet, for example) but not converting the POP3 mail server which
sends passwords in plaintext.
--------------------------------------------------------------
10.6.8.2 Kerberos is intended for single-user workstations
In a multi-user environment, Kerberos is less secure. This is
because it stores the tickets in the /tmp directory, which is
readable by all users. If a user is sharing a computer with
several other people simultaneously (i.e. multi-user), it is
possible that the user's tickets can be stolen (copied) by another
user.
This can be overcome with the -c filename command-line option or
(preferably) the KRB5CCNAME environment variable, but this is
rarely done. In principal, storing the ticket in the users home
directory and using simple file permissions can mitigate this
problem.
--------------------------------------------------------------
10.6.8.3 The KDC is a single point of failure
By design, the KDC must be as secure as the master password
database is contained on it. The KDC should have absolutely no
other services running on it and should be physically secured. The
danger is high because Kerberos stores all passwords encrypted
with the same key (the ``master'' key), which in turn is stored as
a file on the KDC.
As a side note, a compromised master key is not quite as bad as
one might normally fear. The master key is only used to encrypt
the Kerberos database and as a seed for the random number
generator. As long as access to your KDC is secure, an attacker
cannot do much with the master key.
Additionally, if the KDC is unavailable (perhaps due to a denial
of service attack or network problems) the network services are
unusable as authentication can not be performed, a recipe for a
denial-of-service attack. This can alleviated with multiple KDCs
(a single master and one or more slaves) and with careful
implementation of secondary or fall-back authentication (PAM is
excellent for this).
--------------------------------------------------------------
10.6.8.4 Kerberos Shortcomings
Kerberos allows users, hosts and services to authenticate between
themselves. It does not have a mechanism to authenticate the KDC
to the users, hosts or services. This means that a trojanned kinit
(for example) could record all user names and passwords. Something
like security/tripwire or other file system integrity checking
tools can alleviate this.
--------------------------------------------------------------
10.6.9 Resources and further information
* The Kerberos FAQ
* Designing an Authentication System: a Dialogue in Four Scenes
* RFC 1510, The Kerberos Network Authentication Service (V5)
* MIT Kerberos home page
* Heimdal Kerberos home page
--------------------------------------------------------------
10.7 Firewalls
Contributed by Gary Palmer and Alex Nash.
Firewalls are an area of increasing interest for people who are
connected to the Internet, and are even finding applications on
private networks to provide enhanced security. This section will
hopefully explain what firewalls are, how to use them, and how to
use the facilities provided in the DragonFly kernel to implement
them.
Note: People often think that having a firewall between your
internal network and the ``Big Bad Internet'' will solve all
your security problems. It may help, but a poorly set up
firewall system is more of a security risk than not having one
at all. A firewall can add another layer of security to your
systems, but it cannot stop a really determined cracker from
penetrating your internal network. If you let internal security
lapse because you believe your firewall to be impenetrable, you
have just made the crackers job that much easier.
--------------------------------------------------------------
10.7.1 What Is a Firewall?
There are currently two distinct types of firewalls in common use
on the Internet today. The first type is more properly called a
packet filtering router. This type of firewall utilizes a
multi-homed machine and a set of rules to determine whether to
forward or block individual packets. A multi-homed machine is
simply a device with multiple network interfaces. The second type,
known as a proxy server, relies on daemons to provide
authentication and to forward packets, possibly on a multi-homed
machine which has kernel packet forwarding disabled.
Sometimes sites combine the two types of firewalls, so that only a
certain machine (known as a bastion host) is allowed to send
packets through a packet filtering router onto an internal
network. Proxy services are run on the bastion host, which are
generally more secure than normal authentication mechanisms.
DragonFly comes with a kernel packet filter (known as IPFW), which
is what the rest of this section will concentrate on. Proxy
servers can be built on DragonFly from third party software, but
there is such a variety of proxy servers available that it would
be impossible to cover them in this section.
--------------------------------------------------------------
10.7.1.1 Packet Filtering Routers
A router is a machine which forwards packets between two or more
networks. A packet filtering router is programmed to compare each
packet to a list of rules before deciding if it should be
forwarded or not. Most modern IP routing software includes packet
filtering functionality that defaults to forwarding all packets.
To enable the filters, you need to define a set of rules.
To decide whether a packet should be passed on, the firewall looks
through its set of rules for a rule which matches the contents of
the packet's headers. Once a match is found, the rule action is
obeyed. The rule action could be to drop the packet, to forward
the packet, or even to send an ICMP message back to the
originator. Only the first match counts, as the rules are searched
in order. Hence, the list of rules can be referred to as a ``rule
chain''.
The packet-matching criteria varies depending on the software
used, but typically you can specify rules which depend on the
source IP address of the packet, the destination IP address, the
source port number, the destination port number (for protocols
which support ports), or even the packet type (UDP, TCP, ICMP,
etc).
--------------------------------------------------------------
10.7.1.2 Proxy Servers
Proxy servers are machines which have had the normal system
daemons (telnetd, ftpd, etc) replaced with special servers. These
servers are called proxy servers, as they normally only allow
onward connections to be made. This enables you to run (for
example) a proxy telnet server on your firewall host, and people
can telnet in to your firewall from the outside, go through some
authentication mechanism, and then gain access to the internal
network (alternatively, proxy servers can be used for signals
coming from the internal network and heading out).
Proxy servers are normally more secure than normal servers, and
often have a wider variety of authentication mechanisms available,
including ``one-shot'' password systems so that even if someone
manages to discover what password you used, they will not be able
to use it to gain access to your systems as the password expires
immediately after the first use. As they do not actually give
users access to the host machine, it becomes a lot more difficult
for someone to install backdoors around your security system.
Proxy servers often have ways of restricting access further, so
that only certain hosts can gain access to the servers. Most will
also allow the administrator to specify which users can talk to
which destination machines. Again, what facilities are available
depends largely on what proxy software you choose.
--------------------------------------------------------------
10.7.2 What Does IPFW Allow Me to Do?
IPFW, the software supplied with DragonFly, is a packet filtering
and accounting system which resides in the kernel, and has a
user-land control utility, ipfw(8). Together, they allow you to
define and query the rules used by the kernel in its routing
decisions.
There are two related parts to IPFW. The firewall section performs
packet filtering. There is also an IP accounting section which
tracks usage of the router, based on rules similar to those used
in the firewall section. This allows the administrator to monitor
how much traffic the router is getting from a certain machine, or
how much WWW traffic it is forwarding, for example.
As a result of the way that IPFW is designed, you can use IPFW on
non-router machines to perform packet filtering on incoming and
outgoing connections. This is a special case of the more general
use of IPFW, and the same commands and techniques should be used
in this situation.
--------------------------------------------------------------
10.7.3 Enabling IPFW on DragonFly
As the main part of the IPFW system lives in the kernel, you will
need to add one or more options to your kernel configuration file,
depending on what facilities you want, and recompile your kernel.
See "Reconfiguring your Kernel" (Chapter 9) for more details on
how to recompile your kernel.
Warning: IPFW defaults to a policy of deny ip from any to any.
If you do not add other rules during startup to allow access,
you will lock yourself out of the server upon rebooting into a
firewall-enabled kernel. We suggest that you set
firewall_type=open in your /etc/rc.conf file when first enabling
this feature, then refining the firewall rules in
/etc/rc.firewall after you have tested that the new kernel
feature works properly. To be on the safe side, you may wish to
consider performing the initial firewall configuration from the
local console rather than via ssh. Another option is to build a
kernel using both the IPFIREWALL and
IPFIREWALL_DEFAULT_TO_ACCEPT options. This will change the
default rule of IPFW to allow ip from any to any and avoid the
possibility of a lockout.
There are currently four kernel configuration options relevant to
IPFW:
options IPFIREWALL
Compiles into the kernel the code for packet filtering.
options IPFIREWALL_VERBOSE
Enables code to allow logging of packets through
syslogd(8). Without this option, even if you specify that
packets should be logged in the filter rules, nothing will
happen.
options IPFIREWALL_VERBOSE_LIMIT=10
Limits the number of packets logged through syslogd(8) on
a per entry basis. You may wish to use this option in
hostile environments in which you want to log firewall
activity, but do not want to be open to a denial of
service attack via syslog flooding.
When a chain entry reaches the packet limit specified,
logging is turned off for that particular entry. To resume
logging, you will need to reset the associated counter
using the ipfw(8) utility:
# ipfw zero 4500
Where 4500 is the chain entry you wish to continue
logging.
options IPFIREWALL_DEFAULT_TO_ACCEPT
This changes the default rule action from ``deny'' to
``allow''. This avoids the possibility of locking yourself
out if you happen to boot a kernel with IPFIREWALL support
but have not configured your firewall yet. It is also very
useful if you often use ipfw(8) as a filter for specific
problems as they arise. Use with care though, as this
opens up the firewall and changes the way it works.
--------------------------------------------------------------
10.7.4 Configuring IPFW
The configuration of the IPFW software is done through the ipfw(8)
utility. The syntax for this command looks quite complicated, but
it is relatively simple once you understand its structure.
There are currently four different command categories used by the
utility: addition/deletion, listing, flushing, and clearing.
Addition/deletion is used to build the rules that control how
packets are accepted, rejected, and logged. Listing is used to
examine the contents of your rule set (otherwise known as the
chain) and packet counters (accounting). Flushing is used to
remove all entries from the chain. Clearing is used to zero out
one or more accounting entries.
--------------------------------------------------------------
10.7.4.1 Altering the IPFW Rules
The syntax for this form of the command is:
ipfw [-N] command [index] action [log] protocol addresses
[options]
There is one valid flag when using this form of the command:
-N
Resolve addresses and service names in output.
The command given can be shortened to the shortest unique form.
The valid commands are:
add
Add an entry to the firewall/accounting rule list
delete
Delete an entry from the firewall/accounting rule list
Previous versions of IPFW used separate firewall and accounting
entries. The present version provides packet accounting with each
firewall entry.
If an index value is supplied, it is used to place the entry at a
specific point in the chain. Otherwise, the entry is placed at the
end of the chain at an index 100 greater than the last chain entry
(this does not include the default policy, rule 65535, deny).
The log option causes matching rules to be output to the system
console if the kernel was compiled with IPFIREWALL_VERBOSE.
Valid actions are:
reject
Drop the packet, and send an ICMP host or port unreachable
(as appropriate) packet to the source.
allow
Pass the packet on as normal. (aliases: pass, permit, and
accept)
deny
Drop the packet. The source is not notified via an ICMP
message (thus it appears that the packet never arrived at
the destination).
count
Update packet counters but do not allow/deny the packet
based on this rule. The search continues with the next
chain entry.
Each action will be recognized by the shortest unambiguous prefix.
The protocols which can be specified are:
all
Matches any IP packet
icmp
Matches ICMP packets
tcp
Matches TCP packets
udp
Matches UDP packets
The address specification is:
from address/mask [port] to address/mask [port] [via interface]
You can only specify port in conjunction with protocols which
support ports (UDP and TCP).
The via is optional and may specify the IP address or domain name
of a local IP interface, or an interface name (e.g. ed0) to match
only packets coming through this interface. Interface unit numbers
can be specified with an optional wildcard. For example, ppp*
would match all kernel PPP interfaces.
The syntax used to specify an address/mask is:
address
or
address/mask-bits
or
address:mask-pattern
A valid hostname may be specified in place of the IP address.
mask-bits is a decimal number representing how many bits in the
address mask should be set. e.g. specifying 192.216.222.1/24 will
create a mask which will allow any address in a class C subnet (in
this case, 192.216.222) to be matched. mask-pattern is an IP
address which will be logically AND'ed with the address given. The
keyword any may be used to specify ``any IP address''.
The port numbers to be blocked are specified as:
port [,port [,port [...]]]
to specify either a single port or a list of ports, or
port-port
to specify a range of ports. You may also combine a single range
with a list, but the range must always be specified first.
The options available are:
frag
Matches if the packet is not the first fragment of the
datagram.
in
Matches if the packet is on the way in.
out
Matches if the packet is on the way out.
ipoptions spec
Matches if the IP header contains the comma separated list
of options specified in spec. The supported IP options
are: ssrr (strict source route), lsrr (loose source
route), rr (record packet route), and ts (time stamp). The
absence of a particular option may be specified with a
leading !.
established
Matches if the packet is part of an already established
TCP connection (i.e. it has the RST or ACK bits set). You
can optimize the performance of the firewall by placing
established rules early in the chain.
setup
Matches if the packet is an attempt to establish a TCP
connection (the SYN bit is set but the ACK bit is not).
tcpflags flags
Matches if the TCP header contains the comma separated
list of flags. The supported flags are fin, syn, rst, psh,
ack, and urg. The absence of a particular flag may be
indicated by a leading !.
icmptypes types
Matches if the ICMP type is present in the list types. The
list may be specified as any combination of ranges and/or
individual types separated by commas. Commonly used ICMP
types are: 0 echo reply (ping reply), 3 destination
unreachable, 5 redirect, 8 echo request (ping request),
and 11 time exceeded (used to indicate TTL expiration as
with traceroute(8)).
--------------------------------------------------------------
10.7.4.2 Listing the IPFW Rules
The syntax for this form of the command is:
ipfw [-a] [-c] [-d] [-e] [-t] [-N] [-S] list
There are seven valid flags when using this form of the command:
-a
While listing, show counter values. This option is the
only way to see accounting counters.
-c
List rules in compact form.
-d
Show dynamic rules in addition to static rules.
-e
If -d was specified, also show expired dynamic rules.
-t
Display the last match times for each chain entry. The
time listing is incompatible with the input syntax used by
the ipfw(8) utility.
-N
Attempt to resolve given addresses and service names.
-S
Show the set each rule belongs to. If this flag is not
specified, disabled rules will not be listed.
--------------------------------------------------------------
10.7.4.3 Flushing the IPFW Rules
The syntax for flushing the chain is:
ipfw flush
This causes all entries in the firewall chain to be removed except
the fixed default policy enforced by the kernel (index 65535). Use
caution when flushing rules; the default deny policy will leave
your system cut off from the network until allow entries are added
to the chain.
--------------------------------------------------------------
10.7.4.4 Clearing the IPFW Packet Counters
The syntax for clearing one or more packet counters is:
ipfw zero [index]
When used without an index argument, all packet counters are
cleared. If an index is supplied, the clearing operation only
affects a specific chain entry.
--------------------------------------------------------------
10.7.5 Example Commands for ipfw
This command will deny all packets from the host evil.crackers.org
to the telnet port of the host nice.people.org:
# ipfw add deny tcp from evil.crackers.org to nice.people.org 23
The next example denies and logs any TCP traffic from the entire
crackers.org network (a class C) to the nice.people.org machine
(any port).
# ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org
If you do not want people sending X sessions to your internal
network (a subnet of a class C), the following command will do the
necessary filtering:
# ipfw add deny tcp from any to my.org/28 6000 setup
To see the accounting records:
# ipfw -a list
or in the short form
# ipfw -a l
You can also see the last time a chain entry was matched with:
# ipfw -at l
--------------------------------------------------------------
10.7.6 Building a Packet Filtering Firewall
Note: The following suggestions are just that: suggestions. The
requirements of each firewall are different and we cannot tell
you how to build a firewall to meet your particular
requirements.
When initially setting up your firewall, unless you have a test
bench setup where you can configure your firewall host in a
controlled environment, it is strongly recommend you use the
logging version of the commands and enable logging in the kernel.
This will allow you to quickly identify problem areas and cure
them without too much disruption. Even after the initial setup
phase is complete, I recommend using the logging for `deny' as it
allows tracing of possible attacks and also modification of the
firewall rules if your requirements alter.
Note: If you use the logging versions of the accept command, be
aware that it can generate large amounts of log data. One log
entry will be generated for every packet that passes through the
firewall, so large FTP/http transfers, etc, will really slow the
system down. It also increases the latencies on those packets as
it requires more work to be done by the kernel before the packet
can be passed on. syslogd will also start using up a lot more
processor time as it logs all the extra data to disk, and it
could quite easily fill the partition /var/log is located on.
You should enable your firewall from /etc/rc.conf.local or
/etc/rc.conf. The associated manual page explains which knobs to
fiddle and lists some preset firewall configurations. If you do
not use a preset configuration, ipfw list will output the current
ruleset into a file that you can pass to rc.conf. If you do not
use /etc/rc.conf.local or /etc/rc.conf to enable your firewall, it
is important to make sure your firewall is enabled before any IP
interfaces are configured.
The next problem is what your firewall should actually do! This is
largely dependent on what access to your network you want to allow
from the outside, and how much access to the outside world you
want to allow from the inside. Some general rules are:
* Block all incoming access to ports below 1024 for TCP. This is
where most of the security sensitive services are, like
finger, SMTP (mail) and telnet.
* Block all incoming UDP traffic. There are very few useful
services that travel over UDP, and what useful traffic there
is, is normally a security threat (e.g. Suns RPC and NFS
protocols). This has its disadvantages also, since UDP is a
connectionless protocol, denying incoming UDP traffic also
blocks the replies to outgoing UDP traffic. This can cause a
problem for people (on the inside) using external archie
(prospero) servers. If you want to allow access to archie, you
will have to allow packets coming from ports 191 and 1525 to
any internal UDP port through the firewall. ntp is another
service you may consider allowing through, which comes from
port 123.
* Block traffic to port 6000 from the outside. Port 6000 is the
port used for access to X11 servers, and can be a security
threat (especially if people are in the habit of doing xhost +
on their workstations). X11 can actually use a range of ports
starting at 6000, the upper limit being how many X displays
you can run on the machine. The upper limit as defined by RFC
1700 (Assigned Numbers) is 6063.
* Check what ports any internal servers use (e.g. SQL servers,
etc). It is probably a good idea to block those as well, as
they normally fall outside the 1-1024 range specified above.
Another checklist for firewall configuration is available from
CERT at http://www.cert.org/tech_tips/packet_filtering.html
As stated above, these are only guidelines. You will have to
decide what filter rules you want to use on your firewall
yourself. We cannot accept ANY responsibility if someone breaks
into your network, even if you follow the advice given above.
--------------------------------------------------------------
10.7.7 IPFW Overhead and Optimization
Many people want to know how much overhead IPFW adds to a system.
The answer to this depends mostly on your rule set and processor
speed. For most applications dealing with Ethernet and small rule
sets, the answer is ``negligible''. For those of you that need
actual measurements to satisfy your curiosity, read on.
The following measurements were made using FreeBSD 2.2.5-STABLE on
a 486-66. (While IPFW has changed slightly in later releases of
DragonFly, it still performs with similar speed.) IPFW was
modified to measure the time spent within the ip_fw_chk routine,
displaying the results to the console every 1000 packets.
Two rule sets, each with 1000 rules, were tested. The first set
was designed to demonstrate a worst case scenario by repeating the
rule:
# ipfw add deny tcp from any to any 55555
This demonstrates a worst case scenario by causing most of IPFW's
packet check routine to be executed before finally deciding that
the packet does not match the rule (by virtue of the port number).
Following the 999th iteration of this rule was an allow ip from
any to any.
The second set of rules were designed to abort the rule check
quickly:
# ipfw add deny ip from 1.2.3.4 to 1.2.3.4
The non-matching source IP address for the above rule causes these
rules to be skipped very quickly. As before, the 1000th rule was
an allow ip from any to any.
The per-packet processing overhead in the former case was
approximately 2.703 ms/packet, or roughly 2.7 microseconds per
rule. Thus the theoretical packet processing limit with these
rules is around 370 packets per second. Assuming 10 Mbps Ethernet
and a ~1500 byte packet size, we would only be able to achieve
55.5% bandwidth utilization.
For the latter case each packet was processed in approximately
1.172 ms, or roughly 1.2 microseconds per rule. The theoretical
packet processing limit here would be about 853 packets per
second, which could consume 10 Mbps Ethernet bandwidth.
The excessive number of rules tested and the nature of those rules
do not provide a real-world scenario -- they were used only to
generate the timing information presented here. Here are a few
things to keep in mind when building an efficient rule set:
* Place an established rule early on to handle the majority of
TCP traffic. Do not put any allow tcp statements before this
rule.
* Place heavily triggered rules earlier in the rule set than
those rarely used (without changing the permissiveness of the
firewall, of course). You can see which rules are used most
often by examining the packet counting statistics with ipfw -a
l.
--------------------------------------------------------------
10.8 OpenSSL
OpenSSL provides a general-purpose cryptography library, as well
as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport
Layer Security v1 (TLSv1) network security protocols.
However, one of the algorithms (specifically IDEA) included in
OpenSSL is protected by patents in the USA and elsewhere, and is
not available for unrestricted use. IDEA is included in the
OpenSSL sources in DragonFly, but it is not built by default. If
you wish to use it, and you comply with the license terms, enable
the MAKE_IDEA switch in /etc/make.conf and rebuild your sources
using make world.
Today, the RSA algorithm is free for use in USA and other
countries. In the past it was protected by a patent.
--------------------------------------------------------------
10.8.1 Source Code Installations
OpenSSL is part of the src-crypto and src-secure CVSup
collections. See the Obtaining DragonFly section for more
information about obtaining and updating DragonFly source code.
--------------------------------------------------------------
10.9 VPN over IPsec
Written by Nik Clayton.
Creating a VPN between two networks, separated by the Internet,
using DragonFly gateways.
--------------------------------------------------------------
10.9.1 Understanding IPsec
Written by Hiten M. Pandya.
This section will guide you through the process of setting up
IPsec, and to use it in an environment which consists of DragonFly
and Microsoft Windows 2000/XP machines, to make them communicate
securely. In order to set up IPsec, it is necessary that you are
familiar with the concepts of building a custom kernel (see
Chapter 9).
IPsec is a protocol which sits on top of the Internet Protocol
(IP) layer. It allows two or more hosts to communicate in a secure
manner (hence the name). The DragonFly IPsec ``network stack'' is
based on the KAME implementation, which has support for both
protocol families, IPv4 and IPv6.
IPsec consists of two sub-protocols:
* Encapsulated Security Payload (ESP), protects the IP packet
data from third party interference, by encrypting the contents
using symmetric cryptography algorithms (like Blowfish, 3DES).
* Authentication Header (AH), protects the IP packet header from
third party interference and spoofing, by computing a
cryptographic checksum and hashing the IP packet header fields
with a secure hashing function. This is then followed by an
additional header that contains the hash, to allow the
information in the packet to be authenticated.
ESP and AH can either be used together or separately, depending on
the environment.
IPsec can either be used to directly encrypt the traffic between
two hosts (known as Transport Mode); or to build ``virtual
tunnels'' between two subnets, which could be used for secure
communication between two corporate networks (known as Tunnel
Mode). The latter is more commonly known as a Virtual Private
Network (VPN). The ipsec(4) manual page should be consulted for
detailed information on the IPsec subsystem in DragonFly.
To add IPsec support to your kernel, add the following options to
your kernel configuration file:
options IPSEC #IP security
options IPSEC_ESP #IP security (crypto; define w/ IPSEC)
If IPsec debugging support is desired, the following kernel option
should also be added:
options IPSEC_DEBUG #debug for IP security
--------------------------------------------------------------
10.9.2 The Problem
There's no standard for what constitutes a VPN. VPNs can be
implemented using a number of different technologies, each of
which have their own strengths and weaknesses. This article
presents a number of scenarios, and strategies for implementing a
VPN for each scenario.
--------------------------------------------------------------
10.9.3 Scenario #1: Two networks, connected to the Internet, to behave
as one
This is the scenario that caused me to first investigating VPNs.
The premise is as follows:
* You have at least two sites
* Both sites are using IP internally
* Both sites are connected to the Internet, through a gateway
that is running DragonFly.
* The gateway on each network has at least one public IP
address.
* The internal addresses of the two networks can be public or
private IP addresses, it doesn't matter. You can be running
NAT on the gateway machine if necessary.
* The internal IP addresses of the two networks do not collide.
While I expect it is theoretically possible to use a
combination of VPN technology and NAT to get this to work, I
expect it to be a configuration nightmare.
If you find that you are trying to connect two networks, both of
which, internally, use the same private IP address range (e.g.,
both of them use 192.168.1.x), then one of the networks will have
to be renumbered.
The network topology might look something like this:
Network #1 [ Internal Hosts ] Private Net, 192.168.1.2-254
[ Win9x/NT/2K ]
[ UNIX ]
|
|
.---[fxp1]---. Private IP, 192.168.1.1
DragonFly
`---[fxp0]---' Public IP, A.B.C.D
|
|
-=-=- Internet -=-=-
|
|
.---[fxp0]---. Public IP, W.X.Y.Z
DragonFly
`---[fxp1]---' Private IP, 192.168.2.1
|
|
Network #2 [ Internal Hosts ]
[ Win9x/NT/2K ] Private Net, 192.168.2.2-254
[ UNIX ]
Notice the two public IP addresses. I'll use the letters to refer
to them in the rest of this article. Anywhere you see those
letters in this article, replace them with your own public IP
addresses. Note also that internally, the two gateway machines
have .1 IP addresses, and that the two networks have different
private IP addresses (192.168.1.x and 192.168.2.x respectively).
All the machines on the private networks have been configured to
use the .1 machine as their default gateway.
The intention is that, from a network point of view, each network
should view the machines on the other network as though they were
directly attached the same router -- albeit a slightly slow router
with an occasional tendency to drop packets.
This means that (for example), machine 192.168.1.20 should be able
to run
ping 192.168.2.34
and have it work, transparently. Windows machines should be able
to see the machines on the other network, browse file shares, and
so on, in exactly the same way that they can browse machines on
the local network.
And the whole thing has to be secure. This means that traffic
between the two networks has to be encrypted.
Creating a VPN between these two networks is a multi-step process.
The stages are as follows:
1. Create a ``virtual'' network link between the two networks,
across the Internet. Test it, using tools like ping(8), to
make sure it works.
2. Apply security policies to ensure that traffic between the two
networks is transparently encrypted and decrypted as
necessary. Test this, using tools like tcpdump(1), to ensure
that traffic is encrypted.
3. Configure additional software on the DragonFly gateways, to
allow Windows machines to see one another across the VPN.
--------------------------------------------------------------
10.9.3.1 Step 1: Creating and testing a ``virtual'' network link
Suppose that you were logged in to the gateway machine on network
#1 (with public IP address A.B.C.D, private IP address
192.168.1.1), and you ran ping 192.168.2.1, which is the private
address of the machine with IP address W.X.Y.Z. What needs to
happen in order for this to work?
1. The gateway machine needs to know how to reach 192.168.2.1. In
other words, it needs to have a route to 192.168.2.1.
2. Private IP addresses, such as those in the 192.168.x range are
not supposed to appear on the Internet at large. Instead, each
packet you send to 192.168.2.1 will need to be wrapped up
inside another packet. This packet will need to appear to be
from A.B.C.D, and it will have to be sent to W.X.Y.Z. This
process is called encapsulation.
3. Once this packet arrives at W.X.Y.Z it will need to
``unencapsulated'', and delivered to 192.168.2.1.
You can think of this as requiring a ``tunnel'' between the two
networks. The two ``tunnel mouths'' are the IP addresses A.B.C.D
and W.X.Y.Z, and the tunnel must be told the addresses of the
private IP addresses that will be allowed to pass through it. The
tunnel is used to transfer traffic with private IP addresses
across the public Internet.
This tunnel is created by using the generic interface, or gif
devices on DragonFly. As you can imagine, the gif interface on
each gateway host must be configured with four IP addresses; two
for the public IP addresses, and two for the private IP addresses.
Support for the gif device must be compiled in to the DragonFly
kernel on both machines. You can do this by adding the line:
pseudo-device gif
to the kernel configuration files on both machines, and then
compile, install, and reboot as normal.
Configuring the tunnel is a two step process. First the tunnel
must be told what the outside (or public) IP addresses are, using
gifconfig(8). Then the private IP addresses must be configured
using ifconfig(8).
On the gateway machine on network #1 you would run the following
two commands to configure the tunnel.
gifconfig gif0 A.B.C.D W.X.Y.Z
ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
On the other gateway machine you run the same commands, but with
the order of the IP addresses reversed.
gifconfig gif0 W.X.Y.Z A.B.C.D
ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
You can then run:
gifconfig gif0
to see the configuration. For example, on the network #1 gateway,
you would see this:
# gifconfig gif0
gif0: flags=8011 mtu 1280
inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff
physical address inet A.B.C.D --> W.X.Y.Z
As you can see, a tunnel has been created between the physical
addresses A.B.C.D and W.X.Y.Z, and the traffic allowed through the
tunnel is that between 192.168.1.1 and 192.168.2.1.
This will also have added an entry to the routing table on both
machines, which you can examine with the command netstat -rn. This
output is from the gateway host on network #1.
# netstat -rn
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
...
192.168.2.1 192.168.1.1 UH 0 0 gif0
...
As the ``Flags'' value indicates, this is a host route, which
means that each gateway knows how to reach the other gateway, but
they do not know how to reach the rest of their respective
networks. That problem will be fixed shortly.
It is likely that you are running a firewall on both machines.
This will need to be circumvented for your VPN traffic. You might
want to allow all traffic between both networks, or you might want
to include firewall rules that protect both ends of the VPN from
one another.
It greatly simplifies testing if you configure the firewall to
allow all traffic through the VPN. You can always tighten things
up later. If you are using ipfw(8) on the gateway machines then a
command like
ipfw add 1 allow ip from any to any via gif0
will allow all traffic between the two end points of the VPN,
without affecting your other firewall rules. Obviously you will
need to run this command on both gateway hosts.
This is sufficient to allow each gateway machine to ping the
other. On 192.168.1.1, you should be able to run
ping 192.168.2.1
and get a response, and you should be able to do the same thing on
the other gateway machine.
However, you will not be able to reach internal machines on either
network yet. This is because of the routing -- although the
gateway machines know how to reach one another, they do not know
how to reach the network behind each one.
To solve this problem you must add a static route on each gateway
machine. The command to do this on the first gateway would be:
route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
This says ``In order to reach the hosts on the network
192.168.2.0, send the packets to the host 192.168.2.1''. You will
need to run a similar command on the other gateway, but with the
192.168.1.x addresses instead.
IP traffic from hosts on one network will now be able to reach
hosts on the other network.
That has now created two thirds of a VPN between the two networks,
in as much as it is ``virtual'' and it is a ``network''. It is not
private yet. You can test this using ping(8) and tcpdump(1). Log
in to the gateway host and run
tcpdump dst host 192.168.2.1
In another log in session on the same host run
ping 192.168.2.1
You will see output that looks something like this:
16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request
16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply
16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request
16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply
16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request
16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply
As you can see, the ICMP messages are going back and forth
unencrypted. If you had used the -s parameter to tcpdump(1) to
grab more bytes of data from the packets you would see more
information.
Obviously this is unacceptable. The next section will discuss
securing the link between the two networks so that it all traffic
is automatically encrypted.
Summary:
* Configure both kernels with ``pseudo-device gif''.
* Edit /etc/rc.conf on gateway host #1 and add the following
lines (replacing IP addresses as necessary).
gifconfig_gif0="A.B.C.D W.X.Y.Z"
ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
static_routes="vpn"
route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
* Edit your firewall script (/etc/rc.firewall, or similar) on
both hosts, and add
ipfw add 1 allow ip from any to any via gif0
* Make similar changes to /etc/rc.conf on gateway host #2,
reversing the order of IP addresses.
--------------------------------------------------------------
10.9.3.2 Step 2: Securing the link
To secure the link we will be using IPsec. IPsec provides a
mechanism for two hosts to agree on an encryption key, and to then
use this key in order to encrypt data between the two hosts.
The are two areas of configuration to be considered here.
1. There must be a mechanism for two hosts to agree on the
encryption mechanism to use. Once two hosts have agreed on
this mechanism there is said to be a ``security association''
between them.
2. There must be a mechanism for specifying which traffic should
be encrypted. Obviously, you don't want to encrypt all your
outgoing traffic -- you only want to encrypt the traffic that
is part of the VPN. The rules that you put in place to
determine what traffic will be encrypted are called ``security
policies''.
Security associations and security policies are both maintained by
the kernel, and can be modified by userland programs. However,
before you can do this you must configure the kernel to support
IPsec and the Encapsulated Security Payload (ESP) protocol. This
is done by configuring a kernel with:
options IPSEC
options IPSEC_ESP
and recompiling, reinstalling, and rebooting. As before you will
need to do this to the kernels on both of the gateway hosts.
You have two choices when it comes to setting up security
associations. You can configure them by hand between two hosts,
which entails choosing the encryption algorithm, encryption keys,
and so forth, or you can use daemons that implement the Internet
Key Exchange protocol (IKE) to do this for you.
I recommend the latter. Apart from anything else, it is easier to
set up.
Editing and displaying security policies is carried out using
setkey(8). By analogy, setkey is to the kernel's security policy
tables as route(8) is to the kernel's routing tables. setkey can
also display the current security associations, and to continue
the analogy further, is akin to netstat -r in that respect.
There are a number of choices for daemons to manage security
associations with DragonFly. This article will describe how to use
one of these, racoon. racoon is in the FreeBSD ports collection,
in the security/ category, and is installed in the usual way.
racoon must be run on both gateway hosts. On each host it is
configured with the IP address of the other end of the VPN, and a
secret key (which you choose, and must be the same on both
gateways).
The two daemons then contact one another, confirm that they are
who they say they are (by using the secret key that you
configured). The daemons then generate a new secret key, and use
this to encrypt the traffic over the VPN. They periodically change
this secret, so that even if an attacker were to crack one of the
keys (which is as theoretically close to unfeasible as it gets) it
won't do them much good -- by the time they've cracked the key the
two daemons have chosen another one.
racoon's configuration is stored in ${PREFIX}/etc/racoon. You
should find a configuration file there, which should not need to
be changed too much. The other component of racoon's
configuration, which you will need to change, is the ``pre-shared
key''.
The default racoon configuration expects to find this in the file
${PREFIX}/etc/racoon/psk.txt. It is important to note that the
pre-shared key is not the key that will be used to encrypt your
traffic across the VPN link, it is simply a token that allows the
key management daemons to trust one another.
psk.txt contains a line for each remote site you are dealing with.
In this example, where there are two sites, each psk.txt file will
contain one line (because each end of the VPN is only dealing with
one other end).
On gateway host #1 this line should look like this:
W.X.Y.Z secret
That is, the public IP address of the remote end, whitespace, and
a text string that provides the secret. Obviously, you shouldn't
use ``secret'' as your key -- the normal rules for choosing a
password apply.
On gateway host #2 the line would look like this
A.B.C.D secret
That is, the public IP address of the remote end, and the same
secret key. psk.txt must be mode 0600 (i.e., only read/write to
root) before racoon will run.
You must run racoon on both gateway machines. You will also need
to add some firewall rules to allow the IKE traffic, which is
carried over UDP to the ISAKMP (Internet Security Association Key
Management Protocol) port. Again, this should be fairly early in
your firewall ruleset.
ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
Once racoon is running you can try pinging one gateway host from
the other. The connection is still not encrypted, but racoon will
then set up the security associations between the two hosts --
this might take a moment, and you may see this as a short delay
before the ping commands start responding.
Once the security association has been set up you can view it
using setkey(8). Run
setkey -D
on either host to view the security association information.
That's one half of the problem. They other half is setting your
security policies.
To create a sensible security policy, let's review what's been set
up so far. This discussions hold for both ends of the link.
Each IP packet that you send out has a header that contains data
about the packet. The header includes the IP addresses of both the
source and destination. As we already know, private IP addresses,
such as the 192.168.x.y range are not supposed to appear on the
public Internet. Instead, they must first be encapsulated inside
another packet. This packet must have the public source and
destination IP addresses substituted for the private addresses.
So if your outgoing packet started looking like this:
.----------------------.
| Src: 192.168.1.1 |
| Dst: 192.168.2.1 |
| |
+----------------------+
| |
`----------------------'
Then it will be encapsulated inside another packet, looking
something like this:
.--------------------------.
| Src: A.B.C.D |
| Dst: W.X.Y.Z |
| |
+--------------------------+
| .----------------------. |
| | Src: 192.168.1.1 | |
| | Dst: 192.168.2.1 | |
| | | |
| +----------------------+ |
| | | |
| `----------------------' |
`--------------------------'
This encapsulation is carried out by the gif device. As you can
see, the packet now has real IP addresses on the outside, and our
original packet has been wrapped up as data inside the packet that
will be put out on the Internet.
Obviously, we want all traffic between the VPNs to be encrypted.
You might try putting this in to words, as:
``If a packet leaves from A.B.C.D, and it is destined for W.X.Y.Z,
then encrypt it, using the necessary security associations.''
``If a packet arrives from W.X.Y.Z, and it is destined for
A.B.C.D, then decrypt it, using the necessary security
associations.''
That's close, but not quite right. If you did this, all traffic to
and from W.X.Y.Z, even traffic that was not part of the VPN, would
be encrypted. That's not quite what you want. The correct policy
is as follows
``If a packet leaves from A.B.C.D, and that packet is
encapsulating another packet, and it is destined for W.X.Y.Z, then
encrypt it, using the necessary security associations.''
``If a packet arrives from W.X.Y.Z, and that packet is
encapsulating another packet, and it is destined for A.B.C.D, then
encrypt it, using the necessary security associations.''
A subtle change, but a necessary one.
Security policies are also set using setkey(8). setkey(8) features
a configuration language for defining the policy. You can either
enter configuration instructions via stdin, or you can use the -f
option to specify a filename that contains configuration
instructions.
The configuration on gateway host #1 (which has the public IP
address A.B.C.D) to force all outbound traffic to W.X.Y.Z to be
encrypted is:
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;
Put these commands in a file (e.g., /etc/ipsec.conf) and then run
# setkey -f /etc/ipsec.conf
spdadd tells setkey(8) that we want to add a rule to the secure
policy database. The rest of this line specifies which packets
will match this policy. A.B.C.D/32 and W.X.Y.Z/32 are the IP
addresses and netmasks that identify the network or hosts that
this policy will apply to. In this case, we want it to apply to
traffic between these two hosts. ipencap tells the kernel that
this policy should only apply to packets that encapsulate other
packets. -P out says that this policy applies to outgoing packets,
and ipsec says that the packet will be secured.
The second line specifies how this packet will be encrypted. esp
is the protocol that will be used, while tunnel indicates that the
packet will be further encapsulated in an IPsec packet. The
repeated use of A.B.C.D and W.X.Y.Z is used to select the security
association to use, and the final require mandates that packets
must be encrypted if they match this rule.
This rule only matches outgoing packets. You will need a similar
rule to match incoming packets.
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;
Note the in instead of out in this case, and the necessary
reversal of the IP addresses.
The other gateway host (which has the public IP address W.X.Y.Z)
will need similar rules.
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;
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;
Finally, you need to add firewall rules to allow ESP and IPENCAP
packets back and forth. These rules will need to be added to both
hosts.
ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
Because the rules are symmetric you can use the same rules on each
gateway host.
Outgoing packets will now look something like this:
.------------------------------. --------------------------.
| Src: A.B.C.D | |
| Dst: W.X.Y.Z | |
| | | Encrypted
+------------------------------+ | packet.
| .--------------------------. | -------------. | contents
| | Src: A.B.C.D | | | | are
| | Dst: W.X.Y.Z | | | | completely
| | | | | |- secure
| +--------------------------+ | | Encap'd | from third
| | .----------------------. | | -. | packet | party
| | | Src: 192.168.1.1 | | | | Original |- with real | snooping
| | | Dst: 192.168.2.1 | | | | packet, | IP addr |
| | | | | | |- private | |
| | +----------------------+ | | | IP addr | |
| | | | | | | | |
| | `----------------------' | | -' | |
| `--------------------------' | -------------' |
`------------------------------' --------------------------'
When they are received by the far end of the VPN they will first
be decrypted (using the security associations that have been
negotiated by racoon). Then they will enter the gif interface,
which will unwrap the second layer, until you are left with the
innermost packet, which can then travel in to the inner network.
You can check the security using the same ping(8) test from
earlier. First, log in to the A.B.C.D gateway machine, and run:
tcpdump dst host 192.168.2.1
In another log in session on the same host run
ping 192.168.2.1
This time you should see output like the following:
XXX tcpdump output
Now, as you can see, tcpdump(1) shows the ESP packets. If you try
to examine them with the -s option you will see (apparently)
gibberish, because of the encryption.
Congratulations. You have just set up a VPN between two remote
sites.
Summary
* Configure both kernels with:
options IPSEC
options IPSEC_ESP
* Install security/racoon. Edit ${PREFIX}/etc/racoon/psk.txt on
both gateway hosts, adding an entry for the remote host's IP
address and a secret key that they both know. Make sure this
file is mode 0600.
* Add the following lines to /etc/rc.conf on each host:
ipsec_enable="YES"
ipsec_file="/etc/ipsec.conf"
* Create an /etc/ipsec.conf on each host that contains the
necessary spdadd lines. On gateway host #1 this would be:
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;
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;
On gateway host #2 this would be:
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;
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;
* Add firewall rules to allow IKE, ESP, and IPENCAP traffic to
both hosts:
ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
The previous two steps should suffice to get the VPN up and
running. Machines on each network will be able to refer to one
another using IP addresses, and all traffic across the link will
be automatically and securely encrypted.
--------------------------------------------------------------
10.10 OpenSSH
Contributed by Chern Lee.
OpenSSH is a set of network connectivity tools used to access
remote machines securely. It can be used as a direct replacement
for rlogin, rsh, rcp, and telnet. Additionally, any other TCP/IP
connections can be tunneled/forwarded securely through SSH.
OpenSSH encrypts all traffic to effectively eliminate
eavesdropping, connection hijacking, and other network-level
attacks.
OpenSSH is maintained by the OpenBSD project, and is based upon
SSH v1.2.12 with all the recent bug fixes and updates. It is
compatible with both SSH protocols 1 and 2.
--------------------------------------------------------------
10.10.1 Advantages of Using OpenSSH
Normally, when using telnet(1) or rlogin(1), data is sent over the
network in an clear, un-encrypted form. Network sniffers anywhere
in between the client and server can steal your user/password
information or data transferred in your session. OpenSSH offers a
variety of authentication and encryption methods to prevent this
from happening.
--------------------------------------------------------------
10.10.2 Enabling sshd
Be sure to make the following addition to your rc.conf file:
sshd_enable="YES"
This will load sshd(8), the daemon program for OpenSSH, the next
time your system initializes. Alternatively, you can simply run
directly the sshd daemon by typing sshd on the command line.
--------------------------------------------------------------
10.10.3 SSH Client
The ssh(1) utility works similarly to rlogin(1).
# ssh user@example.com
Host key not found from the list of known hosts.
Are you sure you want to continue connecting (yes/no)? yes
Host 'example.com' added to the list of known hosts.
user@example.com's password: *******
The login will continue just as it would have if a session was
created using rlogin or telnet. SSH utilizes a key fingerprint
system for verifying the authenticity of the server when the
client connects. The user is prompted to enter yes only when
connecting for the first time. Future attempts to login are all
verified against the saved fingerprint key. The SSH client will
alert you if the saved fingerprint differs from the received
fingerprint on future login attempts. The fingerprints are saved
in ~/.ssh/known_hosts, or ~/.ssh/known_hosts2 for SSH v2
fingerprints.
By default, OpenSSH servers are configured to accept both SSH v1
and SSH v2 connections. The client, however, can choose between
the two. Version 2 is known to be more robust and secure than its
predecessor.
The ssh(1) command can be forced to use either protocol by passing
it the -1 or -2 argument for v1 and v2, respectively.
--------------------------------------------------------------
10.10.4 Secure Copy
The scp(1) command works similarly to rcp(1); it copies a file to
or from a remote machine, except in a secure fashion.
# scp user@example.com:/COPYRIGHT COPYRIGHT
user@example.com's password: *******
COPYRIGHT 100% |*****************************| 4735
00:00
#
Since the fingerprint was already saved for this host in the
previous example, it is verified when using scp(1) here.
The arguments passed to scp(1) are similar to cp(1), with the file
or files in the first argument, and the destination in the second.
Since the file is fetched over the network, through SSH, one or
more of the file arguments takes on the form
user@host:.
--------------------------------------------------------------
10.10.5 Configuration
The system-wide configuration files for both the OpenSSH daemon
and client reside within the /etc/ssh directory.
ssh_config configures the client settings, while sshd_config
configures the daemon.
Additionally, the sshd_program (/usr/sbin/sshd by default), and
sshd_flags rc.conf options can provide more levels of
configuration.
--------------------------------------------------------------
10.10.6 ssh-keygen
Instead of using passwords, ssh-keygen(1) can be used to generate
RSA keys to authenticate a user:
% ssh-keygen -t rsa1
Initializing random number generator...
Generating p: .++ (distance 66)
Generating q: ..............................++ (distance 498)
Computing the keys...
Key generation complete.
Enter file in which to save the key (/home/user/.ssh/identity):
Enter passphrase:
Enter the same passphrase again:
Your identification has been saved in /home/user/.ssh/identity.
...
ssh-keygen(1) will create a public and private key pair for use in
authentication. The private key is stored in ~/.ssh/identity,
whereas the public key is stored in ~/.ssh/identity.pub. The
public key must be placed in ~/.ssh/authorized_keys of the remote
machine in order for the setup to work.
This will allow connection to the remote machine based upon RSA
authentication instead of passwords.
Note: The -t rsa1 option will create RSA keys for use by SSH
protocol version 1. If you want to use RSA keys with the SSH
protocol version 2, you have to use the command ssh-keygen -t
rsa.
If a passphrase is used in ssh-keygen(1), the user will be
prompted for a password each time in order to use the private key.
A SSH protocol version 2 DSA key can be created for the same
purpose by using the ssh-keygen -t dsa command. This will create a
public/private DSA key for use in SSH protocol version 2 sessions
only. The public key is stored in ~/.ssh/id_dsa.pub, while the
private key is in ~/.ssh/id_dsa.
DSA public keys are also placed in ~/.ssh/authorized_keys on the
remote machine.
ssh-agent(1) and ssh-add(1) are utilities used in managing
multiple passworded private keys.
Warning: The various options and files can be different
according to the OpenSSH version you have on your system, to
avoid problems you should consult the ssh-keygen(1) manual page.
--------------------------------------------------------------
10.10.7 SSH Tunneling
OpenSSH has the ability to create a tunnel to encapsulate another
protocol in an encrypted session.
The following command tells ssh(1) to create a tunnel for telnet:
% ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
%
The ssh command is used with the following options:
-2
Forces ssh to use version 2 of the protocol. (Do not use
if you are working with older SSH servers)
-N
Indicates no command, or tunnel only. If omitted, ssh
would initiate a normal ses