GOPHERSPACE.DE - P H O X Y
gophering on eyeblea.ch
                                FreeBSD Handbook

  The FreeBSD Documentation Project

   Revision: 53526

   Copyright (c) 1995-2019 The FreeBSD Documentation Project

   Copyright

   Redistribution and use in source (XML DocBook) and 'compiled' forms (XML,
   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 (XML 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 FREEBSD DOCUMENTATION 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 FREEBSD DOCUMENTATION
   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.

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   3Com and HomeConnect are registered trademarks of 3Com Corporation.

   3ware is a registered trademark of 3ware Inc.

   ARM is a registered trademark of ARM Limited.

   Adaptec is a registered trademark of Adaptec, Inc.

   Adobe, Acrobat, Acrobat Reader, Flash and PostScript are either registered
   trademarks or trademarks of Adobe Systems Incorporated in the United
   States and/or other countries.

   Apple, AirPort, FireWire, iMac, iPhone, iPad, Mac, Macintosh, Mac OS,
   Quicktime, and TrueType are trademarks of Apple Inc., registered in the
   U.S. and other countries.

   Android is a trademark of Google Inc.

   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, 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, Centrino, Core, 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.

   LSI Logic, AcceleRAID, eXtremeRAID, MegaRAID and Mylex are trademarks or
   registered trademarks of LSI Logic Corp.

   Microsoft, IntelliMouse, 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.

   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.

   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.

   Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM,
   Netra, OpenJDK, Solaris, StarOffice, SunOS and VirtualBox are trademarks
   or registered trademarks of Sun Microsystems, Inc. in the United States
   and other countries.

   MATLAB is a registered trademark of The MathWorks, Inc.

   SpeedTouch is a trademark of Thomson.

   VMware is a trademark of VMware, 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.

   Last modified on 2019-11-03 11:06:00 by bcr.
   Abstract

   Welcome to FreeBSD! This handbook covers the installation and day to day
   use of FreeBSD 12.0-RELEASE and FreeBSD 11.3-RELEASE. This book is the
   result of ongoing work by many individuals. Some sections might be
   outdated. Those interested in helping to update and expand this document
   should send email to the FreeBSD documentation project mailing list.

   The latest version of this book is available from the FreeBSD web site.
   Previous versions can be obtained from https://docs.FreeBSD.org/doc/. The
   book can be downloaded in a variety of formats and compression options
   from the FreeBSD FTP server or one of the numerous mirror sites. Printed
   copies can be purchased at the FreeBSD Mall. Searches can be performed on
   the handbook and other documents on the search page.

   [ Split HTML / Single HTML ]

     ----------------------------------------------------------------------

   Table of Contents

   Preface

   I. Getting Started

                1. Introduction

                             1.1. Synopsis

                             1.2. Welcome to FreeBSD!

                             1.3. About the FreeBSD Project

                2. Installing FreeBSD

                             2.1. Synopsis

                             2.2. Minimum Hardware Requirements

                             2.3. Pre-Installation Tasks

                             2.4. Starting the Installation

                             2.5. Using bsdinstall

                             2.6. Allocating Disk Space

                             2.7. Committing to the Installation

                             2.8. Post-Installation

                             2.9. Troubleshooting

                             2.10. Using the Live CD

                3. FreeBSD Basics

                             3.1. Synopsis

                             3.2. Virtual Consoles and Terminals

                             3.3. Users and Basic Account Management

                             3.4. Permissions

                             3.5. Directory Structure

                             3.6. Disk Organization

                             3.7. Mounting and Unmounting File Systems

                             3.8. Processes and Daemons

                             3.9. Shells

                             3.10. Text Editors

                             3.11. Devices and Device Nodes

                             3.12. Manual Pages

                4. Installing Applications: Packages and Ports

                             4.1. Synopsis

                             4.2. Overview of Software Installation

                             4.3. Finding Software

                             4.4. Using pkg for Binary Package Management

                             4.5. Using the Ports Collection

                             4.6. Building Packages with Poudriere

                             4.7. Post-Installation Considerations

                             4.8. Dealing with Broken Ports

                5. The X Window System

                             5.1. Synopsis

                             5.2. Terminology

                             5.3. Installing Xorg

                             5.4. Xorg Configuration

                             5.5. Using Fonts in Xorg

                             5.6. The X Display Manager

                             5.7. Desktop Environments

                             5.8. Installing Compiz Fusion

                             5.9. Troubleshooting

   II. Common Tasks

                6. Desktop Applications

                             6.1. Synopsis

                             6.2. Browsers

                             6.3. Productivity

                             6.4. Document Viewers

                             6.5. Finance

                7. Multimedia

                             7.1. Synopsis

                             7.2. Setting Up the Sound Card

                             7.3. MP3 Audio

                             7.4. Video Playback

                             7.5. TV Cards

                             7.6. MythTV

                             7.7. Image Scanners

                8. Configuring the FreeBSD Kernel

                             8.1. Synopsis

                             8.2. Why Build a Custom Kernel?

                             8.3. Finding the System Hardware

                             8.4. The Configuration File

                             8.5. Building and Installing a Custom Kernel

                             8.6. If Something Goes Wrong

                9. Printing

                             9.1. Quick Start

                             9.2. Printer Connections

                             9.3. Common Page Description Languages

                             9.4. Direct Printing

                             9.5. LPD (Line Printer Daemon)

                             9.6. Other Printing Systems

                10. Linux(R) Binary Compatibility

                             10.1. Synopsis

                             10.2. Configuring Linux(R) Binary Compatibility

                             10.3. Advanced Topics

   III. System Administration

                11. Configuration and Tuning

                             11.1. Synopsis

                             11.2. Starting Services

                             11.3. Configuring cron(8)

                             11.4. Managing Services in FreeBSD

                             11.5. Setting Up Network Interface Cards

                             11.6. Virtual Hosts

                             11.7. Configuring System Logging

                             11.8. Configuration Files

                             11.9. Tuning with sysctl(8)

                             11.10. Tuning Disks

                             11.11. Tuning Kernel Limits

                             11.12. Adding Swap Space

                             11.13. Power and Resource Management

                12. The FreeBSD Booting Process

                             12.1. Synopsis

                             12.2. FreeBSD Boot Process

                             12.3. Configuring Boot Time Splash Screens

                             12.4. Device Hints

                             12.5. Shutdown Sequence

                13. Security

                             13.1. Synopsis

                             13.2. Introduction

                             13.3. One-time Passwords

                             13.4. TCP Wrapper

                             13.5. Kerberos

                             13.6. OpenSSL

                             13.7. VPN over IPsec

                             13.8. OpenSSH

                             13.9. Access Control Lists

                             13.10. Monitoring Third Party Security Issues

                             13.11. FreeBSD Security Advisories

                             13.12. Process Accounting

                             13.13. Resource Limits

                             13.14. Shared Administration with Sudo

                14. Jails

                             14.1. Synopsis

                             14.2. Terms Related to Jails

                             14.3. Creating and Controlling Jails

                             14.4. Fine Tuning and Administration

                             14.5. Updating Multiple Jails

                             14.6. Managing Jails with ezjail

                15. Mandatory Access Control

                             15.1. Synopsis

                             15.2. Key Terms

                             15.3. Understanding MAC Labels

                             15.4. Planning the Security Configuration

                             15.5. Available MAC Policies

                             15.6. User Lock Down

                             15.7. Nagios in a MAC Jail

                             15.8. Troubleshooting the MAC Framework

                16. Security Event Auditing

                             16.1. Synopsis

                             16.2. Key Terms

                             16.3. Audit Configuration

                             16.4. Working with Audit Trails

                17. Storage

                             17.1. Synopsis

                             17.2. Adding Disks

                             17.3. Resizing and Growing Disks

                             17.4. USB Storage Devices

                             17.5. Creating and Using CD Media

                             17.6. Creating and Using DVD Media

                             17.7. Creating and Using Floppy Disks

                             17.8. Backup Basics

                             17.9. Memory Disks

                             17.10. File System Snapshots

                             17.11. Disk Quotas

                             17.12. Encrypting Disk Partitions

                             17.13. Encrypting Swap

                             17.14. Highly Available Storage (HAST)

                18. GEOM: Modular Disk Transformation Framework

                             18.1. Synopsis

                             18.2. RAID0 - Striping

                             18.3. RAID1 - Mirroring

                             18.4. RAID3 - Byte-level Striping with Dedicated
                             Parity

                             18.5. Software RAID Devices

                             18.6. GEOM Gate Network

                             18.7. Labeling Disk Devices

                             18.8. UFS Journaling Through GEOM

                19. The Z File System (ZFS)

                             19.1. What Makes ZFS Different

                             19.2. Quick Start Guide

                             19.3. zpool Administration

                             19.4. zfs Administration

                             19.5. Delegated Administration

                             19.6. Advanced Topics

                             19.7. Additional Resources

                             19.8. ZFS Features and Terminology

                20. Other File Systems

                             20.1. Synopsis

                             20.2. Linux(R) File Systems

                21. Virtualization

                             21.1. Synopsis

                             21.2. FreeBSD as a Guest on Parallels for
                             Mac OS(R) X

                             21.3. FreeBSD as a Guest on Virtual PC for
                             Windows(R)

                             21.4. FreeBSD as a Guest on VMware Fusion for
                             Mac OS(R)

                             21.5. FreeBSD as a Guest on VirtualBox(TM)

                             21.6. FreeBSD as a Host with VirtualBox(TM)

                             21.7. FreeBSD as a Host with bhyve

                             21.8. FreeBSD as a Xen(TM)-Host

                22. Localization - i18n/L10n Usage and Setup

                             22.1. Synopsis

                             22.2. Using Localization

                             22.3. Finding i18n Applications

                             22.4. Locale Configuration for Specific
                             Languages

                23. Updating and Upgrading FreeBSD

                             23.1. Synopsis

                             23.2. FreeBSD Update

                             23.3. Updating the Documentation Set

                             23.4. Tracking a Development Branch

                             23.5. Updating FreeBSD from Source

                             23.6. Tracking for Multiple Machines

                24. DTrace

                             24.1. Synopsis

                             24.2. Implementation Differences

                             24.3. Enabling DTrace Support

                             24.4. Using DTrace

                25. USB Device Mode / USB OTG

                             25.1. Synopsis

                             25.2. USB Virtual Serial Ports

                             25.3. USB Device Mode Network Interfaces

                             25.4. USB Virtual Storage Device

   IV. Network Communication

                26. Serial Communications

                             26.1. Synopsis

                             26.2. Serial Terminology and Hardware

                             26.3. Terminals

                             26.4. Dial-in Service

                             26.5. Dial-out Service

                             26.6. Setting Up the Serial Console

                27. PPP

                             27.1. Synopsis

                             27.2. Configuring PPP

                             27.3. Troubleshooting PPP Connections

                             27.4. Using PPP over Ethernet (PPPoE)

                             27.5. Using PPP over ATM (PPPoA)

                28. Electronic Mail

                             28.1. Synopsis

                             28.2. Mail Components

                             28.3. Sendmail Configuration Files

                             28.4. Changing the Mail Transfer Agent

                             28.5. Troubleshooting

                             28.6. Advanced Topics

                             28.7. Setting Up to Send Only

                             28.8. Using Mail with a Dialup Connection

                             28.9. SMTP Authentication

                             28.10. Mail User Agents

                             28.11. Using fetchmail

                             28.12. Using procmail

                29. Network Servers

                             29.1. Synopsis

                             29.2. The inetd Super-Server

                             29.3. Network File System (NFS)

                             29.4. Network Information System (NIS)

                             29.5. Lightweight Directory Access Protocol
                             (LDAP)

                             29.6. Dynamic Host Configuration Protocol (DHCP)

                             29.7. Domain Name System (DNS)

                             29.8. Apache HTTP Server

                             29.9. File Transfer Protocol (FTP)

                             29.10. File and Print Services for
                             Microsoft(R) Windows(R) Clients (Samba)

                             29.11. Clock Synchronization with NTP

                             29.12. iSCSI Initiator and Target Configuration

                30. Firewalls

                             30.1. Synopsis

                             30.2. Firewall Concepts

                             30.3. PF

                             30.4. IPFW

                             30.5. IPFILTER (IPF)

                             30.6. Blacklistd

                31. Advanced Networking

                             31.1. Synopsis

                             31.2. Gateways and Routes

                             31.3. Wireless Networking

                             31.4. USB Tethering

                             31.5. Bluetooth

                             31.6. Bridging

                             31.7. Link Aggregation and Failover

                             31.8. Diskless Operation with PXE

                             31.9. IPv6

                             31.10. Common Address Redundancy Protocol (CARP)

                             31.11. VLANs

   V. Appendices

                A. Obtaining FreeBSD

                             A.1. CD and DVD Sets

                             A.2. FTP Sites

                             A.3. Using Subversion

                             A.4. Using rsync

                B. Bibliography

                             B.1. Books Specific to FreeBSD

                             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(R) History

                             B.9. Periodicals, Journals, and Magazines

                C. Resources on the Internet

                             C.1. Websites

                             C.2. Mailing Lists

                             C.3. Usenet Newsgroups

                             C.4. Official Mirrors

                D. OpenPGP Keys

                             D.1. Officers

   FreeBSD Glossary

   Index

   List of Figures

   2.1. FreeBSD Boot Loader Menu

   2.2. FreeBSD Boot Options Menu

   2.3. Welcome Menu

   2.4. Keymap Selection

   2.5. Selecting Keyboard Menu

   2.6. Enhanced Keymap Menu

   2.7. Setting the Hostname

   2.8. Selecting Components to Install

   2.9. Installing from the Network

   2.10. Choosing a Mirror

   2.11. Partitioning Choices on FreeBSD 10.x and Higher

   2.12. Selecting from Multiple Disks

   2.13. Selecting Entire Disk or Partition

   2.14. Review Created Partitions

   2.15. Manually Create Partitions

   2.16. Manually Create Partitions

   2.17. Manually Create Partitions

   2.18. ZFS Partitioning Menu

   2.19. ZFS Pool Type

   2.20. Disk Selection

   2.21. Invalid Selection

   2.22. Analyzing a Disk

   2.23. Disk Encryption Password

   2.24. Last Chance

   2.25. Final Confirmation

   2.26. Fetching Distribution Files

   2.27. Verifying Distribution Files

   2.28. Extracting Distribution Files

   2.29. Setting the root Password

   2.30. Choose a Network Interface

   2.31. Scanning for Wireless Access Points

   2.32. Choosing a Wireless Network

   2.33. WPA2 Setup

   2.34. Choose IPv4 Networking

   2.35. Choose IPv4 DHCP Configuration

   2.36. IPv4 Static Configuration

   2.37. Choose IPv6 Networking

   2.38. Choose IPv6 SLAAC Configuration

   2.39. IPv6 Static Configuration

   2.40. DNS Configuration

   2.41. Select Local or UTC Clock

   2.42. Select a Region

   2.43. Select a Country

   2.44. Select a Time Zone

   2.45. Confirm Time Zone

   2.46. Selecting Additional Services to Enable

   2.47. Enabling Crash Dumps

   2.48. Add User Accounts

   2.49. Enter User Information

   2.50. Exit User and Group Management

   2.51. Final Configuration

   2.52. Manual Configuration

   2.53. Complete the Installation

   31.1. PXE Booting Process with NFS Root Mount

   List of Tables

   2.1. Partitioning Schemes

   3.1. Utilities for Managing User Accounts

   3.2. UNIX(R) Permissions

   3.3. Disk Device Names

   3.4. Common Environment Variables

   5.1. XDM Configuration Files

   7.1. Common Error Messages

   9.1. Output PDLs

   12.1. Loader Built-In Commands

   12.2. Kernel Interaction During Boot

   13.1. Login Class Resource Limits

   16.1. Default Audit Event Classes

   16.2. Prefixes for Audit Event Classes

   22.1. Common Language and Country Codes

   22.2. Defined Terminal Types for Character Sets

   22.3. Available Console from Ports Collection

   22.4. Available Input Methods

   23.1. FreeBSD Versions and Repository Paths

   26.1. RS-232C Signal Names

   26.2. DB-25 to DB-25 Null-Modem Cable

   26.3. DB-9 to DB-9 Null-Modem Cable

   26.4. DB-9 to DB-25 Null-Modem Cable

   29.1. NIS Terminology

   29.2. Additional Users

   29.3. Additional Systems

   29.4. DNS Terminology

   30.1. Useful pfctl Options

   31.1. Commonly Seen Routing Table Flags

   31.2. Station Capability Codes

   31.3. Reserved IPv6 Addresses

   List of Examples

   2.1. Creating Traditional Split File System Partitions

   3.1. Install a Program As the Superuser

   3.2. Adding a User on FreeBSD

   3.3. rmuser Interactive Account Removal

   3.4. Using chpass as Superuser

   3.5. Using chpass as Regular User

   3.6. Changing Your Password

   3.7. Changing Another User's Password as the Superuser

   3.8. Adding a Group Using pw(8)

   3.9. Adding User Accounts to a New Group Using pw(8)

   3.10. Adding a New Member to a Group Using pw(8)

   3.11. Using id(1) to Determine Group Membership

   3.12. Sample Disk, Slice, and Partition Names

   3.13. Conceptual Model of a Disk

   5.1. Select Intel(R) Video Driver in a File

   5.2. Select Radeon Video Driver in a File

   5.3. Select VESA Video Driver in a File

   5.4. Select scfb Video Driver in a File

   5.5. Set Screen Resolution in a File

   5.6. Manually Setting Monitor Frequencies

   5.7. Setting a Keyboard Layout

   5.8. Setting Multiple Keyboard Layouts

   5.9. Enabling Keyboard Exit from X

   5.10. Setting the Number of Mouse Buttons

   11.1. Sample Log Server Configuration

   11.2. Creating a Swap File on FreeBSD 10.X and Later

   11.3. Creating a Swap File on FreeBSD 9.X and Earlier

   12.1. boot0 Screenshot

   12.2. boot2 Screenshot

   12.3. Configuring an Insecure Console in /etc/ttys

   13.1. Create a Secure Tunnel for SMTP

   13.2. Secure Access of a POP3 Server

   13.3. Bypassing a Firewall

   14.1. mergemaster(8) on Untrusted Jail

   14.2. mergemaster(8) on Trusted Jail

   14.3. Running BIND in a Jail

   17.1. Using dump over ssh

   17.2. Using dump over ssh with RSH Set

   17.3. Backing Up the Current Directory with tar

   17.4. Restoring Up the Current Directory with tar

   17.5. Using ls and cpio to Make a Recursive Backup of the Current
   Directory

   17.6. Backing Up the Current Directory with pax

   18.1. Labeling Partitions on the Boot Disk

   23.1. Increasing the Number of Build Jobs

   26.1. Configuring Terminal Entries

   29.1. Reloading the inetd Configuration File

   29.2. Mounting an Export with amd

   29.3. Mounting an Export with autofs(5)

   29.4. Sample /etc/ntp.conf

   31.1. LACP Aggregation with a Cisco(R) Switch

   31.2. Failover Mode

   31.3. Failover Mode Between Ethernet and Wireless Interfaces

                                    Preface

Intended Audience

   The FreeBSD newcomer will find that the first section of this book guides
   the user through the FreeBSD 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 traveled this far, the second, far larger, section of the
   Handbook is a comprehensive reference to all manner of topics of interest
   to FreeBSD 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,
   Bibliography.

Changes from the Third Edition

   The current online version of the Handbook represents the cumulative
   effort of many hundreds of contributors over the past 10 years. The
   following are some of the significant changes since the two volume third
   edition was published in 2004:

     * Chapter 24, DTrace has been added with information about the powerful
       DTrace performance analysis tool.

     * Chapter 20, Other File Systems has been added with information about
       non-native file systems in FreeBSD, such as ZFS from Sun(TM).

     * Chapter 16, Security Event Auditing has been added to cover the new
       auditing capabilities in FreeBSD and explain its use.

     * Chapter 21, Virtualization has been added with information about
       installing FreeBSD on virtualization software.

     * Chapter 2, Installing FreeBSD has been added to cover installation of
       FreeBSD using the new installation utility, bsdinstall.

Changes from the Second Edition (2004)

   The third edition was the culmination of over two years of work by the
   dedicated members of the FreeBSD Documentation Project. The printed
   edition grew to such a size that it was necessary to publish as two
   separate volumes. The following are the major changes in this new edition:

     * Chapter 11, Configuration and Tuning has been expanded with new
       information about the ACPI power and resource management, the cron
       system utility, and more kernel tuning options.

     * Chapter 13, Security has been expanded with new information about
       virtual private networks (VPNs), file system access control lists
       (ACLs), and security advisories.

     * Chapter 15, Mandatory Access Control is a new chapter with this
       edition. It explains what MAC is and how this mechanism can be used to
       secure a FreeBSD system.

     * Chapter 17, Storage has been expanded with new information about USB
       storage devices, file system snapshots, file system quotas, file and
       network backed filesystems, and encrypted disk partitions.

     * A troubleshooting section has been added to Chapter 27, PPP.

     * Chapter 28, Electronic Mail has been expanded with new information
       about using alternative transport agents, SMTP authentication, UUCP,
       fetchmail, procmail, and other advanced topics.

     * Chapter 29, Network Servers is all new with this edition. This chapter
       includes information about setting up the Apache HTTP Server, ftpd,
       and setting up a server for Microsoft(R) Windows(R) clients with
       Samba. Some sections from Chapter 31, Advanced Networking were moved
       here to improve the presentation.

     * Chapter 31, Advanced Networking has been expanded with new information
       about using Bluetooth(R) devices with FreeBSD, setting up wireless
       networks, and Asynchronous Transfer Mode (ATM) networking.

     * A glossary has been added to provide a central location for the
       definitions of technical terms used throughout the book.

     * A number of aesthetic improvements have been made to the tables and
       figures throughout the book.

Changes from the First Edition (2001)

   The second edition was the culmination of over two years of work by the
   dedicated members of the FreeBSD Documentation Project. The following were
   the major changes in this edition:

     * A complete Index has been added.

     * All ASCII figures have been replaced by graphical diagrams.

     * A standard synopsis has been added to each chapter to give a quick
       summary of what information the chapter contains, and what the reader
       is expected to know.

     * The content has been logically reorganized into three parts: "Getting
       Started", "System Administration", and "Appendices".

     * Chapter 3, FreeBSD Basics has been expanded to contain additional
       information about processes, daemons, and signals.

     * Chapter 4, Installing Applications: Packages and Ports has been
       expanded to contain additional information about binary package
       management.

     * Chapter 5, The X Window System has been completely rewritten with an
       emphasis on using modern desktop technologies such as KDE and GNOME on
       XFree86(TM) 4.X.

     * Chapter 12, The FreeBSD Booting Process has been expanded.

     * Chapter 17, Storage has been written from what used to be two separate
       chapters on "Disks" and "Backups". We feel that the topics are easier
       to comprehend when presented as a single chapter. A section on RAID
       (both hardware and software) has also been added.

     * Chapter 26, Serial Communications has been completely reorganized and
       updated for FreeBSD 4.X/5.X.

     * Chapter 27, PPP has been substantially updated.

     * Many new sections have been added to Chapter 31, Advanced Networking.

     * Chapter 28, Electronic Mail has been expanded to include more
       information about configuring sendmail.

     * Chapter 10, Linux(R) Binary Compatibility has been expanded to include
       information about installing Oracle(R) and SAP(R) R/3(R).

     * The following new topics are covered in this second edition:

          * Chapter 11, Configuration and Tuning.

          * Chapter 7, Multimedia.

Organization of This Book

   This book is split into five logically distinct sections. The first
   section, Getting Started, covers the installation and basic usage of
   FreeBSD. It is expected that the reader will follow these chapters in
   sequence, possibly skipping chapters covering familiar topics. The second
   section, Common Tasks, covers some frequently used features of FreeBSD.
   This section, and all subsequent sections, can be read out of order. Each
   chapter 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, System Administration, covers administration topics. The
   fourth section, Network Communication, covers networking and server
   topics. The fifth section contains appendices of reference information.

   Chapter 1, Introduction

           Introduces FreeBSD to a new user. It describes the history of the
           FreeBSD Project, its goals and development model.

   Chapter 2, Installing FreeBSD

           Walks a user through the entire installation process of
           FreeBSD 9.x and later using bsdinstall.

   Chapter 3, FreeBSD Basics

           Covers the basic commands and functionality of the FreeBSD
           operating system. If you are familiar with Linux(R) or another
           flavor of UNIX(R) then you can probably skip this chapter.

   Chapter 4, Installing Applications: Packages and Ports

           Covers the installation of third-party software with both
           FreeBSD's innovative "Ports Collection" and standard binary
           packages.

   Chapter 5, The X Window System

           Describes the X Window System in general and using X11 on FreeBSD
           in particular. Also describes common desktop environments such as
           KDE and GNOME.

   Chapter 6, Desktop Applications

           Lists some common desktop applications, such as web browsers and
           productivity suites, and describes how to install them on FreeBSD.

   Chapter 7, Multimedia

           Shows how to set up sound and video playback support for your
           system. Also describes some sample audio and video applications.

   Chapter 8, Configuring the FreeBSD Kernel

           Explains why you might need to configure a new kernel and provides
           detailed instructions for configuring, building, and installing a
           custom kernel.

   Chapter 9, Printing

           Describes managing printers on FreeBSD, including information
           about banner pages, printer accounting, and initial setup.

   Chapter 10, Linux(R) Binary Compatibility

           Describes the Linux(R) compatibility features of FreeBSD. Also
           provides detailed installation instructions for many popular
           Linux(R) applications such as Oracle(R) and Mathematica(R).

   Chapter 11, Configuration and Tuning

           Describes the parameters available for system administrators to
           tune a FreeBSD system for optimum performance. Also describes the
           various configuration files used in FreeBSD and where to find
           them.

   Chapter 12, The FreeBSD Booting Process

           Describes the FreeBSD boot process and explains how to control
           this process with configuration options.

   Chapter 13, Security

           Describes many different tools available to help keep your FreeBSD
           system secure, including Kerberos, IPsec and OpenSSH.

   Chapter 14, Jails

           Describes the jails framework, and the improvements of jails over
           the traditional chroot support of FreeBSD.

   Chapter 15, Mandatory Access Control

           Explains what Mandatory Access Control (MAC) is and how this
           mechanism can be used to secure a FreeBSD system.

   Chapter 16, Security Event Auditing

           Describes what FreeBSD Event Auditing is, how it can be installed,
           configured, and how audit trails can be inspected or monitored.

   Chapter 17, Storage

           Describes how to manage storage media and filesystems with
           FreeBSD. This includes physical disks, RAID arrays, optical and
           tape media, memory-backed disks, and network filesystems.

   Chapter 18, GEOM: Modular Disk Transformation Framework

           Describes what the GEOM framework in FreeBSD is and how to
           configure various supported RAID levels.

   Chapter 20, Other File Systems

           Examines support of non-native file systems in FreeBSD, like the Z
           File System from Sun(TM).

   Chapter 21, Virtualization

           Describes what virtualization systems offer, and how they can be
           used with FreeBSD.

   Chapter 22, Localization - i18n/L10n Usage and Setup

           Describes how to use FreeBSD in languages other than English.
           Covers both system and application level localization.

   Chapter 23, Updating and Upgrading FreeBSD

           Explains the differences between FreeBSD-STABLE, FreeBSD-CURRENT,
           and FreeBSD releases. Describes which users would benefit from
           tracking a development system and outlines that process. Covers
           the methods users may take to update their system to the latest
           security release.

   Chapter 24, DTrace

           Describes how to configure and use the DTrace tool from Sun(TM) in
           FreeBSD. Dynamic tracing can help locate performance issues, by
           performing real time system analysis.

   Chapter 26, Serial Communications

           Explains how to connect terminals and modems to your FreeBSD
           system for both dial in and dial out connections.

   Chapter 27, PPP

           Describes how to use PPP to connect to remote systems with
           FreeBSD.

   Chapter 28, Electronic Mail

           Explains the different components of an email server and dives
           into simple configuration topics for the most popular mail server
           software: sendmail.

   Chapter 29, Network Servers

           Provides detailed instructions and example configuration files to
           set up your FreeBSD machine as a network filesystem server, domain
           name server, network information system server, or time
           synchronization server.

   Chapter 30, Firewalls

           Explains the philosophy behind software-based firewalls and
           provides detailed information about the configuration of the
           different firewalls available for FreeBSD.

   Chapter 31, Advanced Networking

           Describes many networking topics, including sharing an Internet
           connection with other computers on your LAN, advanced routing
           topics, wireless networking, Bluetooth(R), ATM, IPv6, and much
           more.

   Appendix A, Obtaining FreeBSD

           Lists different sources for obtaining FreeBSD media on CDROM or
           DVD as well as different sites on the Internet that allow you to
           download and install FreeBSD.

   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 FreeBSD users to post
           questions and engage in technical conversations about FreeBSD.

   Appendix D, OpenPGP Keys

           Lists the PGP fingerprints of several FreeBSD 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 C:\> 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:

   Examples starting with # indicate a command that must be invoked as the
   superuser in FreeBSD. 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

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.

   Several companies have supported the development of this document by
   paying authors to work on it full-time, paying for publication, etc. In
   particular, BSDi (subsequently acquired by Wind River Systems) paid
   members of the FreeBSD Documentation Project to work on improving this
   book full time leading up to the publication of the first printed edition
   in March 2000 (ISBN 1-57176-241-8). Wind River Systems then paid several
   additional authors to make a number of improvements to the print-output
   infrastructure and to add additional chapters to the text. This work
   culminated in the publication of the second printed edition in November
   2001 (ISBN 1-57176-303-1). In 2003-2004, FreeBSD Mall, Inc, paid several
   contributors to improve the Handbook in preparation for the third printed
   edition.

                            Part I. Getting Started

   This part of the handbook is for users and administrators who are new to
   FreeBSD. These chapters:

     * Introduce FreeBSD.

     * Guide readers through the installation process.

     * Teach UNIX(R) basics and fundamentals.

     * Show how to install the wealth of third party applications available
       for FreeBSD.

     * Introduce X, the UNIX(R) windowing system, and detail how to configure
       a desktop environment that makes users more productive.

   The number of forward references in the text have been kept to a minimum
   so that this section can be read from front to back with minimal page
   flipping.

   Table of Contents

   1. Introduction

                1.1. Synopsis

                1.2. Welcome to FreeBSD!

                1.3. About the FreeBSD Project

   2. Installing FreeBSD

                2.1. Synopsis

                2.2. Minimum Hardware Requirements

                2.3. Pre-Installation Tasks

                2.4. Starting the Installation

                2.5. Using bsdinstall

                2.6. Allocating Disk Space

                2.7. Committing to the Installation

                2.8. Post-Installation

                2.9. Troubleshooting

                2.10. Using the Live CD

   3. FreeBSD Basics

                3.1. Synopsis

                3.2. Virtual Consoles and Terminals

                3.3. Users and Basic Account Management

                3.4. Permissions

                3.5. Directory Structure

                3.6. Disk Organization

                3.7. Mounting and Unmounting File Systems

                3.8. Processes and Daemons

                3.9. Shells

                3.10. Text Editors

                3.11. Devices and Device Nodes

                3.12. Manual Pages

   4. Installing Applications: Packages and Ports

                4.1. Synopsis

                4.2. Overview of Software Installation

                4.3. Finding Software

                4.4. Using pkg for Binary Package Management

                4.5. Using the Ports Collection

                4.6. Building Packages with Poudriere

                4.7. Post-Installation Considerations

                4.8. Dealing with Broken Ports

   5. The X Window System

                5.1. Synopsis

                5.2. Terminology

                5.3. Installing Xorg

                5.4. Xorg Configuration

                5.5. Using Fonts in Xorg

                5.6. The X Display Manager

                5.7. Desktop Environments

                5.8. Installing Compiz Fusion

                5.9. Troubleshooting

Chapter 1. Introduction

   Restructured, reorganized, and parts rewritten by Jim Mock.
   Table of Contents

   1.1. Synopsis

   1.2. Welcome to FreeBSD!

   1.3. About the FreeBSD Project

1.1. Synopsis

   Thank you for your interest in FreeBSD! The following chapter covers
   various aspects of the FreeBSD Project, such as its history, goals,
   development model, and so on.

   After reading this chapter, you will know:

     * How FreeBSD relates to other computer operating systems.

     * The history of the FreeBSD Project.

     * The goals of the FreeBSD Project.

     * The basics of the FreeBSD open-source development model.

     * And of course: where the name "FreeBSD" comes from.

1.2. Welcome to FreeBSD!

   FreeBSD is an Open Source, standards-compliant Unix-like operating system
   for x86 (both 32 and 64 bit), ARM(R), AArch64, RISC-V(R), MIPS(R),
   POWER(R), PowerPC(R), and Sun UltraSPARC(R) computers. It provides all the
   features that are nowadays taken for granted, such as preemptive
   multitasking, memory protection, virtual memory, multi-user facilities,
   SMP support, all the Open Source development tools for different languages
   and frameworks, and desktop features centered around X Window System, KDE,
   or GNOME. Its particular strengths are:

     * Liberal Open Source license, which grants you rights to freely modify
       and extend its source code and incorporate it in both Open Source
       projects and closed products without imposing restrictions typical to
       copyleft licenses, as well as avoiding potential license
       incompatibility problems.

     * Strong TCP/IP networking - FreeBSD implements industry standard
       protocols with ever increasing performance and scalability. This makes
       it a good match in both server, and routing/firewalling roles - and
       indeed many companies and vendors use it precisely for that purpose.

     * Fully integrated OpenZFS support, including root-on-ZFS, ZFS Boot
       Environments, fault management, administrative delegation, support for
       jails, FreeBSD specific documentation, and system installer support.

     * Extensive security features, from the Mandatory Access Control
       framework to Capsicum capability and sandbox mechanisms.

     * Over 30 thousand prebuilt packages for all supported architectures,
       and the Ports Collection which makes it easy to build your own,
       customized ones.

     * Documentation - in addition to Handbook and books from different
       authors that cover topics ranging from system administration to kernel
       internals, there are also the man(1) pages, not only for userspace
       daemons, utilities, and configuration files, but also for kernel
       driver APIs (section 9) and individual drivers (section 4).

     * Simple and consistent repository structure and build system - FreeBSD
       uses a single repository for all of its components, both kernel and
       userspace. This, along with an unified and easy to customize build
       system and a well thought out development process makes it easy to
       integrate FreeBSD with build infrastructure for your own product.

     * Staying true to Unix philosophy, preferring composability instead of
       monolithic "all in one" daemons with hardcoded behavior.

     * Binary compatibility with Linux, which makes it possible to run many
       Linux binaries without the need for virtualisation.

   FreeBSD is based on the 4.4BSD-Lite release from Computer Systems Research
   Group (CSRG) at the University of California at Berkeley, and carries on
   the distinguished tradition of BSD systems development. In addition to the
   fine work provided by CSRG, the FreeBSD Project has put in many thousands
   of man-hours into extending the functionality and fine-tuning the system
   for maximum performance and reliability in real-life load situations.
   FreeBSD offers performance and reliability on par with other Open Source
   and commercial offerings, combined with cutting-edge features not
   available anywhere else.

  1.2.1. What Can FreeBSD Do?

   The applications to which FreeBSD 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(R) product then it is more than
   likely that you can do it with FreeBSD too! FreeBSD 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.

   Because the source code for FreeBSD 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
   FreeBSD:

     * Internet Services: The robust TCP/IP networking built into FreeBSD
       makes it an ideal platform for a variety of Internet services such as:

          * Web servers

          * IPv4 and IPv6 routing

          * Firewalls and NAT ("IP masquerading") gateways

          * FTP servers

          * Email servers

          * And more...

     * 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 FreeBSD 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, FreeBSD is
       an excellent platform for research in operating systems as well as
       other branches of computer science. FreeBSD'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? FreeBSD can easily turn that
       unused PC sitting in the corner into an advanced router with
       sophisticated packet-filtering capabilities.

     * Embedded: FreeBSD makes an excellent platform to build embedded
       systems upon. With support for the ARM(R), MIPS(R) and PowerPC(R)
       platforms, coupled with a robust network stack, cutting edge features
       and the permissive BSD license FreeBSD makes an excellent foundation
       for building embedded routers, firewalls, and other devices.

     * Desktop: FreeBSD makes a fine choice for an inexpensive desktop
       solution using the freely available X11 server. FreeBSD offers a
       choice from many open-source desktop environments, including the
       standard GNOME and KDE graphical user interfaces. FreeBSD can even
       boot "diskless" from a central server, making individual workstations
       even cheaper and easier to administer.

     * Software Development: The basic FreeBSD system comes with a full
       complement of development tools including a full C/C++ compiler and
       debugger suite. Support for many other languages are also available
       through the ports and packages collection.

   FreeBSD is available to download free of charge, or can be obtained on
   either CD-ROM or DVD. Please see Appendix A, Obtaining FreeBSD for more
   information about obtaining FreeBSD.

  1.2.2. Who Uses FreeBSD?

   FreeBSD has been known for its web serving capabilities - sites that run
   on FreeBSD include Hacker News, Netcraft, NetEase, Netflix, Sina, Sony
   Japan, Rambler, Yahoo!, and Yandex.

   FreeBSD's advanced features, proven security, predictable release cycle,
   and permissive license have led to its use as a platform for building many
   commercial and open source appliances, devices, and products. Many of the
   world's largest IT companies use FreeBSD:

     * Apache - The Apache Software Foundation runs most of its public facing
       infrastructure, including possibly one of the largest SVN repositories
       in the world with over 1.4 million commits, on FreeBSD.

     * Apple - OS X borrows heavily from FreeBSD for the network stack,
       virtual file system, and many userland components. Apple iOS also
       contains elements borrowed from FreeBSD.

     * Cisco - IronPort network security and anti-spam appliances run a
       modified FreeBSD kernel.

     * Citrix - The NetScaler line of security appliances provide layer 4-7
       load balancing, content caching, application firewall, secure VPN, and
       mobile cloud network access, along with the power of a FreeBSD shell.

     * Dell EMC Isilon - Isilon's enterprise storage appliances are based on
       FreeBSD. The extremely liberal FreeBSD license allowed Isilon to
       integrate their intellectual property throughout the kernel and focus
       on building their product instead of an operating system.

     * Quest KACE - The KACE system management appliances run FreeBSD because
       of its reliability, scalability, and the community that supports its
       continued development.

     * iXsystems - The TrueNAS line of unified storage appliances is based on
       FreeBSD. In addition to their commercial products, iXsystems also
       manages development of the open source projects TrueOS and FreeNAS.

     * Juniper - The JunOS operating system that powers all Juniper
       networking gear (including routers, switches, security, and networking
       appliances) is based on FreeBSD. Juniper is one of many vendors that
       showcases the symbiotic relationship between the project and vendors
       of commercial products. Improvements generated at Juniper are
       upstreamed into FreeBSD to reduce the complexity of integrating new
       features from FreeBSD back into JunOS in the future.

     * McAfee - SecurOS, the basis of McAfee enterprise firewall products
       including Sidewinder is based on FreeBSD.

     * NetApp - The Data ONTAP GX line of storage appliances are based on
       FreeBSD. In addition, NetApp has contributed back many features,
       including the new BSD licensed hypervisor, bhyve.

     * Netflix - The OpenConnect appliance that Netflix uses to stream movies
       to its customers is based on FreeBSD. Netflix has made extensive
       contributions to the codebase and works to maintain a zero delta from
       mainline FreeBSD. Netflix OpenConnect appliances are responsible for
       delivering more than 32% of all Internet traffic in North America.

     * Sandvine - Sandvine uses FreeBSD as the basis of their high
       performance real-time network processing platforms that make up their
       intelligent network policy control products.

     * Sony - The PlayStation 4 gaming console runs a modified version of
       FreeBSD.

     * Sophos - The Sophos Email Appliance product is based on a hardened
       FreeBSD and scans inbound mail for spam and viruses, while also
       monitoring outbound mail for malware as well as the accidental loss of
       sensitive information.

     * Spectra Logic - The nTier line of archive grade storage appliances run
       FreeBSD and OpenZFS.

     * Stormshield - Stormshield Network Security appliances are based on a
       hardened version of FreeBSD. The BSD license allows them to integrate
       their own intellectual property with the system while returning a
       great deal of interesting development to the community.

     * The Weather Channel - The IntelliStar appliance that is installed at
       each local cable provider's headend and is responsible for injecting
       local weather forecasts into the cable TV network's programming runs
       FreeBSD.

     * Verisign - Verisign is responsible for operating the .com and .net
       root domain registries as well as the accompanying DNS infrastructure.
       They rely on a number of different network operating systems including
       FreeBSD to ensure there is no common point of failure in their
       infrastructure.

     * Voxer - Voxer powers their mobile voice messaging platform with ZFS on
       FreeBSD. Voxer switched from a Solaris derivative to FreeBSD because
       of its superior documentation, larger and more active community, and
       more developer friendly environment. In addition to critical features
       like ZFS and DTrace, FreeBSD also offers TRIM support for ZFS.

     * WhatsApp - When WhatsApp needed a platform that would be able to
       handle more than 1 million concurrent TCP connections per server, they
       chose FreeBSD. They then proceeded to scale past 2.5 million
       connections per server.

     * Wheel Systems - The FUDO security appliance allows enterprises to
       monitor, control, record, and audit contractors and administrators who
       work on their systems. Based on all of the best security features of
       FreeBSD including ZFS, GELI, Capsicum, HAST, and auditdistd.

   FreeBSD has also spawned a number of related open source projects:

     * BSD Router - A FreeBSD based replacement for large enterprise routers
       designed to run on standard PC hardware.

     * FreeNAS - A customized FreeBSD designed to be used as a network file
       server appliance. Provides a python based web interface to simplify
       the management of both the UFS and ZFS file systems. Includes support
       for NFS, SMB/CIFS, AFP, FTP, and iSCSI. Includes an extensible plugin
       system based on FreeBSD jails.

     * GhostBSD - A desktop oriented distribution of FreeBSD bundled with the
       Gnome desktop environment.

     * mfsBSD - A toolkit for building a FreeBSD system image that runs
       entirely from memory.

     * NAS4Free - A file server distribution based on FreeBSD with a PHP
       powered web interface.

     * OPNSense - OPNsense is an open source, easy-to-use and easy-to-build
       FreeBSD based firewall and routing platform. OPNsense includes most of
       the features available in expensive commercial firewalls, and more in
       many cases. It brings the rich feature set of commercial offerings
       with the benefits of open and verifiable sources.

     * TrueOS - A customized version of FreeBSD geared towards desktop users
       with graphical utilities to exposing the power of FreeBSD to all
       users. Designed to ease the transition of Windows and OS X users.

     * pfSense - A firewall distribution based on FreeBSD with a huge array
       of features and extensive IPv6 support.

     * ZRouter - An open source alternative firmware for embedded devices
       based on FreeBSD. Designed to replace the proprietary firmware on
       off-the-shelf routers.

   A list of testimonials from companies basing their products and services
   on FreeBSD can be found at the FreeBSD Foundation website. Wikipedia also
   maintains a list of products based on FreeBSD.

1.3. About the FreeBSD 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 FreeBSD

   The FreeBSD Project had its genesis in the early part of 1993, partially
   as an outgrowth of the Unofficial 386BSDPatchkit by the patchkit's last 3
   coordinators: Nate Williams, Rod Grimes and Jordan Hubbard.

   The original goal was to produce an intermediate snapshot of 386BSD in
   order to fix a number of problems with it that the patchkit mechanism just
   was not capable of solving. The early working title for the project was
   386BSD 0.5 or 386BSD Interim in reference of that fact.

   386BSD was Bill Jolitz's operating system, which had been up to that point
   suffering rather severely from almost a year's worth of neglect. As the
   patchkit swelled ever more uncomfortably with each passing day, they
   decided to assist Bill by providing this interim "cleanup" snapshot. Those
   plans came to a rude halt when Bill Jolitz suddenly decided to withdraw
   his sanction from the project without any clear indication of what would
   be done instead.

   The trio thought that the goal remained worthwhile, even without Bill's
   support, and so they adopted the name "FreeBSD" coined by David Greenman.
   The initial objectives were set after consulting with the system's current
   users and, once it became clear that the project was on the road to
   perhaps even becoming a reality, Jordan contacted Walnut Creek CDROM with
   an eye toward improving FreeBSD's distribution channels for those many
   unfortunates without easy access to the Internet. Walnut Creek CDROM not
   only supported the idea of distributing FreeBSD on CD but also went so far
   as to provide the project with a machine to work on and a fast Internet
   connection. Without Walnut Creek CDROM's almost unprecedented degree of
   faith in what was, at the time, a completely unknown project, it is quite
   unlikely that FreeBSD would have gotten as far, as fast, as it has today.

   The first CD-ROM (and general net-wide) distribution was FreeBSD 1.0,
   released in December of 1993. This was based on the 4.3BSD-Lite ("Net/2")
   tape from U.C. Berkeley, with many components also provided by 386BSD and
   the Free Software Foundation. It was a fairly reasonable success for a
   first offering, and they followed it with the highly successful FreeBSD
   1.1 release in May of 1994.

   Around this time, some rather unexpected storm clouds formed on the
   horizon as Novell and U.C. Berkeley settled their long-running lawsuit
   over the legal status of the Berkeley Net/2 tape. A condition of that
   settlement was U.C. Berkeley's concession that large parts of Net/2 were
   "encumbered" code and the property of Novell, who had in turn acquired it
   from AT&T some time previously. What Berkeley got in return was Novell's
   "blessing" that the 4.4BSD-Lite release, when it was finally released,
   would be declared unencumbered and all existing Net/2 users would be
   strongly encouraged to switch. This included FreeBSD, and the project was
   given until the end of July 1994 to stop shipping its own Net/2 based
   product. Under the terms of that agreement, the project was allowed one
   last release before the deadline, that release being FreeBSD 1.1.5.1.

   FreeBSD then set about the arduous task of literally re-inventing itself
   from a completely new and rather incomplete set of 4.4BSD-Lite bits. The
   "Lite" releases were light in part because Berkeley's CSRG had removed
   large chunks of code required for actually constructing a bootable running
   system (due to various legal requirements) and the fact that the Intel
   port of 4.4 was highly incomplete. It took the project until November of
   1994 to make this transition, and in December it released FreeBSD 2.0 to
   the world. Despite being still more than a little rough around the edges,
   the release was a significant success and was followed by the more robust
   and easier to install FreeBSD 2.0.5 release in June of 1995.

   Since that time, FreeBSD has made a series of releases each time improving
   the stability, speed, and feature set of the previous version.

   For now, long-term development projects continue to take place in the
   10.X-CURRENT (trunk) branch, and snapshot releases of 10.X are continually
   made available from the snapshot server as work progresses.

  1.3.2. FreeBSD Project Goals

   Contributed by Jordan Hubbard.

   The goals of the FreeBSD Project are to provide software that may be used
   for any purpose and without strings attached. Many of us have a
   significant investment in the code (and project) and would certainly not
   mind a little financial compensation now and then, but we are definitely
   not prepared to insist on it. We believe that our first and foremost
   "mission" is to provide code to any and all comers, and for whatever
   purpose, so that the code gets the widest possible use and provides the
   widest possible benefit. This is, I believe, one of the most fundamental
   goals of Free Software and one that we enthusiastically support.

   That code in our source tree which falls under the GNU General Public
   License (GPL) or Library General Public License (LGPL) comes with slightly
   more strings attached, though at least on the side of enforced access
   rather than the usual opposite. Due to the additional complexities that
   can evolve in the commercial use of GPL software we do, however, prefer
   software submitted under the more relaxed BSD copyright when it is a
   reasonable option to do so.

  1.3.3. The FreeBSD Development Model

   Contributed by Satoshi Asami.

   The development of FreeBSD is a very open and flexible process, being
   literally built from the contributions of thousands of people around the
   world, as can be seen from our list of contributors. FreeBSD's development
   infrastructure allow these thousands of contributors to collaborate over
   the Internet. We are constantly on the lookout for new developers and
   ideas, and those interested in becoming more closely involved with the
   project need simply contact us at the FreeBSD technical discussions
   mailing list. The FreeBSD announcements mailing list is also available to
   those wishing to make other FreeBSD users aware of major areas of work.

   Useful things to know about the FreeBSD Project and its development
   process, whether working independently or in close cooperation:

   The SVN repositories

           For several years, the central source tree for FreeBSD was
           maintained by CVS (Concurrent Versions System), a freely available
           source code control tool. In June 2008, the Project switched to
           using SVN (Subversion). The switch was deemed necessary, as the
           technical limitations imposed by CVS were becoming obvious due to
           the rapid expansion of the source tree and the amount of history
           already stored. The Documentation Project and Ports Collection
           repositories also moved from CVS to SVN in May 2012 and July 2012,
           respectively. Please refer to the Synchronizing your source tree
           section for more information on obtaining the FreeBSD src/
           repository and Using the Ports Collection for details on obtaining
           the FreeBSD Ports Collection.

   The committers list

           The committers are the people who have write access to the
           Subversion tree, and are authorized to make modifications to the
           FreeBSD source (the term "committer" comes from commit, the source
           control command which is used to bring new changes into the
           repository). Anyone can submit a bug to the Bug Database. Before
           submitting a bug report, the FreeBSD mailing lists, IRC channels,
           or forums can be used to help verify that an issue is actually a
           bug.

   The FreeBSD core team

           The FreeBSD core team would be equivalent to the board of
           directors if the FreeBSD Project were a company. The primary task
           of the core team is to make sure the project, as a whole, is in
           good shape and is heading in the right directions. Inviting
           dedicated and responsible developers to join our group of
           committers is one of the functions of the core team, as is the
           recruitment of new core team members as others move on. The
           current core team was elected from a pool of committer candidates
           in July 2018. Elections are held every 2 years.

  Note:

           Like most developers, most members of the core team are also
           volunteers when it comes to FreeBSD development and do not benefit
           from the project financially, so "commitment" should also not be
           misconstrued as meaning "guaranteed support." The "board of
           directors" analogy above is not very accurate, and it may be more
           suitable to say that these are the people who gave up their lives
           in favor of FreeBSD against their better judgement!

   Outside contributors

           Last, but definitely not least, the largest group of developers
           are the users themselves who provide feedback and bug fixes to us
           on an almost constant basis. The primary way of keeping in touch
           with FreeBSD's more non-centralized development is to subscribe to
           the FreeBSD technical discussions mailing list where such things
           are discussed. See Appendix C, Resources on the Internet for more
           information about the various FreeBSD mailing lists.

           The FreeBSD Contributors List is a long and growing one, so why
           not join it by contributing something back to FreeBSD today?

           Providing code is not the only way of contributing to the project;
           for a more complete list of things that need doing, please refer
           to the FreeBSD Project web site.

   In summary, our development model is organized as a loose set of
   concentric circles. The centralized model is designed for the convenience
   of the users of FreeBSD, who are provided with an easy way of tracking one
   central code base, not to keep potential contributors out! Our desire is
   to present a stable operating system with a large set of coherent
   application programs that the users can easily install and use - this
   model works very well in accomplishing that.

   All we ask of those who would join us as FreeBSD developers is some of the
   same dedication its current people have to its continued success!

  1.3.4. Third Party Programs

   In addition to the base distributions, FreeBSD offers a ported software
   collection with thousands of commonly sought-after programs. At the time
   of this writing, there were over 24,000 ports! The list of ports ranges
   from http servers, to games, languages, editors, and almost everything in
   between. The entire Ports Collection requires approximately 500 MB. To
   compile a port, you simply change to the directory of the program you wish
   to install, type make install, and let the system do the rest. The full
   original distribution for each port you build is retrieved dynamically so
   you need only enough disk space to build the ports you want. Almost every
   port is also provided as a pre-compiled "package", which can be installed
   with a simple command (pkg install) by those who do not wish to compile
   their own ports from source. More information on packages and ports can be
   found in Chapter 4, Installing Applications: Packages and Ports.

  1.3.5. Additional Documentation

   All supported FreeBSD versions provide an option in the installer to
   install additional documentation under /usr/local/share/doc/freebsd during
   the initial system setup. Documentation may also be installed at any later
   time using packages as described in Section 23.3.2, "Updating
   Documentation from Ports". You may view the locally installed manuals with
   any HTML capable browser using the following URLs:

   The FreeBSD Handbook

           /usr/local/share/doc/freebsd/handbook/index.html

   The FreeBSD FAQ

           /usr/local/share/doc/freebsd/faq/index.html

   You can also view the master (and most frequently updated) copies at
   https://www.FreeBSD.org/.

Chapter 2. Installing FreeBSD

   Restructured, reorganized, and parts rewritten by Jim Mock.
   Updated for bsdinstall by Gavin Atkinson and Warren Block.
   Updated for root-on-ZFS by Allan Jude.
   Table of Contents

   2.1. Synopsis

   2.2. Minimum Hardware Requirements

   2.3. Pre-Installation Tasks

   2.4. Starting the Installation

   2.5. Using bsdinstall

   2.6. Allocating Disk Space

   2.7. Committing to the Installation

   2.8. Post-Installation

   2.9. Troubleshooting

   2.10. Using the Live CD

2.1. Synopsis

   There are several different ways of getting FreeBSD to run, depending on
   the environment. Those are:

     * Virtual Machine images, to download and import on a virtual
       environment of choice. These can be downloaded from the Download
       FreeBSD page. There are images for KVM ("qcow2"), VMWare ("vmdk"),
       Hyper-V ("vhd"), and raw device images that are universally supported.
       These are not installation images, but rather the preconfigured
       ("already installed") instances, ready to run and perform
       post-installation tasks.

     * Virtual Machine images available at Amazon's AWS Marketplace,
       Microsoft Azure Marketplace, and Google Cloud Platform, to run on
       their respective hosting services. For more information on deploying
       FreeBSD on Azure please consult the relevant chapter in the Azure
       Documentation.

     * SD card images, for embedded systems such as Raspberry Pi or
       BeagleBone Black. These can be downloaded from the Download FreeBSD
       page. These files must be uncompressed and written as a raw image to
       an SD card, from which the board will then boot.

     * Installation images, to install FreeBSD on a hard drive for the usual
       desktop, laptop, or server systems.

   The rest of this chapter describes the fourth case, explaining how to
   install FreeBSD using the text-based installation program named
   bsdinstall.

   In general, the installation instructions in this chapter are written for
   the i386(TM) and AMD64 architectures. Where applicable, instructions
   specific to other platforms will be listed. There may be minor differences
   between the installer and what is shown here, so use this chapter as a
   general guide rather than as a set of literal instructions.

  Note:

   Users who prefer to install FreeBSD using a graphical installer may be
   interested in pc-sysinstall, the installer used by the TrueOS Project. It
   can be used to install either a graphical desktop (TrueOS) or a command
   line version of FreeBSD. Refer to the TrueOS Users Handbook for details
   (https://www.trueos.org/handbook/trueos.html).

   After reading this chapter, you will know:

     * The minimum hardware requirements and FreeBSD supported architectures.

     * How to create the FreeBSD installation media.

     * How to start bsdinstall.

     * The questions bsdinstall will ask, what they mean, and how to answer
       them.

     * How to troubleshoot a failed installation.

     * How to access a live version of FreeBSD before committing to an
       installation.

   Before reading this chapter, you should:

     * Read the supported hardware list that shipped with the version of
       FreeBSD to be installed and verify that the system's hardware is
       supported.

2.2. Minimum Hardware Requirements

   The hardware requirements to install FreeBSD vary by architecture.
   Hardware architectures and devices supported by a FreeBSD release are
   listed on the FreeBSD Release Information page. The FreeBSD download page
   also has recommendations for choosing the correct image for different
   architectures.

   A FreeBSD installation requires a minimum of 96 MB of RAM and 1.5 GB of
   free hard drive space. However, such small amounts of memory and disk
   space are really only suitable for custom applications like embedded
   appliances. General-purpose desktop systems need more resources. 2-4 GB
   RAM and at least 8 GB hard drive space is a good starting point.

   These are the processor requirements for each architecture:

   amd64

           This is the most common desktop and laptop processor type, used in
           most modern systems. Intel(R) calls it Intel64. Other
           manufacturers sometimes call it x86-64.

           Examples of amd64 compatible processors include: AMD Athlon(TM)64,
           AMD Opteron(TM), multi-core Intel(R) Xeon(TM), and
           Intel(R) Core(TM) 2 and later processors.

   i386

           Older desktops and laptops often use this 32-bit, x86
           architecture.

           Almost all i386-compatible processors with a floating point unit
           are supported. All Intel(R) processors 486 or higher are
           supported.

           FreeBSD will take advantage of Physical Address Extensions (PAE)
           support on CPUs with this feature. A kernel with the PAE feature
           enabled will detect memory above 4 GB and allow it to be used by
           the system. However, using PAE places constraints on device
           drivers and other features of FreeBSD. Refer to pae(4) for
           details.

   ia64

           Currently supported processors are the Itanium(R) and the
           Itanium(R) 2. Supported chipsets include the HP zx1, Intel(R)
           460GX, and Intel(R) E8870. Both Uniprocessor (UP) and Symmetric
           Multi-processor (SMP) configurations are supported.

   powerpc

           All New World ROM Apple(R) Mac(R) systems with built-in USB are
           supported. SMP is supported on machines with multiple CPUs.

           A 32-bit kernel can only use the first 2 GB of RAM.

   sparc64

           Systems supported by FreeBSD/sparc64 are listed at the
           FreeBSD/sparc64 Project.

           SMP is supported on all systems with more than 1 processor. A
           dedicated disk is required as it is not possible to share a disk
           with another operating system at this time.

2.3. Pre-Installation Tasks

   Once it has been determined that the system meets the minimum hardware
   requirements for installing FreeBSD, the installation file should be
   downloaded and the installation media prepared. Before doing this, check
   that the system is ready for an installation by verifying the items in
   this checklist:

    1. Back Up Important Data

       Before installing any operating system, always backup all important
       data first. Do not store the backup on the system being installed.
       Instead, save the data to a removable disk such as a USB drive,
       another system on the network, or an online backup service. Test the
       backup before starting the installation to make sure it contains all
       of the needed files. Once the installer formats the system's disk, all
       data stored on that disk will be lost.

    2. Decide Where to Install FreeBSD

       If FreeBSD will be the only operating system installed, this step can
       be skipped. But if FreeBSD will share the disk with another operating
       system, decide which disk or partition will be used for FreeBSD.

       In the i386 and amd64 architectures, disks can be divided into
       multiple partitions using one of two partitioning schemes. A
       traditional Master Boot Record (MBR) holds a partition table defining
       up to four primary partitions. For historical reasons, FreeBSD calls
       these primary partition slices. One of these primary partitions can be
       made into an extended partition containing multiple logical
       partitions. The GUID Partition Table (GPT) is a newer and simpler
       method of partitioning a disk. Common GPT implementations allow up to
       128 partitions per disk, eliminating the need for logical partitions.

  Warning:

       Some older operating systems, like Windows(R) XP, are not compatible
       with the GPT partition scheme. If FreeBSD will be sharing a disk with
       such an operating system, MBR partitioning is required.

       The FreeBSD boot loader requires either a primary or GPT partition. If
       all of the primary or GPT partitions are already in use, one must be
       freed for FreeBSD. To create a partition without deleting existing
       data, use a partition resizing tool to shrink an existing partition
       and create a new partition using the freed space.

       A variety of free and commercial partition resizing tools are listed
       at http://en.wikipedia.org/wiki/List_of_disk_partitioning_software.
       GParted Live (http://gparted.sourceforge.net/livecd.php) is a free
       live CD which includes the GParted partition editor. GParted is also
       included with many other Linux live CD distributions.

  Warning:

       When used properly, disk shrinking utilities can safely create space
       for creating a new partition. Since the possibility of selecting the
       wrong partition exists, always backup any important data and verify
       the integrity of the backup before modifying disk partitions.

       Disk partitions containing different operating systems make it
       possible to install multiple operating systems on one computer. An
       alternative is to use virtualization (Chapter 21, Virtualization)
       which allows multiple operating systems to run at the same time
       without modifying any disk partitions.

    3. Collect Network Information

       Some FreeBSD installation methods require a network connection in
       order to download the installation files. After any installation, the
       installer will offer to setup the system's network interfaces.

       If the network has a DHCP server, it can be used to provide automatic
       network configuration. If DHCP is not available, the following network
       information for the system must be obtained from the local network
       administrator or Internet service provider:

       Required Network Information
         1. IP address

         2. Subnet mask

         3. IP address of default gateway

         4. Domain name of the network

         5. IP addresses of the network's DNS servers

    4. Check for FreeBSD Errata

       Although the FreeBSD Project strives to ensure that each release of
       FreeBSD is as stable as possible, bugs occasionally creep into the
       process. On very rare occasions those bugs affect the installation
       process. As these problems are discovered and fixed, they are noted in
       the FreeBSD Errata
       (https://www.freebsd.org/releases/12.0R/errata.html) on the FreeBSD
       web site. Check the errata before installing to make sure that there
       are no problems that might affect the installation.

       Information and errata for all the releases can be found on the
       release information section of the FreeBSD web site
       (https://www.freebsd.org/releases/index.html).

  2.3.1. Prepare the Installation Media

   The FreeBSD installer is not an application that can be run from within
   another operating system. Instead, download a FreeBSD installation file,
   burn it to the media associated with its file type and size (CD, DVD, or
   USB), and boot the system to install from the inserted media.

   FreeBSD installation files are available at
   www.freebsd.org/where.html#download. Each installation file's name
   includes the release version of FreeBSD, the architecture, and the type of
   file. For example, to install FreeBSD 10.2 on an amd64 system from a DVD,
   download FreeBSD-10.2-RELEASE-amd64-dvd1.iso, burn this file to a DVD, and
   boot the system with the DVD inserted.

   Installation files are available in several formats. The formats vary
   depending on computer architecture and media type.

   Additional installation files are included for computers that boot with
   UEFI (Unified Extensible Firmware Interface). The names of these files
   include the string uefi.

   File types:

     * -bootonly.iso: This is the smallest installation file as it only
       contains the installer. A working Internet connection is required
       during installation as the installer will download the files it needs
       to complete the FreeBSD installation. This file should be burned to a
       CD using a CD burning application.

     * -disc1.iso: This file contains all of the files needed to install
       FreeBSD, its source, and the Ports Collection. It should be burned to
       a CD using a CD burning application.

     * -dvd1.iso: This file contains all of the files needed to install
       FreeBSD, its source, and the Ports Collection. It also contains a set
       of popular binary packages for installing a window manager and some
       applications so that a complete system can be installed from media
       without requiring a connection to the Internet. This file should be
       burned to a DVD using a DVD burning application.

     * -memstick.img: This file contains all of the files needed to install
       FreeBSD, its source, and the Ports Collection. It should be burned to
       a USB stick using the instructions below.

     * -mini-memstick.img: Like -bootonly.iso, does not include installation
       files, but downloads them as needed. A working internet connection is
       required during installation. Write this file to a USB stick as shown
       in Section 2.3.1.1, "Writing an Image File to USB".

   After downloading the image file, download CHECKSUM.SHA256 from the same
   directory. Calculate a checksum for the image file. FreeBSD provides
   sha256(1) for this, used as sha256 imagefilename. Other operating systems
   have similar programs.

   Compare the calculated checksum with the one shown in CHECKSUM.SHA256. The
   checksums must match exactly. If the checksums do not match, the image
   file is corrupt and must be downloaded again.

    2.3.1.1. Writing an Image File to USB

   The *.img file is an image of the complete contents of a memory stick. It
   cannot be copied to the target device as a file. Several applications are
   available for writing the *.img to a USB stick. This section describes two
   of these utilities.

  Important:

   Before proceeding, back up any important data on the USB stick. This
   procedure will erase the existing data on the stick.

   Procedure 2.1. Using dd to Write the Image

  Warning:

   This example uses /dev/da0 as the target device where the image will be
   written. Be very careful that the correct device is used as this command
   will destroy the existing data on the specified target device.

     * The dd(1) command-line utility is available on BSD, Linux(R), and
       Mac OS(R) systems. To burn the image using dd, insert the USB stick
       and determine its device name. Then, specify the name of the
       downloaded installation file and the device name for the USB stick.
       This example burns the amd64 installation image to the first USB
       device on an existing FreeBSD system.

 # dd if=FreeBSD-10.2-RELEASE-amd64-memstick.img of=/dev/da0 bs=1M conv=sync

       If this command fails, verify that the USB stick is not mounted and
       that the device name is for the disk, not a partition. Some operating
       systems might require this command to be run with sudo(8). The dd(1)
       syntax varies slightly across different platforms; for example,
       Mac OS(R) requires a lower-case bs=1m. Systems like Linux(R) might
       buffer writes. To force all writes to complete, use sync(8).

   Procedure 2.2. Using Windows(R) to Write the Image

  Warning:

   Be sure to give the correct drive letter as the existing data on the
   specified drive will be overwritten and destroyed.

    1. Obtaining Image Writer for Windows(R)

       Image Writer for Windows(R) is a free application that can correctly
       write an image file to a memory stick. Download it from
       https://sourceforge.net/projects/win32diskimager/ and extract it into
       a folder.

    2. Writing the Image with Image Writer

       Double-click the Win32DiskImager icon to start the program. Verify
       that the drive letter shown under Device is the drive with the memory
       stick. Click the folder icon and select the image to be written to the
       memory stick. Click [ Save ] to accept the image file name. Verify
       that everything is correct, and that no folders on the memory stick
       are open in other windows. When everything is ready, click [ Write ]
       to write the image file to the memory stick.

   You are now ready to start installing FreeBSD.

2.4. Starting the Installation

  Important:

   By default, the installation will not make any changes to the disk(s)
   before the following message:

 Your changes will now be written to disk.  If you
 have chosen to overwrite existing data, it will
 be PERMANENTLY ERASED. Are you sure you want to
 commit your changes?

   The install can be exited at any time prior to this warning. If there is a
   concern that something is incorrectly configured, just turn the computer
   off before this point and no changes will be made to the system's disks.

   This section describes how to boot the system from the installation media
   which was prepared using the instructions in Section 2.3.1, "Prepare the
   Installation Media". When using a bootable USB stick, plug in the USB
   stick before turning on the computer. When booting from CD or DVD, turn on
   the computer and insert the media at the first opportunity. How to
   configure the system to boot from the inserted media depends upon the
   architecture.

  2.4.1. Booting on i386(TM) and amd64

   These architectures provide a BIOS menu for selecting the boot device.
   Depending upon the installation media being used, select the CD/DVD or USB
   device as the first boot device. Most systems also provide a key for
   selecting the boot device during startup without having to enter the BIOS.
   Typically, the key is either F10, F11, F12, or Escape.

   If the computer loads the existing operating system instead of the FreeBSD
   installer, then either:

    1. The installation media was not inserted early enough in the boot
       process. Leave the media inserted and try restarting the computer.

    2. The BIOS changes were incorrect or not saved. Double-check that the
       right boot device is selected as the first boot device.

    3. This system is too old to support booting from the chosen media. In
       this case, the Plop Boot Manager
       (http://www.plop.at/en/bootmanagers.html) can be used to boot the
       system from the selected media.

  2.4.2. Booting on PowerPC(R)

   On most machines, holding C on the keyboard during boot will boot from the
   CD. Otherwise, hold Command+Option+O+F, or Windows+Alt+O+F on non-Apple(R)
   keyboards. At the 0 > prompt, enter

 boot cd:,\ppc\loader cd:0

  2.4.3. Booting on SPARC64(R)

   Most SPARC64(R) systems are set up to boot automatically from disk. To
   install FreeBSD from a CD requires a break into the PROM.

   To do this, reboot the system and wait until the boot message appears. The
   message depends on the model, but should look something like this:

 Sun Blade 100 (UltraSPARC-IIe), Keyboard Present
 Copyright 1998-2001 Sun Microsystems, Inc.  All rights reserved.
 OpenBoot 4.2, 128 MB memory installed, Serial #51090132.
 Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.

   If the system proceeds to boot from disk at this point, press L1+A or
   Stop+A on the keyboard, or send a BREAK over the serial console. When
   using tip or cu, ~# will issue a BREAK. The PROM prompt will be ok on
   systems with one CPU and ok {0} on SMP systems, where the digit indicates
   the number of the active CPU.

   At this point, place the CD into the drive and type boot cdrom from the
   PROM prompt.

  2.4.4. FreeBSD Boot Menu

   Once the system boots from the installation media, a menu similar to the
   following will be displayed:

   Figure 2.1. FreeBSD Boot Loader Menu
   FreeBSD Boot Loader Menu

   By default, the menu will wait ten seconds for user input before booting
   into the FreeBSD installer or, if FreeBSD is already installed, before
   booting into FreeBSD. To pause the boot timer in order to review the
   selections, press Space. To select an option, press its highlighted
   number, character, or key. The following options are available.

     * Boot Multi User: This will continue the FreeBSD boot process. If the
       boot timer has been paused, press 1, upper- or lower-case B, or Enter.

     * Boot Single User: This mode can be used to fix an existing FreeBSD
       installation as described in Section 12.2.4.1, "Single-User Mode".
       Press 2 or the upper- or lower-case S to enter this mode.

     * Escape to loader prompt: This will boot the system into a repair
       prompt that contains a limited number of low-level commands. This
       prompt is described in Section 12.2.3, "Stage Three". Press 3 or Esc
       to boot into this prompt.

     * Reboot: Reboots the system.

     * Configure Boot Options: Opens the menu shown in, and described under,
       Figure 2.2, "FreeBSD Boot Options Menu".

   Figure 2.2. FreeBSD Boot Options Menu
   FreeBSD Boot Options Menu

   The boot options menu is divided into two sections. The first section can
   be used to either return to the main boot menu or to reset any toggled
   options back to their defaults.

   The next section is used to toggle the available options to On or Off by
   pressing the option's highlighted number or character. The system will
   always boot using the settings for these options until they are modified.
   Several options can be toggled using this menu:

     * ACPI Support: If the system hangs during boot, try toggling this
       option to Off.

     * Safe Mode: If the system still hangs during boot even with ACPI
       Support set to Off, try setting this option to On.

     * Single User: Toggle this option to On to fix an existing FreeBSD
       installation as described in Section 12.2.4.1, "Single-User Mode".
       Once the problem is fixed, set it back to Off.

     * Verbose: Toggle this option to On to see more detailed messages during
       the boot process. This can be useful when troubleshooting a piece of
       hardware.

   After making the needed selections, press 1 or Backspace to return to the
   main boot menu, then press Enter to continue booting into FreeBSD. A
   series of boot messages will appear as FreeBSD carries out its hardware
   device probes and loads the installation program. Once the boot is
   complete, the welcome menu shown in Figure 2.3, "Welcome Menu" will be
   displayed.

   Figure 2.3. Welcome Menu
   Welcome Menu

   Press Enter to select the default of [ Install ] to enter the installer.
   The rest of this chapter describes how to use this installer. Otherwise,
   use the right or left arrows or the colorized letter to select the desired
   menu item. The [ Shell ] can be used to access a FreeBSD shell in order to
   use command line utilities to prepare the disks before installation. The
   [ Live CD ] option can be used to try out FreeBSD before installing it.
   The live version is described in Section 2.10, "Using the Live CD".

  Tip:

   To review the boot messages, including the hardware device probe, press
   the upper- or lower-case S and then Enter to access a shell. At the shell
   prompt, type more /var/run/dmesg.boot and use the space bar to scroll
   through the messages. When finished, type exit to return to the welcome
   menu.

2.5. Using bsdinstall

   This section shows the order of the bsdinstall menus and the type of
   information that will be asked before the system is installed. Use the
   arrow keys to highlight a menu option, then Space to select or deselect
   that menu item. When finished, press Enter to save the selection and move
   onto the next screen.

  2.5.1. Selecting the Keymap Menu

   Depending on the system console being used, bsdinstall may initially
   display the menu shown in Figure 2.4, "Keymap Selection".

   Figure 2.4. Keymap Selection
   Keymap Selection

   To configure the keyboard layout, press Enter with [ YES ] selected, which
   will display the menu shown in Figure 2.5, "Selecting Keyboard Menu". To
   instead use the default layout, use the arrow key to select [ NO ] and
   press Enter to skip this menu screen.

   Figure 2.5. Selecting Keyboard Menu
   Selecting Keyboard Menu

   When configuring the keyboard layout, use the up and down arrows to select
   the keymap that most closely represents the mapping of the keyboard
   attached to the system. Press Enter to save the selection.

  Note:

   Pressing Esc will exit this menu and use the default keymap. If the choice
   of keymap is not clear, United States of America ISO-8859-1 is also a safe
   option.

   In FreeBSD 10.0-RELEASE and later, this menu has been enhanced. The full
   selection of keymaps is shown, with the default preselected. In addition,
   when selecting a different keymap, a dialog is displayed that allows the
   user to try the keymap and ensure it is correct before proceeding.

   Figure 2.6. Enhanced Keymap Menu
   Enhanced Keymap Menu

  2.5.2. Setting the Hostname

   The next bsdinstall menu is used to set the hostname for the newly
   installed system.

   Figure 2.7. Setting the Hostname
   Setting the Hostname

   Type in a hostname that is unique for the network. It should be a
   fully-qualified hostname, such as machine3.example.com.

  2.5.3. Selecting Components to Install

   Next, bsdinstall will prompt to select optional components to install.

   Figure 2.8. Selecting Components to Install
   Selecting Components to Install

   Deciding which components to install will depend largely on the intended
   use of the system and the amount of disk space available. The FreeBSD
   kernel and userland, collectively known as the base system, are always
   installed. Depending on the architecture, some of these components may not
   appear:

     * doc - Additional documentation, mostly of historical interest, to
       install into /usr/share/doc. The documentation provided by the FreeBSD
       Documentation Project may be installed later using the instructions in
       Section 23.3, "Updating the Documentation Set".

     * games - Several traditional BSD games, including fortune, rot13, and
       others.

     * lib32 - Compatibility libraries for running 32-bit applications on a
       64-bit version of FreeBSD.

     * ports - The FreeBSD Ports Collection is a collection of files which
       automates the downloading, compiling and installation of third-party
       software packages. Chapter 4, Installing Applications: Packages and
       Ports discusses how to use the Ports Collection.

  Warning:

       The installation program does not check for adequate disk space.
       Select this option only if sufficient hard disk space is available.
       The FreeBSD Ports Collection takes up about 500 MB of disk space.

     * src - The complete FreeBSD source code for both the kernel and the
       userland. Although not required for the majority of applications, it
       may be required to build device drivers, kernel modules, or some
       applications from the Ports Collection. It is also used for developing
       FreeBSD itself. The full source tree requires 1 GB of disk space and
       recompiling the entire FreeBSD system requires an additional 5 GB of
       space.

  2.5.4. Installing from the Network

   The menu shown in Figure 2.9, "Installing from the Network" only appears
   when installing from a -bootonly.iso CD as this installation media does
   not hold copies of the installation files. Since the installation files
   must be retrieved over a network connection, this menu indicates that the
   network interface must be first configured.

   Figure 2.9. Installing from the Network
   Installing from the Network

   To configure the network connection, press Enter and follow the
   instructions in Section 2.8.2, "Configuring Network Interfaces". Once the
   interface is configured, select a mirror site that is located in the same
   region of the world as the computer on which FreeBSD is being installed.
   Files can be retrieved more quickly when the mirror is close to the target
   computer, reducing installation time.

   Figure 2.10. Choosing a Mirror
   Choosing a Mirror

   Installation will then continue as if the installation files were located
   on the local installation media.

2.6. Allocating Disk Space

   The next menu is used to determine the method for allocating disk space.

   Figure 2.11. Partitioning Choices on FreeBSD 10.x and Higher
   Partitioning Choices on FreeBSD 10.x and Higher

   Guided partitioning automatically sets up the disk partitions, Manual
   partitioning allows advanced users to create customized partitions from
   menu options, and Shell opens a shell prompt where advanced users can
   create customized partitions using command-line utilities like gpart(8),
   fdisk(8), and bsdlabel(8). ZFS partitioning, only available in FreeBSD 10
   and later, creates an optionally encrypted root-on-ZFS system with support
   for boot environments.

   This section describes what to consider when laying out the disk
   partitions. It then demonstrates how to use the different partitioning
   methods.

  2.6.1. Designing the Partition Layout

   When laying out file systems, 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
   parts of the disk. It is a good idea to create partitions in an order
   similar to: /, swap, /var, and /usr.

   The size of the /var partition reflects the intended machine's usage. This
   partition is used to hold mailboxes, log files, and printer spools.
   Mailboxes and log files can grow to unexpected sizes depending on the
   number of users and how long log files are kept. On average, most users
   rarely need more than about a gigabyte of free disk space in /var.

  Note:

   Sometimes, a lot of disk space is required in /var/tmp. When new software
   is installed, the packaging tools extract a temporary copy of the packages
   under /var/tmp. Large software packages, like Firefox, Apache OpenOffice
   or LibreOffice may be tricky to install if there is not enough disk space
   under /var/tmp.

   The /usr partition holds many of the files which support the system,
   including the FreeBSD Ports Collection and system source code. At least 2
   gigabytes of space is 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.

   As a rule of thumb, the swap partition should be about double the size of
   physical memory (RAM). Systems with minimal RAM may perform better with
   more swap. 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 recommended that swap be 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.

   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.
   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.

  2.6.2. Guided Partitioning

   When this method is selected, a menu will display the available disk(s).
   If multiple disks are connected, choose the one where FreeBSD is to be
   installed.

   Figure 2.12. Selecting from Multiple Disks
   Selecting from Multiple Disks

   Once the disk is selected, the next menu prompts to install to either the
   entire disk or to create a partition using free space. If [ Entire Disk ]
   is chosen, a general partition layout filling the whole disk is
   automatically created. Selecting [ Partition ] creates a partition layout
   from the unused space on the disk.

   Figure 2.13. Selecting Entire Disk or Partition
   Selecting Entire Disk or Partition

   After the partition layout has been created, review it to ensure it meets
   the needs of the installation. Selecting [ Revert ] will reset the
   partitions to their original values and pressing [ Auto ] will recreate
   the automatic FreeBSD partitions. Partitions can also be manually created,
   modified, or deleted. When the partitioning is correct, select [ Finish ]
   to continue with the installation.

   Figure 2.14. Review Created Partitions
   Review Created Partitions

  2.6.3. Manual Partitioning

   Selecting this method opens the partition editor:

   Figure 2.15. Manually Create Partitions
   Manually Create Partitions

   Highlight the installation drive (ada0 in this example) and select
   [ Create ] to display a menu of available partition schemes:

   Figure 2.16. Manually Create Partitions
   Manually Create Partitions

   GPT is usually the most appropriate choice for amd64 computers. Older
   computers that are not compatible with GPT should use MBR. The other
   partition schemes are generally used for uncommon or older computers.

   Table 2.1. Partitioning Schemes

   Abbreviation Description                                                   
   APM          Apple Partition Map, used by PowerPC(R).                      
                BSD label without an MBR, sometimes called dangerously        
   BSD          dedicated mode as non-BSD disk utilities may not recognize    
                it.                                                           
   GPT          GUID Partition Table                                          
                (http://en.wikipedia.org/wiki/GUID_Partition_Table).          
   MBR          Master Boot Record                                            
                (http://en.wikipedia.org/wiki/Master_boot_record).            
   PC98         MBR variant used by NEC PC-98 computers                       
                (http://en.wikipedia.org/wiki/Pc9801).                        
   VTOC8        Volume Table Of Contents used by Sun SPARC64 and UltraSPARC   
                computers.                                                    

   After the partitioning scheme has been selected and created, select
   [ Create ] again to create the partitions. The Tab key is used to move the
   cursor between fields.

   Figure 2.17. Manually Create Partitions
   Manually Create Partitions

   A standard FreeBSD GPT installation uses at least three partitions:

     * freebsd-boot - Holds the FreeBSD boot code.

     * freebsd-ufs - A FreeBSD UFS file system.

     * freebsd-swap - FreeBSD swap space.

   Another partition type worth noting is freebsd-zfs, used for partitions
   that will contain a FreeBSD ZFS file system (Chapter 19, The Z File System
   (ZFS)). Refer to gpart(8) for descriptions of the available GPT partition
   types.

   Multiple file system partitions can be created and some people prefer a
   traditional layout with separate partitions for /, /var, /tmp, and /usr.
   See Example 2.1, "Creating Traditional Split File System Partitions" for
   an example.

   The Size may be entered with common abbreviations: K for kilobytes, M for
   megabytes, or G for gigabytes.

  Tip:

   Proper sector alignment provides the best performance, and making
   partition sizes even multiples of 4K bytes helps to ensure alignment on
   drives with either 512-byte or 4K-byte sectors. Generally, using partition
   sizes that are even multiples of 1M or 1G is the easiest way to make sure
   every partition starts at an even multiple of 4K. There is one exception:
   the freebsd-boot partition should be no larger than 512K due to current
   boot code limitations.

   A Mountpoint is needed if the partition will contain a file system. If
   only a single UFS partition will be created, the mountpoint should be /.

   The Label is a name by which the partition will be known. Drive names or
   numbers can change if the drive is connected to a different controller or
   port, but the partition label does not change. Referring to labels instead
   of drive names and partition numbers in files like /etc/fstab makes the
   system more tolerant to hardware changes. GPT labels appear in /dev/gpt/
   when a disk is attached. Other partitioning schemes have different label
   capabilities and their labels appear in different directories in /dev/.

  Tip:

   Use a unique label on every partition to avoid conflicts from identical
   labels. A few letters from the computer's name, use, or location can be
   added to the label. For instance, use labroot or rootfslab for the UFS
   root partition on the computer named lab.

   Example 2.1. Creating Traditional Split File System Partitions

   For a traditional partition layout where the /, /var, /tmp, and /usr
   directories are separate file systems on their own partitions, create a
   GPT partitioning scheme, then create the partitions as shown. Partition
   sizes shown are typical for a 20G target disk. If more space is available
   on the target disk, larger swap or /var partitions may be useful. Labels
   shown here are prefixed with ex for "example", but readers should use
   other unique label values as described above.

   By default, FreeBSD's gptboot expects the first UFS partition to be the /
   partition.

   Partition Type                  Size                   Mountpoint  Label   
   freebsd-boot   512K                                                        
   freebsd-ufs    2G                                      /          exrootfs 
   freebsd-swap   4G                                                 exswap   
   freebsd-ufs    2G                                      /var       exvarfs  
   freebsd-ufs    1G                                      /tmp       extmpfs  
   freebsd-ufs    accept the default (remainder of the    /usr       exusrfs  
                  disk)                                   

   After the custom partitions have been created, select [ Finish ] to
   continue with the installation.

  2.6.4. Root-on-ZFS Automatic Partitioning

   Support for automatic creation of root-on-ZFS installations was added in
   FreeBSD 10.0-RELEASE. This partitioning mode only works with whole disks
   and will erase the contents of the entire disk. The installer will
   automatically create partitions aligned to 4k boundaries and force ZFS to
   use 4k sectors. This is safe even with 512 byte sector disks, and has the
   added benefit of ensuring that pools created on 512 byte disks will be
   able to have 4k sector disks added in the future, either as additional
   storage space or as replacements for failed disks. The installer can also
   optionally employ GELI disk encryption as described in Section 17.12.2,
   "Disk Encryption with geli". If encryption is enabled, a 2 GB unencrypted
   boot pool containing the /boot directory is created. It holds the kernel
   and other files necessary to boot the system. A swap partition of a user
   selectable size is also created, and all remaining space is used for the
   ZFS pool.

   The main ZFS configuration menu offers a number of options to control the
   creation of the pool.

   Figure 2.18. ZFS Partitioning Menu
   ZFS Partitioning Menu

   Select T to configure the Pool Type and the disk(s) that will constitute
   the pool. The automatic ZFS installer currently only supports the creation
   of a single top level vdev, except in stripe mode. To create more complex
   pools, use the instructions in Section 2.6.5, "Shell Mode Partitioning" to
   create the pool. The installer supports the creation of various pool
   types, including stripe (not recommended, no redundancy), mirror (best
   performance, least usable space), and RAID-Z 1, 2, and 3 (with the
   capability to withstand the concurrent failure of 1, 2, and 3 disks,
   respectively). While selecting the pool type, a tooltip is displayed
   across the bottom of the screen with advice about the number of required
   disks, and in the case of RAID-Z, the optimal number of disks for each
   configuration.

   Figure 2.19. ZFS Pool Type
   ZFS Pool Type

   Once a Pool Type has been selected, a list of available disks is
   displayed, and the user is prompted to select one or more disks to make up
   the pool. The configuration is then validated, to ensure enough disks are
   selected. If not, select  to return to the list of
   disks, or  to change the pool type.

   Figure 2.20. Disk Selection
   Disk Selection
   Figure 2.21. Invalid Selection
   Invalid Selection

   If one or more disks are missing from the list, or if disks were attached
   after the installer was started, select - Rescan Devices to repopulate the
   list of available disks. To avoid accidentally erasing the wrong disk, the
   - Disk Info menu can be used to inspect each disk, including its partition
   table and various other information such as the device model number and
   serial number, if available.

   Figure 2.22. Analyzing a Disk
   Analyzing a Disk

   The main ZFS configuration menu also allows the user to enter a pool name,
   disable forcing 4k sectors, enable or disable encryption, switch between
   GPT (recommended) and MBR partition table types, and select the amount of
   swap space. Once all options have been set to the desired values, select
   the >>> Install option at the top of the menu.

   If GELI disk encryption was enabled, the installer will prompt twice for
   the passphrase to be used to encrypt the disks.

   Figure 2.23. Disk Encryption Password
   Disk Encryption Password

   The installer then offers a last chance to cancel before the contents of
   the selected drives are destroyed to create the ZFS pool.

   Figure 2.24. Last Chance
   Last Chance

   The installation then proceeds normally.

  2.6.5. Shell Mode Partitioning

   When creating advanced installations, the bsdinstall partitioning menus
   may not provide the level of flexibility required. Advanced users can
   select the Shell option from the partitioning menu in order to manually
   partition the drives, create the file system(s), populate
   /tmp/bsdinstall_etc/fstab, and mount the file systems under /mnt. Once
   this is done, type exit to return to bsdinstall and continue the
   installation.

2.7. Committing to the Installation

   Once the disks are configured, the next menu provides the last chance to
   make changes before the selected hard drive(s) are formatted. If changes
   need to be made, select [ Back ] to return to the main partitioning menu.
   [ Revert & Exit ] will exit the installer without making any changes to
   the hard drive.

   Figure 2.25. Final Confirmation
   Final Confirmation

   To instead start the actual installation, select [ Commit ] and press
   Enter.

   Installation time will vary depending on the distributions chosen,
   installation media, and speed of the computer. A series of messages will
   indicate the progress.

   First, the installer formats the selected disk(s) and initializes the
   partitions. Next, in the case of a bootonly media, it downloads the
   selected components:

   Figure 2.26. Fetching Distribution Files
   Fetching Distribution Files

   Next, the integrity of the distribution files is verified to ensure they
   have not been corrupted during download or misread from the installation
   media:

   Figure 2.27. Verifying Distribution Files
   Verifying Distribution Files

   Finally, the verified distribution files are extracted to the disk:

   Figure 2.28. Extracting Distribution Files
   Extracting Distribution Files

   Once all requested distribution files have been extracted, bsdinstall
   displays the first post-installation configuration screen. The available
   post-configuration options are described in the next section.

2.8. Post-Installation

   Once FreeBSD is installed, bsdinstall will prompt to configure several
   options before booting into the newly installed system. This section
   describes these configuration options.

  Tip:

   Once the system has booted, bsdconfig provides a menu-driven method for
   configuring the system using these and additional options.

  2.8.1. Setting the root Password

   First, the root password must be set. While entering the password, the
   characters being typed are not displayed on the screen. After the password
   has been entered, it must be entered again. This helps prevent typing
   errors.

   Figure 2.29. Setting the root Password
   Setting the root Password

  2.8.2. Configuring Network Interfaces

   Next, a list of the network interfaces found on the computer is shown.
   Select the interface to configure.

  Note:

   The network configuration menus will be skipped if the network was
   previously configured as part of a bootonly installation.

   Figure 2.30. Choose a Network Interface
   Choose a Network Interface

   If an Ethernet interface is selected, the installer will skip ahead to the
   menu shown in Figure 2.34, "Choose IPv4 Networking". If a wireless network
   interface is chosen, the system will instead scan for wireless access
   points:

   Figure 2.31. Scanning for Wireless Access Points
   Scanning for Wireless Access Points

   Wireless networks are identified by a Service Set Identifier (SSID), a
   short, unique name given to each network. SSIDs found during the scan are
   listed, followed by a description of the encryption types available for
   that network. If the desired SSID does not appear in the list, select
   [ Rescan ] to scan again. If the desired network still does not appear,
   check for problems with antenna connections or try moving the computer
   closer to the access point. Rescan after each change is made.

   Figure 2.32. Choosing a Wireless Network
   Choosing a Wireless Network

   Next, enter the encryption information for connecting to the selected
   wireless network. WPA2 encryption is strongly recommended as older
   encryption types, like WEP, offer little security. If the network uses
   WPA2, input the password, also known as the Pre-Shared Key (PSK). For
   security reasons, the characters typed into the input box are displayed as
   asterisks.

   Figure 2.33. WPA2 Setup
   WPA2 Setup

   Next, choose whether or not an IPv4 address should be configured on the
   Ethernet or wireless interface:

   Figure 2.34. Choose IPv4 Networking
   Choose IPv4 Networking

   There are two methods of IPv4 configuration. DHCP will automatically
   configure the network interface correctly and should be used if the
   network provides a DHCP server. Otherwise, the addressing information
   needs to be input manually as a static configuration.

  Note:

   Do not enter random network information as it will not work. If a DHCP
   server is not available, obtain the information listed in Required Network
   Information from the network administrator or Internet service provider.

   If a DHCP server is available, select [ Yes ] in the next menu to
   automatically configure the network interface. The installer will appear
   to pause for a minute or so as it finds the DHCP server and obtains the
   addressing information for the system.

   Figure 2.35. Choose IPv4 DHCP Configuration
   Choose IPv4 DHCP Configuration

   If a DHCP server is not available, select [ No ] and input the following
   addressing information in this menu:

   Figure 2.36. IPv4 Static Configuration
   IPv4 Static Configuration
     * IP Address - The IPv4 address assigned to this computer. The address
       must be unique and not already in use by another piece of equipment on
       the local network.

     * Subnet Mask - The subnet mask for the network.

     * Default Router - The IP address of the network's default gateway.

   The next screen will ask if the interface should be configured for IPv6.
   If IPv6 is available and desired, choose [ Yes ] to select it.

   Figure 2.37. Choose IPv6 Networking
   Choose IPv6 Networking

   IPv6 also has two methods of configuration. StateLess Address
   AutoConfiguration (SLAAC) will automatically request the correct
   configuration information from a local router. Refer to
   http://tools.ietf.org/html/rfc4862 for more information. Static
   configuration requires manual entry of network information.

   If an IPv6 router is available, select [ Yes ] in the next menu to
   automatically configure the network interface. The installer will appear
   to pause for a minute or so as it finds the router and obtains the
   addressing information for the system.

   Figure 2.38. Choose IPv6 SLAAC Configuration
   Choose IPv6 SLAAC Configuration

   If an IPv6 router is not available, select [ No ] and input the following
   addressing information in this menu:

   Figure 2.39. IPv6 Static Configuration
   IPv6 Static Configuration
     * IPv6 Address - The IPv6 address assigned to this computer. The address
       must be unique and not already in use by another piece of equipment on
       the local network.

     * Default Router - The IPv6 address of the network's default gateway.

   The last network configuration menu is used to configure the Domain Name
   System (DNS) resolver, which converts hostnames to and from network
   addresses. If DHCP or SLAAC was used to autoconfigure the network
   interface, the Resolver Configuration values may already be filled in.
   Otherwise, enter the local network's domain name in the Search field. DNS
   #1 and DNS #2 are the IPv4 and/or IPv6 addresses of the DNS servers. At
   least one DNS server is required.

   Figure 2.40. DNS Configuration
   DNS Configuration

  2.8.3. Setting the Time Zone

   The next menu asks if the system clock uses UTC or local time. When in
   doubt, select [ No ] to choose the more commonly-used local time.

   Figure 2.41. Select Local or UTC Clock
   Select Local or UTC Clock

   The next series of menus are used to determine the correct local time by
   selecting the geographic region, country, and time zone. Setting the time
   zone allows the system to automatically correct for regional time changes,
   such as daylight savings time, and perform other time zone related
   functions properly.

   The example shown here is for a machine located in the Eastern time zone
   of the United States. The selections will vary according to the
   geographical location.

   Figure 2.42. Select a Region
   Select a Region

   The appropriate region is selected using the arrow keys and then pressing
   Enter.

   Figure 2.43. Select a Country
   Select a Country

   Select the appropriate country using the arrow keys and press Enter.

   Figure 2.44. Select a Time Zone
   Select a Time Zone

   The appropriate time zone is selected using the arrow keys and pressing
   Enter.

   Figure 2.45. Confirm Time Zone
   Confirm Time Zone

   Confirm the abbreviation for the time zone is correct. If it is, press
   Enter to continue with the post-installation configuration.

  2.8.4. Enabling Services

   The next menu is used to configure which system services will be started
   whenever the system boots. All of these services are optional. Only start
   the services that are needed for the system to function.

   Figure 2.46. Selecting Additional Services to Enable
   Selecting Additional Services to Enable

   Here is a summary of the services which can be enabled in this menu:

     * sshd - The Secure Shell (SSH) daemon is used to remotely access a
       system over an encrypted connection. Only enable this service if the
       system should be available for remote logins.

     * moused - Enable this service if the mouse will be used from the
       command-line system console.

     * ntpd - The Network Time Protocol (NTP) daemon for automatic clock
       synchronization. Enable this service if there is a Windows(R),
       Kerberos, or LDAP server on the network.

     * powerd - System power control utility for power control and energy
       saving.

  2.8.5. Enabling Crash Dumps

   The next menu is used to configure whether or not crash dumps should be
   enabled. Enabling crash dumps can be useful in debugging issues with the
   system, so users are encouraged to enable crash dumps.

   Figure 2.47. Enabling Crash Dumps
   Enabling Crash Dumps

  2.8.6. Add Users

   The next menu prompts to create at least one user account. It is
   recommended to login to the system using a user account rather than as
   root. When logged in as root, there are essentially no limits or
   protection on what can be done. Logging in as a normal user is safer and
   more secure.

   Select [ Yes ] to add new users.

   Figure 2.48. Add User Accounts
   Add User Accounts

   Follow the prompts and input the requested information for the user
   account. The example shown in Figure 2.49, "Enter User Information"
   creates the asample user account.

   Figure 2.49. Enter User Information
   Enter User Information

   Here is a summary of the information to input:

     * Username - The name the user will enter to log in. A common convention
       is to use the first letter of the first name combined with the last
       name, as long as each username is unique for the system. The username
       is case sensitive and should not contain any spaces.

     * Full name - The user's full name. This can contain spaces and is used
       as a description for the user account.

     * Uid - User ID. Typically, this is left blank so the system will assign
       a value.

     * Login group - The user's group. Typically this is left blank to accept
       the default.

     * Invite user into other groups? - Additional groups to which the user
       will be added as a member. If the user needs administrative access,
       type wheel here.

     * Login class - Typically left blank for the default.

     * Shell - Type in one of the listed values to set the interactive shell
       for the user. Refer to Section 3.9, "Shells" for more information
       about shells.

     * Home directory - The user's home directory. The default is usually
       correct.

     * Home directory permissions - Permissions on the user's home directory.
       The default is usually correct.

     * Use password-based authentication? - Typically yes so that the user is
       prompted to input their password at login.

     * Use an empty password? - Typically no as it is insecure to have a
       blank password.

     * Use a random password? - Typically no so that the user can set their
       own password in the next prompt.

     * Enter password - The password for this user. Characters typed will not
       show on the screen.

     * Enter password again - The password must be typed again for
       verification.

     * Lock out the account after creation? - Typically no so that the user
       can login.

   After entering everything, a summary is shown for review. If a mistake was
   made, enter no and try again. If everything is correct, enter yes to
   create the new user.

   Figure 2.50. Exit User and Group Management
   Exit User and Group Management

   If there are more users to add, answer the Add another user? question with
   yes. Enter no to finish adding users and continue the installation.

   For more information on adding users and user management, see Section 3.3,
   "Users and Basic Account Management".

  2.8.7. Final Configuration

   After everything has been installed and configured, a final chance is
   provided to modify settings.

   Figure 2.51. Final Configuration
   Final Configuration

   Use this menu to make any changes or do any additional configuration
   before completing the installation.

     * Add User - Described in Section 2.8.6, "Add Users".

     * Root Password - Described in Section 2.8.1, "Setting the root
       Password".

     * Hostname - Described in Section 2.5.2, "Setting the Hostname".

     * Network - Described in Section 2.8.2, "Configuring Network
       Interfaces".

     * Services - Described in Section 2.8.4, "Enabling Services".

     * Time Zone - Described in Section 2.8.3, "Setting the Time Zone".

     * Handbook - Download and install the FreeBSD Handbook.

   After any final configuration is complete, select Exit.

   Figure 2.52. Manual Configuration
   Manual Configuration

   bsdinstall will prompt if there are any additional configuration that
   needs to be done before rebooting into the new system. Select [ Yes ] to
   exit to a shell within the new system or [ No ] to proceed to the last
   step of the installation.

   Figure 2.53. Complete the Installation
   Complete the Installation

   If further configuration or special setup is needed, select [ Live CD ] to
   boot the install media into Live CD mode.

   If the installation is complete, select [ Reboot ] to reboot the computer
   and start the new FreeBSD system. Do not forget to remove the FreeBSD
   install media or the computer may boot from it again.

   As FreeBSD boots, informational messages are displayed. After the system
   finishes booting, a login prompt is displayed. At the login: prompt, enter
   the username added during the installation. Avoid logging in as root.
   Refer to Section 3.3.1.3, "The Superuser Account" for instructions on how
   to become the superuser when administrative access is needed.

   The messages that appeared during boot can be reviewed by pressing
   Scroll-Lock to turn on the scroll-back buffer. The PgUp, PgDn, and arrow
   keys can be used to scroll back through the messages. When finished, press
   Scroll-Lock again to unlock the display and return to the console. To
   review these messages once the system has been up for some time, type less
   /var/run/dmesg.boot from a command prompt. Press q to return to the
   command line after viewing.

   If sshd was enabled in Figure 2.46, "Selecting Additional Services to
   Enable", the first boot may be a bit slower as the system will generate
   the RSA and DSA keys. Subsequent boots will be faster. The fingerprints of
   the keys will be displayed, as seen in this example:

 Generating public/private rsa1 key pair.
 Your identification has been saved in /etc/ssh/ssh_host_key.
 Your public key has been saved in /etc/ssh/ssh_host_key.pub.
 The key fingerprint is:
 10:a0:f5:af:93:ae:a3:1a:b2:bb:3c:35:d9:5a:b3:f3 root@machine3.example.com
 The key's randomart image is:
 +--[RSA1 1024]----+
 |    o..          |
 |   o . .         |
 |  .   o          |
 |       o         |
 |    o   S        |
 |   + + o         |
 |o . + *          |
 |o+ ..+ .         |
 |==o..o+E         |
 +-----------------+
 Generating public/private dsa key pair.
 Your identification has been saved in /etc/ssh/ssh_host_dsa_key.
 Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub.
 The key fingerprint is:
 7e:1c:ce:dc:8a:3a:18:13:5b:34:b5:cf:d9:d1:47:b2 root@machine3.example.com
 The key's randomart image is:
 +--[ DSA 1024]----+
 |       ..     . .|
 |      o  .   . + |
 |     . ..   . E .|
 |    . .  o o . . |
 |     +  S = .    |
 |    +  . = o     |
 |     +  . * .    |
 |    . .  o .     |
 |      .o. .      |
 +-----------------+
 Starting sshd.

   Refer to Section 13.8, "OpenSSH" for more information about fingerprints
   and SSH.

   FreeBSD does not install a graphical environment by default. Refer to
   Chapter 5, The X Window System for more information about installing and
   configuring a graphical window manager.

   Proper shutdown of a FreeBSD computer helps protect data and hardware from
   damage. Do not turn off the power before the system has been properly shut
   down! If the user is a member of the wheel group, become the superuser by
   typing su at the command line and entering the root password. Then, type
   shutdown -p now and the system will shut down cleanly, and if the hardware
   supports it, turn itself off.

2.9. Troubleshooting

   This section covers basic installation troubleshooting, such as common
   problems people have reported.

   Check the Hardware Notes (https://www.freebsd.org/releases/index.html)
   document for the version of FreeBSD to make sure the hardware is
   supported. If the hardware is supported and lock-ups or other problems
   occur, build a custom kernel using the instructions in Chapter 8,
   Configuring the FreeBSD Kernel to add support for devices which are not
   present in the GENERIC kernel. The default kernel assumes that most
   hardware devices are in their factory default configuration in terms of
   IRQs, I/O addresses, and DMA channels. If the hardware has been
   reconfigured, a custom kernel configuration file can tell FreeBSD where to
   find things.

  Note:

   Some installation problems can be avoided or alleviated by updating the
   firmware on various hardware components, most notably the motherboard.
   Motherboard firmware is usually referred to as the BIOS. Most motherboard
   and computer manufacturers have a website for upgrades and upgrade
   information.

   Manufacturers generally advise against upgrading the motherboard BIOS
   unless there is a good reason for doing so, like a critical update. The
   upgrade process can go wrong, leaving the BIOS incomplete and the computer
   inoperative.

   If the system hangs while probing hardware during boot, or it behaves
   strangely during install, ACPI may be the culprit. FreeBSD makes extensive
   use of the system ACPI service on the i386, amd64, and ia64 platforms to
   aid in system configuration if it is detected during boot. Unfortunately,
   some bugs still exist in both the ACPI driver and within system
   motherboards and BIOS firmware. ACPI can be disabled by setting the
   hint.acpi.0.disabled hint in the third stage boot loader:

 set hint.acpi.0.disabled="1"

   This is reset each time the system is booted, so it is necessary to add
   hint.acpi.0.disabled="1" to the file /boot/loader.conf. More information
   about the boot loader can be found in Section 12.1, "Synopsis".

2.10. Using the Live CD

   The welcome menu of bsdinstall, shown in Figure 2.3, "Welcome Menu",
   provides a [ Live CD ] option. This is useful for those who are still
   wondering whether FreeBSD is the right operating system for them and want
   to test some of the features before installing.

   The following points should be noted before using the [ Live CD ]:

     * To gain access to the system, authentication is required. The username
       is root and the password is blank.

     * As the system runs directly from the installation media, performance
       will be significantly slower than that of a system installed on a hard
       disk.

     * This option only provides a command prompt and not a graphical
       interface.

Chapter 3. FreeBSD Basics

   Table of Contents

   3.1. Synopsis

   3.2. Virtual Consoles and Terminals

   3.3. Users and Basic Account Management

   3.4. Permissions

   3.5. Directory Structure

   3.6. Disk Organization

   3.7. Mounting and Unmounting File Systems

   3.8. Processes and Daemons

   3.9. Shells

   3.10. Text Editors

   3.11. Devices and Device Nodes

   3.12. Manual Pages

3.1. Synopsis

   This chapter covers the basic commands and functionality of the FreeBSD
   operating system. Much of this material is relevant for any UNIX(R)-like
   operating system. New FreeBSD users are encouraged to read through this
   chapter carefully.

   After reading this chapter, you will know:

     * How to use and configure virtual consoles.

     * How to create and manage users and groups on FreeBSD.

     * How UNIX(R) file permissions and FreeBSD file flags work.

     * The default FreeBSD file system layout.

     * The FreeBSD disk organization.

     * How to mount and unmount file systems.

     * What processes, daemons, and signals are.

     * What a shell is, and how to change the default login environment.

     * How to use basic text editors.

     * What devices and device nodes are.

     * How to read manual pages for more information.

3.2. Virtual Consoles and Terminals

   Unless FreeBSD has been configured to automatically start a graphical
   environment during startup, the system will boot into a command line login
   prompt, as seen in this example:

 FreeBSD/amd64 (pc3.example.org) (ttyv0)

 login:

   The first line contains some information about the system. The amd64
   indicates that the system in this example is running a 64-bit version of
   FreeBSD. The hostname is pc3.example.org, and ttyv0 indicates that this is
   the "system console". The second line is the login prompt.

   Since FreeBSD is a multiuser system, it needs some way to distinguish
   between different users. This is accomplished by requiring every user to
   log into the system before gaining access to the programs on the system.
   Every user has a unique name "username" and a personal "password".

   To log into the system console, type the username that was configured
   during system installation, as described in Section 2.8.6, "Add Users",
   and press Enter. Then enter the password associated with the username and
   press Enter. The password is not echoed for security reasons.

   Once the correct password is input, the message of the day (MOTD) will be
   displayed followed by a command prompt. Depending upon the shell that was
   selected when the user was created, this prompt will be a #, $, or %
   character. The prompt indicates that the user is now logged into the
   FreeBSD system console and ready to try the available commands.

  3.2.1. Virtual Consoles

   While the system console can be used to interact with the system, a user
   working from the command line at the keyboard of a FreeBSD system will
   typically instead log into a virtual console. This is because system
   messages are configured by default to display on the system console. These
   messages will appear over the command or file that the user is working on,
   making it difficult to concentrate on the work at hand.

   By default, FreeBSD is configured to provide several virtual consoles for
   inputting commands. Each virtual console has its own login prompt and
   shell and it is easy to switch between virtual consoles. This essentially
   provides the command line equivalent of having several windows open at the
   same time in a graphical environment.

   The key combinations Alt+F1 through Alt+F8 have been reserved by FreeBSD
   for switching between virtual consoles. Use Alt+F1 to switch to the system
   console (ttyv0), Alt+F2 to access the first virtual console (ttyv1),
   Alt+F3 to access the second virtual console (ttyv2), and so on. When using
   Xorg as a graphical console, the combination becomes Ctrl+Alt+F1 to return
   to a text-based virtual console.

   When switching from one console to the next, FreeBSD manages the screen
   output. The result is an illusion of having multiple virtual screens and
   keyboards that can be used to type commands for FreeBSD to run. The
   programs that are launched in one virtual console do not stop running when
   the user switches to a different virtual console.

   Refer to kbdcontrol(1), vidcontrol(1), atkbd(4), syscons(4), and vt(4) for
   a more technical description of the FreeBSD console and its keyboard
   drivers.

   In FreeBSD, the number of available virtual consoles is configured in this
   section of /etc/ttys:

 # name    getty                         type  status comments
 #
 ttyv0   "/usr/libexec/getty Pc"         xterm   on  secure
 # Virtual terminals
 ttyv1   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv2   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv3   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv4   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv5   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv6   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv7   "/usr/libexec/getty Pc"         xterm   on  secure
 ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure

   To disable a virtual console, put a comment symbol (#) at the beginning of
   the line representing that virtual console. For example, to reduce the
   number of available virtual consoles from eight to four, put a # in front
   of the last four lines representing virtual consoles ttyv5 through ttyv8.
   Do not comment out the line for the system console ttyv0. Note that the
   last virtual console (ttyv8) is used to access the graphical environment
   if Xorg has been installed and configured as described in Chapter 5, The X
   Window System.

   For a detailed description of every column in this file and the available
   options for the virtual consoles, refer to ttys(5).

  3.2.2. Single User Mode

   The FreeBSD boot menu provides an option labelled as "Boot Single User".
   If this option is selected, the system will boot into a special mode known
   as "single user mode". This mode is typically used to repair a system that
   will not boot or to reset the root password when it is not known. While in
   single user mode, networking and other virtual consoles are not available.
   However, full root access to the system is available, and by default, the
   root password is not needed. For these reasons, physical access to the
   keyboard is needed to boot into this mode and determining who has physical
   access to the keyboard is something to consider when securing a FreeBSD
   system.

   The settings which control single user mode are found in this section of
   /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  secure

   By default, the status is set to secure. This assumes that who has
   physical access to the keyboard is either not important or it is
   controlled by a physical security policy. If this setting is changed to
   insecure, the assumption is that the environment itself is insecure
   because anyone can access the keyboard. When this line is changed to
   insecure, FreeBSD will prompt for the root password when a user selects to
   boot into single user mode.

  Note:

   Be careful when changing this setting to insecure! If the root password is
   forgotten, booting into single user mode is still possible, but may be
   difficult for someone who is not familiar with the FreeBSD booting
   process.

  3.2.3. Changing Console Video Modes

   The FreeBSD console default video mode may be adjusted to 1024x768,
   1280x1024, or any other size supported by the graphics chip and monitor.
   To use a different video mode load the VESA module:

 # kldload vesa

   To determine which video modes are supported by the hardware, use
   vidcontrol(1). To get a list of supported video modes issue the following:

 # vidcontrol -i mode

   The output of this command lists the video modes that are supported by the
   hardware. To select a new video mode, specify the mode using vidcontrol(1)
   as the root user:

 # vidcontrol MODE_279

   If the new video mode is acceptable, it can be permanently set on boot by
   adding it to /etc/rc.conf:

 allscreens_flags="MODE_279"

3.3. Users and Basic Account Management

   FreeBSD allows multiple users to use the computer at the same time. While
   only one user can sit in front of the screen and use the keyboard at any
   one time, any number of users can log in to the system through the
   network. To use the system, each user should have their own user account.

   This chapter describes:

     * The different types of user accounts on a FreeBSD system.

     * How to add, remove, and modify user accounts.

     * How to set limits to control the resources that users and groups are
       allowed to access.

     * How to create groups and add users as members of a group.

  3.3.1. Account Types

   Since all access to the FreeBSD system is achieved using accounts and all
   processes are run by users, user and account management is important.

   There are three main types of accounts: system accounts, user accounts,
   and the superuser account.

    3.3.1.1. System Accounts

   System accounts are used to run services such as DNS, mail, and web
   servers. The reason for this is security; if all services ran as the
   superuser, they could act without restriction.

   Examples of system accounts are daemon, operator, bind, news, and www.

   nobody is the generic unprivileged system account. However, 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.

    3.3.1.2. User Accounts

   User accounts are assigned to real people and are used to log in and use
   the system. Every person accessing the system should have a unique user
   account. This allows the administrator to find out who is doing what and
   prevents users from clobbering the settings of other users.

   Each user can set up their own environment to accommodate their use of the
   system, by configuring their default shell, editor, key bindings, and
   language settings.

   Every user account on a FreeBSD system has certain information associated
   with it:

   User name

           The user name is typed at the login: prompt. Each user must have a
           unique user name. There are a number of rules for creating valid
           user names which are documented in passwd(5). It is recommended to
           use user names that consist of eight or fewer, all lower case
           characters in order to maintain backwards compatibility with
           applications.

   Password

           Each account has an associated password.

   User ID (UID)

           The User ID (UID) is a number used to uniquely identify the user
           to the FreeBSD system. Commands that allow a user name to be
           specified will first convert it to the UID. It is recommended to
           use a UID less than 65535, since higher values may cause
           compatibility issues with some software.

   Group ID (GID)

           The Group ID (GID) is a number 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 and allows users to be members of more than
           one group. It is recommended to use a GID of 65535 or lower as
           higher GIDs may break some software.

   Login class

           Login classes are an extension to the group mechanism that provide
           additional flexibility when tailoring the system to different
           users. Login classes are discussed further in Section 13.13.1,
           "Configuring Login Classes".

   Password change time

           By default, passwords do not expire. However, password expiration
           can be enabled on a per-user basis, forcing some or all users to
           change their passwords after a certain amount of time has elapsed.

   Account expiration time

           By default, FreeBSD does not expire accounts. When creating
           accounts that need a limited lifespan, such as student accounts in
           a school, specify the account expiry date using pw(8). 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 FreeBSD, but does
           not necessarily reflect the user's real name. Similar to a
           comment, this information can contain spaces, uppercase
           characters, and be more than 8 characters long.

   Home directory

           The home directory is the full path to a directory on the system.
           This is the user's starting directory when the user logs in. A
           common convention is to put all user home directories under
           /home/username or /usr/home/username. Each user stores their
           personal files and subdirectories in their own home directory.

   User shell

           The shell provides the user's default environment for interacting
           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.

    3.3.1.3. The Superuser Account

   The superuser account, usually called root, is used to manage the system
   with no limitations on privileges. For this reason, it should not be used
   for day-to-day tasks like sending and receiving mail, general exploration
   of the system, or programming.

   The superuser, unlike other user accounts, can operate without limits, and
   misuse of the superuser account may result in spectacular disasters. User
   accounts are unable to destroy the operating system by mistake, so it is
   recommended to login as a user account and to only become the superuser
   when a command requires extra privilege.

   Always double and triple-check any commands issued as the superuser, since
   an extra space or missing character can mean irreparable data loss.

   There are several ways to gain superuser privilege. While one can log in
   as root, this is highly discouraged.

   Instead, use su(1) to become the superuser. If - is specified when running
   this command, the user will also inherit the root user's environment. The
   user running this command must be in the wheel group or else the command
   will fail. The user must also know the password for the root user account.

   In this example, the user only becomes superuser in order to run make
   install as this step requires superuser privilege. Once the command
   completes, the user types exit to leave the superuser account and return
   to the privilege of their user account.

   Example 3.1. Install a Program As the Superuser

 % configure
 % make
 % su -
 Password:
 # make install
 # exit
 %

   The built-in su(1) framework works well for single systems or small
   networks with just one system administrator. An alternative is to install
   the security/sudo package or port. This software provides activity logging
   and allows the administrator to configure which users can run which
   commands as the superuser.

  3.3.2. Managing Accounts

   FreeBSD provides a variety of different commands to manage user accounts.
   The most common commands are summarized in Table 3.1, "Utilities for
   Managing User Accounts", followed by some examples of their usage. See the
   manual page for each utility for more details and usage examples.

   Table 3.1. Utilities for Managing User Accounts

    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 for changing user database information.         
   passwd(1)  The command-line tool to change user passwords.                 
   pw(8)      A powerful and flexible tool for modifying all aspects of user  
              accounts.                                                       

    3.3.2.1. adduser

   The recommended program for adding new users is adduser(8). When a new
   user is added, this program automatically updates /etc/passwd and
   /etc/group. It also creates a home directory for the new user, copies in
   the default configuration files from /usr/share/skel, and can optionally
   mail the new user a welcome message. This utility must be run as the
   superuser.

   The adduser(8) utility is interactive and walks through the steps for
   creating a new user account. As seen in Example 3.2, "Adding a User on
   FreeBSD", either input the required information or press Return to accept
   the default value shown in square brackets. In this example, the user has
   been invited into the wheel group, allowing them to become the superuser
   with su(1). When finished, the utility will prompt to either create
   another user or to exit.

   Example 3.2. Adding a User on FreeBSD

 # adduser
 Username: jru
 Full name: J. Random User
 Uid (Leave empty for default):
 Login group [jru]:
 Login group is jru. Invite jru into other groups? []: wheel
 Login class [default]:
 Shell (sh csh tcsh zsh nologin) [sh]: zsh
 Home directory [/home/jru]:
 Home directory permissions (Leave empty for default):
 Use password-based authentication? [yes]:
 Use an empty password? (yes/no) [no]:
 Use a random password? (yes/no) [no]:
 Enter password:
 Enter password again:
 Lock out the account after creation? [no]:
 Username   : jru
 Password   : ****
 Full Name  : J. Random User
 Uid        : 1001
 Class      :
 Groups     : jru wheel
 Home       : /home/jru
 Shell      : /usr/local/bin/zsh
 Locked     : no
 OK? (yes/no): yes
 adduser: INFO: Successfully added (jru) to the user database.
 Add another user? (yes/no): no
 Goodbye!
 #

  Note:

   Since the password is not echoed when typed, be careful to not mistype the
   password when creating the user account.

    3.3.2.2. rmuser

   To completely remove a user from the system, run rmuser(8) as the
   superuser. This command performs the following steps:

    1. Removes the user's crontab(1) entry, if one exists.

    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. Optionally 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. 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, as shown in the following
   example.

   Example 3.3. 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
 Removing user (jru): mailspool home passwd.
 #

    3.3.2.3. chpass

   Any user can use chpass(1) to change their default shell and personal
   information associated with their user account. The superuser can use this
   utility to change additional account information for any user.

   When passed no options, aside from an optional username, chpass(1)
   displays an editor containing user information. When the user exits from
   the editor, the user database is updated with the new information.

  Note:

   This utility will prompt for the user's password when exiting the editor,
   unless the utility is run as the superuser.

   In Example 3.4, "Using chpass as Superuser", the superuser has typed
   chpass jru and is now viewing the fields that can be changed for this
   user. If jru runs this command instead, only the last six fields will be
   displayed and available for editing. This is shown in Example 3.5, "Using
   chpass as Regular User".

   Example 3.4. Using chpass as 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:

   Example 3.5. Using chpass as Regular 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:

   The commands chfn(1) and chsh(1) are links to chpass(1), as are
   ypchpass(1), ypchfn(1), and ypchsh(1). Since NIS support is automatic,
   specifying the yp before the command is not necessary. How to configure
   NIS is covered in Chapter 29, Network Servers.

    3.3.2.4. passwd

   Any user can easily change their password using passwd(1). To prevent
   accidental or unauthorized changes, this command will prompt for the
   user's original password before a new password can be set:

   Example 3.6. Changing Your Password

 % passwd
 Changing local password for jru.
 Old password:
 New password:
 Retype new password:
 passwd: updating the database...
 passwd: done

   The superuser can change any user's password by specifying the username
   when running passwd(1). When this utility is run as the superuser, it will
   not prompt for the user's current password. This allows the password to be
   changed when a user cannot remember the original password.

   Example 3.7. 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 a link to passwd(1), so NIS works with
   either command.

    3.3.2.5. pw

   The pw(8) utility can 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 in this section.

  3.3.3. Managing Groups

   A group is a list of users. A group is identified by its group name and
   GID. In FreeBSD, the kernel uses the UID of a process, and the list of
   groups it belongs to, to determine what the process is allowed to do. Most
   of the time, the GID of a user or process usually means the first group in
   the list.

   The group name to GID mapping is listed 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 GID, and the
   fourth the comma-delimited list of members. For a more complete
   description of the syntax, refer to group(5).

   The superuser can modify /etc/group using a text editor. Alternatively,
   pw(8) can be used to add and edit groups. For example, to add a group
   called teamtwo and then confirm that it exists:

   Example 3.8. Adding a Group Using pw(8)

 # pw groupadd teamtwo
 # pw groupshow teamtwo
 teamtwo:*:1100:

   In this example, 1100 is the GID of teamtwo. Right now, teamtwo has no
   members. This command will add jru as a member of teamtwo.

   Example 3.9. Adding User Accounts to a New Group Using pw(8)

 # pw groupmod teamtwo -M jru
 # pw groupshow teamtwo
 teamtwo:*:1100:jru

   The argument to -M is a comma-delimited list of users to be added to a new
   (empty) group or to replace the members of an existing group. To the user,
   this group membership is different from (and in addition to) the user's
   primary group listed in the password file. This means that the user will
   not show up as a member when using groupshow with pw(8), but will show up
   when the information is queried via id(1) or a similar tool. When pw(8) is
   used to add a user to a group, it only manipulates /etc/group and does not
   attempt to read additional data from /etc/passwd.

   Example 3.10. Adding a New Member to a Group Using pw(8)

 # pw groupmod teamtwo -m db
 # pw groupshow teamtwo
 teamtwo:*:1100:jru,db

   In this example, the argument to -m is a comma-delimited list of users who
   are to be added to the group. Unlike the previous example, these users are
   appended to the group and do not replace existing users in the group.

   Example 3.11. Using id(1) to Determine Group Membership

 % id jru
 uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)

   In this example, jru is a member of the groups jru and teamtwo.

   For more information about this command and the format of /etc/group,
   refer to pw(8) and group(5).

3.4. Permissions

   In FreeBSD, every file and directory has an associated set of permissions
   and several utilities are available for viewing and modifying these
   permissions. Understanding how permissions work is necessary to make sure
   that users are able to access the files that they need and are unable to
   improperly access the files used by the operating system or owned by other
   users.

   This section discusses the traditional UNIX(R) permissions used in
   FreeBSD. For finer grained file system access control, refer to
   Section 13.9, "Access Control Lists".

   In UNIX(R), basic permissions are assigned using three types of access:
   read, write, and execute. These access types are used to determine file
   access to the file's owner, group, and others (everyone else). The read,
   write, and execute permissions can be represented as the letters r, w, and
   x. They can also be represented as binary numbers as each permission is
   either on or off (0). When represented as a number, the order is always
   read as rwx, where r has an on value of 4, w has an on value of 2 and x
   has an on value of 1.

   Table 4.1 summarizes the possible numeric and alphabetic possibilities.
   When reading the "Directory Listing" column, a - is used to represent a
   permission that is set to off.

   Table 3.2. UNIX(R) Permissions

      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                      

   Use the -l argument to ls(1) to view a long directory listing that
   includes a column of 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

   The first (leftmost) character in the first column indicates whether this
   file is a regular file, a directory, a special character device, a socket,
   or any other special pseudo-file device. In this example, 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 this example, 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.

   How does the system control permissions on devices? FreeBSD treats most
   hardware devices as a file that programs can open, read, and write data
   to. These special device files are stored in /dev/.

   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 is possible to change into that directory using cd(1). This also
   means that it is possible to access the files within that directory,
   subject to the permissions on the files themselves.

   In order to perform a directory listing, the read permission must be set
   on the directory. In order 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. For more
   information on file permissions and how to set them, refer to chmod(1).

  3.4.1. Symbolic Permissions

   Contributed by Tom Rhodes.

   Symbolic permissions use characters instead of octal values to assign
   permissions to files or directories. Symbolic permissions 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 chmod(1), but with letters instead of numbers.
   For example, the following command would 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 removes the
   group and "world" write permission on FILE, and adds the execute
   permissions for everyone:

 % chmod go-w,a+x FILE

  3.4.2. FreeBSD File Flags

   Contributed by Tom Rhodes.

   In addition to file permissions, FreeBSD supports the use of "file flags".
   These flags add an additional level of security and control over files,
   but not directories. With file flags, even root can be prevented from
   removing or altering files.

   File flags are modified using chflags(1). For example, to enable the
   system undeletable flag on the file file1, issue the following command:

 # chflags sunlink file1

   To disable the system undeletable flag, put a "no" in front of the
   sunlink:

 # chflags nosunlink file1

   To view the flags of a file, use -lo with ls(1):

 # ls -lo file1

 -rw-r--r--  1 trhodes  trhodes  sunlnk 0 Mar  1 05:54 file1

   Several file flags may only be added or removed by the root user. In other
   cases, the file owner may set its file flags. Refer to chflags(1) and
   chflags(2) for more information.

  3.4.3. The setuid, setgid, and sticky Permissions

   Contributed by Tom Rhodes.

   Other than the permissions already discussed, there are three other
   specific settings that all administrators should know about. They are the
   setuid, setgid, and sticky permissions.

   These settings are important for some UNIX(R) operations as they provide
   functionality not normally granted to normal users. To understand them,
   the difference between the real user ID and effective user ID must be
   noted.

   The real user ID is the UID who owns or starts the process. The effective
   UID is the user ID the process runs as. As an example, passwd(1) runs with
   the real user ID when a user changes their password. However, in order to
   update the password database, the command runs as the effective ID of the
   root user. This allows users to change their passwords without seeing a
   Permission Denied error.

   The setuid permission may be set by prefixing a permission set with the
   number four (4) as shown in the following example:

 # chmod 4755 suidexample.sh

   The permissions on suidexample.sh now look like the following:

 -rwsr-xr-x   1 trhodes  trhodes    63 Aug 29 06:36 suidexample.sh

   Note that a s is now part of the permission set designated for the file
   owner, replacing the executable bit. This allows utilities which need
   elevated permissions, such as passwd(1).

  Note:

   The nosuid mount(8) option will cause such binaries to silently fail
   without alerting the user. That option is not completely reliable as a
   nosuid wrapper may be able to circumvent it.

   To view this in real time, open two terminals. On one, type passwd as a
   normal user. While it waits for a new password, check the process table
   and look at the user information for passwd(1):

   In terminal A:

 Changing local password for trhodes
 Old Password:

   In terminal B:

 # ps aux | grep passwd

 trhodes  5232  0.0  0.2  3420  1608   0  R+    2:10AM   0:00.00 grep passwd
 root     5211  0.0  0.2  3620  1724   2  I+    2:09AM   0:00.01 passwd

   Although passwd(1) is run as a normal user, it is using the effective UID
   of root.

   The setgid permission performs the same function as the setuid permission;
   except that it alters the group settings. When an application or utility
   executes with this setting, it will be granted the permissions based on
   the group that owns the file, not the user who started the process.

   To set the setgid permission on a file, provide chmod(1) with a leading
   two (2):

 # chmod 2755 sgidexample.sh

   In the following listing, notice that the s is now in the field designated
   for the group permission settings:

 -rwxr-sr-x   1 trhodes  trhodes    44 Aug 31 01:49 sgidexample.sh

  Note:

   In these examples, even though the shell script in question is an
   executable file, it will not run with a different EUID or effective user
   ID. This is because shell scripts may not access the setuid(2) system
   calls.

   The setuid and setgid permission bits may lower system security, by
   allowing for elevated permissions. The third special permission, the
   sticky bit, can strengthen the security of a system.

   When the sticky bit is set on a directory, it allows file deletion only by
   the file owner. This is useful to prevent file deletion in public
   directories, such as /tmp, by users who do not own the file. To utilize
   this permission, prefix the permission set with a one (1):

 # chmod 1777 /tmp

   The sticky bit permission will display as a t at the very end of the
   permission set:

 # ls -al / | grep tmp

 drwxrwxrwt  10 root  wheel         512 Aug 31 01:49 tmp

3.5. Directory Structure

   The FreeBSD directory hierarchy is fundamental to obtaining an overall
   understanding of the system. The most important directory is root or, "/".
   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 other file
   systems that are mounted during the transition to multi-user operation.

   A mount point is a directory where additional file systems can be grafted
   onto a parent file system (usually the root file system). This is further
   described in Section 3.6, "Disk Organization". Standard mount points
   include /usr/, /var/, /tmp/, /mnt/, and /cdrom/. These directories are
   usually referenced to entries in /etc/fstab. This file is a table of
   various file systems and mount points and is read by the system. Most of
   the file systems in /etc/fstab are mounted automatically at boot time from
   the script rc(8) unless their entry includes noauto. Details can be found
   in Section 3.7.1, "The fstab File".

   A complete description of the file system hierarchy is available in
   hier(7). The following table provides a brief overview of the most common
   directories.

      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 boot configuration files. Refer to loader.conf(5)  
                   for details.                                               
   /dev/           Device nodes. Refer to intro(4) for details.               
   /etc/           System configuration files and scripts.                    
   /etc/defaults/  Default system configuration files. Refer to rc(8) for     
                   details.                                                   
   /etc/mail/      Configuration files for mail transport agents such as      
                   sendmail(8).                                               
   /etc/periodic/  Scripts that run daily, weekly, and monthly, via cron(8).  
                   Refer to periodic(8) for details.                          
   /etc/ppp/       ppp(8) configuration files.                                
   /mnt/           Empty directory commonly used by system administrators as  
                   a temporary mount point.                                   
   /proc/          Process file system. Refer to procfs(5), mount_procfs(8)   
                   for details.                                               
   /rescue/        Statically linked programs for emergency recovery as       
                   described in rescue(8).                                    
   /root/          Home directory for the root account.                       
   /sbin/          System programs and administration utilities fundamental   
                   to both single-user and multi-user environments.           
   /tmp/           Temporary files which are usually not preserved across a   
                   system reboot. A memory-based file system is often mounted 
                   at /tmp. This can be automated using the tmpmfs-related    
                   variables of rc.conf(5) or with an entry in /etc/fstab;    
                   refer to mdmfs(8) for details.                             
   /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 and system utilities executed by other      
                   programs.                                                  
   /usr/local/     Local executables and libraries. Also used as the default  
                   destination for the FreeBSD ports framework. Within        
                   /usr/local, the general layout sketched out by hier(7) for 
                   /usr should be used. Exceptions are the man directory,     
                   which is directly under /usr/local rather than under       
                   /usr/local/share, and the ports documentation is in        
                   share/doc/port.                                            
   /usr/obj/       Architecture-specific target tree produced by building the 
                   /usr/src tree.                                             
   /usr/ports/     The FreeBSD Ports Collection (optional).                   
   /usr/sbin/      System daemons and system utilities executed by users.     
   /usr/share/     Architecture-independent files.                            
   /usr/src/       BSD and/or local source files.                             
   /var/           Multi-purpose log, temporary, transient, and spool files.  
                   A memory-based file system is sometimes mounted at /var.   
                   This can be automated using the varmfs-related variables   
                   in rc.conf(5) or with an entry in /etc/fstab; refer to     
                   mdmfs(8) for details.                                      
   /var/log/       Miscellaneous system log files.                            
   /var/mail/      User mailbox files.                                        
   /var/spool/     Miscellaneous printer and mail system spooling             
                   directories.                                               
   /var/tmp/       Temporary files which are usually preserved across a       
                   system reboot, unless /var is a memory-based file system.  
   /var/yp/        NIS maps.                                                  

3.6. Disk Organization

   The smallest unit of organization that FreeBSD uses to find files is the
   filename. Filenames are case-sensitive, which means that readme.txt and
   README.TXT are two separate files. FreeBSD does not use the extension of a
   file to determine whether the file is a program, 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 a hierarchy of directories within one another in
   order to organize 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. For example, if the directory foo contains a directory bar
   which contains the file readme.txt, the full name, or path, to the file is
   foo/bar/readme.txt. Note that this is different from Windows(R) which uses
   \ to separate file and directory names. FreeBSD does not use drive
   letters, or other drive names in the path. For example, one would not type
   c:\foo\bar\readme.txt on FreeBSD.

   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 contain other
   directories. One file system is designated the root file system or /.
   Every other file system is mounted under the root file system. No matter
   how many disks are on the FreeBSD system, every directory appears to be
   part of the same disk.

   Consider 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 ls(1) is used to view the contents of this
   directory, it will show two subdirectories, A1 and A2. The directory tree
   looks like this:

   A file system must be mounted on to a directory in another file system.
   When mounting file system B on to the directory A1, the root directory of
   B replaces A1, and the directories in B appear accordingly:

   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:

   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:

   Or C could be mounted directly on to the A file system, under the A1
   directory:

   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,
       the root file system can be mounted read-only, making it impossible
       for users to inadvertently delete or edit a critical file. Separating
       user-writable file systems, such as /home, from other file systems
       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.

     * FreeBSD 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.

     * FreeBSD's file systems are robust if power is lost. However, a power
       loss at a critical point could still damage the structure of the file
       system. By splitting data over multiple file systems it is more likely
       that the system will still come up, making it easier 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 FreeBSD and give it a specific size, you may later discover
       that you need to make the partition bigger. This is not easily
       accomplished without backing up, recreating the file system with the
       new size, and then restoring the backed up data.

  Important:

       FreeBSD features the growfs(8) command, which makes it possible to
       increase the size of file system on the fly, removing this limitation.

   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(R)
   partition), because of FreeBSD's UNIX(R) 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.

   FreeBSD also uses disk space for swap space to provide virtual memory.
   This allows your computer to behave as though it has much more memory than
   it actually does. When FreeBSD 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.                                    
   c         Normally the same size as the enclosing slice. This allows       
             utilities that need to work on the entire slice, such as a bad   
             block scanner, to work on the c partition. A file system would   
             not normally be created on this partition.                       
   d         Partition d used to have a special meaning associated with it,   
             although that is now gone and d may work as any normal           
             partition.                                                       

   Disks in FreeBSD are divided into slices, referred to in Windows(R) as
   partitions, which are numbered from 1 to 4. These are then divided into
   partitions, which contain file systems, and are labeled using letters.

   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 there can be logical slices inside
   physical slices of the appropriate type. These extended slices are
   numbered starting at 5, so "ada0s5" is the first extended slice on the
   first SATA 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". "ada1s3e" is the fifth partition
   in the third slice of the second SATA 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 are
   listed in Table 3.3, "Disk Device Names".

   When referring to a partition, include the disk name, s, the slice number,
   and then the partition letter. Examples are shown in Example 3.12, "Sample
   Disk, Slice, and Partition Names".

   Example 3.13, "Conceptual Model of a Disk" shows a conceptual model of a
   disk layout.

   When installing FreeBSD, configure the disk slices, create partitions
   within the slice to be used for FreeBSD, create a file system or swap
   space in each partition, and decide where each file system will be
   mounted.

   Table 3.3. Disk Device Names

            Drive Type                        Drive Device Name               
   SATA and IDE hard drives     ada or ad                                     
   SCSI hard drives and USB     da                                            
   storage devices              
   SATA and IDE CD-ROM drives   cd or acd                                     
   SCSI CD-ROM drives           cd                                            
   Floppy drives                fd                                            
   Assorted non-standard CD-ROM mcd for Mitsumi CD-ROM and scd for Sony       
   drives                       CD-ROM devices                                
   SCSI tape drives             sa                                            
   IDE tape drives              ast                                           
                                Examples include aacd for Adaptec(R)          
   RAID drives                  AdvancedRAID, mlxd and mlyd for Mylex(R),     
                                amrd for AMI MegaRAID(R), idad for Compaq     
                                Smart RAID, twed for 3ware(R) RAID.           

   Example 3.12. Sample Disk, Slice, and Partition Names

    Name                                Meaning                               
   ada0s1a The first partition (a) on the first slice (s1) on the first SATA  
           disk (ada0).                                                       
   da1s2e  The fifth partition (e) on the second slice (s2) on the second     
           SCSI disk (da1).                                                   

   Example 3.13. Conceptual Model of a Disk

   This diagram shows FreeBSD's view of the first SATA disk attached to the
   system. Assume that the disk is 250 GB in size, and contains an 80 GB
   slice and a 170 GB slice (MS-DOS(R) partitions). The first slice contains
   a Windows(R) NTFS file system, C:, and the second slice contains a FreeBSD
   installation. This example FreeBSD installation has four data partitions
   and a swap partition.

   The four partitions each hold a file system. Partition a is used for the
   root file system, d for /var/, e for /tmp/, and f for /usr/. Partition
   letter c refers to the entire slice, and so is not used for ordinary
   partitions.

3.7. 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, described in
   Section 29.3, "Network File System (NFS)", or CDROM drives.

  3.7.1. The fstab File

   During the boot process (Chapter 12, The FreeBSD Booting Process), file
   systems listed in /etc/fstab are automatically mounted except for the
   entries containing noauto. This file contains entries in the following
   format:

 device       /mount-point fstype     options      dumpfreq     passno

   device

           An existing device name as explained in Table 3.3, "Disk Device
           Names".

   mount-point

           An existing directory on which to mount the file system.

   fstype

           The file system type to pass to mount(8). The default FreeBSD 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 mount(8).

   dumpfreq

           Used by dump(8) to determine which file systems require dumping.
           If the field is missing, a value of zero is assumed.

   passno

           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 needs to be checked before everything
           else and should have its passno set to one. The other file systems
           should be set to values greater than one. If more than one file
           system has the same passno, fsck(8) will attempt to check file
           systems in parallel if possible.

   Refer to fstab(5) for more information on the format of /etc/fstab and its
   options.

  3.7.2. Using mount(8)

   File systems are mounted using mount(8). The most basic syntax is as
   follows:

 # mount device mountpoint

   This command provides many options which are described in mount(8), The
   most commonly used options include:

   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 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 -o ro.

   -t fstype

           Mount the specified file system type or mount only file systems of
           the given type, if -a is included. "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 following options can be passed to -o as a comma-separated list:

   nosuid

           Do not interpret setuid or setgid flags on the file system. This
           is also a useful security option.

  3.7.3. Using umount(8)

   To unmount a file system use umount(8). This command takes one parameter
   which can be a mountpoint, device name, -a or -A.

   All forms take -f to force unmounting, and -v for verbosity. Be warned
   that -f is not generally a good idea as it might crash the computer or
   damage data on the file system.

   To unmount all mounted file systems, or just the file system types listed
   after -t, use -a or -A. Note that -A does not attempt to unmount the root
   file system.

3.8. Processes and Daemons

   FreeBSD is a multi-tasking operating system. Each program running at any
   one time is called a process. Every running command starts at least one
   new process and there are a number of system processes that are run by
   FreeBSD.

   Each process is uniquely identified by a number called a process ID (PID).
   Similar to files, each process has one owner and group, and the owner and
   group permissions are used to determine which files and devices the
   process can open. Most processes also have a parent process that started
   them. For example, the shell is a process, and any command started in the
   shell is a process which has the shell as its parent process. The
   exception is a special process called init(8) which is always the first
   process to start at boot time and which always has a PID of 1.

   Some programs are not designed to be run with continuous user input and
   disconnect from the terminal at the first opportunity. For example, a web
   server responds to web requests, rather than user input. Mail servers are
   another example of this type of application. These types of programs are
   known as daemons. The term daemon comes from Greek mythology and
   represents an entity that is neither good nor evil, and which invisibly
   performs useful tasks. This is why the BSD mascot is the cheerful-looking
   daemon with sneakers and a pitchfork.

   There is a convention to name programs that normally run as daemons with a
   trailing "d". For example, BIND is the Berkeley Internet Name Domain, but
   the actual program that executes is named. The Apache web server program
   is httpd and the line printer spooling daemon is lpd. This is only a
   naming convention. For example, the main mail daemon for the Sendmail
   application is sendmail, and not maild.

  3.8.1. Viewing Processes

   To see the processes running on the system, use ps(1) or top(1). To
   display a static list of the currently running processes, their PIDs, how
   much memory they are using, and the command they were started with, use
   ps(1). To display all the running processes and update the display every
   few seconds in order to interactively see what the computer is doing, use
   top(1).

   By default, ps(1) only shows the commands that are running and owned by
   the user. For example:

 % ps
  PID TT  STAT    TIME COMMAND
 8203  0  Ss   0:00.59 /bin/csh
 8895  0  R+   0:00.00 ps

   The output from ps(1) is organized into a number of columns. The PID
   column displays the process ID. PIDs are assigned starting at 1, go up to
   99999, then wrap around back to the beginning. However, a PID is not
   reassigned if it is already in use. The TT column shows the tty the
   program is running on and STAT shows the program's state. TIME is the
   amount of time the program has been running on the CPU. This is usually
   not the elapsed time since the program was started, 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 that was used to start the
   program.

   A number of different options are available to change the information that
   is displayed. One of the most useful sets is auxww, where a displays
   information about all the running processes of all users, u displays the
   username and memory usage of the process' owner, x displays information
   about daemon processes, and ww causes ps(1) to display the full command
   line for each process, rather than truncating it once it gets too long to
   fit on the screen.

   The output from top(1) is similar:

 % top
 last pid:  9609;  load averages:  0.56,  0.45,  0.36              up 0+00:20:03  10:21:46
 107 processes: 2 running, 104 sleeping, 1 zombie
 CPU:  6.2% user,  0.1% nice,  8.2% system,  0.4% interrupt, 85.1% idle
 Mem: 541M Active, 450M Inact, 1333M Wired, 4064K Cache, 1498M Free
 ARC: 992M Total, 377M MFU, 589M MRU, 250K Anon, 5280K Header, 21M Other
 Swap: 2048M Total, 2048M Free

   PID USERNAME    THR PRI NICE   SIZE    RES STATE   C   TIME   WCPU COMMAND
   557 root          1 -21  r31   136M 42296K select  0   2:20  9.96% Xorg
  8198 dru           2  52    0   449M 82736K select  3   0:08  5.96% kdeinit4
  8311 dru          27  30    0  1150M   187M uwait   1   1:37  0.98% firefox
   431 root          1  20    0 14268K  1728K select  0   0:06  0.98% moused
  9551 dru           1  21    0 16600K  2660K CPU3    3   0:01  0.98% top
  2357 dru           4  37    0   718M   141M select  0   0:21  0.00% kdeinit4
  8705 dru           4  35    0   480M    98M select  2   0:20  0.00% kdeinit4
  8076 dru           6  20    0   552M   113M uwait   0   0:12  0.00% soffice.bin
  2623 root          1  30   10 12088K  1636K select  3   0:09  0.00% powerd
  2338 dru           1  20    0   440M 84532K select  1   0:06  0.00% kwin
  1427 dru           5  22    0   605M 86412K select  1   0:05  0.00% kdeinit4

   The output is split into two sections. The header (the first five or six
   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, how much memory and swap
   space has been used, and how much time the system is spending in different
   CPU states. If the ZFS file system module has been loaded, an ARC line
   indicates how much data was read from the memory cache instead of from
   disk.

   Below the header is a series of columns containing similar information to
   the output from ps(1), such as the PID, username, amount of CPU time, and
   the command that started the process. By default, top(1) also displays 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 now.

   top(1) automatically updates the display every two seconds. A different
   interval can be specified with -s.

  3.8.2. Killing Processes

   One way to communicate with any running process or daemon is to send a
   signal using kill(1). There are a number of different signals; some have a
   specific meaning while others are described in the application's
   documentation. A user can only send a signal to a process they own and
   sending a signal to someone else's process will result in a permission
   denied error. The exception is the root user, who can send signals to
   anyone's processes.

   The operating system can also send a signal to a process. If an
   application is badly written and tries to access memory that it is not
   supposed to, FreeBSD will send the process the "Segmentation Violation"
   signal (SIGSEGV). If an application has been written to use the alarm(3)
   system call to be alerted after a period of time has elapsed, it will be
   sent the "Alarm" signal (SIGALRM).

   Two signals can be used to stop a process: SIGTERM and SIGKILL. SIGTERM is
   the polite way to kill a process as the process can read the signal, close
   any log files it may have open, and attempt to finish what it is doing
   before shutting down. In some cases, a process may ignore SIGTERM if it is
   in the middle of some task that cannot be interrupted.

   SIGKILL cannot be ignored by a process. Sending a SIGKILL to a process
   will usually stop that process there and then. [1].

   Other commonly used signals are SIGHUP, SIGUSR1, and SIGUSR2. Since these
   are general purpose signals, different applications will respond
   differently.

   For example, after changing a web server's configuration file, the web
   server needs to be told to re-read its configuration. Restarting httpd
   would result in a brief outage period on the web server. Instead, send the
   daemon the SIGHUP signal. Be aware that different daemons will have
   different behavior, so refer to the documentation for the daemon to
   determine if SIGHUP will achieve the desired results.

   Procedure 3.1. Sending a Signal to a Process

   This example shows how to send a signal to inetd(8). The inetd(8)
   configuration file is /etc/inetd.conf, and inetd(8) will re-read this
   configuration file when it is sent a SIGHUP.

    1. Find the PID of the process to send the signal to using pgrep(1). In
       this example, the PID for inetd(8) is 198:

 % pgrep -l inetd
 198  inetd -wW

    2. Use kill(1) to send the signal. Because inetd(8) is owned by root, use
       su(1) to become root first.

 % su
 Password:
 # /bin/kill -s HUP 198

       Like most UNIX(R) commands, kill(1) will not print any output if it is
       successful. If a signal is sent to a process not owned by that user,
       the message kill: PID: Operation not permitted will be displayed.
       Mistyping the PID will either send the signal to the wrong process,
       which could have negative results, or will send the signal to a PID
       that is not currently in use, resulting in the error kill: PID: No
       such process.

  Why Use /bin/kill?:

       Many shells provide kill as a built in command, meaning that the shell
       will send the signal directly, rather than running /bin/kill. Be aware
       that 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 to specify /bin/kill.

   When sending other signals, substitute TERM or KILL with the name of the
   signal.

  Important:

   Killing a random process on the system is a bad idea. In particular,
   init(8), PID 1, is special. Running /bin/kill -s KILL 1 is a quick, and
   unrecommended, way to shutdown the system. Always double check the
   arguments to kill(1) before pressing Return.

3.9. Shells

   A shell provides a command line interface for interacting with the
   operating system. A shell receives commands from the input channel and
   executes them. Many shells provide built in functions to help with
   everyday tasks such as file management, file globbing, command line
   editing, command macros, and environment variables. FreeBSD comes with
   several shells, including the Bourne shell (sh(1)) and the extended C
   shell (tcsh(1)). Other shells are available from the FreeBSD Ports
   Collection, such as zsh and bash.

   The shell that is used is really a matter of taste. A C programmer might
   feel more comfortable with a C-like shell such as tcsh(1). A Linux(R) user
   might prefer bash. Each shell has unique properties that may or may not
   work with a user's preferred working environment, which is why there is a
   choice of which shell to use.

   One common shell feature is filename completion. After a user types the
   first few letters of a command or filename and presses Tab, the shell
   completes the rest of the command or filename. Consider two files called
   foobar and football. To delete foobar, the user might type rm foo and
   press Tab to complete the filename.

   But the shell only shows rm foo. It was unable to complete the filename
   because both foobar and football start with foo. Some shells sound a beep
   or show all the choices if more than one name matches. The user must then
   type more characters to identify the desired filename. Typing a t and
   pressing Tab again is enough to let the shell determine which filename is
   desired and fill in the rest.

   Another feature of the shell is the use of environment variables.
   Environment variables are a variable/key pair stored in the shell's
   environment. This environment can be read by any program invoked by the
   shell, and thus contains a lot of program configuration. Table 3.4,
   "Common Environment Variables" provides a list of common environment
   variables and their meanings. Note that the names of environment variables
   are always in uppercase.

   Table 3.4. Common Environment Variables

   Variable                            Description                            
   USER     Current logged in user's name.                                    
   PATH     Colon-separated list of directories to search for binaries.       
   DISPLAY  Network name of the Xorg display to connect to, if available.     
   SHELL    The current shell.                                                
   TERM     The name of the user's type of 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.                                         
   MACHTYPE The system's CPU architecture.                                    
   EDITOR   The user's preferred text editor.                                 
   PAGER    The user's preferred utility for viewing text one page at a time. 
   MANPATH  Colon-separated list of directories to search for manual pages.   

   How to set an environment variable differs between shells. In tcsh(1) and
   csh(1), use setenv to set environment variables. In sh(1) and bash, use
   export to set the current environment variables. This example sets the
   default EDITOR to /usr/local/bin/emacs for the tcsh(1) shell:

 % setenv EDITOR /usr/local/bin/emacs

   The equivalent command for bash would be:

 % export EDITOR="/usr/local/bin/emacs"

   To expand an environment variable in order to see its current setting,
   type a $ character in front of its name on the command line. For example,
   echo $TERM displays the current $TERM setting.

   Shells treat special characters, known as meta-characters, as special
   representations of data. The most common meta-character is *, which
   represents any number of characters in a filename. Meta-characters can be
   used to perform filename globbing. For example, echo * is equivalent to ls
   because the shell takes all the files that match * and echo lists them on
   the command line.

   To prevent the shell from interpreting a special character, escape it from
   the shell by starting it with a backslash (\). For example, echo $TERM
   prints the terminal setting whereas echo \$TERM literally prints the
   string $TERM.

  3.9.1. Changing the Shell

   The easiest way to permanently change the default shell is to use chsh.
   Running this command will open the editor that is configured in the EDITOR
   environment variable, which by default is set to vi(1). Change the Shell:
   line to the full path of the new shell.

   Alternately, use chsh -s which will set the specified shell without
   opening an editor. For example, to change the shell to bash:

 % chsh -s /usr/local/bin/bash

  Note:

   The new shell must be present in /etc/shells. If the shell was installed
   from the FreeBSD Ports Collection as described in Chapter 4, Installing
   Applications: Packages and Ports, it should be automatically added to this
   file. If it is missing, add it using this command, replacing the path with
   the path of the shell:

 # echo /usr/local/bin/bash >> /etc/shells

   Then, rerun chsh(1).

  3.9.2. Advanced Shell Techniques

   Written by Tom Rhodes.

   The UNIX(R) shell is not just a command interpreter, it acts as a powerful
   tool which allows users to execute commands, redirect their output,
   redirect their input and chain commands together to improve the final
   command output. When this functionality is mixed with built in commands,
   the user is provided with an environment that can maximize efficiency.

   Shell redirection is the action of sending the output or the input of a
   command into another command or into a file. To capture the output of the
   ls(1) command, for example, into a file, redirect the output:

 % ls > directory_listing.txt

   The directory contents will now be listed in directory_listing.txt. Some
   commands can be used to read input, such as sort(1). To sort this listing,
   redirect the input:

 % sort < directory_listing.txt

   The input will be sorted and placed on the screen. To redirect that input
   into another file, one could redirect the output of sort(1) by mixing the
   direction:

 % sort < directory_listing.txt > sorted.txt

   In all of the previous examples, the commands are performing redirection
   using file descriptors. Every UNIX(R) system has file descriptors, which
   include standard input (stdin), standard output (stdout), and standard
   error (stderr). Each one has a purpose, where input could be a keyboard or
   a mouse, something that provides input. Output could be a screen or paper
   in a printer. And error would be anything that is used for diagnostic or
   error messages. All three are considered I/O based file descriptors and
   sometimes considered streams.

   Through the use of these descriptors, the shell allows output and input to
   be passed around through various commands and redirected to or from a
   file. Another method of redirection is the pipe operator.

   The UNIX(R) pipe operator, "|" allows the output of one command to be
   directly passed or directed to another program. Basically, a pipe allows
   the standard output of a command to be passed as standard input to another
   command, for example:

 % cat directory_listing.txt | sort | less

   In that example, the contents of directory_listing.txt will be sorted and
   the output passed to less(1). This allows the user to scroll through the
   output at their own pace and prevent it from scrolling off the screen.

3.10. Text Editors

   Most FreeBSD configuration is done by editing text files. Because of this,
   it is a good idea to become familiar with a text editor. FreeBSD comes
   with a few as part of the base system, and many more are available in the
   Ports Collection.

   A simple editor to learn is ee(1), which stands for easy editor. To start
   this editor, type ee filename where filename is the name of the file to be
   edited. Once inside the editor, all of the commands for manipulating the
   editor's functions are listed at the top of the display. The caret (^)
   represents Ctrl, so ^e expands to Ctrl+e. To leave ee(1), press Esc, then
   choose the "leave editor" option from the main menu. The editor will
   prompt to save any changes if the file has been modified.

   FreeBSD also comes with more powerful text editors, such as vi(1), as part
   of the base system. Other editors, like editors/emacs and editors/vim, are
   part of the FreeBSD Ports Collection. These editors offer more
   functionality at the expense of being more complicated to learn. Learning
   a more powerful editor such as vim or Emacs can save more time in the long
   run.

   Many applications which modify files or require typed input will
   automatically open a text editor. To change the default editor, set the
   EDITOR environment variable as described in Section 3.9, "Shells".

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
   FreeBSD boots, the majority of the boot messages refer to devices being
   detected. A copy of the boot messages are saved to /var/run/dmesg.boot.

   Each device has a device name and number. For example, ada0 is the first
   SATA hard drive, while kbd0 represents the keyboard.

   Most devices in FreeBSD must be accessed through special files called
   device nodes, which are located in /dev.

3.12. Manual Pages

   The most comprehensive documentation on FreeBSD is in the form of manual
   pages. Nearly every program on the system comes with a short reference
   manual explaining the basic operation and available arguments. These
   manuals can be viewed using man:

 % man command

   where command is the name of the command to learn about. For example, to
   learn more about ls(1), type:

 % man ls

   Manual pages are divided into sections which represent the type of topic.
   In FreeBSD, the following sections are available:

    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. System kernel interfaces.

   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. To tell man(1) which section to display, specify the section
   number:

 % man 1 chmod

   This will display the manual page for the user command chmod(1).
   References to a particular section of the online manual are traditionally
   placed in parenthesis in written documentation, so chmod(1) refers to the
   user command and chmod(2) refers to the system call.

   If the name of the manual page is unknown, use man -k to search for
   keywords in the manual page descriptions:

 % man -k mail

   This command displays a list of commands that have the keyword "mail" in
   their descriptions. This is equivalent to using apropos(1).

   To read the descriptions for all of the commands in /usr/bin, type:

 % cd /usr/bin
 % man -f * | more

   or

 % cd /usr/bin
 % whatis * |more

  3.12.1. GNU Info Files

   FreeBSD includes several applications and utilities produced by the Free
   Software Foundation (FSF). In addition to manual pages, these programs may
   include hypertext documents called info files. These can be viewed using
   info(1) or, if editors/emacs is installed, the info mode of emacs.

   To use info(1), type:

 % info

   For a brief introduction, type h. For a quick command reference, type ?.

     ----------------------------------------------------------------------

   [1] There are a few tasks that cannot be interrupted. For example, if the
   process is trying to read from a file that is on another computer on the
   network, and the other computer is unavailable, the process is said to be
   "uninterruptible". Eventually the process will time out, typically after
   two minutes. As soon as this time out occurs the process will be killed.

Chapter 4. Installing Applications: Packages and Ports

   Table of Contents

   4.1. Synopsis

   4.2. Overview of Software Installation

   4.3. Finding Software

   4.4. Using pkg for Binary Package Management

   4.5. Using the Ports Collection

   4.6. Building Packages with Poudriere

   4.7. Post-Installation Considerations

   4.8. Dealing with Broken Ports

4.1. Synopsis

   FreeBSD is bundled with a rich collection of system tools as part of the
   base system. In addition, FreeBSD provides two complementary technologies
   for installing third-party software: the FreeBSD Ports Collection, for
   installing from source, and packages, for installing from pre-built
   binaries. Either method may be used to install software from local media
   or from the network.

   After reading this chapter, you will know:

     * The difference between binary packages and ports.

     * How to find third-party software that has been ported to FreeBSD.

     * How to manage binary packages using pkg.

     * How to build third-party software from source using the Ports
       Collection.

     * How to find the files installed with the application for
       post-installation configuration.

     * What to do if a software installation fails.

4.2. Overview of Software Installation

   The typical steps for installing third-party software on a UNIX(R) system
   include:

    1. Find and download the software, which might be distributed in source
       code format or as a binary.

    2. Unpack the software from its distribution format. This is typically a
       tarball compressed with a program such as compress(1), gzip(1),
       bzip2(1) or xz(1).

    3. Locate the documentation in INSTALL, README or some file 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.

    5. Test and install the software.

   A FreeBSD port is a collection of files designed to automate the process
   of compiling an application from source code. The files that comprise a
   port contain all the necessary information to automatically download,
   extract, patch, compile, and install the application.

   If the software has not already been adapted and tested on FreeBSD, the
   source code might need editing in order for it to install and run
   properly.

   However, over 24,000 third-party applications have already been ported to
   FreeBSD. When feasible, these applications are made available for download
   as pre-compiled packages.

   Packages can be manipulated with the FreeBSD package management commands.

   Both packages and ports understand dependencies. If a package or port is
   used to install an application and a dependent library is not already
   installed, the library will automatically be installed first.

   A FreeBSD package contains pre-compiled copies of all the commands for an
   application, as well as any configuration files and documentation. A
   package can be manipulated with the pkg(8) commands, such as pkg install.

   While the two technologies are similar, packages and ports each have their
   own strengths. Select the technology that meets your requirements for
   installing a particular application.

   Package Benefits
     * A compressed package tarball is typically smaller than the compressed
       tarball containing the source code for the application.

     * Packages do not require compilation time. For large applications, such
       as Mozilla, KDE, or GNOME, this can be important on a slow system.

     * Packages do not require any understanding of the process involved in
       compiling software on FreeBSD.

   Port Benefits
     * Packages are normally compiled with conservative options because they
       have to run on the maximum number of systems. By compiling from the
       port, one can change the compilation options.

     * Some applications have compile-time options relating to which features
       are installed. For example, Apache can be configured with a wide
       variety of different built-in options.

       In some cases, multiple packages will exist for the same application
       to specify certain settings. For example, Ghostscript is available as
       a ghostscript package and a ghostscript-nox11 package, depending on
       whether or not Xorg is installed. Creating multiple packages rapidly
       becomes impossible if an application has more than one or two
       different compile-time options.

     * The licensing conditions of some software forbid binary distribution.
       Such software must be distributed as source code which must be
       compiled by the end-user.

     * Some people do not trust binary distributions or prefer to read
       through source code in order to look for potential problems.

     * Source code is needed in order to apply custom patches.

   To keep track of updated ports, subscribe to the FreeBSD ports mailing
   list and the FreeBSD ports bugs mailing list.

  Warning:

   Before installing any application, check https://vuxml.freebsd.org/ for
   security issues related to the application or type pkg audit -F to check
   all installed applications for known vulnerabilities.

   The remainder of this chapter explains how to use packages and ports to
   install and manage third-party software on FreeBSD.

4.3. Finding Software

   FreeBSD's list of available applications is growing all the time. There
   are a number of ways to find software to install:

     * The FreeBSD web site maintains an up-to-date searchable list of all
       the available applications, at https://www.FreeBSD.org/ports/. The
       ports can be searched by application name or by software category.

     * Dan Langille maintains FreshPorts.org which provides a comprehensive
       search utility and also tracks changes to the applications in the
       Ports Collection. Registered users can create a customized watch list
       in order to receive an automated email when their watched ports are
       updated.

     * If finding a particular application becomes challenging, try searching
       a site like SourceForge.net or GitHub.com then check back at the
       FreeBSD site to see if the application has been ported.

     * To search the binary package repository for an application:

 # pkg search subversion
 git-subversion-1.9.2
 java-subversion-1.8.8_2
 p5-subversion-1.8.8_2
 py27-hgsubversion-1.6
 py27-subversion-1.8.8_2
 ruby-subversion-1.8.8_2
 subversion-1.8.8_2
 subversion-book-4515
 subversion-static-1.8.8_2
 subversion16-1.6.23_4
 subversion17-1.7.16_2

       Package names include the version number and, in the case of ports
       based on python, the version number of the version of python the
       package was built with. Some ports also have multiple versions
       available. In the case of Subversion, there are different versions
       available, as well as different compile options. In this case, the
       statically linked version of Subversion. When indicating which package
       to install, it is best to specify the application by the port origin,
       which is the path in the ports tree. Repeat the pkg search with -o to
       list the origin of each package:

 # pkg search -o subversion
 devel/git-subversion
 java/java-subversion
 devel/p5-subversion
 devel/py-hgsubversion
 devel/py-subversion
 devel/ruby-subversion
 devel/subversion16
 devel/subversion17
 devel/subversion
 devel/subversion-book
 devel/subversion-static

       Searching by shell globs, regular expressions, exact match, by
       description, or any other field in the repository database is also
       supported by pkg search. After installing ports-mgmt/pkg or
       ports-mgmt/pkg-devel, see pkg-search(8) for more details.

     * If the Ports Collection is already installed, there are several
       methods to query the local version of the ports tree. To find out
       which category a port is in, type whereis file, where file is the
       program to be installed:

 # whereis lsof
 lsof: /usr/ports/sysutils/lsof

       Alternately, an echo(1) statement can be used:

 # echo /usr/ports/*/*lsof*
 /usr/ports/sysutils/lsof

       Note that this will also return any matched files downloaded into the
       /usr/ports/distfiles directory.

     * Another way to find software is by using the Ports Collection's
       built-in search mechanism. To use the search feature, cd to /usr/ports
       then run make search name=program-name where program-name is the name
       of the software. For example, to search for lsof:

 # cd /usr/ports
 # make search name=lsof
 Port:   lsof-4.88.d,8
 Path:   /usr/ports/sysutils/lsof
 Info:   Lists information about open files (similar to fstat(1))
 Maint:  ler@lerctr.org
 Index:  sysutils
 B-deps:
 R-deps:

  Tip:

       The built-in search mechanism uses a file of index information. If a
       message indicates that the INDEX is required, run make fetchindex to
       download the current index file. With the INDEX present, make search
       will be able to perform the requested search.

       The "Path:" line indicates where to find the port.

       To receive less information, use the quicksearch feature:

 # cd /usr/ports
 # make quicksearch name=lsof
 Port:   lsof-4.88.d,8
 Path:   /usr/ports/sysutils/lsof
 Info:   Lists information about open files (similar to fstat(1))

       For more in-depth searching, use make search key=string or make
       quicksearch key=string, where string is some text to search for. The
       text can be in comments, descriptions, or dependencies in order to
       find ports which relate to a particular subject when the name of the
       program is unknown.

       When using search or quicksearch, the search string is
       case-insensitive. Searching for "LSOF" will yield the same results as
       searching for "lsof".

4.4. Using pkg for Binary Package Management

   pkg is the next generation replacement for the traditional FreeBSD package
   management tools, offering many features that make dealing with binary
   packages faster and easier.

   For sites wishing to only use prebuilt binary packages from the FreeBSD
   mirrors, managing packages with pkg can be sufficient.

   However, for those sites building from source or using their own
   repositories, a separate port management tool will be needed.

   Since pkg only works with binary packages, it is not a replacement for
   such tools. Those tools can be used to install software from both binary
   packages and the Ports Collection, while pkg installs only binary
   packages.

  4.4.1. Getting Started with pkg

   FreeBSD includes a bootstrap utility which can be used to download and
   install pkg and its manual pages. This utility is designed to work with
   versions of FreeBSD starting with 10.X.

  Note:

   Not all FreeBSD versions and architectures support this bootstrap process.
   The current list is at https://pkg.freebsd.org/. For other cases, pkg must
   instead be installed from the Ports Collection or as a binary package.

   To bootstrap the system, run:

 # /usr/sbin/pkg

   You must have a working Internet connection for the bootstrap process to
   succeed.

   Otherwise, to install the port, run:

 # cd /usr/ports/ports-mgmt/pkg
 # make
 # make install clean

   When upgrading an existing system that originally used the older pkg_*
   tools, the database must be converted to the new format, so that the new
   tools are aware of the already installed packages. Once pkg has been
   installed, the package database must be converted from the traditional
   format to the new format by running this command:

 # pkg2ng

  Note:

   This step is not required for new installations that do not yet have any
   third-party software installed.

  Important:

   This step is not reversible. Once the package database has been converted
   to the pkg format, the traditional pkg_* tools should no longer be used.

  Note:

   The package database conversion may emit errors as the contents are
   converted to the new version. Generally, these errors can be safely
   ignored. However, a list of software that was not successfully converted
   is shown after pkg2ng finishes. These applications must be manually
   reinstalled.

   To ensure that the Ports Collection registers new software with pkg
   instead of the traditional packages database, FreeBSD versions earlier
   than 10.X require this line in /etc/make.conf:

 WITH_PKGNG=     yes

   By default, pkg uses the binary packages from the FreeBSD package mirrors
   (the repository). For information about building a custom package
   repository, see Section 4.6, "Building Packages with Poudriere".

   Additional pkg configuration options are described in pkg.conf(5).

   Usage information for pkg is available in the pkg(8) manual page or by
   running pkg without additional arguments.

   Each pkg command argument is documented in a command-specific manual page.
   To read the manual page for pkg install, for example, run either of these
   commands:

 # pkg help install

 # man pkg-install

   The rest of this section demonstrates common binary package management
   tasks which can be performed using pkg. Each demonstrated command provides
   many switches to customize its use. Refer to a command's help or man page
   for details and more examples.

  4.4.2. Obtaining Information About Installed Packages

   Information about the packages installed on a system can be viewed by
   running pkg info which, when run without any switches, will list the
   package version for either all installed packages or the specified
   package.

   For example, to see which version of pkg is installed, run:

 # pkg info pkg
 pkg-1.1.4_1

  4.4.3. Installing and Removing Packages

   To install a binary package use the following command, where packagename
   is the name of the package to install:

 # pkg install packagename

   This command uses repository data to determine which version of the
   software to install and if it has any uninstalled dependencies. For
   example, to install curl:

 # pkg install curl
 Updating repository catalogue
 /usr/local/tmp/All/curl-7.31.0_1.txz          100% of 1181 kB 1380 kBps 00m01s

 /usr/local/tmp/All/ca_root_nss-3.15.1_1.txz   100% of  288 kB 1700 kBps 00m00s

 Updating repository catalogue
 The following 2 packages will be installed:

         Installing ca_root_nss: 3.15.1_1
         Installing curl: 7.31.0_1

 The installation will require 3 MB more space

 0 B to be downloaded

 Proceed with installing packages [y/N]: y
 Checking integrity... done
 [1/2] Installing ca_root_nss-3.15.1_1... done
 [2/2] Installing curl-7.31.0_1... done
 Cleaning up cache files...Done

   The new package and any additional packages that were installed as
   dependencies can be seen in the installed packages list:

 # pkg info
 ca_root_nss-3.15.1_1    The root certificate bundle from the Mozilla Project
 curl-7.31.0_1   Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
 pkg-1.1.4_6     New generation package manager

   Packages that are no longer needed can be removed with pkg delete. For
   example:

 # pkg delete curl
 The following packages will be deleted:

         curl-7.31.0_1

 The deletion will free 3 MB

 Proceed with deleting packages [y/N]: y
 [1/1] Deleting curl-7.31.0_1... done

  4.4.4. Upgrading Installed Packages

   Installed packages can be upgraded to their latest versions by running:

 # pkg upgrade

   This command will compare the installed versions with those available in
   the repository catalogue and upgrade them from the repository.

  4.4.5. Auditing Installed Packages

   Software vulnerabilities are regularly discovered in third-party
   applications. To address this, pkg includes a built-in auditing mechanism.
   To determine if there are any known vulnerabilities for the software
   installed on the system, run:

 # pkg audit -F

  4.4.6. Automatically Removing Unused Packages

   Removing a package may leave behind dependencies which are no longer
   required. Unneeded packages that were installed as dependencies (leaf
   packages) can be automatically detected and removed using:

 # pkg autoremove
 Packages to be autoremoved:
         ca_root_nss-3.15.1_1

 The autoremoval will free 723 kB

 Proceed with autoremoval of packages [y/N]: y
 Deinstalling ca_root_nss-3.15.1_1... done

   Packages installed as dependencies are called automatic packages.
   Non-automatic packages, i.e the packages that were explicity installed not
   as a dependency to another package, can be listed using:

 # pkg prime-list
 nginx
 openvpn
 sudo

   pkg prime-list is an alias command declared in /usr/local/etc/pkg.conf.
   There are many others that can be used to query the package database of
   the system. For instance, command pkg prime-origins can be used to get the
   origin port directory of the list mentioned above:

 # pkg prime-origins
 www/nginx
 security/openvpn
 security/sudo

   This list can be used to rebuild all packages installed on a system using
   build tools such as ports-mgmt/poudriere or ports-mgmt/synth.

   Marking an installed package as automatic can be done using:

 # pkg set -A 1 devel/cmake

   Once a package is a leaf package and is marked as automatic, it gets
   selected by pkg autoremove.

   Marking an installed package as not automatic can be done using:

 # pkg set -A 0 devel/cmake

  4.4.7. Restoring the Package Database

   Unlike the traditional package management system, pkg includes its own
   package database backup mechanism. This functionality is enabled by
   default.

  Tip:

   To disable the periodic script from backing up the package database, set
   daily_backup_pkgdb_enable="NO" in periodic.conf(5).

   To restore the contents of a previous package database backup, run the
   following command replacing /path/to/pkg.sql with the location of the
   backup:

 # pkg backup -r /path/to/pkg.sql

  Note:

   If restoring a backup taken by the periodic script, it must be
   decompressed prior to being restored.

   To run a manual backup of the pkg database, run the following command,
   replacing /path/to/pkg.sql with a suitable file name and location:

 # pkg backup -d /path/to/pkg.sql

  4.4.8. Removing Stale Packages

   By default, pkg stores binary packages in a cache directory defined by
   PKG_CACHEDIR in pkg.conf(5). Only copies of the latest installed packages
   are kept. Older versions of pkg kept all previous packages. To remove
   these outdated binary packages, run:

 # pkg clean

   The entire cache may be cleared by running:

 # pkg clean -a

  4.4.9. Modifying Package Metadata

   Software within the FreeBSD Ports Collection can undergo major version
   number changes. To address this, pkg has a built-in command to update
   package origins. This can be useful, for example, if lang/php5 is renamed
   to lang/php53 so that lang/php5 can now represent version 5.4.

   To change the package origin for the above example, run:

 # pkg set -o lang/php5:lang/php53

   As another example, to update lang/ruby18 to lang/ruby19, run:

 # pkg set -o lang/ruby18:lang/ruby19

   As a final example, to change the origin of the libglut shared libraries
   from graphics/libglut to graphics/freeglut, run:

 # pkg set -o graphics/libglut:graphics/freeglut

  Note:

   When changing package origins, it is important to reinstall packages that
   are dependent on the package with the modified origin. To force a
   reinstallation of dependent packages, run:

 # pkg install -Rf graphics/freeglut

4.5. Using the Ports Collection

   The Ports Collection is a set of Makefiles, patches, and description
   files. Each set of these files is used to compile and install an
   individual application on FreeBSD, and is called a port.

   By default, the Ports Collection itself is stored as a subdirectory of
   /usr/ports.

   Before an application can be compiled using a port, the Ports Collection
   must first be installed. If it was not installed during the installation
   of FreeBSD, use one of the following methods to install it:

   Procedure 4.1. Portsnap Method

   The base system of FreeBSD includes Portsnap. This is a fast and
   user-friendly tool for retrieving the Ports Collection and is the
   recommended choice for most users. This utility connects to a FreeBSD
   site, verifies the secure key, and downloads a new copy of the Ports
   Collection. The key is used to verify the integrity of all downloaded
   files.

    1. To download a compressed snapshot of the Ports Collection into
       /var/db/portsnap:

 # portsnap fetch

    2. When running Portsnap for the first time, extract the snapshot into
       /usr/ports:

 # portsnap extract

    3. After the first use of Portsnap has been completed as shown above,
       /usr/ports can be updated as needed by running:

 # portsnap fetch
 # portsnap update

       When using fetch, the extract or the update operation may be run
       consecutively, like so:

 # portsnap fetch update

   Procedure 4.2. Subversion Method

   If more control over the ports tree is needed or if local changes need to
   be maintained, Subversion can be used to obtain the Ports Collection.
   Refer to the Subversion Primer for a detailed description of Subversion.

    1. Subversion must be installed before it can be used to check out the
       ports tree. If a copy of the ports tree is already present, install
       Subversion like this:

 # cd /usr/ports/devel/subversion
 # make install clean

       If the ports tree is not available, or pkg is being used to manage
       packages, Subversion can be installed as a package:

 # pkg install subversion

    2. Check out a copy of the ports tree:

 # svn checkout https://svn.FreeBSD.org/ports/head /usr/ports

    3. As needed, update /usr/ports after the initial Subversion checkout:

 # svn update /usr/ports

   The Ports Collection contains directories for software categories. Inside
   each category are subdirectories for individual applications. Each
   application subdirectory contains a set of files that tells FreeBSD how to
   compile and install that program, called a ports skeleton. Each port
   skeleton includes these files and directories:

     * Makefile: contains statements that specify how the application should
       be compiled and where its components should be installed.

     * distinfo: contains the names and checksums of the files that must be
       downloaded to build the port.

     * files/: this directory contains any patches needed for the program to
       compile and install on FreeBSD. This directory may also contain other
       files used to build the port.

     * pkg-descr: provides a more detailed description of the program.

     * pkg-plist: a list of all the files that will be installed by the port.
       It also tells the ports system which files to remove upon
       deinstallation.

   Some ports include pkg-message or other files to handle special
   situations. For more details on these files, and on ports in general,
   refer to the FreeBSD Porter's Handbook.

   The port does not include the actual source code, also known as a
   distfile. The extract portion of building a port will automatically save
   the downloaded source to /usr/ports/distfiles.

  4.5.1. Installing Ports

   This section provides basic instructions on using the Ports Collection to
   install or remove software. The detailed description of available make
   targets and environment variables is available in ports(7).

  Warning:

   Before compiling any port, be sure to update the Ports Collection as
   described in the previous section. Since the installation of any
   third-party software can introduce security vulnerabilities, it is
   recommended to first check https://vuxml.freebsd.org/ for known security
   issues related to the port. Alternately, run pkg audit -F before
   installing a new port. This command can be configured to automatically
   perform a security audit and an update of the vulnerability database
   during the daily security system check. For more information, refer to
   pkg-audit(8) and periodic(8).

   Using the Ports Collection assumes a working Internet connection. It also
   requires superuser privilege.

   To compile and install the port, change to the directory of the port to be
   installed, then type make install at the prompt. Messages will indicate
   the progress:

 # cd /usr/ports/sysutils/lsof
 # make install
 >> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
 ===>  Extracting for lsof-4.88
 ...
 [extraction output snipped]
 ...
 >> Checksum OK for lsof_4.88D.freebsd.tar.gz.
 ===>  Patching for lsof-4.88.d,8
 ===>  Applying FreeBSD patches for lsof-4.88.d,8
 ===>  Configuring for lsof-4.88.d,8
 ...
 [configure output snipped]
 ...
 ===>  Building for lsof-4.88.d,8
 ...
 [compilation output snipped]
 ...

 ===>  Installing for lsof-4.88.d,8
 ...
 [installation output snipped]
 ...
 ===>   Generating temporary packing list
 ===>   Compressing manual pages for lsof-4.88.d,8
 ===>   Registering installation for lsof-4.88.d,8
 ===>  SECURITY NOTE:
       This port has installed the following binaries which execute with
       increased privileges.
 /usr/local/sbin/lsof
 #

   Since lsof is a program that runs with increased privileges, a security
   warning is displayed as it is installed. Once the installation is
   complete, the prompt will be returned.

   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. Users of the tcsh
   shell should type rehash so that a newly installed command can be used
   without specifying its full path. Use hash -r instead for the sh shell.
   Refer to the documentation for the shell for more information.

   During installation, a working subdirectory is created which contains all
   the temporary files used during compilation. Removing this directory saves
   disk space and minimizes the chance of problems later when upgrading to
   the newer version of the port:

 # make clean
 ===>  Cleaning for lsof-88.d,8
 #

  Note:

   To save this extra step, instead use make install clean when compiling the
   port.

    4.5.1.1. Customizing Ports Installation

   Some ports provide build options which can be used to enable or disable
   application components, provide security options, or allow for other
   customizations. Examples include www/firefox, security/gpgme, and
   mail/sylpheed-claws. If the port depends upon other ports which have
   configurable options, it may pause several times for user interaction as
   the default behavior is to prompt the user to select options from a menu.
   To avoid this and do all of the configuration in one batch, run make
   config-recursive within the port skeleton. Then, run make install [clean]
   to compile and install the port.

  Tip:

   When using config-recursive, the list of ports to configure are gathered
   by the all-depends-list target. It is recommended to run make
   config-recursive until all dependent ports options have been defined, and
   ports options screens no longer appear, to be certain that all dependency
   options have been configured.

   There are several ways to revisit a port's build options menu in order to
   add, remove, or change these options after a port has been built. One
   method is to cd into the directory containing the port and type make
   config. Another option is to use make showconfig. Another option is to
   execute make rmconfig which will remove all selected options and allow you
   to start over. All of these options, and others, are explained in great
   detail in ports(7).

   The ports system uses fetch(1) to download the source files, which
   supports various environment variables. The FTP_PASSIVE_MODE, FTP_PROXY,
   and FTP_PASSWORD variables may need to be set if the FreeBSD system is
   behind a firewall or FTP/HTTP proxy. See fetch(3) for the complete list of
   supported variables.

   For users who cannot be connected to the Internet all the time, make fetch
   can be run within /usr/ports, to fetch all distfiles, or within a
   category, such as /usr/ports/net, or within the specific port skeleton.
   Note that if a port has any dependencies, running this command in a
   category or ports skeleton will not fetch the distfiles of ports from
   another category. Instead, use make fetch-recursive to also fetch the
   distfiles for all the dependencies of a port.

   In rare cases, such as when an organization has a local distfiles
   repository, the MASTER_SITES variable can be used to override the download
   locations specified in the Makefile. When using, specify the alternate
   location:

 # cd /usr/ports/directory
 # make MASTER_SITE_OVERRIDE= \
 ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch

   The WRKDIRPREFIX and PREFIX variables can override the default working and
   target directories. For example:

 # make WRKDIRPREFIX=/usr/home/example/ports install

   will compile the port in /usr/home/example/ports and install everything
   under /usr/local.

 # make PREFIX=/usr/home/example/local install

   will compile the port in /usr/ports and install it in
   /usr/home/example/local. And:

 # make WRKDIRPREFIX=../ports PREFIX=../local install

   will combine the two.

   These can also be set as environmental variables. Refer to the manual page
   for your shell for instructions on how to set an environmental variable.

  4.5.2. Removing Installed Ports

   Installed ports can be uninstalled using pkg delete. Examples for using
   this command can be found in the pkg-delete(8) manual page.

   Alternately, make deinstall can be run in the port's directory:

 # cd /usr/ports/sysutils/lsof
 make deinstall
 ===>  Deinstalling for sysutils/lsof
 ===>   Deinstalling
 Deinstallation has been requested for the following 1 packages:

         lsof-4.88.d,8

 The deinstallation will free 229 kB
 [1/1] Deleting lsof-4.88.d,8... done

   It is recommended to read the messages as the port is uninstalled. If the
   port has any applications that depend upon it, this information will be
   displayed but the uninstallation will proceed. In such cases, it may be
   better to reinstall the application in order to prevent broken
   dependencies.

  4.5.3. Upgrading Ports

   Over time, newer versions of software become available in the Ports
   Collection. This section describes how to determine which software can be
   upgraded and how to perform the upgrade.

   To determine if newer versions of installed ports are available, ensure
   that the latest version of the ports tree is installed, using the updating
   command described in either Procedure 4.1, "Portsnap Method" or
   Procedure 4.2, "Subversion Method". On FreeBSD 10 and later, or if the
   system has been converted to pkg, the following command will list the
   installed ports which are out of date:

 # pkg version -l "<"

   For FreeBSD 9.X and lower, the following command will list the installed
   ports that are out of date:

 # pkg_version -l "<"

  Important:

   Before attempting an upgrade, read /usr/ports/UPDATING from the top of the
   file to the date closest to the last time ports were upgraded or the
   system was installed. This file describes various issues and additional
   steps users may encounter and need to perform when updating a port,
   including such things as file format changes, changes in locations of
   configuration files, or any incompatibilities with previous versions. Make
   note of any instructions which match any of the ports that need upgrading
   and follow these instructions when performing the upgrade.

    4.5.3.1. Tools to Upgrade and Manage Ports

   The Ports Collection contains several utilities to perform the actual
   upgrade. Each has its strengths and weaknesses.

   Historically, most installations used either Portmaster or Portupgrade.
   Synth is a newer alternative.

  Note:

   The choice of which tool is best for a particular system is up to the
   system administrator. It is recommended practice to back up your data
   before using any of these tools.

    4.5.3.2. Upgrading Ports Using Portmaster

   ports-mgmt/portmaster is a very small utility for upgrading installed
   ports. It is designed to use the tools installed with the FreeBSD base
   system without depending on other ports or databases. To install this
   utility as a port:

 # cd /usr/ports/ports-mgmt/portmaster
 # make install clean

   Portmaster defines four categories of ports:

     * Root port: has no dependencies and is not a dependency of any other
       ports.

     * Trunk port: has no dependencies, but other ports depend upon it.

     * Branch port: has dependencies and other ports depend upon it.

     * Leaf port: has dependencies but no other ports depend upon it.

   To list these categories and search for updates:

 # portmaster -L
 ===>>> Root ports (No dependencies, not depended on)
 ===>>> ispell-3.2.06_18
 ===>>> screen-4.0.3
         ===>>> New version available: screen-4.0.3_1
 ===>>> tcpflow-0.21_1
 ===>>> 7 root ports
 ...
 ===>>> Branch ports (Have dependencies, are depended on)
 ===>>> apache22-2.2.3
         ===>>> New version available: apache22-2.2.8
 ...
 ===>>> Leaf ports (Have dependencies, not depended on)
 ===>>> automake-1.9.6_2
 ===>>> bash-3.1.17
         ===>>> New version available: bash-3.2.33
 ...
 ===>>> 32 leaf ports

 ===>>> 137 total installed ports
         ===>>> 83 have new versions available

   This command is used to upgrade all outdated ports:

 # portmaster -a

  Note:

   By default, Portmaster makes a backup package before deleting the existing
   port. If the installation of the new version is successful, Portmaster
   deletes the backup. Using -b instructs Portmaster not to automatically
   delete the backup. Adding -i starts Portmaster in interactive mode,
   prompting for confirmation before upgrading each port. Many other options
   are available. Read through the manual page for portmaster(8) for details
   regarding their usage.

   If errors are encountered during the upgrade process, add -f to upgrade
   and rebuild all ports:

 # portmaster -af

   Portmaster can also be used to install new ports on the system, upgrading
   all dependencies before building and installing the new port. To use this
   function, specify the location of the port in the Ports Collection:

 # portmaster shells/bash

   More information about ports-mgmt/portmaster may be found in its
   pkg-descr.

    4.5.3.3. Upgrading Ports Using Portupgrade

   ports-mgmt/portupgrade is another utility that can be used to upgrade
   ports. It installs a suite of applications which can be used to manage
   ports. However, it is dependent upon Ruby. To install the port:

 # cd /usr/ports/ports-mgmt/portupgrade
 # make install clean

   Before performing an upgrade using this utility, it is recommended to scan
   the list of installed ports using pkgdb -F and to fix all the
   inconsistencies it reports.

   To upgrade all the outdated ports installed on the system, use portupgrade
   -a. Alternately, include -i to be asked for confirmation of every
   individual upgrade:

 # portupgrade -ai

   To upgrade only a specified application instead of all available ports,
   use portupgrade pkgname. It is very important to include -R to first
   upgrade all the ports required by the given application:

 # portupgrade -R firefox

   If -P is included, Portupgrade searches for available packages in the
   local directories listed in PKG_PATH. If none are available locally, it
   then fetches packages from a remote site. If packages can not be found
   locally or fetched remotely, Portupgrade will use ports. To avoid using
   ports entirely, specify -PP. This last set of options tells Portupgrade to
   abort if no packages are available:

 # portupgrade -PP gnome3

   To just fetch the port distfiles, or packages, if -P is specified, without
   building or installing anything, use -F. For further information on all of
   the available switches, refer to the manual page for portupgrade.

   More information about ports-mgmt/portupgrade may be found in its
   pkg-descr.

  4.5.4. Ports and Disk Space

   Using the Ports Collection will use up disk space over time. After
   building and installing a port, running make clean within the ports
   skeleton will clean up the temporary work directory. If Portmaster is used
   to install a port, it will automatically remove this directory unless -K
   is specified. If Portupgrade is installed, this command will remove all
   work directories found within the local copy of the Ports Collection:

 # portsclean -C

   In addition, outdated source distribution files accumulate in
   /usr/ports/distfiles over time. To use Portupgrade to delete all the
   distfiles that are no longer referenced by any ports:

 # portsclean -D

   Portupgrade can remove all distfiles not referenced by any port currently
   installed on the system:

 # portsclean -DD

   If Portmaster is installed, use:

 # portmaster --clean-distfiles

   By default, this command is interactive and prompts the user to confirm if
   a distfile should be deleted.

   In addition to these commands, ports-mgmt/pkg_cutleaves automates the task
   of removing installed ports that are no longer needed.

4.6. Building Packages with Poudriere

   Poudriere is a BSD-licensed utility for creating and testing FreeBSD
   packages. It uses FreeBSD jails to set up isolated compilation
   environments. These jails can be used to build packages for versions of
   FreeBSD that are different from the system on which it is installed, and
   also to build packages for i386 if the host is an amd64 system. Once the
   packages are built, they are in a layout identical to the official
   mirrors. These packages are usable by pkg(8) and other package management
   tools.

   Poudriere is installed using the ports-mgmt/poudriere package or port. The
   installation includes a sample configuration file
   /usr/local/etc/poudriere.conf.sample. Copy this file to
   /usr/local/etc/poudriere.conf. Edit the copied file to suit the local
   configuration.

   While ZFS is not required on the system running poudriere, it is
   beneficial. When ZFS is used, ZPOOL must be specified in
   /usr/local/etc/poudriere.conf and FREEBSD_HOST should be set to a nearby
   mirror. Defining CCACHE_DIR enables the use of devel/ccache to cache
   compilation and reduce build times for frequently-compiled code. It may be
   convenient to put poudriere datasets in an isolated tree mounted at
   /poudriere. Defaults for the other configuration values are adequate.

   The number of processor cores detected is used to define how many builds
   will run in parallel. Supply enough virtual memory, either with RAM or
   swap space. If virtual memory runs out, the compilation jails will stop
   and be torn down, resulting in weird error messages.

  4.6.1. Initialize Jails and Port Trees

   After configuration, initialize poudriere so that it installs a jail with
   the required FreeBSD tree and a ports tree. Specify a name for the jail
   using -j and the FreeBSD version with -v. On systems running
   FreeBSD/amd64, the architecture can be set with -a to either i386 or
   amd64. The default is the architecture shown by uname.

 # poudriere jail -c -j 10amd64 -v 10.0-RELEASE
 ====>> Creating 10amd64 fs... done
 ====>> Fetching base.txz for FreeBSD 10.0-RELEASE amd64
 /poudriere/jails/10amd64/fromftp/base.txz      100% of   59 MB 1470 kBps 00m42s
 ====>> Extracting base.txz... done
 ====>> Fetching src.txz for FreeBSD 10.0-RELEASE amd64
 /poudriere/jails/10amd64/fromftp/src.txz       100% of  107 MB 1476 kBps 01m14s
 ====>> Extracting src.txz... done
 ====>> Fetching games.txz for FreeBSD 10.0-RELEASE amd64
 /poudriere/jails/10amd64/fromftp/games.txz     100% of  865 kB  734 kBps 00m01s
 ====>> Extracting games.txz... done
 ====>> Fetching lib32.txz for FreeBSD 10.0-RELEASE amd64
 /poudriere/jails/10amd64/fromftp/lib32.txz     100% of   14 MB 1316 kBps 00m12s
 ====>> Extracting lib32.txz... done
 ====>> Cleaning up... done
 ====>> Jail 10amd64 10.0-RELEASE amd64 is ready to be used

 # poudriere ports -c -p local
 ====>> Creating local fs... done
 ====>> Extracting portstree "local"...
 Looking up portsnap.FreeBSD.org mirrors... 7 mirrors found.
 Fetching public key from ec2-eu-west-1.portsnap.freebsd.org... done.
 Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
 Fetching snapshot metadata... done.
 Fetching snapshot generated at Tue Feb 11 01:07:15 CET 2014:
 94a3431f0ce567f6452ffde4fd3d7d3c6e1da143efec76100% of   69 MB 1246 kBps 00m57s
 Extracting snapshot... done.
 Verifying snapshot integrity... done.
 Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done.
 Fetching snapshot metadata... done.
 Updating from Tue Feb 11 01:07:15 CET 2014 to Tue Feb 11 16:05:20 CET 2014.
 Fetching 4 metadata patches... done.
 Applying metadata patches... done.
 Fetching 0 metadata files... done.
 Fetching 48 patches.
 (48/48) 100.00%  done.
 done.
 Applying patches...
 done.
 Fetching 1 new ports or files... done.
 /poudriere/ports/tester/CHANGES
 /poudriere/ports/tester/COPYRIGHT

 [...]

 Building new INDEX files... done.

   On a single computer, poudriere can build ports with multiple
   configurations, in multiple jails, and from different port trees. Custom
   configurations for these combinations are called sets. See the
   CUSTOMIZATION section of poudriere(8) for details after
   ports-mgmt/poudriere or ports-mgmt/poudriere-devel is installed.

   The basic configuration shown here puts a single jail-, port-, and
   set-specific make.conf in /usr/local/etc/poudriere.d. The filename in this
   example is created by combining the jail name, port name, and set name:
   10amd64-local-workstation-make.conf. The system make.conf and this new
   file are combined at build time to create the make.conf used by the build
   jail.

   Packages to be built are entered in 10amd64-local-workstation-pkglist:

 editors/emacs
 devel/git
 ports-mgmt/pkg
 ...

   Options and dependencies for the specified ports are configured:

 # poudriere options -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist

   Finally, packages are built and a package repository is created:

 # poudriere bulk -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist

   While running, pressing Ctrl+t displays the current state of the build.
   Poudriere also builds files in /poudriere/logs/bulk/jailname that can be
   used with a web server to display build information.

   After completion, the new packages are now available for installation from
   the poudriere repository.

   For more information on using poudriere, see poudriere(8) and the main web
   site, https://github.com/freebsd/poudriere/wiki.

  4.6.2. Configuring pkg Clients to Use a Poudriere Repository

   While it is possible to use both a custom repository along side of the
   official repository, sometimes it is useful to disable the official
   repository. This is done by creating a configuration file that overrides
   and disables the official configuration file. Create
   /usr/local/etc/pkg/repos/FreeBSD.conf that contains the following:

 FreeBSD: {
         enabled: no
 }

   Usually it is easiest to serve a poudriere repository to the client
   machines via HTTP. Set up a webserver to serve up the package directory,
   for instance: /usr/local/poudriere/data/packages/10amd64, where 10amd64 is
   the name of the build.

   If the URL to the package repository is: http://pkg.example.com/10amd64,
   then the repository configuration file in
   /usr/local/etc/pkg/repos/custom.conf would look like:

 custom: {
         url: "http://pkg.example.com/10amd64",
         enabled: yes,
 }

4.7. Post-Installation Considerations

   Regardless of whether the software was installed from a binary package or
   port, most third-party applications require some level of configuration
   after installation. The following commands and locations can be used to
   help determine what was installed with the application.

     * Most applications install at least one default configuration file in
       /usr/local/etc. In cases where an application has a large number of
       configuration files, a subdirectory will be created to hold them.
       Often, sample configuration files are installed which end with a
       suffix such as .sample. The configuration files should be reviewed and
       possibly edited to meet the system's needs. To edit a sample file,
       first copy it without the .sample extension.

     * Applications which provide documentation will install it into
       /usr/local/share/doc and many applications also install manual pages.
       This documentation should be consulted before continuing.

     * Some applications run services which must be added to /etc/rc.conf
       before starting the application. These applications usually install a
       startup script in /usr/local/etc/rc.d. See Starting Services for more
       information.

  Note:

       By design, applications do not run their startup script upon
       installation, nor do they run their stop script upon deinstallation or
       upgrade. This decision is left to the individual system administrator.

     * Users of csh(1) should run rehash to rebuild the known binary list in
       the shells PATH.

     * Use pkg info to determine which files, man pages, and binaries were
       installed with the application.

4.8. Dealing with Broken Ports

   When a port does not build or install, try the following:

    1. Search to see if there is a fix pending for the port in the Problem
       Report database. If so, implementing the proposed fix may fix the
       issue.

    2. Ask the maintainer of the port for help. Type make maintainer in the
       ports skeleton or read the port's Makefile to find the maintainer's
       email address. Remember to include the $FreeBSD: line from the port's
       Makefile and the output leading up to the error in the email to the
       maintainer.

  Note:

       Some ports are not maintained by an individual but instead by a group
       maintainer represented by a mailing list. Many, but not all, of these
       addresses look like . Please take this
       into account when sending an email.

       In particular, ports maintained by  are not
       maintained by a specific individual. Instead, any fixes and support
       come from the general community who subscribe to that mailing list.
       More volunteers are always needed!

       If there is no response to the email, use Bugzilla to submit a bug
       report using the instructions in Writing FreeBSD Problem Reports.

    3. Fix it! The Porter's Handbook includes detailed information on the
       ports infrastructure so that you can fix the occasional broken port or
       even submit your own!

    4. Install the package instead of the port using the instructions in
       Section 4.4, "Using pkg for Binary Package Management".

Chapter 5. The X Window System

   Table of Contents

   5.1. Synopsis

   5.2. Terminology

   5.3. Installing Xorg

   5.4. Xorg Configuration

   5.5. Using Fonts in Xorg

   5.6. The X Display Manager

   5.7. Desktop Environments

   5.8. Installing Compiz Fusion

   5.9. Troubleshooting

5.1. Synopsis

   An installation of FreeBSD using bsdinstall does not automatically install
   a graphical user interface. This chapter describes how to install and
   configure Xorg, which provides the open source X Window System used to
   provide a graphical environment. It then describes how to find and install
   a desktop environment or window manager.

  Note:

   Users who prefer an installation method that automatically configures the
   Xorg and offers a choice of window managers during installation should
   refer to the http://www.trueos.org/ website.

   For more information on the video hardware that Xorg supports, refer to
   the x.org website.

   After reading this chapter, you will know:

     * The various components of the X Window System, and how they
       interoperate.

     * How to install and configure Xorg.

     * How to install and configure several window managers and desktop
       environments.

     * How to use TrueType(R) fonts in Xorg.

     * How to set up your system for graphical logins (XDM).

   Before reading this chapter, you should:

     * Know how to install additional third-party software as described in
       Chapter 4, Installing Applications: Packages and Ports.

5.2. Terminology

   While it is not necessary to understand all of the details of the various
   components in the X Window System and how they interact, some basic
   knowledge of these components can be useful.

   X server

           X was designed from the beginning to be network-centric, and
           adopts a "client-server" model. In this 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 handling input or output from other devices such as a tablet
           or a video projector. 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.

   X client

           Each X application, such as XTerm or Firefox, 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. It is also possible to
           run the X server on a less powerful computer and to run the X
           applications on a more powerful system. In this scenario, the
           communication between the X client and server takes place over the
           network.

   window manager

           X does not dictate what windows should look like on-screen, how to
           move them around with the mouse, which keystrokes should be used
           to move between 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 a separate window
           manager application. There are dozens of window managers
           available. Each window manager provides a different look and feel:
           some support virtual desktops, some allow customized keystrokes to
           manage the desktop, some have a "Start" button, and some are
           themeable, allowing a complete change of the desktop's
           look-and-feel. Window managers are available in the x11-wm
           category of the Ports Collection.

           Each window manager uses a different configuration mechanism. Some
           expect configuration file written by hand while others provide
           graphical tools for most configuration tasks.

   desktop environment

           KDE and GNOME are considered to be desktop environments as they
           include an entire suite of applications for performing common
           desktop tasks. These may include office suites, web browsers, and
           games.

   focus policy

           The window manager is responsible for the mouse focus policy. This
           policy provides some means for choosing which window is actively
           receiving keystrokes and it should also visibly indicate which
           window is currently active.

           One focus policy is called "click-to-focus". In this model, a
           window becomes active upon receiving a mouse click. In the
           "focus-follows-mouse" policy, the window that is under the mouse
           pointer has focus and the focus is changed by pointing at another
           window. If the mouse is over the root window, then this window is
           focused. In the "sloppy-focus" model, if the mouse is moved over
           the root window, the most recently used window still has the
           focus. With sloppy-focus, focus is only changed when the cursor
           enters a new window, and not when exiting the current window. In
           the "click-to-focus" policy, 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.

           Different window managers support different focus models. All of
           them support click-to-focus, and the majority of them also support
           other policies. Consult the documentation for the window manager
           to determine which focus models are available.

   widgets

           Widget is a term for all of the items in the user interface that
           can be clicked or manipulated in some way. This includes buttons,
           check boxes, radio buttons, icons, and lists. A widget toolkit is
           a set of widgets used to create graphical applications. There are
           several popular widget toolkits, including Qt, used by KDE, and
           GTK+, used by GNOME. As a result, applications will have a
           different look and feel, depending upon which widget toolkit was
           used to create the application.

5.3. Installing Xorg

   On FreeBSD, Xorg can be installed as a package or port.

   The binary package can be installed quickly but with fewer options for
   customization:

 # pkg install xorg

   To build and install from the Ports Collection:

 # cd /usr/ports/x11/xorg
 # make install clean

   Either of these installations results in the complete Xorg system being
   installed. Binary packages are the best option for most users.

   A smaller version of the X system suitable for experienced users is
   available in x11/xorg-minimal. Most of the documents, libraries, and
   applications will not be installed. Some applications require these
   additional components to function.

5.4. Xorg Configuration

   Warren Block

  5.4.1. Quick Start

   Xorg supports most common video cards, keyboards, and pointing devices.

  Tip:

   Video cards, monitors, and input devices are automatically detected and do
   not require any manual configuration. Do not create xorg.conf or run a
   -configure step unless automatic configuration fails.

    1. If Xorg has been used on this computer before, move or remove any
       existing configuration files:

 # mv /etc/X11/xorg.conf ~/xorg.conf.etc
 # mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc

    2. Add the user who will run Xorg to the video or wheel group to enable
       3D acceleration when available. To add user jru to whichever group is
       available:

 # pw groupmod video -m jru || pw groupmod wheel -m jru

    3. The TWM window manager is included by default. It is started when Xorg
       starts:

 % startx

    4. On some older versions of FreeBSD, the system console must be set to
       vt(4) before switching back to the text console will work properly.
       See Section 5.4.3, "Kernel Mode Setting (KMS)".

  5.4.2. User Group for Accelerated Video

   Access to /dev/dri is needed to allow 3D acceleration on video cards. It
   is usually simplest to add the user who will be running X to either the
   video or wheel group. Here, pw(8) is used to add user slurms to the video
   group, or to the wheel group if there is no video group:

 # pw groupmod video -m slurms || pw groupmod wheel -m slurms

  5.4.3. Kernel Mode Setting (KMS)

   When the computer switches from displaying the console to a higher screen
   resolution for X, it must set the video output mode. Recent versions of
   Xorg use a system inside the kernel to do these mode changes more
   efficiently. Older versions of FreeBSD use sc(4), which is not aware of
   the KMS system. The end result is that after closing X, the system console
   is blank, even though it is still working. The newer vt(4) console avoids
   this problem.

   Add this line to /boot/loader.conf to enable vt(4):

 kern.vty=vt

  5.4.4. Configuration Files

   Manual configuration is usually not necessary. Please do not manually
   create configuration files unless autoconfiguration does not work.

    5.4.4.1. Directory

   Xorg looks in several directories for configuration files.
   /usr/local/etc/X11/ is the recommended directory for these files on
   FreeBSD. Using this directory helps keep application files separate from
   operating system files.

   Storing configuration files in the legacy /etc/X11/ still works. However,
   this mixes application files with the base FreeBSD files and is not
   recommended.

    5.4.4.2. Single or Multiple Files

   It is easier to use multiple files that each configure a specific setting
   than the traditional single xorg.conf. These files are stored in the
   xorg.conf.d/ subdirectory of the main configuration file directory. The
   full path is typically /usr/local/etc/X11/xorg.conf.d/.

   Examples of these files are shown later in this section.

   The traditional single xorg.conf still works, but is neither as clear nor
   as flexible as multiple files in the xorg.conf.d/ subdirectory.

  5.4.5. Video Cards

   Because of changes made in recent versions of FreeBSD, it is now possible
   to use graphics drivers provided by the Ports framework or as packages. As
   such, users can use one of the following drivers available from
   graphics/drm-kmod.

   Intel KMS driver, Radeon KMS driver, AMD KMS driver

           2D and 3D acceleration is supported on most Intel KMS driver
           graphics cards provided by Intel.

           Driver name: i915kms

           2D and 3D acceleration is supported on most older Radeon KMS
           driver graphics cards provided by AMD.

           Driver name: radeonkms

           2D and 3D acceleration is supported on most newer AMD KMS driver
           graphics cards provided by AMD.

           Driver name: amdgpu

           For reference, please see
           https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units
           or
           https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units
           for a list of supported GPUs.

   Intel(R)

           3D acceleration is supported on most Intel(R) graphics up to Ivy
           Bridge (HD Graphics 2500, 4000, and P4000), including Iron Lake
           (HD Graphics) and Sandy Bridge (HD Graphics 2000).

           Driver name: intel

           For reference, see
           https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units.

   AMD(R) Radeon

           2D and 3D acceleration is supported on Radeon cards up to and
           including the HD6000 series.

           Driver name: radeon

           For reference, see
           https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units.

   NVIDIA

           Several NVIDIA drivers are available in the x11 category of the
           Ports Collection. Install the driver that matches the video card.

           For reference, see
           https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units.

   Hybrid Combination Graphics

           Some notebook computers add additional graphics processing units
           to those built into the chipset or processor. Optimus combines
           Intel(R) and NVIDIA hardware. Switchable Graphics or Hybrid
           Graphics are a combination of an Intel(R) or AMD(R) processor and
           an AMD(R) Radeon GPU.

           Implementations of these hybrid graphics systems vary, and Xorg on
           FreeBSD is not able to drive all versions of them.

           Some computers provide a BIOS option to disable one of the
           graphics adapters or select a discrete mode which can be used with
           one of the standard video card drivers. For example, it is
           sometimes possible to disable the NVIDIA GPU in an Optimus system.
           The Intel(R) video can then be used with an Intel(R) driver.

           BIOS settings depend on the model of computer. In some situations,
           both GPUs can be left enabled, but creating a configuration file
           that only uses the main GPU in the Device section is enough to
           make such a system functional.

   Other Video Cards

           Drivers for some less-common video cards can be found in the
           x11-drivers directory of the Ports Collection.

           Cards that are not supported by a specific driver might still be
           usable with the x11-drivers/xf86-video-vesa driver. This driver is
           installed by x11/xorg. It can also be installed manually as
           x11-drivers/xf86-video-vesa. Xorg attempts to use this driver when
           a specific driver is not found for the video card.

           x11-drivers/xf86-video-scfb is a similar nonspecialized video
           driver that works on many UEFI and ARM(R) computers.

   Setting the Video Driver in a File

           To set the Intel(R) driver in a configuration file:

           Example 5.1. Select Intel(R) Video Driver in a File

           /usr/local/etc/X11/xorg.conf.d/driver-intel.conf

 Section "Device"
         Identifier "Card0"
         Driver     "intel"
         # BusID    "PCI:1:0:0"
 EndSection

           If more than one video card is present, the BusID identifier can
           be uncommented and set to select the desired card. A list of video
           card bus IDs can be displayed with pciconf -lv | grep -B3 display.

           To set the Radeon driver in a configuration file:

           Example 5.2. Select Radeon Video Driver in a File

           /usr/local/etc/X11/xorg.conf.d/driver-radeon.conf

 Section "Device"
         Identifier "Card0"
         Driver     "radeon"
 EndSection

           To set the VESA driver in a configuration file:

           Example 5.3. Select VESA Video Driver in a File

           /usr/local/etc/X11/xorg.conf.d/driver-vesa.conf

 Section "Device"
         Identifier "Card0"
         Driver     "vesa"
 EndSection

           To set the scfb driver for use with a UEFI or ARM(R) computer:

           Example 5.4. Select scfb Video Driver in a File

           /usr/local/etc/X11/xorg.conf.d/driver-scfb.conf

 Section "Device"
         Identifier "Card0"
         Driver     "scfb"
 EndSection

  5.4.6. Monitors

   Almost all monitors support the Extended Display Identification Data
   standard (EDID). Xorg uses EDID to communicate with the monitor and detect
   the supported resolutions and refresh rates. Then it selects the most
   appropriate combination of settings to use with that monitor.

   Other resolutions supported by the monitor can be chosen by setting the
   desired resolution in configuration files, or after the X server has been
   started with xrandr(1).

   Using xrandr(1)

           Run xrandr(1) without any parameters to see a list of video
           outputs and detected monitor modes:

 % xrandr
 Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192
 DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm
    1920x1200     59.95*+
    1600x1200     60.00
    1280x1024     85.02    75.02    60.02
    1280x960      60.00
    1152x864      75.00
    1024x768      85.00    75.08    70.07    60.00
    832x624       74.55
    800x600       75.00    60.32
    640x480       75.00    60.00
    720x400       70.08
 DisplayPort-0 disconnected (normal left inverted right x axis y axis)
 HDMI-0 disconnected (normal left inverted right x axis y axis)

           This shows that the DVI-0 output is being used to display a screen
           resolution of 1920x1200 pixels at a refresh rate of about 60 Hz.
           Monitors are not attached to the DisplayPort-0 and HDMI-0
           connectors.

           Any of the other display modes can be selected with xrandr(1). For
           example, to switch to 1280x1024 at 60 Hz:

 % xrandr --mode 1280x1024 --rate 60

           A common task is using the external video output on a notebook
           computer for a video projector.

           The type and quantity of output connectors varies between devices,
           and the name given to each output varies from driver to driver.
           What one driver calls HDMI-1, another might call HDMI1. So the
           first step is to run xrandr(1) to list all the available outputs:

 % xrandr
 Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192
 LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm
    1366x768      60.04*+
    1024x768      60.00
    800x600       60.32    56.25
    640x480       59.94
 VGA1 connected (normal left inverted right x axis y axis)
    1280x1024     60.02 +  75.02
    1280x960      60.00
    1152x864      75.00
    1024x768      75.08    70.07    60.00
    832x624       74.55
    800x600       72.19    75.00    60.32    56.25
    640x480       75.00    72.81    66.67    60.00
    720x400       70.08
 HDMI1 disconnected (normal left inverted right x axis y axis)
 DP1 disconnected (normal left inverted right x axis y axis)

           Four outputs were found: the built-in panel LVDS1, and external
           VGA1, HDMI1, and DP1 connectors.

           The projector has been connected to the VGA1 output. xrandr(1) is
           now used to set that output to the native resolution of the
           projector and add the additional space to the right side of the
           desktop:

 % xrandr --output VGA1 --auto --right-of LVDS1

           --auto chooses the resolution and refresh rate detected by EDID.
           If the resolution is not correctly detected, a fixed value can be
           given with --mode instead of the --auto statement. For example,
           most projectors can be used with a 1024x768 resolution, which is
           set with --mode 1024x768.

           xrandr(1) is often run from .xinitrc to set the appropriate mode
           when X starts.

   Setting Monitor Resolution in a File

           To set a screen resolution of 1024x768 in a configuration file:

           Example 5.5. Set Screen Resolution in a File

           /usr/local/etc/X11/xorg.conf.d/screen-resolution.conf

 Section "Screen"
         Identifier "Screen0"
         Device     "Card0"
         SubSection "Display"
         Modes      "1024x768"
         EndSubSection
 EndSection

           The few monitors that do not have EDID can be configured by
           setting HorizSync and VertRefresh to the range of frequencies
           supported by the monitor.

           Example 5.6. Manually Setting Monitor Frequencies

           /usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf

 Section "Monitor"
         Identifier   "Monitor0"
         HorizSync    30-83   # kHz
         VertRefresh  50-76   # Hz
 EndSection

  5.4.7. Input Devices

    5.4.7.1. Keyboards

   Keyboard Layout

           The standardized location of keys on a keyboard is called a
           layout. Layouts and other adjustable parameters are listed in
           xkeyboard-config(7).

           A United States layout is the default. To select an alternate
           layout, set the XkbLayout and XkbVariant options in an InputClass.
           This will be applied to all input devices that match the class.

           This example selects a French keyboard layout with the oss
           variant.

           Example 5.7. Setting a Keyboard Layout

           /usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf

 Section "InputClass"
         Identifier      "KeyboardDefaults"
         Driver          "keyboard"
         MatchIsKeyboard "on"
         Option          "XkbLayout" "fr"
         Option          "XkbVariant" "oss"
 EndSection

           Example 5.8. Setting Multiple Keyboard Layouts

           Set United States, Spanish, and Ukrainian keyboard layouts. Cycle
           through these layouts by pressing Alt+Shift. x11/xxkb or x11/sbxkb
           can be used for improved layout switching control and current
           layout indicators.

           /usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf

 Section "InputClass"
         Identifier      "All Keyboards"
         MatchIsKeyboard "yes"
         Option          "XkbLayout" "us, es, ua"
 EndSection

   Closing Xorg From the Keyboard

           X can be closed with a combination of keys. By default, that key
           combination is not set because it conflicts with keyboard commands
           for some applications. Enabling this option requires changes to
           the keyboard InputDevice section:

           Example 5.9. Enabling Keyboard Exit from X

           /usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf

 Section "InputClass"
         Identifier      "KeyboardDefaults"
         Driver          "keyboard"
         MatchIsKeyboard "on"
         Option          "XkbOptions" "terminate:ctrl_alt_bksp"
 EndSection

    5.4.7.2. Mice and Pointing Devices

   Many mouse parameters can be adjusted with configuration options. See
   mousedrv(4) for a full list.

   Mouse Buttons

           The number of buttons on a mouse can be set in the mouse
           InputDevice section of xorg.conf. To set the number of buttons to
           7:

           Example 5.10. Setting the Number of Mouse Buttons

           /usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf

 Section "InputDevice"
         Identifier  "Mouse0"
         Option      "Buttons" "7"
 EndSection

  5.4.8. Manual Configuration

   In some cases, Xorg autoconfiguration does not work with particular
   hardware, or a different configuration is desired. For these cases, a
   custom configuration file can be created.

  Warning:

   Do not create manual configuration files unless required. Unnecessary
   manual configuration can prevent proper operation.

   A configuration file can be generated by Xorg based on the detected
   hardware. This file is often a useful starting point for custom
   configurations.

   Generating an xorg.conf:

 # Xorg -configure

   The configuration file is saved to /root/xorg.conf.new. Make any changes
   desired, then test that file with:

 # Xorg -config /root/xorg.conf.new

   After the new configuration has been adjusted and tested, it can be split
   into smaller files in the normal location,
   /usr/local/etc/X11/xorg.conf.d/.

5.5. Using Fonts in Xorg

  5.5.1. Type1 Fonts

   The default fonts that ship with Xorg are less than ideal for typical
   desktop publishing applications. Large presentation fonts show up jagged
   and unprofessional looking, and small fonts are almost completely
   unintelligible. However, there are several free, high quality Type1
   (PostScript(R)) fonts available which can be readily used with Xorg. For
   instance, the URW font collection (x11-fonts/urwfonts) includes high
   quality versions of standard type1 fonts (Times Roman(R), Helvetica(R),
   Palatino(R) and others). The Freefonts collection (x11-fonts/freefonts)
   includes many more 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, Xorg can be configured to use TrueType(R)
   fonts with a minimum of effort. For more details on this, see the X(7)
   manual page or Section 5.5.2, "TrueType(R) Fonts".

   To install the above Type1 font collections from binary packages, run the
   following commands:

 # pkg install urwfonts

   Alternatively, to build from the Ports Collection, run the following
   commands:

 # cd /usr/ports/x11-fonts/urwfonts
 # make install clean

   And likewise with the freefont or other collections. To have the X server
   detect these fonts, add an appropriate line to the X server configuration
   file (/etc/X11/xorg.conf), which reads:

 FontPath "/usr/local/share/fonts/urwfonts/"

   Alternatively, at the command line in the X session run:

 % xset fp+ /usr/local/share/fonts/urwfonts
 % 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/local/etc/fonts/local.conf as
   demonstrated in Section 5.5.3, "Anti-Aliased Fonts".

  5.5.2. TrueType(R) Fonts

   Xorg has built in support for rendering TrueType(R) 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 /etc/X11/xorg.conf.

 Load  "freetype"

   Now make a directory for the TrueType(R) fonts (for example,
   /usr/local/share/fonts/TrueType) and copy all of the TrueType(R) fonts
   into this directory. Keep in mind that TrueType(R) fonts cannot be
   directly taken from an Apple(R) Mac(R); they must be in
   UNIX(R)/MS-DOS(R)/Windows(R) format for use by Xorg. Once the files have
   been copied into this directory, use mkfontscale to create a fonts.dir, so
   that the X font renderer knows that these new files have been installed.
   mkfontscale can be installed as a package:

 # pkg install mkfontscale

   Then create an index of X font files in a directory:

 # cd /usr/local/share/fonts/TrueType
 # mkfontscale

   Now add the TrueType(R) directory to the font path. This is just the same
   as described in Section 5.5.1, "Type1 Fonts":

 % xset fp+ /usr/local/share/fonts/TrueType
 % xset fp rehash

   or add a FontPath line to xorg.conf.

   Now Gimp, Apache OpenOffice, and all of the other X applications should
   now recognize the installed TrueType(R) fonts. Extremely small fonts (as
   with text in a high resolution display on a web page) and extremely large
   fonts (within StarOffice(TM)) will look much better now.

  5.5.3. Anti-Aliased Fonts

   All fonts in Xorg that are found in /usr/local/share/fonts/ and ~/.fonts/
   are automatically made available for anti-aliasing to Xft-aware
   applications. Most recent applications are Xft-aware, including KDE,
   GNOME, and Firefox.

   To control which fonts are anti-aliased, or to configure anti-aliasing
   properties, create (or edit, if it already exists) the file
   /usr/local/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/local/share/fonts/ as well as
   ~/.fonts/ are already made available to Xft-aware applications. To add
   another directory outside of these two directory trees, add a line like
   this to /usr/local/etc/fonts/local.conf:

 /path/to/my/fonts

   After adding new fonts, and especially new font directories, 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 might also be inappropriate with
   anti-aliasing. This seems to be an issue with KDE, in particular. One
   possible fix is to force the spacing for such fonts to be 100. Add these
   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 to crash. To avoid this, consider
   adding the following to local.conf:

          
              
                  Helvetica
              
              
                  sans-serif
              
                 

   After editing local.conf, make certain to end the file with the
   
 tag. Not doing this will cause changes to be ignored.

   Users can add personalized settings by creating their own
   ~/.config/fontconfig/fonts.conf. This file uses the same XML format
   described above.

   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 local.conf:

          
              
                  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.

5.6. The X Display Manager

   Originally contributed by Seth Kingsley.

   Xorg provides an X Display Manager, XDM, which can be used for login
   session management. XDM provides a graphical interface for choosing which
   display server to connect to and for entering authorization information
   such as a login and password combination.

   This section demonstrates how to configure the X Display Manager on
   FreeBSD. Some desktop environments provide their own graphical login
   manager. Refer to Section 5.7.1, "GNOME" for instructions on how to
   configure the GNOME Display Manager and Section 5.7.2, "KDE" for
   instructions on how to configure the KDE Display Manager.

  5.6.1. Configuring XDM

   To install XDM, use the x11/xdm package or port. Once installed, XDM can
   be configured to run when the machine boots up by editing this entry in
   /etc/ttys:

 ttyv8   "/usr/local/bin/xdm -nodaemon"  xterm   off secure

   Change the off to on and save the edit. The ttyv8 in this entry indicates
   that XDM will run on the ninth virtual terminal.

   The XDM configuration directory is located in /usr/local/etc/X11/xdm. This
   directory contains several files used to change the behavior and
   appearance of XDM, as well as a few scripts and programs used to set up
   the desktop when XDM is running. Table 5.1, "XDM Configuration Files"
   summarizes the function of each of these files. The exact syntax and usage
   of these files is described in xdm(1).

   Table 5.1. XDM Configuration Files

      File                              Description                           
              The protocol for connecting to XDM is called the X Display      
              Manager Connection Protocol (XDMCP) This file is a client       
   Xaccess    authorization ruleset for controlling XDMCP connections from    
              remote machines. By default, this file does not allow any       
              remote clients to connect.                                      
              This file controls the look and feel of the XDM display chooser 
              and login screens. The default configuration is a simple        
   Xresources rectangular login window with the hostname of the machine       
              displayed at the top in a large font and "Login:" and           
              "Password:" prompts below. The format of this file is identical 
              to the app-defaults file described in the Xorg documentation.   
   Xservers   The list of local and remote displays the chooser should        
              provide as login choices.                                       
              Default session script for logins which is run by XDM after a   
   Xsession   user has logged in. This points to a customized session script  
              in ~/.xsession.                                                 
              Script to automatically launch applications before displaying   
              the chooser or login interfaces. There is a script for each     
   Xsetup_*   display being used, named Xsetup_*, where * is the local        
              display number. Typically these scripts run one or two programs 
              in the background such as xconsole.                             
   xdm-config Global configuration for all displays running on this machine.  
              Contains errors generated by the server program. If a display   
   xdm-errors that XDM is trying to start hangs, look at this file for error  
              messages. These messages are also written to the user's         
              ~/.xsession-errors on a per-session basis.                      
   xdm-pid    The running process ID of XDM.                                  

  5.6.2. Configuring Remote Access

   By default, only users on the same system can login using XDM. To enable
   users on other systems to connect to the display server, edit the access
   control rules and enable the connection listener.

   To configure XDM to listen for any remote connection, comment out the
   DisplayManager.requestPort line in /usr/local/etc/X11/xdm/xdm-config by
   putting a ! in front of it:

 ! 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

   Save the edits and restart XDM. To restrict remote access, look at the
   example entries in /usr/local/etc/X11/xdm/Xaccess and refer to xdm(1) for
   further information.

5.7. Desktop Environments

   Contributed by Valentino Vaschetto.

   This section describes how to install three popular desktop environments
   on a FreeBSD system. A desktop environment can range from a simple window
   manager to a complete suite of desktop applications. Over a hundred
   desktop environments are available in the x11-wm category of the Ports
   Collection.

  5.7.1. GNOME

   GNOME is a user-friendly desktop environment. It includes a panel for
   starting applications and displaying status, a desktop, a set of tools and
   applications, and a set of conventions that make it easy for applications
   to cooperate and be consistent with each other. More information regarding
   GNOME on FreeBSD can be found at https://www.FreeBSD.org/gnome. That web
   site contains additional documentation about installing, configuring, and
   managing GNOME on FreeBSD.

   This desktop environment can be installed from a package:

 # pkg install gnome3

   To instead build GNOME from ports, use the following command. GNOME is a
   large application and will take some time to compile, even on a fast
   computer.

 # cd /usr/ports/x11/gnome3
 # make install clean

   GNOME requires /proc to be mounted. Add this line to /etc/fstab to mount
   this file system automatically during system startup:

 proc           /proc       procfs  rw  0   0

   GNOME uses D-Bus and HAL for a message bus and hardware abstraction. These
   applications are automatically installed as dependencies of GNOME. Enable
   them in /etc/rc.conf so they will be started when the system boots:

 dbus_enable="YES"
 hald_enable="YES"

   After installation, configure Xorg to start GNOME. The easiest way to do
   this is to enable the GNOME Display Manager, GDM, which is installed as
   part of the GNOME package or port. It can be enabled by adding this line
   to /etc/rc.conf:

 gdm_enable="YES"

   It is often desirable to also start all GNOME services. To achieve this,
   add a second line to /etc/rc.conf:

 gnome_enable="YES"

   GDM will start automatically when the system boots.

   A second method for starting GNOME is to type startx from the command-line
   after configuring ~/.xinitrc. If this file already exists, replace the
   line that starts the current window manager with one that starts
   /usr/local/bin/gnome-session. If this file does not exist, create it with
   this command:

 % echo "exec /usr/local/bin/gnome-session" > ~/.xinitrc

   A third method is to use XDM as the display manager. In this case, create
   an executable ~/.xsession:

 % echo "exec /usr/local/bin/gnome-session" > ~/.xsession

  5.7.2. KDE

   KDE is another easy-to-use desktop environment. This desktop provides a
   suite of applications with a consistent look and feel, a standardized menu
   and toolbars, keybindings, color-schemes, internationalization, and a
   centralized, dialog-driven desktop configuration. More information on KDE
   can be found at http://www.kde.org/. For FreeBSD-specific information,
   consult http://freebsd.kde.org.

   To install the KDE package, type:

 # pkg install x11/kde5

   To instead build the KDE port, use the following command. Installing the
   port will provide a menu for selecting which components to install. KDE is
   a large application and will take some time to compile, even on a fast
   computer.

 # cd /usr/ports/x11/kde5
 # make install clean

   KDE requires /proc to be mounted. Add this line to /etc/fstab to mount
   this file system automatically during system startup:

 proc           /proc       procfs  rw  0   0

   KDE uses D-Bus and HAL for a message bus and hardware abstraction. These
   applications are automatically installed as dependencies of KDE. Enable
   them in /etc/rc.conf so they will be started when the system boots:

 dbus_enable="YES"
 hald_enable="YES"

   Since KDE Plasma 5, the KDE Display Manager, KDM is no longer developed. A
   possible replacement is SDDM. To install it, type:

 # pkg install x11/sddm

   Add this line to /etc/rc.conf:

 sddm_enable="YES"

   A second method for launching KDE is to type startx from the command line.
   For this to work, the following line is needed in ~/.xinitrc:

 exec ck-launch-session startkde

   A third method for starting KDE is through XDM. To do so, create an
   executable ~/.xsession as follows:

 % echo "exec ck-launch-session startkde" > ~/.xsession

   Once KDE is started, refer to its built-in help system for more
   information on how to use its various menus and applications.

  5.7.3. Xfce

   Xfce is a desktop environment based on the GTK+ toolkit used by GNOME.
   However, it is more lightweight and provides a simple, efficient,
   easy-to-use desktop. It is fully configurable, has a main panel with
   menus, applets, and application launchers, provides a file manager and
   sound manager, and is themeable. Since it is fast, light, and efficient,
   it is ideal for older or slower machines with memory limitations. More
   information on Xfce can be found at http://www.xfce.org.

   To install the Xfce package:

 # pkg install xfce

   Alternatively, to build the port:

 # cd /usr/ports/x11-wm/xfce4
 # make install clean

   Xfce uses D-Bus for a message bus. This application is automatically
   installed as dependency of Xfce. Enable it in /etc/rc.conf so it will be
   started when the system boots:

 dbus_enable="YES"

   Unlike GNOME or KDE, Xfce does not provide its own login manager. In order
   to start Xfce from the command line by typing startx, first create
   ~/.xinitrc with this command:

 % echo ". /usr/local/etc/xdg/xfce4/xinitrc" > ~/.xinitrc

   An alternate method is to use XDM. To configure this method, create an
   executable ~/.xsession:

 % echo ". /usr/local/etc/xdg/xfce4/xinitrc" > ~/.xsession

5.8. Installing Compiz Fusion

   One way to make using a desktop computer more pleasant is with nice 3D
   effects.

   Installing the Compiz Fusion package is easy, but configuring it requires
   a few steps that are not described in the port's documentation.

  5.8.1. Setting up the FreeBSD nVidia Driver

   Desktop effects can cause quite a load on the graphics card. For an
   nVidia-based graphics card, the proprietary driver is required for good
   performance. Users of other graphics cards can skip this section and
   continue with the xorg.conf configuration.

   To determine which nVidia driver is needed see the FAQ question on the
   subject.

   Having determined the correct driver to use for your card, installation is
   as simple as installing any other package.

   For example, to install the latest driver:

 # pkg install x11/nvidia-driver

   The driver will create a kernel module, which needs to be loaded at system
   startup. Add the following line to /boot/loader.conf:

 nvidia_load="YES"

  Note:

   To immediately load the kernel module into the running kernel issue a
   command like kldload nvidia. However, it has been noted that some versions
   of Xorg will not function properly if the driver is not loaded at boot
   time. After editing /boot/loader.conf, a reboot is recommended.

   With the kernel module loaded, you normally only need to change a single
   line in xorg.conf to enable the proprietary driver:

   Find the following line in /etc/X11/xorg.conf:

 Driver      "nv"

   and change it to:

 Driver      "nvidia"

   Start the GUI as usual, and you should be greeted by the nVidia splash.
   Everything should work as usual.

  5.8.2. Configuring xorg.conf for Desktop Effects

   To enable Compiz Fusion, /etc/X11/xorg.conf needs to be modified:

   Add the following section to enable composite effects:

 Section "Extensions"
     Option         "Composite" "Enable"
 EndSection

   Locate the "Screen" section which should look similar to the one below:

 Section "Screen"
     Identifier     "Screen0"
     Device         "Card0"
     Monitor        "Monitor0"
     ...

   and add the following two lines (after "Monitor" will do):

 DefaultDepth    24
 Option         "AddARGBGLXVisuals" "True"

   Locate the "Subsection" that refers to the screen resolution that you wish
   to use. For example, if you wish to use 1280x1024, locate the section that
   follows. If the desired resolution does not appear in any subsection, you
   may add the relevant entry by hand:

 SubSection     "Display"
     Viewport    0 0
     Modes      "1280x1024"
 EndSubSection

   A color depth of 24 bits is needed for desktop composition, change the
   above subsection to:

 SubSection     "Display"
     Viewport    0 0
     Depth       24
     Modes      "1280x1024"
 EndSubSection

   Finally, confirm that the "glx" and "extmod" modules are loaded in the
   "Module" section:

 Section "Module"
     Load           "extmod"
     Load           "glx"
     ...

   The preceding can be done automatically with x11/nvidia-xconfig by running
   (as root):

 # nvidia-xconfig --add-argb-glx-visuals
 # nvidia-xconfig --composite
 # nvidia-xconfig --depth=24

  5.8.3. Installing and Configuring Compiz Fusion

   Installing Compiz Fusion is as simple as any other package:

 # pkg install x11-wm/compiz-fusion

   When the installation is finished, start your graphic desktop and at a
   terminal, enter the following commands (as a normal user):

 % compiz --replace --sm-disable --ignore-desktop-hints ccp &
 % emerald --replace &

   Your screen will flicker for a few seconds, as your window manager (e.g.
   Metacity if you are using GNOME) is replaced by Compiz Fusion. Emerald
   takes care of the window decorations (i.e. close, minimize, maximize
   buttons, title bars and so on).

   You may convert this to a trivial script and have it run at startup
   automatically (e.g. by adding to "Sessions" in a GNOME desktop):

 #! /bin/sh
 compiz --replace --sm-disable --ignore-desktop-hints ccp &
 emerald --replace &

   Save this in your home directory as, for example, start-compiz and make it
   executable:

 % chmod +x ~/start-compiz

   Then use the GUI to add it to Startup Programs (located in System,
   Preferences, Sessions on a GNOME desktop).

   To actually select all the desired effects and their settings, execute
   (again as a normal user) the Compiz Config Settings Manager:

 % ccsm

  Note:

   In GNOME, this can also be found in the System, Preferences menu.

   If you have selected "gconf support" during the build, you will also be
   able to view these settings using gconf-editor under apps/compiz.

5.9. Troubleshooting

   If the mouse does not work, you will need to first configure it before
   proceeding. In recent Xorg versions, the InputDevice sections in xorg.conf
   are ignored in favor of the autodetected devices. To restore the old
   behavior, add the following line to the ServerLayout or ServerFlags
   section of this file:

 Option "AutoAddDevices" "false"

   Input devices may then be configured as in previous versions, along with
   any other options needed (e.g., keyboard layout switching).

  Note:

   As previously explained the hald daemon will, by default, automatically
   detect your keyboard. There are chances that your keyboard layout or model
   will not be correct, desktop environments like GNOME, KDE or Xfce provide
   tools to configure the keyboard. However, it is possible to set the
   keyboard properties directly either with the help of the setxkbmap(1)
   utility or with a hald's configuration rule.

   For example if, one wants to use a PC 102 keys keyboard coming with a
   french layout, we have to create a keyboard configuration file for hald
   called x11-input.fdi and saved in the /usr/local/etc/hal/fdi/policy
   directory. This file should contain the following lines:

 
 
   
     
           pc102
           fr
     
   

 

   If this file already exists, just copy and add to your file the lines
   regarding the keyboard configuration.

   You will have to reboot your machine to force hald to read this file.

   It is possible to do the same configuration from an X terminal or a script
   with this command line:

 % setxkbmap -model pc102 -layout fr

   /usr/local/share/X11/xkb/rules/base.lst lists the various keyboard,
   layouts and options available.

   The xorg.conf.new configuration file may now be tuned to taste. Open the
   file in a text editor such as emacs(1) or ee(1). If the monitor is an
   older or unusual model that does not support autodetection of sync
   frequencies, those settings can be added to xorg.conf.new under the
   "Monitor" section:

 Section "Monitor"
         Identifier   "Monitor0"
         VendorName   "Monitor Vendor"
         ModelName    "Monitor Model"
         HorizSync    30-107
         VertRefresh  48-120
 EndSection

   Most monitors support sync frequency autodetection, making manual entry of
   these values unnecessary. For the few monitors that do not support
   autodetection, avoid potential damage by only entering values provided by
   the manufacturer.

   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 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). 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 Xorg log files, which contain information on each device that the
   Xorg server attaches to. Xorg log file names are in the format of
   /var/log/Xorg.0.log. The exact name of the log can vary from Xorg.0.log to
   Xorg.8.log and so forth.

   If all is well, the configuration file needs to be installed in a common
   location where Xorg(1) can find it. This is typically /etc/X11/xorg.conf
   or /usr/local/etc/X11/xorg.conf.

 # cp xorg.conf.new /etc/X11/xorg.conf

   The Xorg configuration process is now complete. Xorg may be now started
   with the startx(1) utility. The Xorg server may also be started with the
   use of xdm(1).

  5.9.1. Configuration with Intel(R) i810 Graphics Chipsets

   Configuration with Intel(R) i810 integrated chipsets requires the agpgart
   AGP programming interface for Xorg 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.

  5.9.2. Adding a Widescreen Flatpanel to the Mix

   This section assumes a bit of advanced configuration knowledge. If
   attempts to use the standard configuration tools above have not resulted
   in a working configuration, there is information enough in the log files
   to be of use in getting the setup working. Use of a text editor will be
   necessary.

   Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+, et.al.) formats
   support 16:10 and 10:9 formats or aspect ratios that can be problematic.
   Examples of some common screen resolutions for 16:10 aspect ratios are:

     * 2560x1600

     * 1920x1200

     * 1680x1050

     * 1440x900

     * 1280x800

   At some point, it will be as easy as adding one of these resolutions as a
   possible Mode in the Section "Screen" as such:

 Section "Screen"
 Identifier "Screen0"
 Device     "Card0"
 Monitor    "Monitor0"
 DefaultDepth 24
 SubSection "Display"
         Viewport  0 0
         Depth     24
         Modes     "1680x1050"
 EndSubSection
 EndSection

   Xorg is smart enough to pull the resolution information from the
   widescreen via I2C/DDC information so it knows what the monitor can handle
   as far as frequencies and resolutions.

   If those ModeLines do not exist in the drivers, one might need to give
   Xorg a little hint. Using /var/log/Xorg.0.log one can extract enough
   information to manually create a ModeLine that will work. Simply look for
   information resembling this:

 (II) MGA(0): Supported additional Video Mode:
 (II) MGA(0): clock: 146.2 MHz   Image Size:  433 x 271 mm
 (II) MGA(0): h_active: 1680  h_sync: 1784  h_sync_end 1960 h_blank_end 2240 h_border: 0
 (II) MGA(0): v_active: 1050  v_sync: 1053  v_sync_end 1059 v_blanking: 1089 v_border: 0
 (II) MGA(0): Ranges: V min: 48  V max: 85 Hz, H min: 30  H max: 94 kHz, PixClock max 170 MHz

   This information is called EDID information. Creating a ModeLine from this
   is just a matter of putting the numbers in the correct order:

 ModeLine   <4 horiz. timings> <4 vert. timings>

   So that the ModeLine in Section "Monitor" for this example would look like
   this:

 Section "Monitor"
 Identifier      "Monitor1"
 VendorName      "Bigname"
 ModelName       "BestModel"
 ModeLine        "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
 Option          "DPMS"
 EndSection

   Now having completed these simple editing steps, X should start on your
   new widescreen monitor.

  5.9.3. Troubleshooting Compiz Fusion

   5.9.3.1. I have installed Compiz Fusion, and after running the commands
   you mention, my windows are left without title bars and buttons. What is
   wrong?

   5.9.3.2. When I run the command to start Compiz Fusion, the X server
   crashes and I am back at the console. What is wrong?

5.9.3.1. I have installed Compiz Fusion, and after running the commands you mention, my  
         windows are left without title bars and buttons. What is wrong?                 
         You are probably missing a setting in /etc/X11/xorg.conf. Review this file      
         carefully and check especially the DefaultDepth and AddARGBGLXVisuals           
         directives.                                                                     
5.9.3.2. When I run the command to start Compiz Fusion, the X server crashes and I am    
         back at the console. What is wrong?                                             
         If you check /var/log/Xorg.0.log, you will probably find error messages during  
         the X startup. The most common would be:                                        
                                                                                         
         (EE) NVIDIA(0):     Failed to initialize the GLX module; please check in your X 
         (EE) NVIDIA(0):     log file that the GLX module has been loaded in your X      
         (EE) NVIDIA(0):     server, and that the module is the NVIDIA GLX module.  If   
         (EE) NVIDIA(0):     you continue to encounter problems, Please try              
         (EE) NVIDIA(0):     reinstalling the NVIDIA driver.                             
                                                                                         
         This is usually the case when you upgrade Xorg. You will need to reinstall the  
         x11/nvidia-driver package so glx is built again.                                

                             Part II. Common Tasks

   Now that the basics have been covered, this part of the book discusses
   some frequently used features of FreeBSD. These chapters:

     * Introduce popular and useful desktop applications: browsers,
       productivity tools, document viewers, and more.

     * Introduce a number of multimedia tools available for FreeBSD.

     * Explain the process of building a customized FreeBSD kernel to enable
       extra functionality.

     * Describe the print system in detail, both for desktop and
       network-connected printer setups.

     * Show how to run Linux applications on the FreeBSD system.

   Some of these chapters recommend prior reading, and this is noted in the
   synopsis at the beginning of each chapter.

   Table of Contents

   6. Desktop Applications

                6.1. Synopsis

                6.2. Browsers

                6.3. Productivity

                6.4. Document Viewers

                6.5. Finance

   7. Multimedia

                7.1. Synopsis

                7.2. Setting Up the Sound Card

                7.3. MP3 Audio

                7.4. Video Playback

                7.5. TV Cards

                7.6. MythTV

                7.7. Image Scanners

   8. Configuring the FreeBSD Kernel

                8.1. Synopsis

                8.2. Why Build a Custom Kernel?

                8.3. Finding the System Hardware

                8.4. The Configuration File

                8.5. Building and Installing a Custom Kernel

                8.6. If Something Goes Wrong

   9. Printing

                9.1. Quick Start

                9.2. Printer Connections

                9.3. Common Page Description Languages

                9.4. Direct Printing

                9.5. LPD (Line Printer Daemon)

                9.6. Other Printing Systems

   10. Linux(R) Binary Compatibility

                10.1. Synopsis

                10.2. Configuring Linux(R) Binary Compatibility

                10.3. Advanced Topics

Chapter 6. Desktop Applications

   Table of Contents

   6.1. Synopsis

   6.2. Browsers

   6.3. Productivity

   6.4. Document Viewers

   6.5. Finance

6.1. Synopsis

   While FreeBSD is popular as a server for its performance and stability, it
   is also suited for day-to-day use as a desktop. With over 24,000
   applications available as FreeBSD packages or ports, it is easy to build a
   customized desktop that runs a wide variety of desktop applications. This
   chapter demonstrates how to install numerous desktop applications,
   including web browsers, productivity software, document viewers, and
   financial software.

  Note:

   Users who prefer to install a pre-built desktop version of FreeBSD rather
   than configuring one from scratch should refer to the trueos.org website.

   Readers of this chapter should know how to:

     * Install additional software using packages or ports as described in
       Chapter 4, Installing Applications: Packages and Ports.

     * Install X and a window manager as described in Chapter 5, The X Window
       System.

   For information on how to configure a multimedia environment, refer to
   Chapter 7, Multimedia.

6.2. Browsers

   FreeBSD does not come with a pre-installed web browser. Instead, the www
   category of the Ports Collection contains many browsers which can be
   installed as a package or compiled from the Ports Collection.

   The KDE and GNOME desktop environments include their own HTML browser.
   Refer to Section 5.7, "Desktop Environments" for more information on how
   to set up these complete desktops.

   Some lightweight browsers include www/dillo2, www/links, and www/w3m.

   This section demonstrates how to install the following popular web
   browsers and indicates if the application is resource-heavy, takes time to
   compile from ports, or has any major dependencies.

   Application Name Resources Installation from             Notes             
                     Needed         Ports       
                                                FreeBSD, Linux(R), and        
   Firefox          medium    heavy             localized versions are        
                                                available                     
   Opera            light     light             FreeBSD and Linux(R) versions 
                                                are available                 
   Konqueror        medium    heavy             Requires KDE libraries        
   Chromium         medium    heavy             Requires Gtk+                 

  6.2.1. Firefox

   Firefox is an open source browser that features a standards-compliant HTML
   display engine, tabbed browsing, popup blocking, extensions, improved
   security, and more. Firefox is based on the Mozilla codebase.

   To install the package of the latest release version of Firefox, type:

 # pkg install firefox

   To instead install Firefox Extended Support Release (ESR) version, use:

 # pkg install firefox-esr

   Localized versions are available in www/firefox-i18n and
   www/firefox-esr-i18n.

   The Ports Collection can instead be used to compile the desired version of
   Firefox from source code. This example builds www/firefox, where firefox
   can be replaced with the ESR or localized version to install.

 # cd /usr/ports/www/firefox
 # make install clean

  6.2.2. Opera

   Opera is a full-featured and standards-compliant browser which is still
   lightweight and fast. It comes with a built-in mail and news reader, an
   IRC client, an RSS/Atom feeds reader, and more. It is available as a
   native FreeBSD version and as a version that runs under Linux(R)
   emulation.

   This command installs the package of the FreeBSD version of Opera. Replace
   opera with linux-opera to instead install the Linux(R) version.

 # pkg install opera

   Alternately, install either version through the Ports Collection. This
   example compiles the native version:

 # cd /usr/ports/www/opera
 # make install clean

   To install the Linux(R) version, substitute linux-opera in place of opera.

   To install Adobe(R) Flash(R) plugin support, first compile the
   www/linux-flashplayer port. Licensing restrictions prevent making a
   package available. Then install www/opera-linuxplugins. This example
   compiles both applications from ports:

 # cd /usr/ports/www/linux-flashplayer
 # make install clean
 # cd /usr/ports/www/opera-linuxplugins
 # make install clean

   Once installed, check the presence of the plugin by starting the browser,
   entering opera:plugins in the location bar and pressing Enter. A list
   should appear with all the currently available plugins.

   To add the Java(TM) plugin, follow install java/icedtea-web.

  6.2.3. Konqueror

   Konqueror is more than a web browser as it is also a file manager and a
   multimedia viewer. It is included in the x11/kde4-baseapps package or
   port.

   Konqueror supports WebKit as well as its own KHTML. WebKit is a rendering
   engine used by many modern browsers including Chromium. To use WebKit with
   Konqueror on FreeBSD, install the www/kwebkitpart package or port. This
   example installs the package:

 # pkg install kwebkitpart

   To install from the Ports Collection:

 # cd /usr/ports/www/kwebkitpart
 # make install clean

   To enable WebKit within Konqueror, click "Settings", "Configure
   Konqueror". In the "General" settings page, click the drop-down menu next
   to "Default web browser engine" and change "KHTML" to "WebKit".

   Konqueror also supports Flash(R). A "How To" guide for getting Flash(R)
   support on Konqueror is available at
   http://freebsd.kde.org/howtos/konqueror-flash.php.

  6.2.4. Chromium

   Chromium is an open source browser project that aims to build a safer,
   faster, and more stable web browsing experience. Chromium features tabbed
   browsing, popup blocking, extensions, and much more. Chromium is the open
   source project upon which the Google Chrome web browser is based.

   Chromium can be installed as a package by typing:

 # pkg install chromium

   Alternatively, Chromium can be compiled from source using the Ports
   Collection:

 # cd /usr/ports/www/chromium
 # make install clean

  Note:

   The executable for Chromium is /usr/local/bin/chrome, not
   /usr/local/bin/chromium.

6.3. Productivity

   When it comes to productivity, users often look for an office suite or an
   easy-to-use word processor. While some desktop environments like KDE
   provide an office suite, there is no default productivity package. Several
   office suites and graphical word processors are available for FreeBSD,
   regardless of the installed window manager.

   This section demonstrates how to install the following popular
   productivity software and indicates if the application is resource-heavy,
   takes time to compile from ports, or has any major dependencies.

   Application Name    Resources    Installation from   Major Dependencies    
                         Needed           Ports       
   Calligra          light          heavy             KDE                     
   AbiWord           light          light             Gtk+ or GNOME           
   The Gimp          light          heavy             Gtk+                    
   Apache OpenOffice heavy          huge              JDK(TM) and Mozilla     
   LibreOffice       somewhat heavy huge              Gtk+, or KDE/ GNOME, or 
                                                      JDK(TM)                 

  6.3.1. Calligra

   The KDE desktop environment includes an office suite which can be
   installed separately from KDE. Calligra includes standard components that
   can be found in other office suites. Words is the word processor, Sheets
   is the spreadsheet program, Stage manages slide presentations, and Karbon
   is used to draw graphical documents.

   In FreeBSD, editors/calligra can be installed as a package or a port. To
   install the package:

 # pkg install calligra

   If the package is not available, use the Ports Collection instead:

 # cd /usr/ports/editors/calligra
 # make install clean

  6.3.2. AbiWord

   AbiWord is a free word processing program similar in look and feel to
   Microsoft(R) Word. It is fast, contains many features, and is
   user-friendly.

   AbiWord can import or export many file formats, including some proprietary
   ones like Microsoft(R) .rtf.

   To install the AbiWord package:

 # pkg install abiword

   If the package is not available, it can be compiled from the Ports
   Collection:

 # cd /usr/ports/editors/abiword
 # make install clean

  6.3.3. The GIMP

   For image authoring or picture retouching, The GIMP provides a
   sophisticated image manipulation program. It can be used as a simple paint
   program or as a quality photo retouching suite. It supports a large number
   of plugins and features a scripting interface. The GIMP can read and write
   a wide range of file formats and supports interfaces with scanners and
   tablets.

   To install the package:

 # pkg install gimp

   Alternately, use the Ports Collection:

 # cd /usr/ports/graphics/gimp
 # make install clean

   The graphics category (freebsd.org/ports/graphics.html) of the Ports
   Collection contains several GIMP-related plugins, help files, and user
   manuals.

  6.3.4. Apache OpenOffice

   Apache OpenOffice is an open source office suite which is developed under
   the wing of the Apache Software Foundation's Incubator. It includes all of
   the applications found in a complete office productivity suite: a word
   processor, spreadsheet, presentation manager, and drawing program. Its
   user interface is similar to other office suites, and it can import and
   export in various popular file formats. It is available in a number of
   different languages and internationalization has been extended to
   interfaces, spell checkers, and dictionaries.

   The word processor of Apache OpenOffice uses a native XML file format for
   increased portability and flexibility. The spreadsheet program features a
   macro language which can be interfaced with external databases. Apache
   OpenOffice is stable and runs natively on Windows(R), Solaris(TM),
   Linux(R), FreeBSD, and Mac OS(R) X. More information about Apache
   OpenOffice can be found at openoffice.org. For FreeBSD specific
   information refer to porting.openoffice.org/freebsd/.

   To install the Apache OpenOffice package:

 # pkg install apache-openoffice

   Once the package is installed, type the following command to launch Apache
   OpenOffice:

 % openoffice-X.Y.Z

   where X.Y.Z is the version number of the installed version of Apache
   OpenOffice. The first time Apache OpenOffice launches, some questions will
   be asked and a .openoffice.org folder will be created in the user's home
   directory.

   If the desired Apache OpenOffice package is not available, compiling the
   port is still an option. However, this requires a lot of disk space and a
   fairly long time to compile:

 # cd /usr/ports/editors/openoffice-4
 # make install clean

  Note:

   To build a localized version, replace the previous command with:

 # make LOCALIZED_LANG=your_language install clean

   Replace your_language with the correct language ISO-code. A list of
   supported language codes is available in files/Makefile.localized, located
   in the port's directory.

  6.3.5. LibreOffice

   LibreOffice is a free software office suite developed by
   documentfoundation.org. It is compatible with other major office suites
   and available on a variety of platforms. It is a rebranded fork of Apache
   OpenOffice and includes applications found in a complete office
   productivity suite: a word processor, spreadsheet, presentation manager,
   drawing program, database management program, and a tool for creating and
   editing mathematical formulae. It is available in a number of different
   languages and internationalization has been extended to interfaces, spell
   checkers, and dictionaries.

   The word processor of LibreOffice uses a native XML file format for
   increased portability and flexibility. The spreadsheet program features a
   macro language which can be interfaced with external databases.
   LibreOffice is stable and runs natively on Windows(R), Linux(R), FreeBSD,
   and Mac OS(R) X. More information about LibreOffice can be found at
   libreoffice.org.

   To install the English version of the LibreOffice package:

 # pkg install libreoffice

   The editors category (freebsd.org/ports/editors.html) of the Ports
   Collection contains several localizations for LibreOffice. When installing
   a localized package, replace libreoffice with the name of the localized
   package.

   Once the package is installed, type the following command to run
   LibreOffice:

 % libreoffice

   During the first launch, some questions will be asked and a .libreoffice
   folder will be created in the user's home directory.

   If the desired LibreOffice package is not available, compiling the port is
   still an option. However, this requires a lot of disk space and a fairly
   long time to compile. This example compiles the English version:

 # cd /usr/ports/editors/libreoffice
 # make install clean

  Note:

   To build a localized version, cd into the port directory of the desired
   language. Supported languages can be found in the editors category
   (freebsd.org/ports/editors.html) of the Ports Collection.

6.4. Document Viewers

   Some new document formats have gained popularity since the advent of
   UNIX(R) and the viewers they require may not be available in the base
   system. This section demonstrates how to install the following document
   viewers:

   Application Name Resources Needed   Installation from   Major Dependencies 
                                             Ports         
   Xpdf             light            light                 FreeType           
   gv               light            light                 Xaw3d              
   Geeqie           light            light                 Gtk+ or GNOME      
   ePDFView         light            light                 Gtk+               
   Okular           light            heavy                 KDE                

  6.4.1. Xpdf

   For users that prefer a small FreeBSD PDF viewer, Xpdf provides a
   light-weight and efficient viewer which requires few resources. It uses
   the standard X fonts and does not require any additional toolkits.

   To install the Xpdf package:

 # pkg install xpdf

   If the package is not available, use the Ports Collection:

 # cd /usr/ports/graphics/xpdf
 # make install clean

   Once the installation is complete, launch xpdf and use the right mouse
   button to activate the menu.

  6.4.2. gv

   gv is a PostScript(R) and PDF viewer. It is based on ghostview, but has a
   nicer look as it is based on the Xaw3d widget toolkit. gv has many
   configurable features, such as orientation, paper size, scale, and
   anti-aliasing. Almost any operation can be performed with either the
   keyboard or the mouse.

   To install gv as a package:

 # pkg install gv

   If a package is unavailable, use the Ports Collection:

 # cd /usr/ports/print/gv
 # make install clean

  6.4.3. Geeqie

   Geeqie is a fork from the unmaintained GQView project, in an effort to
   move development forward and integrate the existing patches. Geeqie is an
   image manager which supports viewing a file with a single click, launching
   an external editor, and thumbnail previews. It also features a slideshow
   mode and some basic file operations, making it easy to manage image
   collections and to find duplicate files. Geeqie supports full screen
   viewing and internationalization.

   To install the Geeqie package:

 # pkg install geeqie

   If the package is not available, use the Ports Collection:

 # cd /usr/ports/graphics/geeqie
 # make install clean

  6.4.4. ePDFView

   ePDFView is a lightweight PDF document viewer that only uses the Gtk+ and
   Poppler libraries. It is currently under development, but already opens
   most PDF files (even encrypted), save copies of documents, and has support
   for printing using CUPS.

   To install ePDFView as a package:

 # pkg install epdfview

   If a package is unavailable, use the Ports Collection:

 # cd /usr/ports/graphics/epdfview
 # make install clean

  6.4.5. Okular

   Okular is a universal document viewer based on KPDF for KDE. It can open
   many document formats, including PDF, PostScript(R), DjVu, CHM, XPS, and
   ePub.

   To install Okular as a package:

 # pkg install okular

   If a package is unavailable, use the Ports Collection:

 # cd /usr/ports/graphics/okular
 # make install clean

6.5. Finance

   For managing personal finances on a FreeBSD desktop, some powerful and
   easy-to-use applications can be installed. Some are compatible with
   widespread file formats, such as the formats used by Quicken and Excel.

   This section covers these programs:

   Application Name Resources Needed   Installation from   Major Dependencies 
                                             Ports         
   GnuCash          light            heavy                 GNOME              
   Gnumeric         light            heavy                 GNOME              
   KMyMoney         light            heavy                 KDE                

  6.5.1. GnuCash

   GnuCash is part of the GNOME effort to provide user-friendly, yet
   powerful, applications to end-users. GnuCash can be used to keep track of
   income and expenses, bank accounts, and stocks. It features an intuitive
   interface while remaining professional.

   GnuCash provides a smart register, a hierarchical system of accounts, and
   many keyboard accelerators and auto-completion methods. It can split a
   single transaction into several more detailed pieces. GnuCash can import
   and merge Quicken QIF files. It also handles most international date and
   currency formats.

   To install the GnuCash package:

 # pkg install gnucash

   If the package is not available, use the Ports Collection:

 # cd /usr/ports/finance/gnucash
 # make install clean

  6.5.2. Gnumeric

   Gnumeric is a spreadsheet program developed by the GNOME community. It
   features convenient automatic guessing of user input according to the cell
   format with an autofill system for many sequences. It can import files in
   a number of popular formats, including Excel, Lotus 1-2-3, and Quattro
   Pro. It has a large number of built-in functions and allows all of the
   usual cell formats such as number, currency, date, time, and much more.

   To install Gnumeric as a package:

 # pkg install gnumeric

   If the package is not available, use the Ports Collection:

 # cd /usr/ports/math/gnumeric
 # make install clean

  6.5.3. KMyMoney

   KMyMoney is a personal finance application created by the KDE community.
   KMyMoney aims to provide the important features found in commercial
   personal finance manager applications. It also highlights ease-of-use and
   proper double-entry accounting among its features. KMyMoney imports from
   standard Quicken QIF files, tracks investments, handles multiple
   currencies, and provides a wealth of reports.

   To install KMyMoney as a package:

 # pkg install kmymoney-kde4

   If the package is not available, use the Ports Collection:

 # cd /usr/ports/finance/kmymoney-kde4
 # make install clean

Chapter 7. Multimedia

   Edited by Ross Lippert.
   Table of Contents

   7.1. Synopsis

   7.2. Setting Up the Sound Card

   7.3. MP3 Audio

   7.4. Video Playback

   7.5. TV Cards

   7.6. MythTV

   7.7. Image Scanners

7.1. Synopsis

   FreeBSD supports a wide variety of sound cards, allowing users to enjoy
   high fidelity output from a FreeBSD system. This includes the ability to
   record and play back audio in the MPEG Audio Layer 3 (MP3), Waveform Audio
   File (WAV), Ogg Vorbis, and other formats. The FreeBSD Ports Collection
   contains many applications for editing recorded audio, adding sound
   effects, and controlling attached MIDI devices.

   FreeBSD also supports the playback of video files and DVDs. The FreeBSD
   Ports Collection contains applications to encode, convert, and playback
   various video media.

   This chapter describes how to configure sound cards, video playback, TV
   tuner cards, and scanners on FreeBSD. It also describes some of the
   applications which are available for using these devices.

   After reading this chapter, you will know how to:

     * Configure a sound card on FreeBSD.

     * Troubleshoot the sound setup.

     * Playback and encode MP3s and other audio.

     * Prepare a FreeBSD system for video playback.

     * Play DVDs, .mpg, and .avi files.

     * Rip CD and DVD content into files.

     * Configure a TV card.

     * Install and setup MythTV on FreeBSD

     * Configure an image scanner.

     * Configure a Bluetooth headset.

   Before reading this chapter, you should:

     * Know how to install applications as described in Chapter 4, Installing
       Applications: Packages and Ports.

7.2. Setting Up the Sound Card

   Contributed by Moses Moore.
   Enhanced by Marc Fonvieille.

   Before beginning the configuration, determine the model of the sound card
   and the chip it uses. FreeBSD supports a wide variety of sound cards.
   Check the supported audio devices list of the Hardware Notes to see if the
   card is supported and which FreeBSD driver it uses.

   In order to use the sound device, its device driver must be loaded. The
   easiest way is to load a kernel module for the sound card with kldload(8).
   This example loads the driver for a built-in audio chipset based on the
   Intel specification:

 # kldload snd_hda

   To automate the loading of this driver at boot time, add the driver to
   /boot/loader.conf. The line for this driver is:

 snd_hda_load="YES"

   Other available sound modules are listed in /boot/defaults/loader.conf.
   When unsure which driver to use, load the snd_driver module:

 # kldload snd_driver

   This is a metadriver which loads all of the most common sound drivers and
   can be used to speed up the search for the correct driver. It is also
   possible to load all sound drivers by adding the metadriver to
   /boot/loader.conf.

   To determine which driver was selected for the sound card after loading
   the snd_driver metadriver, type cat /dev/sndstat.

  7.2.1. Configuring a Custom Kernel with Sound Support

   This section is for users who prefer to statically compile in support for
   the sound card in a custom kernel. For more information about recompiling
   a kernel, refer to Chapter 8, Configuring the FreeBSD Kernel.

   When using a custom kernel to provide sound support, make sure that the
   audio framework driver exists in the custom kernel configuration file:

 device sound

   Next, add support for the sound card. To continue the example of the
   built-in audio chipset based on the Intel specification from the previous
   section, use the following line in the custom kernel configuration file:

 device snd_hda

   Be sure to read the manual page of the driver for the device name to use
   for the driver.

   Non-PnP ISA sound cards may require the IRQ and I/O port settings of the
   card to be added to /boot/device.hints. During the boot process, loader(8)
   reads this file and passes the settings to the kernel. For example, an old
   Creative SoundBlaster(R) 16 ISA non-PnP card will use the snd_sbc(4)
   driver in conjunction with snd_sb16. For this card, the following lines
   must be added to the kernel configuration file:

 device snd_sbc
 device snd_sb16

   If the card uses the 0x220 I/O port and IRQ 5, these lines must also be
   added to /boot/device.hints:

 hint.sbc.0.at="isa"
 hint.sbc.0.port="0x220"
 hint.sbc.0.irq="5"
 hint.sbc.0.drq="1"
 hint.sbc.0.flags="0x15"

   The syntax used in /boot/device.hints is described in sound(4) and the
   manual page for the driver of the sound card.

   The settings shown above are the defaults. In some cases, the IRQ or other
   settings may need to be changed to match the card. Refer to snd_sbc(4) for
   more information about this card.

  7.2.2. Testing Sound

   After loading the required module or rebooting into the custom kernel, the
   sound card should be detected. To confirm, run dmesg | grep pcm. This
   example is from a system with a built-in Conexant CX20590 chipset:

 pcm0:  at nid 5 on hdaa0
 pcm1:  at nid 6 on hdaa0
 pcm2:  at nid 31,25 and 35,27 on hdaa1

   The status of the sound card may also be checked using this command:

 # cat /dev/sndstat
 FreeBSD Audio Driver (newpcm: 64bit 2009061500/amd64)
 Installed devices:
 pcm0:  (play)
 pcm1:  (play)
 pcm2:  (play/rec) default

   The output will vary depending upon the sound card. If no pcm devices are
   listed, double-check that the correct device driver was loaded or compiled
   into the kernel. The next section lists some common problems and their
   solutions.

   If all goes well, the sound card should now work in FreeBSD. If the CD or
   DVD drive is properly connected to the sound card, one can insert an audio
   CD in the drive and play it with cdcontrol(1):

 % cdcontrol -f /dev/acd0 play 1

  Warning:

   Audio CDs have specialized encodings which means that they should not be
   mounted using mount(8).

   Various applications, such as audio/workman, provide a friendlier
   interface. The audio/mpg123 port can be installed to listen to MP3 audio
   files.

   Another quick way to test the card is to send data to /dev/dsp:

 % cat filename > /dev/dsp

   where filename can be any type of file. This command should produce some
   noise, confirming that the sound card is working.

  Note:

   The /dev/dsp* device nodes will be created automatically as needed. When
   not in use, they do not exist and will not appear in the output of ls(1).

  7.2.3. Setting up Bluetooth Sound Devices

   Connecting to a Bluetooth device is out of scope for this chapter. Refer
   to Section 31.5, "Bluetooth" for more information.

   To get Bluetooth sound sink working with FreeBSD's sound system, users
   have to install audio/virtual_oss first:

 # pkg install virtual_oss

   audio/virtual_oss requires cuse to be loaded into the kernel:

 # kldload cuse

   To load cuse during system startup, run this command:

 # sysrc -f /boot/loader.conf cuse_load=yes

   To use headphones as a sound sink with audio/virtual_oss, users need to
   create a virtual device after connecting to a Bluetooth audio device:

 # virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 768 -R /dev/null -P /dev/bluetooth/headphones -d dsp

  Note:

   headphones in this example is a hostname from /etc/bluetooth/hosts.
   BT_ADDR could be used instead.

   Refer to virtual_oss(8) for more information.

  7.2.4. Troubleshooting Sound

   Table 7.1, "Common Error Messages" lists some common error messages and
   their solutions:

   Table 7.1. Common Error Messages

             Error                               Solution                     
   sb_dspwr(XX) timed out     The I/O port is not set correctly.              
   bad irq XX                 The IRQ is set incorrectly. Make sure that the  
                              set IRQ and the sound IRQ are the same.         
   xxx: gus pcm not attached, There is not enough available memory to use the 
   out of memory              device.                                         
                              Type fstat | grep dsp to check if another       
   xxx: can't open /dev/dsp!  application is holding the device open.         
                              Noteworthy troublemakers are esound and KDE's   
                              sound support.                                  

   Modern graphics cards often come with their own sound driver for use with
   HDMI. This sound device is sometimes enumerated before the sound card
   meaning that the sound card will not be used as the default playback
   device. To check if this is the case, run dmesg and look for pcm. The
   output looks something like this:

 ...
 hdac0: HDA Driver Revision: 20100226_0142
 hdac1: HDA Driver Revision: 20100226_0142
 hdac0: HDA Codec #0: NVidia (Unknown)
 hdac0: HDA Codec #1: NVidia (Unknown)
 hdac0: HDA Codec #2: NVidia (Unknown)
 hdac0: HDA Codec #3: NVidia (Unknown)
 pcm0:  at cad 0 nid 1 on hdac0
 pcm1:  at cad 1 nid 1 on hdac0
 pcm2:  at cad 2 nid 1 on hdac0
 pcm3:  at cad 3 nid 1 on hdac0
 hdac1: HDA Codec #2: Realtek ALC889
 pcm4:  at cad 2 nid 1 on hdac1
 pcm5:  at cad 2 nid 1 on hdac1
 pcm6:  at cad 2 nid 1 on hdac1
 pcm7:  at cad 2 nid 1 on hdac1
 ...

   In this example, the graphics card (NVidia) has been enumerated before the
   sound card (Realtek ALC889). To use the sound card as the default playback
   device, change hw.snd.default_unit to the unit that should be used for
   playback:

 # sysctl hw.snd.default_unit=n

   where n is the number of the sound device to use. In this example, it
   should be 4. Make this change permanent by adding the following line to
   /etc/sysctl.conf:

 hw.snd.default_unit=4

  7.2.5. Utilizing Multiple Sound Sources

   Contributed by Munish Chopra.

   It is often desirable to have multiple sources of sound that are able to
   play simultaneously. FreeBSD uses "Virtual Sound Channels" to multiplex
   the sound card's playback by mixing sound in the kernel.

   Three sysctl(8) knobs are available for configuring virtual channels:

 # sysctl dev.pcm.0.play.vchans=4
 # sysctl dev.pcm.0.rec.vchans=4
 # sysctl hw.snd.maxautovchans=4

   This example allocates four virtual channels, which is a practical number
   for everyday use. Both dev.pcm.0.play.vchans=4 and dev.pcm.0.rec.vchans=4
   are configurable after a device has been attached and represent the number
   of virtual channels pcm0 has for playback and recording. Since the pcm
   module can be loaded independently of the hardware drivers,
   hw.snd.maxautovchans indicates how many virtual channels will be given to
   an audio device when it is attached. Refer to pcm(4) for more information.

  Note:

   The number of virtual channels for a device cannot be changed while it is
   in use. First, close any programs using the device, such as music players
   or sound daemons.

   The correct pcm device will automatically be allocated transparently to a
   program that requests /dev/dsp0.

  7.2.6. Setting Default Values for Mixer Channels

   Contributed by Josef El-Rayes.

   The default values for the different mixer channels are hardcoded in the
   source code of the pcm(4) driver. While sound card mixer levels can be
   changed using mixer(8) or third-party applications and daemons, this is
   not a permanent solution. To instead set default mixer values at the
   driver level, define the appropriate values in /boot/device.hints, as seen
   in this example:

 hint.pcm.0.vol="50"

   This will set the volume channel to a default value of 50 when the pcm(4)
   module is loaded.

7.3. MP3 Audio

   Contributed by Chern Lee.

   This section describes some MP3 players available for FreeBSD, how to rip
   audio CD tracks, and how to encode and decode MP3s.

  7.3.1. MP3 Players

   A popular graphical MP3 player is Audacious. It supports Winamp skins and
   additional plugins. The interface is intuitive, with a playlist, graphic
   equalizer, and more. Those familiar with Winamp will find Audacious simple
   to use. On FreeBSD, Audacious can be installed from the
   multimedia/audacious port or package. Audacious is a descendant of XMMS.

   The audio/mpg123 package or port provides an alternative, command-line MP3
   player. Once installed, specify the MP3 file to play on the command line.
   If the system has multiple audio devices, the sound device can also be
   specified:

 # mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3
 High Performance MPEG 1.0/2.0/2.5 Audio Player for Layers 1, 2 and 3
         version 1.18.1; written and copyright by Michael Hipp and others
         free software (LGPL) without any warranty but with best wishes

 Playing MPEG stream from Foobar-GreatestHits.mp3 ...
 MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo

   Additional MP3 players are available in the FreeBSD Ports Collection.

  7.3.2. Ripping CD Audio Tracks

   Before encoding a CD or CD track to MP3, the audio data on the CD must be
   ripped to the hard drive. This is done by copying the raw CD Digital Audio
   (CDDA) data to WAV files.

   The cdda2wav tool, which is installed with the sysutils/cdrtools suite,
   can be used to rip audio information from CDs.

   With the audio CD in the drive, the following command can be issued as
   root to rip an entire CD into individual, per track, WAV files:

 # cdda2wav -D 0,1,0 -B

   In this example, the -D 0,1,0 indicates the SCSI device 0,1,0 containing
   the CD to rip. Use cdrecord -scanbus to determine the correct device
   parameters for the system.

   To rip individual tracks, use -t to specify the track:

 # cdda2wav -D 0,1,0 -t 7

   To rip a range of tracks, such as track one to seven, specify a range:

 # cdda2wav -D 0,1,0 -t 1+7

   To rip from an ATAPI (IDE) CDROM drive, specify the device name in place
   of the SCSI unit numbers. For example, to rip track 7 from an IDE drive:

 # cdda2wav -D /dev/acd0 -t 7

   Alternately, dd can be used to extract audio tracks on ATAPI drives, as
   described in Section 17.5.5, "Duplicating Audio CDs".

  7.3.3. Encoding and Decoding MP3s

   Lame is a popular MP3 encoder which can be installed from the audio/lame
   port. Due to patent issues, a package is not available.

   The following command will convert the ripped WAV file audio01.wav to
   audio01.mp3:

 # lame -h -b 128 --tt "Foo Song Title" --ta "FooBar Artist" --tl "FooBar Album" \
 --ty "2014" --tc "Ripped and encoded by Foo" --tg "Genre" audio01.wav audio01.mp3

   The specified 128 kbits is a standard MP3 bitrate while the 160 and 192
   bitrates provide higher quality. The higher the bitrate, the larger the
   size of the resulting MP3. The -h turns on the "higher quality but a
   little slower" mode. The options beginning with --t indicate ID3 tags,
   which usually contain song information, to be embedded within the MP3
   file. Additional encoding options can be found in the lame manual page.

   In order to burn an audio CD from MP3s, they must first be converted to a
   non-compressed file format. XMMS can be used to convert to the WAV format,
   while mpg123 can be used to convert to the raw Pulse-Code Modulation (PCM)
   audio data format.

   To convert audio01.mp3 using mpg123, specify the name of the PCM file:

 # mpg123 -s audio01.mp3 > audio01.pcm

   To use XMMS to convert a MP3 to WAV format, use these steps:

   Procedure 7.1. Converting to WAV Format in XMMS
    1. Launch XMMS.

    2. Right-click the window to bring up the XMMS menu.

    3. Select Preferences under Options.

    4. Change the Output Plugin to "Disk Writer Plugin".

    5. Press Configure.

    6. Enter or browse to a directory to write the uncompressed files to.

    7. Load the MP3 file into XMMS as usual, with volume at 100% and EQ
       settings turned off.

    8. Press Play. The XMMS will appear as if it is playing the MP3, but no
       music will be heard. It is actually playing the MP3 to a file.

    9. When finished, be sure to set the default Output Plugin back to what
       it was before in order to listen to MP3s again.

   Both the WAV and PCM formats can be used with cdrecord. When using WAV
   files, there will be a small tick sound at the beginning of each track.
   This sound is the header of the WAV file. The audio/sox port or package
   can be used to remove the header:

 % sox -t wav -r 44100 -s -w -c 2 track.wav track.raw

   Refer to Section 17.5, "Creating and Using CD Media" for more information
   on using a CD burner in FreeBSD.

7.4. Video Playback

   Contributed by Ross Lippert.

   Before configuring video playback, determine the model and chipset of the
   video card. While Xorg supports a wide variety of video cards, not all
   provide good playback performance. To obtain a list of extensions
   supported by the Xorg server using the card, run xdpyinfo while Xorg is
   running.

   It is a good idea to have a short MPEG test file for evaluating various
   players and options. Since some DVD applications look for DVD media in
   /dev/dvd by default, or have this device name hardcoded in them, it might
   be useful to make a symbolic link to the proper device:

 # ln -sf /dev/cd0 /dev/dvd

   Due to the nature of devfs(5), manually created links will not persist
   after a system reboot. In order to recreate the symbolic link
   automatically when the system boots, add the following line to
   /etc/devfs.conf:

 link cd0 dvd

   DVD decryption invokes certain functions that require write permission to
   the DVD device.

   To enhance the shared memory Xorg interface, it is recommended to increase
   the values of these sysctl(8) variables:

 kern.ipc.shmmax=67108864
 kern.ipc.shmall=32768

  7.4.1. Determining Video Capabilities

   There are several possible ways to display video under Xorg and what works
   is largely hardware dependent. Each method described below will have
   varying quality across different hardware.

   Common video interfaces include:

    1. Xorg: normal output using shared memory.

    2. XVideo: an extension to the Xorg interface which allows video to be
       directly displayed in drawable objects through a special acceleration.
       This extension provides good quality playback even on low-end
       machines. The next section describes how to determine if this
       extension is running.

    3. SDL: the Simple Directmedia Layer is a porting layer for many
       operating systems, allowing cross-platform applications to be
       developed which make efficient use of sound and graphics. SDL provides
       a low-level abstraction to the hardware which can sometimes be more
       efficient than the Xorg interface. On FreeBSD, SDL can be installed
       using the devel/sdl20 package or port.

    4. DGA: the Direct Graphics Access is an Xorg extension which allows a
       program to bypass the Xorg server and directly alter the framebuffer.
       Because it relies on a low level memory mapping, programs using it
       must be run as root. The DGA extension can be tested and benchmarked
       using dga(1). When dga is running, it changes the colors of the
       display whenever a key is pressed. To quit, press q.

    5. SVGAlib: a low level console graphics layer.

    7.4.1.1. XVideo

   To check whether this extension is running, use xvinfo:

 % xvinfo

   XVideo is supported for the card if the result is similar to:

 X-Video Extension version 2.2
   screen #0
   Adaptor #0: "Savage Streams Engine"
     number of ports: 1
     port base: 43
     operations supported: PutImage
     supported visuals:
       depth 16, visualID 0x22
       depth 16, visualID 0x23
     number of attributes: 5
       "XV_COLORKEY" (range 0 to 16777215)
               client settable attribute
               client gettable attribute (current value is 2110)
       "XV_BRIGHTNESS" (range -128 to 127)
               client settable attribute
               client gettable attribute (current value is 0)
       "XV_CONTRAST" (range 0 to 255)
               client settable attribute
               client gettable attribute (current value is 128)
       "XV_SATURATION" (range 0 to 255)
               client settable attribute
               client gettable attribute (current value is 128)
       "XV_HUE" (range -180 to 180)
               client settable attribute
               client gettable attribute (current value is 0)
     maximum XvImage size: 1024 x 1024
     Number of image formats: 7
       id: 0x32595559 (YUY2)
         guid: 59555932-0000-0010-8000-00aa00389b71
         bits per pixel: 16
         number of planes: 1
         type: YUV (packed)
       id: 0x32315659 (YV12)
         guid: 59563132-0000-0010-8000-00aa00389b71
         bits per pixel: 12
         number of planes: 3
         type: YUV (planar)
       id: 0x30323449 (I420)
         guid: 49343230-0000-0010-8000-00aa00389b71
         bits per pixel: 12
         number of planes: 3
         type: YUV (planar)
       id: 0x36315652 (RV16)
         guid: 52563135-0000-0000-0000-000000000000
         bits per pixel: 16
         number of planes: 1
         type: RGB (packed)
         depth: 0
         red, green, blue masks: 0x1f, 0x3e0, 0x7c00
       id: 0x35315652 (RV15)
         guid: 52563136-0000-0000-0000-000000000000
         bits per pixel: 16
         number of planes: 1
         type: RGB (packed)
         depth: 0
         red, green, blue masks: 0x1f, 0x7e0, 0xf800
       id: 0x31313259 (Y211)
         guid: 59323131-0000-0010-8000-00aa00389b71
         bits per pixel: 6
         number of planes: 3
         type: YUV (packed)
       id: 0x0
         guid: 00000000-0000-0000-0000-000000000000
         bits per pixel: 0
         number of planes: 0
         type: RGB (packed)
         depth: 1
         red, green, blue masks: 0x0, 0x0, 0x0

   The formats listed, such as YUV2 and YUV12, are not present with every
   implementation of XVideo and their absence may hinder some players.

   If the result instead looks like:

 X-Video Extension version 2.2
 screen #0
 no adaptors present

   XVideo is probably not supported for the card. This means that it will be
   more difficult for the display to meet the computational demands of
   rendering video, depending on the video card and processor.

  7.4.2. Ports and Packages Dealing with Video

   This section introduces some of the software available from the FreeBSD
   Ports Collection which can be used for video playback.

    7.4.2.1. MPlayer and MEncoder

   MPlayer is a command-line video player with an optional graphical
   interface which aims to provide speed and flexibility. Other graphical
   front-ends to MPlayer are available from the FreeBSD Ports Collection.

   MPlayer can be installed using the multimedia/mplayer package or port.
   Several compile options are available and a variety of hardware checks
   occur during the build process. For these reasons, some users prefer to
   build the port rather than install the package.

   When compiling the port, the menu options should be reviewed to determine
   the type of support to compile into the port. If an option is not
   selected, MPlayer will not be able to display that type of video format.
   Use the arrow keys and spacebar to select the required formats. When
   finished, press Enter to continue the port compile and installation.

   By default, the package or port will build the mplayer command line
   utility and the gmplayer graphical utility. To encode videos, compile the
   multimedia/mencoder port. Due to licensing restrictions, a package is not
   available for MEncoder.

   The first time MPlayer is run, it will create ~/.mplayer in the user's
   home directory. This subdirectory contains default versions of the
   user-specific configuration files.

   This section describes only a few common uses. Refer to mplayer(1) for a
   complete description of its numerous options.

   To play the file testfile.avi, specify the video interfaces with -vo, as
   seen in the following examples:

 % mplayer -vo xv testfile.avi

 % mplayer -vo sdl testfile.avi

 % mplayer -vo x11 testfile.avi

 # mplayer -vo dga testfile.avi

 # mplayer -vo 'sdl:dga' testfile.avi

   It is worth trying all of these options, as their relative performance
   depends on many factors and will vary significantly with hardware.

   To play a DVD, replace testfile.avi with dvd://N -dvd-device DEVICE, where
   N is the title number to play and DEVICE is the device node for the DVD.
   For example, to play title 3 from /dev/dvd:

 # mplayer -vo xv dvd://3 -dvd-device /dev/dvd

  Note:

   The default DVD device can be defined during the build of the MPlayer port
   by including the WITH_DVD_DEVICE=/path/to/desired/device option. By
   default, the device is /dev/cd0. More details can be found in the port's
   Makefile.options.

   To stop, pause, advance, and so on, use a keybinding. To see the list of
   keybindings, run mplayer -h or read mplayer(1).

   Additional playback options include -fs -zoom, which engages fullscreen
   mode, and -framedrop, which helps performance.

   Each user can add commonly used options to their ~/.mplayer/config like
   so:

 vo=xv
 fs=yes
 zoom=yes

   mplayer can be used to rip a DVD title to a .vob. To dump the second title
   from a DVD:

 # mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd

   The output file, out.vob, will be in MPEG format.

   Anyone wishing to obtain a high level of expertise with UNIX(R) video
   should consult mplayerhq.hu/DOCS as it is technically informative. This
   documentation should be considered as required reading before submitting
   any bug reports.

   Before using mencoder, it is a good idea to become familiar with the
   options described at mplayerhq.hu/DOCS/HTML/en/mencoder.html. There are
   innumerable ways to improve quality, lower bitrate, and change formats,
   and some of these options may make the difference between good or bad
   performance. Improper combinations of command line options can yield
   output files that are unplayable even by mplayer.

   Here is an example of a simple copy:

 % mencoder input.avi -oac copy -ovc copy -o output.avi

   To rip to a file, use -dumpfile with mplayer.

   To convert input.avi to the MPEG4 codec with MPEG3 audio encoding, first
   install the audio/lame port. Due to licensing restrictions, a package is
   not available. Once installed, type:

 % mencoder input.avi -oac mp3lame -lameopts br=192 \
          -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi

   This will produce output playable by applications such as mplayer and
   xine.

   input.avi can be replaced with dvd://1 -dvd-device /dev/dvd and run as
   root to re-encode a DVD title directly. Since it may take a few tries to
   get the desired result, it is recommended to instead dump the title to a
   file and to work on the file.

    7.4.2.2. The xine Video Player

   xine is a video player with a reusable base library and a modular
   executable which can be extended with plugins. It can be installed using
   the multimedia/xine package or port.

   In practice, xine requires either a fast CPU with a fast video card, or
   support for the XVideo extension. The xine video player performs best on
   XVideo interfaces.

   By default, the xine player starts a graphical user interface. The menus
   can then be used to open a specific file.

   Alternatively, xine may be invoked from the command line by specifying the
   name of the file to play:

 % xine -g -p mymovie.avi

   Refer to xine-project.org/faq for more information and troubleshooting
   tips.

    7.4.2.3. The Transcode Utilities

   Transcode provides a suite of tools for re-encoding video and audio files.
   Transcode can be used to merge video files or repair broken files using
   command line tools with stdin/stdout stream interfaces.

   In FreeBSD, Transcode can be installed using the multimedia/transcode
   package or port. Many users prefer to compile the port as it provides a
   menu of compile options for specifying the support and codecs to compile
   in. If an option is not selected, Transcode will not be able to encode
   that format. Use the arrow keys and spacebar to select the required
   formats. When finished, press Enter to continue the port compile and
   installation.

   This example demonstrates how to convert a DivX file into a PAL MPEG-1
   file (PAL VCD):

 % transcode -i input.avi -V --export_prof vcd-pal -o output_vcd
 % mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa

   The resulting MPEG file, output_vcd.mpg, is ready to be played with
   MPlayer. The file can be burned on a CD media to create a video CD using a
   utility such as multimedia/vcdimager or sysutils/cdrdao.

   In addition to the manual page for transcode, refer to
   transcoding.org/cgi-bin/transcode for further information and examples.

7.5. TV Cards

   Original contribution by Josef El-Rayes.
   Enhanced and adapted by Marc Fonvieille.

   TV cards can be used to watch broadcast or cable TV on a computer. Most
   cards accept composite video via an RCA or S-video input and some cards
   include a FM radio tuner.

   FreeBSD provides support for PCI-based TV cards using a Brooktree
   Bt848/849/878/879 video capture chip with the bktr(4) driver. This driver
   supports most Pinnacle PCTV video cards. Before purchasing a TV card,
   consult bktr(4) for a list of supported tuners.

  7.5.1. Loading the Driver

   In order to use the card, the bktr(4) driver must be loaded. To automate
   this at boot time, add the following line to /boot/loader.conf:

 bktr_load="YES"

   Alternatively, one can statically compile support for the TV card into a
   custom kernel. In that case, add the following lines to the custom kernel
   configuration file:

 device   bktr
 device  iicbus
 device  iicbb
 device  smbus

   These additional devices are necessary as the card components are
   interconnected via an I2C bus. Then, build and install a new kernel.

   To test that the tuner is correctly detected, reboot the system. The TV
   card should appear in the boot messages, as seen in this example:

 bktr0:  mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
 iicbb0:  on bti2c0
 iicbus0:  on iicbb0 master-only
 iicbus1:  on iicbb0 master-only
 smbus0:  on bti2c0
 bktr0: Pinnacle/Miro TV, Philips SECAM tuner.

   The messages will differ according to the hardware. If necessary, it is
   possible to override some of the detected parameters using sysctl(8) or
   custom kernel configuration options. For example, to force the tuner to a
   Philips SECAM tuner, add the following line to a custom kernel
   configuration file:

 options OVERRIDE_TUNER=6

   or, use sysctl(8):

 # sysctl hw.bt848.tuner=6

   Refer to bktr(4) for a description of the available sysctl(8) parameters
   and kernel options.

  7.5.2. Useful Applications

   To use the TV card, install one of the following applications:

     * multimedia/fxtv provides TV-in-a-window and image/audio/video capture
       capabilities.

     * multimedia/xawtv is another TV application with similar features.

     * audio/xmradio provides an application for using the FM radio tuner of
       a TV card.

   More applications are available in the FreeBSD Ports Collection.

  7.5.3. Troubleshooting

   If any problems are encountered with the TV card, check that the video
   capture chip and the tuner are supported by bktr(4) and that the right
   configuration options were used. For more support or to ask questions
   about supported TV cards, refer to the freebsd-multimedia mailing list.

7.6. MythTV

   MythTV is a popular, open source Personal Video Recorder (PVR)
   application. This section demonstrates how to install and setup MythTV on
   FreeBSD. Refer to mythtv.org/wiki for more information on how to use
   MythTV.

   MythTV requires a frontend and a backend. These components can either be
   installed on the same system or on different machines.

   The frontend can be installed on FreeBSD using the
   multimedia/mythtv-frontend package or port. Xorg must also be installed
   and configured as described in Chapter 5, The X Window System. Ideally,
   this system has a video card that supports X-Video Motion Compensation
   (XvMC) and, optionally, a Linux Infrared Remote Control (LIRC)-compatible
   remote.

   To install both the backend and the frontend on FreeBSD, use the
   multimedia/mythtv package or port. A MySQL(TM) database server is also
   required and should automatically be installed as a dependency.
   Optionally, this system should have a tuner card and sufficient storage to
   hold recorded data.

  7.6.1. Hardware

   MythTV uses Video for Linux (V4L) to access video input devices such as
   encoders and tuners. In FreeBSD, MythTV works best with USB DVB-S/C/T
   cards as they are well supported by the multimedia/webcamd package or port
   which provides a V4L userland application. Any Digital Video Broadcasting
   (DVB) card supported by webcamd should work with MythTV. A list of known
   working cards can be found at wiki.freebsd.org/WebcamCompat. Drivers are
   also available for Hauppauge cards in the multimedia/pvr250 and
   multimedia/pvrxxx ports, but they provide a non-standard driver interface
   that does not work with versions of MythTV greater than 0.23. Due to
   licensing restrictions, no packages are available and these two ports must
   be compiled.

   The wiki.freebsd.org/HTPC page contains a list of all available DVB
   drivers.

  7.6.2. Setting up the MythTV Backend

   To install MythTV using binary packages:

 # pkg install mythtv

   Alternatively, to install from the Ports Collection:

 # cd /usr/ports/multimedia/mythtv
 # make install

   Once installed, set up the MythTV database:

 # mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql

   Then, configure the backend:

 # mythtv-setup

   Finally, start the backend:

 # sysrc mythbackend_enable=yes
 # service mythbackend start

7.7. Image Scanners

   Written by Marc Fonvieille.

   In FreeBSD, access to image scanners is provided by SANE (Scanner Access
   Now Easy), which is available in the FreeBSD Ports Collection. SANE will
   also use some FreeBSD device drivers to provide access to the scanner
   hardware.

   FreeBSD supports both SCSI and USB scanners. Depending upon the scanner
   interface, different device drivers are required. Be sure the scanner is
   supported by SANE prior to performing any configuration. Refer to
   http://www.sane-project.org/sane-supported-devices.html for more
   information about supported scanners.

   This chapter describes how to determine if the scanner has been detected
   by FreeBSD. It then provides an overview of how to configure and use SANE
   on a FreeBSD system.

  7.7.1. Checking the Scanner

   The GENERIC kernel includes the device drivers needed to support USB
   scanners. Users with a custom kernel should ensure that the following
   lines are present in the custom kernel configuration file:

 device usb
 device uhci
 device ohci
 device ehci

   To determine if the USB scanner is detected, plug it in and use dmesg to
   determine whether the scanner appears in the system message buffer. If it
   does, it should display a message similar to this:

 ugen0.2:  at usbus0

   In this example, an EPSON Perfection(R) 1650 USB scanner was detected on
   /dev/ugen0.2.

   If the scanner uses a SCSI interface, it is important to know which SCSI
   controller board it will use. Depending upon the SCSI chipset, a custom
   kernel configuration file may be needed. The GENERIC kernel supports the
   most common SCSI controllers. Refer to /usr/src/sys/conf/NOTES to
   determine the correct line to add to a custom kernel configuration file.
   In addition to the SCSI adapter driver, the following lines are needed in
   a custom kernel configuration file:

 device scbus
 device pass

   Verify that the device is displayed in the system message buffer:

 pass2 at aic0 bus 0 target 2 lun 0
 pass2:  Fixed Scanner SCSI-2 device
 pass2: 3.300MB/s transfers

   If the scanner was not powered-on at system boot, it is still possible to
   manually force detection by performing a SCSI bus scan with camcontrol:

 # camcontrol rescan all
 Re-scan of bus 0 was successful
 Re-scan of bus 1 was successful
 Re-scan of bus 2 was successful
 Re-scan of bus 3 was successful

   The scanner should now appear in the SCSI devices list:

 # camcontrol devlist
               at scbus0 target 5 lun 0 (pass0,da0)
               at scbus0 target 6 lun 0 (pass1,da1)
            at scbus1 target 2 lun 0 (pass3)
      at scbus2 target 0 lun 0 (pass2,cd0)

   Refer to scsi(4) and camcontrol(8) for more details about SCSI devices on
   FreeBSD.

  7.7.2. SANE Configuration

   The SANE system is split in two parts: the backends
   (graphics/sane-backends) and the frontends (graphics/sane-frontends or
   graphics/xsane). The backends provide access to the scanner. Refer to
   http://www.sane-project.org/sane-supported-devices.html to determine which
   backend supports the scanner. The frontends provide the graphical scanning
   interface. graphics/sane-frontends installs xscanimage while
   graphics/xsane installs xsane.

   To install the two parts from binary packages:

 # pkg install xsane sane-frontends

   Alternatively, to install from the Ports Collection

 # cd /usr/ports/graphics/sane-frontends
 # make install clean
 # cd /usr/ports/graphics/xsane
 # make install clean

   After installing the graphics/sane-backends port or package, use
   sane-find-scanner to check the scanner detection by the SANE system:

 # sane-find-scanner -q
 found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3

   The output should show the interface type of the scanner and the device
   node used to attach the scanner to the system. The vendor and the product
   model may or may not appear.

  Note:

   Some USB scanners require firmware to be loaded. Refer to
   sane-find-scanner(1) and sane(7) for details.

   Next, check if the scanner will be identified by a scanning frontend. The
   SANE backends include scanimage which can be used to list the devices and
   perform an image acquisition. Use -L to list the scanner devices. The
   first example is for a SCSI scanner and the second is for a USB scanner:

 # scanimage -L
 device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner
 # scanimage -L
 device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner

   In this second example, 'epson2:libusb:/dev/usb:/dev/ugen0.2' is the
   backend name (epson2) and /dev/ugen0.2 is the device node used by the
   scanner.

   If scanimage is unable to identify the scanner, this message will appear:

 # scanimage -L

 No scanners were identified. If you were expecting something different,
 check that the scanner is plugged in, turned on and detected by the
 sane-find-scanner tool (if appropriate). Please read the documentation
 which came with this software (README, FAQ, manpages).

   If this happens, edit the backend configuration file in
   /usr/local/etc/sane.d/ and define the scanner device used. For example, if
   the undetected scanner model is an EPSON Perfection(R) 1650 and it uses
   the epson2 backend, edit /usr/local/etc/sane.d/epson2.conf. When editing,
   add a line specifying the interface and the device node used. In this
   case, add the following line:

 usb /dev/ugen0.2

   Save the edits and verify that the scanner is identified with the right
   backend name and the device node:

 # scanimage -L
 device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner

   Once scanimage -L sees the scanner, the configuration is complete and the
   scanner is now ready to use.

   While scanimage can be used to perform an image acquisition from the
   command line, it is often preferable to use a graphical interface to
   perform image scanning. The graphics/sane-frontends package or port
   installs a simple but efficient graphical interface, xscanimage.

   Alternately, xsane, which is installed with the graphics/xsane package or
   port, is another popular graphical scanning frontend. It offers advanced
   features such as various scanning modes, color correction, and batch
   scans. Both of these applications are usable as a GIMP plugin.

  7.7.3. Scanner Permissions

   In order to have access to the scanner, a user needs read and write
   permissions to the device node used by the scanner. In the previous
   example, the USB scanner uses the device node /dev/ugen0.2 which is really
   a symlink to the real device node /dev/usb/0.2.0. The symlink and the
   device node are owned, respectively, by the wheel and operator groups.
   While adding the user to these groups will allow access to the scanner, it
   is considered insecure to add a user to wheel. A better solution is to
   create a group and make the scanner device accessible to members of this
   group.

   This example creates a group called usb:

 # pw groupadd usb

   Then, make the /dev/ugen0.2 symlink and the /dev/usb/0.2.0 device node
   accessible to the usb group with write permissions of 0660 or 0664 by
   adding the following lines to /etc/devfs.rules:

 [system=5]
 add path ugen0.2 mode 0660 group usb
 add path usb/0.2.0 mode 0666 group usb

   Finally, add the users to usb in order to allow access to the scanner:

 # pw groupmod usb -m joe

   For more details refer to pw(8).

Chapter 8. Configuring the FreeBSD Kernel

   Table of Contents

   8.1. Synopsis

   8.2. Why Build a Custom Kernel?

   8.3. Finding the System Hardware

   8.4. The Configuration File

   8.5. Building and Installing a Custom Kernel

   8.6. If Something Goes Wrong

8.1. Synopsis

   The kernel is the core of the FreeBSD operating system. It is responsible
   for managing memory, enforcing security controls, networking, disk access,
   and much more. While much of FreeBSD is dynamically configurable, it is
   still occasionally necessary to configure and compile a custom kernel.

   After reading this chapter, you will know:

     * When to build a custom kernel.

     * How to take a hardware inventory.

     * How to customize a kernel configuration file.

     * How to use the kernel configuration file to create and build a new
       kernel.

     * How to install the new kernel.

     * How to troubleshoot if things go wrong.

   All of the commands listed in the examples in this chapter should be
   executed as root.

8.2. Why Build a Custom Kernel?

   Traditionally, FreeBSD used a monolithic kernel. The kernel was one large
   program, supported a fixed list of devices, and in order to change the
   kernel's behavior, one had to compile and then reboot into a new kernel.

   Today, most of the functionality in the FreeBSD kernel is contained in
   modules which can be dynamically loaded and unloaded from the kernel as
   necessary. This allows the running kernel to adapt immediately to new
   hardware and for new functionality to be brought into the kernel. This is
   known as a modular kernel.

   Occasionally, it is still necessary to perform static kernel
   configuration. Sometimes the needed functionality is so tied to the kernel
   that it can not be made dynamically loadable. Some security environments
   prevent the loading and unloading of kernel modules and require that only
   needed functionality is statically compiled into the kernel.

   Building a custom kernel is often a rite of passage for advanced BSD
   users. This process, while time consuming, can provide benefits to the
   FreeBSD system. Unlike the GENERIC kernel, which must support a wide range
   of hardware, a custom kernel can be stripped down to only provide support
   for that computer's hardware. This has a number of benefits, such as:

     * Faster boot time. Since the kernel will only probe the hardware on the
       system, the time it takes the system to boot can decrease.

     * Lower memory usage. A custom kernel often uses less memory than the
       GENERIC kernel by omitting unused features and device drivers. This is
       important because the kernel code remains resident in physical memory
       at all times, preventing that memory from being used by applications.
       For this reason, a custom kernel is useful on a system with a small
       amount of RAM.

     * Additional hardware support. A custom kernel can add support for
       devices which are not present in the GENERIC kernel.

   Before building a custom kernel, consider the reason for doing so. If
   there is a need for specific hardware support, it may already exist as a
   module.

   Kernel modules exist in /boot/kernel and may be dynamically loaded into
   the running kernel using kldload(8). Most kernel drivers have a loadable
   module and manual page. For example, the ath(4) wireless Ethernet driver
   has the following information in its manual page:

 Alternatively, to load the driver as a module at boot time, place the
 following line in loader.conf(5):

     if_ath_load="YES"

   Adding if_ath_load="YES" to /boot/loader.conf will load this module
   dynamically at boot time.

   In some cases, there is no associated module in /boot/kernel. This is
   mostly true for certain subsystems.

8.3. Finding the System Hardware

   Before editing the kernel configuration file, it is recommended to perform
   an inventory of the machine's hardware. On a dual-boot system, the
   inventory can be created from the other operating system. For example,
   Microsoft(R)'s Device Manager contains information about installed
   devices.

  Note:

   Some versions of Microsoft(R) Windows(R) have a System icon which can be
   used to access Device Manager.

   If FreeBSD is the only installed operating system, use dmesg(8) to
   determine the hardware that was found and listed during the boot probe.
   Most device drivers on FreeBSD have a manual page which lists the hardware
   supported by that driver. For example, the following lines indicate that
   the psm(4) driver found a mouse:

 psm0:  irq 12 on atkbdc0
 psm0: [GIANT-LOCKED]
 psm0: [ITHREAD]
 psm0: model Generic PS/2 mouse, device ID 0

   Since this hardware exists, this driver should not be removed from a
   custom kernel configuration file.

   If the output of dmesg does not display the results of the boot probe
   output, instead read the contents of /var/run/dmesg.boot.

   Another tool for finding hardware is pciconf(8), which provides more
   verbose output. For example:

 % pciconf -lv
 ath0@pci0:3:0:0:        class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
     vendor     = 'Atheros Communications Inc.'
     device     = 'AR5212 Atheros AR5212 802.11abg wireless'
     class      = network
     subclass   = ethernet

   This output shows that the ath driver located a wireless Ethernet device.

   The -k flag of man(1) can be used to provide useful information. For
   example, it can be used to display a list of manual pages which contain a
   particular device brand or name:

 # man -k Atheros
 ath(4)                   - Atheros IEEE 802.11 wireless network driver
 ath_hal(4)               - Atheros Hardware Access Layer (HAL)

   Once the hardware inventory list is created, refer to it to ensure that
   drivers for installed hardware are not removed as the custom kernel
   configuration is edited.

8.4. The Configuration File

   In order to create a custom kernel configuration file and build a custom
   kernel, the full FreeBSD source tree must first be installed.

   If /usr/src/ does not exist or it is empty, source has not been installed.
   Source can be installed using Subversion and the instructions in
   Section A.3, "Using Subversion".

   Once source is installed, review the contents of /usr/src/sys. This
   directory contains a number of subdirectories, including those which
   represent the following supported architectures: amd64, i386, ia64,
   powerpc, and sparc64. Everything inside a particular architecture's
   directory deals with that architecture only and the rest of the code is
   machine independent code common to all platforms. Each supported
   architecture has a conf subdirectory which contains the GENERIC kernel
   configuration file for that architecture.

   Do not make edits to GENERIC. Instead, copy the file to a different name
   and make edits to the copy. The convention is to use a name with all
   capital letters. When maintaining multiple FreeBSD machines with different
   hardware, it is a good idea to name it after the machine's hostname. This
   example creates a copy, named MYKERNEL, of the GENERIC configuration file
   for the amd64 architecture:

 # cd /usr/src/sys/amd64/conf
 # cp GENERIC MYKERNEL

   MYKERNEL can now be customized with any ASCII text editor. The default
   editor is vi, though an easier editor for beginners, called ee, is also
   installed with FreeBSD.

   The format of the kernel configuration file is simple. Each line contains
   a keyword that represents a device or subsystem, an argument, and a brief
   description. Any text after a # is considered a comment and ignored. To
   remove kernel support for a device or subsystem, put a # at the beginning
   of the line representing that device or subsystem. Do not add or remove a
   # for any line that you do not understand.

  Warning:

   It is easy to remove support for a device or option and end up with a
   broken kernel. For example, if the ata(4) driver is removed from the
   kernel configuration file, a system using ATA disk drivers may not boot.
   When in doubt, just leave support in the kernel.

   In addition to the brief descriptions provided in this file, additional
   descriptions are contained in NOTES, which can be found in the same
   directory as GENERIC for that architecture. For architecture independent
   options, refer to /usr/src/sys/conf/NOTES.

  Tip:

   When finished customizing the kernel configuration file, save a backup
   copy to a location outside of /usr/src.

   Alternately, keep the kernel configuration file elsewhere and create a
   symbolic link to the file:

 # cd /usr/src/sys/amd64/conf
 # mkdir /root/kernels
 # cp GENERIC /root/kernels/MYKERNEL
 # ln -s /root/kernels/MYKERNEL

   An include directive is available for use in configuration files. This
   allows another configuration file to be included in the current one,
   making it easy to maintain small changes relative to an existing file. If
   only a small number of additional options or drivers are required, this
   allows a delta to be maintained with respect to GENERIC, as seen in this
   example:

 include GENERIC
 ident MYKERNEL

 options         IPFIREWALL
 options         DUMMYNET
 options         IPFIREWALL_DEFAULT_TO_ACCEPT
 options         IPDIVERT

   Using this method, the local configuration file expresses local
   differences from a GENERIC kernel. As upgrades are performed, new features
   added to GENERIC will also be added to the local kernel unless they are
   specifically prevented using nooptions or nodevice. A comprehensive list
   of configuration directives and their descriptions may be found in
   config(5).

  Note:

   To build a file which contains all available options, run the following
   command as root:

 # cd /usr/src/sys/arch/conf && make LINT

8.5. Building and Installing a Custom Kernel

   Once the edits to the custom configuration file have been saved, the
   source code for the kernel can be compiled using the following steps:

   Procedure 8.1. Building a Kernel
    1. Change to this directory:

 # cd /usr/src

    2. Compile the new kernel by specifying the name of the custom kernel
       configuration file:

 # make buildkernel KERNCONF=MYKERNEL

    3. Install the new kernel associated with the specified kernel
       configuration file. This command will copy the new kernel to
       /boot/kernel/kernel and save the old kernel to
       /boot/kernel.old/kernel:

 # make installkernel KERNCONF=MYKERNEL

    4. Shutdown the system and reboot into the new kernel. If something goes
       wrong, refer to The kernel does not boot.

   By default, when a custom kernel is compiled, all kernel modules are
   rebuilt. To update a kernel faster or to build only custom modules, edit
   /etc/make.conf before starting to build the kernel.

   For example, this variable specifies the list of modules to build instead
   of using the default of building all modules:

 MODULES_OVERRIDE = linux acpi

   Alternately, this variable lists which modules to exclude from the build
   process:

 WITHOUT_MODULES = linux acpi sound

   Additional variables are available. Refer to make.conf(5) for details.

8.6. If Something Goes Wrong

   There are four categories of trouble that can occur when building a custom
   kernel:

   config fails

           If config fails, it will print the line number that is incorrect.
           As an example, for the following message, make sure that line 17
           is typed correctly by comparing it to GENERIC or NOTES:

 config: line 17: syntax error

   make fails

           If make fails, it is usually due to an error in the kernel
           configuration file which is not severe enough for config to catch.
           Review the configuration, and if the problem is not apparent, send
           an email to the FreeBSD general questions mailing list which
           contains the kernel configuration file.

   The kernel does not boot

           If the new kernel does not boot or fails to recognize devices, do
           not panic! Fortunately, FreeBSD has an excellent mechanism for
           recovering from incompatible kernels. Simply choose the kernel to
           boot from at the FreeBSD boot loader. This can be accessed when
           the system boot menu appears by selecting the "Escape to a loader
           prompt" option. At the prompt, type boot kernel.old, or the name
           of any other kernel that is known to boot properly.

           After booting with a good kernel, check over the configuration
           file and try to build it again. One helpful resource is
           /var/log/messages which records the kernel messages from every
           successful boot. Also, dmesg(8) will print the kernel messages
           from the current boot.

  Note:

           When troubleshooting a kernel, make sure to keep a copy of
           GENERIC, or some other kernel that is known to work, as a
           different name that will not get erased on the next build. This is
           important because every time a new kernel is installed, kernel.old
           is overwritten with the last installed kernel, which may or may
           not be bootable. As soon as possible, move the working kernel by
           renaming the directory containing the good kernel:

 # mv /boot/kernel /boot/kernel.bad
 # mv /boot/kernel.good /boot/kernel

   The kernel works, but ps(1) does not

           If the kernel version differs from the one that the system
           utilities have been built with, for example, a kernel built from
           -CURRENT sources is installed on a -RELEASE system, many system
           status commands like ps(1) and vmstat(8) will not work. To fix
           this, recompile and install a world built with the same version of
           the source tree as the kernel. It is never a good idea to use a
           different version of the kernel than the rest of the operating
           system.

Chapter 9. Printing

   Originally contributed by Warren Block.
   Table of Contents

   9.1. Quick Start

   9.2. Printer Connections

   9.3. Common Page Description Languages

   9.4. Direct Printing

   9.5. LPD (Line Printer Daemon)

   9.6. Other Printing Systems

   Putting information on paper is a vital function, despite many attempts to
   eliminate it. Printing has two basic components. The data must be
   delivered to the printer, and must be in a form that the printer can
   understand.

9.1. Quick Start

   Basic printing can be set up quickly. The printer must be capable of
   printing plain ASCII text. For printing to other types of files, see
   Section 9.5.3, "Filters".

    1. Create a directory to store files while they are being printed:

 # mkdir -p /var/spool/lpd/lp
 # chown daemon:daemon /var/spool/lpd/lp
 # chmod 770 /var/spool/lpd/lp

    2. As root, create /etc/printcap with these contents:

 lp:\
         :lp=/dev/unlpt0:\  1
         :sh:\
         :mx#0:\
         :sd=/var/spool/lpd/lp:\
         :lf=/var/log/lpd-errs:

       1 This line is for a printer connected to a USB port.                  
                                                                              
         For a printer connected to a parallel or "printer" port, use:        
                                                                              
         :lp=/dev/lpt0:\                                                      
                                                                              
         For a printer connected directly to a network, use:                  
                                                                              
         :lp=:rm=network-printer-name:rp=raw:\                                
                                                                              
         Replace network-printer-name with the DNS host name of the network   
         printer.                                                             

    3. Enable lpd by editing /etc/rc.conf, adding this line:

 lpd_enable="YES"

       Start the service:

 # service lpd start
 Starting lpd.

    4. Print a test:

 # printf "1. This printer can print.\n2. This is the second line.\n" | lpr

  Tip:

       If both lines do not start at the left border, but "stairstep"
       instead, see Section 9.5.3.1, "Preventing Stairstepping on Plain Text
       Printers".

       Text files can now be printed with lpr. Give the filename on the
       command line, or pipe output directly into lpr.

 % lpr textfile.txt
 % ls -lh | lpr

9.2. Printer Connections

   Printers are connected to computer systems in a variety of ways. Small
   desktop printers are usually connected directly to a computer's USB port.
   Older printers are connected to a parallel or "printer" port. Some
   printers are directly connected to a network, making it easy for multiple
   computers to share them. A few printers use a rare serial port connection.

   FreeBSD can communicate with all of these types of printers.

   USB

           USB printers can be connected to any available USB port on the
           computer.

           When FreeBSD detects a USB printer, two device entries are
           created: /dev/ulpt0 and /dev/unlpt0. Data sent to either device
           will be relayed to the printer. After each print job, ulpt0 resets
           the USB port. Resetting the port can cause problems with some
           printers, so the unlpt0 device is usually used instead. unlpt0
           does not reset the USB port at all.

   Parallel (IEEE-1284)

           The parallel port device is /dev/lpt0. This device appears whether
           a printer is attached or not, it is not autodetected.

           Vendors have largely moved away from these "legacy" ports, and
           many computers no longer have them. Adapters can be used to
           connect a parallel printer to a USB port. With such an adapter,
           the printer can be treated as if it were actually a USB printer.
           Devices called print servers can also be used to connect parallel
           printers directly to a network.

   Serial (RS-232)

           Serial ports are another legacy port, rarely used for printers
           except in certain niche applications. Cables, connectors, and
           required wiring vary widely.

           For serial ports built into a motherboard, the serial device name
           is /dev/cuau0 or /dev/cuau1. Serial USB adapters can also be used,
           and these will appear as /dev/cuaU0.

           Several communication parameters must be known to communicate with
           a serial printer. The most important are baud rate or BPS (Bits
           Per Second) and parity. Values vary, but typical serial printers
           use a baud rate of 9600 and no parity.

   Network

           Network printers are connected directly to the local computer
           network.

           The DNS hostname of the printer must be known. If the printer is
           assigned a dynamic address by DHCP, DNS should be dynamically
           updated so that the host name always has the correct IP address.
           Network printers are often given static IP addresses to avoid this
           problem.

           Most network printers understand print jobs sent with the LPD
           protocol. A print queue name can also be specified. Some printers
           process data differently depending on which queue is used. For
           example, a raw queue prints the data unchanged, while the text
           queue adds carriage returns to plain text.

           Many network printers can also print data sent directly to port
           9100.

  9.2.1. Summary

   Wired network connections are usually the easiest to set up and give the
   fastest printing. For direct connection to the computer, USB is preferred
   for speed and simplicity. Parallel connections work but have limitations
   on cable length and speed. Serial connections are more difficult to
   configure. Cable wiring differs between models, and communication
   parameters like baud rate and parity bits must add to the complexity.
   Fortunately, serial printers are rare.

9.3. Common Page Description Languages

   Data sent to a printer must be in a language that the printer can
   understand. These languages are called Page Description Languages, or
   PDLs.

   ASCII

           Plain ASCII text is the simplest way to send data to a printer.
           Characters correspond one to one with what will be printed: an A
           in the data prints an A on the page. Very little formatting is
           available. There is no way to select a font or proportional
           spacing. The forced simplicity of plain ASCII means that text can
           be printed straight from the computer with little or no encoding
           or translation. The printed output corresponds directly with what
           was sent.

           Some inexpensive printers cannot print plain ASCII text. This
           makes them more difficult to set up, but it is usually still
           possible.

   PostScript(R)

           PostScript(R) is almost the opposite of ASCII. Rather than simple
           text, a PostScript(R) program is a set of instructions that draw
           the final document. Different fonts and graphics can be used.
           However, this power comes at a price. The program that draws the
           page must be written. Usually this program is generated by
           application software, so the process is invisible to the user.

           Inexpensive printers sometimes leave out PostScript(R)
           compatibility as a cost-saving measure.

   PCL (Printer Command Language)

           PCL is an extension of ASCII, adding escape sequences for
           formatting, font selection, and printing graphics. Many printers
           provide PCL5 support. Some support the newer PCL6 or PCLXL. These
           later versions are supersets of PCL5 and can provide faster
           printing.

   Host-Based

           Manufacturers can reduce the cost of a printer by giving it a
           simple processor and very little memory. These printers are not
           capable of printing plain text. Instead, bitmaps of text and
           graphics are drawn by a driver on the host computer and then sent
           to the printer. These are called host-based printers.

           Communication between the driver and a host-based printer is often
           through proprietary or undocumented protocols, making them
           functional only on the most common operating systems.

  9.3.1. Converting PostScript(R) to Other PDLs

   Many applications from the Ports Collection and FreeBSD utilities produce
   PostScript(R) output. This table shows the utilities available to convert
   that into other common PDLs:

   Table 9.1. Output PDLs

   Output PDL    Generated By            Notes                                
   PCL or PCL5   print/ghostscript9-base -sDEVICE=ljet4 for monochrome,       
                                         -sDEVICE=cljet5 for color            
   PCLXL or PCL6 print/ghostscript9-base -sDEVICE=pxlmono for monochrome,     
                                         -sDEVICE=pxlcolor for color          
   ESC/P2        print/ghostscript9-base -sDEVICE=uniprint                    
   XQX           print/foo2zjs                                                

  9.3.2. Summary

   For the easiest printing, choose a printer that supports PostScript(R).
   Printers that support PCL are the next preferred. With
   print/ghostscript9-base, these printers can be used as if they understood
   PostScript(R) natively. Printers that support PostScript(R) or PCL
   directly almost always support direct printing of plain ASCII text files
   also.

   Line-based printers like typical inkjets usually do not support
   PostScript(R) or PCL. They often can print plain ASCII text files.
   print/ghostscript9-base supports the PDLs used by some of these printers.
   However, printing an entire graphic-based page on these printers is often
   very slow due to the large amount of data to be transferred and printed.

   Host-based printers are often more difficult to set up. Some cannot be
   used at all because of proprietary PDLs. Avoid these printers when
   possible.

   Descriptions of many PDLs can be found at
   http://www.undocprint.org/formats/page_description_languages. The
   particular PDL used by various models of printers can be found at
   http://www.openprinting.org/printers.

9.4. Direct Printing

   For occasional printing, files can be sent directly to a printer device
   without any setup. For example, a file called sample.txt can be sent to a
   USB printer:

 # cp sample.txt /dev/unlpt0

   Direct printing to network printers depends on the abilities of the
   printer, but most accept print jobs on port 9100, and nc(1) can be used
   with them. To print the same file to a printer with the DNS hostname of
   netlaser:

 # nc netlaser 9100 < sample.txt

9.5. LPD (Line Printer Daemon)

   Printing a file in the background is called spooling. A spooler allows the
   user to continue with other programs on the computer without waiting for
   the printer to slowly complete the print job.

   FreeBSD includes a spooler called lpd(8). Print jobs are submitted with
   lpr(1).

  9.5.1. Initial Setup

   A directory for storing print jobs is created, ownership is set, and the
   permissions are set to prevent other users from viewing the contents of
   those files:

 # mkdir -p /var/spool/lpd/lp
 # chown daemon:daemon /var/spool/lpd/lp
 # chmod 770 /var/spool/lpd/lp

   Printers are defined in /etc/printcap. An entry for each printer includes
   details like a name, the port where it is attached, and various other
   settings. Create /etc/printcap with these contents:

 lp:\                            1
         :lp=/dev/unlpt0:\       2
         :sh:\                   3
         :mx#0:\                 4
         :sd=/var/spool/lpd/lp:\ 5
         :lf=/var/log/lpd-errs:  6

   1 The name of this printer. lpr(1) sends print jobs to the lp printer      
     unless another printer is specified with -P, so the default printer      
     should be named lp.                                                      
   2 The device where the printer is connected. Replace this line with the    
     appropriate one for the connection type shown here.                      
                                                                              
     +----------------------------------------------------------------------+ 
     | Connection Type |           Device Entry in /etc/printcap            | 
     |-----------------+----------------------------------------------------| 
     |                 |:lp=/dev/unlpt0:\                                   | 
     |                 |                                                    | 
     | USB             | This is the non-resetting USB printer device. If   | 
     |                 | problems are experienced, use ulpt0 instead, which | 
     |                 | resets the USB port on each use.                   | 
     |-----------------+----------------------------------------------------| 
     | Parallel        |:lp=/dev/lpt0:\                                     | 
     |-----------------+----------------------------------------------------| 
     |                 | For a printer supporting the LPD protocol:         | 
     |                 |                                                    | 
     |                 |:lp=:rm=network-printer-name:rp=raw:\               | 
     |                 |                                                    | 
     | Network         | For printers supporting port 9100 printing:        | 
     |                 |                                                    | 
     |                 |:lp=9100@network-printer-name:\                     | 
     |                 |                                                    | 
     |                 | For both types, replace network-printer-name with  | 
     |                 | the DNS host name of the network printer.          | 
     |-----------------+----------------------------------------------------| 
     |                 |:lp=/dev/cuau0:br=9600:pa=none:\                    | 
     |                 |                                                    | 
     | Serial          | These values are for a typical serial printer      | 
     |                 | connected to a motherboard serial port. The baud   | 
     |                 | rate is 9600, and no parity is used.               | 
     +----------------------------------------------------------------------+ 
   3 Suppress the printing of a header page at the start of a print job.      
   4 Do not limit the maximum size of a print job.                            
   5 The path to the spooling directory for this printer. Each printer uses   
     its own spooling directory.                                              
   6 The log file where errors on this printer will be reported.              

   After creating /etc/printcap, use chkprintcap(8) to test it for errors:

 # chkprintcap

   Fix any reported problems before continuing.

   Enable lpd(8) in /etc/rc.conf:

 lpd_enable="YES"

   Start the service:

 # service lpd start

  9.5.2. Printing with lpr(1)

   Documents are sent to the printer with lpr. A file to be printed can be
   named on the command line or piped into lpr. These two commands are
   equivalent, sending the contents of doc.txt to the default printer:

 % lpr doc.txt
 % cat doc.txt | lpr

   Printers can be selected with -P. To print to a printer called laser:

 % lpr -Plaser doc.txt

  9.5.3. Filters

   The examples shown so far have sent the contents of a text file directly
   to the printer. As long as the printer understands the content of those
   files, output will be printed correctly.

   Some printers are not capable of printing plain text, and the input file
   might not even be plain text.

   Filters allow files to be translated or processed. The typical use is to
   translate one type of input, like plain text, into a form that the printer
   can understand, like PostScript(R) or PCL. Filters can also be used to
   provide additional features, like adding page numbers or highlighting
   source code to make it easier to read.

   The filters discussed here are input filters or text filters. These
   filters convert the incoming file into different forms. Use su(1) to
   become root before creating the files.

   Filters are specified in /etc/printcap with the if= identifier. To use
   /usr/local/libexec/lf2crlf as a filter, modify /etc/printcap like this:

 lp:\
         :lp=/dev/unlpt0:\
         :sh:\
         :mx#0:\
         :sd=/var/spool/lpd/lp:\
         :if=/usr/local/libexec/lf2crlf:\   1
         :lf=/var/log/lpd-errs:

   1   if= identifies the input filter that will be used on incoming text.  

  Tip:

   The backslash line continuation characters at the end of the lines in
   printcap entries reveal that an entry for a printer is really just one
   long line with entries delimited by colon characters. An earlier example
   can be rewritten as a single less-readable line:

 lp:lp=/dev/unlpt0:sh:mx#0:sd=/var/spool/lpd/lp:if=/usr/local/libexec/lf2crlf:lf=/var/log/lpd-errs:

    9.5.3.1. Preventing Stairstepping on Plain Text Printers

   Typical FreeBSD text files contain only a single line feed character at
   the end of each line. These lines will "stairstep" on a standard printer:

 A printed file looks
                     like the steps of a staircase
                                                  scattered by the wind

   A filter can convert the newline characters into carriage returns and
   newlines. The carriage returns make the printer return to the left after
   each line. Create /usr/local/libexec/lf2crlf with these contents:

 #!/bin/sh
 CR=$'\r'
 /usr/bin/sed -e "s/$/${CR}/g"

   Set the permissions and make it executable:

 # chmod 555 /usr/local/libexec/lf2crlf

   Modify /etc/printcap to use the new filter:

 :if=/usr/local/libexec/lf2crlf:\

   Test the filter by printing the same plain text file. The carriage returns
   will cause each line to start at the left side of the page.

    9.5.3.2. Fancy Plain Text on PostScript(R) Printers with print/enscript

   GNU Enscript converts plain text files into nicely-formatted PostScript(R)
   for printing on PostScript(R) printers. It adds page numbers, wraps long
   lines, and provides numerous other features to make printed text files
   easier to read. Depending on the local paper size, install either
   print/enscript-letter or print/enscript-a4 from the Ports Collection.

   Create /usr/local/libexec/enscript with these contents:

 #!/bin/sh
 /usr/local/bin/enscript -o -

   Set the permissions and make it executable:

 # chmod 555 /usr/local/libexec/enscript

   Modify /etc/printcap to use the new filter:

 :if=/usr/local/libexec/enscript:\

   Test the filter by printing a plain text file.

    9.5.3.3. Printing PostScript(R) to PCL Printers

   Many programs produce PostScript(R) documents. However, inexpensive
   printers often only understand plain text or PCL. This filter converts
   PostScript(R) files to PCL before sending them to the printer.

   Install the Ghostscript PostScript(R) interpreter,
   print/ghostscript9-base, from the Ports Collection.

   Create /usr/local/libexec/ps2pcl with these contents:

 #!/bin/sh
 /usr/local/bin/gs -dSAFER -dNOPAUSE -dBATCH -q -sDEVICE=ljet4 -sOutputFile=- -

   Set the permissions and make it executable:

 # chmod 555 /usr/local/libexec/ps2pcl

   PostScript(R) input sent to this script will be rendered and converted to
   PCL before being sent on to the printer.

   Modify /etc/printcap to use this new input filter:

 :if=/usr/local/libexec/ps2pcl:\

   Test the filter by sending a small PostScript(R) program to it:

 % printf "%%\!PS \n /Helvetica findfont 18 scalefont setfont \
 72 432 moveto (PostScript printing successful.) show showpage \004" | lpr

    9.5.3.4. Smart Filters

   A filter that detects the type of input and automatically converts it to
   the correct format for the printer can be very convenient. The first two
   characters of a PostScript(R) file are usually %!. A filter can detect
   those two characters. PostScript(R) files can be sent on to a
   PostScript(R) printer unchanged. Text files can be converted to
   PostScript(R) with Enscript as shown earlier. Create
   /usr/local/libexec/psif with these contents:

 #!/bin/sh
 #
 #  psif - Print PostScript or plain text on a PostScript printer
 #
 IFS="" read -r first_line
 first_two_chars=`expr "$first_line" : '\(..\)'`

 case "$first_two_chars" in
 %!)
     # %! : PostScript job, print it.
     echo "$first_line" && cat && exit 0
     exit 2
     ;;
 *)
     # otherwise, format with enscript
     ( echo "$first_line"; cat ) | /usr/local/bin/enscript -o - && exit 0
     exit 2
     ;;
 esac

   Set the permissions and make it executable:

 # chmod 555 /usr/local/libexec/psif

   Modify /etc/printcap to use this new input filter:

 :if=/usr/local/libexec/psif:\

   Test the filter by printing PostScript(R) and plain text files.

    9.5.3.5. Other Smart Filters

   Writing a filter that detects many different types of input and formats
   them correctly is challenging. print/apsfilter from the Ports Collection
   is a smart "magic" filter that detects dozens of file types and
   automatically converts them to the PDL understood by the printer. See
   http://www.apsfilter.org for more details.

  9.5.4. Multiple Queues

   The entries in /etc/printcap are really definitions of queues. There can
   be more than one queue for a single printer. When combined with filters,
   multiple queues provide users more control over how their jobs are
   printed.

   As an example, consider a networked PostScript(R) laser printer in an
   office. Most users want to print plain text, but a few advanced users want
   to be able to print PostScript(R) files directly. Two entries can be
   created for the same printer in /etc/printcap:

 textprinter:\
         :lp=9100@officelaser:\
         :sh:\
         :mx#0:\
         :sd=/var/spool/lpd/textprinter:\
         :if=/usr/local/libexec/enscript:\
         :lf=/var/log/lpd-errs:

 psprinter:\
         :lp=9100@officelaser:\
         :sh:\
         :mx#0:\
         :sd=/var/spool/lpd/psprinter:\
         :lf=/var/log/lpd-errs:

   Documents sent to textprinter will be formatted by the
   /usr/local/libexec/enscript filter shown in an earlier example. Advanced
   users can print PostScript(R) files on psprinter, where no filtering is
   done.

   This multiple queue technique can be used to provide direct access to all
   kinds of printer features. A printer with a duplexer could use two queues,
   one for ordinary single-sided printing, and one with a filter that sends
   the command sequence to enable double-sided printing and then sends the
   incoming file.

  9.5.5. Monitoring and Controlling Printing

   Several utilities are available to monitor print jobs and check and
   control printer operation.

    9.5.5.1. lpq(1)

   lpq(1) shows the status of a user's print jobs. Print jobs from other
   users are not shown.

   Show the current user's pending jobs on a single printer:

 % lpq -Plp
 Rank   Owner      Job  Files                                 Total Size
 1st    jsmith     0    (standard input)                      12792 bytes

   Show the current user's pending jobs on all printers:

 % lpq -a
 lp:
 Rank   Owner      Job  Files                                 Total Size
 1st    jsmith     1    (standard input)                      27320 bytes

 laser:
 Rank   Owner      Job  Files                                 Total Size
 1st    jsmith     287  (standard input)                      22443 bytes

    9.5.5.2. lprm(1)

   lprm(1) is used to remove print jobs. Normal users are only allowed to
   remove their own jobs. root can remove any or all jobs.

   Remove all pending jobs from a printer:

 # lprm -Plp -
 dfA002smithy dequeued
 cfA002smithy dequeued
 dfA003smithy dequeued
 cfA003smithy dequeued
 dfA004smithy dequeued
 cfA004smithy dequeued

   Remove a single job from a printer. lpq(1) is used to find the job number.

 % lpq
 Rank   Owner      Job  Files                                 Total Size
 1st    jsmith     5    (standard input)                      12188 bytes
 % lprm -Plp 5
 dfA005smithy dequeued
 cfA005smithy dequeued

    9.5.5.3. lpc(8)

   lpc(8) is used to check and modify printer status. lpc is followed by a
   command and an optional printer name. all can be used instead of a
   specific printer name, and the command will be applied to all printers.
   Normal users can view status with lpc(8). Only root can use commands which
   modify printer status.

   Show the status of all printers:

 % lpc status all
 lp:
         queuing is enabled
         printing is enabled
         1 entry in spool area
         printer idle
 laser:
         queuing is enabled
         printing is enabled
         1 entry in spool area
         waiting for laser to come up

   Prevent a printer from accepting new jobs, then begin accepting new jobs
   again:

 # lpc disable lp
 lp:
         queuing disabled
 # lpc enable lp
 lp:
         queuing enabled

   Stop printing, but continue to accept new jobs. Then begin printing again:

 # lpc stop lp
 lp:
         printing disabled
 # lpc start lp
 lp:
         printing enabled
         daemon started

   Restart a printer after some error condition:

 # lpc restart lp
 lp:
         no daemon to abort
         printing enabled
         daemon restarted

   Turn the print queue off and disable printing, with a message to explain
   the problem to users:

 # lpc down lp Repair parts will arrive on Monday
 lp:
         printer and queuing disabled
         status message is now: Repair parts will arrive on Monday

   Re-enable a printer that is down:

 # lpc up lp
 lp:
         printing enabled
         daemon started

   See lpc(8) for more commands and options.

  9.5.6. Shared Printers

   Printers are often shared by multiple users in businesses and schools.
   Additional features are provided to make sharing printers more convenient.

    9.5.6.1. Aliases

   The printer name is set in the first line of the entry in /etc/printcap.
   Additional names, or aliases, can be added after that name. Aliases are
   separated from the name and each other by vertical bars:

 lp|repairsprinter|salesprinter:\

   Aliases can be used in place of the printer name. For example, users in
   the Sales department print to their printer with

 % lpr -Psalesprinter sales-report.txt

   Users in the Repairs department print to their printer with

 % lpr -Prepairsprinter repairs-report.txt

   All of the documents print on that single printer. When the Sales
   department grows enough to need their own printer, the alias can be
   removed from the shared printer entry and used as the name of a new
   printer. Users in both departments continue to use the same commands, but
   the Sales documents are sent to the new printer.

    9.5.6.2. Header Pages

   It can be difficult for users to locate their documents in the stack of
   pages produced by a busy shared printer. Header pages were created to
   solve this problem. A header page with the user name and document name is
   printed before each print job. These pages are also sometimes called
   banner or separator pages.

   Enabling header pages differs depending on whether the printer is
   connected directly to the computer with a USB, parallel, or serial cable,
   or is connected remotely over a network.

   Header pages on directly-connected printers are enabled by removing the
   :sh:\ (Suppress Header) line from the entry in /etc/printcap. These header
   pages only use line feed characters for new lines. Some printers will need
   the /usr/share/examples/printing/hpif filter to prevent stairstepped text.
   The filter configures PCL printers to print both carriage returns and line
   feeds when a line feed is received.

   Header pages for network printers must be configured on the printer
   itself. Header page entries in /etc/printcap are ignored. Settings are
   usually available from the printer front panel or a configuration web page
   accessible with a web browser.

  9.5.7. References

   Example files: /usr/share/examples/printing/.

   The 4.3BSD Line Printer Spooler Manual,
   /usr/share/doc/smm/07.lpd/paper.ascii.gz.

   Manual pages: printcap(5), lpd(8), lpr(1), lpc(8), lprm(1), lpq(1).

9.6. Other Printing Systems

   Several other printing systems are available in addition to the built-in
   lpd(8). These systems offer support for other protocols or additional
   features.

  9.6.1. CUPS (Common UNIX(R) Printing System)

   CUPS is a popular printing system available on many operating systems.
   Using CUPS on FreeBSD is documented in a separate
   article:../../../../doc/en_US.ISO8859-1/articles/cups

  9.6.2. HPLIP

   Hewlett Packard provides a printing system that supports many of their
   inkjet and laser printers. The port is print/hplip. The main web page is
   at http://hplipopensource.com/hplip-web/index.html. The port handles all
   the installation details on FreeBSD. Configuration information is shown at
   http://hplipopensource.com/hplip-web/install/manual/hp_setup.html.

  9.6.3. LPRng

   LPRng was developed as an enhanced alternative to lpd(8). The port is
   sysutils/LPRng. For details and documentation, see http://www.lprng.com/.

Chapter 10. Linux(R) Binary Compatibility

   Restructured and parts updated by Jim Mock.
   Originally contributed by Brian N. Handy and Rich Murphey.
   Table of Contents

   10.1. Synopsis

   10.2. Configuring Linux(R) Binary Compatibility

   10.3. Advanced Topics

10.1. Synopsis

   FreeBSD provides binary compatibility with Linux(R), allowing users to
   install and run most Linux(R) binaries on a FreeBSD system without having
   to first modify the binary. It has even been reported that, in some
   situations, Linux(R) binaries perform better on FreeBSD than they do on
   Linux(R).

   However, some Linux(R)-specific operating system features are not
   supported under FreeBSD. For example, Linux(R) binaries will not work on
   FreeBSD if they overly use i386(TM) specific calls, such as enabling
   virtual 8086 mode.

  Note:

   Support for 64-bit binary compatibility with Linux(R) was added in
   FreeBSD 10.3.

   After reading this chapter, you will know:

     * How to enable Linux(R) binary compatibility on a FreeBSD system.

     * How to install additional Linux(R) shared libraries.

     * How to install Linux(R) applications on a FreeBSD system.

     * The implementation details of Linux(R) compatibility in FreeBSD.

   Before reading this chapter, you should:

     * Know how to install additional third-party software.

10.2. Configuring Linux(R) Binary Compatibility

   By default, Linux(R) libraries are not installed and Linux(R) binary
   compatibility is not enabled. Linux(R) libraries can either be installed
   manually or from the FreeBSD Ports Collection.

   Before attempting to build the port, load the Linux(R) kernel module,
   otherwise the build will fail:

 # kldload linux

   For 64-bit compatibility:

 # kldload linux64

   To verify that the module is loaded:

 % kldstat
       Id Refs Address    Size     Name
       1    2 0xc0100000 16bdb8   kernel
       7    1 0xc24db000 d000     linux.ko

   The emulators/linux_base-c6 package or port is the easiest way to install
   a base set of Linux(R) libraries and binaries on a FreeBSD system. To
   install the port:

 # pkg install emulators/linux_base-c6

   For Linux(R) compatibility to be enabled at boot time, add this line to
   /etc/rc.conf:

 linux_enable="YES"

   On 64-bit machines, /etc/rc.d/abi will automatically load the module for
   64-bit emulation.

   Since the Linux(R) binary compatibility layer has gained support for
   running both 32- and 64-bit Linux(R) binaries (on 64-bit x86 hosts), it is
   no longer possible to link the emulation functionality statically into a
   custom kernel.

  10.2.1. Installing Additional Libraries Manually

   If a Linux(R) application complains about missing shared libraries after
   configuring Linux(R) binary compatibility, determine which shared
   libraries the Linux(R) binary needs and install them manually.

   From a Linux(R) system, ldd can be used to determine which shared
   libraries the application needs. For example, to check which shared
   libraries linuxdoom needs, run this command from a Linux(R) system that
   has Doom installed:

 % ldd linuxdoom
 libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29

   Then, copy all the files in the last column of the output from the
   Linux(R) system into /compat/linux on the FreeBSD system. Once copied,
   create symbolic links to the names in the first column. This example will
   result in the following files on the FreeBSD system:

 /compat/linux/usr/X11/lib/libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
 /compat/linux/lib/libc.so.4.6.29
 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29

   If a Linux(R) shared library already exists with a matching major revision
   number to the first column of the ldd output, it does not need to be
   copied to the file named in the last column, as the existing library
   should work. It is advisable to copy the shared library if it is a newer
   version, though. The old one can be removed, as long as the symbolic link
   points to the new one.

   For example, these libraries already exist on the FreeBSD system:

 /compat/linux/lib/libc.so.4.6.27
 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27

   and ldd indicates that a binary requires a later version:

 libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29

   Since the existing library is only one or two versions out of date in the
   last digit, the program should still work with the slightly older version.
   However, it is safe to replace the existing libc.so with the newer
   version:

 /compat/linux/lib/libc.so.4.6.29
 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29

   Generally, one will need to look for the shared libraries that Linux(R)
   binaries depend on only the first few times that a Linux(R) program is
   installed on FreeBSD. After a while, there will be a sufficient set of
   Linux(R) shared libraries on the system to be able to run newly installed
   Linux(R) binaries without any extra work.

  10.2.2. Installing Linux(R) ELF Binaries

   ELF binaries sometimes require an extra step. When an unbranded ELF binary
   is executed, it will generate an error message:

 % ./my-linux-elf-binary
 ELF binary type not known
 Abort

   To help the FreeBSD kernel distinguish between a FreeBSD ELF binary and a
   Linux(R) binary, use brandelf(1):

 % brandelf -t Linux my-linux-elf-binary

   Since the GNU toolchain places the appropriate branding information into
   ELF binaries automatically, this step is usually not necessary.

  10.2.3. Installing a Linux(R) RPM Based Application

   To install a Linux(R) RPM-based application, first install the
   archivers/rpm4 package or port. Once installed, root can use this command
   to install a .rpm:

 # cd /compat/linux
 # rpm2cpio < /path/to/linux.archive.rpm | cpio -id

   If necessary, brandelf the installed ELF binaries. Note that this will
   prevent a clean uninstall.

  10.2.4. Configuring the Hostname Resolver

   If DNS does not work or this error appears:

 resolv+: "bind" is an invalid keyword resolv+:
 "hosts" is an invalid keyword

   configure /compat/linux/etc/host.conf as follows:

 order hosts, bind
 multi on

   This specifies that /etc/hosts is searched first and DNS is searched
   second. When /compat/linux/etc/host.conf does not exist, Linux(R)
   applications use /etc/host.conf and complain about the incompatible
   FreeBSD syntax. Remove bind if a name server is not configured using
   /etc/resolv.conf.

10.3. Advanced Topics

   This section describes how Linux(R) binary compatibility works and is
   based on an email written to FreeBSD chat mailing list by Terry Lambert
    (Message ID:
   <199906020108.SAA07001@usr09.primenet.com>).

   FreeBSD has an abstraction called an "execution class loader". This is a
   wedge into the execve(2) system call.

   Historically, the UNIX(R) loader examined the magic number (generally the
   first 4 or 8 bytes of the file) to see if it was a binary known to the
   system, and if so, invoked the binary loader.

   If it was not the binary type for the system, the execve(2) call returned
   a failure, and the shell attempted to start executing it as shell
   commands. The assumption was a default of "whatever the current shell is".

   Later, a hack was made for sh(1) to examine the first two characters, and
   if they were :\n, it invoked the csh(1) shell instead.

   FreeBSD has a list of loaders, instead of a single loader, with a fallback
   to the #! loader for running shell interpreters or shell scripts.

   For the Linux(R) ABI support, FreeBSD sees the magic number as an ELF
   binary. The ELF loader looks for a specialized brand, which is a comment
   section in the ELF image, and which is not present on SVR4/Solaris(TM) ELF
   binaries.

   For Linux(R) binaries to function, they must be branded as type Linux
   using brandelf(1):

 # brandelf -t Linux file

   When the ELF loader sees the Linux brand, the loader replaces a pointer in
   the proc structure. All system calls are indexed through this pointer. In
   addition, the process is flagged for special handling of the trap vector
   for the signal trampoline code, and several other (minor) fix-ups that are
   handled by the Linux(R) kernel module.

   The Linux(R) system call vector contains, among other things, a list of
   sysent[] entries whose addresses reside in the kernel module.

   When a system call is called by the Linux(R) binary, the trap code
   dereferences the system call function pointer off the proc structure, and
   gets the Linux(R), not the FreeBSD, system call entry points.

   Linux(R) mode dynamically reroots lookups. This is, in effect, equivalent
   to union to file system mounts. First, an attempt is made to lookup the
   file in /compat/linux/original-path. If that fails, the lookup is done in
   /original-path. This makes sure that binaries that require other binaries
   can run. For example, the Linux(R) toolchain can all run under Linux(R)
   ABI support. It also means that the Linux(R) binaries can load and execute
   FreeBSD binaries, if there are no corresponding Linux(R) binaries present,
   and that a uname(1) command can be placed in the /compat/linux directory
   tree to ensure that the Linux(R) binaries cannot tell they are not running
   on Linux(R).

   In effect, there is a Linux(R) kernel in the FreeBSD kernel. The various
   underlying functions that implement all of the services provided by the
   kernel are identical to both the FreeBSD system call table entries, and
   the Linux(R) system call table entries: file system operations, virtual
   memory operations, signal delivery, and System V IPC. The only difference
   is that FreeBSD binaries get the FreeBSD glue functions, and Linux(R)
   binaries get the Linux(R) glue functions. The FreeBSD glue functions are
   statically linked into the kernel, and the Linux(R) glue functions can be
   statically linked, or they can be accessed via a kernel module.

   Technically, this is not really emulation, it is an ABI implementation. It
   is sometimes called "Linux(R) emulation" because the implementation was
   done at a time when there was no other word to describe what was going on.
   Saying that FreeBSD ran Linux(R) binaries was not true, since the code was
   not compiled in.

                        Part III. System Administration

   The remaining chapters cover all aspects of FreeBSD system administration.
   Each chapter starts by describing what will be learned as a result of
   reading the chapter, and also details what the reader is expected to know
   before tackling the material.

   These chapters are designed to be read as the information is needed. They
   do not need to be read in any particular order, nor must all of them be
   read before beginning to use FreeBSD.

   Table of Contents

   11. Configuration and Tuning

                11.1. Synopsis

                11.2. Starting Services

                11.3. Configuring cron(8)

                11.4. Managing Services in FreeBSD

                11.5. Setting Up Network Interface Cards

                11.6. Virtual Hosts

                11.7. Configuring System Logging

                11.8. Configuration Files

                11.9. Tuning with sysctl(8)

                11.10. Tuning Disks

                11.11. Tuning Kernel Limits

                11.12. Adding Swap Space

                11.13. Power and Resource Management

   12. The FreeBSD Booting Process

                12.1. Synopsis

                12.2. FreeBSD Boot Process

                12.3. Configuring Boot Time Splash Screens

                12.4. Device Hints

                12.5. Shutdown Sequence

   13. Security

                13.1. Synopsis

                13.2. Introduction

                13.3. One-time Passwords

                13.4. TCP Wrapper

                13.5. Kerberos

                13.6. OpenSSL

                13.7. VPN over IPsec

                13.8. OpenSSH

                13.9. Access Control Lists

                13.10. Monitoring Third Party Security Issues

                13.11. FreeBSD Security Advisories

                13.12. Process Accounting

                13.13. Resource Limits

                13.14. Shared Administration with Sudo

   14. Jails

                14.1. Synopsis

                14.2. Terms Related to Jails

                14.3. Creating and Controlling Jails

                14.4. Fine Tuning and Administration

                14.5. Updating Multiple Jails

                14.6. Managing Jails with ezjail

   15. Mandatory Access Control

                15.1. Synopsis

                15.2. Key Terms

                15.3. Understanding MAC Labels

                15.4. Planning the Security Configuration

                15.5. Available MAC Policies

                15.6. User Lock Down

                15.7. Nagios in a MAC Jail

                15.8. Troubleshooting the MAC Framework

   16. Security Event Auditing

                16.1. Synopsis

                16.2. Key Terms

                16.3. Audit Configuration

                16.4. Working with Audit Trails

   17. Storage

                17.1. Synopsis

                17.2. Adding Disks

                17.3. Resizing and Growing Disks

                17.4. USB Storage Devices

                17.5. Creating and Using CD Media

                17.6. Creating and Using DVD Media

                17.7. Creating and Using Floppy Disks

                17.8. Backup Basics

                17.9. Memory Disks

                17.10. File System Snapshots

                17.11. Disk Quotas

                17.12. Encrypting Disk Partitions

                17.13. Encrypting Swap

                17.14. Highly Available Storage (HAST)

   18. GEOM: Modular Disk Transformation Framework

                18.1. Synopsis

                18.2. RAID0 - Striping

                18.3. RAID1 - Mirroring

                18.4. RAID3 - Byte-level Striping with Dedicated Parity

                18.5. Software RAID Devices

                18.6. GEOM Gate Network

                18.7. Labeling Disk Devices

                18.8. UFS Journaling Through GEOM

   19. The Z File System (ZFS)

                19.1. What Makes ZFS Different

                19.2. Quick Start Guide

                19.3. zpool Administration

                19.4. zfs Administration

                19.5. Delegated Administration

                19.6. Advanced Topics

                19.7. Additional Resources

                19.8. ZFS Features and Terminology

   20. Other File Systems

                20.1. Synopsis

                20.2. Linux(R) File Systems

   21. Virtualization

                21.1. Synopsis

                21.2. FreeBSD as a Guest on Parallels for Mac OS(R) X

                21.3. FreeBSD as a Guest on Virtual PC for Windows(R)

                21.4. FreeBSD as a Guest on VMware Fusion for Mac OS(R)

                21.5. FreeBSD as a Guest on VirtualBox(TM)

                21.6. FreeBSD as a Host with VirtualBox(TM)

                21.7. FreeBSD as a Host with bhyve

                21.8. FreeBSD as a Xen(TM)-Host

   22. Localization - i18n/L10n Usage and Setup

                22.1. Synopsis

                22.2. Using Localization

                22.3. Finding i18n Applications

                22.4. Locale Configuration for Specific Languages

   23. Updating and Upgrading FreeBSD

                23.1. Synopsis

                23.2. FreeBSD Update

                23.3. Updating the Documentation Set

                23.4. Tracking a Development Branch

                23.5. Updating FreeBSD from Source

                23.6. Tracking for Multiple Machines

   24. DTrace

                24.1. Synopsis

                24.2. Implementation Differences

                24.3. Enabling DTrace Support

                24.4. Using DTrace

   25. USB Device Mode / USB OTG

                25.1. Synopsis

                25.2. USB Virtual Serial Ports

                25.3. USB Device Mode Network Interfaces

                25.4. USB Virtual Storage Device

Chapter 11. Configuration and Tuning

   Written by Chern Lee.
   Based on a tutorial written by Mike Smith.
   Also based on tuning(7) written by Matt Dillon.
   Table of Contents

   11.1. Synopsis

   11.2. Starting Services

   11.3. Configuring cron(8)

   11.4. Managing Services in FreeBSD

   11.5. Setting Up Network Interface Cards

   11.6. Virtual Hosts

   11.7. Configuring System Logging

   11.8. Configuration Files

   11.9. Tuning with sysctl(8)

   11.10. Tuning Disks

   11.11. Tuning Kernel Limits

   11.12. Adding Swap Space

   11.13. Power and Resource Management

11.1. Synopsis

   One of the important aspects of FreeBSD is proper system configuration.
   This chapter explains much of the FreeBSD configuration process, including
   some of the parameters which can be set to tune a FreeBSD system.

   After reading this chapter, you will know:

     * The basics of rc.conf configuration and /usr/local/etc/rc.d startup
       scripts.

     * How to configure and test a network card.

     * How to configure virtual hosts on network devices.

     * How to use the various configuration files in /etc.

     * How to tune FreeBSD using sysctl(8) variables.

     * How to tune disk performance and modify kernel limitations.

   Before reading this chapter, you should:

     * Understand UNIX(R) and FreeBSD basics (Chapter 3, FreeBSD Basics).

     * Be familiar with the basics of kernel configuration and compilation
       (Chapter 8, Configuring the FreeBSD Kernel).

11.2. Starting Services

   Contributed by Tom Rhodes.

   Many users install third party software on FreeBSD from the Ports
   Collection and require the installed services to be started upon system
   initialization. Services, such as mail/postfix or www/apache22 are just
   two of the many software packages which may be started during system
   initialization. This section explains the procedures available for
   starting third party software.

   In FreeBSD, most included services, such as cron(8), are started through
   the system startup scripts.

  11.2.1. Extended Application Configuration

   Now that FreeBSD includes rc.d, configuration of application startup is
   easier and provides more features. Using the key words discussed in
   Section 11.4, "Managing Services in FreeBSD", applications can be set to
   start after certain other services and extra flags can be passed through
   /etc/rc.conf in place of hard coded flags in the startup script. A basic
   script may look similar to the following:

 #!/bin/sh
 #
 # PROVIDE: utility
 # REQUIRE: DAEMON
 # KEYWORD: shutdown

 . /etc/rc.subr

 name=utility
 rcvar=utility_enable

 command="/usr/local/sbin/utility"

 load_rc_config $name

 #
 # DO NOT CHANGE THESE DEFAULT VALUES HERE
 # SET THEM IN THE /etc/rc.conf FILE
 #
 utility_enable=${utility_enable-"NO"}
 pidfile=${utility_pidfile-"/var/run/utility.pid"}

 run_rc_command "$1"

   This script will ensure that the provided utility will be started after
   the DAEMON pseudo-service. It also provides a method for setting and
   tracking the process ID (PID).

   This application could then have the following line placed in
   /etc/rc.conf:

 utility_enable="YES"

   This method allows for easier manipulation of command line arguments,
   inclusion of the default functions provided in /etc/rc.subr, compatibility
   with rcorder(8), and provides for easier configuration via rc.conf.

  11.2.2. Using Services to Start Services

   Other services can be started using inetd(8). Working with inetd(8) and
   its configuration is described in depth in Section 29.2, "The inetd
   Super-Server".

   In some cases, it may make more sense to use cron(8) to start system
   services. This approach has a number of advantages as cron(8) runs these
   processes as the owner of the crontab(5). This allows regular users to
   start and maintain their own applications.

   The @reboot feature of cron(8), may be used in place of the time
   specification. This causes the job to run when cron(8) is started,
   normally during system initialization.

11.3. Configuring cron(8)

   Contributed by Tom Rhodes.

   One of the most useful utilities in FreeBSD is cron. This utility runs in
   the background and regularly checks /etc/crontab for tasks to execute and
   searches /var/cron/tabs for custom crontab files. These files are used to
   schedule tasks which cron runs at the specified times.