Difference between revisions of "Flat html/9.2"

From PC-BSD Wiki
Jump to: navigation, search
 
Line 17: Line 17:
 
{{flatten|2.4|title=Obtaining PC-BSD®}}
 
{{flatten|2.4|title=Obtaining PC-BSD®}}
 
{{flatten|2.5|title=Burning the Installation Media}}
 
{{flatten|2.5|title=Burning the Installation Media}}
{{flatten|2.6|title=Using VirtualBox}}
+
{{flatten|2.6|title=PC-BSD® Live Mode}}
 +
{{flatten|2.7|title=Using VirtualBox}}
 
{{flatten|3.|title=Installing PC-BSD®}}
 
{{flatten|3.|title=Installing PC-BSD®}}
{{flatten|3.1|title=Language Selection Screen}}
+
{{flatten|3.1|title=Starting the PC-BSD® Installation}}
{{flatten|3.2|title=System Selection Screen}}
+
{{flatten|3.2|title=Language Selection Screen}}
{{flatten|3.3|title=Disk Selection Screen}}
+
{{flatten|3.3|title=System Selection Screen}}
{{flatten|3.4|title=Installation Progress Screen}}
+
{{flatten|3.4|title=Disk Selection Screen}}
{{flatten|3.5|title=Installation Finished Screen}}
+
{{flatten|3.5|title=Installation Progress Screen}}
 +
{{flatten|3.6|title=Installation Finished Screen}}
 
{{flatten|4.|title=Post Installation Configuration and Installation Troubleshooting}}
 
{{flatten|4.|title=Post Installation Configuration and Installation Troubleshooting}}
 
{{flatten|4.1|title=Booting Into PC-BSD®}}
 
{{flatten|4.1|title=Booting Into PC-BSD®}}
Line 35: Line 37:
 
{{flatten|4.9|title=Installation Troubleshooting}}
 
{{flatten|4.9|title=Installation Troubleshooting}}
 
{{flatten|5.|title=Advanced Installation Topics}}
 
{{flatten|5.|title=Advanced Installation Topics}}
{{flatten|5.1|title=Using the Text Installer}}
+
{{flatten|5.1|title=Install a Server}}
{{flatten|5.2|title=Install a Server}}
+
 
{{flatten|5.2|title=Convert a FreeBSD System to PC-BSD®}}
 
{{flatten|5.2|title=Convert a FreeBSD System to PC-BSD®}}
 
{{flatten|5.3|title=Using a Rolling Release}}
 
{{flatten|5.3|title=Using a Rolling Release}}
Line 77: Line 78:
 
{{flatten|8.12|title=Sound Configuration}}
 
{{flatten|8.12|title=Sound Configuration}}
 
{{flatten|8.13|title=Display}}
 
{{flatten|8.13|title=Display}}
{{flatten|8.14|title=Disk Manager}}
+
{{flatten|8.14|title=Printing}}
{{flatten|8.15|title=Printing}}
+
{{flatten|8.15|title=Scanner}}
{{flatten|8.16|title=Scanner}}
+
{{flatten|8.16|title=Network Configuration}}
{{flatten|8.17|title=Network Configuration}}
+
{{flatten|8.17|title=Firewall Manager}}
{{flatten|8.18|title=Firewall Manager}}
+
{{flatten|8.18|title=Adobe Flash Player preferences}}
{{flatten|8.19|title=Adobe Flash Player preferences}}
+
{{flatten|8.19|title=Life Preserver}}
{{flatten|8.20|title=Life Preserver}}
+
{{flatten|8.20|title=PC-BSD® Bug Reporting}}
{{flatten|8.21|title=PC-BSD® Bug Reporting}}
+
{{flatten|8.21|title=Warden®}}<!-- End control panel section - special item order -->
{{flatten|8.22|title=Warden®}}<!-- End control panel section - special item order -->
+
 
{{flatten|9.|title=Using PC-BSD®}}
 
{{flatten|9.|title=Using PC-BSD®}}
 
{{flatten|9.1|title=Java, Flash, and Fonts}}
 
{{flatten|9.1|title=Java, Flash, and Fonts}}

Latest revision as of 23:58, 3 December 2013

Contents


Preface
PC-BSD® Users Handbook

Written by users of the PC-BSD® operating system.

Version 9.2

Copyright © 2005-2013, The PC-BSD® Project.

Welcome to PC-BSD®! This Handbook covers the installation and use of PC-BSD® 9.2. This Handbook is a work in progress and relies on the contributions of many individuals. If you are interested in assisting with the Handbook, visit http://wiki.pcbsd.org and create a login account for yourself. If you use IRC Freenode, you are welcome to join the #pcbsd channel where you will find other PC-BSD® users.

Previous versions of the Handbook in various formats and languages are available from ftp://ftp.pcbsd.org/pub/handbook/. Errata may be found at http://wiki.pcbsd.org/index.php/Errata. The PC-BSD® Users Handbook is freely available for sharing and redistribution under the terms of the Creative Commons Attribution License[1]. This means that you have permission to copy, distribute, translate, and adapt the work as long as you attribute the PC-BSD® Project as the original source of the Handbook.

PC-BSD® and the PC-BSD® logo are registered trademarks of iXsystems[2]. If you wish to use the PC-BSD® logo in your own works, ask for permission first from marketing at ixsystems dot com.

Trademarks

AMD is a trademark of Advanced Micro Devices, Inc.

Apache is a trademark of The Apache Software Foundation.

AppCafe® is a registered trademark of iXsystems.

Asus® and Eee PC® are registered trademarks of ASUSTeK® Computer Inc.

Facebook® is a registered trademark of Facebook Inc.

Flash® is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries.

FreeBSD® is a registered trademark of the FreeBSD Foundation[3].

FreeNAS® is a registered trademark of iXsystems.

IBM® is a registered trademark of International Business Machines Corporation.

Intel, the Intel logo, Pentium Inside, and Pentium are trademarks of Intel Corporation in the U.S. and/or other countries.

Java™ is a trademark of Oracle America and/or its affiliates in the United States and other countries.

Lenovo® is a registered trademark of Lenovo.

LinkedIn® is a registered trademark of LinkedIn Corporation.

Linux® is a registered trademark of Linus Torvalds.

Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries.

MacBook® is a registered trademark of Apple Inc.

MySQL is a trademark of Oracle.

NVIDIA® is a trademark and/or registered trademark of NVIDIA Corporation in the U.S. and other countries.

PostgreSQL® is a registered trademark of the PostgreSQL Global Development Group.

ThinkPad® is a registered trademark of Lenovo.

TrueOS® is a registered trademark of iXsystems.

Twitter is a trademark of Twitter, Inc. in the United States and other countries.

UNIX® is a registered trademark of The Open Group.

VirtualBox® is a registered trademark of Oracle.

VMWare® is a registered trademark of VMWare, Inc.

Warden® is a registered trademark of iXsystems.

Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.

Typographic Conventions

The PC-BSD® 9.2 Handbook uses the following typographic conventions:

bold text: represents a command written at the command line. In usage examples, the font is changed to Courier 10 with any command output displayed in unbolded text.

italic text: used to represent device names or file name paths.

bold italic text: used to emphasize an important point.

The following icons are also used:


Introduction

Welcome to PC-BSD®!

PC-BSD®[4] began in 2005 when Kris Moore presented the first beta version of a FreeBSD[5] operating system pre-configured for desktop use. Since then, PC-BSD® has matured into a polished, feature-rich, free-of-charge, open source operating system that meets the desktop needs of the beginner to the advanced user alike.

PC-BSD® is essentially a customized installation of FreeBSD, not a forked derivative. Since the underlying FreeBSD system has been kept intact, you have a fully functional FreeBSD system under the hood. PC-BSD® provides a graphical installer which can be used to easily install a desktop or a server version of FreeBSD known as TrueOS®. Other differences include:

  • PC-BSD® pre-configures at least one desktop environment during a desktop installation.
  • The PC-BSD® graphical installer supports additional features such as configuring ZFS during installation.
  • PC-BSD® provides a graphical software management system for the desktop and a command line equivalent for the server.
  • PC-BSD® provides a Control Panel of utilities for configuring the system. The graphical versions of these utilities are available on the desktop and the command line versions are available on both the desktop and server.
  • PC-BSD® comes pre-configured with a number of automatic scripts to perform tasks such as connecting digital cameras or USB memory sticks.

PC-BSD® started off as an independent project, but since October, 2006 PC-BSD® is financially backed and supported by the enterprise-class hardware solutions provider iXsystems[6].

The rest of this section discusses:



Goals and Features

PC-BSD® provides the following features:

  • Easy installation: to install either a graphical desktop or command-line server version of PC-BSD®, simply insert the installation media, reboot the system to start the installer, and answer a few questions in the graphical menus.
  • Automatically configured hardware: video, sound, network and other devices are automatically configured for you.
  • Intuitive desktop interface: PC-BSD® comes with a choice of desktop environments to support your day-to-day computing needs.
  • Easy software management: with AppCafe®, installing, upgrading, and uninstalling software is safe and easy.
  • Lots of software available: in addition to its own software, PC-BSD® can install software that has been ported to FreeBSD (currently over 24,000 applications).
  • Binary compatibility: for software that has not been specifically ported to FreeBSD. PC-BSD® can run almost any GNU/Linux application using Linux binary compatability.[7] It is also able to run many Windows applications using Wine.
  • Easy to update: PC-BSD® provides a built-in Update Manager that will notify you of available updates and allow you to apply operating system security fixes, bug fixes, system enhancements as well as upgrade to newer versions of the operating system or installed software.
  • Virus-free: PC-BSD® is not affected by viruses, spyware, or other malware.
  • No defragmentation: PC-BSD® hard drives do not need to be defragmented and do not slow down over time. PC-BSD® uses ZFS[8] which is a self-healing filesystem.
  • Laptop support: provides power saving and swap space encryption and automatically switches between wired and wifi network connections.
  • Secure environment: PC-BSD® provides a pre-configured PF firewall[9], brute-force attack protection with OSSEC[10], and a Host-based Intrusion Detection System with Fail2ban[11].
  • Easy system administration: PC-BSD® provides a Control Panel containing many graphical tools for performing system administration tasks.
  • Professional support: professional email and phone support is available from iXsystems[12].



What's New in 9.2

The following features have been added to or improved for PC-BSD® 9.2:

  • Based on FreeBSD 9.2-RELEASE which adds this list of features[13].
  • Uses ZFSv5000 (feature flags), the latest open source version of ZFS. This version includes the LZ4 compression algorithm.
  • The pkgng repository used by the software installed with the operating system is updated on or about the 5th and 20th of each month and a new freebsd-update patch is released on the 1st of each month.
  • PC-BSD® is only available on 64-bit systems and the graphical installer will format the selected drive(s) or partition as ZFS. This means that images are no longer provided for 32-bit systems and that the graphical installer no longer provides an option to format with UFS.
  • GRUB is used to provide the graphical boot menu. It provides support for multiple boot environments, serial consoles, GPT booting, UEFI, graphics, and faster loading of kernel modules. During installation, most other existing operating systems will automatically be added to the boot menu.
  • The system has changed from the traditional ports system to pkgng and all of the PC-BSD® utilities that deal with installing or updating software use pkgng. This means that you can safely install non-PBI software from the command line and that a system upgrade will no longer delete non-PBI software.
  • The PC-BSD® utilities that deal with installing software or updates use aria2[14] which greatly increases download speed over slow links. aria2 achieves this by downloading a file from multiple sources over multiple protocols in order to utilize the maximum download bandwidth. The pc-pkg command has been added as a wrapper script to pkg. Use pc-pkg if you wish to increase your download speed when installing or upgrading pkgng packages.
  • PC-BSD® uses a Content Delivery Network (CDN) service for its network backbone. This means that users no longer have to pick a mirror close to their geographical location in order to get decent download speeds when downloading PC-BSD, updates, or software. It will also prevent failed updates as it removes the possibility of a mirror being out of date or offline.
  • The source code repository for PC-BSD® has changed to GitHub[15]. Instructions for obtaining the source code using git can be found on our trac site[16].
  • The installer provides a built-in status tip bar, instead of tooltips, to display text about the moused-over widget.
  • If a non-English language is selected during installation, the post-installation configuration screens will automatically be displayed in the selected language. Additionally, if the user installed the KDE window manager, KDE-L10N will be installed.
  • The installer provides an option to install a Desktop or a Server. If you select to Install a Server, it will install TrueOS®, a command-line version of FreeBSD which adds the command-line versions of the PC-BSD® utilities.
  • The installer provides an option to restore or clone the operating system from a remote snapshot created with Life Preserver. A network configuration icon is included to configure the connection to the server containing the remote snapshot.
  • The Advanced Mode screen provides configurable options to force 4K sector size, install GRUB, and set the ZFS pool name.
  • The installation summary screen provides an option to save configuration of the current installation selections to a FAT-formatted USB stick so that it can be re-used at a later time.
  • The PEFS[17] encryption system has replaced the GELI encryption system. PEFS offers several benefits over GELI. Rather than encrypting the entire disk(s), which may expose too much known cryptographic data, it can be used on a per-user basis to encrypt that user's home directory. When the user logs in, their home directory is automatically decrypted and it is again encrypted when the user logs out. PEFS supports hardware acceleration. It can also be used to encrypt other directories using the command line; read man pefs for examples.
  • The encryption option has been removed from the installer and has been replaced by a "Encrypt user files" checkbox in the post-installation Create a User Screen for the primary login account and in the User Manager utility for creating additional user accounts. If you choose to use PEFS, it is very important to select a good password that you will not forget. At this time, the password cannot be easily changed as it is associated with the encryption key. A future version of PC-BSD® will provide a utility for managing encryption keys. In the mean time, this forum post provides a work around if you need to change a password of a user that is using PEFS.
  • When administrative access is needed, the user will be prompted for their own password. This means that users do not have to know the root password. Any user which is a member of the wheel group will have the ability to gain administrative access. By default, the only user in this group is the user account that you create during post-installation configuration. If additional users need this ability, use the Groups tab of User Manager to add them to the wheel group.
  • AppCafe® has been re-designed with a cleaner code base. New features include the ability to perform actions on multiple applications, save downloaded .pbi files to a specified directory, downgrade installed software if an earlier version is available as a PBI, the ability to import and export PBI lists, and improved search ability.
  • EasyPBI has been revamped as version 2, making it even easier to create PBIs.
  • A graphical Boot Manager utility for managing boot environments and the GRUB configuration has been added to Control Panel.
  • The mirrors tab of System Manager has been removed as downloads are provided through a CDN.
  • The Mount Tray interface and detection algorithm has been improved. It can also mount an ISO to a memory disk.
  • The Life Preserver utility has been completely rewritten. It allows you to schedule the creation of local ZFS snapshots and provides a built-in browser for finding previous versions of files and restoring them. It includes optional support for replicating the snapshots to a remote system, such as FreeNAS. A remote snapshot can be used to restore the operating system if disaster recovery is required.
  • Many improvements to Warden® including the ability to create jails by hostname instead of by IP address, jail IP addresses can be changed after jail creation, vimage can be enabled/disabled on a per-jail basis, IPv4 or IPv6 addressing can be enabled or disabled, aliases can be added on a per-jail basis, and jail sysctls can be easily enabled on a per-jail basis.
  • A Template Manager has been added to Warden®. Templates can be added then used to create a new jail. For example, templates can be used to install different versions of FreeBSD and have been tested from FreeBSD 4.1.1 to FreeBSD-CURRENT.
  • The ability to use an external DHCP server has been added to Thin Client and the ports collection is no longer a requirement for using this script.
  • The system uses /etc/rc.conf.pcbsd as the default, desktop operating system version of the RC configuration file. The server operating system version of this file is called /etc/rc.conf.trueos. Do not make any changes to either of these files. Instead, make any needed customizations to /etc/rc.conf. This way, when the system is upgraded, changes to the default configuration file will not affect any settings and overrides which have been placed into /etc/rc.conf.
  • The default wallpaper has been updated and 9.2 is referred to as PC-BSD® Isotope Infusion to differentiate it from 9.1.
  • The graphical gsmartcontrol[18] command has been added to PC-BSD® and the command line equivalent smartctl has been added to both PC-BSD® and TrueOS®. These utilities can be used to inspect and test the system's SMART[19]-capable hard drives to determine their health.
  • Mosh has been added to base to provide an SSH replacement over intermittent links.
  • VirtualBox[20] has been added to base which should prevent kernel module mis-matches. The installation includes the VirtualBox Guest Additions[21]. If you are currently using the VirtualBox PBI, you should uninstall it.



PC-BSD® Releases

PC-BSD® version numbers are the same as those used by FreeBSD. Unlike FreeBSD, PC-BSD® also uses a rolling release model. The name of the file image that you choose to install or upgrade to will determine how often you receive updates to the software that is installed with the operating system as well as whether or not you will receive updates as new features and drivers are added to the operating system. Image names will include the version number, where 9.2 is the most recent version, and either the word RELEASE or STABLE, where:

- RELEASE: indicates that updates to the software installed with the operating system will appear in Update Manager on or about the 1st and 15th of each month. This means that these applications will never be more than a month out of date. However, new drivers and features will not be added to the operating system until the next RELEASE version becomes available and the user upgrades to that new version.

- STABLE: indicates that updates to the software installed with the operating system will appear in Update Manager on or about the 5th and 20th of each month. In addition, on the 1st of each month, Update Manager will provide a patch which will update the operating system to include all of the new features and drivers.

Despite the name, RELEASE is considered to be more stable than STABLE. If you can wait until the next release (typically every 6 months or so) for new drivers and features, install RELEASE instead of STABLE.

If you are currently running RELEASE and would like to change to STABLE, refer to Using a Rolling Release.

Occasionally, the FreeBSD project releases security patches that affect the operating system or the software installed with the operating system. These will appear in Update Manager for both RELEASE and STABLE users, making it easy to keep your PC-BSD® system fully patched against known security vulnerabilities.



PC-BSD® for Linux Users

PC-BSD® is based on BSD Unix[22], meaning that it is not a Linux distribution. If you have used Linux before, you will find that some features that you are used to have different names on a BSD system and that some commands are different. This section covers some of these differences.

Filesystems

BSD and Linux use different filesystems during installation. Many Linux distros use EXT2, EXT3, EXT4, or ReiserFS, while PC-BSD® uses UFS or ZFS. This means that if you wish to dual-boot with Linux or access data on an external drive that has been formatted with another filesystem, you will want to do a bit of research first to see if the data will be accessible to both operating systems.

Table 1.4a summarizes the various filesystems commonly used by desktop systems. Most of the desktop managers available from PC-BSD® should automatically mount the following filesystems: FAT16, FAT32, EXT2, EXT3 (without journaling), EXT4 (read-only), NTFS5, NTFS6, and XFS. See the section on Files and File Sharing for more information about available file manager utilities.

Table 1.4a: Filesystem Support on PC-BSD® [tables 1]
Filesystem Native to Type of non-native support Usage notes
Btrfs Linux none
exFAT Windows r/w support loaded by default
EXT2 Linux r/w support loaded by default
EXT3 Linux r/w support loaded by default since EXT3 journaling is not supported, you will not be able to mount a filesystem requiring a journal replay unless you fsck it using an external utility such as e2fsprogs[23].
EXT4 Linux r/o support loaded by default EXT3 journaling, extended attributes, and inodes greater than 128-bytes are not supported; EXT3 filesystems converted to EXT4 may have better performance
FAT16 Windows r/w support loaded by default
FAT32 Windows r/w support loaded by default
HFS+ Mac OS X none older Mac versions might work with hfsexplorer[24].
JFS Linux none
NTFS5 Windows full r/w support loaded by default
NTFS6 Windows r/w support loaded by default
ReiserFS Linux r/o support is loaded by default
UFS2 PC‑BSD® check if your Linux distro provides ufsutils;
r/w support on Mac;
UFS Explorer[25] can be used on Windows
changed to r/o support in Mac Lion
XFS Linux r/o support is loaded by default
ZFSv5000 PC‑BSD®, FreeBSD

Device Names

Linux and BSD use different naming conventions for devices. For example:

  • in Linux, Ethernet interfaces begin with eth; in BSD, interface names indicate the name of the driver. For example, an Ethernet interface may be listed as re0, indicating that it uses the Realtek re driver. The advantage of this convention is that you can read the man 4 page for the driver (e.g. type man 4 re) to see which models and features are provided by that driver.
  • BSD disk names differ from Linux. IDE drives begin with ad and SCSI and USB drives begin with da.

Feature Names

Some of the features used by BSD have similar counterparts to Linux, but the name of the feature is different. Table 1.4b provides some common examples:

Table 1.4b: Names for BSD and Linux Features [tables 2]
PC-BSD® Linux Description
PF iptables default firewall
/etc/rc.d/ for operating system and /usr/local/etc/rc.d/ for applications rc0.d/, rc1.d/, etc. in PC-BSD® the directories containing the startup scripts do not link to runlevels as there are no runlevels; system startup scripts are separated from third-party application scripts
/etc/ttys and /etc/rc.conf telinit and init.d/ terminals are configured in ttys and rc.conf indicates which services will start at boot time

Commands

If you are comfortable with the command line, you may find that some of the commands that you are used to have different names on BSD. Table 1.4c lists some common commands and what they are used for.

Table 1.4c: Common BSD and Linux Commands [tables 3]
Command Used to:
dmesg discover what hardware was detected by the kernel
sysctl dev display configured devices
pciconf -l -cv show PCI devices
dmesg | grep usb show USB devices
kldstat list all modules loaded in the kernel
kldload <module> load a kernel module for the current session
pbi_add -r <pbiname> install software from the command line
sysctl hw.realmem display hardware memory
sysctl hw.model display CPU model
sysctl hw.machine_arch display CPU Architecture
sysctl hw.ncpu display number of CPUs
uname -vm get release version information
gpart show show device partition information
fuser list IDs of all processes that have one or more files open

A common complaint is that the size of PC-BSD® PBI files are much larger than the actual program. What complaints of this sort often do not recognize is that very few installable applications are complete by themselves. If you take a look at what happens while the program is being compiled, or when you install a package, you will notice that there are additional applications being pulled in or downloaded and installed. These are all dependencies: things that the program will require in order to fully function. An application of any complexity, especially if it is desktop-oriented, is likely to depend upon many programs. These programs may relate to audio or video playback, window management, or libraries for encoding, compression, encryption. -->


Additional Resources

The following articles and videos provide additional information about some of the differences between BSD and Linux:



Pre-Installation Tasks

While the PC-BSD® installer is very easy to use, installing a brand new operating system can sometimes be a daunting task.

Before you begin, there are a few things you should check to ensure that your system is ready to install PC-BSD®.

  • Are you dual-booting or installing over the entire drive? If you are dual-booting you will need to ensure that you have a primary partition available. Refer to the section on Dual Booting.
  • Have you backed up your important data? Any irreplaceable data, such as emails, bookmarks, or important files and documents should always be backed up to an external media, such as a removable drive or another system, before installing or upgrading any operating system.

If you wish to determine if your hardware is detected by PC-BSD®, start an installation and click the Hardware Compatibility button in the first screen of the installer.

If you would like to use a portable version of PC-BSD® instead of performing an installation, use PC-BSD® Live Mode.

Should you run into an issue with your installation there are many different ways to get help.

This section discusses the following topics:



Hardware Requirements

PC-BSD® has moderate hardware requirements and commonly uses less resources than its commercial counterparts. Before installing PC-BSD®, make sure that your hardware or virtual machine at least meets the minimum requirements. To get the most out of your PC-BSD® experience, refer to the recommended system requirements.

Minimum System Requirements

At a bare minimum, you need to meet these requirements in order to install PC-BSD®:

  • 64-bit processor
  • 1 GB RAM
  • 20GB of free hard drive space on a primary partition for a TrueOS® server installation
  • Network card

Recommended System Requirements

The following are the minimum recommended requirements. The more RAM and available disk space, the better your computing experience:

  • 64-bit processor
  • 4 GB of RAM
  • 50GB of free hard drive space on a primary partition for a desktop installation
  • Network card
  • Sound card
  • NVIDIA 3D accelerated video card

The PC-BSD installer's hardware check will display a warning message if the selected partition contains less than 20GB for a server installation or less than 50GB for a desktop installation. The installation itself does not require this much disk space. Instead the minimum recommendation is to provide sufficient room for the installation of multiple desktops, applications, and to store local ZFS snapshots.

You can never have too much RAM, so install as much as you can afford. To play modern video games, you should use a fast CPU. If you want to create a collection of tunes and movies on your computer, you will want a large hard disk drive which can be internal or external.

Supported Processors

PC-BSD® should install on any system containing a 64-bit (also called amd64) processor. Despite the amd64 name, a 64-bit processor does not need to be manufactured by AMD in order to be supported. The FreeBSD Hardware Notes[36] lists the amd64 processors known to work.

Supported Video Cards

Like most open source operating systems, PC-BSD® uses X.org drivers for graphics support. PC-BSD® will automatically detect the optimal video settings for supported video drivers. You can verify that your graphics hardware is supported by clicking the Hardware Compatibility icon within the installer.

Support for the major graphic vendors is as follows:

NVIDIA: if you want to use 3D acceleration, NVIDIA is currently the best supported as there is a native driver for PC-BSD®. If an NVIDIA video card is detected, an "nVidia settings" icon will be added to the Control Panel for managing NVIDIA settings.

Intel: 3D acceleration on most Intel graphics is supported. Due to the current KMS support, you will not be able to switch between the graphical console and a virtual console using Crtl+Alt+F#.

ATI/Radeon: 3D acceleration will not work on ATI or Radeon cards until FreeBSD completes its TTM work. You can still use these cards, but you will have to choose the 2D driver, and if that does not work, you will need to resort to using the Vesa driver.

Optimus: at this time Bumblebee[37] has not been ported to FreeBSD, meaning that there is no switching support between the two graphics adapters provided by Optimus. Optimus implementations vary, so PC-BSD® may or may not be able to successfully load a graphics driver on your hardware. If you get a blank screen after installation, check your BIOS to see if it has an option to disable one of the graphics adapters or to set “discrete” mode. If the BIOS does not provide a discrete mode, PC-BSD® will default to the 3D Intel driver and disable NVIDIA. This will change in the future when the NVIDIA driver supports Optimus.

Wireless Cards

PC-BSD® has built-in support for dozens of wireless networking cards. You can check if your card has a FreeBSD driver[38]. If it does, it should "just work". A list of supported Atheros devices and known limitations can be found on the FreeBSD wiki[39].

PC-BSD® will automatically detect available wireless networks for supported wireless devices. You can verify that your device is supported by clicking the Hardware Compatibility icon within the installer. If it an external wireless device, insert it before running the Hardware Compatibility utility. If your device is not detected, the Wireless Testing page has some information about drivers which have not been ported yet. It also contains instructions for converting a Microsoft driver to a FreeBSD kernel module, though results will vary by driver. Known missing wireless drivers are typically for the Broadcom and newer Realtek series of cards.

Certain Broadcom devices, typically found in cheap laptops, are quite buggy and can have lockups when in DMA mode. If the device freezes, try switching to PIO mode in the BIOS. Alternately, add the line hw.bwn.usedma=0 to /boot/loader.conf and reboot to see if that makes a difference.

Checking Hardware Compatibility

If you wish to check your hardware before installing PC-BSD®, a good place to start is the FreeBSD 9.2 Hardware Notes[40]. Another good resource is to start the installer and click the Hardware Compatibility icon.

While most hardware "just works" with PC-BSD®, it is possible that you will run across a piece of hardware that does not. It should be remembered that PC-BSD® is really FreeBSD, meaning that any hardware that works on FreeBSD will work on PC-BSD®. If you are experiencing problems with a device, start with a web search for the term "FreeBSD" plus the type and model of the hardware. This will let you know if there is a known issue with the device. If there are many search results, concentrate on the most recent ones as often hardware that used to be problematic has since been fixed or the missing driver will be available in an upcoming release of FreeBSD. If you experience problems with a device that should work but does not or you can not find any existing problem reports for your hardware, you can help improve hardware support for all PC-BSD® users by reporting the problem so that it can be addressed by the developers.



Laptops

Many PC-BSD® users successfully run PC-BSD® on their laptops. To determine if the hardware on your laptop is supported, search the FreeBSD Laptop Compatibility List[41]. Consider adding to this list if your model is not listed or the information for your model is out-of-date.

Depending upon the model of laptop, you may run across some issues. These typically deal with:

  • Sleep/suspend: unfortunately, ACPI[42] is not an exact science, meaning that you may have to experiment with various sysctl variables in order to achieve successful sleep and suspend states on your particular laptop model. If your laptop is a ThinkPad, Thinkwiki[43] is an excellent source. For other types of laptops, try reading the SYSCTL VARIABLES section of man 4 acpi and check to see if there is an ACPI man page specific to your vendor by typing apropos acpi. The Tuning with sysctl(8)[44] section of the FreeBSD Handbook demonstrates how to determine your current sysctl values, modify a value, and make a modified value persist after a reboot. If the battery reading is incorrect, try the workaround in this PR[45].
  • Internal wireless: some chipsets do not have a FreeBSD driver yet. If you would like to try converting a Windows driver into a FreeBSD module, use the instructions in this Official PC-BSD® blog post[46].
  • Internal ATI or Radeon graphics: some chipsets will only support 2D graphics.
  • Synaptics: depending upon the hardware, you may or may not be able to disable the system's touchpad. This forum post[47] describes how to enable Synaptics and some of the sysctl options that this feature provides.
  • Optimus graphics: the current workaround is to disable Optimus in the BIOS, set the onboard Intel video to be dominant, or to change the graphics mode to discrete.

If you wish to test your laptop's hardware, use the Hardware Compatibility icon in the first screen of the installer before continuing with the installation.

If you would like to install PC-BSD® onto an Asus Eee, read the FreeBSD Eee page[48] first.

The FreeBSD Tuning Power Consumption page[49] has some tips for reducing power consumption.

ThinkPads with Known Bugs

The ThinkPad T420 may panic during install. If it does, go into the BIOS and set the video mode to "discrete" which should allow you to complete an installation.

Some Thinkpads have a BIOS bug that prevents them from booting from GPT labelled disks. If you are unable to boot into a new installation, restart the installer and go into Advanced Mode in the Disk Selection Screen. Make sure that the "Partition disk with GPT" box is unchecked. If it was checked previously, redo the installation with the box unchecked.

Acer Laptops with Known Bug

In models 2920z and 4920G, there is an issue with the BIOS settings for the HPET timer. The solution is to set a hardware hint[50].

Boot the installation media and select "7. Escape to the loader prompt" when you see the menu shown in Figure 2.2a.

Figure 2.2a: PC-BSD® Boot Menu

At the resulting prompt, type:

set hint.hpet.0.allowed_irqs="0x400000"                              
boot

You should now be able to install PC-BSD®. Once the installer boots for the first time, you will need to repeat that command in order to boot into PC-BSD®. Once you are in PC-BSD®, you can make the hint permanent by carefully adding this line to /boot/loader.conf as the superuser:

hint.hpet.0.allowed_irqs="0x400000"                                  

MacBooks

Before starting, you should review the MacBook on FreeBSD Wiki[51].

Starting in PC-BSD® 9.0-RC1, support has been added for installing directly to Mac OS X BootCamp partitions.

First, you can install an OS X boot manager, such as rEFIt[52]. This step is optional as it requires either a dedicated partition or it installs into your OS X partition and takes over the boot process.

Next you will need to make some free space to install into. You can use the MacBook's Boot Camp[53] utility to make a primary partition of at least 25 GB in size.

After creating the BootCamp partition, boot from the PC-BSD® install media and proceed with a normal installation. When you get to the "Disk Selection" screen, be sure to select the ada0p3: linux-data partition for installation. After installation, reboot and select BSD from the rEFIt (or an alternate) boot menu to boot into the new PC-BSD® installation.

Touch Screens

Starting in PC-BSD® 9.0, automatic detection of USB-based touch screen devices has been added. During the display wizard phase, if your touch-screen is auto-detected, the necessary flags will be added to /etc/X11/xorg.conf automatically. If your display is USB and is NOT auto-detected, please send the output of usbconfig and your /etc/X11/xorg.conf file tusing the PC-BSD® Bug Reporting tool.



Partitioning the Hard Drive

WARNING PC-BSD® will not install into a secondary or logical partition, it must be a primary[54] partition.

PC-BSD® does not include its own built-in partition manager. The installer assumes that the drive is already prepared for an installation. If you are not planning to install PC-BSD® onto the entire hard drive, you will need to use a third-party application in order to prepare a primary partition to use as the destination for your PC-BSD® install.

DANGER! Before creating or editing your hard drive's partitions, make sure that you first back up your valuable data to an external media such as a removable USB drive, then remove the drive during this operation. Data stored on the hard drives attached to the computer have the chance for damage or loss. Extreme care must be taken but this will not eliminate the unforeseen from happening. It is always best to back up first or your valuable data will be at risk.

Shrinking a Drive in Windows 7

If you are currently running Windows 7, it is using the entire hard drive. This means that you will need to first shrink the drive in order to make room to create a new partition. Shrinking is an operation that retains the current data on the partition, while reducing the size of the partition.

To shrink the drive, go to Start menu → right-click Computer → Manage → Storage → Disk Management. Figure 2.3a shows an example of a system running Windows 7. In this example, Windows has created three partitions: a 16GB recovery partition, a 100MB system partition, and a 450GB data partition.

Figure 2.3a: Viewing Disk Layout in Disk Management
Figure 2.3c: Disk Now Has Free Space
WARNING if you plan to dual-boot with Windows, it is important that you do not choose to install PC-BSD® into any of these three partitions when you get to the Disk Selection Screen of the installer. It is a good idea to write down the sizes of the partitions so that you will recognize them when the PC-BSD® installer displays your current partitions.
Figure 2.3b: Available Shrink Space

Since the three Windows partitions are using the entire disk, the data partition needs to be shrunk in order to create space to install PC-BSD® into. To shrink the data partition, right-click the partition, in this example it is called Acer (C:), and select "Shrink Volume". Wait a moment as it queries the volume for available shrink space; the results will be displayed as seen in the example in Figure 2.3b.

In this example, 321089MB of space is available. To divide the partition between Windows and PC-BSD®, change that number to 230000 and click the "Shrink" button. When finished, the newly created free space will be displayed, as seen in Figure 2.3c.

You can now format the newly created free space using a utility such as Parted Magic, as described in the next section.

NOTE: While the Disk Management utility in Windows 7 indicates that it will let you format a primary partition, in reality it will only create an extended partition which will not allow you to install PC-BSD®. This means that you still need another utility such as Parted Magic.

Using Parted Magic to Create a Primary Partition

Parted Magic[55] is a graphical, easy-to-use partition editor that is packaged on a live CD. It can be used to shrink an existing partition and to create a primary partition from existing free space.

Figure 2.3d: Formatting the Unallocated Space into a Primary Partition

To use Parted Magic, download the latest .iso.zip file, unzip it, and burn it to CD. Boot the system with the CD and let it boot into "Default settings (Runs from RAM)". Wait for it to boot into the graphical screen, then select the "Partition Editor" desktop icon.

Figure 2.3d shows the same Windows 7 system in Partition Editor. The 225.05GB partition is the Windows data partition (which was displayed as drive C within Windows 7) and the 224.61GB of unallocated space was created using the Windows Disk Management utility. The "Create new Partition" screen was opened by right-clicking on the unallocated space and selecting "New" from the menu.

When creating your partition from unallocated space, make sure that "Primary Partition" is selected. The filesystem type does not matter as the PC-BSD® installer will reformat it. It is a good idea to write down the size and filesystem type so that you will recognize the partition that you will be installing PC-BSD® into. Once you have made your selections, click the "Add" button. Note that the partition will not actually be created until you click the "Apply" button to apply your changes. A popup menu will prompt you to make sure that you have selected the correct partition, as formatting a partition destroys all data on that portion of the disk. Once the operation is complete you can reboot and start the PC-BSD® installation.



Obtaining PC-BSD®

The installation files for PC-BSD® can be downloaded for free and end with an .iso or .img.bz2 file extension. Depending upon the type of file you choose, the size will vary between ~650MB and ~3.5GB. This section will show you how to select which file to download and how to verify the downloaded file's checksum. The next section will demonstrate how to burn the file to bootable media.

If you have a slow download connection or wish to support the PC-BSD® project financially, you can purchase PC-BSD® DVDs from the FreeBSD Mall[56].

Members of the PC-BSD® project attend many IT conferences across the globe and give out PC-BSD® DVDs at conference booths. Visiting a PC-BSD® booth is an excellent way to meet other PC-BSD® users and to get your questions answered. Check the PC-BSD® Blog[57] to see if any events are happening near you. If you are organizing a PC-BSD® booth, contact us[58] to arrange for DVDs.

Selecting Which File to Download

When you go to the Download[59] page of the PC-BSD® website, you will find a number of files available for download:

  • DVD: contains the full version of PC-BSD® (all system components, ports, and source); requires a DVD burner.
  • USB: contains the full version of PC-BSD® (all system components, ports, and source); requires a USB memory stick or flash card that is at least 4GB in size.
  • USB-live: contains a writable, live version of PC-BSD® running the LXDE desktop; requires a USB memory stick or flash card that is at least 8GB in size. It does not include the installer.
  • VMware disk image: contains a pre-installed version of PC-BSD® with the GNOME, KDE, LXDE, Openbox, and XFCE desktops. See the section on Using VirtualBox for instructions on using the VMware disk image.
  • VirtualBox disk: contains a pre-installed version of PC-BSD® with the GNOME, KDE, LXDE, Openbox, and XFCE desktops. See the section on Using VirtualBox for instructions on using the VirtualBox disk.

Regardless of which media you use to install PC-BSD®, you have the option to install additional components and applications after the installation using Package Manager and AppCafe®.

Data Integrity Check

After downloading the file that is correct for your installation media, it is a good idea to check that the file is exactly the same as the one on the PC-BSD® server. While downloading, a portion of the file may get damaged or lost, making the installation file unusable. Each
Figure 2.4a: Verifying a Checksum Using FastSum
PC-BSD® download has an associated MD5 checksum which is listed next to the download link. If the checksum of the file you downloaded has the same number, your download was successful. If the MD5 numbers do not match, try downloading the file again. In order to verify the checksum, you will need to use a checksum verification utility.

If you are currently using a Windows system, you can download and install the FastSum[60] utility. Once installed, launch the program and click the "Files" button, shown in Figure 2.4a, to browse to the location of your downloaded file.

Once the file is selected, click the green arrow to calculate the checksum. Once calculated, it will be listed in the "Checksum\State" column, though FastSum will capitalize the letters.

On Linux and BSD systems you can use the built-in md5 (or md5sum) command line tool to check the data integrity of the downloaded file. In this example, the file is located in the Downloads subdirectory. You should substitute the name and location of the file that you downloaded:

md5 Downloads/PCBSD9.2-RELEASE-x64-DVD.iso



Burning the Installation Media

Once you have downloaded PC-BSD® and verified its checksum, burn the file to the correct media type. This section demonstrates how to do so using several different applications and operating systems. Each application assumes that the correct media (CD, DVD, or USB flash drive) for the type of file is inserted.

Burning the CD/DVD ISO File on a BSD or Linux System

This section demonstrates how to burn the installation ISO on a Linux or BSD system using the following tools: K3B, Brasero, and growisofs.

K3B

K3B[61] is an easy-to-use graphical burning application for Linux and BSD systems. On a PC-BSD® system, it is installed with the KDE desktop. You can also install the K3B PBI using AppCafe®.

To burn your ISO, launch K3B, browse to the location of the .iso file in the screen shown in Figure 2.5f and click ToolsBurn Image... to see the screen in Figure 2.5g.

Figure 2.5f: Selecting the Burn Image Tool Within K3B
Figure 2.5g: K3B's Burn Image Screen

Click the "Start" button to burn the file. K3B will automatically eject the media once the burn is complete.

Brasero

Brasero[62] is an easy to use burning application included with the GNOME desktop. A PBI is also available within AppCafe®. To launch Brasero within GNOME, click ApplicationsMultimediaBrasero Disk Burner and the dialog window shown in Figure 2.5h will be displayed. Alternately, type brasero from within any window manager.

Click Burn image to open the screen seen in Figure 2.5i. Use the Click here to select a disk image button to select your .iso file.

Figure 2.5h: Brasero's Initial Screen
Figure 2.5i: Brasero Image Burning Setup

The name and size of your .iso file should appear and Brasero will indicate the size of the media. The lower portion of Figure 2.5i shows the menu that appears if you click on the "Properties" button. You can change these options if you wish, but the default settings are fine in most cases. When you are ready, click the "Burn" button and Brasero will burn your ISO.

Xfburn

Xfburn[63] is available to install as PBI Software and is installed with XFCE4.

growisofs

If you are familiar with using the command line on a FreeBSD or PC-BSD® system, you can use the growisofs command line utility to burn the DVD. This utility is included with the dvd+rw-tools FreeBSD port which is installed by default on a PC-BSD® system. If that software is not yet installed on a FreeBSD system, issue this command as the superuser:

pkg_add -r dvd+rw-tools

Depending upon the type of DVD burner hardware, you may have to configure the system to use it. If the device is ATAPI (i.e. not USB or SCSI), the ATAPI driver must be loaded. The superuser can issue this command:

kldload atapicam

If you just get your prompt back, the driver successfully loaded. If you get the message "kldload: cannot load atapicam: File exists", this means that the driver was already loaded. If the device is USB or SCSI, no additional drivers need to be loaded if you are running the generic FreeBSD kernel. After inserting the DVD media into the device, you can start the burn using this command:

growisofs -Z /dev/cd0=PCBSD9.2-x64-DVD.iso

If your device is not the first CD device, change the number 0 accordingly. If your ISO has a different name, substitute the correct name in the command shown above.

Burning the CD/DVD ISO File on a Mac OS X System

To burn the ISO on a Mac OS X system, go to "Finder ➜ Applications ➜ Utilities ➜ Disk Utility". With a blank media inserted into the burner, highlight the device representing the CD/DVD writer and click the "Burn" button.
Figure 2.5j: Using Disk Utility on Mac OS X
This will open up a browser where you can select the ISO to burn. In the example shown in Figure 2.5j, the DVD ISO has been selected and the device is a Sony DVD writer.

Once the ISO is highlighted, click the "Burn" button. A pop-up message will indicate that the device is ready to burn. Click "Burn" once more and "Disk Utility" will write the ISO to the CD/DVD media.

Burning the CD/DVD ISO File on a Windows System

Several burning applications are available for Windows. This section will demonstrate how to use Windows 7's Disc Image Burner, ImgBurn, and InfraRecorder.

Windows 7 Disc Image Burner

Windows 7 has built-in support for writing ISO images to disc. Right-click on the .iso file in Windows Explorer and select "Open with ➜ Windows Disc Image Burner" to open the screen shown in Figure 2.5a. Click "Burn" to write the disc. See the Microsoft article Burn a CD or DVD from an ISO file[64] for more detailed instructions.

Figure 2.5a: Windows Disc Image Burner
Figure 2.5b: Initial ImgBurn Screen

ImgBurn

ImgBurn[65] is an easy to use ISO burner for Windows that is available for free download. After installing and launching ImgBurn, select "Write image file to disk" from the main menu, seen in Figure 2.5b:

You can then use File ➜ Browse for a source file... to select the .iso file to burn; once selected, your screen should look similar to Figure 2.5c. Click the Write icon in the lower left corner to begin the burn.

Figure 2.5c: Selecting the Source and Destination in ImgBurn

ImgBurn will provide a status bar to indicate the progress of the burn. When it is finished, ImgBurn will eject the burner tray then reclose it in order to verify the burn. If the tray does not return itself, which may occur on a laptop, push the tray back in if you wish to verify the burn.

InfraRecorder

InfraRecorder[66] is an open source burning application for both CDs and DVDs. Once installed, open InfraRecorder and click on the "Write Image" button shown in Figure 2.5d:

Figure 2.5d: Initial InfraRecorder Screen

InfraRecorder will display a screen where you can browse to the location of the .iso file. Once selected, you will be presented with an options screen shown in Figure 2.5e:

Figure 2.5e: Burn Options in InfraRecorder

You can accept the defaults and click "OK" to start the burn. When finished, the burner tray will open and a dialog box will appear indicating that the burning process has finished.

Writing an IMG File to USB

To write an .img.bz2 file you will need the following:

  • a utility that can extract .bz2 zipped files
  • a utility that can write the image to a USB media; the utility that you use will depend upon your operating system
  • a USB thumb drive or hard drive large enough to hold the image

Once the image is written, boot from the removable device and proceed with the PC-BSD® installation.

NOTE: If there is a card reader on the system or used via USB dongle, the device enumeration may be affected. For example, with the USB card reader dongle as the destination for the image burn below, it would be /dev/da1 instead of /dev/da0.

Writing the IMG File on a BSD or Linux System

If you selected to download an .img.bz2 file instead of an ISO, you can write the image file to a flash card or removable USB drive using the bunzip2 and dd command line utilities on a BSD or Linux system. On a FreeBSD system, the superuser can use these commands to extract the specified image and write it to the first plugged in USB device:

bunzip2 -k PCBSD9.2-RELEASE-x64-USBFULL.img.bz2

dd if=PCBSD9.2-RELEASE-x64-USBFULL.img of=/dev/da0 bs=64k conv=sync 63200+0 records in 63200+0 records out

4141875200 bytes transferred in 1395.261087 secs (2968531 bytes/sec)

When using the dd command:

  • if= refers to the input file to be written; it should end with an .img extension
  • of= refers to the output file (the device name of the flash card or removable USB drive); increment the number in the name if it is not the first USB device
  • bs= refers to the block size
  • conv=sync pads the final block so it is the specified block size
NOTE: Linux users: if you type mount with the USB stick inserted, you will see two or more device nodes corresponding to the USB stick. For example, /dev/sdc and /dev/sdc1, where /dev/sdc1 corresponds to the primary partition of the USB stick. Before using the dd command, ensure that the usb stick is first unmounted. When using the dd command, remember to use /dev/sdc (device node without the number) as the option for the output file of=. Once the dd completes, you might not be able to mount the USB stick on Linux, as Linux has very limited support for UFS (the BSD filesystem that gets created on the USB stick).

Writing the IMG File on a Windows System

To burn the image file on a Windows system, you can use win32-image-writer[67]. You will also need a utility that can extract .bz2 files such as 7-Zip[68].

When downloading win32-image-writer, download the latest version that ends in -binary.zip and use a utility such as Windows Explorer or 7zip to unzip the executable.

To extract the PC-BSD® image file using 7-Zip, browse to the location containing your downloaded .img.bz2 file, as seen in the example in Figure 2.5k.

Click the "Extract" button and browse to the location where you would like to save the extracted image. Once extracted, your image will end in .img, and will be ready to be written to a USB device using the win32-image-writer application.

If you launch win32-image-writer.exe, it will start the "Win32 Disk Imager" utility, shown in Figure 2.5l. Use the "Browse" button to browse to the location of the .img file. Insert a USB thumb drive and select its drive letter (in this example, drive D). Click the "Write" button and the image will be written to the USB thumb drive.

Figure 2.5k: Using 7-Zip to Extract Image File
Figure 2.5l: Using Win32 Disk Imager to Write the Image

Writing the IMG File on a Mac OS X System

To extract the .img.bz2 file on a Mac system, use Finder to browse to the location of the file. Double-click the file to extract it to the .img format. Finder will create a second file with the .img extension.

To burn that .img file, insert a USB stick and open "Terminal". Run the diskutil list command to find out the device name of the USB disk, unmount the USB disk, then use dd to write the image to the raw disk (rdisk). In the following example, an 8GB USB stick has a device name of /dev/disk1 and a raw device name of /dev/rdisk1.

diskutil list

/dev/disk0   #: TYPE NAME SIZE IDENTIFIER   0: GUID_partition_scheme *500.1 GB disk0   1: EFI 209.7 MB disk0s1   2: Apple_HFS Macintosh HD 499.2 GB disk0s2   3: Apple_Boot Recovery HD 650.0 MB disk0s3 /dev/disk1   #: TYPE NAME SIZE IDENTIFIER   0: FDisk_partition_scheme *8.0 GB disk1   1: DOS_FAT_32 UNTITLED 8.0 GB disk1s1

diskutil unmountDisk /dev/disk1 Unmount of all volumes on disk1 was successful

sudo dd if=/Users/dru/Downloads/PCBSD9.2-RELEASE-x64-USBFULL.img of=/dev/rdisk1 bs=4m Password: 375+0 records in 375+0 records out

1572864000 bytes transferred in 86.742798 secs (18132502 bytes/sec)



PC-BSD® Live Mode

Live Mode is a read-write live image that is only available for USB media. It is meant to be a portable version of PC-BSD®, similar to an operating system on a stick. The uncompressed live image requires a USB device that is at least 8GB in size. However, you will want to write it to a USB device that will provide sufficient room for the files that you wish to save and any applications that you wish to install.

NOTE: The PC-BSD® live image does not include an installer. This is to reduce the size of the live image for users who want to have a live portable system. If you prefer to have an installer included, you should instead download the DVD or USB image. Also, the speed of Live Mode is dependent upon the quality of the USB device. If you are purchasing a device, look for one that is advertised as "high speed".

To use PC-BSD® Live Mode, download the live USB version. Once you have written the image file to a USB media, boot the system with the USB device inserted. Assuming your BIOS has been set to boot from that device, you should see some startup messages. The first time you boot the image, the boot process will pause with this message:

Trying to mount root from ufs:mdo []...

tput: no terminal type specified and no TERM environmental variable. Do you want to expand the file-system for this LIVE media? This process may take up to 15 minutes.

Resize? (y/n):

This step grows the filesystem so that it can use the entire capacity of the USB device. Press y to expand the filesystem and reboot into live mode:

Resizing file-system da0a on da0, this may take a few minutes...

Adjusting partition tables on da0... Running growfs on da0a, this may take a while... Cleaning up...

Rebooting...

You will know that you have successfully entered live mode when you are asked to accept the graphics resolution mode that is considered to be optimal for your hardware.

If this is your first boot, you will then proceed through the post-installation configuration screens, ending in the Logging In screen. When logging in, use the user account and password that you were prompted to create. Three desktops are available: Fluxbox, LXDE, and Openbox.



Using VirtualBox

A virtualized environment allows you to test drive an operating system without overwriting your current operating system. This is an excellent way to practice installation, determine whether all of your hardware is supported, or to try multiple versions of different operating systems. Virtualization software effectively creates windows (known as virtual machines) into which you can install and use an operating system. The only limitation to virtualization is your hardware as each virtual machine uses CPU and RAM.
Figure 2.7a: Initial VirtualBox Screen
Depending upon the amount of CPU and RAM in your computer, you may find that the operating system you install using virtualization software runs slowly. If your computer slows down greatly, try closing other applications running on your computer to free up some RAM.

PC-BSD® 9.2 automatically installs the VirtualBox[69] open source virtualization program and the VirtualBox Guest Additions[21] with the operating system. The guest additions add mouse pointer integration, shared folders between the host and guest, better video support, and a shared clipboard.

If your computer is running another operating system, download the binary for your operating system from the VirtualBox Downloads page[70]. VirtualBox runs on Windows, Linux, Macintosh, and OpenSolaris and supports a large number of operating systems that can be installed into a virtual machine.

In order to use PC-BSD® within VirtualBox, you will need to either:

  • download the PC-BSD® virtual disk, which contains a virtual machine with a pre-installed version of PC-BSD® or
  • download the PC-BSD® ISO, create your own virtual machine, and use the ISO to install PC-BSD® into it.
NOTE: VirtualBox does not automatically support USB as a boot device. The Oracle VM VirtualBox Extension Pack[71] can be used to convert an .img file to a VMDK. However, there is no BSD Extension Pack at this time. This means that you should not download a PC-BSD® USB image if you plan to use it within VirtualBox on a BSD system.

If you have downloaded the PC-BSD® virtual disk, skip ahead to Using the Downloadable VirtualBox Disk.

If you have downloaded the ISO file, you will need to first create a virtual machine that meets the following minimum requirements:

  • 1024 MB base memory size
  • a virtual disk at least 20 GB in size for a TrueOS® installation or at least 50 GB in size for a PC-BSD® installation
  • a bridged adapter

Creating a Virtual Machine

Figure 2.7b: Type in a Name and Select the Operating System for the New Virtual Machine

Once installed, start VirtualBox to see the screen shown in Figure 2.7a. To create the virtual machine, click the "New" button to start the new virtual machine wizard. Click the "Next" button to see the screen in Figure 2.7b.

Enter a name for your virtual machine, which can be anything that makes sense to you. Click the "Operating System" drop-down menu and select BSD which will automatically change the "Version" menu item to FreeBSD. Click Next to see the screen in Figure 2.7c:

Figure 2.7c: Select the Amount of Memory Reserved for the Virtual Machine

The base memory size must be changed to at least 1024 MB. If your system has a lot of RAM, use more. Any number within the green area is considered a safe value by VirtualBox, meaning it should not slow down your computer too much. When finished, click "Next" to see the screen in Figure 2.7d:

Figure 2.7d: Select Whether to Use an Existing or Create a New Virtual Disk

This screen is used to create the virtual hard disk--in other words, the amount of disk space that will be available to the virtual machine. If this is your first virtual machine, keep the default of "Start-up disk" and click "Next". If you have created a virtual machine in the past and wish to reuse its disk space, select "Use existing hard disk" from the drop-down menu. You can create as many virtual machines as you wish. However, if your computer is getting low on disk space, you should consider reusing existing virtual hard disks to prevent your hard drive from being used up by old virtual machines.

If you choose to create a new hard disk, the "Create New Virtual Disk Wizard", seen in Figure 2.7e, will launch when you click "Next".

Figure 2.7e: Create New Virtual Disk Wizard

The wizard can be used to create the following types of virtual disk formats:

  • VDI: Virtual Disk Image is the format used by VirtualBox. Select this option if you downloaded a PC-BSD® ISO file.
  • VMDK: Virtual Machine Disk is the format used by VMWare[72].

Once you make a selection, click the "Next" button to see the screen in Figure 2.7f:

Figure 2.7f: Select the Storage Type for the Virtual Disk

You can now choose whether you want "Dynamically allocated" or "Fixed size" storage. The first option uses disk space as needed until it reaches the maximum size that you will set in the next screen. The second option creates a disk the same size as that specified amount of disk space, whether it is used or not. Choose the first option if you are worried about disk space; otherwise, choose the second option as it allows VirtualBox to run slightly faster. Once you select "Next", you will see the screen in Figure 2.7g:

Figure 2.7g: Select the File Name and Size of the Virtual Disk

This screen is used to set the size (or upper limit) of the virtual machine. If you plan to install PC-BSD® into the virtual machine, increase the size to at least 20 GB or you will receive an error during the PC-BSD® installation. If you plan to install KDE, GNOME, multiple desktop managers, or PBIs within the virtual machine, you will probably want to choose at least 50 GB. Whatever size you set, make sure that your computer has enough free disk space to support it. Use the folder icon to browse to a directory on disk with sufficient space to hold your virtual machine.

Once you make your selection and press "Next", you will see a summary of your choices. You can use the "Back" button to return to a previous screen if you wish to change any values. Otherwise, click "Create" to finish using the wizard. Your virtual machine should now show up in the left box, as seen in the example in Figure 2.7h:

Figure 2.7h: The New Virtual Machine

Configuring the Network Adapter

If you wish to use your network card, you will need to configure bridging on your virtual machine. To do this, go to SettingsNetwork. In the "Attached to" drop-down menu select "Bridged Adapter" then select the name of the physical interface from the Name drop-down menu. In the example shown in Figure 2.7i, the Intel Pro/1000 Ethernet card is attached to the network and has a device name of re0.

Figure 2.7i: Configuring a Bridged Adapter in VirtualBox

Configuring the Storage Device

Before starting your virtual machine, you will want to configure it to use your installation media. Click the Storage hyperlink in the right frame to access the storage screen seen in Figure 2.7j:

Figure 2.7j: The Storage Settings of the Virtual Machine

Double-click the word Empty, which represents your DVD reader. If you wish to access the PC-BSD® installer from your DVD reader, double-check that the Slot is pointing to the correct location (e.g. IDE Secondary Master) and use the drop-down menu to change it if the location is incorrect. Click the "CD/DVD Device" drop-down menu to change it from empty to the Host Drive value.

If you prefer to use an ISO that is stored on your hard disk, click the DVD icon ➜ Choose a virtual CD/DVD disk file to open a browser menu where you can navigate to the location of the ISO. Highlight the desired ISO and click Open. The name of the ISO will now appear in the Storage Tree section.

You are now ready to install PC-BSD® into your virtual machine. Simply highlight the virtual machine and click on the green "Start" icon. A window will open indicating that the virtual machine is starting. If you have a DVD inserted, you should hear it spin and it should start to boot into the installation program. If it does not or if you are using an ISO stored on the hard disk, press F12 to select the boot device when you see the message to do so, then press "c" to boot from CD-ROM. You can then proceed through the installation as described in the Installation section.

Using the Downloadable VirtualBox or VMWare Disk

PC-BSD® provides pre-built VirtualBox and VMWare disks which create a a pre-made virtual machine with PC-BSD already installed. The VirtualBox file ends in a .vdi.bz2 extension and the VMWare disk file ends in a .vmdk.bz2 extension. The .bz2 means that either file needs to be unzipped first so that it just ends with a .vdi or .vmdk extension.

On a Linux or BSD system, use the bunzip2 command by giving it the name of the file which you downloaded:

bunzip2 -k PCBSD9.2-x64-VBOX.vdi.bz2

Since this is a large file, the command will take a few minutes to extract the image. You will receive the prompt back when it has finished.

On a Windows system, you can use a utility such as 7-Zip[68]. On a Mac OS X system, simply double-click the file in "Finder" to extract it.

Once the file is unzipped, open VirtualBox as described in Creating a Virtual Machine. When you get to Figure 2.7d, select "Use existing hard disk".

Use the browse icon to browse to the location of the .vdi or .vmdk file then press "Next". A message will indicate that the virtual machine will be created; click the "Create" button to finish the wizard. You can then configure the network adapter and start the virtual machine.

The virtual machine will boot into the first boot wizard for PC-BSD® so that the system can be configured. Once the display wizard is finished and the login prompt appears, input the username and password that you configured at the login screen.

Troubleshooting VirtualBox

While using a virtual environment allows you to test an operating system without affecting what else is currently installed on the system, there are some things to be aware of when using VirtualBox.

If the installer program fails to load, try increasing the amount of RAM in the virtual machine.

If the installation fails and you would like to review the installation log, right-click the virtual machine window and select xterm from the menu. You can now type more /tmp/pc-sysinstall.log to review the log.

The FreeBSD VirtualBox wiki[75] contains additional information that may assist you in troubleshooting VirtualBox issues.



Installing PC-BSD®

PC-BSD® can be installed from the installation media directly onto a hard drive or into a virtual machine using virtualization software such as Virtualbox[69]. You can also try PC-BSD® without installing it by using PC-BSD® Live Mode.

The installation of PC-BSD® is a fast, easy and straight-forward process. The graphical installer will take you step-by-step through the whole process by asking a few simple questions. Within a short period of time, your PC-BSD® system will be installed, configured, and ready to use. This section will walk you through the following installation steps:



Starting the PC-BSD® Installation

To begin the PC-BSD® installation, insert the boot media and boot the system. If the computer boots into an existing operating system instead of the installer, reboot and check your computer's BIOS program to ensure that the drive containing the installation media is listed first in the boot order. Save your BIOS changes and reboot.

Figure 3.1a: PC-BSD® Installer Boot Menu

After a couple of seconds, a series of lines of code will scroll down the screen, meaning that PC-BSD® is being loaded. Soon after, you should see a screen similar to Figure 3.1a.

There are 7 options to choose from:

1. Boot [default]: starts the installation program with all standard options enabled. This is the default if you do not select anything else within 10 seconds.

2. Boot with ACPI enabled: this enables power management, which may be useful[76] for certain BIOS varieties and laptops.

3. Boot in Safe Mode: select this option if the installation still hangs when probing your hardware and option #2 did not help. It will boot with a forced PIO mode (disabling the use of DMA), disable write caching for all IDE hard drives and CD ROM drives, disable the probing of EISA slots (as very few systems have them), and (on i386 systems) disables the use of ACPI and APICs.

4. Boot with verbose logging: select this option if you would like to see more detailed messages during the boot process. This can be useful if you are troubleshooting which piece of hardware is causing the installation to hang.

5. Boot to emergency console: advanced users can use this option to fix critical system failures.

6. Boot with X in VESA mode: if the installation program is unable to load your video driver, restart the computer and select this option. The installer will default to VESA mode which should work on any system with a video card.

7. Escape to loader prompt: advanced users can select this option to perform advanced operations, such as changing kernels or loading kernel modules.

If you press enter or select any option other than 5 or 7, PC-BSD® will boot into the graphical installer.



Language Selection Screen

The first graphical installer screen, seen in Figure 3.2a, indicates that the installer successfully loaded and is ready to present you with its options.

Figure 3.2a: Welcome and Language Selection Screen

Starting on the left-hand side, the icons in the bottom navigation area allow you to:

  • read that screen's "Help" text
  • use the onscreen keyboard
  • switch between the US keyboard layout and a user selected layout
  • abort the installation
  • navigate to a previous or upcoming screen

Hover over an icon to view its description in the tip bar at the bottom of the screen.

NOTE: The default keyboard layout can be changed now, during post-install configuration, or during login.

A button is also provided to "Load config from USB". If you have saved the configuration from a previous installation, it can be loaded at this time from a FAT-formatted USB stick.

This initial screen allows you to select your language. The menus in PC-BSD® have been translated to several different languages and you can see the status of your native language at the PC-BSD® Translation Site[77]. If your language does not show 100% translation at this website, it means that not all of the menus have been translated yet and that the untranslated menus will instead display in English. You are welcome to join the PC-BSD® Translators Mailing List[78] if you would like to assist in translating menus to your native language.

By default, PC-BSD® menus will display in English, unless you select another language in the drop-down menu in this screen.

NOTE: Small screens may not display the entire installer window, which means that the buttons at the bottom of the window are hidden and inaccessible. There are two solutions for this situation: press Alt while dragging the window with the mouse, or press Alt+N to select the next button of the window.

When you are finished, click the next "Next" button to go to the next installation screen.



System Selection Screen

The "System Selection" screen, shown in Figure 3.3a, allows you to install a desktop (PC-BSD®) or a server (TrueOS®) operating system. It also allows you to restore the operating system from a Life Preserver backup.

Figure 3.3a: Desktop Selection Screen

By default, PC-BSD® will be selected and the default window manager will depend upon the amount of RAM on the system. Systems containing more than 2GB of RAM will default to the KDE desktop and all other systems will default to the LXDE desktop. To change the default window manager or to browse for additional desktops and components to install, click the "Customize" button. If you highlight then right-click a component and select "View Packages", a pop-up menu will list the packages that are installed with that component.

After installation, you can return to this "Customize" screen in order to install or uninstall additional components by going to Control PanelPackage Manager.

In the example shown in Figure 3.3b, the user clicked “Customize” then expanded “Development” and right-clicked Development ➜ Development-Debug to access the “View Packages” option for this component.

Figure 3.3b: Browsing Additional System Components

The following components are available for installation.

  • Desktops: includes the following supported desktops: GNOME2, KDE4, LXDE, and XFCE4. If you expand the + next to a desktop, you can select which components to install with that desktop. You can select as many desktops and components as you wish to install.
  • Development: software utilities suited for developers. These include the valgrind debugging tool, QT development tools, CMake, GNU make, Subversion, and git.
  • Hardware-Drivers: if you expand the + you can select additional drivers to install: HPLIP (for HP printers), Handheld (for syncing with WinCE devices), and NVIDIA . If you have an NVIDIA video card or a HP printer, check the applicable box to install the required drivers.
Template:Word-note Fluxbox is always installed and available in the login menu of a PC-BSD® system.

If you check the box of a component that has a + next to it, it will automatically select all of its sub-components. You can click the + to expand and uncheck any sub-components that you do not wish to install.

Once you have made your selection(s), click the "Save" button to save your selections. The "System Selection" box will list the components that you selected for installation. You can now click the "Next" button to proceed to the next screen.

Template:Word-note if you are installing a desktop, the installer will display a pop-up message if it cannot find a physical or virtual disk that meets the recommended minimum size of 50GB. It will let you continue an installation on a smaller disk, but you may run into disk space issues.



Disk Selection Screen

The "Disk Selection" screen, seen in Figure 3.4a, summarizes the default disk configuration.

By default, PC-BSD® will assume that you wish to install on the entire first disk.
Figure 3.4a: Disk Selection Screen
DANGER! If you are installing PC-BSD® as the only operating system on your computer, simply click "Next" to start the installation. However, if this is not your intent, review the rest of this section to determine how to layout your disk. If you plan on booting PC-BSD® with another operating system, you should also review the section on Dual Booting.

If you wish to select which disk or partition to install PC-BSD® into, click the "Customize" button to start the "Disk Setup Wizard", shown in Figure 3.4b.

The wizard provides three modes of operation. The rest of this section describes these modes in detail.

  • Basic: (default) select this mode if you wish to specify which partition or disk to install to.
  • Advanced: select this mode if you wish to specify the installation partition or disk, use GPT partitioning, disable the FreeBSD boot menu, or specify the filesystem layout.
  • FreeBSD Expert: select this mode if you prefer to drop down to a shell to manually enter the commands to setup your disk.
DANGER! Regardless of the mode that you select, once the disk wizard completes and you click "Next" at the disk "Summary" screen, a pop-up window will ask if you would like to start the installation. Be sure to review the disk summary before clicking "Yes" and starting the installation.  The disk "Summary" screen is your very last chance to make sure that you are ready.  Once you click "Yes", the selected hard drive or partition will be formatted and any data it contains will be lost .
Figure 3.4b: Disk Setup Wizard

Once you have finished configuring your disks, you can save the finished configuration to re-use it at a later time. Insert a FAT-formatted USB stick and click "Save Config to USB".

Basic Mode

If you select "Basic" mode, the wizard will display the screen shown in Figure 3.4c.

Figure 3.4c: Select a Disk or Partition

By default, the first hard disk will be selected. If you wish to install on a different disk, use the "Selected Disk" drop-down menu to select the disk to install into.

By default, the entire selected disk will be formatted. If the disk has been divided into partitions and you wish to install into a specific partition, use the "Selected Partition" drop-down menu to select the desired primary partition.

NOTE: PC-BSD® will only install into a primary partition. That is, you can not install PC-BSD® into a secondary or an extended partition. If you wish to create a new primary partition to install into, see Partitioning the Hard Drive for instructions on how to do this.

Once you have selected the disk and partition, click "Next" to return to the disk "Summary" screen so that you can review your selections. If you wish to change anything, use the "Back" button to return to a previous screen. Otherwise, click "Finish" to leave the wizard. Click Next then Yes to start the installation.

Advanced Mode

If you select advanced mode, the wizard will display the screen shown in Figure 3.4d.

Figure 3.4d: Advanced Mode Options

This screen provides the following options:

  • Partition disk with GPT: GPT[80] is a partition table layout that supports larger partition sizes than the traditional MBR layout. If your installation disk/partition is larger than 2 TB, this box must be checked, otherwise checking this box is optional. Some older motherboards do not support this option. If the installation fails with this option checked, try again with the box unchecked. When in doubt, leave this box unchecked.
  • Force ZFS 4k block size: this option should only be checked if you know for sure that the disk supports 4k, even though it lies and reports its size as 512b. Use with caution as it may cause the installation to fail.
  • Install GRUB boot-loader: unchecking this option will disable Boot Manager.
  • ZFS pool name: if you wish to use a pool name other than the default of tank, check this box and input the name of the pool. Note that root is a reserved term and can not be used as a pool name.

After making your selections click “Next” to access the ZFS configuration screen. The rest of this section provides a ZFS overview and demonstrates how to customize the ZFS layout.

ZFS Overview

ZFS is an enterprise grade file-system, which provides many features including: support for high storage capacities, high reliability, the ability to quickly take snapshots, boot environments, continuous integrity checking and automatic repair, RAIDZ which was designed to overcome the limitations of hardware RAID, and native NFSv4 ACLs.

If you are new to ZFS, the Wikipedia entry on ZFS[8] provides an excellent starting point to learn about its features. These resources are also useful to bookmark and refer to as needed:

The following is a glossary of terms used by ZFS:

Pool: a collection of devices that provides physical storage and data replication managed by ZFS. This pooled storage model eliminates the concept of volumes and the associated problems of partitions, provisioning, wasted bandwidth and stranded storage. Thousands of filesystems can draw from a common storage pool, each one consuming only as much space as it actually needs. The combined I/O bandwidth of all devices in the pool is available to all filesystems at all times. The Storage Pools Recommendations[87] of the ZFS Best Practices Guide provides detailed recommendations for creating the storage pool.

Mirror: a form of RAID where all data is mirrored onto two or more disks, creating a redundant copy should a disk fail.

RAIDZ: ZFS software solution that is equivalent to RAID5 in that it allows one disk to fail without losing data. Requires a minimum of 3 disks though 5 disks is recommended.

RAIDZ2: double-parity ZFS software solution that is similar to RAID6 in that it allows two disks to fail without losing data. Requires a minimum of 4 disks.

RAIDZ3: triple-parity ZFS software solution. RAIDZ3 offers three parity drives and can operate in degraded mode if up to three drives fail with no restrictions on which drives can fail.

Dataset: once a pool is created, it can be divided into datasets. A dataset is similar to a folder in that it supports permissions. A dataset is also similar to a filesystem in that you can set properties such as quotas and compression.

Snapshot: a read-only point-in-time copy of a filesystem. Snapshots can be created quickly and, if little data changes, new snapshots take up very little space. For example, a snapshot where no files have changed takes 0MB of storage, but if you change a 10GB file it will keep a copy of both the old and the new 10GB version. Snapshots provide a clever way of keeping a history of files, should you need to recover an older copy or even a deleted file. For this reason, many administrators take snapshots often (e.g. every 15 minutes), store them for a period of time (e.g. for a month), and store them on another system. Such a strategy allows the administrator to roll the system back to a specific time or, if there is a catastrophic loss, an off-site snapshot can restore the system up to the last snapshot interval (e.g. within 15 minutes of the data loss). Snapshots can be cloned or rolled back, but the files on the snapshot cannot be accessed independently.

Clone: a writable copy of a snapshot which can only be created on the same ZFS volume. Clones provide an extremely space-efficient way to store many copies of mostly-shared data such as workspaces, software installations, and diskless clients. Clones do not inherit the properties of the parent dataset, but rather inherit the properties based on where the clone is created in the ZFS pool. Because a clone initially shares all its disk space with the original snapshot, its used property is initially zero. As changes are made to the clone, it uses more space.

ZFS Layout

In Advanced Mode, the disk setup wizard allows you to configure your ZFS layout. The initial ZFS configuration screen is seen in Figure 3.4e.

Figure 3.4e: ZFS Configuration

If your system contains multiple drives and you would like to use them to create a ZFS mirror or RAIDZ, check the box "Enable ZFS mirror/raidz mode" which will enable the rest of the options in this screen. In the example shown in Figure 3.4e, the system has 7 disks, all of which are the same size. The first disk, ada0, was pre-selected in Figure 3.4d and the remaining 6 disks (ada1 to ada6) are available to be added to the ZFS pool.

NOTE: The PC-BSD® installer requires you to use entire disks (not partitions) when creating a ZFS mirror or RAIDZ.

If you have never configured a RAIDZ before, take the time to read the RAIDZ Configuration Requirements and Recommendations[88] first. It indicates the optimum number of disks for each type of configuration. While ZFS will let you use disks of different sizes, this is discouraged as it will decrease storage capacity and performance of the ZFS system.

The PC-BSD® installer supports the following ZFS configurations:

  • mirror: requires a minimum of 2 disks.
  • RAIDZ1: requires a minimum of 3 disks. For best performance, 3, 5, or 9 disks are recommended.
  • RAIDZ2: requires a minimum of 4 disks. For best performance, 4, 6, or 10 disks are recommended.
  • RAIDZ3: requires a minimum of 5 disks. For best performance, 5, 7, or 11 disks are recommended.

The installer will not let you save a configuration if your system does not meet the minimum number of disks required by that configuration. As you select a configuration, a message will indicate how many more disks you need to select.

To use multiple disks, select the type of configuration from the "ZFS Virtual Device Mode" drop-down menu, then check the box for each disk that you would like to add to that configuration. When finished, click the Next button to see the default layout screen shown in Figure 3.4f.

Figure 3.4f: Default ZFS Layout

Regardless of how many disks you selected for your ZFS configuration, the default layout will be the same. ZFS does not require separate partitions for /usr, /tmp, or /var. Instead, you create one ZFS partition (pool) and specify a mount for each dataset. A /boot partition is not mandatory with ZFS as the PC-BSD® installer puts a 64k partition at the beginning of the drive.


WARNING do not remove any of the default mount points as they are used by PC-BSD®.

You can use the "Add" button to add additional mount points. You will only be prompted for the name of the mount point as size is not limited at creation time. Instead, the data on any mount point can continue to grow as long as space remains within the ZFS pool.

If you wish to set the swap size, click the "Swap Size" button. This will prompt you to enter a size in MB. If you have created a RAIDZ or mirror, a swap partition of the specified size will be created on each disk and mirrored between the drives. For example, if you specify a 2048MB swap size, a 2GB swap partition will be created on all of the specified disks, yet the total swap size will be 2GB, due to redundancy.

If you right-click any mount point, you can toggle between enabling or disabling any of the following ZFS properties.

  • atime: when set to "on", controls whether the access time for files is updated when they are read. When set to "off", this property avoids producing write traffic when reading files and can result in significant performance gains, though it might confuse mailers and some other utilities.
  • canmount: if set to "off", the filesystem cannot be mounted.
  • checksum: automatically verifies the integrity of the data stored on disks. Setting this property to "off" is highly discouraged.
  • compression: if set to "on", automatically compresses stored data to conserve disk space.
  • exec: if set to "off", processes can not be executed from within this filesystem.

Once you click "Next", the wizard will show a summary of your selections. If you wish to change anything, use the "Back" button to return to a previous screen. Otherwise, click "Finish" to leave the wizard and return to the "Disk Selection" screen.

FreeBSD Expert Mode

If you select FreeBSD expert mode, you will be prompted to launch a terminal where you can use command line utilities such as bsdinstall or sysinstall to manually configure the partitions. When you are finished, type exit to leave the terminal, then click "Next" to review the disk summary. If you wish to change anything, use the "Back" button to return to a previous screen. Otherwise, click "Finish" to leave the wizard and return to the "Disk Selection" screen.



Installation Progress Screen

Figure 3.5a: Installation Progress Screen

Once you select "Yes" to start the installation, a progress screen, seen in Figure 3.5a, provides a progress bar and messages so that you can watch the installation's progress.

How long the installation takes depends upon the speed of your hardware, the installation type you selected, and the number of components to be installed. A typical installation takes between 15 and 30 minutes.



Installation Finished Screen

Figure 3.6a: PC-BSD® Installation is Now Complete

The screen shown in Figure 3.6a appears once the installation is complete.

Click the "Finish" button to reboot into your PC-BSD® installation. Wait until the installer exits before removing the installation media.



Post Installation Configuration and Installation Troubleshooting

Once PC-BSD® is installed, it will reboot into the new operating system.

Once the PC-BSD® system has finished booting for the first time, the installer will present you with some additional screens so that you can configure your system. This section describes the following post-installation steps and provides some troubleshooting tips for failed installations.



Booting Into PC-BSD®

After installation, PC-BSD® will reboot and you will be prompted to configure your system and to login to a desktop.

Figure 4.1a: PC-BSD® Graphical Boot Menu

Once the first boot is complete, the installer will attempt to set the optimal display settings. A pop-up menu will ask if you would like to accept these settings. Simply click "Yes" to continue. PC-BSD® will then play a short video before proceeding to the first post configuration screen. You can press Esc to skip the video. If you wish to watch the video at a later time, it is located in /usr/local/share/pcbsd/movies/.

Read through the rest of this section if your system hangs at boot time or if you have problems setting the display settings. If you are dual booting and your other operating system was not automatically added to the graphical boot menu by the installer, refer to Dual Booting.

Interrupting the Boot to Access the Boot Menu

By default, the graphical PC-BSD® bootloader menu shown in Figure 4.1a is not displayed at boot time.

This menu is used to display the installation of PC-BSD®, any boot environments created with Boot Manager, and other operating systems installed on a dual-boot system.

To access this menu, you have to be quick. As soon as the boot process starts and you see a "GRUB loading" message in the upper left corner, press Esc. After the system boots, you can increase the timer value in Boot Manager if you find that the boot delay is too quick.
Figure 4.1b: PC-BSD® Graphical Boot Menu Options

Once you access the graphical menu, it will pause for a few seconds then continue to boot PC-BSD®. If you wish to select a different operating system or specify how PC-BSD® boots, press a key to pause this screen. If multiple operating systems are available and you want to boot into PC-BSD®, make sure it is highlighted and press enter. This will load the PC-BSD® boot options screen shown in Figure 4.1b.

The following boot options are available:

  • Normal Bootup: continues to boot PC-BSD®.
  • Single User Mode: advanced users can select this option to fix critical system failures.
  • Verbose Mode: select this option if you would like to see more detailed messages during the boot process. This can be useful if you are troubleshooting a piece of hardware.


  • Run the Display Wizard: if you are unable to access the GUI due to a display setting, enable this option to boot into the display settings wizard.
  • Run X in vesa mode: try this option if the screen goes black or the system freezes when booting into PC-BSD®.

Use the arrow keys to select an option then press enter to boot using that option.

This menu is provided by GRUB. If you are familiar with editing GRUB, you can press e to access the GRUB editor or c to access the GRUB command line.
Figure 4.1c: Display Settings Wizard

If Your Display is Not Automatically Detected

If the optimal display settings can not be determined during first boot, if you select “No” in the “Confirm Resolution” screen when asked to confirm the display settings, or if you select “Run the Display Wizard” from the boot menu, the “Display Settings” screen shown in Figure 4.1c will launch.

The settings in this screen are described in more detail in Display. If you wish to return to this display wizard at a later time, go to Control Panel → Display.

If you change any display settings, click the "Apply" button for the settings to be tested. If anything goes wrong during testing, you will be taken back to the "Display Settings" screen so that you can try another setting. Once you are happy with the tested setting, click the "Yes" button to save the setting and to proceed.

Fast Boot

PC-BSD® uses a "fast boot" script to decrease the amount of time that it takes the system to boot to the login screen. When this script is enabled, which is the default, services are started in the background and the boot process does not wait for confirmation from each service as it starts. This is referred to as delayed mode.

The fast boot script is controlled by these lines in /etc/rc.conf.pcbsd:

fastboot_enable="YES"
fastboot_earlyrc="/etc/rc.d/moused /etc/rc.d/pefs /usr/local/etc/rc.d/dbus /usr/local/etc/rc.d/hald /usr/local/etc/rc.d/gdm"

The logfile /var/log/rc_delay.log shows the startup messages for the services which were started in delayed mode. If this log indicates that a delayed mode service is not starting correctly, become the superuser, copy the fastboot_earlyrc line to /etc/rc.conf, remove that service from that line, and reboot to see if that fixes the problem.

If a faster boot time is not important to you and you prefer to watch each service as it starts at boot time, you can disable fast boot by adding fastboot_enable="NO" to /etc/rc.conf.



Language Screen

Figure 4.2a: Language Selection Screen

Once the introductory video finishes, the language selection screen will again be displayed, as seen in Figure 4.2a. This allows you to select the language you will use to access the installed system. Once you have made your selection, click "Next" to go to the next configuration screen.



Time Zone Selection Screen

Figure 4.3a: Select Time Zone

The next configuration screen, shown in Figure 4.3a, allows you to select your timezone. Use the drop-down menu to select the city closest to your location.

A default system hostname will be created for you. If you wish to change the default, type in the desired hostname in the "System Hostname" field.

When finished, click "Next" to proceed to the next screen.



Set Root Password Screen

This configuration screen, seen in Figure 4.4a, requires you to set the root password. The password must be a minimum of 4 characters, and you are required to type it in twice to confirm the password. Click the "Next" button when you are finished.

Figure 4.4a: Set Root Password



Create a User Screen

This screen is used to create the primary user account that will be used to login to the system.
Figure 4.5a: User Creation Screen
Set a good value for the password as it is used whenever the system indicates that administrative access is required.

Figure 4.5a shows the configuration screen used to create the initial user account. This screen requires you to complete the following fields:

  • Name: this value will be displayed in the login screen. It can be your full name and can contain capital letters and spaces.
  • Username: this is the name you will use when logging in. It can not contain spaces and is case sensitive (e.g. Kris is a different username than kris).
  • Password: this is the password you will use when logging in. You must type it twice in order to confirm it.

If you share your computer with other users, you will be able to create additional user accounts once you are logged in using Control Panel → User Manager.

If you hover over "Encrypt user files", a checkbox will appear. If you check this box, the contents of the user's home directory will be encrypted using PEFS[89]. This type of encryption automatically decrypts the files in the user's home directory when they login and automatically encrypts the contents again when the user logs out.

NOTE: At this time, the PEFS encryption system does not support the user changing their password. For this reason, be sure to select a strong password that you will not forget.



Connect to a Wireless Network

If the system has an active wireless interface, a screen similar to Figure 4.6a will indicate the wireless networks which were automatically detected.

Figure 4.6a: Connect to a Wireless Network

If you would like to set the default wireless connection, highlight the network that you would like to connect to. If the network does not appear, you can click the "Rescan" button. If you are unable to connect or you wish to configure the connection at a later time, see the section on Network Configuration.

When finished, click the "Next" button to continue the post-configuration tasks.



Post Install Finished Screen

Figure 4.7a: Setup is Complete

The screen in Figure 4.7a indicates that the post-installation setup is complete.

Click the "Finish" button to access the login menu.



Logging In

Once you have finished setting up your system, you will be presented with the login screen seen in Figure 4.8a. The Username that you created in the Create a User Screen will be listed (in this example, it is dru).

Figure 4.8a: PC-BSD® Login Screen


WARNING Do not log in as the root user. Instead, login as the user account that you created and reinput your password whenever a task requires it. If you are working from the command line, you can use the pc-su or sudo commands which will prompt for your password before performing a task that requires administrative permissions.

Accessibility Options

Figure 4.8b: Universal Access Preferences

If you click the "Universal Access" button in the task bar (round icon with a stick figure), you can set the accessibility options shown in Figure 4.8b.

If you installed PC-BSD® on a laptop, the taskbar will also show the current battery charge level when you hover your mouse over the power icon. The taskbar includes a clock followed by a "Shutdown Options" icon. If you click that icon, you can choose to restart or shutdown the system.

Login Options

If you highlight the username, some more options will be added to the left side of the taskbar as shown in Figure 4.8c:

These options allow you to select your language, keyboard layout, and desktop to use for the login session. Once you have made your selections, input the password associated with the selected user and press enter.

NOTE: If you just get the login prompt after typing the password, the password was incorrect. Double-check that caps lock is not on and try typing the password again.

If you wish to add or delete any desktops, use Package Manager.

If you wish to enable auto-login, see the section on GDM Manager.

Figure 4.8c: Login Menu with User Selected
Figure 4.8d: PC-BSD® Getting Started Screen

Welcome & Getting Started

The first time you log in, the PC-BSD® "Getting Started" screen will load as seen in Figure 4.8d.

If you click the "Next" button, you can read an overview of the utilities that are used to configure your network connection, install applications, configure your system, make a backup, and keep the system updated, as well as how to get involved with the PC-BSD® community. Check the box “Don't show this greeting on next startup” if you do not want to see this screen the next time you log in. To re-open the screen after checking that box, type pc-welcome.



Installation Troubleshooting

Installing PC-BSD® is usually an easy process that "just works". Sometimes, however, you will run into a problem. This section will look at solutions to the most common installation problems.

Installation Starts But Fails

The PC-BSD® installer creates a log which keeps a record of all the steps that are completed as well as any errors. When an installation error occurs, the PC-BSD® installer will ask if you would like to generate an error report. If you click "Yes", a pop-up message will ask if you would like to save the error log to a USB stick. Type y and insert a FAT formatted USB thumb drive to copy the log.

While in the installer, you can read this log to see what went wrong. Right-click an area on the desktop outside of the installation window and select "xterm" from the menu. You can read the log with this command:

more /tmp/pc-sysinstall.log                                                     

If you can not figure out how to fix the error or believe that you have discovered an installation bug, send the log that was saved on the USB stick using the PC-BSD® Bug Reporting tool.

System Does not Boot Into the Installer

If the installer does not make it to the initial GUI installer screen, try unplugging as many devices as possible, such as webcams, scanners, printers, USB mice and keyboards. If this solves the problem, plug in one piece of hardware at a time, then reboot. This will help you pinpoint which device is causing the problem.

If your computer freezes while probing hardware, and unplugging extra devices does not fix the problem, it is possible that the installation media is corrupt. If the checksum on the file you downloaded is correct, try burning the file again at a lower speed.

If the system freezes and you suspect the video card to be the cause, review your system's BIOS settings. If there is a setting for video memory, set it to its highest value. Also check to see if the BIOS is set to prefer built-in graphics or a non-existent graphics card. On some systems this is determined by the order of the devices listed; in this case, make sure that the preferred device is listed first. If you cannot see your BIOS settings you may need to move a jumper or remove a battery to make it revert to the default of built-in graphics; check your manual or contact your manufacturer for details.

If that change did not help, try rebooting and selecting option "7. Escape to loader prompt" from the boot menu shown in Figure 4.9a.

Figure 4.9a: PC-BSD® Installer Boot Menu

Selecting this option will open the boot loader prompt where you can type the following commands:

unload                                                                

disable-module vesa set module_path=/boot/kernel;/boot/modules;CONSOLE

boot

Those commands will disable the vesa splash screen before attempting to boot the installer.

A not uncommon cause for problems is the LBA (Logical Block Addressing) setting in the BIOS. If your PC is not booting up before or after installation, check your BIOS and turn LBA off (do not leave it on automatic).

If the SATA settings in your BIOS are set to "compatibility" mode, try changing this setting to "AHCI". If the system hangs with a BTX error, try turning off AHCI in the BIOS.

USB Keyboard Does not Work in Installer

If the USB keyboard is non-functional, check if there is an option in your BIOS for legacy support in relation to the keyboard or to USB, or both. Enabling this feature in your BIOS may solve this issue.

mountroot prompt

If you boot your system and you receive a mountroot> command prompt, it may be due to a change in the location of the boot device. This can occur when the installation was made on another machine and then transferring the HDD without an adjustment to the /etc/fstab file, or if a card reader is involved (including card readers on a USB dongle). The solution is to enter ufs:/dev/da1 at the prompt (it will always be ufs for the installer media). Depending on the exact location of the boot media, it may be different than da1. Typing ? at the prompt should display available devices.

Getting Help

If none of the above has fixed your problem, search the PC-BSD® forums[90] to see if a solution exists, try a web search, or check the section on Finding Help.



Advanced Installation Topics

The previous section discussed a default installation of PC-BSD®. This section covers the following advanced installation topics:



Install a Server

Figure 5.1a: Selecting to Install TrueOS®

The System Selection Screen of the PC-BSD® installer can be used to install TrueOS®, a FreeBSD-based server operating system, rather than a PC-BSD® desktop operating system.

TrueOS® adds the following to a vanilla installation of FreeBSD: PBI Manager, the command line version of warden, and the command line versions of most of the Control Panel utilities. You will find those utilities in /usr/local/bin/pc-*. It also installs this list [91] of additional shells and utilities.

For a server installation, using the PC-BSD® installer rather than the FreeBSD installer offers several benefits:

  • a wizard (described in this section) is provided during installation to configure the server for first use.

To perform a server installation, start the PC-BSD® installation as usual. When you get to the System Selection Screen of the installer, select "Server (TrueOS)", as shown in Figure 5.1a.

If you wish to install any additional server software, click the "Customize" button. This screen, shown in Figure 5.1b, can be used to install packages such as MySQL, PostgreSQL, Samba, PHP, VirtualBox, Apache, and Lighttp.

Figure 5.1b: Installing Server Applications into TrueOS®

After making your selections, press "Next" to start the "Server Setup Wizard". Click "Next" again to see the screen shown in Figure 5.1c.

Figure 5.1c: Set the Root Password

Input and confirm the root password then click "Next" to proceed to the screen shown in Figure 5.1d.

Figure 5.1d: Create the Primary User Account

For security reasons, you should not login as the root user. For this reason, the wizard requires you to create a primary user account that will be used to login to the FreeBSD system. This account will automatically be added to the wheel group, allowing that user to su to the root account when administrative access is required.

This screen contains the following fields:

  • Name: can contain capital letters and spaces.
  • Username: the name used when logging in. Can not contain spaces and is case sensitive (e.g. Kris is a different username than kris).
  • Password: the password used when logging in. You must type it twice in order to confirm it.
  • Default shell: use the drop-down menu to select the csh, tcsh, or sh login shell.

When finished, click "Next" to proceed to the screen shown in Figure 5.1e.

Figure 5.1e: Set the Hostname

Input the system's hostname. If you will be using ssh to administer the system, check the box "Enable remote SSH login". Click "Next" to proceed to the network configuration screen shown in Figure 5.1f.

Figure 5.1f: Configure the Network

Use the "Network Interface" drop-down menu to select from the following:

  • AUTO-DHCP-SLAAC: (default) will configure every active interface configured for DHCP and both IPv4 and IPv6
  • AUTO-DHCP: will configure every active interface for DHCP and IPv4
  • IPv6-SLAAC: will configure every active interface for DHCP and IPv6

Alternately, select the device name for the interface that you wish to manually configure and input the IPv4 and/or IPv6 addressing information. When finished, click "Next" to proceed to the screen shown in Figure 5.1g.

Figure 5.1g: Install Source or Ports

If you wish to install FreeBSD source or ports, check the associated box(es) then click "Finish" to exit the wizard and access the summary screen shown in Figure 5.1h.

Figure 5.1h: Review Installation Summary

Click "Customize" if you wish to proceed to the Disk Selection Screen in order to configure the system's disk(s).

If you wish to save the finished configuration to re-use it at a later time, insert a FAT-formatted USB stick and click "Save Config to USB".

Once you are ready to start the installation, click "Next". A pop-up menu will ask if you would like to start the installation now.

Once the system is installed, it will boot to a command-line login prompt. Login using the primary user account that was configured during installation. You can now configure and use the server as you would any other FreeBSD server installation. The FreeBSD Handbook[92] is an excellent reference for performing common FreeBSD server tasks.



Convert a FreeBSD System to PC-BSD®

PC-BSD® utilities dealing with software installation and upgrades use pkgng[93], FreeBSD's Next Generation package management tool. Part of this change included the creation of a custom PC-BSD® package repository which contains all of the packages that can be built using pkgng. FreeBSD users who use pkgng are also welcome to use the PC-BSD® package repository.

This package repository contains a custom package, called pcbsd-base, which can be used to easily convert an existing FreeBSD installation into a PC-BSD® desktop. It also contains a custom package called trueos-base which can be used to convert an existing FreeBSD installation into a TrueOS® server. The converted desktop will contain all of the graphical utilities that come with PC-BSD® and the converted server will contain all of their command line equivalents.

This section describes how to:

  • Configure a FreeBSD or PC-BSD® system to use the pkgng repository.
  • Convert a FreeBSD system to a PC-BSD® desktop.
  • Convert a FreeBSD system to a TrueOS® server.

Switching to the PC-BSD® pkgng Repository

If you are running PC-BSD® 9.2-RELEASE or FreeBSD 9.2 or higher, type pkg in order to automatically install the software that is required. NOTE: PKGNG will need to be version 1.2.x or higher!

Then, run the command pkg2ng to import your existing package database from the old format to the new pkgng format.

Next, configure access to the PC-BSD® repository. Start by creating the file /usr/local/etc/pkg/repos/pcbsd.conf with the following contents:

pcbsd: { url: "http://pkg.cdn.pcbsd.org/9.2-RELEASE/amd64", signature_type: "fingerprints", fingerprints: "/usr/local/etc/pkg/fingerprints/pcbsd", enabled: true }


Next, create the following directories:

mkdir /usr/local/etc/pkg/fingerprints/pcbsd/revoked mkdir /usr/local/etc/pkg/fingerprints/pcbsd/trusted

Now download the repository's fingerprint file public fingerprint file[94], and copy it to /usr/local/etc/pkg/fingerprints/pcbsd/trusted/.

The system is now configured and you now update your packages to the latest versions from the pkgng repository using the following command:

pkg upgrade -fy                                                                 

Depending upon what is already installed, you may have to resolve some error messages in order to successfully upgrade all packages.

To install and delete packages, use the pkg command. This command differs in usage from the original package format version. You can learn more about how to use this command in Section 5.5.3 of the FreeBSD Handbook[93].

Converting FreeBSD to a PC-BSD® Desktop

Once the repository configuration is complete, it is now easy to convert a FreeBSD system into a PC-BSD® desktop using the following commands as the superuser:

pkg install -fy pcbsd-base                                                      

rehash pbreg set /PC-BSD/SysType PCBSD pc-extractoverlay desktop

pc-extractoverlay ports

Next, reboot the system and the PC-BSD® login manager will start, allowing you to login to the desktop. If you want the PC-BSD® display wizard and first boot wizards to run first, run these commands before rebooting:

touch /var/.runxsetup                                                           

touch /var/.pcbsd-firstboot

touch /var/.pcbsd-firstgui

If you are running FreeBSD 10-CURRENT, specify the PBI version to pull from. To do so, edit /usr/local/etc/pbi.conf and add this line:

PBI_FBSDMAJOR: 9                                                                
NOTE: If you are using NVIDIA video hardware, load the driver before rebooting into the display wizard by running the command pc-metapkgmanager add NVIDIA.

Converting FreeBSD to a TrueOS® Server

If you wish to convert a FreeBSD server to TrueOS®, use the following commands:

pkg install -fy trueos-base                                                     

rehash pbreg set /PC-BSD/SysType TRUEOS pc-extractoverlay server

pc-extractoverlay ports

The installation of the trueos-base package will install the following: PBI Manager, the command line version of warden, and the command line versions of most of the Control Panel utilities. You will find those utilities in /usr/local/bin/pc-*. It also installs these additional shells and utilities[95]. </translate>


Using a Rolling Release

In February, 2013, PC‑BSD® switched to a rolling release model. This is intended to make it easier for users to keep the packages that came with the operating system up-to-date and to make new features available for testing before the next major version is released.

The rolling release model is optional. This means that users can choose to either remain on a RELEASE or to upgrade an existing RELEASE to STABLE. Users that remain on RELEASE will still be notified of security updates and updates to software installed using PC-BSD® utilities. However, they will not receive any new drivers or features until they upgrade to the next RELEASE.

Currently, the schedule for updates is as follows:

  • RELEASE: PC-BSD® software repository is updated on or about the 1st and 15th of each month.
  • STABLE: PC-BSD® software repository is updated on or about the 5th and 20th of each month. In addition, a new update patch is issued on the 1st of each month which can be used to update to the latest STABLE.

Users who wish to install a version of PC-BSD® which contains the latest operating system features can choose to install STABLE instead of RELEASE.

The rest of this section will demonstrate how to upgrade a RELEASE to STABLE. It also describes how to install a STABLE version.

NOTE: The rolling release model is new to PC-BSD® and glitches should be expected. RELEASE is recommended for users who prefer stability and who do not wish to test new features. STABLE is recommended for users who are comfortable with finding and reporting bugs.

Upgrading a RELEASE to STABLE

To upgrade a PC-BSD® RELEASE system to STABLE, become the superuser and edit the file /usr/local/share/pcbsd/pc-updatemanager/conf/sysupdate.conf. Change this line:

PATCHSET: pcbsd                                                                 

to

PATCHSET: pcbsdtest                                                             

Once the edit is saved, you can use either Update Manager or pc-updatemanager to upgrade to the latest STABLE. Once the upgrade is complete, it will automatically change the above line so that it looks like this:

PATCHSET: updates                                                               

Around the 1st of each month, the upgrade to the next STABLE will appear in Update Manager. If you find a bug in a rolling release, please report it using the PC-BSD® Bug Reporting utility.

NOTE: As with any upgrade, always backup your data first. Life Preserver can be used to backup your home directory to another system in your network.

Installing a Rolling Release

To install the latest STABLE version from DVD or USB media, or to try a live USB image, select the desired media type from the PC-BSD CDN[96]. Rolling releases always have a date in the media name and you should choose the most recent date. After downloading the desired file, you can install or use the live image as usual, as described in Chapters 2-4 of this Handbook.

Once installed, STABLE will automatically notify you when a newer STABLE version becomes available. You can use either Update Manager or pc-updatemanager to upgrade to the latest STABLE.

Before upgrading, always backup your data. If you find a bug in a STABLE version, please report it using the PC-BSD® Bug Reporting utility.



Dual Booting

A PC-BSD® installation assumes that you have an existing primary partition to install into. If your computer has only one disk and PC-BSD® will be the only operating system, it is fine to accept the default partitioning scheme. However, if you will be sharing PC-BSD® with other operating systems, care has to be taken that PC-BSD® is installed into the correct partition; otherwise, you may inadvertently overwrite an existing operating system.

If you wish to install multiple operating systems on your computer, you will need the following:

  • a partition for each operating system. Many operating systems, including PC-BSD®, can only be installed into a primary partition. This means that you will need to use partitioning software as described in Partitioning the Hard Drive.
  • a boot loader that allows you to select which operating system you wish to boot into. Depending upon the choice of boot loader and the operating systems that you install, you may or may not have to configure the boot loader to list all of the installed operating systems. Also, depending upon the order that you install the operating systems, the existing MBR data may be overwritten. This section will describe the configuration of several different boot loaders and how to restore an overwritten MBR.
  • a backup of any existing data. This backup should not be stored on your computer's hard drive but on another computer; on removable media, such as a USB drive; or burnt onto a DVD media. If you are careful in your installation, everything should go fine. However, you will be glad that you made a backup should something go wrong.

Choosing the Installation Partition

When installing PC-BSD® onto a computer that is to contain multiple operating systems, care must be taken to select the correct partition in the Disk Selection screen of the installation. On a system containing multiple partitions, each partition will be listed. Highlight the partition that you wish to install into and make sure that you do not select a partition that already contains an operating system or data that you wish to keep.

DANGER! make sure that you click the "Customize" button while in the "Disk Selection" screen. If you just click Next without customizing the disk layout, the installer will overwrite the contents of the primary disk.

GRUB Boot Loader

If you install PC-BSD® on a computer that already contains an operating system, an entry for PC-BSD® will automatically be added to the PC-BSD® boot menu. Depending upon which other operating systems are installed, the installer may or may not automatically detect and add entries for the other operating systems.

If your other operating system is not found, use the PC-BSD® Bug Reporting tool to create a bug report. Include the version of the missing operating system and on which disk and partition that operating system is installed. If you are already familiar with how to create GRUB entries and are successful in manually adding an entry, include that entry in your bug report. This way, other PC-BSD® users with similar layouts can benefit when the required GRUB entry is added to the installer's logic.



Creating an Automated Installation with pc-sysinstall

PC-BSD® provides a set of Bourne shell scripts that allow advanced users to create automatic or customized PC-BSD® installations. pc-sysinstall is the name of the master script; it reads a customizable configuration file and uses dozens of backend scripts to perform the installation. You can read more about this utility by typing man pc-sysinstall.

Here is a quick overview of the components used by pc-sysinstall:

  • /usr/share/pc-sysinstall/backend/ contains the scripts used by the PC-BSD® installer. Scripts have been divided by function, such as functions-bsdlabel.sh and functions-installcomponents.sh. If you have ever wondered how the PC-BSD® installer works, read through these scripts. This directory also contains the parseconfig.sh and startautoinstall.sh scripts which pc-sysinstall uses to parse the configuration file and begin the installation.
  • /usr/share/pc-sysinstall/backend-partmanager/ contains the scripts which are used by the installer to create and delete partitions.
  • /usr/share/pc-sysinstall/backend-query/ contains the scripts which are used by the installer to detect (e.g. detect-nics.sh) and configure (e.g. enable-net.sh) hardware.
  • /usr/share/pc-sysinstall/conf/ contains the configuration file pc-sysinstall.conf. It also contains a file indicating which localizations are available (avail-langs), and a license/ subdirectory containing text files of applicable licenses (e.g. bsd-en.txt and nvidia-en.txt).
  • /usr/share/pc-sysinstall/doc/ contains the help text that is seen if you run pc-sysinstall without any arguments.
  • /usr/share/examples/pc-sysinstall/ contains several example configuration files for different scenarios (e.g. upgrade, fbsd-netinstall). The README file in this directory should be considered as mandatory reading before using pc-sysinstall.
  • /usr/sbin/pc-sysinstall this is the script that is used to perform a customized installation.

To create a custom installation, perform the following steps:

  1. Determine which variables you wish to customize.
  2. Create a customized configuration.
  3. Create a custom installation media.

These steps are discussed in more detail below.

Determine Which Variables you Wish to Customize

A list of possible variables can be found in /usr/share/examples/pc-sysinstall/README and in Table 5.5a. Note that the Table is meant as a quick reference to determine which variables are available. The README file contains more complete descriptions for each variable.


Table 5.5a: Available Variables for Customizing a PC-BSD® Installation [tables 4]
Variable Options Description
hostname= should be unique for the network optional as installer will auto-generate a hostname if empty
installMode= fresh, upgrade, extract, or zfsrestore sets the installation type
installLocation= /path/to/location used only when installMode is extract and should point to an already mounted location
installInteractive= yes or no set to no for automated installs without user input
netDev= AUTO-DHCP or FreeBSD interface name type of network connection to use during the installation
netIP= IP address of interface used during installation only use if netDev is set to an interface name
netMask= subnet mask of interface only use if netDev is set to an interface name
netNameServer= IP address of DNS server only use if netDev is set to an interface name
netDefaultRouter= IP address of default gateway only use if netDev is set to an interface name
netSaveDev= AUTO-DHCP or FreeBSD interface name(s) (multiple allowed separated by spaces) type of network configuration to enable on the installed system; can set multiple interfaces
netSaveIP= IP address of interface <interface_name> or DHCP only use if netSaveDev is set to an interface name or a list of interface names (repeat for each interface)
netSaveMask= subnet mask of interface <interface_name> only use if netSaveDev is set to an interface name or a list of interface names (repeat for each interface)
netSaveNameServer= IP address of DNS server (multiple allowed separated by spaces) only use if netSaveDev is set to an interface name or a list of interface names (do not repeat for each interface)
netSaveDefaultRouter= IP address of default gateway only use if netSaveDev is set to an interface name or a list of interface names (do not repeat for each interface)
disk0= FreeBSD disk device Name, (e.g. ad0) see README for examples
partition= all, free, s1, s2, s3, s4, image see README for examples
partscheme= MBR or GPT partition scheme type
mirror= FreeBSD disk device name (e.g. ad1) sets the target disk for the mirror (i.e. the second disk)
mirrorbal= load, prefer, round-robin, split defaults to round-robin if the mirrorbal method is not specified
bootManager= none, bsd whether or not to install the FreeBSD boot manager
image= /path/to/image will write specified image file
commitDiskPart this variable is mandatory and must be placed at the end of each diskX section; create a diskX section for each disk you wish to configure.
encpass= password value at boot time, system will prompt for this password in order to mount the associated GELI encrypted partition
commitDiskLabel this variable is mandatory and must be placed at the end of disk's partitioning settings; see the README for examples on how to set the <File System Type> <Size> <Mountpoint> entries for each disk
installMedium= dvd, usb, ftp, rsync, image source to be used for installation
installType= PCBSD, FreeBSD determines whether this is a desktop or a server install
installFile= e.g. fbsd-release.tbz only set if using a customized installer archive
packageType= tar, uzip, split the archive type on the installation media
ftpPath= e.g. ftp://iso.cdn.pcbsd.org/9.1/amd64/netinstall/ location of the installer archive when using installMedium=ftp
rsyncPath= e.g. life-preserver/back-2011-09-12T14_53_14 location of the rsync data on the remote server when using installMedium=rsync
rsyncUser= username set when using installMedium=rsync
rsyncHost= IP address of rsync server set when using installMedium=rsync
rsyncPort= port number set when using installMedium=rsync
installComponents= e.g. amarok,firefox,ports components must exist in /PCBSD/pc-sysinstall/components/
upgradeKeepDesktopProfile= yes or no specify if you wish to keep your existing user's desktop profile data during an upgrade
rootPass= password set the root password of the installed system to the specified string
rootEncPass= encrypted string set root password to specified encrypted string
userName= case sensitive value create a separate block of user values for each user you wish to create
userComment= description description text can include spaces
userPass= password of user
userEncPass encrypted string set user password to specified encrypted string
userShell= e.g. /bin/csh path to default shell
userHome= e.g. /home/username path to home directory
userGroups= e.g. wheel,operator comma separated (no spaces) list of groups
commitUser mandatory, must be last line in each user block
runCommand= path to command run the specified command within chroot of the installed system, after the installation is complete
runScript= path to script runs specified script within chroot of the installed system, after the installation is complete
runExtCommand= path to command runs a command outside the chroot
timeZone= e.g. America/New_York location must exist in /usr/share/zoneinfo/
enableNTP= yes or no enable/disable NTP
localizeLang= e.g. en sets the system console and Desktop to the target language
localizeKeyLayout= e.g. en updates the system's Xorg config to set the keyboard layout
localizeKeyModel= e.g. pc104 updates the system's Xorg config to set the keyboard model
localizeKeyVariant= e.g. intl updates the Xorg config to set the keyboard variant
autoLoginUser= username user will be logged in automatically without entering a password

Create a Customized Configuration

One way to create this file is to read through the configuration examples in /usr/share/examples/pc-sysinstall/ to find the one that most closely matches your needs. Copy that file (to any location) and customize it so that it includes the variables and values you would like to use in your installation.

An alternate way to create this file is to perform an installation of the version that you wish to customize. The installer will automatically create a file containing the settings you selected during the installation to /root/pc-sysinstall.cfg. You can use that configuration file as-is, or customize it to meet an installation's needs. This method may prove easier to use if you are performing complex disk layouts.

Here is a sample configuration:

# Sample configuration file for an installation using pc-sysinstall

installMode=fresh installInteractive=no hostname=myhost.mydomain.com

# Set the disk parameters - 1st disk disk0=da0 partition=all bootManager=none commitDiskPart

# Set the disk parameters - 2nd disk disk1=da1 partition=all bootManager=none commitDiskPart

# Setup the disk label - 1st disk # All sizes are expressed in MB # Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP disk0-part=UFS+S 1024 / disk0-part=SWAP.eli 2048 none disk0-part=UFS+S 1024 /tmp disk0-part=UFS+S 1024 /var disk0-part=UFS+S 0 /usr # Size 0 means use the rest of the slice size # Do it now! commitDiskLabel

# Setup the disk label - 2nd disk # All sizes are expressed in MB # Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP disk1-part=UFS+S 1024 /usr/src disk1-part=UFS+S 4096 /usr/local disk1-part=UFS+S 0 /usr/ports # Size 0 means use the rest of the slice size # Do it now! commitDiskLabel

netDev=em1 netIP=172.16.80.250 netMask=255.255.240.0 netNameServer=172.16.80.1 netDefaultRouter=172.16.80.1 netSaveDev=em0 em1 netSaveIP_em0=192.168.101.42 netSaveIP_em1=172.16.80.156 netSaveMask_em0=255.255.252.0 netSaveMask_em1=255.255.240.0 netSaveNameServer=172.16.80.1 netSaveDefaultRouter=192.168.100.1

# Set if we are installing via optical, USB, or FTP installType=FreeBSD installMedium=ftp ftpPath=http://pkgbuilder.mydomain.com/images/freebsd/8.2/ packageType=tar

# List our components to install #installComponents=ports,src

# Set the root pass rootPass=root

# Setup our users userName=demo userComment=Demo User userPass=demo userShell=/bin/sh userHome=/home/demo commitUser

# Set up date/time runCommand=cp /usr/share/zoneinfo/EST5EDT /etc/localtime runCommand=touch /etc/wall_cmos_clock runCommand=adjkerntz -a

# Install packages required for VMware Tools installation/configuration runCommand=pkg_add -r compat6x-amd64 runCommand=pkg_add -r perl runCommand=pkg_add -r pcre runCommand=pkg_add -r puppet runCommand=pkg_add -r sysrc

# Fetch/install VMware Tools runCommand=fetch -o /tmp/vmtools.tar.gz http://pkgbuilder.mydomain.com/images/freebsd/vmware-freebsd-tools.tar.gz

runCommand=zcat /tmp/vmtools.tar.gz

If you wish to perform a fully-automated installation that does not prompt for any user input, you will also need to review /usr/share/examples/pc-sysinstall/pc-autoinstall.conf and place a customized copy of that file into /boot/pc-autoinstall.conf on your installation media.

Table 5.5b summarizes the additional variables that are available for fully automatic installations. More detailed descriptions can be found in the /usr/share/examples/pc-sysinstall/pc-autoinstall.conf file. Note that the variables in this file use a different syntax than those in Table 5.5a, in that the values follow a colon and a space rather than an equal sign.


Table 5.5b: Additional Variables for Automated Installations [tables 5]
Variable Options Description
pc_config URL or /path/to/file location of customized pc-sysinstall.conf
confirm_install yes or no should be set to yes, otherwise booting the wrong disk will result in a system wipe
shutdown_cmd e.g. shutdown -p now good idea to run a shutdown, but can be any command/script you wish to execute post-install
nic_config dhcp-all or <interface name> <IP address> <subnet mask> will attempt dhcp on all found NICs until the installation file can be fetched or will setup specified interface
nic_dns IP address DNS server to use
nic_gateway IP address default gateway to use

Here is a sample pc-autoinstall.conf file:

# pc-autoinstall.conf example                                                   

# # Usage: Modify these variables, and copy the file to # /boot/pc-autoinstall.conf on your PC-BSD installation medium # # The conf will then be read at bootup, and your automated # install will take place ##################################################################

# Where the pc-sysinstall main config is located # Can be either a file on the booted CD / DVD / USB media, # or a remote file on http / ftp # # The value %%NIC_MAC%% is special, and will be substituted with # the macaddress of the enabled NIC from DHCP or manually set # with 'nic_config:' ##################################################################

# Examples: # pc_config: ftp://192.168.0.2/cust-install.cfg # pc_config: http://192.168.0.2/cust-install.cfg # pc_config: http://192.168.0.2/%%NIC_MAC%%.cfg # pc_config: /boot/cust-install.cfg pc_config: http://pkgbuilder.mydomain.com/images/freebsd/pc-sysinstall.cfg>

# Set this to yes if we should confirm before doing an install # This should normally be set to yes, otherwise booting the wrong # disk will result in a system wipe confirm_install: no

# Set the command to run post-install, usually best to run shutdown # but this can be replaced with any other command / script you wish # to execute post-install
shutdown_cmd: shutdown -r now

# Options for the network setup, should the cfg need to be fetched # from a remote location, only necessary when using ftp or http ##################################################################

# Special option, will attempt dhcp on all found NICs # until the file can be fetched, or we run out of interfaces # nic_config: dhcp-all

# Line to be passed to the "ifconfig" command to bring up an interface nic_config: em1 172.16.80.250 255.255.240.0

# DNS server to use nic_dns: 172.16.80.1

# Default router / gateway

nic_gateway: 172.16.80.1

Create a Custom Installation Media or Installation Server

pc-sysinstall supports the following installation methods:

  • from a CD, DVD, or USB media
  • from an installation directory on an HTTP, FTP, SSH+rsync, or a PXE Boot Install server

The easiest way to create a custom installation media is to modify an existing installation image. For example, if you have downloaded an ISO for the PC-BSD® version that you wish to customize, the superuser can access the contents of the ISO as follows:

mdconfig -a -t vnode -f PCBSD9.0-x86-DVD.iso -u 1                                mount -t cd9660 /dev/md1 /mnt

Make sure you have changed into a directory (use cd) where you would like to copy the contents of the ISO. In the following examples, /tmp/custominstall/ was created as the directory for this purpose:

cd /tmp/custominstall                                                           

tar -C /mnt -cf - . | tar -xvf -

umount /mnt

Alternately, if you have inserted an installation CD or DVD, you can mount the media and copy its contents to your desired directory:

mount -t cd9660 /dev/cd0 /mnt                                                   

cp -R /mnt/* /tmp/custominstall/

umount /mnt

If you are creating an automated installation, copy your customized pc-autoinstall.conf to /tmp/custominstall/boot/.

Copy your customized configuration file to /tmp/custominstall/. Double-check that the "installMedium=" variable in your customized configuration file is set to the type of media that you will be installing from.

You may also need to add some extra files if you set the following variables in your custom configuration file:

  • installComponents= make sure that any extra components you wish to install exist in extras/PBI/ (if they end in the .pbi extension) or extras/components/ (if they end in .tbz)
  • runCommand= make sure the command exists in the specified path
  • runScript= make sure the script exists in the specified path
  • runExtCommand= make sure the command exists in the specified path

If the installation media is a CD or DVD, you will need to create a bootable media that contains the files in your directory. To create a bootable ISO:

cd /tmp/custominstall                                                            mkisofs -V mycustominstall -J -R -b boot/cdboot -no-emul-boot -o myinstall.iso

You can then use your favorite burning utility to burn the ISO to the media.

To begin an installation that requires user interaction:

pc-sysinstall -c /path_to_your_config_file

To begin a fully automated installation, insert the installation media and reboot.

If you are using an HTTP, FTP, or SSH server as the installation media, untar or copy the required files to a directory on the server that is accessible to users. Be sure to configure the server so that the installation files are accessible to the systems that you wish to install. If you are using a PXE Boot Install server, follow the instructions at Connecting to and Customizing the PXE Boot Install Server.



Desktops

Once you have installed PC-BSD®, you will want to become familiar with your desktop environment. This section discusses the desktops which can be selected during the installation of PC-BSD® or installed afterwards using Package Manager.

These desktops are fully supported, meaning that all of the PC-BSD® utilities are integrated into the desktop environment:

NOTE: Fluxbox is always installed and available in the login menu of a PC-BSD® system.

By default, three PC-BSD® icons will appear on these desktops:

Appcafelogo1.png AppCafe®: graphical utility used to install, uninstall, and upgrade software. See the section on AppCafe® for more details.

Controlpanellogo.png PC-BSD® Control Panel: contains applications for administering the computer. See the section on Control Panel for more details.

Acrobat.png PC-BSD® Handbook: a PDF version of the PC-BSD® 9.2 Users Handbook (this document).

The following desktops are called "unsupported" in the PC-BSD® installer as they are meant for more advanced users who are comfortable working at the command line. The PC-BSD® utilities will work in these environments, but the user may need to start some utilities manually from the command line if they do not appear as an icon on the desktop or in the desktop's application menu:

Advanced users can also install other desktops using the FreeBSD ports and packages collection. You can browse the 160+ available desktops in the x11-wm[97] category at Freshports.org.

The rest of this section provides an overview of each of the desktops that can be installed with PC-BSD®.



GNOME2

GNOME2[98] is a popular desktop environment that provides many built-in utilities. Figure 6.1a shows a screenshot of GNOME2 on a PC-BSD® 9.2 system with the "Applications" menu open.

NOTE: GNOME3 has not yet been ported to FreeBSD. Until it is, pkgdemon has instructions[99] for installing GNOME3 with or without Cinnamon on PC-BSD® Isotope Infusion.
Figure 6.1a: GNOME2 Desktop on a PC-BSD® System

Each category in the "Applications" menu contains many applications and the "Settings" and "System" categories contain many utilities for configuring your system. If you are new to GNOME2, take some time to discover which applications best suit your needs. Some of the applications which are provided by GNOME include:

  • Epiphany[101]: web browser found in Internet → Epiphany Web Browser.
  • Brasero[62]: CD/DVD burning software found in Multimedia → Brasero Disk Burner.
  • Totem[102]: movie player found in Multimedia → Movie Player.
  • Evolution[103]: email client with address book and calendar. Found in Office → Evolution Mail and Calendar.
  • Nautilus[104]: file manager found in Utilities → File Browser.
NOTE: Some games, such as Lights Off, Quadrapassel, and Swell Foop, require 3D acceleration. If your video driver does not support this, you will not be able to launch those games.

You may or may not have installed all of GNOME's components during installation. You can view the installed components and check (to add) or uncheck (to delete) various components using Control Panel → Package Manager → Desktops → GNOME.

You can find additional themes and wallpapers at gnome-look.org[105].



KDE4

The KDE[106] desktop environment provides many features and applications. However, it is hardware intensive and may run slowly on a computer with an older processor or a small amount of RAM. Figure 6.2a shows a screenshot of KDE4 running on PC-BSD® 9.2 with the "Applications" menu open.

Figure 6.2a: KDE4 Desktop on a PC-BSD® System

Each category in the "Applications" menu contains many applications and the "Settings" and "System" categories contain many utilities for configuring your system. If you are new to KDE4, take some time to discover which applications best suit your needs. Some of the applications which are provided by KDE4 include:

  • Gwenview[107]: image viewer found in Graphics → Image Viewer.
  • Digikam[108]: photo-management program found in Graphics → Photo Management Program.
  • Konqueror[109]: file manager, web browser, and SSH client found in Internet → Web Browser.
  • Okular[110]: document viewer and annotator found in Office → Document Viewer. Supports PDF, OpenOffice, and Postscript files.
  • KOrganizer[111]: organizer utility and reminder daemon found in Office → Personal Organizer.
  • Dolphin[112]: file manager found in System → File Manager. Dolphin provides many features for manipulating files such as comments, tags, search, encryption, and archival (zip/unzip) functions.

By default, desktop effects are disabled, as not all video cards support them. If your video card supports 3D effects and you would like to enable them in KDE, go to System Settings → Desktop Effects → General and check the box "Enable desktop effects at startup".

Some of KDE's games require 3D support. If your video card does not support 3D, these games will fail to start.

You may or may not have installed all of KDE's components during installation. You can view the installed components and check (to add) or uncheck (to delete) various components using Control Panel → Package Manager → Desktops → KDE.

If you have KDE installed and are currently logged into a different window manager, you can still run any KDE application by specifying its name. For example, type konqueror to run the Konqueror web browser or dolphin to access the Dolphin File Manager.

KDE Applications[113] includes descriptions and screenshots of all of KDE's applications as well as links to their handbooks.

kde-look.org[114] contains additional themes and wallpapers.



LXDE

LXDE[115] is the Lightweight X11 Desktop Environment. It is an excellent choice for older hardware or for users who want a complete desktop environment without all of the overhead required by KDE or GNOME. Since it is XDG-compliant, the PC-BSD® Control Panel, AppCafe®, and Life Preserver are available on the desktop and integrated into LXDE's menus. Figure 6.3a shows a screenshot of the default LXDE installation with the LXPanel open.

Figure 6.3a: LXDE Desktop on a PC-BSD® System

In addition to the PC-BSD® utilities, LXDE provides the following utilities:

  • LXPanel[116]: desktop panel which is launched by clicking on the PC-BSD® icon in the lower right corner of the desktop. To configure the panel, right-click the PC-BSD® icon and select "Panel Settings" or "Add/Remove Panel Items" from the right-click menu.
  • PCManFM[117]: found in Accessories → File Manager PCManFM. A file manager with features like drag and drop, tabbed browsing, built-in file search, file association with default application, thumbnails for images, bookmarks, and support for non-UTF-8 encoded filenames.
  • GPicView[118]: fast image viewer found in Accessories → Image Viewer.
  • Leafpad[119]: a light-weight graphical text editor found in Accessories → Leafpad.
  • LXTerminal[120]: terminal emulator found in Accessories → LXTerminal.
  • Xarchiver[121]: archiver utility that supports the 7z, ARJ, bzip2, gzip, lzma, RAR, RPM, DEB, tar, and ZIP file formats. Found in Accessories → Xarchiver.
  • epdfview: a PDF viewer with printing support found in Office → ePDFViewer.
  • LXTask[122]: task manager and system monitor found in System Tools → Task Manager.
  • LXAppearance[123]: a theme switcher for customizing the widgets, colors, icons, mouse cursors, and sound effects used by applications, found in Preferences → Customize Look and Feel.
  • LXInput: a tool to configure your keyboard and mouse found in Preferences → Keyboard and Mouse.
  • Openbox[124]: the window manager used by LXDE. You can configure settings such as themes, appearance, mouse, and margins by going to Preferences → Openbox Configuration Manager.
  • obkey[125]: a key editor found in Preferences → Openbox Key bindings.

This PC-BSD® forum post[126] describes how to configure an application to autostart when you login to LXDE.



XFCE4

Xfce[127] is a lightweight desktop environment that aims to be low on system resources and fast, while still being visually appealing and user friendly. The first time you start XFCE4, you will see the Welcome Message shown in Figure 6.4a.

Figure 6.4a: Panel Welcome Message

In XFCE, a panel[128] is a bar which can hold many items such as application launchers, window lists, a clock, a notification area, and application menus. Your initial panel setup options are:

  • Migrate old config: select this option if you wish to have a single panel with an application launcher and other icons as shown in Figure 6.4b. The application launcher menu may be reached from the upper left, or by right-clicking on the desktop.
  • Use default config: this option will install a large panel across the top and a small, minimal panel centered on the bottom, as shown in Figure 6.4c. The application launcher menu may be accessed by the fireball icon in the lower left, or by a right-click on the desktop.
  • One empty panel: this option will install a panel with no icons. The application menu is available by right-clicking the desktop as shown in Figures 6.4b and 6.4c.
Figure 6.4b: XFCE Desktop on a PC-BSD® System with Complete Panel Migrated From Old Config
Figure 6.4c: XFCE Desktop on a PC-BSD® System with Minimal Panel Using Default Config

If you wish to change your configuration choice at a later time, reset the panel using Applications → Settings → Settings Editor, as shown in Figure 6.4d, then exit to the login prompt without saving session info. The next login to XFCE will present the panel configuration choice again.

Figure 6.4d: Using Settings Editor to Reset Panel
Figure 6.4e: Using alacarte to Customize Applications Menu

In addition to the PC-BSD® utilities, XFCE provides the following utilities:

  • Xdesktop[129]: desktop manager found in Settings → Desktop. Sets the background image, provides a right-click menu to launch applications, and can show files (including application launchers) or iconified windows.
  • Xfwm4[130]: window manager found in Settings → Window Manager. It provides window decorations, virtual desktops, multiscreen mode, transparency and a keyboard shortcuts editor.
  • Ristretto[131]: fast and light-weight picture viewer found in Graphics → Ristretto Image Viewer.
  • Midori[132]: light-weight graphical browser found in Internet → Midori.
  • Xfburn[63]: CD/DVD burning tool found in Multimedia → Xfburn.
  • Orage[133]: calendar and reminder daemon found in Office → Orage Calendar.
  • Thunar[134]: file manager found in System → Thunar File Manager.

A list of recommended applications for XFCE can be found on the XFCE Wiki[136].

Editing the Menu

XFCE no longer includes a graphical menu editor. The XFCE team recommends using alacarte which is included when you install XFCE4 on PC-BSD® and which can be started by typing alacarte within an xterm. Figure 6.4e shows a screenshot of alacarte running on PC-BSD®.

Any entry with a checkbox will appear in your menu. To remove an item from the menu, simply uncheck its box. To create a new menu category, either highlight a top-level menu (e.g. KDE Menu or System) or an existing category and click the "New Menu" button. To add a new entry, highlight the category where you wish the entry to appear and click the "New Item" button. Input a name for the entry, browse to the path of the application and press "OK".

XFCE Plugins

XFCE supports many plugins which provide additional applications that are separate from the official XFCE distribution. You can browse for plugins and read descriptions for each at the XFCE goodies website[137]. If you find a plugin that is not available within AppCafe®, this README[138]
Figure 6.4f: Adding a Plugin to the Panel
explains how to determine if a FreeBSD port is available, how to request a PBI if a port is available, and how to request a port if one does not already exist.

After installing a plugin, go to Settings®Panel → Items and click the + button to see the "Add New Items" window shown in Figure 6.4f.

Simply select your new plugin from the list, and click the "+Add" button. It will immediately be added as an icon in the panel.



Awesome

Awesome[139] is a highly configurable and fast window manager that is primarily targeted at power users who prefer to use the command line within their graphical environment. Figure 6.5a shows a screenshot of Awesome running on PC-BSD® 9.2. The user has right-clicked the desktop in order to launch the awesome application manager.
Figure 6.5a: Awesome Window Manager on PC-BSD®

If you click awesome → manual, the man page for awesome will open in a terminal. If you click awesome → edit config, the awesome configuration file will open in the ee text editor. The numbers in the upper left corner represent virtual desktops. For example, you can have different terminals open in each virtual desktop.

Bluetooth Manager (if the system has a Bluetooth interface), Update Manager, Wireless Configuration Manager (if your wireless card is detected), and Life Preserver are located in the system tray near the clock in the upper right corner. If you wish to access Control Panel type pc-controlpanel in a terminal. To launch AppCafe®, type appcafe in a terminal.



Fluxbox

Fluxbox[140] is a light-weight and fast window manager. Regardless of the window managers that you have selected to install, Fluxbox is always available as an option in the login menu.

Figure 6.6a shows a screenshot of Fluxbox running on PC-BSD®. In this example, the user has launched the Application menu by right-clicking on the desktop.

Figure 6.6a: Fluxbox on PC-BSD®

Fluxbox provides many configuration files which can be edited in order to customize the desktop. The Features[141] page of the Fluxbox website lists the available configuration files and links to instructions for getting the most out of Fluxbox.

To ease some aspects of configuration, the Fluxconf PBI, available in AppCafe®, adds the following graphical tools:

  • fluxbare: seen in Figure 6.6b, provides a tiny toolbar allowing you to launch the next three utilities. Type fluxbare within an xterm to open the toolbar.
  • fluxconf: seen in Figure 6.6c, is used for managing window placement.
  • fluxkeys: seen in Figure 6.6d, is used to define and manage keyboard shortcuts.
  • fluxmenu: seen in Figure 6.6e, is used to add or remove entries from the Fluxbox menu.
Figure 6.6b: Fluxbare Toolbar
Figure 6.6e: Editing the Menu Using fluxmenu
Figure 6.6c: Configuring Window Placement with fluxconf
Figure 6.6d: Managing Keyboard Shortcuts with fluxkeys

The following resources are useful when customizing Fluxbox:



FVWM

FVWM[147] is a powerful and highly configurable desktop window manager for the X Window system. It supports any number of virtual desktops, each divided into multiple pages. It also supports side title bars, including vertical text.

Figure 6.7a: FVWM Running on PC-BSD®
Figure 6.7b: FVWM-Crystal Running on PC-BSD®

When you install FVWM on PC-BSD®, it also installs FVWM-Crystal[148]. Both window managers will be added to the login menu. Figure 6.7a shows the default PC-BSD® desktop if you select FVWM from the login menu. The application menu was opened by clicking the mouse anywhere on the desktop. Figure 6.7b shows the default PC-BSD® desktop if you select FVWM-Crystal from the login menu. To open an xterm in FVWM-Crystal, right-click any area of the desktop.

This article[149] provides a good overview of the features and configurable options for FVWM-Crystal.

The FVWM Documentation[150] provides further information about configuring FVWM.



i3

i3[151] is a lightweight, tiling window manager. Keyboard shortcuts are provided to open xterms in order to start applications from the command line. Figure 6.8a shows a screenshot of i3 running on PC-BSD® 9.2.
Figure 6.8a: i3 Window Manager on PC-BSD®

i3 provides a panel that on PC-BSD® will contain icons for Bluetooth Manager (if the system has a Bluetooth interface), Update Manager, Network Configuration (if your wireless card is detected), and Life Preserver.

To open an xterm, use Alt+Enter. Windows do not provide minimize/mazimize or close buttons, so type exit when you are finished using an xterm. To leave the window manager and return to the login screen, type killall i3 from within an xterm.

The i3 Users Guide[152] contains the default key bindings and instructions for customizing i3.



IceWM

Figure 6.9a: IceWM on PC-BSD®

IceWM[153] is a light-weight window manager.

Figure 6.9a shows a screenshot of IceWM running on PC-BSD®. In this example, the user has launched the Application menu by clicking on the IceWM button in the lower left corner. This menu can also be launched by right-clicking anywhere on the desktop.

If you are new to IceWM, see the IceWM FAQ and Howto[154] for more information about configuration, customization, and keyboard shortcuts.



Openbox

Openbox[155] is a highly configurable, minimalist window manager. It is the window manager used by LXDE but can also be run separately from LXDE.

Figure 6.10a: Openbox on a PC-BSD® System
Figure 6.10b: Openbox Configuration Manager

Figure 6.10a provides a screenshot of Openbox running on a PC-BSD® system. The application menu was launched by right-clicking on an area of the desktop.

The application menu contains an entry for the Openbox Configuration Manager which can be used to customize settings such as themes, appearance, mouse, and margins. A screenshot of this configuration utility is shown in Figure 6.10b.

A list of websites containing additional themes is available from the Openbox wiki[156].



Ratpoison

Ratpoison[157] is a simple window manager with no fat library dependencies, fancy graphics, or window decorations. Figure 6.11a provides a screenshot of Ratpoison running on a PC-BSD® system:
Figure 6.11a: Ratpoison on a PC-BSD® System

Ratpoision uses keyboard shortcuts. To view the shortcuts, press Ctrl-t then ?. To leave this help screen, press enter.

To open an xterm, press Ctrl-t then c. Type exit to close the xterm. Type killall ratpoison with an xterm to leave Ratpoison and return to the login screen.

The Ratpoison wiki[158] contains an FAQ and tips for setting keyboard shortcuts.



spectrwm

spectrwm[159], formerly known as Scrotwm, is a minimalist window manager written by OpenBSD hackers. It provides keyboard shortcuts, a configuration file, and assumes that the user prefers to use the command line. Figure 6.12a provides a screenshot of spectrwm running on a PC-BSD® system.
Figure 6.12a: spectrwm on a PC-BSD® System

If you have not used spectrwm before, spend some time reading through its man page[160] first.

To launch applications within spectrwm, start an xterm by pressing Alt+Shift+Return. Once you have an xterm, you can start any program you wish. For example, to start Control Panel type pc-controlpanel.

spectrwm does not provide minimize, maximize, or close buttons within its windows. To close a GUI application, use Ctrl-c within the xterm you used to launch the application. To leave this desktop, type killall spectrwm from an xterm.



WindowLab

WindowLab[161] is a small and simple window manager. It uses a window resizing mechanism that allows one or many edges of a window to be changed in one action, and an innovative menubar that shares the same part of the screen as the taskbar. It follows a click-to-focus but not raise-on-focus policy. This means that when a window is clicked it gets focus, but it is not redrawn to obscure other windows. This allows one, for example, to switch to a terminal to enter commands while keeping documentation visible in a web browser.

File:Windowlab1a.png
Figure 6.13a: WindowLab Running on PC-BSD®

Figure 6.13a shows a screenshot of WindowLab running on PC-BSD® 9.1. The right mouse button is pressed in order to display the top menu panel. Use the left mouse button or hover over a taskbar entry to open that application.

To add the applications you use most often to the menubar, select "Edit menu" while holding the right mouse button.

To leave the WindowLab session, select "Quit" from the menubar.



Window Maker

Window Maker[162] is a light-weight window manager that was designed to reproduce the elegant look and feel of the NEXTSTEP[163] user interface. Figure 6.14a shows a screenshot of Window Maker running on PC-BSD®. In this example, the user launched the Application menu by right-clicking an area of the desktop.

Figure 6.14a: Window Maker on PC-BSD®
Figure 6.14b: Editing the Application Menu Using wmakerconf

In addition to the PC-BSD® utilities, Window Maker provides the following applications:

  • WPrefs: located in Appearance → Preferences Utility. Allows you to configure window focus, window placement, menu alignment, icons, keyboard actions, mouse, fonts, and various other window manager settings.
  • wmakerconf[164]: found in Utils → wmakerconf. Allows you to fine-tune your menu entries as well as your desktop's appearance, themes, background, mouse, and special effects. Figure 6.14b shows wmakerconf with the "Menu" button selected.

Working with the Dock

Window Maker uses a dock to store application shortcuts. The dock appears as a series of icons in the upper right corner of the desktop. Docked applications always show on the desktop, even after you close an application or close and restart your Window Maker session.

Whenever you start an application, an icon will appear in the lower left corner of the screen. You can move that icon elsewhere on the desktop with your mouse. If you right-click the icon, you have the option to hide/unhide the icon, set icon (change its picture), or kill the application. If you drag the icon onto the dock, it will remain on the desktop.

Once an icon is docked, a settings menu is added to the icon's right-click menu. Figure 6.14c demonstrates how to configure an icon for AppCafe®.

Figure 6.14c: Configuring an Icon

You will find the icons for AppCafe® and Control Panel in /usr/local/share/pcbsd/pc-controlpanel/icons. Choose the 64x64 versions as this is the size that Window Maker uses. The application name for AppCafe® is appcafe and for Control Panel it is pc-controlpanel.

DockApps

Window Maker supports dockapps[165] which are applications that were designed to work with Window Maker but which are separate from the Window Maker project. Dockapps tend to be small and designed to perform a particular function. For example, there are clocks, weather applications, and CPU monitors. Most dockapps have been ported to FreeBSD and the port always begins with "wm". You can search for these at FreshPorts[166] by entering a "Short Description" containing "dockapp".

If your favourite dockapp has not been ported to FreeBSD, you can request that a port be created on the Ports Requests forum using these instructions[167]. If a port already exists and you would like to see it made into a PBI, you can request that a PBI be created on the PBI Requests forum using these instructions[138].



Installing Applications and Keeping Up-to-Date

Installing Applications and Keeping Up-to-Date/9.2


AppCafe®

PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the .pbi extension and are self-contained installation programs. When a PBI is installed using AppCafe®, even novice users are protected from the risk of inadvertently overwriting or deleting files needed by the operating system or other applications.
Figure 7.1a: Browsing for Software Using AppCafe®

A PBI file includes all the runtime and library dependencies required by the application. This means that the initial download of a PBI is a large file; but this does not necessarily mean that same amount of space will be used. During installation, the PBI system compares the currently installed libraries and files with the ones contained within the PBI file and only installs the ones that are not already installed on the system. A hash database is used to eliminate dependency problems while allowing the computer to share libraries between different programs. Subsequent downloads to upgrade a PBI are significantly smaller as only what has changed in the new version will be downloaded.

AppCafe® provides an intuitive, graphical method for installing and managing PBI software. AppCafe® does not require the root password to install software. This means that you do not have to give out the root password on multi-user systems. However, server applications, such as web servers or databases, will prompt for the user's password and will fail if that user is not a member of the wheel group. This allows you to control which users are able to install server software.

After a regular user installs an application, they have the option to install menu icons for all users, meaning that an application only needs to be installed once on a multi-user system.

If you prefer to install PBIs from the command line, see the section on using pbi_add.

Installing and Managing Software

To install a PBI, start AppCafe® by double-clicking its icon on the Desktop, going to Control Panel → AppCafe®, or by typing appcafe from a command prompt. The "Browse for Apps" tab in AppCafe® can be used to browse for available software, as seen in Figure 7.1a. In the example shown in Figure 7.1a, 1153 PBIs are currently available. The names and versions of the PBIs which were added or updated in the last 10 days are listed in the “View Recent Additions” pane.

If you know the name of the application you would like to install, type its name into the "Search Here" bar. Alternately, you can click on a software category (for example, "Archivers") to browse for available software. Use the home icon to return to the main screen. In the example shown in Figure 7.1b, the user searched for the "gimp" application. The search has found that PBI as well as two others that may match the search term.

Figure 7.1b: Browsing the Information Available for a PBI

In Figure 7.1c, the user has clicked on the "gimp" PBI and can now view the following information:

  • Name and icon of the application.
  • A hyperlink to the application's website. In this example, clicking "The GIMP Team" will open gimp.org in the user's default web browser.
  • An "Install Now!" icon. If the application is already installed, this will either be an "Upgrade" icon (if a newer version is available) or a "Downgrade" button (if the latest version is already installed).
  • The version of the application.
  • The size of the initial download of the PBI.
  • The platform (i386 for 32-bit applications and amd64 for 64-bit applications). If the application only provides a 32-bit version, AppCafe® will install the 32-bit application and PC-BSD® will still be able to run the program.
  • The license used by the software.
  • The type will indicate whether the application is graphical or text (command line).
  • A description of the application.

AppCafe® will also suggest similar applications which may meet the user's needs.

Figure 7.1c: Details for a Selected PBI

Once you find a PBI that you would like to install, click on its “Install Now!” icon. AppCafe® will switch focus to the "Installed" tab so that you can watch the status of the download and installation. Figure 7.1d shows a screenshot of this tab after “gimp” is successfully installed.

Figure 7.1d: Viewing an Installed PBI in AppCafe®
Figure 7.1e: Using the Installed Tab to Upgrade Installed PBIs

If you highlight an installed PBI and click the “Actions”button, the following actions become available:

  • Update: if the “Status” column indicates that a newer version is available, click this action to upgrade to the newer version. Once clicked, it will change to a cancel button should you decide to cancel the operation while the new version is still being downloaded.
  • Desktop Icons: used to add or remove a shortcut to the application on any installed and supported desktop (GNOME4, KDE, LXDE, and XFCE4).
  • Menu Icons: used to add or remove an entry for the application to the menu of any installed and supported desktop (GNOME4, KDE, LXDE, and XFCE4). Menu icons can be for that user only or for all users. Adding for all users requires you to be in the wheel group and to input your password.
  • Path Links: used to add or remove the command's location to your $PATH or to the $PATH of all users. Adding for all users requires you to be in the wheel group and to input your password. This option is useful if users will be starting the application from the command line.
  • File Associations: installs any xdg-mime type file associations from the PBI. For example,*.odt files are associated with OpenOffice and LibreOffice.
  • Uninstall: will uninstall the PBI. Once the PBI removal is complete, it will be removed from the Installed list.
  • Cancel Actions: cancels any currently pending or running PBI operations such as uninstallation, updating, or installation.

The buttons in the “Application Details” can be used to:

  • start the application; if the application has multiple start modes, such as graphical or command-line, a drop-down menu will provide the available ways to start the application
  • uninstall the application
  • open the application's website in the default web browser
  • have the application automatically update itself when a newer version is available. By default, this option is unchecked, meaning that AppCafe® will indicate when a new version is available in the "Status" column, but will wait for you to start the update.

Updating Installed PBIs

The "Status" column of the "Installed" tab will indicate if there are any newer versions available for the PBIs that you have installed. PBIs are created from the original FreeBSD package and automatically become available as an upgrade whenever the underlying package version changes. Figure 7.1e provides an example of a system that has newer PBI versions available.

In this example, newer versions are available for firefox-esr and Thunderbird. Check the box for each PBI that you wish to update then click Actions ➜ Update. If any of the selected PBIs require root, AppCafe® will prompt for your password before starting the upgrade.

A status bar will indicate the progress of the download and upgrade process. When the upgrade is complete, the entry will be updated to show the new version. The upgrade process will save all of the current version's settings. For example, when you upgrade Firefox, it will keep all of your bookmarks, history, and cache.

Importing and Exporting PBI Lists

PC-BSD® has the ability to import and export PBI lists. A PBI list is an ASCII text file that contains the names of PBIs (without a version number), one per line. An example is as follows:

apacheopenoffice                                                                

thunderbird firefox qtcreator scite gimp pithos quassel ksnapshot

openjdk7

If you import a PBI list into AppCafe®, it will add those applications to the installation queue so that they can be installed. To do so, create the list and save it with a .pbilist extension. Then, go to File → Import PBI List and browse to the location of the list. A pop-up menu will ask if you would like to install the applications in the list. AppCafe® will ignore any invalid lines and PBIs which are already installed.

Alternately, if you export a PBI list on a system that already has PBIs installed, you can then import that list into another PC-BSD® system. To do so, click File → Export PBI List and save the file to the desired location. By default, it will be saved as exportfile.pbilist.

Configuring AppCafe®

Figure 7.1f shows the screen that opens when you click Configure → AppCafe Settings.

Figure 7.1f: AppCafe® Settings Menu

Appcafe7a.png

The settings in the "Configuration" tab apply to all PBIs, whereas the settings in a highlighted application's "Actions" button only apply to that PBI. This tab adds an extra option to store a copy of the downloaded PBI. If you check this box, it will expand to let you select the directory to store the downloaded .pbi files. If you change a setting in the "Configuration" tab, it will not affect PBIs which are already installed.

Figure 7.1g shows the "Repositories" tab.

Figure 7.1g: Repositories Tab

Appcafe8a.png

By default, AppCafe® is configured to connect to the official PC-BSD® PBI repository which uses a CDN (Content Delivery Network) to provide the fastest possible download, regardless of geographic location.

If you have access to a custom PBI repository, click the “+” button next to "001 - Official PC-BSD Repository" to add the URL of the repository.

If you have created your own PBI repository, click the “+” button next to "PCBSDCDN" to browse to the location of your .rpo file.



Package Manager

PC-BSD® provides a graphical Package Manager utility to Control Panel which can be used to manage installed desktops and system components. It can also be used as a front-end to the FreeBSD packages collection. If you prefer to start this utility from the command line, type pc-su pc-pkgmanager.

Figure 7.2a shows Package Manager with its categories expanded. This sample system uses NVIDIA for graphics and the default desktop manager of KDE was kept during the installation. This default view is known as Basic View.

Figure 7.2a: Viewing Installed Components

Install System Components

To install or uninstall components, check the boxes for the components that you wish to install, uncheck the boxes for the components that you wish to remove, then click the "Apply" button to perform the requested operations.

Install FreeBSD Packages

To instead manage FreeBSD packages, click View → Advanced to change to Advanced View. This view is shown in Figure 7.2b with the editors category expanded.

Figure 7.2b: Managing FreeBSD Packages

The search utility can be used to find packages to install. Alternately, if you know the software category, expand it and check the software you would like to install. As you browse, you can select multiple packages. If you click an application name, its Package Information screen will display, as seen in the example in Figure 7.2c.

Figure 7.2c: Viewing a Package's Information

The Package Information is divided into three tabs:

  • Description: displays the name and version of the package, its download size, the URL to its homepage, and a brief description.
  • Options: shows the options compiled into the package. Options will be listed as either on or off.
  • Dependencies: lists any additional packages that will be installed as dependencies of the selected package.

Once you have made your selections, click the "Apply" button to install the selected software.

Update Installed Packages

As newer versions of installed packages become available, they are listed in the "Package Updates" tab of Package Manager. In the example shown in Figure 7.2d, three updates are available, representing package updates to the PC-BSD® utilities, the GUI versions of those utilities, and to the base packages installed with the operating system.

Figure 7.2d: Package Updates Available

Updates are added using the following target schedule:

  • if you are running RELEASE, any changes to the packages that come with the operating system as well as any packages installed in Basic View show up around the 1st and 15th of each month
  • if you are running STABLE, any changes to the packages that come with the operating system as well as any packages installed in Basic View show up around the 5th and 20th of each month
  • if you installed any FreeBSD packages from Advanced View, these show up whenever a new version becomes available

Note that these are target dates which may slip by a few days if the build server experiences problems building packages from ports.

To update to the newest versions of packages, click the "Update packages" button.



Update Manager

Update Manager provides a graphical interface for updating the version of PC-BSD® and for applying security updates. This utility can be started from Control Panel or by typing pc-updategui. It can also be accessed from its icon in the system tray, if you are logged into a desktop that provides a system tray.

The status of the icon lets you determine at a glance if any of your installed applications are out-of-date, if a system update is available, or if a new version of the operating system is available. Table 7.3a summarizes the possible statuses of this icon.

Table 7.3a: Update Manager Status

Updated1.png your system is up-to-date
Working1.png the system is currently checking for updates and patches
Sysupdates1.png your operating system is out-of-date and system update(s) or patch(es) are available
Pbiupdates1.png newer versions of installed PBI(s) are available
Pkgupdates.png newer versions of installed packages are available
Connecterror1.png the system was unable to check for updates, meaning you should check your Internet connection
Updating.png the system is currently updating
Restart.png the system needs to restart in order for the newly installed update to take effect

If you right-click the icon, you will see the menu shown in Figure 7.3a. As seen in the menu, Update Manager will automatically track updates to software installed using either the graphical or command line equivalents of Package Manager, AppCafe®, and Warden®.

Figure 7.3a: Right-click Menu for Update Manager
Figure 7.3b: Applying a System Update

By default, updates are checked every 24 hours or whenever you boot the system. You can check for updates at any time by selecting "Check for updates". To disable the update check when the system boots, uncheck the "Run at startup" box. To disable the pop-up message over the icon when an update becomes available, uncheck the "Display notifications" box. To remove Update Manager from the system tray, click "Quit". You can put the icon back into the tray by typing pc-systemupdatertray.

Applying a System Update

Occasionally, the PC-BSD® project releases a system update which addresses a fixed security vulnerability or a bug which impacts the use of the operating system. If the update is based on a FreeBSD security advisory, the update is usually available within 24 hours of the FreeBSD security announcement. To install a system update, open Update Manager. Figure 7.3b shows an example of an available system update within Update Manager.

If your system is fully up-to-date, there will not be any entries in Update Manager. If you click the entry for a listed update, the “Update Details” box will provide some details about the update.

To install an update, highlight its entry and click the "Install selected updates" button. A progress bar will indicate the progress of the update.

If the update requires a reboot, you will be notified to do so after the update has been installed. If a reboot is needed, clicking the "OK" button at the informational message will not automatically reboot the system, meaning you can continue to use your computer for other tasks while the system is being updated. Finish whatever you are doing and reboot the computer at a time that is convenient for you.

Upgrading the Operating System

If you are running a rolling release, Update Manager can be used to upgrade to the latest version of the operating system.

DANGER!  IMPORTANT--README BEFORE ATTEMPTING AN UPGRADE! 
  • PC-BSD® has switched to ZFS-only. This means that you can not upgrade a system that is either 32-bit or formatted with UFS. If the hardware supports 64-bit, you will need to backup your important data to another system or external drive and then perform a new installation. The new installation will perform a format of the selected disk(s) with ZFS.
  • The boot loader and default ZFS layout changed with the July 23, 2013 rolling release. This change was needed to support boot environments and ZFS snapshot management with Life Preserver. This means that you can not upgrade from a release prior to that date. If you are running PC-BSD® 9.1-RELEASE or a rolling release prior to July 23, you will need to backup your important data to another system or external drive and then perform a new installation. The new installation will create the required ZFS layout.
  • The ZFS version changed between 9.2 and 9.1 and ZFS does not support downgrading to an earlier version of ZFS. This means that you cannot downgrade a 9.2 installation to a 9.1 installation.

Before performing an operating system upgrade, always back up the data that is important to you. Life Preserver can be used to backup your home directory to a remote system. It is also recommended to use Boot Manager to backup your current boot environment before performing the upgrade.

Figure 7.3c: Upgrading the Operating System

Before attempting an upgrade, you should also be aware of the following caveats:

  • the temporary files used by the upgrade process require 2GB of free space in /usr/. If you receive an error message indicating that you do not have enough free space to perform the upgrade, you will need to delete some files or move them elsewhere in order to create enough free space.
  • an upgrade will preserve the data in the home directories, any installed PBIs, and user accounts. It also preserves common configuration files and will merge any customizations you have made into the new versions of the following files: boot/loader.conf, /etc/rc.conf, and /etc/sysctl.conf.

Once you have backed up your data and confirmed that your version of PC-BSD® is older than July 23, you can use Update Manager to upgrade the operating system. In the example shown in Figure 7.3c, the "Base System Updates" indicates that a system advisory is available, as well as an update to 9.2-RC3 and then 9.2-RC4. The "Update Details" section lists the files that will be changed if the system is upgraded.

NOTE: If you know that a new release is available and it is not showing in Update Manager, make sure that any updates that do show are applied first. That way, the system will be fully patched and ready for the system upgrade.

To perform the upgrade, check the box for the "Base System Updates" entry and click the "Install selected updates" button. A progress bar will indicate the download status of the files that changed with the upgrade.

Once the downloads are finished and applied, Update Manager will indicate that the system is fully updated. Close any applications that you have open, then reboot in order to load the latest version of the operating system.



PBI Manager

PBI Manager is a suite of command line utilities which can be used to install, remove, create and manage PBIs.

The PBI format provides the following features:

  • Self-Contained: rather than making every application a part of the base system, PBIs are self-contained, including their own dependent library tree and related data. As a result, when you install a PBI there are no dependency issues to resolve, and applications can be added or removed freely, without fear of causing breakage to the desktop or any other installed software.
  • Upgrade deltas: since PBIs are self-contained, installation files tend to be large. The PBI specification performs updates using binary diff patches known as PBP (Push Button Patch) files. PBPs are a fraction of the PBI`s size; in some cases less than 5% of the original PBI archive. An upgrade automatically checks for for the presence of a PBP file and attempts to use it, only falling back to the original archive should the process fail.
  • Library and file sharing: a hash-dir directory shares libraries and common files through a system of hard links. When an identical file is found in a PBI, the original will be removed and a hard-link stored in the hash-dir. After a PBI has been removed, any unneeded files left in the hash-dir are cleaned up by the pbid(8) daemon which monitors and maintains the integrity of the shared files.
  • Repository management: allows administrators and PBI builders to create and manage their own repositories of PBIs. This repository system provides a number of tools for PBI distribution, release management, and repository browsing.
  • Digitally signed PBIs: each repository includes an OpenSSL public key file which is installed on the end user's system. Each PBI includes several signatures for the content archive and installation and removal scripts. During the PBI installation process, these signatures are checked to confirm that the archive has not been tampered with during transit. This key file is also used to associate a particular PBI with a parent repository for upgrade purposes, since it is possible that multiple repositories will have the same applications.
  • Root password not required: most applications can be installed and upgraded by regular user accounts. This allows enhanced security in office or home situations, where users can now add/remove desktop applications without needing access to the root password. PBIs that impact on the security of the system (e.g. installing a web server) will require the user to be a member of the wheel group.
  • Implementation: the PBI format is implemented 100% in shell and is comprised of command line utilities, each with an associated man page. These utilities are discussed in more detail in the rest of this section.

The underlying files and directories used by PBI Manager are as follows:

  • /usr/local/etc/pbi.conf: location of the PBI Manager configuration file
  • /usr/pbi/: where PBIs are installed on the system
  • /var/db/pbi/: contains data files related to installed PBIs and repositories
  • /usr/local/sbin/pbi_*: location of the PBI Manager commands

Command Reference

The following commands are installed by PBI Manager. For more details, refer to that command's man page. Note that single character options can not be stacked. As an example, you must type pbi_add -i -v as pbi_add -iv will fail.

pbi_add(1)

Similar to FreeBSD's pkg_add, the pbi_add command is used for adding/installing PBIs on a system, either from a local file or remotely from a repository. This utility supports the options listed in Table 7.4a. All of the options, except for -r, assume that the .pbi file has already been downloaded and is in the current or specified directory.

Table 7.4a: pbi_add Options [tables 6]
Switch Description
-e extract only, do not install; will extract the archive to ~/<pbidirname> unless the -o option is used
-f force installation, overwriting an already installed copy of the application
-g show path to icons and images for GUI installations
-i display information about specified PBI; if combined with -v, will display all of the files that will be installed with the PBI
-l display license for specified PBI
-o outdir specify the directory to use when extracting the PBI with -e
-r remote fetch installation file from update server; the system version will be automatically determined in order to fetch the correct file and resume support is built-in
-R remote fetch the install file from the update server but do not install
-v enable verbose output
--checkscript display any custom scripts used in the installation/removal of the PBI
--licagree agree to license terms and conditions; to view the license, use -l
--no-checksig skip the openssl signature verification of the PBI data
--no-checksum skip the checksum verification of the archive data
--no-hash disable using the shared hash dir
--repo repoid specify which repository to use
--rArch arch manually specify the PBI architecture type of i386 or amd64
--rVer version specify which version of the PBI to install

For security reasons, it is recommend that users first use the -i -v and --checkscript options to view archive contents and installation scripts prior to installing a PBI file.

To install a PBI from a remote repository, use: pbi_add -r name_of.pbi. The following example will install the alpine PBI:

pbi_add -r alpine

[#81c1ca 10MiB/11MiB(93%) CN:1 DL:589KiB ETA:1s] 08/07 11:16:14 [NOTICE] Download complete: /usr/pbi/.alpine-2.00_3-amd64.pbi 08/07 11:16:14 [NOTICE] ServerStat file /root/.pcbsd-aria-stat saved successfully. Download Results: gid |stat|avg speed |path/URI ======+====+===========+======================================================= <!--T:110--> 81c1ca|OK | 356KiB/s|/usr/pbi/.alpine-2.00_3-amd64.pbi Status Legend: (OK):download completed. Verifying Checksum...OK Extracting to: /usr/pbi/alpine-amd64

Installed: Alpine-2.00_3

PBI Manager will automatically install the appropriate PBI. If only a 32-bit version is available, the 32-bit PBI will be installed and will work correctly on the PC-BSD® system.

If you previously downloaded the PBI, do not include the -r switch and give the fullname of the PBI:

pbi_add alpine-2.00_3-amd64.pbi

pbi_addrepo(8)

The pbi_addrepo command is used to register a new PBI repository on a system. If the pbid daemon is running, the repository's index and meta files will be automatically fetched and made ready for browsing. The command has one argument: the name of the repository file. Repository files have a .rpo extension and are created with the pbi_makerepo command.

pbi_autobuild(8)

The pbi_autobuild command is used on the PBI build system to build any out-of-date or new packages. It can traverse the FreeBSD ports and metadata trees, building missing PBI files or PBIs in which the target port version has been updated. Instructions for using this command to keep a custom repository up-to-date can be found in the section Configure the Automatic Build of Updated Ports.

Table 7.4b summarizes this command's options:

Table 7.4b: pbi_autobuild Options [tables 7]
Switch Description
-c confdir mandatory; specify the directory containing the PBI configuration modules; any found pbi.conf files will be parsed, and if PBI_MAKEPORT is set, the target port will be used for the build; if PBI_MAKEPORT is unset, the auto-build will attempt to match the module to a FreeBSD port based upon the dirname of pbi.conf
-d portsdir specify an alternative ports directory; defaults to /usr/ports/
-h script specify a helper script to call after building a PBI
-o outdir mandatory; the directory to place the finished PBI files
-p num if your build hardware has the CPU and disk I/O to support concurrent build processes, specify the number of concurrent builds
-32 include when building a 32-bit PBI on a 64-bit system
-32fallback only build the 32bit PBI if a 64-bit version does build
--genpatch when building a new PBI, check for archived copies and generate smaller patch updates to the new version (*.pbp files)
--keep num when building new PBIs, keep <num> copies of past versions of working PBI in <outdir>/archived/ folder; these archived copies can be used with the --genpatch command to generate update patch files
--pkgcache enable caching of .txz pkg files which greatly speeds up subsequent builds of a PBI
--prune remove any PBIs which no longer have an associated module
--tmpfs automatically create and mount a tmp filesystem which can speed up port compiles on systems with available RAM
--sign keyfile digitally sign the PBI file with the specified openssl private key file

pbi_browser(1)

The pbi_browser command provides a CLI front-end to browsing a repository's available PBIs. Options for viewing categories and searching by keyword are available, and once the desired PBI is located, it will show the pbi_add command which can be used to install the application. Table 7.4c summarizes the available options.

Table 7.4c: pbi_browser Options [tables 8]
Switch Description
-c category displays a list of PBIs in the specified category
-s search search for PBIs containing the specified string in the name, description, or keywords
--listcats list the available categories
--viewall list all available PBIs

pbi.conf(5)

pbi.conf is an ASCII text configuration file containing values that are used by the various pbi_* commands. The proxy variables are only needed if the system uses a proxy server to access the Internet. Table 7.4d lists the supported variables.

Table 7.4d: pbi_conf Variables [tables 9]
Variable Description
PBID_REFRESH wakeup time in seconds for pbid to run its checks
PBI_INDEXREFRESH number of hours representing how often pbid refreshes the index and meta files from repos; default is every 24 hours
PBI_PROXYURL proxy server IP address
PBI_PROXYPORT proxy server port number
PBI_PROXYTYPE can be HTTP or SOCKS5
PBI_PROXYUSER username used to authenticate with proxy server
PBI_PROXYPASS password used to authenticate with proxy server

pbi_create(1)

The pbi_create command provides a way for packagers to manually specify a target directory to be compressed into a PBI file. The option -b can also be used to re-package an already installed PBI back to an archive. PBI creators are encouraged to send a tarball of the resulting PBI module to the PBI-dev mailing list[168] so they can be added to the PC-BSD® PBI repository and made available to other PC-BSD® users.

Table 7.4e summarizes the available options:

Table 7.4e: pbi_create Options [tables 10]
Switch Description
-a author specify the author for this PBI
-b make a backup of an installed PBI; specify the target PBI name instead of the PBI directory
-c confdir specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
-d portsdir specify an alternative ports directory; defaults to /usr/ports/
-i icon specify a default icon, relative to pbidir/
-n name specify a name for this PBI
-o outdir place the finished .pbi file into the specified directory; defaults to $HOME
-p port use the given port to get PBI name and version
-r version specify a version for this PBI
-u weburl specify a website URL for the PBI
--no-hash disable using the shared hash directory which uses hard links to share files between applications
--sign keyfile digitally sign the PBI file with the specified openssl private key file

As the superuser, you can create a PBI with the pbi_create command using the following syntax:

pbi_create -a <author> -n <name> -r <version> -w <weburl> <target directory>    

Inside the target directory place the application's binaries or scripts along with any required dependencies. To indicate which file(s) represent the runtime command(s), include a file named external-links in the target directory. That file contains an entry for each command, as seen in the following example:

# Files to be symlinked into the default LOCALBASE                              

# One per-line, relative to %%PBI_APPDIR%% and LOCALBASE # Defaults to keeping any existing files in LOCALBASE # Use bin-files/ for binaries that need wrapper functionality

# TARGET LINK IN LOCALBASE ACTION

bin/myapp bin/myapp binary,nocrash

This entry instructs pbi_create to make the wrapper scripts for the myapp binary, along with placing it in the user's PATH at install time.

It is also possible to include desktop icons and mime entries using the xdg-mime/, xdg-desktop/ and xdg-menu/ directories. The section on how to Create PBIs contains more details about creating these files. These directories should be created as subdirectories of the target directory of your application.

pbi_delete(1)

Similar to FreeBSD's pkg_delete, the pbi_delete command removes an installed PBI from the system. It also schedules cleaning for the shared library directory, which is performed by pbid. Table 7.4f summarizes its options:

Table 7.4f: pbi_delete Options [tables 11]
Switch Description
-v enable verbose output
--clean-hdir perform a full cleaning of the shared hash directory, removing any unused files; should only be required after a system crash or failure in removing a PBI

When removing a PBI, you must give its full name. The full name can be found in the output of pbi_info. The following example searches for the ntop PBI and removes it:

pbi_info | grep ntop

ntop-4.0.1_1-i386 pbi_delete -v ntop-4.0.1_1-i386 Running pre-removal script: /var/db/pbi/installed/ntop-4.0.1_1-i386/pre-remove.sh Removing: /usr/pbi/ntop-i386

Removing: /var/db/pbi/installed/ntop-4.0.1_1-i386

pbi_deleterepo(8)

The pbi_deleterepo command can be used to remove a registered repository from the system. It takes the repository's ID as the only command argument.

pbi_icon(1)

The pbi_icon command provides a number of options for adding desktop icons, menu entries, and mime data for an installed PBI. Not all PBIs will contain desktop/menu/mime data. Additionally, the window manager must be XDG[169]-compliant to understand a PBI's icon and mime settings. Table 7.4g summarizes this command's options:

Table 7.4g: pbi_icon Options [tables 12]
Switch Description
add-desktop installs desktop icon; should be run as regular user
add-mime installs mime information; should be run as root
add-menu installs menu icons; should be run as root
add-pathlnk installs any $PATH links to ~/bin when run as user or to $LOCALBASE when run as root
del-desktop removes desktop icon; should be run as regular user
del-menu removes menu icons; should be run as root
del-mime removes mime information; should be run as root
del-pathlnk removes any $PATH links to ~/bin when run as user or to $LOCALBASE when run as root

pbi_indextool(1)

The pbi_indextool command is useful for repository maintainers. It allows PBI files to be added and removed from the repository's INDEX file. An example of using this command can be found in Create Your Own PBI Repository. Table 7.4h summarizes the available options:

Table 7.4h: pbi_indextool Options [tables 13]
Command Switch Description
add -b vers mark previous versions as having a binary diff patch (.pbp file used for upgrading) available
-f pbifile mandatory, name of PBI being added to the target INDEX file
-k num number of previous versions of this PBI to keep in the INDEX file
-u fileurl mandatory URL to PBI location on server in the format category/pbi_name
rem -m arch mandatory architecture type for PBI being removed (e.g. i386, amd64)
-n pbiname mandatory name of PBI being removed from the INDEX file
-v version mandatory, version of the PBI being removed from the INDEX file

pbi_info(1)

Similar to FreeBSD's pkg_info command, the pbi_info command is used to determine which PBIs are currently installed. Table 7.4i summarizes the available options:

Table 7.4i: pbi_info Options [tables 14]
Switch Description
-a list all PBIs installed on the system; same as running pbi_info without an argument
-i list all available PBIs from any repo
-v enable verbose output

pbi_listrepo(1)

The pbi_listrepo command manages installed repositories on a system. Table 7.4j summarizes this command's options:

Table 7.4j: pbi_listrepo Options [tables 15]
Switch Description
--down move the targeted repoID down a single number in priority
-mirror URL change the specified repoID's mirror URL
--up move the targeted repoID up a single number in priority

Run the command without any options to list the IDs of the available repositories.

pbi_makepatch(1)

The pbi_makepatch command is automatically used by pbi_autobuild to create small *.pbp (Push Button Patch) files. These files can be downloaded to a user's system in order to update a PBI's version without re-downloading the entire archive. This allows users to download only the incremental changes when a PBI is upgraded. The command can also be run manually by providing two PBI archives to compare and generate a patch file for.

Table 7.4k summarizes the available options:

Table 7.4k: pbi_makepatch Options [tables 16]
Switch Description
-o outdir save the resulting *pbp file to the specified directory
--sign keyfile use the specified openssl key to digitally sign the patch file
--tmpfs can reduce building time for large PBIs

pbi_makeport(1)

The pbi_makeport command can be used by packagers to build a target FreeBSD port and convert it into a PBI file. Many options are provided to fine-tune the build process, and meta-data modules can also be specified to further improve the resulting PBI file. The first time this command is run, it will build a fresh chroot sandbox environment which can be used for clean-room building of the target port without affecting the host system. More details about how to create a PBI using this command, can be found in the PBI Module Builder Guide.

NOTE: The pbi_makeport command has support for using ccache[170] to speed up the compile process. If ccache is installed on the host system and the CCACHE_DIR variable is set, the pbi_makeport command will automatically utilize it for the port compile phase. This can be disabled by setting NO_CCACHE=yes in /etc/pbi-make.conf on the host system, or as an optional make flag in a module's pbi.conf file.

pbi_makeport, will attempt to create any users or groups that the underlying ports require during the PBI installation. If the PBI is being installed as non-root, it will instead provide a warning message regarding any users or groups that need to be manually created. For this functionality to work, the port must set USERS= or GROUPS= in its Makefile and provide the corresponding UID and/or GID entries.

Table 7.4l summarizes the available options:

Table 7.4l: pbi_makeport Options [tables 17]
Switch Description
-B build-only; generally used with -k to build a port before running pbi_create manually
-c confdir specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
-d portsdir specify an alternative ports directory; defaults to /usr/ports
-k keep the build files after building the PBI
-o outdir the directory to place the finished PBI file; defaults to user's $HOME directory
-p prefix manually provide a PREFIX which determines the location where the PBI will be installed on the end-user's system
--32 include when building a 32-bit PBI on a 64-bit system
--delbuild remove any existing build directories before starting the build
--mkdebug will drop to a debugging shell should the port make fail
--no-prune disable auto-pruning of non-REQUIREDBY ports after the compile phase; by default any ports which are used solely for building and which are not required for program execution will be pruned
--pkgdir dir uses the specified directory to cache the .txz package so subsequent builds will not rebuild the port from source
--tmpfs automatically create and mount a tmp filesystem and use it for WRKDIRPREFIX; can speed up port compiles on systems with available RAM
--sign keyfile digitally sign the PBI file with the specified openssl private key file

pbi_makerepo(1)

The pbi_makerepo command allows repository maintainers to create a single *.rpo file containing various information about the new repository. This .rpo file can then be installed on the target system with pbi_addrepo. Table 7.4m summarizes the available options.

Table 7.4m: pbi_makerepo Options [tables 18]
Switch Description
--desc description required; description of the repo to be shown in the repo list
--key keyfile required; OpenSSL public key used to verify the digital signature of PBIs installed from this repo
--mirror URL required; URL in http://, https://, or ftp:// format to download PBIs and updates from
--url URL required; URL in http://, https://, or ftp:// format to use when downloading the master INDEX file of available PBIs

pbi_metatool(1)

The pbi_metatool command provides a way for repository maintainers to modify the PBI metadata in their repository in order to add or remove application categories or specified PBIs. An example of using this command can be found in Create Your Own PBI Repository. Table 7.4n summarizes the available options:

Table 7.4n: pbi_metatool Options [tables 19]
Command Switch Description
add or rem --cat indicates that a new category is being added to or removed from the target metafile
--app adds or removes a new PBI to/from the target metafile
add -a author adds the name of the application's author to the target metafile
-c category name of new category to add to the target metafile
-d desc mandatory description of PBI or category being added
-i icon mandatory URL to 64x64 .png icon of PBI or category being added
-k keywords comma delimited list (with no spaces) of search keywords
-l license type of license (e.g. BSD, GPL, Commercial)
add or rem -n name mandatory name of category or PBI being added to or removed from the target metafile
add -t type type of application (e.g. Graphical, Text, Service)
-u URL website of application being added
-r include if application needs to be installed as the superuser

pbi_patch(1)

The pbi_patch command is used to update an installed PBI to a different version using a small diff Push Button Patch *.pbp file. This allows the user to perform an incremental upgrade of an installed PBI. The available options are summarized in Table 7.4o.

Table 7.4o: pbi_patch Options [tables 20]
Switch Description
-e extract only, do not install; will extract the archive to ~/<pbidirname> unless -o is used.
-g extract image data from header; commonly used for GUI installations
-i display information about this PBI file
-o outdir specify the directory to use when only extracting the PBI with -e
--checkscript display any custom scripts used in the installation/removal of this PBI file; recommended if the PBI file is suspect in any way
--no-checksig skip the openssl signature verification of the PBI data
--no-hash disable using the shared hash directory which uses hard links to share files between applications

pbi_update(1)

The pbi_update command is used to display information about which PBIs have available updates and to perform the updates. Table 7.4p summarizes the available options.

Table 7.4p: pbi_update Options [tables 21]
Switch Description
-c check only the specified PBI for available updates
--check-all run a full check of all installed PBIs and display list of available updates
-disable-auto disable auto-updating of the target PBI
--enable-auto enable auto-updating of the target PBI
--update-all update all installed PBIs to the latest versions

pbi_update_hashdir(1)

The pbi_update_hashdir command is used by the pbid daemon to merge the contents of a PBI into the hash directory.

pbid(8)

The pbid command runs a small daemon which performs maintenance of installed PBIs, merges files into the shared hashdir, fetches the repository INDEX and meta files, and makes the adding and removing of PBIs much faster. It will automatically be started from the/usr/local/etc/rc.d/pbid startup script if pbid_enable="YES" is in the /etc/rc.conf file.

This utility supports the option summarized in table 7.4q:

Table 7.4q: pbid Options [tables 22]
Switch Description
-v enable verbose output when the daemon starts
--refresh schedule a refresh of index and meta files

This command logs its output to /var/log/pbid.log. Check this log for errors should you experience any problems with PBI maintenance.



pkgng and pc-metapkgmanager

PC-BSD® uses pkgng, the next generation package management system for FreeBSD. All of the PC-BSD® utilities that deal with installing or updating non-PBI software now use the pkgng system. This allows users to safely install non-PBI software from the command line without that software being deleted by a system upgrade.

Since FreeBSD does not have an official pkgng repository yet, the PC-BSD® project provides its own repository containing all of the packages that can be built using pkgng.

PC-BSD® provides a custom command, pc-pkg, which is a small wrapper to pkg. When pc-pkg is used with the install or upgrade flags, it will automatically connect to the PC-BSD® pkgng repository using the integrated aria2[14] downloader utility, which can significantly reduce download speeds over a slow link.

If you are used to using the traditional FreeBSD package system, take note that the commands used to install and manage software differ slightly. For example, instead of using pkg_add to install a package from a remote repository, use pkg install or pc-pkg install (notice there is now a space instead of an underscore).

The FreeBSD Handbook[93] provides an introduction to using pkgng. Section 5.5.1 is not needed on a PC-BSD® or TrueOS® system as the operating system installation does this for you. The various pkgng commands have associated man pages. Type man pkg for an overview of general usage; the names of the associated man pages will be found towards the bottom of this man page. Once you know the name of a command, you can also use the built-in help system to get more information about that command. For example, to learn more about pkg install, type pkg help install.

pc-metapkgmanager

pc-metapkgmanager is the back-end command line utility used by the PC-BSD® installer, Package Manager, and Warden® to manage meta-packages. Meta-packages are like system components, and include supported and unsupported desktops, development utilities, hardware drivers, and miscellaneous applications such as MythTV or XBMC.

The pc-metapkgmanager command can be used to install or delete meta-packages. If you type the command without any options, it will display its usage:

pc-metapkgmanager

usage: pc-metapkgmanager [options] Options: add pkg1,pkg2 <loc> -- Add the specified list of meta-packages del pkg1,pkg2 -- Delete the specified list of meta-packages list -- List the available meta-packages status <pkg> -- List the status of the specified meta-packages  

--pkgset <pkgset> -- Change default pkgset we are using

To determine which meta-packages are available:

pc-metapkgmanager list | more

Meta Package: Awesome ------------------------------------- Description: A highly configurable, next generation framework window manager Icon: /usr/local/share/pcbsd/metaset/pcbsd/Awesome/pkg-icon.png Parent: Unsupported-Desktops Desktop: YES Required Packages: pcbsd-meta-awesome Meta Package: Compiz ------------------------------------- Description: Compiz - OpenGL compositing manager Icon: /usr/local/share/pcbsd/metaset/pcbsd/Compiz/pkg-icon.png Parent: Misc Desktop: NO Required Packages: pcbsd-meta-compiz Meta Package: Desktops ------------------------------------- Description: Supported Desktop Environments for your PC-BSD system. Icon: /usr/local/share/pcbsd/metaset/pcbsd/Desktops/pkg-icon.png Desktop: NO

--More--(byte 989)

To determine if a meta-package is installed, specify its "Meta Package" name as shown in the output of the pc-metapkgmanager list command. For example, to see if the Awesome desktop is installed:

pc-metapkgmanager status Awesome The meta-pkg Awesome is not installed                                       

To install the meta-package, use the add option and specify the meta-package name. Only the superuser can install meta-packages.

The following example installs the Awesome meta-package. pc-metapkgmanager will provide messages regarding the status of the installation:

pc-metapkgmanager add Awesome

Pending Meta-Package changes: 1 Installing Meta-Package: Awesome (pcbsd-meta-awesome) Updating repository catalogue /usr/local/tmp/All/pcbsd-meta-awesome-13661335 100% of 2860 B 18 kBps 00m01s Updating repository catalogue Resuming download of: /usr/local/tmp/All/pcbsd-meta-awesome-1366133527.txz   The following 1 packages will be installed:   Installing pcbsd-meta-awesome: 1366133527 0 B to be downloaded Checking integrity... done [1/1] Installing pcbsd-meta-awesome-1366133527... done Cleaning up cache files..Done The meta-pkg Awesome is installed Extracting ports overlay data...DONE Finished Meta-Package: Awesome

Meta-Package changes finished!

To delete an installed meta-package, specify its name. Only the superuser can uninstall meta-packages. As seen in the following example, pc-metapkgmanager automatically determines which dependent packages are still needed by other applications and which can be safely removed.

pc-metapkgmanager del Awesome

Pending Meta-Package changes: 1 Removing Meta-Package: Awesome Removing: pcbsd-meta-awesome The meta-pkg Awesome is not installed                                       

Meta-Package changes finished!



pc-updatemanager

pc-updatemanager is the command line equivalent to Update Manager. It can be used to apply system updates and to perform an operating system upgrade. It can also be used to update packages, providing a command line equivalent to the "Package Updates" tab of Package Manager.

If you type pc-updatemanager, it will show its available options:

pc-updatemanager                                                                

/usr/local/bin/pc-updatemanager - Usage ----   branches - List available system branches   chbranch <tag> - Change to new system branch   check - Check for system updates   install <tag>,<tag2> - Install system updates   pkgcheck - Check for updates to packages

  pkgupdate - Install packages updates

Upgrading Packages

To determine if newer versions of packages are available, type the following command as the superuser.

pc-updatemanager pkgcheck                                                       

  Updating repository catalogue   Upgrades have been requested for the following 253 packages:   list of packages snipped   The upgrade will require 70 MB more space   439 MB to be downloaded

  To start the upgrade run "/usr/local/bin/pc-updatemanager pkgupdate"

In this example, newer versions are available for 253 packages. The list of package names was snipped from the sample output. If no updates were available, the output would have instead said "All packages are up to date!".

If updates are available, you can install them with this command:

pc-updatemanager pkgupdate                                                      

  Updating repository catalogue   snip downloading and reinstalling output   [253/253] Upgrading pcbsd-base from 1374071964 to 1378408836... done

  Extracting desktop overlay data...DONE

While the output has been snipped from this example, the update process will download the latest versions of the packages which need updating, displaying the download progress for each file. Once the downloads are complete, it will display the reinstallation process for each file. The last step of the update process is to extract the desktop (or server) overlay and then to return the prompt.

How long the package upgrade takes depends upon the number of packages and the speed of the Internet connection. If you run this command on a desktop, you should log out and log in again so that you load the latest version of the desktop and its applications. If you run this command on a server while running the tcsh shell, type rehash in order to tell the shell that new applications have been installed.


To determine if any system updates are available, type the following command as the superuser:

pc-updatemanager check                                                          

  The following updates are available:

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

Follow the instructions to install the update:

Upgrading the Operating System

Caveat:
before performing an operating system upgrade, read the caveats listed in Update manager. Be sure to backup your important data to another system or external device before starting the upgrade.
pc-updatemanager install release-9.1                                            

  STARTINGUPDATE: 9.1

  Downloading Master Files...

The upgrade will then proceed as usual and you will be prompted when the system is ready to reboot. -->



Control Panel

PC-BSD® provides a Control Panel which contains tools for managing your system. The Control Panel is available from any desktop, meaning it is available regardless of which desktop you log into.
Figure 8.a: PC-BSD® Control Panel
NOTE: If an unsupported desktop does not contain an icon or menu item for Control Panel, simply type pc-controlpanel from a shell prompt to launch the Control Panel.

A screenshot of Control Panel started from the KDE desktop can be seen in Figure 8.a.

The search box in the upper right can be used to find the proper control panel item if you know what you would like to configure but are uncertain which utility to use.

If an icon includes a yellow exclamation mark, you will need to input your password in order to access that configuration utility.

NOTE: If your user account is not a member of the wheel group, you will not see the configuration utilities in Control Panel that require a password. By default, the first user account that you create is made a member of the wheel group. You can log in as that user and use User Manager to add other accounts to this group.

Desktop Selector

Control Panel includes a desktop selector drop-down menu which allows you to view the configuration utilities from KDE4, GNOME2, XFCE4, or LXDE. Figure 8.b shows the desktop selector menu in use. In this example, the user is currently logged into the LXDE desktop but they have chosen to view the GNOME utilities. The menu icon indicates the control panel view while "(current)" will be beside the desktop that is presently active. If any other desktop were active, then "Unsupported DE (current)" would be shown. The icon used for installed unsupported desktops looks like a window with a red 'X' on the lower left corner.

Figure 8.b: Desktop Selector Menu

Switching between the icons in the selector changes the icons displayed within the control panel window to match those used in that desktop. If "All" is set by the desktop selector, you will see every utility that is available, depending upon which desktops are currently installed. You can change which desktops are installed using Package Manager.

Included Utilities

The following utilities are found in the Control Panel of a PC-BSD® system, regardless of the desktop that is installed:

Software and updates
System management
Hardware
Networking
Tools



EasyPBI2

EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. PC‑BSD® 9.2 uses EasyPBI version 2 which can be launched from Control Panel or by typing EasyPBI.

The new features built into EasyPBI version 2 include:

  • The ability to package a local directory into a PBI without using the FreeBSD Ports Collection.
  • An additional option for building 32-bit PBIs on 64-bit systems.
  • Complete support for editing installation wrapper scripts as well as a basic template for creating new binary wrapper scripts.
  • Improved support for the creation and editing of XDG desktop and menu entries with easy MIME type integration.
  • The OptionsNG format for setting port build options is enabled by default.
  • Support for multiple lines when specifying build options.
  • New "Settings" dialog for setting and changing default directory paths, PBI build settings, and external utilities.
  • New "Ports" dialog displays the last time the ports tree was updated and simplifies the process of using portsnap or svn to update the system ports tree.
  • New "About" dialog for quickly viewing information about EasyPBI such as its license information and development history.

Quick Start to Creating a PBI Module

Before building a PBI, refer to the PBI Requests forum to determine which PBIs have been requested by users. You should also check that a module does not already exist for the PBI in the PBI Modules repository. Existing PBI modules are listed alphabetically, according to their category in the ports collection.

When EasyPBI starts up, it automatically checks to see if the FreeBSD ports tree is installed. If it is not, the message shown in Figure 8.1a will appear.

Figure 8.1a: Ports Tree not Installed

EasypbiMissingUtils2.png

Since the ports tree is needed to create PBIs, click OK to close this message then go to Options → EasyPBI Settings → FreeBSD Ports to access the screen shown in Figure 8.1b.

Figure 8.1b: Updating FreeBSD Ports

EasypbiFreebsdports1.png

Click the "Ports Tree" drop-down menu to select to install the ports tree to a specified directory ("Other"), only within the current user's home directory, or in /usr/ports so that it is available to other users. After making your selection, click the "Create Dir" button to be prompted for your password in order to install the ports collection.

Once the ports tree is installed, you are ready to create a new module. Click the “New” button to access the screen shown in Figure 8.1c.

Figure 8.1c: Creating a New Module

Newmodule1.png

Use the FreeBSD Port “Select” button to browse to the desired port from the FreeBSD ports tree. A generic icon will be supplied for the module. You can change the default icon by clicking the Icon File “Select” button. When selecting a custom icon, use a 64x64 .png file with a transparent background. After making your selections, click “OK”.

EasyPBI will automatically supply the port information for the PBI and display the results. In the example shown in Figure 8.1d, the net-p2p/linuxdcpp port has been selected.

Figure 8.1d: Module Program Information

Newmodule2.png

You are now ready to build and test the PBI.

The next section describes all of the EasyPBI settings should you wish to further customize the module before building it. Otherwise, you can skip ahead to the section on building and testing the PBI module.

Advanced Configuration

The previous section demonstrated how to quickly generate a PBI using the default module settings. This section describes which options are available for customizing PBI modules.

EasyPBI Settings

To setup the options for building PBIs, click “Options” → “EasyPBI Settings”. There are three available tabs which are discussed in this section.

FreeBSD Ports Tab

Figure 8.1e shows the FreeBSD Ports tab on a system that already has FreeBSD ports installed to /usr/ports.

Figure 8.1e: FreeBSD Ports Settings

Freebsdports.png

In this example, the ports tree was last updated on July 2. To update the ports tree, click the "Update" button. To install the ports tree into another directory, click the drop-down "Ports Tree" menu.

PBI Builds Tab

The PBI Builds tab is shown in Figure 8.1f.

Figure 8.1f: PBI Build Settings

Builds.png

The options in this screen can be summarized as follows:

PBI Output Dir: specifies the directory to store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory. Click the “Select” button to browse to another location.

Digitally Sign PBI: if you check this box, you will be prompted to select the location of the file containing the OpenSSL signature which will be used to digitally sign the PBI so that it is ready for for tamper-evident distribution. Create Your Own PBI Repository provides instructions for creating a signature file.

Use TMPFS: if your build system has more than 2GB of RAM, checking this option can speed up the build as it instructs the PBI build process to save all of the relevant port build pieces into memory rather than disk. If you get “Out of memory” errors when building a large port, you can uncheck this option for that particular build.

Use Package Caching: this setting is recommended as it saves all compiled ports as packages in the system cache in order to speed up subsequent builds by using the pre-built packages from the cache whenever possible rather than re-compiling every port dependency. Two additional options for dealing with the cache are available. The first option is to clear all packages from the cache and start fresh. The second option is to add a problematic package to the “Ignore” list. This will remove the specified package from the cache before starting each build, ensuring that it will always compile that port for each build that requires it.

Local Paths Tab

The Local Paths tab is shown in Figure 8.1g.

Figure 8.1g: Local Paths Settings

Paths.png

The options in this screen allow you to configure the following paths:

External Utilities: the default paths of the utilities used by EasyPBI to build PBI modules. The "Auto-Detect" button can be used to detect a new path if a missing utility is installed onto a FreeBSD system running EasyPBI.

Default Search Paths: the default directory that new modules are saved to, the initial search location for icons and other resources, and the default icon used by PBI modules.

Module Editor

The module editor pane for EasyPBI2 supports complete control over all the options available when creating PBI modules. Most of these options are not necessary for the majority of PBI modules, but they are available for applications that need some extra tweaking to work properly.

EasyPBI provides suggestions and default settings whenever there is a green arrow next to an option within the module editor. Click the arrow to view the suggestions, then click a suggestion to instruct EasyPBI to add it to the proper option within the module.

This section describes the five tabs that are available within the module editor pane.

PBI Configuration

Figure 8.1h shows the PBI Configuration tab of the module editor pane. This tab is used to set the required information about the program being packaged as a PBI.

Figure 8.1h: PBI Configuration

Newmodule2.png

As seen in the Quick Start, EasyPBI automatically fill in the port information when you browse to a FreeBSD port to convert into a PBI. Under "Program Information" the port's name, website, author (FreeBSD maintainer), and default icon are filled in for you. You should review these fields for accuracy:

  • if necessary, correct the capitalization in "Name".
  • if the application's author is not listed in the port information, it will instead list the email address of the FreeBSD port maintainer. If the application has a specific author, this should be corrected.
  • if you wish to change the default icon, see the next section on the Resources tab to add additional icons to the drop-down selection list.

The "Build Information" box provides all of the options available for building the PBI. If you selected to build a PBI from local sources in Figure 8.1c, this section will only contain the local directory to be packaged as a PBI. If you are building a PBI from a FreeBSD port, there are a number of other options as seen in Figure 8.1i.

When converting a FreeBSD port to a PBI, the only required option is the “Main FreeBSD Port”. This is set automatically based upon the port that you selected in Figure 8.3c, but you can change your initial port selection by clicking the “Change Port” button.

Some FreeBSD ports provide build options. If you click “Information” → “FreeBSD Ports”, the FreshPorts entry for that port will open up in a web browser. Look for the "Configuration Options" for that entry. If there are any options, you can enable them in the “Port Build Options” box. EasyPBI will autodetect the available options and provide them as suggestions. Clicking the button with the green arrow to see the options and to select the build options to use. The selected options will be added to the "Port Build Options" box. If the port does not have any options, no suggestions will appear when you click the green arrow.

If you discover that the port appears to be missing a dependancy for the application you are packaging as a PBI, you can add additional FreeBSD ports to the "Make Port Before/After” options. If the missing dependency is causing the port to not build properly, add it to the “Make Port Before” option. If it is a missing runtime dependency, add it to the “Make Port After” option.

The last option is for both local and port PBI modules. The “Requires Root Permissions” checkbox lets you set whether the PBI can only be installed and uninstalled using root privileges. This is important if the program requires special users or groups to be created, or an installation script needs access to the local system to make modifications.

NOTE: changes within this screen will not be saved until you click the “Save Configuration” button. Be sure to save any changes before leaving this tab.

Resources

The resources tab, shown in Figure 8.1i, displays any extra files to included in the PBI. If you click the entry for an image file, the full size image with size and type information will be displayed. For other types of files, such as scripts, EasyPBI will attempt to display the text inside the file.

Figure 8.1i: Resource Options

Easypbiresources1.png

This tab is mainly used to add PNG images to be used as PBI icons. If you add an icon, use a 64x64 .png file with a transparent background.

An example of an additional file would be an application that requires the user to accept a License. Use the “+Add File” button to browse to the location of the LICENSE file.

If the application uses custom installer graphics, add them using this screen.

Another use is to create a wrapper script for starting the application. This is generally used for applications that have an environment variable that needs to be set before starting the program, such as JAVA_HOME. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.

EasyPBI will assist in creating a wrapper script if you click the “+Wrapper Script” button. This will prompt for a filename in the format application_name.sh. Click the "OK" button and an entry will appear as EasyPBI automatically generates the script from a template that sets the most commonly used variables. In the example shown in Figure 8.1j, click the area below the DO SOMETHING HERE comment to customize the script. Creating a wrapper script is considered an advanced task that requires some knowledge of shell scripting, so feel free to ask for help on the PBI Discussion forum or on the PBI developers mailing list.

Figure 8.1j: Edit the Automatically Generated Script

Script.png

XDG Entries

This tab, shown in Figure 8.1k, is used to create desktop icons and menu entries so that the application can be easily started from within a desktop environment. This is important step for graphical applications as it configures the primary method for interacting with the program.

Figure 8.1k: Desktop Entries

Easypbixdgdesktop.png

As seen in this example, the entries currently configured for the module will appear in the left side of the tab. Click an existing entry to display its details on the right. You can remove an entry by clicking the “-” (minus sign) button, or create a new entry by clicking on the white paper button under the entry list. On the right side of this tab, you can edit the currently selected entry and click the “Save” button to overwrite the current entry with the new settings. Alternately, click “Add” to copy the existing details to a new entry.

The "Entry Details" section of this tab are as follows when the "Desktop" button is selected:

  • Name: this is the text that will appear for the desktop menu entry, and is usually the full name of the application.
  • Executable: click the green arrow to select the executable or script that is used to start the application. Some ports have multiple binaries, so select the one associated with the program. If you created a script in the Resources tab, it will be added to the list and should be selected.
  • Icon: the available icons will include the default icon and any that you added in the Resources tab.
  • Open in Terminal: used to specify whether the application needs to be opened in an X terminal. This is useful for running some text-based programs that need to be embedded into a console for user interaction.
  • Make Invisible: if checked, the entry will be hidden. This is not as useful for desktop entries but can be handy with menu entries.
  • Requires Root: if checked, the user will be prompted for their password when the application starts.

Figure 8.1l shows the "Entry Details" that are available when "Menu" is selected.

Figure 8.1l: Menu Entry Details

Easypbixdgmenu.png

This screen adds two fields:

  • Category: indicates the menu category that the entry will be placed under when listed in the desktop environment. Click the green arrow to see the available menu categories. The recommended category will have a small black arrow next to it.
  • MIME Patterns: used to associate a space-separated list of file types with the application. This is useful when paired with the “Make Invisible” option. For example, consider an application which has two binaries representing two different aspects of the program and an additional binary that asks which of the two you want to use. You could create menu entries for all three binaries, but make the two specific ones invisible and associate file types with them. This means that when a user tries to open one of those file types, it will automatically run the particular binary that uses it, rather than prompting the user for input about what to do with the file.

Scripts

This tab, shown in figure 8.1m, is used to view and edit installation scripts used by the PBI.

Figure 8.1m: Installation Scripts

Easypbiscripts.png

If you click on the drop-down menu, you will see a list of available scripts, with an icon indicating whether or not that script exists in the module. Selecting a script will activate a "Create" button if the script does not exist, or will display the full script in a box for editing.

For “Local Source” PBIs, the only valid scripts are pre-install.sh, post-install.sh, and pre-remove.sh. EasyPBI will only display the list of valid scripts.

NOTE: changes to the scripts in this screen will not be saved until you click the “Save ” button. Be sure to save your work before leaving this tab.

External Links

This tab, shown in Figure 8.1n, is used to setup links for additional binaries within the PBI.

Figure 8.1n: External Links

Easypbiexternallinks.png

This screen becomes important if you add additional files to the PBI, such as wrapper scripts, that are not included in the FreeBSD port. Also, if you are packaging a local directory into a PBI instead of using a FreeBSD port, this screen is needed to setup the main binaries for the application.

When adding an entry, configure the following fields:

  • File: the binary location in the PBI directory. Click the green arrow to select the binary to link. For FreeBSD ports, the binaries from the port are already configured, so you do not need to add them here unless you want to change the "File Type".
  • Link To: input the path to link the binary to on the base system, relative to /usr/local/.
  • File Type: click the green arrow to set the type of link.

The following "File Type"s are supported:

  • binary: indicates that this is an executable. The PBI will automatically create the necessary wrapper and PATH links.
  • linux: indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links.
  • keep: instructs the PBI to not overwrite an existing file when linking a file into the LOCALBASE. By default, LOCALBASE is set to /usr/local.
  • replace: instructs the PBI to overwrite an existing file when linking a file into the LOCALBASE.
  • nocrash: disables the crashhandler GUI from running on this PBI. However, the glue for the crash handler is not built into the base system yet.

Build, Test, and Submit the PBI

The PBI Builder pane provides a graphical front-end to the PBI build structure. Once you have finished using "Module Editor", click the "PBI Builder" pane to build the PBI on your local system.

In the example shown in Figure 8.1o, the user has created a PBI module for the FreeBSD port p7zip. Since this is the module that appears at the top of the screen, this is the module that will be built if the user clicks the "Build PBI" button.

Figure 8.1o: PBI Builder

Easypbibuildsettings.png

To build a different module, either click the "Load" button to browse to the location of a previously saved PBI module or the "New" button to select a different FreeBSD port or local source to build.

To start the build of the PBI module, click the "Build PBI" button. A pop-up message will remind you that a working Internet connection is required so that the build process can download the source required to build the port. It will also prompt for the user's password.

The first time you build a PBI, EasyPBI will download the chroot environment used to build PBIs. Subsequent builds will reuse this environment. The build process itself may take some time, depending upon the size of the port selected and the speed of your computer. Build messages will be displayed in the white window. EasyPBI will inform you when the PBI build is finished, and whether it was successful or not.

If you wish to build a 32-bit version of the PBI on a 64-bit system, check the box "Build 32-bit".

During the build, you can create additional PBI modules by clicking the "Module Editor" pane. Click the "PBI Builder (Working)" pane to check on the status of the build. However, you can only build one PBI module at a time. If you need to stop the build process, click the "Cancel Build" button.

If the build fails, you may need to modify the module using "Module Editor". Click the "Save Build Log" button and browse to the location to save the log file which can be read with any ASCII text editor. Read the saved log to determine the error so that you can modify the module as needed. If you are unsure how to fix the PBI module, send the log for the failure to the pbi-dev mailing list.

Test the PBI

Once your build is finished, test the PBI to ensure that it installs and that the application works.

To install the PBI, become the superuser, cd to your PBI directory, and use the pbi_add command. Unless you have specified your own digital signature, include the --no-checksig option.

su

Password: cd ~dru/EasyPBI/PBI ls p7zip-9.20.1-amd64.pbi p7zip-9.20.1-amd64.pbi.sha256                          pbi_add --no-checksig p7zip-9.20.1-amd64.pbi Verifying Checksum...OK Extracting to: /usr/pbi/p7zip-amd64

Installed: p7zip-9.20.1

If the module installs successfully, perform the following tests:

  • for a graphical application, verify that a desktop icon was created (from a desktop that supports icons), that an entry was added to that desktop's application menu, and that the application successfully launches from the application menu. If you used a custom icon, verify that the icon was used.
  • start the application from the command line to determine if there are any error messages at application launch. When starting the application, specify the full path to the application's binary to make sure that you are testing the PBI's binary.
  • for a graphical application, go through the various menus to see if they produce any errors. If you encounter any error messages in either starting or using the application, record them. If the fix for resolving the error messages is not clear to you, send the error report the pbi-dev mailing list.

If you modify any settings in the PBI's module, rebuild the PBI then test again to see if the changes fixed the PBI.

Submit the PBI Module

Once you are satisfied with the PBI, go to “Options” ➜ “Package Module”. A pop-up window will indicate that the module has been successfully packaged within the default "Modules" directory. The file name for the example PBI would be ~dru/EasyPBI/Modules/p7zip.tar.gz.

If you send that file to the pbi-dev mailing list, it will be added to the PC-BSD® build servers so that the PBI can be built. Once the built PBIs are tested, they will be added to AppCafe® so that other PC-BSD® users can benefit from the PBI.



About

The "About" icon of Control Panel can be used to quickly find information about the PC-BSD system. To start the application, double-click its icon in Control Panel or type about-gui. An example is seen in Figure 8.2a.

The displayed information includes the version of PC-BSD®, the hostname of the system, the architecture, the name of the kernel (ident), the type of CPU, and the amount of installed memory.

If you click the “System components” button, the X.org version and release versions of the PC-BSD command line and graphical utilities will be displayed, as seen in the example shown in Figure 8.2b.

If you click "Back" and then the "Desktop environments" button, the currently installed desktops and their versions will be displayed, as seen in the example in Figure 8.2c. If you wish to install additional desktops, use Package Manager.

Figure 8.2a: About Information
Figure 8.2b: System Components Screen
Figure 8.2c: Desktop Environments Screen



Active Directory & LDAP

The “Active Directory & LDAP” icon is used for managing connections to an Active Directory or OpenLDAP domain. If your network contains an Active Directory or OpenLDAP server, use this icon to input the settings needed to connect to your account information stored on the network.
Figure 8.3b: Managing LDAP Client Settings
NOTE: This utility is used to manage the settings of the client, not the Active Directory or OpenLDAP server itself. This application also needs more testing from users. If you have trouble using this utility or find a bug, please post the details using the PC-BSD® Bug Reporting tool.

To start the application, double-click its icon in Control Panel or type pc-su pc-adsldap. You will be prompted to input your password. Figure 8.3a shows the configuration utility with the Active Directory tab open.

Connecting to Active Directory

If you need to connect to a network running Active Directory, check the box "Enable Active Directory". This will change the greyed-out status of the rest of the screen, allowing you to configure the following:

  • Domain Name (DNS/Realm-Name): input the name of the Active Directory domain (e.g. example.com) or child domain (e.g. sales.example.com). This setting is mandatory.
  • NetBIOS Name: input the hostname of the PC-BSD® system as listed in the About icon.
  • Workgroup Name: input the name of the Windows workgroup. Unless the administrator has changed it, the default workgroup name is WORKGROUP.
  • Administrator Name: input the name of the Active Directory Administrator account.
  • Administrator Password: input and confirm the password for the Active Directory Administrator account.

The values that you input using this GUI are saved to /usr/local/etc/pc-activedirectory.conf.

NOTE: Once you enable AD, you can no longer use auto login as users will now authenticate with the Active Directory server.

Connecting to an OpenLDAP Server

Figure 8.3b shows the configuration utility with the LDAP tab open.

If you need to connect to a network which contains a configured LDAP server, check the box "Enable LDAP". This will change the greyed-out status of the rest of the screen, allowing you to configure the following:

Figure 8.3a: Initial Active Directory & LDAP Screen
  • Hostname: input the hostname or IP address of the OpenLDAP server. This setting is mandatory.
  • Base DN: input the top level of the LDAP directory tree to be used when searching for resources (e.g. dc=test,dc=org).
  • Allow Anon Binding: only check this box if the LDAP server allows read and write access without requiring authentication.
  • Root bind DN: input the name of the administrative account on the LDAP server (e.g. cn=Manager,dc=test,dc=org).
  • Root bind password: input the password for the Root bind DN.
  • Password Encryption: select a type supported by the LDAP server, choices are: clear (unencrypted), crypt, md5, nds, racf, ad, or exop.
  • User Suffix: this setting is optional and is usually a dept. or company name. The input value will be added to the name when a user account is added to the LDAP directory
  • Group Suffix: this setting is optional and is usually a dept. or company name. The input value will be added to the name when a group is added to the LDAP directory.
  • Password Suffix: this setting is optional. The input value will be added to the password when a password is added to the LDAP directory.
  • Machine Suffix: this setting is optional and usually represents a description such as server or accounting. The input value will be added to the name when a system is added to the LDAP directory.
  • Encryption Mode: choices are "Off", "SSL", or "TLS". The selected type must be supported by the LDAP server.
  • Self Signed Certificate: used to verify the certificate of the LDAP server if SSL connections are used. Paste the output of the command openssl s_client -connect server:port -showcerts.
  • Auxiliary Parameters: ldap.conf(5)[172] options, one per line, not covered by other options in this screen.

The values that you input into this tab are saved to /usr/local/etc/pc-ldap.conf.

If you are new to LDAP terminology, you may find it useful to skim through the OpenLDAP Software 2.4 Administrator's Guide[173].



Boot Manager

PC-BSD® supports a feature of ZFS known as multiple boot environments (BEs). With multiple boot environments, the process of updating software becomes a low-risk operation as you can backup your current boot environment before upgrading or making software updates to your system. If needed, you also have the option of booting into a backup boot environment. For example:

  • if you are making software changes to a boot environment, you can take a snapshot of that environment at any stage during the modifications.
  • you can save multiple boot environments on your system and perform various updates on each of them as needed. You can install, test, and update different software packages on each.
  • you can mount a boot environment in order to chroot into the mount point and update specific packages on the mounted environment.
  • you can move a boot environment to another machine, physical or virtual, in order to check hardware support.


WARNING For boot environments to work properly, do not delete the default ZFS mount points during installation. The default ZFS layout ensures that when you create multiple boot environments, the /usr/pbi/, /usr/local/, /usr/home/, /usr/ports/, /usr/src/ and /var/ directories remain untouched. This way, if you rollback to a previous boot environment, you will not lose data in your home directories, any installed applications, or downloaded src or ports. During installation, you can add additional mount points, just don't delete the default ones.

Managing Boot Environments Using Boot Manager

To create and manager boot environments using a graphical interface, go to Control Panel ➜ Boot Manager or type pc-su pc-bootconfig. You will be prompted to enter your password.

During installation, PC-BSD® creates a boot environment named default. As seen in Figure 8.4a, an entry for this boot environment will be displayed in the Boot Manager screen.

Figure 8.4a: Managing Boot Environments

Anything outside of the default dataset will not be included in the boot environment. To ensure that the files that the operating system needs are included when the system boots, all boot environments include /usr, /usr/local, and /var. User-specific data is not included in the boot environment. This means that /usr/home, /usr/jails, /var/log, /var/tmp, and /var/audit will not change, regardless of which boot environment is selected at system boot.

From top to bottom, the icons on the far left are used to:

Create: a new boot environment. You should do this before making any changes to the system that may impact on your current boot environment. You will be prompted for a name. Once you click OK, the system will create the environment, then add it to the list of boot environments.

Remove: will delete the highlighted boot environment. You can not delete the boot environment which has a Running status of Yes as that is the current boot environment.

Copy: creates a copy of an existing boot environment.

Rename: used to rename the highlighted boot environment. The name is what appears in the boot menu when the system boots.

Activate: tells the system to boot into the highlighted boot environment at next system boot. The Default will change to Yes, but the Running will remain the same. In other words, Running refers to the boot environment the system last booted into (is currently running from) whereas Default indicates which boot environment the system will boot into at next system boot.

If you create any boot environments, a boot menu similar to the one seen in Figure 8.4b will appear for five seconds during system boot. The menu contains the names of the boot environments and the date each was created. If you don't make a selection, the system will automatically boot into either the last "Running" boot environment or, if you have activated another boot environment, the environment that was set as the "Default".

Figure 8.4b: Boot Menu Shows Created Boot Environments

To customize this menu, click the "Grub Configuration" tab to see the screen seen in Figure 8.4c.

Figure 8.4c: Managing GRUB Configuration

The fields in this screen are used to configure the:

  • Font File: before a font can be used in the GRUB menu, it must first be converted to .pf2 format using the grub-mkfont(1) command.
  • Timer: sets the delay time for accessing the GRUB menu. By default it is 2 seconds, so if you find that the time to access the menu goes by too quickly, increase this timer.
  • Custom Entries: if you have an existing GRUB configuration that you would like to add to the menu, cut and paste it into the box. Refer to the GRUB Manual[176] for more information on creating a custom GRUB configuration.

If you make any changes in this tab, the two buttons below "Settings" or "Custom Entries" will be activated. Use them to save your changes and to re-load the GRUB configuration. If you forget to do so, a pop-up message will remind you that you have unsaved changes when you exit Boot Manager. If you do not save the changes, the boot menu will remain the same.

Managing Boot Environments From the Command Line

If you are running TrueOS® or prefer to use the command line, you can manage boot environments using the beadm command as the superuser. For example, this command creates a boot environment named beforeupgrade:

beadm create beforeupgrade                                              Created successfully

To view all boot environments, use the list command:

beadm list                                                                      

BE Active Mountpoint Space Policy Created default NR / 6.05G static 2013-08-23 09:03

beforeupgrade - - 1K static 2013-08-27 10:14

The possible flags in the "Active" field are as follows:

  • R: active on reboot
  • N: active now
  • -: inactive

In this example, the current boot environment is called default, it is active now, will be used at next reboot, and it is mounted. The newly created beforeupgrade boot environment exists, but is inactive and unmounted. To activate the new boot environment:

beadm activate beforeupgrade                                                    

Activated successfully beadm list BE Active Mountpoint Space Policy Created default N / 64.5K static 2013-08-23 09:03

beforeupgrade R - 6.05G static 2013-08-27 10:14

The flags now indicate that the system is currently booted into default, but at next boot the system will boot into beforeupgrade.

The boot menu configuration can be found in the ASCII text file /usr/local/etc/default/grub:

more /usr/local/etc/default/grub                                                

GRUB_THEME=/boot/grub/themes/pcbsd/theme.txt GRUB_FONT=/boot/grub/pcbsdfont.pf2 GRUB_HIDDEN_TIMEOUT_QUIET=false GRUB_TIMEOUT=2

GRUB_DEFAULT=1



Hardware Compatibility

The PC-BSD® installer allows you to quickly determine if your system's video card, Ethernet card, wireless device, and sound card are compatible with PC-BSD®. The "Hardware Compatibility" icon in Control Panel provides a quick overview of the system's detected hardware.
Figure 8.5a: Sample Hardware Compatibility

To start the application, double-click its icon in Control Panel or open an xterm and type pc-sysinstaller -checkhardware.

In the example shown in Figure 8.5a, this system has a detected NVIDIA video card with a configured resolution of 1600x900, one Ethernet device using the em(4)[177] driver, and one wireless device using the iwn(4)[178] driver. Currently no sound card is detected, meaning that the user should configure and test their sound card using the Sound Configuration icon in Control Panel.

If the wireless device shows as unsupported, check the Wireless Testing page to help determine if a driver is forthcoming or if the device is well suited to converting a Windows driver into a FreeBSD loadable module.

Hardware that is currently incompatible may show with a green checkbox after a system upgrade or update. This indicates that the update added the driver for the device.



GDM Manager

PC-BSD® uses the GNOME Display Manager (GDM[179]) as its graphical login program. This program was chosen for its support of keyboard layouts, localizations, and accessibility.

A GDM Manager utility is available in Control Panel. Figure 8.6a shows the initial screen when you click on this icon in Control Panel or type pc-su pc-gdmconf at the command line. Note that this utility will prompt you for your password.

Figure 8.6a: GDM Configuration Utility
Figure 8.6b: Configuring Remote Login

For security reasons, PC-BSD® defaults to a login screen. This means that users are required to input their password before logging into the PC-BSD® system. If you are the only user on the PC-BSD® computer, always use the same window manager, and do not consider it a security risk for the system to automatically boot into that window manager, you can enable auto-login using the "Auto login" tab.

Figure 8.6c: Allowing X Connections

As seen in the example in Figure 8.6a, the "Enable auto login" box is unchecked by default. If you check the box, the "Auto login user" drop-down menu will be activated. Select the user account to automatically login as. You can also set a delay period (in seconds) to give time to cancel the auto-login, for example if you wish to log into a different desktop.

The "Remote login" tab, shown in Figure 8.6b, is used to configure XDMCP[54], a protocol that comes with Xorg and allows a connection to an X session from a remote system. Uncheck the "Enable XDMCP" box to enable this service and expose the configuration options. By default, XDMCP uses UDP port 177, allows one connection per host, and allows up to 16 simultaneous sessions.


WARNING Use extreme caution when enabling this option as it can make your system available to anyone over the network. If you need someone to access your PC-BSD® system to assist with troubleshooting, consider using Desktop Sharing instead, which allows you to send an invitation to connect. Always disable any type of remote login immediately after finishing your troubleshooting session.

The "Misc" tab, shown in Figure 8.6c, is used to configure whether or not other computers are allowed to connect to your X server, which provides your GUI environment.

For security reasons, no connections are allowed by default. If you check the "Allow incoming TCP X connections", other computers in your network may have access to your GUI. Use extreme caution when enabling this option as it can make your system available to anyone over the network. If you are enabling this option for troubleshooting purposes, uncheck this box immediately after finishing your troubleshooting session.



Service Manager

Service Manager, seen in Figure 8.7a, provides a graphical utility for managing PC-BSD® services. Buttons make it easy to start, stop, or restart services and to set the highlighted service to be enabled or disabled whenever the system boots. To access this utility, go to Control PanelService Manager or open an xterm then type pc-su pc-servicemanager.
Figure 8.7a: Managing Services Using Service Manager
You will be prompted to input your password.

By default, services will be listed alphabetically. You can reorder the services by clicking on the "Service Name", "Running", or "Enabled" header.

Service Manager is a graphical front-end to the rc scripts located in /etc/rc.d. PC-BSD® 9.2 will include an "Info" button where you can get a short description of the highlighted service.

If you do not know what a service does, do not change its settings in Service Manager. If you would like to learn more about a service, try seeing if there is a man page for it. For example, type man apm or man bootparamd. If a man page does not exist, try seeing what man pages are associated with that keyword. For example:

apropos accounting

ac(8) - connect time accounting acct(2) - enable or disable process accounting acct(5) - execution accounting file accton(8) - enable/disable system accounting ipfw(4) - IP packet filter and traffic accounting pac(8) - printer/plotter accounting information pam_lastlog(8) - login accounting PAM module

sa(8) - print system accounting statistics



System Manager

This section describes the various tasks that can be performed using the graphical System Manager utility. System Manager can be accessed from Control Panel → System Manager or by typing pc-sysmanager. You will be prompted to input your password.

General Tab

The "General" tab, shown in Figure 8.8a, displays the following system information:

  • the version of PC-BSD®
Figure 8.8a: General Tab of System Manager Utility
  • the version of the underlying FreeBSD base
  • the CPU type and speed
  • the amount of physical memory

The "Generate" button can be used to create a report that includes the following items:

  • the output of the dmesg command, which shows messages from the kernel
  • the last few lines of the /var/log/messages log file
  • the output of the pciconf -lv command, which lists all the devices that were found when the system booted
  • your X configuration file, which shows your display settings
  • your /etc/rc.conf file, which shows your startup settings
  • your /boot/loader.conf file, which shows which drivers are loaded at boot time
  • the output of the command df -m, which shows your amount of free disk space
  • a listing from the top command, which shows the currently running processes

When you click the "Generate" button, you will be prompted to input the name and location of the text file that will be created. Since it is a text file, you can view its contents in any text editor. When troubleshooting your system, this file is handy to include when reporting a bug.

Tasks Tab

During the installation of PC-BSD® you had an opportunity to install FreeBSD source and ports. If you did not and wish to do so after installation, use the "Tasks" tab of System Manager, shown in Figure 8.8b.

Figure 8.8b: Tasks Tab of the System Manager Utility

This tab provides a graphical interface for installing system source (using svn) or the ports tree (using portsnap).

If you click the "Fetch System Source" button, a progress screen will indicate that sources are being downloaded to /usr/src/. Once the download is complete, a "Finished!" message will appear and you can click the "Close" button to exit this screen.

If you click the “Fetch Ports Tree” button, a message will indicate that ports are being fetched and will indicate when this is complete by adding a “Finished!” message to the lower left corner of the message. Ports will be installed to /usr/ports/.

Misc Tab

Figure 8.8c: Misc Tab of the System Manager Utility

The "Misc" tab of System Manager is seen in Figure 8.8c.

This tab contains a checkbox to "Force IBUS keyboard input". Check this box if you wish to to input Chinese, Japanese, Korean or Indic characters using a Latin keyboard.



User Manager

The PC-BSD® User Manager utility allows you to easily add and delete users and groups, as well as change a user's or the root user's password. To access this utility, go to Control Panel → User Manager or type pc-su pc-usermanager. You will need to input your password in order to access this utility.


Figure 8.9a: Viewing User Accounts in User Manager

Managing User Accounts

In the example shown in Figure 8.9a, the system has two user accounts. The dru account has the ability to become the superuser as the "Can administrate system" checkbox is checked.

If you click the "Remove" button for a highlighted user, a pop-up menu will ask if you would like to also delete the user's home directory (along with all of their files). If you click "No", the user will still be deleted but their home directory will remain. If you have only created one user account, the "Remove" button will be greyed out as you need at least one user to be able to login to the PC-BSD® system.

NOTE: While a removed user will no longer be listed, the user account will not actually be deleted until you click the "Apply" button. A pop-up message will indicate that you have pending changes if you close User Manager without clicking "Apply". If you change your mind, click "No" and the user account will not be deleted; otherwise, click "Yes" and the user will be deleted and User Manager will close.

The password for any user can be changed by first highlighting the user name then clicking the "Change Password" button. You will not be prompted for the old password in order to reset a user's password; this can be handy if a user has forgotten their password and can no longer log into the PC-BSD® system. If you click the "Change Admin Password" button, you can change the root user's password.

DANGER! Do not change the user's password if you checked the “Encrypt user files” box in either the Create a User screen or by clicking the “Add” button within User Manager. The password is associated with the user's encryption key, meaning that the contents of the user's home directory will become permanently inaccessible if the password is changed. A future version of PC-BSD® will add a utility to make it easy to change the password for a user with an encrypted home directory.

If you click the "Advanced View" button, this screen will change to show all of the accounts on the system, not just the user accounts that you created. An example is seen in Figure 8.9b.

Figure 8.9b: Viewing All Accounts and Their Details

The accounts that you did not create are known as system accounts and are needed by the operating system or installed applications. You should not delete any accounts that you did not create yourself as doing so may cause a previously working application to stop working. "Advanced View" provides additional information associated with each account, such as the user ID number, full name (description), home directory, default shell, and primary group. System accounts usually have a shell of nologin for security reasons, meaning that an attacker cannot try to login to the system using that account name.

Figure 8.9c shows the add user account creation screen that opens when you click the "Add" button.

NOTE: If you click the "Add" button while in "Simple View", you will only be prompted to enter the username, full name, password, and to optionally encrypt that user's files.
Figure 8.9c: Creating a New User Account

This screen is used to input the following information when adding a new user or system account:

Full Name: this field provides a description of the account and can contain spaces. If it is a user account, use the person's first and last name. If it is a system account, input a description to remind you which application uses the account.

Username: the name the user will use when they log in to the system; it is case sensitive and can not contain any spaces. If you are creating a system account needed by an application, use the name provided by the application's installation instructions. If the name that you choose already exists as an account, it will be highlighted in red and the utility will prompt you to use another name.

Home Directory: leave this field empty for a user account as the system will automatically create a ZFS dataset for the user's home directory under /usr/home/username. However, if you are creating a system account it is important to override this default by typing in /var/empty or /nonexistent unless the application's installation instructions specify that the account needs a specific home directory.

Shell: this drop-down menu contains the shells that are available to users when they are at a command prompt. You can either keep the default or select a shell which the user prefers.

Primary Group: if you leave the default button of "New Group" selected, a group will be created with the same name as the user. This is usually what you want unless you are creating a system account and the installation instructions specify a different group name. Note that the drop-down menu for specifying a group name will only show existing groups, but you can quickly create a group using the "Groups" tab.

Password: the password is case-sensitive and needs to be confirmed.

Encrypt Files: if this box is selected, the user's home directory will automatically be encrypted with PEFS[89]. When the user logs in, the contents of their home directory are automatically decrypted after they enter their password. When they logout, the contents of their home directory are automatically encrypted and will appear as gibberish to other users who do not know the password. For this reason, it is important to select a good password that the user will not forget. At this time, there is no easy mechanism for changing the user's password if their home directory is encrypted. A future version of PC-BSD® will add a utility to allow the user to manage their password and encryption key.

Once you have made your selections, press the "Ok" button to create the account.

Managing Groups

If you click the "Groups" tab, you can view all of the groups on the system, as seen in Figure 8.9d.

Figure 8.9d: Managing Groups Using User Manager

This screen has 3 columns:

Groups: shows all of the groups on the system.

Available: shows all of the system and user accounts on the system in alphabetical order.

Members: indicates if the highlighted group contains any user accounts.

To add an account to a group, highlight the group name in the first column. Then, highlight the account name in the "Available" column. Click the right arrow and the selected account will appear in the "Members" column. You should only add user accounts to groups that you create yourself or when an application's installation instructions indicate that an account needs to be added to a group.

If you click the "Add" button, a pop-up menu will prompt you for the name of the new group. Once you press "OK", the group will be added to the "Groups" column.

If you click the "Remove" button, the highlighted group will automatically be deleted after you press the "Apply" button, so be sure to do this with care. Again, do not remove any groups that you did not create yourself or applications that used to work may stop working.



Bluetooth Manager

Bluetooth Manager can be used to configure Bluetooth device pairing (authentication) and provides a graphical front-end to support FreeBSD's hcsecd(8)[180] daemon which controls the link keys and PIN codes used by Bluetooth pairing.

Figure 8.10a: New Device Detected in Bluetooth Manager
Figure 8.10b: Configure Bluetooth Pairing

FreeBSD supports all Bluetooth USB dongle devices that conform with Bluetooth specification v1.1. More information about FreeBSD's Bluetooth implementation can be found in the Bluetooth section of the FreeBSD Handbook[181].

To launch Bluetooth Manager, either click its icon in Control Panel or type pc-su pc-bluetoothmanager. You will be prompted for your password. If you plug in in a Bluetooth USB dongle device and click on the "New Devices" tab, it should be displayed as it appears in Figure 8.10a. If the device is not found, a message in the lower half of the screen will prompt you to put the device in discovery mode and then to rescan by clicking the "Scan" button.

If the device, such as a cell phone, requires a PIN key in order to access a service, use the "Saved Devices" tab to view and modify the pairing configuration. In the example shown in Figure 8.10b, the first three entries (Default, Dummy, and Dummy) are three FreeBSD sample entries and the fourth entry is for the inserted device. The sample entries are included as they provide examples of valid link keys and PIN codes. You can remove any entry by highlighting it and clicking the "Remove Device" button.

To modify an existing configuration, highlight the device and click the "Configure" button. In the screen shown in Figure 8.10c, input the PIN code required by the provider. The system will automatically generate the link key for you.

Figure 8.10c: Input the PIN Code

If you wish to add the Bluetooth Manager to the system tray, type pc-su pc-bluetoothtray and input your password. The Bluetooth tray icon will only automatically appear in the system tray if the USB dongle is plugged in when you log into the system.

Since the developers do not have access to every possible Bluetooth device, it is possible that your device will not be recognized. If this is the case, please take the time to report a bug so that the developers can work with you to fix the issue.



Mount Tray

The Mount Tray application is used to facilitate the mounting and unmounting of filesystems and USB storage devices. It is included in the system tray, meaning that in can be used within any window manager that provides a system tray. If you remove the icon from the system tray, you can re-add it using Control Panel → Mount Tray or by opening an xterm and then typing pc-mounttray &.
Figure 8.11a: Mount Tray Example

Mounting USB Drives

To access the contents of a USB drive, insert the USB drive and click the "Mount Tray" icon in the system tray. You should see a screen similar to Figure 8.11a.

In this example, a USB thumb drive was inserted and detected while logged into the KDE desktop. Click the "Mount" button next to the "USB DISK" entry to mount that device. As the device mounts, the "Mount" button will change to an "Eject" button and the contents of the drive will be displayed in the default file manager for the desktop. A list of available file managers can be found on the Files and File Sharing page.

If the internal disk drives are partitioned with other filesystems, these will also appear in Mount Tray. Table 1.4a lists which filesystems are supported by Mount Tray.

When you are finished using the device or filesystem, click that entry's "Eject" button. A pop-up message will indicate that the device has been unmounted and that it is now safe to remove the device.

DANGER! Do NOT physically remove the device without unmounting it first.

Right-click Mount Tray to see the "More Options" menu which allows you to perform the following actions:

  • Open Media Directory: click this if the default file manager does not automatically open. If the desktop does not provide a default file manager, Mount Tray will provide an "open with" dialogue so that you can select the utility to use to browse the contents of the USB device.
  • View Disk Usage: in the example shown in Figure 8.11b, a UFS formatted USB device is mounted at /media/USB-Device. The amount of disk space used by the system hard drive and the USB drive is shown in both GB and as a percentage of available disk space. The mount tray will turn yellow if disk space is over 75% and red if disk space is over 90%.
  • Rescan Devices: click this option if an entry for the USB device does not automatically appear.
  • Load ISO File: used to mount an ISO to a memory disk. When the ISO is unmounted, the memory disk is also detached from the system.
  • Change Settings: as seen in Figure 8.11c, this screen allows you to configure how often Mount Tray checks the disk space used by mounted devices. Leave the checkbox checked if you would like it to automatically check disk space when a disk is mounted.
  • Close Tray: click this option to remove Mount Tray from the system tray.
Figure 8.11b: View Disk Usage Using Mount Tray
Figure 8.11c: Configure Disk Space Check



Sound Configuration

A "Sound Configuration" icon is available which automatically determines which audio devices are available and provides a button to play a test sound. To access this utility, use Control Panel → Sound Configuration or type pc-soundconfig from within an xterm.
Figure 8.12a: Sound Configuration Utility

An example of the "Sound Configuration" screen is shown in Figure 8.12a.

To determine which audio devices are available, click the drop-down menu. In the example shown in Figure 8.12b, this system has four available sound devices with the FreeBSD device names pcm0 to pcm3. The default device is the Conexant CX20590 on pcm2.

To change the default audio device, select the desired device from the drop-down menu and test that it works by clicking the "Test sound" button. To make the change permanent, click the "Apply" button.

If you connect a USB headset, PC-BSD® will detect the new device and will automatically change the audio device to the USB input. At this time, if you insert a headset into an audio jack, the system will not detect the new input so you will have to manually change the default device using "Sound Configuration".
Figure 8.12b: Selecting the Audio Device

Troubleshooting Sound

If you are unable to get sound working using the sound configuration utility, you can try using mixer from the command line. As your regular user, type mixer to see your current settings:

mixer

Mixer vol is currently set to 0:0 Mixer pcm is currently set to 100:100 Mixer mic is currently set to 50:50 Mixer mix is currently set to 60:60 Mixer rec is currently set to 75:75 Mixer igain is currently set to 100:100

Mixer ogain is currently set to 100:100

If any of these settings are set to 0, set them to a higher value, by specifying the name of the mixer setting and a percentage value up to 100:

mixer vol 100 Setting the mixer vol from 0:0 to 100:100.

You can make that change permanent by creating a file named .xprofile in your home directory that contains the corrected mixer setting.

If you only get one or two mixer settings instead of the example output shown above, you need to change the default mixer channel. As the superuser, try this command:

sysctl -w hw.snd.default_unit=1

To see if that changed to the correct channel, type mixer again. If you still only have one or two mixer settings, try setting the sysctl value to 2, and if necessary, to 3.

Once you have all of the mixer settings and none are set to 0, your sound should work. If it still doesn't, these resources may help you to pinpoint the problem:

If you still have problems with sound, see the section on Finding Help to determine which help resources are available. When reporting your problem, include your version of PC-BSD® and the name of your sound card.



Display

Control Panel → Display can be used to configure the system to run the display wizard the next time the system boots. This allows you to reconfigure your video driver and display settings.

If you click this icon in Control Panel, you will receive the message shown in Figure 8.13a.

Figure 8.13a: Display Wizard Will Run at Next Boot

Select “Yes” which will prompt for your password. You should then save your work and reboot the system.

Alternately, you can use the boot menu to start the display wizard. As soon as the system starts to boot, press ESC to access the GRUB boot menu. Unless you are dual booting or have configured boot environments, there will be one entry named "PC-BSD (default) in the boot menu. Press enter and select "Run the Display Wizard" from the menu.

Regardless of whether you started the Display Wizard from Control Panel or from the boot menu, it will finish booting the system and then prompt you to confirm the resolution if it finds an optimal one. To configure a different resolution, click “No” to access the display wizard, shown in Figure 8.13b.
Figure 8.13b: Display Settings Wizard

This screen can be used to select the desired screen resolution, color depth, and video driver. If you select the "vesa" driver, it will always work but will provide sub-optimal performance. Click on the drop-down menu to select the driver that most closely matches your video card name.

WARNING If you have an NVIDIA card, double-check that the NVIDIA driver is installed in Control Panel → Package Manager → Hardware-Drivers and install it if it is not already installed.

You can also use the drop-down menus to change the screen resolution and color depth values. If the value you desire is not listed, it may be that the selected driver does not support that resolution or depth.

Advanced users can select their monitor's horizontal sync and vertical refresh rate in the "Advanced" tab, seen in Figure 8.13c:

Figure 8.13c: Advanced Tab of Display Settings

Use caution and refer to your monitor's documentation if you make any changes here. If you are not sure what you are doing, leave the default values as-is.

If your computer is connected to two monitors, check the box "Enable Dual-Head support".

When you are finished, click the "Apply" button for your settings to be tested. If anything goes wrong during testing, you should be taken back to the "Display Settings" screen so that you can try another setting. Once you are satisfied with the settings, click "Yes" when prompted to accept them.

Desktop Effects, Compiz, and Compositing

To prevent problems with video cards that do not support them, desktop effects (used by KDE) and compiz or compositing (used by other window managers) are disabled by default. You can change this default if your video card supports desktop effects.

To enable desktop effects while logged into KDE, click Control PanelSystem SettingsDesktop Effects to access the configuration screen shown in Figure 8.13d.

Figure 8.13d: Enabling Desktop Effects in KDE

Check the box "Enable desktop effects at startup". You can use the "All Effects" tab to get more information about each possible effect and to enable the effects that interest you.

If XFCE is installed, you can enable compositing from any logged in desktop. Go to Control Panel ➜ Window Manager Tweaks ➜ Compositor. If Window Manager Tweaks does not appear in the Control Panel menu, use the desktop selector drop-down menu to select "All" or "XFCE".

In the screen shown in Figure 8.13e, check the "Enable display compositing" box to enable the compositing options.

Figure 8.13e: Enabling Compositing in XFCE

If you do not use KDE or XFCE, install Compiz[184] instead using Control PanelPackage ManagerMiscCompiz. Once installed, you can configure Compiz by clicking SystemPreferencesCompizConfig Settings Manager while logged into GNOME or by typing ccsm from any desktop. This will open the screen shown in Figure 8.13f.

Figure 8.13f: Configuring Compiz

Troubleshooting

Until TTM is ported to PC-BSD®, ATI/Radeon video cards will not be fully supported. If the screen goes blank or otherwise does not work when you select the HD version of the driver, selecting the non-HD version should allow you to use the card. Radeon HD5xxx and higher GPUs have no support for acceleration, 2D or 3D. At this time, these video cards can only use the Vesa driver.

If you are having problems with your display settings and would like to manually edit /etc/X11/xorg.conf or run Xorg --config, first tell the PC-BSD® system to not automatically start X. You can temporarily stop your current X session and prevent additional sessions from starting by typing this command as the superuser:

/usr/local/etc/rc.d/gdm stop

This will drop you down to a console where you can try the instructions in the FreeBSD Handbook[185] to manually configure and test Xorg. Once you have a configuration that works for you, save it to /etc/X11/xorg.conf, and restart gdm to test the configuration:

/usr/local/etc/rc.d/gdm start

If your graphics white-out after a suspend or resume, try running this command as the superuser:

sysctl hw.acpi.reset_video=1

If that fixes the problem, carefully add this line to /etc/sysctl.conf:

hw.acpi.reset_video=1

If the monitor goes blank and does not come back, try running this command as your regular user account:

xset -dpms

If that fixes the problem, add that line to the .xprofile file in your home directory.



Printing

Like many open source operating systems, PC-BSD® uses the Common Unix Printing System (CUPS[186]) to manage printing. Control Panel provides a graphical front-end for adding and managing printers.

While the graphical utility is easy to use, it may or may not automatically detect your printer depending upon how well your printer is supported by an open source print driver. This section will walk you through a sample configuration for a HP Officejet 4500 printer. Your printer may "just work", allowing you to breeze through the configuration screens. If your printer configuration does not work, read this section more closely for hints on how to locate the correct driver for your printer.

Researching your Printer

Before configuring your printer, it is worth the time to see if a print driver exists for your particular model, and if so, which driver is recommended. If you are planning to purchase a printer, this is definitely good information to know beforehand. You can look up the vendor and model of the printer in the Open Printing Database[187] which will indicate if the model is supported and if there are any known caveats with the print driver.

Figure 8.14a shows a search for our example printer. There are two models in this series and this particular hardware supports wireless.

Figure 8.14a: Using Open Printing Database to Locate a Driver

Once the model is selected, click on the "Show this printer" button to see the results, as demonstrated in Figure 8.14b.

Figure 8.14b: Driver Recommendation from Open Printing Database

For this model, the HPLIP driver is recommended. In PC-BSD®, the HPLIP driver is available as an optional system component. You can see if the driver is installed, and install it if it is not, using Control PanelPackage ManagerHardware-Drivers as seen in Figure 8.14c.

Figure 8.14c: Installing the HPLIP Driver

Adding a Printer

Once you know that your printer is supported, make sure that the printer is plugged into your computer or, if the printer is a network printer, that both your computer and the printer are connected to the network. Then, go to Control Panel → Printing or type pc-su system-config-printer. Input your password to see a window similar to Figure 8.14d.

Figure 8.14d: Printer Configuration Utility

To add a new printer, click the +Add button. The printing utility will pause for a few seconds as as the wizard searches to see if any printers are connected to your computer or network. When it is finished, you should see a screen similar to Figure 8.14e.

Figure 8.14e: Select a Print Device

In this example, the wizard has found this printer and highlighted the entry for the HP OfficeJet 4500. To also install the fax capability, instead select the driver which includes “HP Fax”. The wizard should find any supported printer that is attached to the computer or network and list it as the highlighted entry in the "Devices" frame. If it does not automatically find your printer, read the section Manually Adding a Driver.

After making your selection and clicking "Forward", you will see a screen similar to the one shown in Figure 8.14f.

Figure 8.14f: Select the Manufacturer

Press forward to select the model, as seen in the example in Figure 8.14g.

Figure 8.14g: Select the Driver

The recommended driver should be selected for you, so click Forward to access the screen shown in Figure 8.14h.

Figure 8.14h: Describe Printer Screen

Since the configuration wizard found the printer in the previous screens, the "Describe Printer" screen automatically fills out the printer model series, a description, and the hostname of your computer, if the printer is locally attached, or the hostname of the network printer. If you wish, you can change the printer's name or description. Once you click the "Apply" button, the wizard will ask if you would like to print a test page. Ensure the printer has paper and click "Yes" to print the test page. If you can not print a successful test page, see the Printer Troubleshooting section.

Once the printer is created, a screen will open where you can set the properties of the printer. Our sample printer's properties screen is shown in Figure 8.14i:

Figure 8.14i: Viewing the Settings of the Newly Created Printer

You may wish to take a few minutes to review the settings in "Policies", "Access Control", "Printer Options", and "Job Options" tabs as these allow you to configure options such as print banners, permissions, the default paper size, and double-sided printing. The available settings will vary, depending upon the capabilities of the print driver.

Manually Adding a Driver

If the print configuration wizard does not automatically list your printer, double-check that it is supported as described in the Researching your Printer section and that HPLIP is installed if it is a HP printer. Also check that the printer is plugged in and powered on.

You can also try to manually add your printer. In the "Select Device" screen (Figure 8.14e) you will need to highlight and configure the type of connection to the printer:

USB: this entry will only appear if a printer is plugged into a USB port and the number of entries will vary depending upon the number of USB ports on the system. If there are multiple USB entries, highlight the one that represents the USB port your printer is plugged into.

Other: this option allows you to manually type in the URI to the printer. A list of possible URIs is available on the cups site[188].

AppSocket/HP JetDirect: select this option if you are connecting to an HP network printer. You will need to input the IP address of the printer in the "Host" field. Only change the port number if the printer is using a port other than the default of 9100.

IPP: select this option if you are connecting to a printer cabled to another computer (typically running a Microsoft operating system) that is sharing the printer using IPP. You will need to input the IP address of the printer in the "Host" field and the name of the print queue. You can then click the "Verify" button to ensure that you can connect to the print queue.

LPD/LPR: select this option if you are connecting to a printer which is cabled to a Unix computer that is using LPD to share the printer. You will need to select the hostname and queue name from the drop-down menus.

The screen shown in 8.14f provides three options for installing the driver:

  1. Select printer from database: if you click the “Forward” button but the recommended driver is not available in the screen shown in Figure 8.14g, click the “Back” button and try option 2 or 3.
  2. Provide PPD file: a PostScript Printer Description (PPD) is a driver created by the manufacturer that ends in a .ppd extension. Sometimes the file will end with a .ppd.gz extension, indicating that it has been compressed with gzip. If the driver you need was not automatically found, see if there is a PPD file on the driver CD that came with the printer or if one is available for download from the manufacturer's website. If you find a PPD, click "(None)", shown in Figure 8.14j, to browse to the location of that file. Then, click "Forward" to continue with the printer configuration.
  3. Search for a printer driver to download: if you know the name of the driver that you are looking for, try typing its name or number into the "Search" box. If found, it will display in the "Printer" model drop-down menu.
Figure 8.14j: Selecting a PPD

Printer Troubleshooting

Here are some solutions to common printing problems:

  • A test page prints but it is all garbled: this typically means that you are using the wrong driver. If your specific model was not listed, click the "Change" button in the "Driver Details" section of the "Settings" tab of the printer and try choosing another driver model that is close to your model number. If trial and error does not fix the problem, see if there are any suggestions for your model in the Open Printing database[187]. A web search for the word freebsd followed by the printer model name may also help you to find the correct driver to use.
  • Nothing happens when you try to print: in this case, type tail -f /var/log/cups/error_log in a console and then print a test page. The error messages should appear in the console. If the solution is not obvious from the error messages, try a web search for the error message. If you are still stuck, post the error, the model of your printer, and your version using the PC-BSD® Bug Reporting tool.



Scanner

Control Panel provides an icon for accessing XSane[189], a graphical utility for managing scanners.

Figure 8.15a: XSane Interface

To use your scanner, make sure the device is plugged into the PC-BSD® system and click Control PanelScanner icon, or type xsane from the command line. A pop-up message will indicate that XSane is detecting devices and will prompt you to accept the XSane license if a device is detected. If a device is not detected, search for your device at the list of supported scanners[190].

NOTE: If the scanner is part of an HP All-in-One device, make sure that HPLIP is first installed in Control PanelPackage ManagerHardware-Drivers.

Figure 8.15a shows the XSane interface running on a PC-BSD® system attached to an HP OfficeJet.

The XSane Documentation[191] contains details on how to perform common tasks such as saving an image to a file, photocopying an image, and creating a fax. It also describes all of the icons in the interface and how to use them.

By default, XSane uses the default browser when you click F1 to access its built-in documentation. How to configure the default browser varies by window manager so you may need to do an Internet search if you need to set that configuration setting and can not find it.



Network Configuration

During installation, PC-BSD® configures your Ethernet interfaces to use DHCP and provides a post-install configuration screen to configure your wireless connection. In most cases, this means that your connected interfaces should "just work" whenever you use your PC-BSD® system.

For desktops that provide a system tray, a wireless configuration icon will appear if PC-BSD® detects a supported wireless card. If you hover over the wireless icon, shown in Figure 8.16a, it will indicate if the interface is associated and provide information regarding the IP address, IPv6 address, SSID, connection strength, connection speed, MAC address, and type of wireless device.

Figure 8.16a: Wireless Information in System Tray

If you right-click the wireless icon, you will see a list of detected wireless networks. Simply click the name of a network to associate with it. The right-click menu also provides options to configure the wireless device, start the Network Manager, restart the network (useful if you need to renew your DHCP address), and to close the Network Monitor so that the icon no longer shows in the system tray. If you have multiple wireless devices, each will have its own icon in the system tray. If you do not use one of the devices, click Close the Network Monitor to remove it from the tray.

To view or manually configure all of your network interfaces click Control Panel → Network Configuration or type pc-su pc-netmanager. If a new device has been inserted (e.g. a USB wireless interface), a pop-up message will open when you start Network Configuration, indicate the name of the new device, and ask if you would like to enable it. Click Yes and the new device will be displayed with the list of network interfaces that PC-BSD® recognizes. In the example seen in Figure 8.16b, the system has one Realtek Ethernet interface that uses the em driver and a wireless interface that uses the wlan driver.

Figure 8.16b: Network Configuration Utility

The rest of this section describes each tab of the Network Configuration utility and demonstrate how to view and configure the network settings for both Ethernet and wireless devices. It will then present some common troubleshooting scenarios, known issues, and suggestions for when a device does not have a built-in driver.

Devices: Ethernet Adapters

If you highlight an Ethernet interface in the Devices tab and either click the Configure button or double-click the interface name, you will see the screen shown in Figure 8.16c:

Figure 8.16c: Network Settings for an Ethernet Interface

There are two ways to configure an Ethernet interface:

  1. Use DHCP: this method assumes that your Internet provider or network assigns your addressing information automatically using the DHCP protocol. Most networks are already setup to do this. This method is recommended as it should "just work".
  2. Manually type in the IP addressing information: this method requires you to understand the basics of TCP/IP addressing or to know which IP address you should be using on your network. If you do not know which IP address or subnet mask to use, you will have to ask your Internet provider or network administrator.

By default, PC-BSD® will attempt to obtain an address from a DHCP server. If you wish to manually type in your IP address, check the box "Assign static IP address". Type in the IP address, using the right arrow key or the mouse to move between octets. Then, double-check that the subnet mask (Netmask) is the correct value and change it if it is not.

If the Ethernet network uses 802.1x authentication, check the box "Enable WPA authentication" which will enable the "Configure WPA" button. Click this button to select the network and to input the authentication values required by the network.

By default, the "Disable this network device" box is unchecked. If you check this checkbox, PC-BSD® will immediately stop the interface from using the network. The interface will remain inactive until this checkbox is unchecked.

The "Advanced" tab, seen in Figure 8.16d, allows advanced users to change their MAC address[192] and to use DHCP to automatically obtain an IPv6 address[193]. Both boxes should remain checked unless you are an advanced user who has a reason to change the default MAC or IPv6 address and you understand how to input an appropriate replacement address.

Figure 8.16d: Advanced Tab of an Ethernet Interface's Network Settings

The "Info" tab, seen in Figure 8.16e, will display the current network address settings and some traffic statistics.

Figure 8.16e: Info Tab of an Ethernet Interface's Network Settings

If you make any changes within any of the tabs, click the "Apply" button to activate them. Click the "OK" button when you are finished to go back to the main Network Configuration window.

You can repeat this procedure for each network interface that you wish to view or configure.

Devices: Wireless Adapters

If your wireless interface does not automatically associate with a wireless network, you probably need to configure a wireless profile that contains the security settings required by the wireless network. Double-click the wireless icon in the system tray or highlight the wireless interface displayed in the "Devices" tab of Network Configuration and click the "Configure" button. Figure 8.16f demonstrates that this system's wireless interface is currently not associated with any wireless networks as none are listed in the "Configured Network Profiles" section:

Figure 8.16f: Wireless Configuration Window of Network Configuration Utility

To associate with a wireless network, click the "Scan" button to receive the list of possible wireless networks to connect to. Highlight the network you wish to associate with and click the "Add Selected" button. If the network requires authentication, a pop-up window will prompt you for the authentication details. Input the values required by the network then click the "Close" button. PC-BSD® will add an entry for the network in the "Configured Network Profiles" section.

If the network is hidden, click the Add Hidden button, input the name of the network in the pop-up window, and click “OK”.

If you add multiple networks, use the arrow keys to place them in the desired connection order. PC-BSD® will try to connect to the first profile in the list and will move down the list in order if it is unable to connect. When finished, click the "Apply" button. A pop-up message will indicate that PC-BSD® is restarting the network. If all went well, there should be an IP address and status of "associated" when you hover over the wireless icon in the system tray. If this is not the case, double-check for typos in your configuration values and read the section on Troubleshooting Network Settings.

PC-BSD® supports the types of authentication shown in Figure 8.16g. You can access this screen (and change your authentication settings) by highlighting an entry in the "Configured Network Profiles" section and clicking the "Edit" button.

Figure 8.16g: Configuring Wireless Authentication Settings

This screen allows you to configure the following types of wireless security:

  • Disabled: if the network is open, no additional configuration is required.
  • WEP: this type of network can be configured to use either a hex or a plaintext key. If you click WEP then the "Configure" button, you will see the screen shown in Figure 8.16h. Type the key into both network key boxes. If the key is complex, check the Show Key box to make sure that the passwords are correct and that they match. Uncheck this box when you are finished to replace the characters in the key with the * symbol. A wireless access point that uses WEP can store up to 4 keys; the number in the key index indicates which key you wish to use.
  • WPA Personal: this type of network uses a plaintext key. If you click WPA Personal then the Configure button, you will see the screen shown in Figure 8.16i. Type in the key twice to verify it. If the key is complex, you can check the Show Key box to make sure the passwords match.
  • WPA Enterprise: if you click WPA Enterprise then the Configure button, you will see the screen shown in Figure 8.16j. Select the authentication method (EAP-TLS, EAP-TTLS, or EAP-PEAP); input the EAP identity; browse for the CA certificate, client certificate and private key file; and input and verify the password.
NOTE: If you are unsure which type of encryption is being used, ask the person who setup the wireless router. They should also be able to give you the value of any of the settings seen in these configuration screens.
Figure 8.16h: WEP Security Settings
Figure 8.16i: WPA Personal Security Settings
Figure 8.16j: WPA Enterprise Security Settings

If you wish to disable this wireless interface, check the Disable this wireless device box. This setting can be desirable if you want to temporarily prevent the wireless interface from connecting to untrusted wireless networks.

The Advanced tab, seen in Figure 8.16k, allows you to configure the following:

  • a custom MAC address. This setting is for advanced users and requires the Use hardware default MAC address box to be unchecked.
  • how the interface receives its IP address information. If the network contains a DHCP server, check the Obtain IP automatically (DHCP) box. Otherwise, input the IP address and subnet mask to use on the network.
  • the country code. This setting is not required if you are in North America. For other countries, check the Set Country Code box and select your country from the drop-down menu.
Figure 8.16k: Advanced Tab of a Wireless Interface

The Info tab, seen in Figure 8.16l, shows the current network status and statistics for the wireless interface:

Figure 8.16l: Info Tab of a Wireless Interface

Network Configuration (Advanced)

The Network Configuration (Advanced) tab of the Network Configuration utility is seen in Figure 8.16m. The displayed information is for the currently highlighted interface. If you wish to edit these settings, make sure that the interface that you wish to configure is highlighted in the Devices tab.

Figure 8.16m: Network Configuration (Advanced) tab of the Network Configuration Utility

If the interface receives its IP address information from a DHCP server, this screen allows you to view the received DNS information. If you wish to override the default DNS settings or set them manually, check the Enable Custom DNS box. You can then set the following:

DNS 1: the IP address of the primary DNS server. If you do not know which IP address to use, click the Public servers button to select a public DNS server.

DNS 2: the IP address of the secondary DNS server.

Search Domain: the name of the domain served by the DNS server.

If you wish to change or set the default gateway, check the Enable Custom Gateway box and input the IP address of the default gateway.

The following settings can be modified in the IPv6 section:

Enable IPv6 support: if this box is checked, the specified interface can participate in IPv6 networks.

IPv6 gateway: the IPv6 address of the default gateway used on the IPv6 network.

IPv6 DNS 1: the IPv6 address of the primary DNS server used on the IPv6 network. If you do not know which IP address to use, click the Public servers button to select a public DNS server.

IPv6 DNS 2: the IPv6 address of the secondary DNS server used on the IPv6 network.

The Misc section allows you to configure these options:

System Hostname: the name of your computer. It must be unique on your network.

Enable wireless/wired failover via lagg0 interface: the lagg[194] interface allows you to seamlessly switch between using an Ethernet interface and a wireless interface. If you want this functionality, check this box.

NOTE: Some users experience problems using lagg. If you have problems connecting to a network using an interface that previously worked, uncheck this box and remove any references to "lagg" in your /etc/rc.conf file.

If you make any changes within this window, click the Save button to apply them.

Proxy Settings

The Proxy tab, shown in Figure 8.16n, is used when your network requires you to go through a proxy server in order to access the Internet.

Figure 8.16n: Proxy Settings Configuration

Check the Proxy Configuration check box to activate the settings. The follow settings can be configured in this screen:

Server Address: enter the IP address or hostname of the proxy server.

Port Number: enter the port number used to connect to the proxy server.

Proxy Type: choices are "Basic" (sends the username and password unencrypted to the server) and "Digest" (never transfers the actual password across the network, but instead uses it to encrypt a value sent from the server). Do not select "Digest" unless you know that the proxy server supports it.

Specify a Username/Password: check this box and input the username and password if they are required to connect to the proxy server.

Proxy settings are saved to the /etc/profile and /etc/csh.cshrc files so that they are available to the PC-BSD® utilities as well as any application that uses fetch.

Applications that did not come with the operating system, such as web browsers, may require you to configure proxy support using that application's configuration utility.

If you save any changes to this tab, a pop-up message will warn that you may have to logout and back in in order for the proxy settings to take effect.

Troubleshooting Network Settings

While Ethernet networking usually "just works" on a PC-BSD® system, users sometimes encounter problems, especially when connecting to wireless networks. Sometimes the problem is due to a configuration error; sometimes a driver is buggy or is not yet available. This section is meant to help you pinpoint the problem so that you can either fix it yourself or give the developers the information they need to fix or create the driver.

Useful Files and Commands

When troubleshooting your network configuration, use the following files and commands:

/etc/rc.conf

This file is read when the system boots up. In order for the system to configure an interface at boot time, an entry must exist for it in this file. Entries are automatically created for you during installation for each interface that is active. An entry will be added (if it does not exist) or modified (if it already exists) when you configure an interface using the Network Configuration utility.

Here is an example of the rc.conf entries for an ethernet driver (em0) and a wireless driver (run0):

ifconfig_em0="DHCP"

wlans_run0="wlan0"

ifconfig_wlan0="WPA SYNCDHCP"

When reading through your own file, look for lines that begin with ifconfig. For a wireless interface, also look for lines containing wlans.

NOTE: Unlike Linux interface driver names, FreeBSD/PC-BSD® interface driver names indicate the type of chipset. Each driver name has an associated man page where you can learn which devices use that chipset and if there are any configuration options or limitations for the driver. When reading the man page, do not include the interface number. In the above example, you could read man em and man run.

/etc/wpa_supplicant.conf

This file is used by wireless interfaces and contains the information needed to connect to a WPA network. If this file does not already exist, it is created for you when you enter the "Configuration" screen of a wireless interface.

ifconfig

This command shows the current state of your interfaces. When reading through its output, check that your interface is listed, has a status of "active", and has an IP address. Here is a sample ifconfig output showing the entries for the re0 Ethernet interface and the run0 wireless interface:

re0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500

  options=389b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_UCAST ,WOL_MCAST,WOL_MAGIC>   ether 60:eb:69:0b:dd:4d   inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255   media: Ethernet autoselect (100baseTX <full-duplex>)   status: active run0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 2290   ether 00:25:9c:9f:a2:30   media: IEEE 802.11 Wireless Ethernet autoselect mode 11g   status: associated wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500   ether 00:25:9c:9f:a2:30   media: IEEE 802.11 Wireless Ethernet autoselect (autoselect)   status: no carrier   ssid "" channel 10 (2457 MHz 11g)   country US authmode WPA1+WPA2/802.11i privacy ON deftxkey UNDEF   txpower 0 bmiss 7 scanvalid 60 protmode CTS wme roaming MANUAL

  bintval 0

In this example, the ethernet interface (re0) is active and has an IP address. However, the wireless interface (run0, which is associated with wlan0) has a status of "no carrier" and does not have an IP address. In other words, it has not yet successfully connected to the wireless network.

dmesg

This command lists the hardware that was probed during boot time and will indicate if the associated driver was loaded. If you wish to search the output of this command for specific information, pipe to grep as seen in the following examples:

dmesg | grep Ethernet

re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem 0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8 re0: Ethernet address: 60:eb:69:0b:dd:4d

dmesg | grep re0 re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem 0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8 re0: Using 1 MSI messages re0: Chip rev. 0x28000000 re0: MAC rev. 0x00000000 miibus0: <MII bus> on re0 re0: Ethernet address: 60:eb:69:0b:dd:4d re0: [FILTER] re0: link state changed to DOWN re0: link state changed to UP

dmesg | grep run0 run0: <1.0> on usbus3 run0: MAC/BBP RT3070 (rev 0x0201), RF RT2020 (MIMO 1T1R), address 00:25:9c:9f:a2:30

run0: firmware RT2870 loaded

pciconf

If your interface does not show up in ifconfig or dmesg, it is possible that a driver for this card is not provided with the operating system. If the interface is built into the motherboard of the computer, you can use the pciconf command to find out the type of card. Here is an example:

pciconf -lv | grep Ethernet

device = 'Gigabit Ethernet NIC(NDIS 6.0) (RTL8168/8111/8111c)'

pciconf -lv | grep wireless

device = 'Realtek RTL8191SE wireless LAN 802.11N PCI-E NIC (RTL8191SE ?)'

In this example, there is a built-in Ethernet device that uses a driver that supports the RTL8168/8111/8111c chipsets. As we saw earlier, that driver is re0. The built-in wireless device was also found but the "?" indicates that a driver for the RTL8191SE chipset was not found. A web search for "FreeBSD RTL8191SE" will give an indication of whether a driver exists (perhaps in a version of FreeBSD that has not been released yet) or if a driver is being developed. You can also use a web search to locate a Windows driver and try using the ndisgen command, as described in this PC-BSD®blog post[46], to convert it to a FreeBSD driver.

The FreeBSD Handbook chapter on Wireless Networking[195] provides a good overview of how wireless works and offers some troubleshooting suggestions.

If a Driver Does Not Exist

If a FreeBSD driver does not exist for your wireless card, you may be able to convert a Windows driver to a FreeBSD kernel module using the instructions on the Wireless Testing page. If your chipset is not listed in Table 1 of that page, please add an entry indicating whether or not you were able to successfully convert and use the driver.

If you are still unable to get your network interface to work, create a bug report. When describing your problem, include the following information:

  • the version of PC-BSD® you are using
  • the name of the chipset used by the interface
  • the applicable entries in /etc/rc.conf
  • if you include the /etc/wpa_supplicant.conf for your wireless adapter, sanitize the psk[196] value so you do not tell the world what the password is on your wireless network (e.g. replace the actual password with ***** or something similar)

Known Issues

The bge(4) Ethernet driver has a known issue[197] where the interface is seen but does not respond to networking requests. Carefully adding this line to /boot/loader.conf and rebooting should solve this issue.

hw.pci.enable_msi="0"



Firewall Manager

PC-BSD® uses the PF firewall[9] to protect your system. By default, the firewall is configured to let your system make Internet connections, use the ping utility, and to communicate with other Windows and Unix-like systems using SMB and NFS.

Advanced users who are already familiar with pf will find the default rulebase in /etc/pf.conf. Users who are not familiar with directly editing this file can instead use the Firewall Manager GUI utility to view and modify the existing firewall rules.

NOTE: Typically it is not necessary to change the firewall rules. You should not remove any existing rules unless you fully understand what the rule does. Similarly, you should only add rules if you understand the security implications of doing so, especially if the rule allows connections to your computer.

To access the Firewall Manager, go to Control Panel → Firewall Manager or open an xterm and type pc-su pc-pfmanager. You will be prompted to input your password. Figure 8.17a shows the initial screen when you launch this utility:

Figure 8.17a: Firewall Manager Utility

The "General Settings" tab of this utility allows you to:

  • determine whether or not the firewall starts when the system boots; unless you have a reason to do so and understand the security implications, this box should be so that your system is protected by the firewall
  • start, stop, or restart the firewall: if you add, delete, or modify a firewall rule, restart the firewall for your changes to take effect
  • restore default configuration: this button allows you to return to the original, working configuration should you not like the changes you make to your firewall rules

To view or modify the firewall rules, click on the "Exceptions" tab, seen in Figure 8.17b:

Figure 8.17b: Adding a New Firewall Rule

In this example, the user has clicked on the "Add entry" button to add a new firewall rule. The following information is needed when creating a rule:

  • Service or Port: you can either select the name of the service you wish to allow or block from the drop-down menu or type in the number of the port used by the service. Which you choose does not matter as the firewall will match the name and number for you and display both after you save the rule.
  • Policy: you need to choose whether to allow or block this service/port.
  • Direction: use the drop-down menu to determine whether the policy applies to incoming or outgoing connections. The direction is from the perspective of your computer. Do you want others to connect to your service (incoming) or do you want to connect to the service running on another system (outgoing).
  • Protocol: use the drop-down menu to select whether the service uses the TCP or UDP protocol.
  • Interface: use the drop-down menu to select the interface that will make or receive the connection.

Once you have made your selections, press "Ok" to save the new rule.

NOTE: The new rule will not be used by the firewall until the firewall is restarted by clicking the "Restart" button in the "General" tab.

Test that your new rule(s) work as expected. For example, if you create a rule to allow an SSH connection, try connecting to your PC-BSD® system using SSH to verify that the firewall is now allowing the connection.



Adobe Flash Player preferences

Figure 8.18a: Flash Player Configuration Utility

This utility allows for changes to various configuration settings related to Adobe Flash[198]. Many of the same configurations can be done via right-click within an active flash object in a web browser.

To access the utility shown in Figure 8.18a, use Control Panel → Adobe Flash Player preferences or open an xterm and type flash-player-properties.

The options available in each tab and when to use them are described at the Adobe website:

  • Storage:[199] describes private browsing support and the privacy issues associated with local storage of flash information.
  • Playback:[201] describes how to configure peer-assisted networking to improve bandwidth.
  • Advanced:[202] controls how Flash Player handles browsing data, updates, trusted locations, and protected content.



Life Preserver

The built-in Life Preserver utility was redesigned for 9.2 to take full advantage of ZFS snapshot functionality. This utility now allows you to schedule snapshots of a local ZFS pool and to optionally replicate those snapshots to another system using SSH. This design provides several benefits:

  • a snapshot provides a "point-in-time" image of the ZFS pool. In one way, this is similar to a full system backup as the snapshot contains the information for the entire filesystem. However, it has several advantages over a full backup. Snapshots occur instantaneously, meaning that the filesystem does not need to be unmounted and you can continue to use applications on your system as the snapshot is created. Since snapshots contain the meta-data ZFS uses to access files, the snapshots themselves are small and subsequent snapshots only contain the changes that occurred since the last snapshot was taken. This space efficiency means that you can take snapshots often. Snapshots also provide a convenient way to access previous versions of files as you can simply browse to the point-in-time for the version of the file that you need. Life Preserver makes it easy to configure when snapshots are taken and provides a built-in graphical browser for finding and restoring the files within a snapshot.
  • replication is an efficient way to keep the files on two systems in sync. In the case of Life Preserver, the snapshots taken on the PC-BSD system will be synchronized with their versions stored on the backup server.
  • SSH means that the snapshots will be sent to the backup server oven an encrypted connection, which protects the contents of the snapshots.
  • having a copy of the snapshots on another system makes it possible to restore the pool should your PC-BSD® system become unusable.

If you decide to replicate the snapshots to a backup server, keep the following points in mind when choosing which system to use as the backup server:

  • the backup server must be formatted with the latest version of ZFS, also known as ZFS feature flags or ZFSv5000. Operating systems that support this version of ZFS include PC-BSD® 9.2, FreeBSD 9.2, and FreeNAS 9.1.x.
  • that system must have SSH installed and the SSH service must be running. If the backup server is running PC-BSD, you can start SSH using Service Manager. If that system is running FreeNAS, SSH is already installed. How to configure this service is described in Backing Up to a FreeNAS System. If the system is running FreeBSD, SSH is already installed.
  • if the backup server is running PC-BSD, you will need to open TCP ports 22 (SSH) using Firewall Manager. If the server is running FreeBSD and a firewall has been configured, add rules to open this port in the firewall ruleset. FreeNAS does not run a firewall by default.
Figure 8.19a: Life Preserver Icon in System Tray

Managing Snapshots Using the GUI

An icon to the Life Preserver utility, seen in Figure 8.19a, can be found in the system tray.

To remove the icon from the system tray, right-click it. To re-add it to the tray, go to Control Panel → Life Preserver or type pc-su life-preserver & at the command line. If your desktop manager does not provide a system tray, you will need to instead manage backups from the command line.

To open the screen shown in Figure 8.19b, double-click the Life Preserver icon. Click the "+" button and select the name of the ZFS pool to backup. Unless you configured a custom pool name during installation, it will be tank. This will launch the the "New Life Preserver Wizard", allowing you to configure the backup schedule. Click "Next" to see the screen in Figure 8.19c.

Figure 8.19b: Life Preserver Screen
Figure 8.19c: Snapshot Schedule Screen

This screen is used to schedule how often a snapshot is taken of the system. The default is to perform one snapshot per day at 1:00 AM. You can either change the time that this one daily snapshot occurs or select to take a snapshot once every hour, 30 minutes, 10 minutes or 5 minutes.

After making your selection, press "Next" to see the screen shown in Figure 8.19d.

Figure 8.19d: Snapshot Pruning Screen

This screen schedules how long to keep the created snapshots on the PC-BSD® system. By default, the last 7 days of snapshots are stored. In other words, once a snapshot becomes older than 7 days, it is automatically deleted. You can select to either keep snapshots for so many days or to keep a certain quantity of snapshots.

After making your selection, press "Next" to see the screen shown in Figure 8.19e.

Figure 8.19e: Replication Server Screen

If you wish to keep a copy of the snapshots on another system, this screen is used to indicate which system to send the snapshots to. If you do not have another system available, you can click “Next” and then “Finish” to complete the configuration.

If you do have another system available which is running the same version of ZFS and has SSH enabled, click the "Replicate my data" box, then input the following information. Before entering the information in these fields, you need to first configure the backup system. An example configuration is demonstrated in Backing Up to a FreeNAS System.

  • Host Name: of the remote system that will store your backup. If the backup server is on your local network, the host name must be in your hosts file or in the database of the local DNS server. You may find it easier to instead input the IP address of the backup server as this will eliminate any host name resolution problems.
  • User Name: this user must have permission to log in to the system that will hold the backup. If the account does not already exist, you should create it first on the backup server.
  • SSH Port: port 22, the default port used by SSH is selected for you. You only need to change this if the remote system is using a non-standard port to listen for SSH connections. In that case, use the up/down arrows or type in the port number.
  • Remote Dataset: input the name of an existing ZFS dataset on the backup server. This is where the backups will be stored. To get a list of existing datasets, type zfs list on the remote server. The "NAME" column in the output of that command gives the fullname of each dataset. Type the fullname of the desired dataset into this field. When selecting a dataset, make sure that the selected "User Name" has permission to write to the dataset.

Once you have input the information, click "Next" and then "Finish". Life Preserver will check that it can connect to the backup server and will prompt for the password of "User Name". A second pop-up message will remind you to save the SSH key to a USB stick (as described below) as this key is required should you ever need to perform an operating system restore. It will then add an entry for the backup in the screen shown in Figure 8.19b.

NOTE: If you don't receive the pop-up message asking for the password, check that the firewall on the backup system, or a firewall within the network, is not preventing access to the configured "SSH Port".

Configuration Options

Click the entry for a backup to activate its configuration buttons, as shown in Figure 8.19f.

Figure 8.19f: Life Preserver Entry

These buttons, from left to right, allow you to:

  • Enable backups of a new dataset: this button will be greyed out if you only have one pool and have already scheduled a backup of the pool. Otherwise, it will start the "New Life Preserver Wizard" as described above.
  • Remove selected dataset from automatic backup: if you click this button, a pop-up message will ask if you wish to cancel snapshot creation and replication. If you click "Yes", another pop-up message will ask if you also want to permanently delete all of the snapshots currently stored on the local PC-BSD system.
  • Customize the backup configuration: this will open the screen shown in Figure 8.19g so that you can modify when the backups occur and how long they are stored on the backup server. If you click the "Replication" tab, you will see the screen shown in Figure 8.19h. This allows you to edit the connection information to the backup server. It also adds a "Frequency" option. By default, the backup occurs right after the snapshot is created. You can modify this so that the backup itself occurs at a set time, regardless of when the snapshots are created. For example, if you have configured snapshots to occur every 30 minutes but the replication frequency to occur daily at 2:00 AM, the newly created snapshots won't be copied to the backup server until 2:00 AM.
  • Manage SSH keys: after creating a backup entry, you should immediately generate an SSH key and copy it to a USB stick. To do so, click this button then click "Generate SSH Key". A pop-up message will indicate that the key was successfully generated. Then, insert a FAT32 formatted USB stick and mount it with Mount Tray. Then, click this button again and select "Copy To USB Stick".
  • Make a new snapshot: click this button to create a backup now, instead of waiting for the schedule. You can create a snapshot before making changes to a file, so that you can preserve a copy of the previous version of the file. When creating a snapshot, a pop-up message will prompt you to input a name for the snapshot. Once you do, the "Latest Snapshot" field will show the name of the snapshot (with the date and time added). The snapshot itself happens instantaneously, however the replication of the snapshot to the backup server will take some time, depending upon the speed of the network and the size of the snapshot. The Life Preserver icon will change to indicate whenever a replication is in progress.
  • Browse a snapshot: click this button to browse to the data stored in a snapshot. In the example shown in Figure 8.19i, two test snapshots have been taken: the first was taken on September 10 at 11:02 and the second was taken on September 10 at 11:09. The datasets contained within the ZFS pool are listed and if you hover over a dataset name, such as /usr/home/dru, the available snapshots are listed. If you click a snapshot name, the contents of that dataset at that point in time will be displayed in the "Revert a file" screen. For example, if a file named /usr/home/dru/important.odt was modified at 11:05 and the user wished to access the previous version of that file, they could browse to it in the test-2013-09-10-11-02-23 snapshot as that snapshot was taken before the file was modified. If you double-click a file, it will restore that file to the version it was at the time the snapshot was taken.
  • Revert an entire data subset: use this option with care as it will restore every single file in the selected dataset to the point-in-time when the snapshot was taken. While this can sometimes be handy if you mess things up in a dataset, it will also overwrite all of the files that were modified since that point-in-time.
Figure 8.19g: Changing the Backup Schedule
Figure 8.19h: Changing the Replication Schedule
Figure 8.19i: Browsing Snapshots

Managing Snapshots From the Command Line

The lpreserver command line utility can be used to manage snapshots and replication from the command line of a PC-BSD® or TrueOS® system. This command needs to be run as the superuser. To display its usage, type the command without any arguments:

lpreserver

Life-Preserver --------------------------------- Available commands   cronsnap - Schedule snapshot creation via cron        get - Get list of lpreserver options   listcron - Listing of scheduled snapshots   listsnap - List snapshots of a zpool/dataset     mksnap - Create a ZFS snapshot of a zpool/dataset  replicate - Enable / Disable ZFS replication to a remote system revertsnap - Revert zpool/dataset to a snapshot     rmsnap - Remove a snapshot        set - Set lpreserver options     status - List datasets, along with last snapshot / replication date

     zpool - Manage a zpool by attaching / detaching disks


Each command has its own help text that describes its parameters and provides a usage example. For example, to receive help on how to use the lpreserver cronsnap command, type:

lpreserver help cronsnap

Life-Preserver --------------------------------- Help cronsnap Schedule a ZFS snapshot Usage: For a listing of all scheduled snapshots  # lpreserver listcron  or  To start / stop snapshot scheduling  # lpreserver cronsnap <dataset> <action> <frequency> <numToKeep>  action = start / stop  frequency = daily@XX / hourly / 30min / 10min / 5min                    ^^ Hour to execute  numToKeep = Number of snapshots to keep total Example:  lpreserver cronsnap tank1/usr/home/kris start daily@22 10  or

 lpreserver cronsnap tank1/usr/home/kris stop

Table 8.19a shows the command line equivalents to the graphical options provided by the Life Preserver GUI. Note that some options are only available from the command line.

Table 8.19a: Command Line and GUI Equivalents [tables 23]
Command Line GUI Description
cronsnap Customize the backup configuration ➜ Local Snapshots schedule when snapshots occur and how long to keep them; the "stop" option can be used to disable snapshot creation
get list Life Preserver options
listcron main screen of Life Preserver list which ZFS pools have a scheduled snapshot
listsnap Browse a snapshot list snapshots of specified dataset
mksnap Make a new snapshot create and replicate a new ZFS snapshot; by default, snapshots are recursive, meaning that a snapshot is taken of every dataset within a pool
replicate Customize the backup configuration ➜ Replication used to list, add, and remove backup server; read the help for this command for examples
revertsnap Revert an entire data subset revert dataset to the specified snapshot version
rmsnap Remove selected dataset from automatic backup deletes specified snapshot; by default, all datasets within the snapshot are deleted
set configures Life Preserver options; read help for the list of configurable options
status main screen of Life Preserver lists the last snapshot name and replication status
zpool used to attach/detach drives from the pool; read help for examples

Mirroring the System to a Local Disk

In addition to replicating to a remote server, the lpreserver command also provides a method for attaching a new disk drive to an existing ZFS pool, and live-mirroring all data to that disk as data changes on the pool. The attached disk drive can be another internal disk or an external USB disk. When the new disk is attached for the first time, it will be erased and used solely as a mirror of the existing system drive. In addition, it will be made bootable, allowing you to boot from and use the new disk should the primary disk fail. In order to use this feature you will need the following:

  • an internal or external disk drive that is the same size or larger than the existing system disk.
  • since the disk will be formatted, it must be either blank or not have any data that you wish to keep intact.
  • in order to boot from the disk should the primary disk fail, the system must support booting from the new disk. For example, if you are using a USB disk, make sure that the BIOS is able to boot from a USB disk.

The superuser can setup the new disk using the following command. Replace tank1 with the name of your ZFS pool and /dev/da0 with the name of the disk to format. For example, the first USB disk will be /dev/da0 and the second internal hard disk will be /dev/ad1.

lpreserver zpool attach tank1 /dev/da0

When the disk is first attached, it will be formatted and configured to mirror the existing disk. You can add multiple disks to the pool in this manner, giving any level of redundancy that you require.

Once the disk is attached, it will begin to resilvering. This process mirrors the data from the primary disk to the newly attached disk. This may take a while, depending upon the speed of the disks and system load. Until this is finished you should not reboot the system, or detach the disk. You can monitor the resilvering process by typing zpool status.

To get a listing of the disks in your mirror, run this command, replacing tank1 with the name of the pool:

lpreserver zpool list tank1

If you are using an external drive, there may be occasions where you wish to disconnect the backup drive, such as when using a laptop and going on the road. In order to so this safely, it is recommended that you first offline the external disk using the following command:

lpreserver zpool offline tank1 /dev/da0

Then when you re-connect the drive, you can place it in online mode again using:

lpreserver zpool online tank1 /dev/da0

Sometimes, the disk name will change as a result of being disconnected. The lpreserver zpool list tank1 command can be used to get the proper device ID.

If you wish to permanently remove a disk from the mirror, run the following command. If you decide to re-attach this disk later, a full disk copy will again have to be performed.

lpreserver zpool detach tank1 /dev/da0
Template:Word-note in addition to working with mirrors, the lpreserver zpool command can also be used to manage a RAIDZ configuration, although you will probably not want to use external disks in this case.

Backing Up to a FreeNAS System

FreeNAS®[203] is an open source Networked Attached Storage (NAS) operating system based on FreeBSD. This operating system is designed to be installed onto a USB stick or CF card so that it is kept separate from the storage disk(s) installed on the system. You can download the latest version of FreeNAS® as well as a PDF of its Users Guide from the download page[204] of the FreeNAS® website.

This section demonstrates how to configure FreeNAS® 9.1.1 as the backup server for Life Preserver to replicate to. It assumes that you have already installed this version of FreeNAS® using the installation instructions in the FreeNAS® 9.1.1 Users Guide and are able to access the FreeNAS® system from a web browser.

In order to prepare the FreeNAS® system to store the backups created by Life Preserver, you will need to create a ZFS volume, create and configure the dataset to store the backups, create a user account that has permission to access that dataset, and enable the SSH service.

In the example shown in Figure 8.19j, the system has three 40GB drives and the user has clicked Storage ➜ Volumes ➜ ZFS Volume Manager in order to create the ZFS volume.

Figure 8.19j: Creating a ZFS Volume in FreeNAS® 9.1.1

Input a "Volume Name", drag the slider to select the number of disks, and click the "Add Volume" button. The ZFS Volume Manager will automatically select the optimal layout for both storage capacity and redundancy. In this example, a RAIDZ1 volume named volume1 will be created.

To create the dataset to backup to, click the + next to the entry for the newly created volume, then click "Create ZFS Dataset". In the example shown in Figure 8.19k, the "Dataset Name" is backups. Click the "Add Dataset" button to create the dataset.

Figure 8.19k: Creating a ZFS Dataset in FreeNAS® 9.1.1

To create the user account, go to Account ➜ Users ➜ Add User. In the screen shown in Figure 8.19l, input a "Username" that will match the "User Name" configured in Life Preserver. Under "Home Directory", use the browse button to browse to the location that you made to store the backups. Input a "Full Name", then input and confirm a "Password". When finished, click the "OK" button to create the user.

Figure 8.19l: Creating a User in FreeNAS® 9.1.1

Next, give the user permissions to the dataset by going to Storage ➜ Volumes, click the + next to the name of the volume, click the + next to the name of the dataset, then click "Change Permissions" for the expanded dataset. In the screen shown in Figure 8.19m, change the "Owner(user)" and "Owner(group)" to the user that you created. Click "Change" to save the change.

Figure 8.19m: Setting Permissions in FreeNAS® 9.1.1

Next, click on Shell and type the following command, replacing dru and volume1/backups with the name of the user, volume, and dataset that you created:

zfs allow -u dru create,receive,mount,userprop,destroy,send,hold volume1/backups

Click the x in the upper right corner to close Shell. Then, to enable the SSH service, go to Services ➜ Control Services, shown in Figure 8.19n.

Figure 8.19n: Start SSH in FreeNAS® 9.1.1

Click the red "OFF" button next to SSH to enable that service. Once it turns to a blue "ON", the FreeNAS® system is ready to be used as the backup server.

To finish the configuration, go to the PC-BSD® system. In the Life Preserver screen shown in Figure 8.19e, use the IP address of the FreeNAS® system in the "Host Name" field, the name of the user you created in the "User Name" field, and the name of the dataset you created (in this example it is volume1/backups) in the "Remote Dataset" field.

Restoring the Operating System From a Replicated Life Preserver Backup

If you have replicated the system's snapshots to a backup server, you can use a PC-BSD® installation media to perform an operating system restore or to clone another system. Start the installation as usual until you get to the screen shown in Figure 8.19o.


Figure 8.19o: Selecting to Restore/Clone From Backup

Before you can perform a restore, the network interface must be configured. Click the "network connectivity" icon (second from the left) in order to determine if the network connection was automatically detected. If it was not, configure the network connection before continuing.

Next, click "Restore from Life-Preserver backup" and the "Next" button. This will start the Restore Wizard. Click "Next" to see the screen shown in Figure 8.19p.

Figure 8.19p: Select the Backup Server

Input the IP address of the backup server and the name of the user account used to replicate the snapshots. If the server is listening on a non-standard SSH port, change the "SSH port" number. Click "Next" to see the screen shown in Figure 8.19q.

Figure 8.19q: Select the Authentication Method

If you previously saved the SSH key to a USB stick, insert the stick then press "Next". Otherwise, change the selection to "Use password authentication" and press "Next". The next screen will either read the USB key or prompt for the password, depending upon your selection. The wizard will then attempt a connection to the server. If it succeeds, you will be able to select which backup to restore. After making your selection, the installer will proceed to the Disk Selection Screen shown in Figure 3.4e. After selecting the disk(s), the installer will show Figure 3.4f, but the ZFS datasets will be greyed out as they will be recreated from the backup during the restore. Press "Next" then "Next" to perform the restore.



PC-BSD® Bug Reporting

Beginning with PC-BSD® 9.2, a bug reporting tool is available in Control Panel. This tool can be used to easily send a bug report to the development team responsible for the software which produced the bug.

To access this tool, go to Control Panel → PC-BSD Bug Reporting or type pc-bugreport from the command line. The initial screen for this tool is shown in Figure 8.20a.

Figure 8.20a: PC-BSD® Bug Reporting Utility

Select the software component that most closely matches where the bug occurs. For example, if the bug occurs when using a KDE utility, select "Desktop environment", or if the bug occurs when using an application that was installed using AppCafe®, select "PC-BSD software (pbi)". When in doubt, select "PC-BSD base system".

In the example shown in Figure 8.20b, the user has selected "PC-BSD base system" then "Next".

NOTE: Regardless of the selection, the resulting screen will be similar to 8.20b. The various screens only differ in which bug tracking system or mailing list is used by the development team for that component. If you select "Desktop environment" you will also be asked to indicate which desktop so that the correct information is displayed for that development team. Similarly, if you select "PBI software" you will be asked to select which PBI produces the error.

If the development team has a bug tracker, its URL will be displayed. If you click the "Launch web browser" button, that website will be opened in the default web browser so that you can search for existing bugs and create a new bug if one does not already exist. Note that you will need to register first if this is your first bug and that you must be logged in in order to create a new bug.

If the development team has a mailing list, its email address will be listed. The URL to the mailing list will also be displayed so that you can search its archives and subscribe to the list. Note that you will need to be subscribed to a mailing list before you can report a bug on that list. To report the bug, click the "Compose email" button to open the default mail application. To subscribe to or read the archives of the list, click the "Launch web browser" button.
Figure 8.20b: Reporting a Bug

The three icons in the "Toolbox" section can be used to gather useful information to include in your bug report. If you click the first icon on the left, a pop-up menu allows you to create any of the following:

  • Diagnostic report
  • FreeBSD version (uname -a)
  • dmesg output
  • Xorg version
  • Xorg log

If you click an entry in the menu, the results will be displayed in a window so that you can copy the contents into your bug report.

If you click the second icon, it will generate a PCI devices list. This is useful information if your built-in wireless card is not working.

If you click the third icon, the default snapshot utility for the desktop will open so that you can include a snapshot in your bug report.

Writing Good Bug Reports

While this utility makes it easy to find the correct place to send a bug report, it is still up to you to make sure that your report includes the information that developers need to recreate and eventually fix the bug. The following resources contain useful tips for the various development teams for the bugs you may encounter when using PC-BSD®. Before reporting:

  • a bug about the "PC-BSD base system" or "PC-BSD software (pbi)", read through Report Bugs.



Warden®

Warden® is an easy to use, graphical jail[211] management program.
Figure 8.21b: Initial Warden® Screen
Using Warden®, it is possible to create multiple, isolated virtual instances of FreeBSD which can be used to run services such as Apache, PHP, or MySQL in a secure manner. Each jail is considered to be a unique FreeBSD operating system and whatever happens in that jail will not affect your operating system or other jails running on the PC-BSD® system.

Some of the features in Warden® include the ability to:

  • create three types of jails: a traditional FreeBSD jail for running network services, a (less secure) ports jail for safely installing and running FreeBSD ports/packages from your PC-BSD® system, and a Linux jail for installing Linux
  • set multiple IPv4 and IPv6 addresses per jail
  • quickly install common network server applications on a per-jail basis
  • update installed software on a per-jail basis
  • manage user accounts on a per-jail basis
  • manage ZFS snapshots on a per-jail basis
  • export a jail which can be then be imported into the same or a different jail

Creating a Jail using the GUI Version of Warden®

Warden® can be started by clicking on its icon in Control Panel or by typing pc-su warden gui from the command line. You will be prompted for your password as administrative access is needed to create and manage jails.

The first time you start Warden®, you will be prompted to set the network interface as your jails will not work if the wrong interface is configured. Click Yes to set the interface using the screen shown in Figure 8.21a. You can access this screen at a later time from JailsConfiguration.

Figure 8.21a: Warden® Configuration

This screen allows you to configure the following:

  • Jail Network Interface: all jails created within Warden® share the same physical interface. Use the drop-down menu to select the network interface to be used by the jails.
  • Jail Directory: contains all of the created jails where each jail has its own sub-directory named after its IP address. By default, it is /usr/jails. If you change this directory, make sure the location has sufficient space to hold the jails.
  • Temp Directory: used when exporting and importing jails. Make sure that the directory has sufficient space to create a tar file of the jail and its contents.

Once you click the "Save" button to save your interface configuration, you will be presented with the main Warden® configuration screen, shown in Figure 8.21b.

To create your first jail, click the "+" button or go to FileNew Jail. A jail creation wizard, seen in Figure 8.21c, will launch.

Figure 8.21c: Creating the New Jail

The first screen in the jail creation wizard will prompt you for the following information:

Hostname: you can change the default of "Jailbird" to another value. The hostname must be unique on your network. Use a hostname that reminds you of the type of jail and your reason for creating it.

IPV4 Address: input the IPv4 address to be used by the jail and access its contents. Choose an address on your network that is not already in use by another computer or jail and which will not conflict with the address range assigned by a DHCP server.

IPv6 Address: if you plan to access the jail and its contents using IPv6, check the "IPv6 Address" box and input an IPv6 address that is not already in use by another computer or jail on your network.

When finished, click "Next" to select the type of jail, as shown in Figure 8.21d:

Figure 8.21d: Select the Type of Jail

There are three types of jails supported by Warden®:

Traditional Jail: select this type if you are creating the jail in order to install and run network services. For example, this type of jail is appropriate if you wish to run a web server or a database which is accessible to other systems on a network or over the Internet. This is the most secure type of jail as it is separate from the PC-BSD® host and any other jails that you create using Warden®. By default, FreeBSD's next generation of package management, known as pkgng, and the command line versions of the PC-BSD® utilities are added to a default FreeBSD installation. If you do not plan to use these tools, uncheck the box “Install PKGNG and PC-BSD utilities”. If you have already created a jail template, select the desired operating system version from the “Jail Version” drop-down menu.

Ports Jail: select this type of jail if your intention is to install software using FreeBSD packages and ports and you wish to have access to that software from your PC-BSD® system or if you plan to install any GUI applications within the jail. This type of jail is less secure then a traditional jail as applications are shared between the jail and the PC-BSD® system. This means that you should not use this type of jail to install services that will be available to other machines over a network.

Linux Jail: select this type of jail if you would like to install a Linux operating system within a jail.

The remaining screens will differ depending upon the type of jail that you select.

Traditional or Ports Jail

If you select "Traditional Jail", you will be prompted to set the root password as seen in Figure 8.21e.

Figure 8.21e: Setting the Traditional Jail's Root Password

Input and confirm the password then press "Next" to see the screen shown in Figure 8.21f. If you instead select to create a "Ports Jail", you will go directly to Figure 8.21f.


Figure 8.21f: Select the Jail Options

This screen allows you to install the following options:

Include system source: if you check this box, make sure that /usr/src/ exists on the PC-BSD system as the source is copied to the jail from this location. If it is not installed, use Control Panel → System Manager → Tasks ➜ Fetch System Source to install it.

Include ports tree: if you check this box, the latest version of the ports tree will be downloaded into /usr/ports/ of the jail. This will allow you to compile FreeBSD ports within this jail.

Start jail at system bootup: if this box is checked, the jail will be started (become available) whenever you boot your main system. If the box is not checked, you can manually start the jail whenever you wish to access it using Warden®.

Once you have made your selections, click the "Finish" button to create the jail. Warden® will display a pop-up window containing status messages as it downloads the files it needs and creates and configures the new jail.

Once Warden® is finished creating the jail, a message should appear at the bottom of the pop-up window indicating that the jail has been successfully created. Click the "Close" button to return to the main screen.

Linux Jail

If you select the "Linux Jail" and click "Next", you will be prompted to set the root password as seen in Figure 8.21e. After inputting the password, the wizard will prompt you to select a Linux install script, as seen in Figure 8.21g.

Figure 8.21g: Select the Linux Distribution to Install

The installation script is used to install the specified Linux distribution. At this time, installation scripts for Debian Squeeze and for Gentoo are provided. Scripts for other distros will be added over time.

NOTE: A Linux installation script is simply a shell script which invokes a Linux network installation. In the case of Debian Squeeze, it invokes the debootstrap command.

Once you select the install script, the wizard will ask if you would like to start the jail at boot time as seen in Figure 8.21h.

Figure 8.21h: Linux Jail Options

Click the "Finish" button to begin the Linux installation.

Configuring Existing Jails From the GUI

Once a jail is created, an entry for the jail will be added to the "Installed Jails" box and the tabs within Warden® will become available. Each entry indicates the jail's hostname, whether or not it is currently running, and whether or not any updates are available for the meta-packages installed within the jail. The buttons beneath the "Installed Jails" box can be used to start/stop the highlighted jail, configure the jail, add a new jail, or delete the highlighted jail.

If you highlight a jail and click the configure (wrench) icon, the screen shown in Figure 8.21i will open.

Figure 8.21i: Jail Configuration Options

The Options tab has one checkbox for enabling or disabling VNET/VIMAGE support. This option provides that jail with its own, independent networking stack. This allows the jail to do its own IP broadcasting, which is required by some applications. However, it breaks some other applications. If an application within a jail is having trouble with networking, try changing this option to see if it fixes the issue.

The IPv4 tab is shown in Figure 8.21j.

Figure 8.21j: Jail IPv4 Options

This screen allows you to configure the following:

IPv4 Address: uncheck this box if you do not want the jail to have an IPv4 address.

IPv4 Bridge Address (Requires VNET): if this box is checked, an IP address is input, and the "IPv4 Default Router" box is left unchecked, the bridge address will be used as the default gateway for the jail. If the "IPv4 Default Router" address is also configured, it will be used as the default gateway address and the bridge address will be used as just another address that is configured and reachable. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

IPv4 Default Router: check this box and input an IP address if the jail needs a different default gateway address than that used by the PC-BSD® system. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

The IPv6 tab is shown in Figure 8.21k.

Figure 8.21k: Jail IPv6 Options

This screen allows you to configure the following:

IPv6 Address: check this box if you want the jail to have an IPv6 address.

IPv6 Bridge Address (Requires VNET): if this box is checked, an IPv6 address is input, and the "IPv6 Default Router" box is left unchecked, the bridge address will be used as the default gateway for the jail. If the "IPv6 Default Router" address is also configured, it will be used as the default gateway address and the bridge address will be used as just another address that is configured and reachable. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

IPv6 Default Router: check this box and input an IPv6 address if the jail needs a different default gateway address than that used by the PC-BSD® system. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

The Aliases tab is shown in Figure 8.21l.

Figure 8.21l: Jail Aliases Options

Click the drop-down menu to see all of the options shown in Figure 8.2l. An alias allows you to add additional IP addresses to an interface. Select the type of address you would like to add an alias to, click the Add button, type in the IP address to add and click OK.

The Permissions tab is shown in Figure 8.21m. This screen can be used to easily enable or disable the sysctl values that are available for jails.

Figure 8.21m: Jail Permissions

The rest of this section provides an overview of how to manage jails using the tabs listed in the bottom half of the Warden® interface.

Info Tab

The "Info" tab, as seen in the example in Figure 8.21n, provides an overview of a jail's configuration. If you have created multiple jails, the "Info" tab displays the configuration of the currently highlighted jail.

Figure 8.21n: Info Tab of Warden®

In the example shown in Figure 8.21n, three jails have been created: a traditional jail, a ports jail, and Debian Squeeze has been installed into a Linux jail.

The "Info" tab contains the following information:

  • Jail Type: will indicate if the jail is a Traditional, Ports, or Linux jail.
  • Size on Disk: indicates the amount of space being used by the jail. The jail itself takes up about 300MB of space, source is about 300MB, and ports are about 850MB.
  • Start at boot: a status of "Enabled" indicates that the jail will automatically start when the system reboots. "Disabled" means that you will manually start the jail as needed.
  • Active Connections: will list the number of active connections to the jail (e.g. through ssh or one of the running services).
  • IPs: lists the jail's IP address as well as any configured aliases.
  • Listening on Ports: indicates which ports are currently listening for connections.

You can sort the jail listing by clicking on the "Jail", "Status", or "Updates" header name. The "Updates" column will indicate if a software or system update is available for a jail.

Tools Tab

The "Tools" tab, shown in Figure 8.21o, allows you to manage common configuration tasks within a jail.


WARNING Make sure that the desired jail is highlighted when using the "Tools" tab.
Figure 8.21o: Tools Tab for the Highlighted Jail

This tab provides the following buttons:

  • Package Manager: opens Package Manager in Advanced View so that you can install packages within the specified traditional or ports jail. Software installed using this method will be tracked by Update Manager, meaning that Warden® will be notified when updates are available for the installed software. Since BSD-based packages are not available for Linux jails, this button is not available if a Linux jail is highlighted.
  • User Administrator: opens User Manager so that you can manage the highlighted jail's user accounts and groups. The title bar will indicate that you are "Editing Users for Jail:Jailname". Note that any users and groups that you have created on your PC-BSD® system will not be added to a traditional jail as each traditional jail has its own users and groups. However, a ports jail has access to the users and groups that exist on the PC-BSD® system, yet the users you create on a ports jail will only be available within the ports jail. This button is not available if a Linux jail is highlighted.
  • Service Manager: opens Service Manager so that you can view which services are running in the jail and configure which services should start when the jail is started. Note that this button is not available if a Linux jail is highlighted.
  • Launch Terminal: opens a terminal with the root user logged into the jail. This allows you to administer the jail from the command line. This button will be greyed out if the highlighted jail is not running. You can start a jail by right-clicking its entry and selecting "Start this Jail" from the menu or by clicking the start jail icon (a blue arrow icon below the list of jails).
  • Check for Updates: launches Update Manager to determine if any of the jail's meta-packages have newer versions available. Update Manager will also indicate if system updates are available to be installed into the jail. Note that this button is not available if a Linux jail is highlighted. By default, Update Manager automatically checks for updates every 12 hours to see if there are any system updates or if any of the applications installed using "Package Manager" within a ports or traditional jail have newer versions. If an update is found, the text "Updates available!" will appear in the "Updates" column for that jail.
  • Export Jail: launches a pop-up window prompting you to choose the directory in which to save a backup of the jail (and all of its software, configuration, and files) as a .wdn file. Creating the .wdn file may take some time, especially if you have installed src, ports, or software.

Snapshots Tab

The “Snapshots” tab, shown in Figure 8.21p, is used to create and manage ZFS snapshots within the currently highlighted jail. The ZFS snapshot feature can be used to make point in time filesystem backups of jails. A snapshot is essentially a picture of what the filesystem looked like at that point in time. Snapshots are space efficient in that they take up zero space when created and the snapshot only grows in size as files contained within the snapshot are modified after the snapshot was taken. In other words, ZFS manages the changes between snapshots, providing a way to return to what a file looked like at the time a snapshot was taken.

Since jails share the filesystem used by PC-BSD®, any type of jail, including a Linux jail, can take advantage of this ZFS feature.

Figure 8.21p: Snapshots Tab for the Highlighted Jail

To create a snapshot of the jail, click the "+Add" button. A snapshot indicating the date and time will be added to the slider bar. If you create multiple snapshots at different times, use the slider bar to select a snapshot.

Once you have created a snapshot, the following actions can be used to manage the snapshot. Make sure that the desired snapshot is highlighted in the slider bar before clicking these buttons:

  • Restore: returns the system to what it looked like at the time the snapshot was taken. Think about what you wish to accomplish before using this option as any changes to files that occurred after the snapshot was taken will be lost. Unless you really want to go back to this point in time, this is probably not what you want to do.
  • Mount: if you wish to retrieve some files or directories from a snapshot, use this button. Once mounted, a message will indicate where on the PC-BSD® system the jail's contents have been mounted.
  • Unmount: when you are finished accessing the contents of the mounted snapshot, click this button to unmount the snapshot.
  • Add: use this button to create additional snapshots.
  • Remove: use this button to remove the highlighted snapshot.

This screen also allows you to schedule automatic snapshots. To enable this feature, check the box "Scheduled Snapshots". Use the drop-down menu to set the frequency to daily or hourly. You can also type in or use the arrows to configure the number of days to keep each snapshot.

Right-Click Menu

If you highlight a jail, its right-click menu contains the following options:

  • Start or Stop this Jail: allows you to start a jail (if it is currently not running) or to stop a jail (if it is currently running). You will not be able to access a jail that has not been started. The icon next to the jail will change to indicate the current status.
  • Toggle Autostart: toggles a jail's Autostart between "Disabled" (does not automatically start when the PC-BSD® system is booted) and "Enabled" (will start the jail when the PC-BSD® system is booted). The "Info" tab will be updated to indicate the new "Start at boot" status. Note that toggling autostart will not affect the current running status of the jail (i.e. it does not start or stop the jail right now) as autostart is only used when the system boots.
  • Export jail to .wdn file: allows you to save the jail (and all of its software, configuration, and files) as a .wdn file. This allows you to quickly clone a pre-configured jail to a new jail on either the same or another PC-BSD® system. The exported jail will end with a .wdn extension and the filename will be the IP address of the jail. When exporting a jail, a pop-up window will prompt you to choose the directory in which to store the backup. A progress bar will indicate that the export is in progress. Creating the .wdn file may take some time, especially if you have installed src, ports, or software.


WARNING You should close all network connections to the jail before exporting it as Warden® will need to stop the jail in order to back it up. If your jail is running services (e.g. a webserver), export the jail at a time that will least impact network connections to the jail.
  • Delete Jail: removes the jail and all of its contents from the PC-BSD® system. You will be prompted to confirm this action.

Importing a Jail

The "File" menu can be used to create a new jail, import a jail, create templates, or exit Warden®.

If you click FileImport Jail you will be prompted to browse to the location of a previously created .wdn file. After selecting the file, you will then see the screen shown in Figure 8.21q.

Figure 8.21q: Importing a Jail


If you are creating a new jail on the same system that still has the original jail installed, check the "Change IP Address" box and input an unused IP address for the new jail. Then, check the box "Change Hostname" and input an unused hostname for the new jail. However, if you have deleted the original jail or need to restore that same jail on another computer (for example, there was a hardware failure on the system containing the original jail), you can choose to leave both boxes unchecked and to reuse the same IP address and hostname. Once you press OK, Warden® will recreate the jail with all of the original settings. Whether or not those settings include the original IP address and hostname depends upon your selections.

Using Template Manager

The version of Warden® used in PC-BSD® 9.2 introduces a template manager for creating and managing jail templates. Once created, templates can be used when installing a new jail. A template specifies the version and architecture of FreeBSD to be used as the operating system running in the jail. Templates have been tested from FreeBSD versions 4.1.1 to FreeBSD-CURRENT. Until you create your own templates and specify them during jail creation, the default version and architecture of the operating system used in the jail will be the same as that running on the PC-BSD® system.

To create a template, click File ➜ Template Manager to see the screen shown in Figure 8.21r.

Figure 8.21r: Template Manager

The default icon will indicate the version of TrueOS® used by the underlying PC-BSD® system. To create a new template, click the + button. In the "System Type" drop-down menu select either:

  • TrueOS: adds the command line versions of the PC-BSD® utilities to the FreeBSD base.
  • FreeBSD: uses only the FreeBSD base without any of the PC-BSD® utilities.

Press OK to see the screen shown in Figure 8.21s.

Figure 8.21s: Select the Operating System Version

If desired, change the 9.1 in this example to the release number to use. If you selected FreeBSD as the system type, a list of available release numbers can be found on this FreeBSD webpage[212]. If you selected TrueOS, the list of available release numbers is currently limited to 9.0, 9.1, and 9.2..

Press OK. In the "System Architecture" drop-down menu, select either amd64 (for 64-bit) or i386 (for 32-bit). Press OK and input a nickname for the template. Click OK and the files needed for that version will be downloaded. Once the template is created, it will appear in the Template Manager as seen in the example in Figure 8.21t.

Figure 8.21t: New Template Added

To delete a template, highlight it and click the - button. Note that Warden® will not let you delete a template if any jails exist which are using the template.

To use the template when creating a new jail, click the "Jail Version" drop-down menu shown in Figure 8.21d and select the desired template.

Using the Command Line Version of Warden®

The Warden® GUI is based on a Bourne shell script. This script can be manually run from the command line on a PC-BSD® server or by users who prefer using the command line. Advanced users can also refer to the command line version in their own scripts.

If you type warden at the command line, you will receive a summary of its usage:

warden

Warden version 1.3

--------------------------------- Available commands Type in help <command> for information and usage about that command help - This help file gui - Launch the GUI menu auto - Toggles the autostart flag for a jail bspkgng - BootStrap pkgng and setup TrueOS repo checkup - Check for updates to a jail chroot - Launches chroot into a jail create - Creates a new jail details - Display usage details about a jail delete - Deletes a jail export - Exports a jail to a .wdn file fstab - Start users $EDITOR on jails custom fstab get - Gets options list for a jail import - Imports a jail from a .wdn file list - Lists the installed jails pkgs - Lists the installed packages in a jail pbis - Lists the installed pbi's in a jail set - Sets options for a jail start - Start a jail stop - Stops a jail type - Set the jail type (pbibox|pluginjail|portjail|standard) template - Manage jail templates zfsmksnap - Create a ZFS snapshot of a jail zfslistclone - List clones of jail snapshots zfslistsnap - List snapshots of a jail zfsclonesnap - Clone a jail snapshot zfscronsnap - Schedule snapshot creation via cron zfsrevertsnap - Revert jail to a snapshot zfsrmclone - Remove a clone directory zfsrmsnap - Remove snapshot of a jail


Each command has its own help text that describes its parameters and provides a usage example. For example, to receive help on how to use the warden create command, type:

warden help create

Warden version 1.3

--------------------------------- Help create Creates a new jail, with options for system source, ports and autostarting. Available Flags: -32 (Create 32bit jail on 64bit system) --ipv4 <ip/mask> (Set primary IPv4 address for jail) --ipv6 <ip/mask> (Set primary IPv6 address for jail) --src (Includes /usr/src system source) --ports (Includes the ports tree) --vanilla (Don't install PC-BSD pkgng repo and utilities) --startauto (Start this jail at system boot) --pbibox (Make this a pbi container) --portjail (Make this a portjail) --pluginjail (Make this a pluginjail) --linuxjail <script> (Make this a linux jail and use supplied script for installation) --archive <tar> (Use specified tar file for BSD jail creation) --linuxarchive <tar> (Use specified tar file for Linux jail creation) --version <string> (Use this instead of /etc/version) --template <string> (Specify a jail template to build with) Usage: warden create <JAILNAME> <flags> Example: warden create jailbird --ipv4 192.168.0.25/24 --src --ports --startauto

You do not need superuser access to use the view commands but will for any commands that create or manage a jail. The warden command will display an error message if a command requires superuser access and you currently are not the superuser. On PC-BSD®, you can put pc-su at the beginning of the warden command to be prompted for your password. On a FreeBSD server, you can type su to become superuser, then repeat the warden command.

Creating and Accessing a Jail

Before creating a jail, make sure that the correct interface is specified in /usr/local/etc/warden.conf. In this example, the default interface is set to em0:

# Network Interface for the jails to use NIC: em0

To create a jail, specify a unique IP address and hostname for the jail:

warden create jail1 --ipv4 10.0.0.1 Building new Jail... Please wait... Boot-strapping pkgng <snip install messages> Extracting ports overlay data...DONE Extracting server overlay data...DONE Success! Jail created at /usr/jails/jail1

Before you can access the jail, you will need to start it:

warden start jail1

As the jail starts, the SSH host keys will be generated and sshd will start. At this point, you can use the warden chroot command to access the jail from the host system. Alternately, to access the jail over the network using ssh, you will need to first create a user account.

To access the jail in order to create that user:

warden chroot jail1

Started shell session on jail1 . Type exit when finished.

adduser

Follow the prompts of the adduser script in order to create a user. When you get to the following prompt, do not press enter. Instead type in wheel so that the user can use the su command to become the superuser within the jail.

Login group is username. Invite username into other groups? [] wheel

When you are finished creating the user, you can type exit to exit the jail. Test that ssh works by specifying the username that you created:

ssh username@jail1

Managing Jails from the Command Line

Table 8.21a shows the command line equivalents to the graphical options provided by the Warden® GUI. To get usage examples for each command, insert help into the command. For example, to get help on the auto command, type warden help auto. Note that some options are only available from the command line.

Table 8.21a: Command Line and GUI Equivalents

Command Line GUI Description
auto right-click highlighted jail and click Autostart toggles the jail's autostart between Enabled and Disabled
bspkgng in the GUI, this happens automatically during jail creation unless "Install PKGNG and PC-BSD utilities" is unchecked adds the PC-BSD® utilities to an existing jail
checkup in the GUI, update checks occur automaticaly and any un-applied updates are shown in the Updates column checks for updates to either the specified jail or all jails
chroot Tools ➜ Launch Terminal opens a terminal with the root user logged into the jail
create "+" button or File ➜ New Jail creates a new jail with specified attributes
details Info tab provides an overview of specified jail's configuration
delete "-" button or right-click jail ➜ Delete Jail deletes the specified jail
export right-click ➜ Export jail to .wdn file saves the specified jail and all of its software, configuration, and files as a .wdn file.
fstab opens the jail's /etc/fstab in an editor
get configure (wrench) icon for highlighted jail lists the various IP addresses used by the jail
import File ➜ Import Jail import a previously created .wdn file
list "Installed Jails" section of GUI list all jails
pkgs Tools ➜ Package Manager lists packages installed into specified jail
pbis lists PBIs installed into specified jail
set right-click jail used to set options, addresses, aliases, and permissions in specified jail
start right-click jail ➜ Start this Jail starts the specified jail
stop right-click jail ➜ Stop this Jail stops the specified jail
type "Jail Type" during jail creation types differ as choices are pbibox, portjail, pluginjail, or standard; to create a Linux jail, instead use the linuxjail option with the create command
template File ➜ Template Manager used to create, delete, or list templates
zfsmksnap Snapshots ➜ Add creates a snapshot of specified jail
zfslistclone Snapshots ➜ Mount lists any mounted snapshot clones
zfslistsnap Snapshots lists any created snapshots
zfsclonesnap Snapshots ➜ Mount creates and mounts a snapshot clone
zfscronsnap Snapshots ➜ Scheduled Snapshots schedules ZFS snapshot creation
zfsrevertsnap Snapshots ➜ Restore restores ZFS snapshot
zfsrmclone Snapshots ➜ Unmount unmounts a mounted clone
zfsrmsnap Snapshots ➜ Remove deletes specified snapshot

The Warden® configuration file located in /usr/local/etc/warden.conf is the equivalent to Jails ➜ Configuration in the GUI. In addition, it specifies the default template to use when creating a jail.

more /usr/local/etc/warden.conf #!/bin/sh # Configuration options for the Warden ###################################################################### # Network Interface for the jails to use NIC: em0 # Directory to use for compressing / decompressing files WTMP: /usr/jails # Location of the jails JDIR: /usr/jails # FreeBSD release to use FREEBSD_RELEASE: 9.1-RELEASE



Using PC-BSD®

This section discusses how to perform common tasks that were not discussed in the Control Panel section. This section contains the following categories:

-->



Java, Flash, and Fonts

This section demonstrates how to install and configure Java, Flash, and fonts to improve your desktop experience.

Java

The OpenJDK PBI provides an open source implementation of the Java Platform. It includes the IcedTea Java browser plugin which automatically works with the FireFox, Chrome, and Opera web browsers without any additional configuration. To install this PBI, search for "jdk" within AppCafe®.

Adobe Flash

PC-BSD® installs and configures the Adobe Flash player (version 10) plugin for you.
Adobe Flash icon
This means that flash should "just work" when browsing the web. You will find several web browsers in the Web Browsers category of AppCafe®, including Firefox, Opera, and Chromium.

If Adobe Flash does not seem to be working, invoking the following command from an xterm as your regular user account should fix the problem:

flashpluginctl on

The Adobe Flash Player preferences icon in Control Panel can be used to modify how websites interact with your browser using Adobe Flash.

Installing Custom Fonts

PC-BSD® installs Microsoft TrueType fonts for you which includes the Times New Roman, Courier New, Georgia, Trebuchet MS, Comic Sans MS Arial, Arial Black, Verdana, Andale Mono, and Impact fonts.

If you have a collection of fonts that you have downloaded or purchased, you can configure your PC-BSD® system to also use these fonts. Which utility you use depends upon which window manager you have logged into.
Figure 9.1a: Using KDE's Font Installer to Install Custom Fonts
NOTE: Many fonts are available from FreshPorts[213]. To find a font, search for "font". If you find a font you like, FreshPorts will indicate the pkg_add command that is used to add that font to your system. Any font installed using pkg_add should not require any additional configuration to "just work".

The rest of this section demonstrates how to install fonts that you have downloaded manually or purchased from the Internet.

Using KDE

To install custom fonts within KDE, go to System Settings → Font Management. In Figure 9.1a, "All Fonts" is currently selected under the "Group" column, showing all of the fonts installed on this system.

To install your fonts, highlight "Personal Fonts" under the "Group" column, then click the "+Add" button. This will allow you to browse to the font you wish to add. You can add multiple fonts in the same directory by holding down the Ctrl key while making your selection. Click the "Open" button, which will install the font for you. When it is finished, a pop-up message will indicate that you will need to restart any open applications for the font change to take affect. Your newly installed font(s) should now show up in the "Personal Fonts" section in the "Group" column and be available to the applications you use.

Using GNOME

To install custom fonts within GNOME, go to Applications → Utilities → File Browser. Navigate to the location of the font that you would like to install and either double-click the font name or select "Font Viewer" from the icon's right-click menu. This will open the font in "Font Viewer", allowing you to view it. If you like the font, click the "Install Font" button to make it available to your applications. In the example shown in Figure 9.1b, the user is installing the BlackFlag font.

Figure 9.1b: Using GNOME's Nautilus to Install a Custom Font

Using XFCE

To install custom fonts within XFCE, use Applications → System → Thunar File Manager. Once you browse to the location of the font and double- or right-click it, you will see the same Font Viewer used by GNOME.

Using Other Desktops

For any desktop, you can use XFCE's thunar to install fonts. Depending upon which desktop(s) you have installed, this utility may or may not already be installed. If nothing happens when you type thunar, install it using AppCafe®.

From the Command Line

If you prefer to install fonts from the command line, become the superuser and copy the downloaded font to the /usr/local/share/fonts/ directory. Then, refresh the fonts cache with the fc-cache -f -v /usr/local/share/fonts/name_of_font command.



Multimedia

PC-BSD® has been pre-configured to support most multimedia formats and makes it easy to install most open source media applications using AppCafe®. In addition, the following Control Panel icons are available, regardless of the desktop:

  • Sound Configuration: this utility displays the recognized audio devices and allows you to select and test which device to use by default.
  • Mount Tray: this application automatically detects the insertion and removal of media in USB devices. This means that any desktop should notify you if media is inserted into a USB CD/DVD device.

If you insert a CD/DVD media into an internal CD/DVD device and your desktop does not notify you, you can still mount the media manually as the superuser. This command will mount a CD inserted into the first internal CD device:

mount -t cd9660 /dev/cd0 /media

If you install your web browser using AppCafe®, you should be able to play most media formats, including YouTube videos, Internet radio, and many trailer and movie sites.

If people are blue in YouTube videos, this is due to a known issue in flash which Adobe hasn't fixed for open source players. To resolve this issue, right-click an area in the video, select "Settings", then uncheck the box "Enable hardware acceleration". Alternately, use the Minitube PBI to watch YouTube.

NOTE: If you happen to come across a file that you can not play in a web browser or media player, it is probably because it is in a proprietary format that requires a licensing fee or restricts distribution of the codec that is required to play that media format.

The "Multimedia" category of AppCafe® contains several dozen applications for playing and editing multimedia. It includes these popular applications (click the links to view screenshots):

  • Ardour[214]: digital audio workstation that provides non-destructive, non-linear editing with unlimited undo and more than 200 LADSPA & LV2 plugins.
  • aTunes[215]: full-featured audio player and manager that can play mp3, ogg, wma, wav, flac, mp4 and radio streaming, allowing users to easily edit tags, organize music and rip audio CDs.
  • Audacious[217]: audio player with a focus on low resource usage, high audio quality, and support for a wide range of audio formats.
  • Decibel-audio-player[218]: audio player built around a highly modular structure that lets the user disable completely the features he does not need. Able to play CDs directly.
  • gtkpod[219]: graphical user interface for the Apple iPod.
  • Hulu-Desktop: an application for watching Hulu programming without a web browser.
  • Miro[221]: HD video player that can play almost any video file and offers over 6,000 free Internet TV shows and video podcasts.
  • Totem[102]: the official movie player of the GNOME desktop environment based on GStreamer. It features a playlist, a full-screen mode, seek and volume controls, as well as keyboard navigation.
  • UMPlayer[223]: universal media player that can handle any media format and play audio CDs, DVDs, (S)VCDs, TV/radio cards, YouTube™ and SHOUTcast™ streams.
  • VLC[224]: simple, fast and powerful media player which plays everything: files, discs, webcams, devices and streams.



Files and File Sharing

This section describes the various file managers that are available for managing the files on your PC-BSD system. It then shows how you can configure your PC-BSD system to share files with other systems in your network using Samba.

File Managers and File Structure

Depending upon which window managers you have installed, different graphical file manager utilities may already be installed for you. You do not need to be logged into a specific window manager to use an installed file manager. For example, if KDE is installed, you can run its file manager from any window manager by typing dolphin. KDE, GNOME, LXDE, and XFCE install their own file managers while most of the unsupported desktops assume that you will install your favorite file manager. Table 9.3a summarizes the available file managers and indicates which desktop they are installed with. Some file managers can be installed independent of a desktop using AppCafe® to install the PBI. Once a file manager is installed, type its name if you wish to run it from another desktop.


Table 9.3a: Available File Managers [tables 24]
File Manager Desktop/PBI Screenshots Notes
dolphin KDE http://dolphin.kde.org/features.html[225]
emelfm2 PBI http://emelfm2.net/wiki/ScreenShots[226]
/usr/local/GNUstep/Apps/FSViewer.app/FSViewer Window Maker
gnome-commander PBI http://www.nongnu.org/gcmd/shots.html[227]
krusader PBI http://www.krusader.org[228]
mucommander PBI http://www.mucommander.com/screenshots.php[229]
nautilus GNOME https://projects.gnome.org/nautilus/screenshots.html[230]
pcmanfm LXDE or PBI http://lxde.org/easy_fast_file_management_pcmanfm[231]
thunar XFCE or PBI http://www.xfce.org/projects/thunar[134] unable to automount internal NTFS disks (try pcmanfm or emelfm2 instead)
xfe PBI http://roland65.free.fr/xfe/index.php?page=screenshots[232]

When working with files on your PC-BSD system, save your own files to your home directory. Since most of the files outside of your home directory are used by the operating system and applications, you should not delete or modify any files outside of your home directory, unless you know what you are doing.

Table 9.3b summarizes the directory structure found on a PC-BSD system. man hier explains this directory structure in more detail.


Table 9.3b: PC-BSD Directory Structure [tables 25]
Directory Contents
/ pronounced as "root" and represents the beginning of the directory structure
/bin/ applications (binaries) that were installed with the operating system
/boot/ stores the startup code, including kernel modules (such as hardware drivers)
/compat/linux/ Linux software compatibility files
/dev/ files which are used by the operating system to access devices
/etc/ operating system configuration files
/etc/X11/ the xorg.conf configuration file
/etc/rc.d/ operating system startup scripts
/home/ subdirectories for each user account; each user should store their files in their own home directory
/lib/ operating system libraries needed for applications
/libexec/ operating system libraries and binaries
/media/ mount point for storage media such as DVDs and USB drives
/mnt/ another mount point
/proc/ the proc filesystem required by some Linux applications
/rescue/ necessary programs for emergency recovery
/root/ administrative account's home directory
/sbin/ operating system applications; typically only the superuser can run these applications
/tmp/ temporary file storage; files stored here may disappear when the system reboots
/usr/bin/ contains most of the command line programs available to users
/usr/local/ contains the binaries, libraries, startup scripts, documentation, and configuration files used by applications installed from ports or packages
/usr/pbi/ contains the binaries, libraries, startup scripts, documentation, and configuration files used by installed PBIs
/usr/local/share/fonts/ system wide fonts for graphical applications
/usr/local/share/icons/ system wide icons
/usr/ports/ location of system ports tree (if installed)
/usr/share/ system documentation and man pages
/usr/sbin/ command line programs for the superuser
/usr/src/ location of system source code (if installed)
/var/ files that change (vary), such as log files and print jobs

Samba

Samba[233] allows any operating system to share volumes using Microsoft's CIFS protocol. There are two components to Samba:

  • client libraries: this allows an operating system to access existing CIFS shares. The client is built into the Windows and Mac OS X operating systems and is installed for you during the PC-BSD installation. Most Linux distros also install the Samba client; if your Linux distro does not, search its software repository.
  • server: this allows a computer to act like a Windows server in that it can create shares and printers that are available to any CIFS client on the same network.

This section will demonstrate how to access shares using the Samba client as well as how to configure your PC-BSD system as a Samba server.

Using the Samba Client

Since the Samba client libraries are pre-installed for you, you simply have to decide which utility you prefer to access existing Windows shares on your network. If a desktop is installed, you do not have to be logged into that desktop in order to use that utility.

Table 9.3c summarizes the available utilities (type a utility's name to launch it in any desktop), which desktop it installs with and whether or not a separate PBI is available, and a short description of how to access the available shares using that utility.


Table 9.3c: Utilities that Support Windows Shares [tables 26]
Utility Desktop/PBI How to Access Existing Shares
dolphin KDE in the left frame, click on Network → Samba Shares, then the Workgroup name; if the network requires a username and password to browse for shares, set this in Control Panel → System Settings → Sharing while in KDE or type systemsettings → Sharing while in another desktop
konqueror KDE in the location bar, type smb:/
krusader PBI add Local Network to toolbar by going to Settings → Configure Toolbars; once in toolbar click Local Network → Samba Shares
mucommander PBI click on Go → Connect to server → SMB; input the NETBIOS name of server, name of share, name of domain (or workgroup), and the share's username and password
nautilus GNOME click on Go → Network → Windows Network
smb4k PBI click on the "Network Neighborhood" tab
thunar XFCE or PBI in the left frame, click on Network → Windows Network

Configuring the Samba Server

If you would like to share folders or a printer attached to your PC-BSD system with other users in your network, configure the built-in Samba server.

In order to create shares, Samba's configuration file, smb.conf[234], needs to be modified. You can either edit this file manually or use a GUI utility such as SWAT[235]. This section will demonstrate both methods.

Edit smb.conf Manually

To modify the file manually, become the superuser and copy the sample file to the configuration directory:

cp /usr/local/share/examples/samba36/smb.conf.sample /usr/local/etc/smb.conf

Open the copied file in your favorite editor and review the default settings, editing them to match your network. In particular, check these global settings:

Figure 9.3a: SWAT Graphical Menu
  • workgroup = must match the Windows workgroup or domain name; unless the administrator has changed it, the default workgroup name is WORKGROUP
  • hosts allow = you should input the network address to restrict connections to the local network

In the share definitions section, review the [homes] settings. You can also define your own shares. This example will share the Downloads directory of user1 as read-only:

[Downloads]

path = /usr/home/user1/Downloads public = yes

writable = no

To test your changes, restart the Samba service:

/usr/local/etc/rc.d/samba restart

and try browsing to the share from another system. Note that you may have to first map a drive to the share in order for it to appear in Windows Explorer or within the file manager utility of another PC-BSD or Linux system.

Create Shares Using SWAT

SWAT provides a graphical front-end to smb.conf through a web browser.

To enable SWAT, remove the # at the beginning of this line in /etc/inetd.conf:

#swat stream tcp nowait/400 root /usr/local/sbin/swat swat

Add the following line to /etc/rc.conf:

inetd_enable=”YES”

And start inetd:

/etc/rc.d/inetd start

To connect to SWAT, open a web browser and input the IP address of the PC-BSD computer followed by :901. When prompted, input the username root and the password associated with the superuser account. In the example shown in Figure 9.3a, the user has clicked on the "Globals" button in order to view the global settings.

One of the nice features of SWAT is the built-in help system. If you need more information about an option, simply click its "Help" hyperlink to access that section of the Samba documentation. The "shares" button allows you to quickly create shares and the "view" button allows you to review the current configuration.



MythTV

Figure 9.4a: MythTV Configuration GUI

MythTV[237] is an open source software digital video recorder (DVR) that is an alternative to Tivo or Windows Media Center. It allows you to pause and rewind live TV shows, skip commercials, schedule TV show recordings, and control a set-top box[238] using an infrared remote or firewire. In order to use MythTV, you will need a video capture card. Hardware requirements are described on the MythTV Wiki[239].

NOTE: In PC-BSD®, webcamd is used to provide the drivers for video capture cards. This is enabled by default, meaning any devices supported by Video for Linux[240] should “just work”.

During the installation of PC-BSD® the installer provided an option to install MythTV. If you wish to install MythTV afterwards, use Control Panel → Package Manager → Misc. Once MythTV is installed, an entry should be added to the "Multimedia" section of the application menu of your desktop. You can also run MythTV from the command line by typing /usr/local/share/pcbsd/scripts/mythtv.sh.

Running MythTV for the First Time

Figure 9.4b: MythTV Configuration Screen

The PC-BSD® version of MythTV provides an initialization script to properly setup the database backend used by MythTV. The first time you run MythTV, you will be prompted for your password in order to configure MythTV. After inputting your password, a console will temporarily open indicating that the MySQL service is starting and that the MySQL database is being created. Once that is complete, you will see the configuration GUI shown in Figure 9.4a.

The initial screen will prompt you to select your "Country" and "Language". Once the desired options are highlighted, click the "Save" button. You should see the MythTV front-end screen shown in Figure 9.4b.

Navigate to the configuration screen you wish to access, then press enter. To leave a screen, press ESC. To exit the front-end completely, press ESC from the main configuration menu.

Chapter 5 of the MythTV Howto[241] demonstrates the possible configurations and how to schedule recordings.

Additional Resources



XBMC

XBMC[244] is a GPL licensed software media player and entertainment hub for digital media. XBMC can play most[245] popular audio and video formats. It can play CDs and DVDs from a disk or image file and even files inside ZIP and RAR archives. It can scan all of your media and automatically create a personalized library with album covers, descriptions, and fan art.


WARNING Before installing XBMC, make sure that your system meets the minimum hardware requirements[246]. The XBMC team recommends using an NVIDIA GeForce 6150 or later.

During the installation of PC-BSD® the installer provided an option to install XBMC. If you wish to install XBMC afterwards, use Control Panel → Package Manager → Misc. Once XBMC is installed, an entry should be added to the "Multimedia" section of the application menu of your desktop. You can also start XBMC by typing xbmc from a command prompt.

If you have never used XBMC before, take some time to skim through the XBMC Quick Start Guide[247] and the XBMC Online Manual[248].



Windows Emulation

Wine[249] is an application that allows you to create a Windows environment for installing Windows software. This can be useful if your favorite Windows game or productivity application has not been ported to Linux or BSD.

Wine is not guaranteed to work with every Windows application.
Figure 9.6b: Wine Configuration Menu
If you are unsure if the application that you require is supported, search for it in the "Browse Apps" section of the Wine Application Database[250]. The Wine Wiki[251] contains many resources to get you started and to refer to if you encounter problems with your Windows application.

Installing and Using Wine

Wine can be installed from AppCafe®. In Figure 9.6a, the user has performed a search to find the Wine PBI.

Figure 9.6a: Installing Wine from AppCafe®

Once installed, an icon for Wine Configuration will be added to the Control Panel and, depending upon your desktop, a desktop icon may be created as well. Double-clicking the icon will load the Wine configuration menu shown in Figure 9.6b. You can also start this program by typing winecfg at the command line.

Click the "Add application" button to browse to the application's installer file. By default, the contents of your hard drive will be listed under "drive_c". If the installer is on a CD/DVD, use the drop-down menu to browse to your home directory → .wine → dosdevices folder. The contents of the CD/DVD should be listed under d:. If they are not, the most likely reason is that your CD/DVD was not automatically mounted by the desktop. To mount the media, type the following as the superuser:

mount -t cd9660 /dev/cd0 /cdrom

You should hear the media spin and be able to select the installer file. Once selected, press "Apply" then "OK" to exit the configuration utility.

To install the application, click the Winefile desktop icon or type winefile to see the screen shown in Figure 9.6c:

Figure 9.6c: Installing the Application Using winefile

Click the button representing the drive containing the installer (in this example, D:\) and double click on the installation file (e.g. setup.exe). The installer should launch and you can proceed to install the application as you would on a Windows system.


WARNING If you had to manually mount the CD/DVD, you will need to unmount it before it will eject. As the superuser, use the command umount /mnt in an xterm.

Once the installation is complete, browse to C:\ and find the application's location. Figure 9.6d shows an example of running Internet Explorer within winefile.

Figure 9.6d: Running the Installed Application

Using Swine

This is a helpful configuration application available from AppCafe®.
(Need images and further text to flesh this out)



Remote Desktop

Figure 9.7a: Creating a Connection Using KRDC

Occasionally it is useful to allow connections between desktop sessions running on different computers. This can be handy when troubleshooting a problem since both users will be able to see the error on the problematic system and either user can take control of the mouse and keyboard in order to fix the problem. Typically this is a temporary situation as providing access to one's computer allows a remote user the ability to both view and modify its settings.

This section will demonstrate two remote desktop scenarios: how to configure an RDP connection to another computer from PC-BSD® and how to invite another computer to connect to your desktop session.

Connecting to Another Computer With RDP

The remote desktop protocol (RDP)[252] can be used to make a connection to another computer. This section will demonstrate what is needed on the remote computer for an RDP connection, how to connect using KDE's KRDC, and how to connect using VNC.
Figure 9.7b: Settings for the RDP Connection

Preparing the Remote System

Depending upon the operating system, you may have to first install or enable RDP software on the remote computer:

  • not every edition of Windows provides a fully functional version of RDP; for example, it may not be fully supported in a Home Edition of Windows. Even if the full version of RDP is included, remote access may or may not be enabled by default. If you have trouble connecting using RDP, do a web search for "remote desktop" and the name of the version of Windows you are using to find out how to configure its remote desktop settings. If you still cannot connect, you will need to download, install and configure VNC[253] server software on the system.
  • if the other computer you are connecting to is a Mac, Linux, or BSD system, you will have to first install either xrdp[254] or a VNC server on the other system. Depending upon the operating system, either software may or may not already be installed. If it is not, check the software repository for the operating system or use a web search to find out how to install and configure one of these applications on that operating system. If you are connecting to another PC-BSD® system, the krfb VNC server is automatically installed with KDE and additional VNC server software is available in AppCafe®.

If the remote system is protected by a firewall, you will need to check that it allows connections to the TCP port required by the type of connection that you will be using:

  • RDP: uses port 3389
  • VNC: uses port 5900 (for the first connection, 5901 for the second connection, etc.)

If you need to manually add a firewall rule, it is best to only allow the IP address of the computer that will be connecting. You should immediately remove or disable this firewall rule after the connection is finished so that other computers do not try to connect to the computer. Since your PC-BSD® system is considered to be the client and will be initiating the connection, you do not have to modify the firewall on the PC-BSD® system.

Connecting with KDE's KRDC

If your PC-BSD® system has the KDE desktop installed, you can initiate a connection request using KRDC. To launch this application, go to Applications → Internet → Remote Desktop Client within KDE or type krdc at the command line within any desktop. If you click F1 while in KRDC you can access the Remote Connection Desktop Handbook to learn more about how to use this application.

Figure 9.7a shows the initial KRDC screen which allows you to specify which system you wish to connect to.

Use the drop-down menu to indicate whether the remote system is using RDP or VNC for the connection. Then type in the IP address of the system you wish to connect to. If you are connecting to a VNC system, the IP address needs to be followed by a colon and a number indicating the number of the session. Typically, the number will be 1 unless the VNC server is hosting multiple simultaneous connections. Once you press enter, the connection will be initiated and, if it is an RDP connection, you will see the screen shown in Figure 9.7b.

Here is a quick overview of the settings:

Desktop resolution: since the contents of the screen are sent over the network, select the lowest resolution that still allows you to see what is happening on the other system. If you have a very fast network connection, you can choose a higher resolution; if you find that the other system is very slow to refresh its screen, try choosing a lower resolution.

Color depth: choose the lowest color depth that allows you to see the other system; you can choose a higher color depth if the network connection is fast.
Figure 9.7c: Initiating a Connection Request Using krfb

Keyboard layout: this drop-down menu allows you to select the desired keyboard layout.

Sound: this drop-down menu allows you to choose whether any sounds heard during the connection are produced on this system, the remote system, or to disable sound during the connection.

Console login: if you are connecting to a Unix-like system, you can check this box if you wish to have access to the other system's command line console.

Extra options: allows you to specify rdesktop switches[255] that are not covered by the other options in this screen.

Show this dialog again for this host: if you plan on using the same settings every time you connect to this computer, you can uncheck this box. If you need to change the settings at a later time, you can right-click the connection (which will appear in a list as a past connection) and choose Settings from the right-click menu.

Remember password: KWallet[256] is KDE's password storage system. If this box stays checked, you will only need to input the password the first time you make this connection as it will be saved for you. If this is the first time you have stored a password using KWallet, it will prompt you for some information to set up your wallet.

If it is a VNC connection, you will be able to choose your connection type (speed), screen resolution, and have the option to remember the password.
Figure 9.7d: Connection Invitation Created Using krfb

Once you press OK, the connection should be initiated and you will receive pop-up messages asking for a username then a password; the details you provide must match a user account on the system you are connecting to. Once your authentication details are confirmed, you should see the desktop of the other system. If you move your mouse, it will move on the other desktop as well. Click the button View Only in the top toolbar whenever you wish to disable this mouse behaviour. When you are finished your session, you can click the button Disconnect in the top toolbar.

NOTE: If the connection fails, check on the remote computer that either the RDP software is enabled or that the VNC server is listening for connections. Also double-check that a firewall is not preventing the connection.

Connecting with VNC

If you prefer to install VNC software instead of using KDE's KRDC, use AppCafe® to install TightVNC. If you use VNC, the VNC server must be installed on the remote desktop.

Once TightVNC is installed, type vncviewer to start the VNC client. A small window will appear, allowing you to type in the IP address of the remote system in the format IP_ADDRESS:5801. Change the 5801 if the VNC server is listening on a different port.

Allowing Another Computer to Connect Using Desktop Sharing

If you wish another user to connect to your computer and have the KDE desktop installed, you can use the KDE Desktop Sharing application to generate a connection invitation. To launch this application within KDE, go to Applications → Internet → Desktop Sharing or type krfb from the command prompt of any desktop. If you press F1 while in this application, it will open the Desktop Sharing Handbook where you can learn more about using this utility. Figure 9.7c shows the initial screen for this application.

There are two types of invitations that you can create:

Personal Invitation: if you click this button it will display the hostname that the other person will use to connect, a temporary password to use for the connection, and a connection request expiration time of one hour. It will include a warning reminding you to only give this information to the person you wish to connect as anyone can connect using that information. The connection itself can be made from any VNC client. If the person is using PC-BSD®, they can use kdrc or vncviewer as described above. On other operating systems, they will need to check if VNC is installed and download a VNC client if it is not. Once you press the "Close" button, the invitation expiry date will be listed in the main screen. Figure 9.7d shows an example of a personal invitation.

Email Invitation: if you click this button it will display a warning that anyone who reads the email containing the invitation can connect. Once you click the "Continue" button, the default email program will open the invitation so that you can input the email address of the recipient and send the email.
Figure 9.7e: The Other User is Trying to Connect Using the Invitation

It should be noted that the most secure way to convey the invitation information is through an alternate communications channel such as a phone call. Ideally, you are speaking to the other person as they connect so that you can walk them through the problem you are experiencing and they can let you know what they are doing to your system as you watch them do it.

Once the other person has the invitation, they should input the information in the invitation into their VNC client in order to start the connection. You will know when they try to connect as a pop-up message will appear on your screen similar to Figure 9.7e.

In this example, a computer with an IP address of 192.168.1.111 is trying to connect. Buttons are provided to either accept or refuse the connection. You can also check or uncheck the box to "allow remote user to control keyboard and mouse". If you accept the connection, the other user will be prompted to input the invitation password. Once the password is accepted, they will see your desktop.



Thin Client

PC-BSD® provides a Thin Client script which can be used to easily create a PXE Boot Desktop Server, to support thin clients, and a PXE Boot Install Server, for creating a central server which systems can connect to in order to be installed with PC-BSD®.

This section demonstrates how to configure and use both the PXE Boot Desktop Server and the PXE Boot Install Server.

Creating a PXE Boot Desktop Server

A PC-BSD® PXE Boot Desktop Server allows you to automatically configure a network of diskless computers[257] where each computer has a network interface card capable of PXE[258] booting. When a client boots from their network interface instead of their hard disk, they automatically connect to the PXE Boot Desktop Server and receive a login window. Once authenticated, they can use PC-BSD®, even if PC-BSD® is not installed on their own computer and even if their computer does not have a hard drive.

To prepare your PC-BSD® system for a PXE Boot Desktop Server configuration, perform these tasks first:

  1. If the diskless clients will require Internet access, install two network cards where one NIC is connected to the Internet and the other is connected to a private LAN from which the thin clients can PXE boot from.
  2. The PC-BSD® system should have lots of RAM installed, especially if multiple clients will be connecting. It is recommended that you use a 64-bit system with as much RAM installed as possible.

To configure the PC-BSD® system as a PXE Boot Desktop Server, run the following script as the superuser:

pc-thinclient

/usr/local/bin/pc-thinclient will install the components to convert this system into a thin-client server. Continue? (Y/N) y Do you wish to install the dhcpd server port or use an external server? If you wish to use an external server please make sure it supports adding next server and bootfile name options.

(d/e)

If you wish to have the PC-BSD® system act as the DHCP server, type d. If the network already has a configured DHCP server, type e. The following example will install the DHCP server on the PC-BSD® system. After making your selection, press enter to continue:

Do you wish to make this a remote X desktop server or install server? (r/i) r

If your intent is to install a PXE Boot Desktop Server, input r and press enter. If you previously typed d and a DHCP server is not already installed, it will be installed for you. Once the DHCP server is installed, the tools needed in the PXE environment will be installed and messages will indicate the progress. Once everything is installed, you will see this message:

Setting up system for PXE booting...

What NIC do you wish DHCPD to listen on? (I.E. re0)

nic) em0

Input the FreeBSD device name of the interface that is attached to the local network containing the diskless workstations. This interface will run the DHCP server and should not be connected to a network with another DHCP server running. In the example shown here, the user has input the em0 interface. If you are unsure of the device name, type ifconfig from another terminal.

The script will now configure the specified interface and start the required services:

Starting /etc/rc.d/nfsd...OK

Starting /etc/rc.d/inetd...OK Starting /usr/local/etc/rc.d/isc-dhcpd...OK

You will need to reboot the system for the login manager changes to take effect.

Your system is now setup to do PXE booting!

Before rebooting, you may wish to customize the installation.

The installation creates a chroot directory that contains a small PXE image that is used by clients to launch Xorg and connect to the PXE Boot Desktop Server. You can access this chroot by typing this command as the superuser:

chroot /usr/home/thinclient

Running pkg info within the chroot will show which X components and drivers are available. Should you need to install additional video drivers, use pkg install within the chroot. When you are finished using the chroot, type exit to leave it.

The thin client script installs and configures the following services:

NFS: the Network File System is a protocol for sharing files on a network. It has been configured to allow clients on the network attached to the interface that you specified to connect to the thin client server. Its configuration file is located in /etc/exports.

TFTP: the Trivial File Transfer Protocol is a light-weight version of FTP used to transfer configuration or boot files between machines. The PXE network cards on the diskless computers will use TFTP to receive their configuration information. This service was enabled in /etc/inetd.conf with a home directory of /usr/home/thinclient.

DHCP: the Dynamic Host Configuration Protocol is used to configure IP addressing info on the diskless workstations. If you selected to install a DHCP server, it will be configured to assign addresses for the network attached to the interface that you specified. Its configuration file is located in /usr/local/etc/dhcpd.conf.

The thin client script also creates the pxeboot user with the default password thinclient. This username and password is used to save the working Xorg configuration files for each of the diskless computers. It is highly recommended that you change this password right away by running this command as the superuser:

passwd pxeboot

You will also need to create the users that will connect to the system. You can do so using User Manager or by typing adduser at the command line and following the prompts.

Connecting to the PXE Boot Desktop Server

After a successful installation and reboot of the PXE Boot Desktop Server, the DHCP service will be running on the NIC you specified. Make sure that this NIC and a PXE capable client are connected to the same hub or switch. When you boot up the client, PXE should automatically obtain an IP address and begin to load PC-BSD®. If it does not, review the boot order settings in the BIOS on the client to make sure that PXE is listed first.

After the boot process has finished, the client will be brought to this prompt:

No saved xorg-config for this MAC: <MAC_Address> Do you wish to setup a custom xorg.conf for this system? (Y/N)

If you wait 10 seconds, this message will timeout, and the client will bring up X in 1024x768 mode. If this is not the resolution that you wish to use, type "Y" at the prompt and hit enter to bring up the Xorg Configuration screen. In this menu, you will be able to setup your own custom xorg.conf file, auto-detect settings, and test the new configuration. When finished, choose "Save working config" to send this configuration to the PXE Boot Desktop Server. This will prompt for the password of the pxeboot user.

NOTE: In order for the login to succeed, the user account must already exist on the PXE Boot Desktop Server.
Once authenticated, the file will be saved by the client's MAC address in /home/pxeboot/mnt/xorg-config/<mac>.conf. The next time you boot the client, it will automatically use the saved xorg.conf file and bring the system to the PC-BSD® login screen.

The client's boot environment is located in /home/pxeboot. This is mounted read-only during the PXE boot process to allow the client to bootup and create an XDCMP connection to the server.

Once logged in to the PXE Boot Desktop Server, using PC-BSD® will be the same as if you had installed PC-BSD® on the client system. You will be able to use AppCafe® to install software and to save and use the files in your home directory.

Uninstalling the PXE Boot Desktop Server

Use the -remove option if you wish to uninstall the PXE Boot Desktop Server:

pc-thinclient -remove Removing /usr/home/thinclient

This will remove the PXE environment from the system. If you are finished using the PXE boot services, you can stop them using these commands:

service nfsd stop

service inetd stop

service isc-dhcpd stop

and prevent them from restarting by removing these lines from /etc/rc.conf:

# pc-thinclient configuration

dhcpd_enable="YES" dhcpd_ifaces="em0" portmap_enable="YES" nfs_server_enable="YES" inetd_enable="YES"

ifconfig_em0="192.168.2.2"

Your interface name and IP address may differ from those in the example. The dhcpd and portmap lines will not exist if you did not install a DHCP server.

Creating a PXE Boot Install Server

A PC-BSD® PXE Boot Install Server can be used to install PC-BSD®, FreeBSD, or TrueOS® onto computers who connect to the server using PXE. The installations can be interactive or fully automated. The PXE Boot Install Server supports multiple, concurrent installations with the only limiting factor being the server's disk I/O and the network's bandwidth.

The installation of the PXE Boot Install Server starts the same way, except this time you select i when prompted:

pc-thinclient

/usr/local/bin/pc-thinclient will install the components to convert this system into a thin-client server. Continue? (Y/N) y Do you wish to install the dhcpd server port or use an external server? If you wish to use an external server please make sure it supports adding next server and bootfile name options. (d/e) d Do you wish to make this a remote X desktop server or install server?

(r/i) i

Once the environment is downloaded and configured, you will be asked if you would like to install the web interface:

PC-ThinClient includes a web-interface for client management.

Would you like to install the Apache / PHP packages required?

default: (y)

You will then be prompted to input the interface to be used by the server and then the services will be started:

Setting up system for PXE booting...

What NIC do you wish DHCPD to listen on? (I.E. re0) nic) em0 Starting /etc/rc.d/nfsd...OK Starting /etc/rc.d/inetd...OK Starting /usr/local/etc/rc.d/isc-dhcpd...OK To perform system installations, place your custom pc-sysinstall scripts in: /usr/home/thinclient/installscripts An example script is provided in the above directory For unattended installations, save your pc-sysinstall script as: /usr/home/thinclient/installscripts/unattended.cfg

Your system is now setup to do PXE booting!

Connecting to and Customizing the PXE Boot Install Server

Once the PXE Boot Install Server is installed, try to PXE boot a client which is connected to the same network. If the client boots successfully, you will see the installation screen shown in Figure 9.8a.

Figure 9.8a: PXE Boot Installation Menu

By default, selecting “install” from the boot menu will use the /usr/home/thinclient/installscripts/pc-sysinstall.example script which installs a basic FreeBSD system. In addition to starting an installation, this menu provides an emergency shell prompt. This can be useful if you have a system which can no longer boot and you wish to either access the disk's contents or attempt to repair the installation.

Any scripts that you create and place in the /usr/home/thinclient/installscripts/ directory will be selectable as an installation option within the PXE client boot menu. Tables 5.4a and 5.4b in Creating an Automated Installation with pc-sysinstall summarize the available configuration options when creating an installation script. Alternately, every time you install PC-BSD, the installation script is automatically saved to /root/pc-sysinstall.cfg. This means that if you wish to repeat an installation, you simply need to copy that file to the /usr/home/thinclient/installscripts/ directory on the PXE Boot Install Server.

The PXE Boot Install Server also supports completely unattended installations. To perform fully-automated installations over the PXE interface, create a configuration script named /usr/home/thinclient/installscripts/unattended.cfg. When a PXE client first boots, it checks for the existence of the unattended.cfg file, and if found, it will automatically use it for installation. Some caution should be taken when using this method since simply plugging a PXE boot client into the wrong LAN cable could cause it to be re-installed.



Security

Your PC-BSD® system is secure by default. This section provides an overview of the built-in security features and additional resources should you like to learn more about increasing the security of your system beyond its current level.

The security features built into PC-BSD® include:

  • Naturally immune to viruses and other malware: most viruses are written to exploit Windows systems and do not understand the binaries or paths found on a PC-BSD® system. Antivirus software is still available in the Security section of AppCafe® as this can be useful if you send or forward email attachments to users running other operating systems.
  • Potential for serious damage is limited: file and directory ownership and permissions along with separate user and group functions mean that as an ordinary user any program executed will only be granted the abilities and access of that user. A user that is not a member of the wheel group can not switch to administrative access and cannot enter or list the contents of a directory that has not been set for universal access.
  • Built-in firewall: the default firewall ruleset allows you to access the Internet and the shares available on your network. If there are no shared resources on your network, you can use Firewall Manager to further tighten the default ruleset. In addition, Fail2ban[11] is installed. This service can be configured to identify possible break-in attempts and to respond with an action such as creating a firewall rule to ban the intruder. Instructions for configuring fail2ban can be found on the fail2ban wiki[259].
  • Built-in Host-based Intrusion Detection System: PC-BSD® installs OSSEC[10] which can be configured to perform log analysis, file integrity checking, policy monitoring, rootkit detection, real-time alerting, and active response. If you have never used OSSEC before, take some time to read through its manual[260] to determine which features interest you and how to configure them.
  • Very few services are enabled by default: you can easily view which services are started at boot time using Service Manager or by reading through /etc/rc.conf. You can also disable the services that you do not use by disabling that service in Service Manager or by commenting out that line with a # in /etc/rc.conf.
  • SSH is disabled by default: and can only be enabled by the superuser. This setting prevents bots and other users from trying to access your system. If you do need to use SSH, change the "NO" to a "YES" in the line sshd_enable= in the file /etc/rc.conf. You can start the service right away by typing /etc/rc.d/sshd start. You will need to add a firewall rule to allow SSH connections from the systems that require SSH access.
  • SSH root logins are disabled by default: if you enable SSH, you must login as a regular user and can use su or sudo when you need to perform administrative actions. You should not change this default as this prevents an unwanted user from having complete access to your system.
  • sudo is installed: and configured to allow users in the wheel group permission to run an administrative command after typing their password. By default, the first user you create during installation is added to the wheel group. You can use User Manager to add other users to this group. You can change the default sudo configuration using the visudo command as the superuser.
  • AESNI[261] support is loaded by default for the Intel Core i5/i7 processors that support this encryption set. This support speeds up AES encryption and decryption.
  • Automatic notification of security advisories: Update Manager will automatically notify you if an update is available as the result of a FreeBSD security advisory[262] that affects PC-BSD®. This allows you to keep your operating system fully patched with just the click of a mouse.

If you would like to learn more about security on FreeBSD/PC-BSD® systems, man security is a good place to start. These resources provide more information about security on FreeBSD-based operating systems:



Accessibility

The GNOME and KDE desktop environments included with PC-BSD provide accessibility features to assist users with vision and mobility impairments. This section provides an overview of these features and references to additional accessibility information.
Figure 9.10a: Changing the Input Device in Dasher
NOTE: If you install the GNOME-Accessibility or KDE-Accessibility system components, most of the applications installed with those components can also be started from the command line, regardless of which desktop a user is logged into.

GNOME Accessibility Tools

To install the GNOME accessibility tools, make sure that the "GNOME-Accessibility" box is checked (it is by default) when selecting to install GNOME either during installation or afterwards using Control Panel → Package Manager → Desktops.

The GNOME-Accessibility component installs the following software:

  • dasher[266]: supports alternative input devices such as a joystick, touchscreen, trackball, head-mouse, or eyetracker. In GNOME, this utility is located in Applications → Utilities → Dasher. It can also be started from the command line by typing dasher. To change the input device, start dasher and click Edit → Preferences → Control, shown in Figure 9.10a.
  • gok[267]: application which displays virtual keyboards. You can use a mouse or an alternative pointing device to operate the virtual keyboards. It generates dynamic keyboards that contain keys to represent the applications that are running on your desktop or the menus that are contained in an application. In GNOME, this utility is located in System → Preferences → Assistive Technologies, or you can type gok at the command line.
    Figure 9.10b: gok Main Screen
    Check the box Enable assistive technologies and then press the Close and Log Out button. Once you log back in, you can start this program by typing gok in a terminal. To start the virtual keyboard, click "Compose" in the main window, shown in Figure 9.10b. You can set your gok preferences by clicking GOK → Preferences.
  • mousetweaks[268]: provides mouse accessibility enhancements while logged into GNOME, such as simulating different mouse clicks without using physical buttons and a delay-click feature which opens a context menu. To configure mousetweaks within GNOME, go to System → Preferences → Mouse → Accessibility. In the screen shown in Figure 9.10c, if you check the box Trigger secondary click by holding down the primary button, you can simulate a secondary click on a mouse with one button by keeping the primary mouse button pressed without moving the pointer for the time determined by the delay slider. If you check the box Initiate click when stopping pointer movement, you will activate dwell click. This allows you to assign actions to a single primary click, double click, drag click, and secondary click without having to actually click a mouse button.
Figure 9.10c: Configuring mousetweaks

The GNOME-Accessibility component also adds the following options to the login Accessibility screen shown in Figure 4.8b:

  • Use on-screen keyboard
  • Use screen reader
  • Use screen magnifier

More information about GNOME-Accessibility can be found in the GNOME Desktop Accessibility Guide[269].

KDE Accessibility Tools

To install the KDE accessibility tools, make sure that the "KDE-Accessibility" box is checked (it is by default) when selecting to install KDE either during installation or afterwards using Control Panel → Package Manager → Desktops.

The KDE-Accessibility component installs the following software:
Figure 9.10d: Configuring KMouseTool
  • KMag[270]: a screen magnifier. In KDE, this application is in Applications → Utilities → Screen Magnifier or you can type kmag from the command line. Drag the magnifier window over the text you wish to magnify or click its "Settings" button to view the shortcuts for its various modes. Press F1 while the application is open to access the Kmagnifier Handbook.
  • KMouseTool[271]: clicks the mouse whenever the mouse cursor pauses briefly. It can also drag the mouse, although this takes a bit more practice. To start this utility in KDE, click Applications → Utilities → Automatic Mouse Click or type kmousetool from the command line. In the screen shown in Figure 9.10d, check the settings you wish to use, click the "Apply" button, then click the "Start" button. If you quit this screen, it will be added to the system tray and will continue to run until you launch its icon and click the "Stop" button. A PDF of the KMouseTool Handbook can be downloaded from the KDE site[272].



Create Your Own PBI Repository

By default, AppCafe® displays the PBIs which are available from the official PC-BSD® repository. It also supports custom repositories, allowing organizations to create PBIs for their own applications and to make them available to their users within AppCafe®.

In order to create a custom repository, you need to:

  • create the OpenSSL signing key which will be used to sign custom PBIs
  • generate a repository file and populate it with custom PBIs
  • generate the meta-data for the PBIs which are available within the repository

This section describes these steps in more detail.

Generate the Signing Key

Running a repository requires that all the PBIs in the custom repository be digitally signed for security and identification purposes. In order to sign the PBIs, generate an OpenSSL key pair using the following commands:

openssl genrsa -out privkey.pem 4096

Generating RSA private key, 4096 bit long modulus ..................++ .............................................................................++ e is 65537 (0x10001) openssl rsa -in privkey.pem -pubout > pub.key

writing RSA key

These commands will create the files privkey.pem and pub.key. The privkey.pem file will be used to digitally sign your created PBI files and the pub.key file will be included with the repository configuration (.rpo) file.

Create the Repository

In order to create the repository you will need a FTP, HTTP, or HTTPS server to host your repository’s meta-data files and to store the repository's PBIs. The server can be a public URL on the Internet or a private LAN server, as long as it is accessible to your target audience.

Once you have the URL to the server, create the repository's .rpo file using the pbi_makerepo command. Replace the values in the following example with your own description, path to your generated pub.key file, the URL to the location where the PBIs will be hosted, the URL to the location to contain the repository's meta-data files, and the directory to place the created .rpo file.

pbi_makerepo --desc “My Example Repository” --key pub.key --mirror ftp:////ftp.example.org/pbi-files” --url http://www.example.org/pbi-meta” /root

This command will generate the pbi-repo.rpo file in the specified directory on the server. This file is needed for clients to register with and begin using the new repository. Instruct your clients to download this file to their PC-BSD® desktop, then to configure their system to use the repository using this command as the superuser:

pbi_addrepo pbi-repo.rpo

Once the repository is registered on the clients system, their pbi daemon will automatically keep track of downloading and updating both meta-files and PBIs from the URLs you specified in the repository configuration file.

Generate the Repository's Meta-Data

On the server, you can now create the meta-data and PBI files so that clients have something to download. The meta-data file is used to give the client information about the PBIs available from the repository, such as categories, application names, and descriptions. When creating categories, you can use the same category names that appear in AppCafe®, or you can create your own categories. Each category and each PBI will need its own icon. These icons need to exist on the server before generating the meta-data file.

When you are ready, create an empty meta-data file in the format pbi-meta-<Major Version Number>. This command should be used for 9.x series PBIs:

touch pbi-meta-9

Then use the pbi_metatool command to add the category for a PBI. The following command adds the "Archivers" category, its description, and the URL pointing to the mandatory 64x64 .png icon file to the specified meta-data file.

pbi_metatool add --cat -n “Archivers” -d “File Archivers and Utilities” -i http://www.example.org/pbiicons/archivers.png” pbi-meta-9

Next, add the following information about the PBI: the name of the application, the category, the application author, a description of the application, the URL pointing to the mandatory 64x64 .png icon file for the application, a comma delimited list (with no spaces) of search keywords, the type of license, the type of application ("Graphical", "Text", or "Service"), the URL to the application's website, and the name of the meta-data file to add the information to.

pbi_metatool add --app -n “cabextract” -c “Archivers” -a “Stuart Caie” -d “Utility for reading and extracting .cab files.” -i http://www.example.org/pbi-icons/cabextract.png -k “cab,archive,extract” -l “LGPL” -t “Text” -u “http://www.cabextract.org.uk” pbi-meta-9

Repeat this command for each PBI that will be available in the repository, creating new categories as you need to do so.

When you are finished adding the information for the repository's PBIs, compress the file with bzip2 and upload it to the server. The location in our example would be http://www.example.org/pbi-meta/pbi-meta-9.bz2. Once the file is uploaded, clients can use the pbi_browser command or AppCafe® to browse the repository's PBIs.

You should now create your custom PBIs then upload them to their specified category in the download directory on the server. In our example, the download directory is ftp://ftp.example.org/pbi-files. Refer to the section on creating PBIs for instructions on creating PBIs using either the EasyPBI2 graphical utility or the pbi_makeport command line utility.

When creating your PBIs, remember to sign them with the private key. If you are using EasyPBI2, specify the location to the privkey.pem file by clicking the "Change File" button shown in Figure 8.1d. If you are using the pbi_makeport command, include --sign privkey.pem in the command.

Lastly, create the pbi-index-9 file and add the names of the uploaded PBIs to the file. Use the pbi_indextool to add each entry, specifying that PBI's filename (will end in .pbi), the download location (in the format category/pbi_name), and the name of the index file.

touch pbi-index-9 pbi_indextool -f cabextract-1.2-amd64.pbi -u “archivers/cabextract-1.2-amd64.pbi” pbi-index-9

When you are finished adding entries to this file, use bzip2 to compress it and upload the pbi-index-9.bz2 to the same location on the server where the pbi-meta-9.bz2 file is stored. Clients can now download and install PBIs from your custom repository, using the pbi_add command or AppCafe®.

Configure the Automatic Build of Updated Ports

Over time, the PBIs in your repository will become out-of-date as the versions of the underlying ports change. You can automate the process of automatically rebuilding the newer version of a PBI, as well as generating the binary diff changes to the PBI (which users use to upgrade their installed version of the PBI), whenever an underlying port changes.

To configure this scenario, ensure that all of your PBI modules exist under the same directory and follow the directory structure of the ports tree. For example, if you have created PBIs for cabextract and firefox, the subdirectory structure for /usr/local/my_pbis/ would be archivers/cabextract/ and www/firefox/.

To start the build process, use the pbi_autobuild command as seen in this example:

pbi_autobuild --keep 2 -c /usr/local/my_pbis -o /usr/local/my_pbis --prune --tmpfs --sign /root/privkey.pem –genpatch

This command keeps the last 2 versions of the PBI, reads the modules located in the subdirectories of /usr/local/my_pbis, places the built PBIs in the /usr/local/my_pbis directory, removes any PBIs which no longer have an associated module, uses tmpfs to optimize build speed, signs the PBIs with the specified key, and generates the .pbp patch files needed by users to upgrade an installed version of the previous PBI. The new PBIs and .pbp files will be placed in the specified outgoing directory. If an earlier version of the PBI exists in that directory, it will be placed into the archived subdirectory.

If the ccache FreeBSD port is installed on the build system and the CCACHE_DIR variable is set, pbi_autobuild will detect and use it which can greatly speed up the process of building the PBIs.

Depending upon the load on the build server and how many PBIs are affected by the build, you may wish to modify some pbi.conf values in particular PBI modules. The variables that can affect a build are:

  • PBI_BUILDKEY: set to a numerical value to instruct pbi_autobuild to rebuild that particular PBI. This is useful when a port has failed to build or you wish to rebuild a PBI with new compile options even though the upstream target port has not changed.
  • PBI_AB_PRIORITY: when automatically building a large number of PBIs, the build process occurs alphabetically. By setting an incremental integer value, it is possible to artificially force the building of PBIs in the specified order of importance.
  • PBI_AB_NOTMPFS: typically, using the --tmpfs flag greatly speeds up the build process by extracting a port's files into memory, and compiling directly into RAM. However some ports, such as OpenOffice, require more memory than is available, causing the build to fail. By setting this variable to YES in that PBI's pbi.conf, it is possible to flag that port as needing to build in the traditional manner from disk.
  • PBI_MAKEOPTS: if you use ccache, you may occasionally run into a port that will not compile properly with CCACHE enabled. For that PBI, edit this variable to include NO_CCACHE=yes which will disable CCACHE for that specific port build.



Finding Help

While professional PC-BSD® support is available from iXsystems[273], most users turn to the Internet for help. We are doing our best to make PC-BSD® as easy as possible for newcomers. Should you need help, there are plenty of ways to get in touch with the PC-BSD® community. This section discusses the following help resources:

As your teacher may have told you, "Do or Do Not, there is no try," or more likely, that "there is no such thing as a stupid question." However, there are better ways to ensure that you receive the response you seek and that it will be a productive exchange for all parties involved. The two articles below help to describe how and why it is important to follow certain protocols when requesting help:



PC-BSD® Forums

The PC-BSD® Forums[276] contain a wealth of information, tips and solutions which you can access from a web browser. There are many active members and you will find that most questions are replied to quickly. If you are having problems with something on your PC-BSD® system, try using the forum's search utility. You will often find that someone else has posted a similar question and that other users have responded with a fix or a how-to.

The Forums have been categorized, allowing users to skim through the categories that interest them while learning some things along the way. You do not have to create a login account in order to search or read through the forums. However, if you wish to ask or answer a question on a forum or subscribe to a forum or a thread (to be automatically notified when a new post is added), you will need to be logged in. To subscribe to a forum, open the page for the forum and select Forum Tools → Subscribe to this Forum. You will be prompted to choose how often to be notified whenever a post is added to the forum. If you wish to subscribe to a specific post, open the post and select Thread Tools → Subscribe to this Thread. You will be notified whenever someone responds to that post.

The current categories and the forum descriptions are described below:

The General category contains the following forums:

  • Announcements[277]: this is a read only forum containing announcements of new releases and news related to PC-BSD®. Subscribing to this forum is a good way to keep up-to-date with the latest news about PC-BSD®.
  • General Questions[278]: use this forum if your question does not fit into any of the other forum categories.
  • The Lounge[279]: this is a general discussion area for PC-BSD® users. Posts in this forum are not of a technical nature. Posts should be of interest to other PC-BSD® users and not contain any mature or slanderous content.
  • Advocacy[280]: this is a brainstorming area for promoting PC-BSD®.
  • Guides[281]: this forum contains how-tos and guides for performing specific tasks on PC-BSD®.
  • Tips and Tricks[282]: this forum contains suggestions for configuring and tweaking your PC-BSD® system.

The PC-BSD® Software category allows developers to become aware of any problems with current PBIs or software installed using pkgng and to receive requests for software that should be made into a PBI. If you start a post in any of these forums, subscribe to it so you can be notified of any responses to your post. The forums in this category include:

  • PBI Discussion[285]: a general discussion area for resolving PBI problem reports. If you have a problem installing or using a PBI, post the details in this forum.
  • PBI Requests[286]: do you have a favorite application that is not currently available as a PBI? You can request it in this forum. Be sure to read the Readme first[138] post if this is your first PBI request.
  • Finished PBIs[287]: once a new PBI is created as the result of a PBI request, the original request is moved to this forum.
  • Port Requests[288]: do you have a favorite application that is not currently available as a FreeBSD port? You can request it here. If someone does make a port it can also be converted into a PBI, as PBIs are based on FreeBSD ports. Again, read the Readme first[167] file if this is your first port request.
  • pkgng Discussion[289]: if you have problems installing software using pkgng or running an application installed using pkgng, post the details here.

The Support category deals with the following types of support questions. PC-BSD® developers are subscribed to this list so they can help determine what is causing the problem, and if a fix is made available, can commit it for the next version of PC-BSD®. If you start a post in any of these forums, subscribe to it so you can be notified of any responses to your post.

  • General Bug Reports[290]: if you are having a problem on your PC-BSD® system that does not match any of the other forum categories, you can report it here. Read any posts marked as "sticky" (they will always be at the top of the forum) if this is your first bug report.
  • Installing PC-BSD®[291]: if you are having problems installing PC-BSD®, post the details of your problem to this forum.
  • Startup Bug Reports[292]: if you have been able to install PC-BSD® but are having problems booting into PC-BSD®, post the details of your problem in this forum.
  • Usage Bug Reports[293]: if you are having problems performing a task or using the software that was installed with your PC-BSD® system, post the details of your problem to this forum.

The Hardware Support category is for reporting hardware-related problems. PC-BSD® developers are subscribed to this list so they can help determine what is causing the problem, and if a fix is made available, can commit it for the next version of PC-BSD®. If you start a post in any of these forums, subscribe to it so you can be notified of any responses to your post. Be sure to read the README first[296] before posting.

  • General Support[297]: if your hardware problem does not match any of the other forum categories, post the details of your problem in this forum.
  • Graphics Cards[298]: if you are having problems with your video card settings, post the details of your problem to this forum.
  • Sound and Multimedia[299]: if you are having problems with sound or in playing multimedia such as CDs or videos, post the details of your problem to this forum.
  • Networking[300]: if you are having problems using or configuring a network interface, post the details of your problem to this forum.
  • Laptops[301]: if you are having problems with power management or other laptop-specific issues, post the details of your problem to this forum.
  • Drives[302]: if you are having problems accessing or formatting CD, DVD, USB or hard drives, post the details of your problem to this forum.

The Development category contains the following forums:

  • Feature Requests[304]: do you have an idea for a feature that you would like to be available in PC-BSD®? This is the forum to request it.
  • Translations[305]: this is a discussion area for translators who localize PC-BSD® menus or translate PC-BSD® documentation.
  • PC-BSD® Installer[307]: this is a discussion area for feature requests and testing of the PC-BSD® installation program.

The Testing category is for PC-BSD® beta testers to report problems found in upcoming versions of PC-BSD®. It contains the following forums:

  • General Testing[308]: if your problem is not related to one of the following desktop environments, report the problem in this forum. Be sure to read the sticky threads first as they contain useful information about beta testing and any known issues with the testing snapshot.
  • KDE[309]: if your problem is related to the KDE desktop or KDE applications, report the problem in this forum. Be sure to read README first[310] for instructions before posting.
  • Gnome[311]: if your problem is related to the GNOME desktop or GNOME applications, report the problem in this forum. Be sure to read README first[312] for instructions before posting.
  • XFCE[313]: if your problem is related to the XFCE desktop, report the problem in this forum. Be sure to read README first[314] for instructions before posting.
  • LXDE[315]: if your problem is related to the LXDE desktop, report the problem in this forum. Be sure to read README first[316] for instructions before posting.
  • Fluxbox[317]: if your problem is related to the Fluxbox desktop, report the problem in this forum. Be sure to read README first[318] for instructions before posting.
  • Ports Testers[319]: if your problem is related to a FreeBSD package or port, you can report the problem in this forum. Be sure to read README first[320] for instructions before posting.

The Hardware Compatibility category contains forums to help users determine if their hardware is compatible with PC-BSD®. It contains the following forums:

The Server Administration category contains forums for discussing system administrative tasks system administration topics and questions for PC-BSD®, TrueOS®, FreeBSD, and Warden®. It contains the following forums:

The International category contains forums for non-English speakers for PC-BSD® related discussions in their native language. Each forum has its own categories for organizing posts. The following forums are available:

While logged into the forums, a link called "UserCP" will appear in the upper left hand corner. This is your control panel and it contains many settings to customize your forums experience. You should review the settings in your Control Panel.

Before asking a question on the forums or starting a new thread, first use the search utility to see if a similar thread already exists. If one does, you can add to the conversation by using the "Reply" button. If you find a thread useful, feel free to click the "Thanks" button to let the original poster know that you benefited from their knowledge.

If a similar thread does not already exist, review the forum categories to determine which one is the best fit for your post. When creating a new thread, use a useful "Title" name to describe your problem or question -- remember, other users may be researching a similar issue and you want them to find your thread. Include enough details in your message so that others can quickly understand what you are experiencing -- otherwise, they will have to ask you additional questions to understand your problem. Make sure you are subscribed to your thread so that you will receive a notification when someone responds to it.

You can ask a question by clicking on the "New Thread" button in the forum category that most closely matches your question. For example, if you are having problems with your video settings, you should create a new thread in the "Graphics Card" forum. If you do not see a category that matches your question, try the "General Support" category.

In addition to the forums available from the PC-BSD® Forums website, the following forums may assist you in troubleshooting your PC-BSD® system:

  • FreeBSD Forums[333]: many PC-BSD® problems are related to the underlying FreeBSD operating system. The FreeBSD forums are very active and full of useful information that can apply to your PC-BSD® system.
  • BSD Nexus[334]: contains categories for each of the BSD operating systems as well as general BSD information.
  • BSD Foren[335]: these forums are in German and contain many categories for each of the BSD operating systems.



IRC Channel

Like many open source projects, PC-BSD® has an IRC channel[338] to connect supporters and users. To get connected, use the following information in your IRC client:

  • Server name: irc.freenode.net
  • Channel name: #pcbsd (note that the # is required)

AppCafe® has an IRC category where you can find PBIs for IRC clients. If you do not wish to install an IRC client, you can instead use the the web interface to #pcbsd[339].

IRC is a great way to chat with other users and get answers to your questions. A few things to keep in mind if you ask a question on IRC:

  • Most of the regular users are always logged in, even when they are away from their computer or are busy doing other computing tasks. If you do not get an answer right away, do not get mad, leave the channel and never come back again. Stick around for a while to see if anyone responds.
  • IRC users represent many different time zones. It is quite possible that it is late at night or very early in the morning for some users when you ask a question.
  • Do not post error messages in the channel as the IRC software will probably kick you out for flooding and it is considered to be bad etiquette. Instead, use a pasting service such as pastebin[340] and refer to the URL on channel.
  • Be polite and do not demand that others answer your question.
  • It is considered rude to DM (direct message) someone who does not know you. If no one answers your question, do not start DMing people you do not know.
  • The first time you join a channel, it is okay to say hi and introduce yourself.



Mailing Lists

Mailing lists are a handy way to discuss problems, solutions, and requested features as they create a searchable archive of discussions. The PC-BSD® Project offers the following mailing lists[341] to cover a wide variety of discussion topics:

  • Announce:[342] a read-only, low frequency list used by the PC-BSD® team to make announcements to the community.
  • Commits:[343] lists commit messages as PC-BSD® code is added or modified by developers.
  • Dev:[344] for discussion related to PC-BSD® technical development.
  • Docs:[345] for communications between those who are involved, or interested in contributing to, the PC-BSD® documentation effort.
  • Installer:[346] for discussions about the backend to the pc-sysinstall utility.
  • PBI-bugs:[347] for users to report and discuss bugs found in PBI applications.
  • PBI-dev:[168] for discussions between PBI developers and users concerning PBI construction and maintenance.
  • PBIbuild:[348] lists commits as PBIs are added or modified by PBI developers.
  • Public:[351] general public list for discussion not related to the other mailing lists.
  • Support:[352] if you have a problem, you should report your issue or error messages on this list.
  • Testing:[353] for those wishing to participate in PC-BSD® beta testing and feedback.
  • Trac-bugs:[354] lists notifications about changes to PC-BSD® bug reports in Trac database.

Each mailing list includes a description of topics suitable for discussion on that list, and indicates if it is read only or available for user discussion. Anyone can read the archives of a list. If you wish to send an email to a mailing list, you will need to first subscribe to the list. The link for each mailing list provides an interface for subscribing to that list. When you send an email to the list, remember to use the mailing address that you used when you subscribed to the list.

Several of the mailing lists are archived at gmane[355]. Gmane allows you to read the archives in several different formats. It also provides RSS feeds in various formats for keeping up-to-date on new messages and topics.

In addition to the official mailing lists, there are mailing lists set up by PC-BSD® users. Many of these lists are designed for discussion in other languages. A list of alternative PC-BSD® mailing lists can be found at Google Groups[356].



FreeBSD Handbook and FAQ

PC-BSD® uses FreeBSD as its underlying operating system, so everything in the FreeBSD Handbook[92] and FreeBSD FAQ[357] applies to PC-BSD® as well. Both documents are very comprehensive and cover nearly every task you can accomplish on a FreeBSD system. They are also an excellent resource for learning how things work under the hood of your PC-BSD® system.

NOTE: Some configurations described in the FreeBSD Handbook already "just work" on your PC-BSD® system as they have been pre-configured for you. In these instances, reading that FreeBSD Handbook section can help you to understand how your system is configured and why it works.



Social Media

The PC-BSD® project maintains several social media sites to help users keep up-to-date with what is happening and to provide venues for developers and users to network with each other. Anyone is welcome to join.



Search and Portals

Many BSD related search portals exist. If you can not find the answer that you are looking for in the forums or mailing lists, try searching these websites:



Other Resources

The following BSD sites and resources may also contain useful information:



Supporting PC-BSD®

PC-BSD® is a community project and relies on involvement from its users and supporters. This section lists some ideas for becoming involved. We also have a list of Tasks Looking for People if you are looking for a specific task to assist with.


Become a Beta Tester

If you like playing around with operating systems and have a bit of spare time, one of the most effective ways you can assist the PC-BSD® community is by reporting problems you encounter while using PC-BSD®.

If you have a spare system, or virtual machine, you can also download and try out the latest alpha, beta or release candidate snapshots. These versions are still in testing and have not been officially released yet. Having as many people as possible using PC-BSD® on many different hardware configurations assists the project in finding and fixing bugs. This makes using PC-BSD® better for everyone. Subscribing to the PC-BSD® blog[57] is a good way to keep up-to-date on the availability of testing snapshots and any major bugs that are found within a snapshot.

If becoming a tester interests you, subscribe to the testing mailing list[353]. As new testing versions become available they will be announced on this list. You will also be able to see what problems other testers are finding and can check to see if the problem exists on your hardware as well. You can also subscribe to Gmane's RSS feeds[381] if you want a quick way to keep up with the subjects being discussed on the testing mailing list.

Anyone can become a beta tester. Follow these tips so that you can accurately describe your findings so they can be fixed as soon as possible:

  • before reporting a bug, search the testing mailing list to see if anyone else has reported a similar problem.
  • when reporting a new issue, use a descriptive subject that includes the error and the version of PC-BSD®. Ideally, the subject should be short (8 words or less), and contains key words about the error. An example would be "Warden on 9.2-RC1 fails to export jail".
  • ensure that the body of the bug report includes the PC-BSD® version.
  • give a short (2-3 sentences) description of how to recreate the error (e.g. when I right click a jail in warden and select Export jail to a .wdn file, it lets me select a file name, but then it freezes). If there is an error message, include its text.
  • include any other info that may be useful (e.g. this used to work on 9.1).
  • if the problem appears to be hardware related, include a copy of /var/run/dmesg.boot as this file shows the hardware that was probed the last time the PC-BSD® system booted.



Become a Translator

Figure 11.2a: The PC-BSD® Pootle Translation System

If you are interested in translating PC-BSD® into your native language, there are three translation areas that you can choose to become involved in:

1. Translate the graphical menus within the PC-BSD® operating system.

2. Translate the documentation that is published with PC-BSD®.

3. Translate the PC-BSD® website.

This section describes each of these translation areas in more detail and how to get started as a translator.

Join the Translations Mailing List

Regardless of the type of translation you are interested in, you should first join the translations mailing list[78]. When you join, send an email to introduce yourself and indicate which language(s) and which type(s) of translations you can assist with. This will allow you to meet other volunteers as well as keep abreast of any notices or updates that may affect translators.

Interface Translation

PC-BSD® uses Pootle[382] for managing localization of the menu screens used by the installer and the PC-BSD® utilities. Pootle makes it possible to find out if your native language has been fully localized for PC-BSD®. Pootle also makes it easy for users to check and submit translated text, as it provides a web editor and commenting system. This means that translators can spend their time making and reviewing translations rather than learning how to use a translation tool.

To see the status of a localization, open up the PCBSD Translation System[77] in a web browser, as seen in Figure 11.2a.
Figure 11.2b: Viewing a Language's Available Menus

The localizations PC-BSD® users have requested are listed alphabetically on the left. If your language is missing and you would like to help in its translation, send an email to the translations mailing list[78] so it can be added.

The green bar in the "Overall Completion" column indicates the percentage of PC-BSD® menus that have been localized. If a language is not at 100%, it means that the menus that currently are not translated will appear in English instead of in that language.

If you click on a language name then click on the pcbsd hyperlink under the "Name" column, you will see each menu item that is available for translation. The example shown in Figure 11.2b is for the Greek localization:

In this example, the menu for CrashHandler is complete, but the one for Life Preserver is not.

Editing a Translation

If you click on the "Review" tab, you will see a list of statistics as seen in Figure 11.2c. This page will indicate the results of Pootle's quality checks, helping translators to notice any problematic items. A description of each quality check can be found at sourceforge's translate site[383]. Some tests are more important than others so they are classified to help determine which to run first:

  • Criticalcan break a program
accelerators, escapes, newlines, nplurals, printf, tabs, variables, xmltags, dialogsizes
  • Functionalmay confuse the user
acronyms, blank, emails, filepaths, functions, gconf, kdecomments, long, musttranslatewords, notranslatewords, numbers, options, purepunc, sentencecount, short, spellcheck, urls, unchanged
  • Cosmeticmake it look better
brackets, doublequoting, doublespacing, doublewords, endpunc, endwhitespace, puncspacing, simplecaps, simpleplurals, startcaps, singlequoting, startpunc, startwhitespace, validchars
Figure 11.2c: Reviewing a Language's Quality Checks

In order to edit a translation, you will also need to create a Pootle login account. Once you are logged in to Pootle, navigate to the menu item that you wish to translate. Figure 11.2d continues the earlier example by clicking on the link for the Greek version of LifePreserver.po.

Figure 11.2d: Using the Pootle Interface to Edit a Translation String

In this example, the first string, the phrase "No Previous Backup" has been translated. Each text field (string) in the menu is numbered -- click on the hyperlink associated with the number to open that text field in the Pootle editor, or use the "Next" and "Previous" links to navigate between text fields.

For untranslated strings, you can use the "Google translate" button to suggest a translation, then fix as necessary for correctness. If a string fails a quality check, a message will indicate which check failed. For example, if the whitespace or double-spacing check fails, remove the extra space. As you translate or fix a string, click the "Add Comment" link to type in an optional comment then press the "Submit" button to save the translated text.

If you need help with a translation or using the Pootle system, you can ask for help on the translations mailing list or in the PC-BSD® Translations Forum[305].

Documentation Translation

The PC-BSD® Users Handbook is published with each version of PC-BSD®. The PC-BSD® wiki is used to create the next version of the Handbook. As new features are added to the upcoming version of PC-BSD®, they are documented on the wiki.

The wiki has been configured with the MediaWiki Translate Extension[384]. Wiki pages that are to appear in the published version of the Handbook has been marked with the translate tag so that they can be translated by translators.

In order to translate a wiki page, you must first create a wiki account and log in.

To translate a page, click the "Translate this page" link at the top of the page. This will open the translation editor. In the upper right corner, click the "Translate to English" drop-down menu to select the language you wish to translate into. Once the language is selected, click the "Edit" link next to the string to be translated. This will open an editor where you can type in the translation. You can then either click the "Save translation" button to return to the previous page or click the "Skip to next" button to go to the next string to be translated. In the example shown in Figure 11.2e, the user selected the Introduction page, clicked to translate to Russian, and has selected a paragraph to translate.

Figure 11.2e: Translating a Wiki Page

You can review the status of the translation by clicking the "Page" button at the bottom of the screen. This will display the English and the translated versions side by side.

When translating, make sure to adhere to the following rules. This is important as it ensures that the formatting of the published document is consistent across all translations.

  • do not translate any text between formatting tags which are enclosed within < > brackets.
  • do not translate the names of a command (such as pc-updatemanager) or application (such as AppCafe®).
  • do not translate the output of a command unless it appears differently in a localized version of PC-BSD®.
  • do not translate or remove any text contained between comment tags <!-- and -->.
  • do not translate template names, they appear directly after {{.

Website Translation

If you are interested in translating the PC-BSD® website, send an email to the translations mailing list[78]. Someone will introduce you to the webmaster who will get you started on website translation.



Become a Developer

If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team[385] as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the developers mailing list[344]. Once you have signed up, feel free to browse the active TODO list, or search for bugs that need fixing in the PC-BSD® [ Trac database][386]. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.

Most of the PC-BSD® specific GUI tools are developed in C++ using the QT Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.

Developers will also find the following resources helpful:

  • [Developers Development Wiki][387]
  • [GettingSource Getting PC-BSD® Source][388]



Submit PBI Requests

Is an application that you need not currently available as a PBI? Making a PBI request is an excellent way to let PBI developers know which applications are most useful to PC-BSD® users. Before requesting a PBI, please do the following:

To make your request, start a new thread in the PBI Requests Forum[286]. If this is your first forum post, you will need to use the "Register" hyperlink to create a username and password so that you can login to make your request.

NOTE: You do not need to login to read the content in the PC-BSD® forums; you do have to login in order to start a new thread or respond to an existing one.

Once you have submitted your request, click the Thread Tools link → Subscribe to this Thread and select your "Notification Type" so that you can be notified of any responses to your request. If you would like to receive notifications about all of the PBI requests in this forum, click Forum Tools → Subscribe to this Forum while in the forum.

When creating a new forum thread, include the name of the PBI you are requesting in the thread name. That way it is easy for PBI developers and other PC-BSD® users to know which applications have been requested.

People who create PBIs are subscribed to the PBI Requests forum. Usually, someone will respond to a request within a few days either indicating that they are working on creating the PBI or with an explanation if creating a PBI will be problematic. The PBI process is as follows:

  1. A user requests a PBI.
  2. Someone responds to the request and creates a PBI module.
  3. The PBI module is sent to the pbi-dev mailing list[168] so it can be added to the PBI build server.
  4. The PBI module is built on the PBI build server.
  5. Once the PBI is built, PBI testers test for basic functionality such as verifying that the application starts and its menus appear to be present and working.
  6. Once the PBI is tested, the PBI is made available in AppCafe®.
  7. The PBI request is moved from the PBI Requests Forum to the Finished PBIs forum[287].

Please note that it takes at least 2-7 days for a new PBI to go from step 3 to step 7 as it needs to be fully tested. If there is a delay, that usually means that a problem was found in the PBI and that the testers are trying to resolve the problem.



Test PBIs

The previous section indicated that new PBI modules are uploaded to the PBI build server so that they can be built and tested. This section describes the two ways you can assist in testing PBIs.
Figure 11.6a: Viewing the Status of PBIs on the Build Server

Test PBIs Waiting for Approval

If you wish to help test a PBI before it has been approved, go to the build server[391] as shown in Figure 11.6a.

Find the name of the PBI you wish to test in the "Module" column and click its hyperlink. You can then download the file with the .pbi extension. Once downloaded, run pbi_add /path/to/pbi to install the PBI. If you find any problems with the PBI, send an email to the PBI-dev[168] mailing list describing how to recreate the problem. Include the text of any error messages you receive.

Investigate or Fix a Failed Build

You can try to resolve PBI modules that have a "Build Status" of "FAILED". If you click on the name of a failed module, you can download the file named last_100.log for that module. This file is in ASCII text so it can be viewed in any text editor.

If you think you know the cause of the problem after reading the error messages, you can review the PBI's module by clicking its "git" hyperlink. If you decide to copy/paste a file in order to edit it locally, click the "Raw" link for the file.

If you make an edit to correct the problem, send the modified file (or a diff) to the PBI-dev[168] mailing list so the changes can be uploaded to the build server.



Create PBIs

PC-BSD® provides a unique file format known as a PBI (push button installer). PBI files end with the .pbi extension and are self-contained installation programs. This means that even novice users can safely install and uninstall PBIs without inadvertently overwriting or deleting files needed by the operating system or other applications.

PBI Module Components

This section describes the various components that comprise a PBI module. A PBI module is simply a collection of files which controls the contents of the PBI.

When creating a PBI module, create a directory on your computer to hold the module's components. For example, if you are creating a PBI module for firefox, create the directory as the superuser using this command:

mkdir -p /usr/local/my_pbis/www/firefox

As you create the subdirectories and files needed by the PBI module, save them to that directory. This directory is referred to as %%PBI_APPDIR%%. The rest of this section assumes that you are the superuser.

LICENSE File

If the application requires the user to read a license agreement, save that license as a file named LICENSE in your %%PBI_APPDIR%%. This file is optional unless the underlying port is restricted and requires the user to accept a license in order to install and use the software.

pbi.conf

The pbi.conf file is mandatory. It is a simple shell script that contains the information needed to build the PBI. Typically this file requires you to modify a few simple variables, such as the name of the program, its location in the ports tree, and the name of its icon. Sometimes you will need to set a few additional variables in order to make sure that required dependencies are included in the PBI. If you get stuck when creating your own pbi.conf, you can view the pbi.conf file for every PBI module in the PC-BSD® repository[390].

Here is an example of the pbi.conf file for firefox. When creating your file, modify the text in red to meet the needs of the PBI.

#!/bin/sh

# PBI Build Configuration # Place over-rides and settings here # # XDG Desktop Menu Spec: # http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html ############################################################################## # Program Name PBI_PROGNAME="Firefox"

# Program Website PBI_PROGWEB="http://www.mozilla.com"

# Program Author / Vendor PBI_PROGAUTHOR="The Mozilla Foundation"

# Default Icon (Relative to %%PBI_APPDIR%% or resources/) PBI_PROGICON="share/pixmaps/FireFox-128.png"

# The target port we are building PBI_MAKEPORT="www/firefox"

# Additional options for make.conf PBI_MAKEOPTS="PACKAGE_BUILDING=Y WITH_CUPS=yes WITH_GECKO=libxul"

# Ports to build before / after PBI_MKPORTBEFORE="" PBI_MKPORTAFTER="audio/esound x11-fonts/dejavu x11-themes/qtcurve-gtk2 devel/gconf2 x11/libXScrnSaver www/gecko-mediaplayer www/firefox-i18n"

# do not include the PBI_BUILDKEY or PBI_AB_PRIORITY options # as the correct values will be added for you when the PBI is added to the build server PBI_BUILDKEY="06" PBI_AB_PRIORITY="50"

export PBI_PROGNAME PBI_PROGWEB PBI_PROGAUTHOR PBI_PROGICON PBI_MAKEPORT PBI_MAKEOPTS PBI_MKPORTBEFORE PBI_MKPORTAFTER PBI_BUILDKEY PBI_AB_PRIORITY

Table 11.7a describes the most commonly used variables. When creating your pbi.conf file, refer to the FreeBSD port's Makefile and pkg-descr to determine which values to use.

Table 11.7a: Commonly Used pbi.conf Variables [tables 27]
Variable Description
PBI_PROGNAME= mandatory; should be the same value as PORTNAME= in the port's Makefile, but capitalized
PBI_PROGWEB= mandatory unless does not exist; should be the same value as WWW= in the port's pkg-descr
PBI_PROGAUTHOR= mandatory; often found in the port's pkg-descr or at the website for the application
PBI_PROGICON= mandatory path, relative to %%PBI_APPDIR%%, to application icon file in .png format
PBI_PROGREVISION= bump up a PBI's revision number; useful when rebuilding a port with new PBI specific options
PBI_MAKEPORT= mandatory; the path to the port within /usr/ports/
PBI_MAKEOPTS= optional; set this to the options that you want saved to make.conf for the port building process (e.g. WITH_CUPS=YES)
PBI_MKPORTBEFORE= optional; port(s) to build before building the PBI
PBI_MKPORTAFTER= optional; port(s) to build after building the PBI
PBI_BUILDKEY= should not be included; this variable is used on the PBI build server to force the rebuild of a PBI that has failed to build
PBI_REQUIRESROOT= set to to YES to require this app to be installed as root; default is NO which allows it to be installed as a regular user
PBI_EXCLUDELIST= list of files or directories to exclude from the final archive, such as ./include or ./share
PBI_AB_PRIORITY= may be set by build server administrator; a higher number indicates a greater priority and will be built before lower priority PBIs
PBI_AB_NOTMPFS= set to YES to disable using tmpfs when doing auto-builds on a server
PBI_HASH_EXCLUDES= set to a space delimited list of files to exclude from merging into the shared hash-dir
export mandatory; followed by a list of all of the variables that will be included when the PBI is built

external-links

The optional external-links file contains a list of targets to link into the system's LOCALBASE at PBI installation time. This is useful for placing binaries and files in the user's PATH. This file is usually not needed as most binaries and files are auto-detected and automatically placed in the LOCALBASE.

Example 11.7a shows an example usage:

Example 11.7a: Example external-links File

# Files to be Sym-Linked into the default LOCALBASE

# One per-line, relative to %%PBI_APPDIR%% and LOCALBASE # Defaults to keeping any existing files in LOCALBASE


# TARGET LINK IN LOCALBASE ACTION #etc/rc.d/servfoo etc/rc.d/servfoo keep #include/libfoo.h include/libfoo.h replace #etc/rc.d/servfoo etc/rc.d/servfoo keep

bin/firefox3 bin/firefox3 binary,nocrash

The flags in the "ACTION" column are as follows:

  • keep: if this file already exists in LOCALBASE, do not overwrite it
  • replace: replace this file in LOCALBASE if it exists
  • binary: this file is an executable
  • nocrash: used for binary files; do not display crash handler if program exits with non-0 status
  • linux: used for binary files; indicates that this is a Linux application, and needs to be run with Linux compat

resources/

The resources/ directory can contain extra files you wish copied into the PBI application directory. This is often the best place for icons and other files not included with a port.

scripts/

This directory can contain the following scripts:

  • post-install.sh: script run immediately after the extraction of PBI contents to disk
  • post-portmake.sh: script run during building of the PBI file, after the port compile is finished
  • pre-portmake.sh: script run during building of the PBI file, prior to the port compile
  • pre-install.sh: script run before installation of the PBI; return non-0 to halt installation
  • pre-remove.sh: script run before deletion of the PBI file

Table 11.7b summarizes the variables that may be used in these scripts:

Table 11.7b Supported Variables [tables 28]
Variable Description
PBI_PROGNAME= mandatory; should be the same value as PORTNAME= in the port's Makefile, but capitalized
PBI_PROGDIRNAME= name of the subdirectory that is created for the PBI in /usr/pbi/ (e.g. "firefox-amd64" for the 64-bit Firefox PBI)
PBI_PROGDIRPATH= full path to the PBI install directory (e.g. /usr/pbi/firefox-amd64/ for the 64-bit Firefox PBI)
PBI_PROGVERSION= version of the program - should be the same value as the DISTVERSION in the port's Makefile
PBI_RCDIR= location of rc.d/ directory used by PBIs, usually /usr/local/etc/rc.d
SYS_LOCALBASE= LOCALBASE of the default system, typically /usr/local
PBI_FAKEBIN_DIR= the binary wrapper directory, typically /usr/pbi/<pbidir>/.sbin/

xdg-menu/ and xdg-desktop/

The xdg-menu/ and xdg-desktop/ directories can be used to supply menu and desktop icons, respectively. The file that you place in these directories should be in the format pbiname.desktop. Example 11.7b shows the firefox.desktop files for the firefox PBI:

Example 11.7b: firefox.desktop File

more xdg-menu/firefox.desktop

#!/usr/bin/env xdg-open [Desktop Entry] Value=1.0 Type=Application Name=FireFox GenericName=FireFox Exec=%%PBI_EXEDIR%%/firefox %U Path=%%PBI_APPDIR%% Icon=%%PBI_APPDIR%%/share/pixmaps/FireFox-128.png StartupNotify=true Categories=Network;

more xdg-desktop/firefox.desktop #!/usr/bin/env xdg-open [Desktop Entry] Value=1.0 Type=Application Name=FireFox GenericName=FireFox Exec=%%PBI_EXEDIR%%/firefox %U Path=%%PBI_APPDIR%% Icon=%%PBI_APPDIR%%/share/pixmaps/FireFox-128.png

StartupNotify=true

%%PBI_EXEDIR%% should reference the PBI's executable and any required switches.

For more details on the XDG menu specifications, please refer to the freedesktop specifications[392].

xdg-mime/

The xdg-mime/ directory is used to register file associations according to the freedesktop MIME specs[393]. This requires the creation of an XML file. The example shown in Figure 11.7c adds the MIME information for gimp, so that it can be available as an application choice in a web browser:

Example 11.7c: Gimp MIME Info

more xdg-mime/gimp-xdg.xml

<?xml version="1.0"?> <mime-info xmlns='http:////www.freedesktop.org/standards/shared-mime-info'>  <mime-type type="application/x-gimp">   <comment>Gimp File</comment>    <glob weight="100" pattern="*.xcf"/>    <glob weight="100" pattern="*.XCF"/>  </mime-type>

</mime-info>

Creating a New PBI with pbi_makeport

Once you have created the files needed by your PBI module, use the built-in pbi_makeport command to convert the FreeBSD port to a PBI module.

Before attempting to build the PBI, make sure that the FreeBSD ports collection is installed. If /usr/ports/ does not exist or is empty, the ports collection is not installed. To install the ports collection either use Control Panel → System Manager → Tasks → Fetch Ports Tree or type portsnap fetch extract.

To build the PBI, make sure that you are in %%PBI_APPDIR%% then specify where to place the built PBI and the port to build the PBI from, as seen in this example:

pbi_makeport -o /usr/local/my_pbis archivers/cabextract

Fetching FreeBSD chroot environment... This may take a while... <snip build output> ===> Compressing manual pages for cabextract-1.4 ===> Registering installation for cabextract-1.4 ===> Cleaning for cabextract-1.4 Checking for Linux libraries to copy... Creating PBI: cabextract-1.4 Creating Stage Dir: /usr/pbi/cabextract-amd64/.stagedir Creating external link entries... Creating xdg scripts... Creating install script... Creating deinstall script... Creating hash list... Creating compressed archive... Created PBI: /pbiout/cabextract-1.4-amd64.pbi Cleaning /usr/pbi/cabextract-amd64

Cleaning /usr/pbi/cabextract-amd64.chroot

The first time you run the pbi_makeport command, a clean chroot environment will automatically download and install. This chroot environment will be used for all PBI builds.

NOTE: Each time you run pbi_makeport, it cleans up its environment, including all of the files that it downloaded and built. Since you may have to rebuild your PBI after testing it, you can save re-downloading and re-building all of these files again by including the --pkgdir <dir> option. You can manually remove that directory when you are finished if you need to save disk space.

FreeBSD ports may contain build dependencies, runtime dependencies, and required libraries. When building a PBI, pbi_makeport automatically compiles all of the required dependencies. When the build is finished, it prunes the build dependencies before packaging the PBI file, leaving only the runtime packages and libraries that are required for the program to work. This means that any files which are included in the PBI are necessary for the program to run, and manually removing them will cause the program to fail.

After the PBI build has finished, two files should be created in the specified directory: the PBI itself and its SHA256 checksum.

ls /usr/local/my_pbis cabextract-1.4-amd64.pbi cabextract-1.4-amd64.pbi.sha256

Use the pbi_add command to verify the information about the PBI.

pbi_add -i /usr/local/my_pbis/cabextract-1.4-amd64.pbi

PBI Information for: cabextract-1.4-amd64 -----------------------------------------------------> Name: cabextract RootInstall: NO Version: 1.4 Built: 20120829 144309 Prefix: /usr/pbi/cabextract-amd64 Author: Website: Arch: amd64 FbsdVer: 9.1-RELEASE CreatorVer: 1.0 ArchiveCount: 498 ArchiveSum: b75ef8fe699bfed50ad28b058f26af3e685915b5c2330951e2802f891a5b4a85 Signature: Not Signed

AutoUpdate: NO

Once the process completes and a PBI is built successfully, it is very important to test the PBI, especially if the intent is to submit it for inclusion in AppCafe. Even quality control for your own sake is good because it will aid in learning the PBI build process. It will be easier to make corrections while everything is still fresh in your mind and little else has changed.



Purchase PC-BSD® Swag

While PC-BSD® is free, some users may wish to purchase media or other items to show their support for the PC-BSD® Project. PC-BSD® items are available from the following websites:

  • FreeBSD Mall:[394] sells PC-BSD® DVDs and subscriptions, stickers, The Definitive Guide to PC-BSD®, and apparel.
  • Amazon: sells The Definitive Guide to PC-BSD® (hard copy and Kindle formats) as well as the Kindle versions of the PC-BSD® Handbook. Items available for purchase in your country may vary.



Become an Advocate

So you love PC-BSD®? Why not tell your family, friends, fellow students and colleagues about it? You will not be the only one that likes a virus-free, feature-rich, no-cost operating system. Here are some suggestions to get you started:

  • Burn a couple of DVDs and pass them out. If your school or user group has an upcoming event where you can promote PC-BSD®, you can request additional DVDs from sales at pcbsd dot com.
  • Consider giving a presentation about PC-BSD® at a local community event or conference. Let us know about it and we will help you spread the word.
  • Write a personal blog detailing your journey from your first PC-BSD® install experience to your most recent accomplishment. The blog could also be used to teach or explain how to perform tasks on PC-BSD®. A regional language blog may help build the community in your area and to find others with similar interests.


References


  1. https://creativecommons.org/licenses/by/3.0/deed.en
  2. https://www.ixsystems.com/
  3. http://www.freebsdfoundation.org
  4. http://www.pcbsd.org/
  5. http://www.freebsd.org/
  6. http://www.ixsystems.com/
  7. http://www.freebsd.org/doc/en/books/handbook/linuxemu.html
  8. 8.0 8.1 http://en.wikipedia.org/wiki/ZFS
  9. 9.0 9.1 http://www.openbsd.org/faq/pf/
  10. 10.0 10.1 http://www.ossec.net/
  11. 11.0 11.1 http://www.fail2ban.org/wiki/
  12. 12.0 12.1 https://www.ixsystems.com/ix/support/software/pc-bsd-support
  13. http://www.freebsd.org/releases/9.2R/relnotes.html
  14. 14.0 14.1 http://aria2.sourceforge.net/
  15. https://github.com/pcbsd/
  16. http://trac.pcbsd.org/wiki/GettingSource
  17. https://wiki.freebsd.org/PEFS
  18. http://gsmartcontrol.berlios.de/home/index.php/en/About
  19. http://en.wikipedia.org/wiki/S.M.A.R.T.
  20. https://www.virtualbox.org/
  21. 21.0 21.1 http://www.virtualbox.org/manual/ch04.html
  22. http://en.wikipedia.org/wiki/Berkeley_Software_Distribution
  23. http://e2fsprogs.sourceforge.net/
  24. http://www.catacombae.org/hfsx.html
  25. http://www.ufsexplorer.com/download_stdr.php
  26. http://www.freebsd.org/doc/en/articles/explaining-bsd/comparing-bsd-and-linux.html
  27. http://www.freebsd.org/doc/en/articles/linux-comparison/article.html
  28. http://www.freebsd.org/doc/en/articles/linux-users/index.html
  29. http://www.over-yonder.net/~fullermd/rants/bsd4linux/01
  30. http://www.freebsd.org/advocacy/whyusefreebsd.html
  31. http://www.unixmen.com/bsd-for-human-beings-interview/
  32. http://www.youtube.com/watch?v=xk6ouxX51NI
  33. http://www.freebsd.org/doc/en/articles/bsdl-gpl/article.html
  34. http://bhami.com/rosetta.html
  35. http://www.leidinger.net/blog/2010/09/28/the-freebsd-linuxulator-explained-for-users/
  36. http://www.freebsd.org/releases/9.1R/hardware.html#PROC
  37. https://github.com/Bumblebee-Project/Bumblebee/wiki/FAQ
  38. http://www.freebsd.org/releases/9.1R/hardware.html#WLAN
  39. https://wiki.freebsd.org/dev/ath_hal%284%29/HardwareSupport
  40. http://www.freebsd.org/releases/9.2R/hardware.html
  41. http://laptop.bsdgroup.de/freebsd/
  42. http://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface
  43. http://thinkwiki.org
  44. http://www.freebsd.org/doc/en/books/handbook/configtuning-sysctl.html
  45. http://www.freebsd.org/cgi/query-pr.cgi?pr=kern/160838
  46. 46.0 46.1 http://blog.pcbsd.org/2010/11/looking-for-ndis-testers-freebsd-and-pc-bsd/
  47. http://forums.freebsd.org/showpost.php?s=63c71cacb981215c14b64b74481d17cd&p=100670&postcount=17
  48. http://wiki.freebsd.org/AsusEee
  49. http://wiki.freebsd.org/TuningPowerConsumption
  50. http://www.freebsd.org/doc/en/books/handbook/device-hints.html
  51. http://wiki.freebsd.org/AppleMacbook
  52. http://refit.sourceforge.net/
  53. http://en.wikipedia.org/wiki/Boot_Camp_(software)
  54. 54.0 54.1 http://en.wikipedia.org/wiki/
  55. http://sourceforge.net/projects/partedmagic
  56. http://www.freebsdmall.com/cgi-bin/fm/scan/su=yes/fi=prod_bsd/sf=sku/sf=title/sf=category/se=pcbsd
  57. 57.0 57.1 57.2 http://blog.pcbsd.org/
  58. http://pcbsd.org/en/support/
  59. http://pcbsd.org/en/download.html
  60. http://www.fastsum.com/
  61. http://www.kde.org/applications/multimedia/k3b/
  62. 62.0 62.1 http://projects.gnome.org/brasero/
  63. 63.0 63.1 http://goodies.xfce.org/projects/applications/xfburn
  64. http://windows.microsoft.com/en-US/windows7/Burn-a-CD-or-DVD-from-an-ISO-file
  65. http://www.imgburn.com/
  66. http://infrarecorder.org/
  67. https://launchpad.net/win32-image-writer
  68. 68.0 68.1 http://www.7-zip.org/
  69. 69.0 69.1 http://www.virtualbox.org/
  70. http://www.virtualbox.org/wiki/Downloads
  71. https://www.virtualbox.org/wiki/Downloads
  72. http://vmware.com/
  73. http://en.wikipedia.org/wiki/Microsoft_Virtual_PC
  74. http://www.parallels.com/
  75. http://wiki.freebsd.org/VirtualBox
  76. http://www.freebsd.org/doc/en/books/handbook/acpi-debug.html
  77. 77.0 77.1 http://pootle.pcbsd.org/
  78. 78.0 78.1 78.2 78.3 78.4 http://lists.pcbsd.org/mailman/listinfo/translations
  79. http://open-vm-tools.sourceforge.net/about.php
  80. http://en.wikipedia.org/wiki/GUID_Partition_Table
  81. http://www.solarisinternals.com/wiki/index.php/ZFS_Evil_Tuning_Guide
  82. http://wiki.freebsd.org/ZFSTuningGuide
  83. http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide
  84. http://download.oracle.com/docs/cd/E19253-01/819-5461/index.html
  85. http://blogs.oracle.com/video/entry/becoming_a_zfs_ninja
  86. https://blogs.oracle.com/bonwick/entry/rampant_layering_violation
  87. http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide#ZFS_Storage_Pools_Recommendations
  88. http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide#RAIDZ_Configuration_Requirements_and_Recommendations
  89. 89.0 89.1 http://wiki.freebsd.org/PEFS
  90. http://forums.pcbsd.org/
  91. http://trac.pcbsd.org/browser/build-files/ports-overlay/misc/trueos-base/Makefile list
  92. 92.0 92.1 http://www.freebsd.org/doc/en/books/handbook/
  93. 93.0 93.1 93.2 http://www.freebsd.org/doc/en/books/handbook/pkgng-intro.html
  94. https://github.com/pcbsd/pcbsd/raw/master/src-sh/pc-extractoverlay/ports-overlay/usr/local/etc/pkg/fingerprints/pcbsd/trusted/pkg.cdn.pcbsd.org.20131209
  95. http://trac.pcbsd.org/browser/build-files/ports-overlay/misc/trueos-base/Makefile
  96. http://iso.cdn.pcbsd.org/9-STABLE/amd64/
  97. http://www.freshports.org/x11-wm/
  98. http://library.gnome.org/misc/release-notes/2.32/
  99. http://www.pkgdemon.com/support/install-pcbsd-testing
  100. http://projects.gnome.org/eog/
  101. http://projects.gnome.org/epiphany/
  102. 102.0 102.1 http://projects.gnome.org/totem/
  103. http://projects.gnome.org/evolution/
  104. http://live.gnome.org/Nautilus
  105. http://gnome-look.org/
  106. http://kde.org/
  107. http://docs.kde.org/stable/en/kdegraphics/gwenview/index.html
  108. http://docs.kde.org/development/en/extragear-graphics/digikam/index.html
  109. http://docs.kde.org/stable/en/applications/konqueror/index.html