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® 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:

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.

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:

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

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.

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.

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.

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:

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!

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.

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:

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

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:

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.

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:

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® keyboards. At the 0 > prompt, enter

boot cd:,\ppc\loader cd:0

Most SPARC64® 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.

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

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

Figure 2.2. 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:

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

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

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

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

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.

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

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

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

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

Figure 2.8. 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:

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

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

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

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.

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.

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

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

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

Selecting this method opens the partition editor:

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

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.

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

A standard FreeBSD GPT installation uses at least three partitions:

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.

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

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

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

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

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 <Change Selection> to return to the list of disks, or <Cancel> to change the pool type.

Figure 2.20. Disk Selection

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

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

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

The installation then proceeds normally.

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.

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

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

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

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

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

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

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

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

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

Figure 2.36. IPv4 Static Configuration

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

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

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

Figure 2.39. IPv6 Static Configuration

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

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

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

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

Figure 2.43. Select a Country

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

Figure 2.44. Select a Time Zone

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

Figure 2.45. Confirm Time Zone

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

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

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

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

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

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

Here is a summary of the information to input:

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

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

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

Figure 2.51. Final Configuration

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

After any final configuration is complete, select Exit.

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

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.

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

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.

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"

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.

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

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.

# 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!
#

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

#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:

#Changing user database information for jru.
Shell: /usr/local/bin/zsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:

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

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

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:

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

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

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

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

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:

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

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.

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

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

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

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

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

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:

The following options can be passed to -o as a comma-separated list:

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.

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.

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.

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

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

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

The UNIX® 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® 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® 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.

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

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.

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

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.

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

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

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.

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

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

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

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

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

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

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

# pkg install -Rf graphics/freeglut

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