handbook_ja_ver9_1

include[PRINT_PCBSD_Handbook_9_1_Cover] [PRINT_PCBSD_Handbook_9_1_Preface] Table of Contents

1 Introduction

1.1 Goals and Features

1.2 What's New in 9.1

1.3 PC-BSD? Releases

1.4 PC-BSD? for Linux Users

1.4.1 Filesystems

1.4.2 Device Names

1.4.3 Feature Names

1.4.4 Commands

1.4.5 Additional Resources

2 Pre-Installation Tasks

2.1 Hardware Requirements

2.1.1 Minimum System Requirements

2.1.2 Recommended System Requirements

2.1.3 Supported Processors

2.1.4 Supported Video Cards

2.1.5 Wireless Cards

2.1.6 Checking Hardware Compatibility

2.2 Laptops

2.2.1 ThinkPads with Known Bugs

2.2.2 Acer Laptops with Known Bug

2.2.3 MacBooks

2.2.4 Touch Screens

2.3 Partitioning the Hard Drive

2.3.1 Shrinking a Drive in Windows 7

2.3.2 Using Parted Magic to Create a Primary Partition

2.4 Obtaining PC-BSD?

2.4.1 Selecting Which File to Download

2.4.2 Data Integrity Check

2.5 Burning the Installation Media

2.5.1 Burning the CD/DVD ISO File on Windows

2.5.1.1 Windows 7 Disc Image Burner

2.5.1.2 InfraRecorder

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

2.5.2.1 K3B

2.5.2.2 Brasero

2.5.2.3 growisofs

2.5.3 Burning the CD/DVD ISO File on a Mac OSX System

2.5.4 Writing an IMG File to USB

2.5.4.1 Writing the IMG File on a Linux or BSD System

2.5.4.2 Writing the IMG File on a Windows System

2.5.4.3 Writing the IMG File on a Mac OSX System

2.6 PC-BSD? Live Mode

2.7 Using VirtualBox

2.7.1 Creating a Virtual Machine

2.7.1.1 Configuring the Network Adapter

2.7.1.2 Configuring the Storage Device

2.7.2 Installing VirtualBox Guest Additions

2.7.3 Using the Downloadable VirtualBox or VMWare Disk

2.7.4 Troubleshooting VirtualBox

3 Installing PC-BSD?

3.1 Starting the PC-BSD? Installation

3.2 Language Selection Screen

3.3 System Selection Screen

3.4 Disk Selection Screen

3.4.1 Basic Mode

3.4.2 Advanced Mode

3.4.2.1 UFS Layout

3.4.2.2 ZFS Overview

3.4.2.3 ZFS Layout

3.4.3 FreeBSD Expert Mode

3.5 Installation Progress Screen

3.6 Installation Finished Screen

4 Post Installation Configuration and Installation Troubleshooting

4.1 Booting Into PC-BSD?

4.1.1 If You Encrypted a Filesystem

4.1.2 If Your Display is Not Automatically Detected

4.1.3 Fast Boot

4.1.4 Creating a Custom Boot Theme

4.2 Language Screen

4.3 Time Zone Selection Screen

4.4 Set Root Password Screen

4.5 Create a User Screen

4.6 Connect to a Wireless Network

4.7 Post Install Finished Screen

4.8 Logging In

4.8.1 Welcome & Getting Started

4.9 Installation Troubleshooting

4.9.1 Installation Starts But Fails

4.9.2 System Does Not Boot Into the Installer

4.9.3 USB Keyboard Does Not Work in Installer

4.9.4 Getting Help

5 Advanced Installation Topics

5.1 Install a Server

5.2 Dual Booting

5.2.1 Choosing the Installation Partition

5.2.2 Choosing a Boot Manager

5.2.3 GAG, The Graphical Boot Manager

5.2.4 GRUB

5.2.4.1 Adding PC-BSD? to Legacy GRUB

5.2.4.2 Adding PC-BSD? to GRUB Version 2

5.2.5 Dual Boot with Windows Using EasyBCD

5.2.6 Recovering Windows Boot loader After Installing PC-BSD?

5.3 Multiple Boot Environments

5.3.1 Managing Boot Environments

5.4 Upgrading PC-BSD?

5.4.1 Using Update Manager

5.4.2 Using the Command Line

5.5 Creating an Automated Installation with pc-sysinstall

5.5.1 Determine Which Variables you Wish to Customize

5.5.2 Create a Customized Configuration

5.5.3 Create a Custom Installation Media or Installation Server

6 Desktops

6.1 GNOME2

6.2 KDE4

6.3 LXDE

6.4 XFCE4

6.4.1 Editing the Menu

6.4.2 XFCE Plugins

6.5 Awesome

6.6 Enlightenment

6.7 evilwm

6.8 Fluxbox

6.9 FVWM

6.10 i3

6.11 IceWM

6.12 Openbox

6.13 Ratpoison

6.14 spectrwm

6.15 WindowLab

6.16 Window Maker

6.16.1 Working with the Dock

6.16.2 DockApps

7 Installing Applications and Keeping PC-BSD? Updated

7.1 Using AppCafe?

7.1.1 Installing and Uninstalling PBI Software

7.1.2 Updating Installed PBIs

7.1.3 Preferences

7.1.4 Repositories

7.2 PBI Manager

7.2.1 pbi_add(1)

7.2.2 pbi_addrepo(8)

7.2.3 pbi_autobuild(8)

7.2.4 pbi_browser(1)

7.2.5 pbi.conf(5)

7.2.6 pbi_create(1)

7.2.7 pbi_create(1)

7.2.8 pbi_delete(1)

7.2.9 pbi_deleterepo(8)

7.2.10 pbi_icon(1)

7.2.11 pbi_indextool(1)

7.2.12 pbi_info(1)

7.2.13 pbi_listrepo(1)

7.2.14 pbi_makepatch(1)

7.2.15 pbi_makeport(1)

7.2.16 pbi_makerepo(1)

7.2.17 pbi_metatool(1)

7.2.18 pbi_patch(1)

7.2.19 pbi_update(1)

7.2.20 pbi_update_hashdir(1)

7.2.21 pbid(8)

7.3 Update Manager

7.4 Meta Package Manager

7.4.1 Finding, Installing, and Uninstalling Meta-Packages

7.4.2 Upgrading Meta-Packages

7.5 Create Your Own PBI Repository

7.5.1 Generate the Signing Key

7.5.2 Create the Repository

7.5.3 Generate the Repository's Meta-Data

7.5.4 Configure the Automatic Build of Updated Ports

8 Control Panel

8.1 EasyPBI

8.1.1 Creating a PBI Module

8.1.2 Build the Module

8.1.3 Test and Fine-Tune the Module

8.1.3.1 pbi.conf

8.1.3.2 Resources

8.1.3.3 Desktop/Menu Entries

8.1.3.4 External-Links

8.1.4 Submit the Module

8.2 About

8.3 Active Directory & LDAP

8.3.1 Connecting to Active Directory

8.3.2 Connecting to an OpenLDAP Server

8.4 Hardware Compatibility

8.5 GDM Configuration

8.6 Service Manager

8.7 System Manager

8.7.1 Generating a Diagnostic Report

8.7.2 Setting an Update Mirror

8.7.3 Install/Uninstall Desktops and System Components

8.7.4 Install FreeBSD Source and Ports

8.7.5 Set Miscellaneous Options

8.8 User Manager

8.9 Bluetooth Manager

8.10 Mount Tray

8.10.1 Mounting USB Drives

8.10.2 Accessing Data on Non-PCBSD Partitions

8.11 Sound Configuration

8.11.1 Troubleshooting Sound

8.12 Display

8.12.1 Desktop Effects, Compiz, and Compositing

8.12.2 Troubleshooting

8.13 Printing

8.13.1 Researching your Printer

8.13.2 Adding a Printer

8.13.3 Manually Adding a Driver

8.13.4 Printer Troubleshooting

8.14 Scanner

8.15 Network Configuration

8.15.1 Devices: Ethernet Adapters

8.15.2 Devices: Wireless Adapters

8.15.3 Network Configuration (Advanced)

8.15.4 Proxy Settings

8.15.5 Troubleshooting Network Settings

8.15.5.1 Useful Files and Commands

8.15.6 If a Driver Does Not Exist

8.15.7 Known Issues

8.16 Firewall Manager

8.17 Adobe Flash Player Preferences

8.18 Life Preserver

8.18.1 Creating a Backup Schedule

8.18.2 Configuration Options

8.18.3 Restoring a Backup

8.19 Warden?

8.19.1 Creating a Jail using Warden?

8.19.1.1 Traditional or Ports Jail

8.19.1.2 Linux Jail

8.19.2 Managing Jails

8.19.2.1 Info Tab

8.19.2.2 Tools Tab

8.19.2.3 Snapshots Tab

8.19.2.4 Packages Tab

8.19.2.5 Right-Click Menu

8.19.2.6 Importing a Jail

8.19.3 Using the Command Line Version of Warden?

8.19.4 Managing Software Not Available in Packages Tab

8.19.4.1 Installing FreeBSD Packages Within a Traditional or Ports Jail

8.19.4.2 Compiling FreeBSD Ports Within a Traditional or Ports Jail

8.19.4.3 Keeping Software Up-to-Date

9 Using PC-BSD?

9.1 Java, Flash, and Fonts

9.1.1 Java

9.1.2 Adobe Flash

9.1.3 Installing Custom Fonts

9.1.3.1 Using KDE

9.1.3.2 Using GNOME

9.1.3.3 Using XFCE

9.1.3.4 Using Other Desktops

9.1.3.5 From the Command Line

9.2 Multimedia

9.3 Files and File Sharing

9.3.1 File Managers and File Structure

9.3.2 Samba

9.3.2.1 Using the Samba Client

9.3.2.2 Configuring the Samba Server

9.3.2.2.1 Edit smb.conf Manually

9.3.2.2.2 Create Shares Using SWAT

9.4 MythTV

9.4.1 Running MythTV for the First Time

9.5 XBMC

9.6 Windows Emulation

9.6.1 Installing and Using Wine

9.7 Remote Desktop

9.7.1 Connecting to Another Computer With RDP

9.7.1.1 Preparing the Remote System

9.7.1.2 Connecting with KDE's KRDC

9.7.1.3 Connecting with VNC

9.7.2 Allowing Another Computer to Connect Using Desktop Sharing

9.8 Thin Client

9.8.1 Creating a PXE Boot Desktop Server

9.8.1.1 Connecting to the PXE Boot Desktop Server

9.8.1.2 Uninstalling the PXE Boot Desktop Server

9.8.2 Creating a PXE Boot Install Server

9.8.2.1 Connecting to and Customizing the PXE Boot Install Server

9.9 ownCloud

9.9.1 Install and Start the Required Services

9.9.2 Configuring ownCloud

9.10 Security

9.11 Accessibility

9.11.1 GNOME Accessibility Tools

9.11.2 KDE Accessibility Tools

10 Finding Help

10.1 PC-BSD? Forums

10.2 IRC Channel

10.3 Mailing Lists

10.4 FreeBSD Handbook and FAQ

10.5 Social Media

10.6 Search and Portals

10.7 Other Resources

11 Supporting PC-BSD?

11.1 Become a Beta Tester

11.2 Become a Translator

11.3 Become a Developer

11.4 Report Bugs

11.4.1 Application Packaging Bug

11.4.2 Application Runtime Bug

11.4.3 System Driver Bugs

11.4.4 System Installation Bugs

11.5 Submit PBI Requests

11.6 Test PBIs

11.7 Create PBIs

11.7.1 PBI Module Components

11.7.1.1 LICENSE File

11.7.1.2 pbi.conf

11.7.1.3 external-links

11.7.1.4 resources/

11.7.1.5 scripts/

11.7.1.6 xdg-menu/ and xdg-desktop/

11.7.1.7 xdg-mime/

11.7.2 Creating a New PBI with pbi_makeport

11.7.3 Testing the PBI

11.8 Purchase PC-BSD? Swag

11.9 Host a Mirror

11.10 Seed a Torrent

11.11 Become an Advocate

Preface

written by users of the PC-BSD? operating system.

Version 9.1

Published November 30, 2012

Welcome to PC-BSD?! This Handbook covers the installation and use of PC-BSD? 9.1. 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 the PC-BSD? wiki 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.pcbsd.org/pub/handbook/.

The PC-BSD? Users Handbook is freely available for sharing and redistribution under the terms of the Creative Commons Attribution License. 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. If you wish to use the PC-BSD? logo in your own works, ask for permission first from marketing@ixsystems.com.

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.

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

1 Introduction

Welcome to PC-BSD?!

PC-BSD? began in 2005 when Kris Moore presented the first beta version of a FreeBSD 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, a graphical package management system, and dozens of graphical utilities that make PC-BSD? suitable for desktop use. As a user of PC-BSD?, you don?t have to worry about configuring a FreeBSD system for desktop use; instead you can simply install and start using it.

The main difference between PC-BSD? and FreeBSD is that PC-BSD? is geared towards desktop use, while FreeBSD has been created with server use in mind. Other differences include:

�E PC-BSD? pre-configures at least one desktop manager during installation

�E PC-BSD? is installed by a graphical installer rather than a text based
   installer

�E the PC-BSD? installer supports additional features such as configuring ZFS
   and encryption during installation

�E PC-BSD? provides a graphical software management system

�E PC-BSD? provides a Control Panel of graphical utilities for configuring the
   system

�E PC-BSD??s rc.conf and sysctl.conf have been tweaked for a desktop
   environment

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

The rest of this section discusses:

�E Goals and Features

�E What's New in 9.1

�E PC-BSD? Releases

�E PC-BSD? for Linux Users

1.1 Goals and Features

Designed with the desktop computer user in mind, PC-BSD? provides the following features:

�E Easy installation: to install PC-BSD?, simply insert the installation
   media, reboot the system to start the installer, and answer a few questions
   in the graphical menus.

�E Automatically configured hardware: video, sound, network and other devices
   are automatically configured for you.

�E Intuitive desktop interface: PC-BSD? comes with a choice of desktop
   environments to support your day-to-day computing needs.

�E Easy software management: with AppCafe?, installing, upgrading, and
   uninstalling software is safe and easy.

�E Lots of software available: in addition to its own software, PC-BSD? can
   install software that has been ported to FreeBSD (currently nearly 24,000
   applications).

�E 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. It is also able to run many Windows applications
   using Wine.

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

�E Virus-free: PC-BSD? is not affected by viruses, spyware and other malware.

�E No defragmentation: PC-BSD? hard drives do not need to be defragmented and
   do not slow down over time. PC-BSD? also supports ZFS which is a
   self-healing filesystem.

�E Architecture support: PC-BSD? is available for 32-bit and 64-bit systems.

�E Laptop support: provides power saving and swap space encryption and
   automatically switches between wired and wifi network connections.

�E Secure environment: PC-BSD? provides a pre-configured PF firewall,
   brute-force attack protection with OSSEC, and a Host-based Intrusion
   Detection System with Fail2ban.

�E Easy system administration: PC-BSD? provides a Control Panel containing
   many graphical tools for performing system administration tasks.

�E Localization: PC-BSD? supports a number of native languages and locales.

�E Vibrant community: PC-BSD? has a friendly and helpful support community.

�E Professional support: professional email and phone support is available
   from iXsystems.

1.2 What's New in 9.1

The following features have been added to or improved for PC-BSD? 9.1:

�E Based on FreeBSD 9.1, which includes improved Intel video support. The
   Release Notes for FreeBSD 9.1 list the new features and drivers introduced
   in FreeBSD 9.1.

�E The PC-BSD? installer has been revamped to separate pre-installation tasks
   from post-installation tasks. This makes it easier to automate the roll-out
   of multiple installations because the end-user can configure their account
   information and display settings before logging in for the first time.

�E The PC-BSD? installer now sets its default settings according to the
   hardware installed. 64-bit systems containing over 2GB of RAM will default
   to the ZFS filesystem whereas 32-bit systems and any system containing less
   than 2GB of RAM will default to UFS+SUJ. Systems containing more than 2GB
   of RAM will default to the KDE desktop and all other systems will default
   to the LXDE desktop. A hardware compatibility icon within the installer
   allows the user to see at a glance if their video card, Ethernet card,
   wireless card, and sound card are compatible with PC-BSD?.

�E The PC-BSD? installer now provides a wizard to install either a vanilla
   FreeBSD server or a TrueOS server. In addition to the base FreeBSD system
   provided by a vanilla FreeBSD server installation, the TrueOS server
   edition adds the command line versions of PBI Manager, Update Manager, and
   Warden?.

�E The ability to perform a network install has been removed from the
   graphical installer. The scriptable back-end still provides the variables
   needed for network installations.

�E The ZFS section of the PC-BSD? installer now allows you to set ZFS
   properties such as compression and quotas, create datasets, and import
   existing ZFS pools.

�E Multiple Boot Environments support allows systems formatted with ZFS to
   create alternate bootable snapshots. These can be used for testing purposes
   or to create a bootable backup of the boot environment before performing an
   upgrade.

�E Warden? is now built into the operating system and available through
   Control Panel. It can now be used to manage multiple jails.

�E Warden? now supports the creation of three types of jails: traditional
   FreeBSD jails for running network services, (a less secure) ports jail for
   safely installing and running FreeBSD ports/packages from your PC-BSD?
   system, and the installation of Linux within a jail.

�E Warden? now supports the management of ZFS snapshots on a per-jail basis.

�E  has been integrated into Warden?. Combined with the meta-package support,
   it is now easier than ever to install software into a jail and to keep that
   software up-to-date.

�E AppCafe? now shows the number of available PBIs and supports automatic
   updating.

�E EasyPBI is now available through Control Panel, making it easier than ever
   to convert existing FreeBSD ports to PC-BSD? PBIs.

�E An About icon has been added to the Control Panel, making it easy to
   determine the PC-BSD? version, which desktops, and the version of X that
   have been installed.

�E A Hardware Compatibility icon has been added to the control panel,
   providing a quick overview of detected hardware devices.

�E The GDM Configuration GUI has been added to Control Panel and can be used
   to configure auto-login and remote login through XDMCP.

�E A Mount Tray icon has been added to the Control Panel and System Tray,
   allowing easy access to USB drives.

�E A Sound Configuration icon has been added to the Control Panel and can be
   used to test sound or change the default audio device.

�E Network Configuration manager now supports 802.1x authentication over
   Ethernet networks.

�E Life Preserver now provides a browse button when creating an include or
   exclude filter.

�E Thin Client now allows you to create a PXE Boot Desktop Server or a PXE
   Boot Installation Server.

�E Bluetooth Manager has been added to the System Tray.

�E PC-BSD? Live Mode is now a USB-only, read/write image.

�E When ZFS formatting during installation, gnop 4K alignment is now used when
   creating the zpool. This results in a dramatic increase in performance. For
   this reason, it is recommended that users with existing ZFS installations
   re-install rather than upgrade in order to receive these performance
   benefits.

1.3 PC-BSD? Releases

As of September 2008, PC-BSD? release version numbers are the same as those for FreeBSD. When the first number of a release is followed by a zero (e.g. version 9.0), this means that this version of PC-BSD? introduces many new features. When the second number of a release is not a zero (e.g. version 9.1), this means that the new version may have some new features, but it mostly fixes known software problems and security vulnerabilities. If a release includes the letters RC, this means that it is a ?Release Candidate?, or that the developers are still adding and fixing features and need testers to help them find any existing problems in preparation for the upcoming release. If the release includes the word BETA, it means that that version is still buggy and needs the help of testers to find as many problems as possible so that they can be fixed.

NOTE: if you want to use PC-BSD? (not test it), you should install the most recent release (i.e. the one with the highest number), not a BETA or RC version.

PC-BSD? releases follow the same EoL (end of life) schedule as the underlying FreeBSD release. Any security patches for a supported release will appear in Update Manager, making it easy to keep your PC-BSD? system fully patched against known security vulnerabilities.

1.4 PC-BSD? for Linux Users

PC-BSD? is based on BSD Unix, 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.

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

�� Filesystem�� Native to �� Type of non-native �� Usage notes �� support �� Btrfs ��Linux ��none �� exFAT ��Windows ��r/w support loaded �� by default �� EXT2 ��Linux ��r/w support loaded �� by default �� since EXT3 journaling is not �� supported, you will not be �� r/w support loaded ��able to mount a filesystem �� EXT3 ��Linux ��by default ��requiring a journal replay �� unless you fsck it using an �� external utility such as �� e2fsprogs �� EXT3 journaling, extended �� attributes, and inodes greater�� EXT4 ��Linux ��r/o support loaded ��than 128-bytes are not �� by default ��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 OSX ��none ��older Mac versions might work �� with hfsexplorer �� 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 �� r/o support is �� included in Linux �� kernel 2.6.5 ��changed to r/o support in Mac �� UFS ��PC-BSD? ��onwards; ��Lion �� r/w support on Mac; �� UFS Explorer can be �� used on Windows �� check if your Linux �� distro provides �� UFS+S ��PC-BSD? ��ufsutils; ��changed to r/o support in Mac �� r/w support on Mac; ��Lion �� UFS Explorer can be �� used on Windows �� check if your Linux �� distro provides �� UFS+J ��PC-BSD? ��ufsutils; ��changed to r/o support in Mac �� r/w support on Mac; ��Lion �� UFS Explorer can be �� used on Windows �� XFS ��Linux ��r/o support is �� loaded by default �� PC-BSD?, �� Linux port �� ZFS ��OpenSolaris �� Mac support is under �� development ��

1.4.2 Device Names

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

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

�E BSD disk names differ from Linux. IDE drives begin with ad and SCSI and USB
   drives begin with da.

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

Figure 1.4b: Names for BSD and Linux Features

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

1.4.4 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

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

1.4.5 Additional Resources

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

�E Comparing BSD and Linux

�E FreeBSD: An Open Source Alternative to Linux

�E FreeBSD Quickstart Guide for Linux? Users

�E BSD vs Linux

�E Why Choose FreeBSD?

�E Interview: BSD for Human Beings

�E Video: BSD 4 Linux Users

�E Why you should use a BSD style license for your Open Source Project

3 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. You can also try PC-BSD? without installing it by using a Live version.

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:

�E Starting the PC-BSD? Installation

�E Language Selection Screen

�E System Selection Screen

�E Disk Selection Screen

�E Installation Progress Screen

�E Installation Finished Screen

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

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:

Figure 3.1a: PC-BSD? Installer Boot Menu

[Install1b]

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 for certain BIOS's 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.

3.2 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

[Installer1]

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

�E access Hardware Compatibility information

�E read that screen's Help text

�E use the onscreen keyboard

�E switch between the US keyboard layout and a user selected layout

�E abort the installation

�E navigate to a previous or upcoming screen

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. 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 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? button to go to the next installation screen.

3.3 System Selection Screen

The ?System Selection? screen, shown in Figure 3.3a, allows you to select the system components and window managers to install with PC-BSD?.

The default selection 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. The arrow buttons can be used to browse through the primary window managers or to install a FreeBSD or TrueOS server instead of a PC-BSD? desktop. Before leaving this screen, click the "Customize" button to review a larger selection of desktops and system components to install. If you 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 Panel ? System Manager ? System Packages.

Figure 3.3a: System Selection Screen

[Installer2b]

In the example shown in Figure 3.3b, the user clicked ?Components? then right-clicked Development ? Development-Science to view the packages to be installed with this component.

Figure 3.3b: Browsing Additional System Components

[Installer2d]

The following components are available for installation.

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

�E Development: software utilities suited for developers. These include the
   valgrind debugging tool, QT development tools, CMake, GNU make, Subversion,
   and git.

�E 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 (for older NVIDIA cards). If you have an older NVIDIA
   video card or a HP printer, check the applicable box to install the
   required drivers.

�E Misc: if you expand the + you can select from the following: Compiz, the
   MythTV DVR, VMwareGuest, VirtualBox Guest additions, and the XBMC media
   center.

�E Unsupported-Desktops: additional light-weight desktops for expert users. If
   you expand the + you can select from Awesome, Enlightenment, evilWM, FVWM,
   i3, IceWM, Openbox, Ratpoison, spectrwm, WindowLab, or Window Maker.

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.

3.4 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. On systems with less than 2GB of RAM, that drive will be formatted with the UFS+SUJ filesystem. On systems with 2GB or RAM or more, that drive will be formatted with the ZFS filesystem.

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.

Figure 3.4a: Disk Selection Screen

[Installer3]

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.

Figure 3.4b: Disk Setup Wizard

[Installer3a]

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

�E Basic: (default) select this mode if you wish to specify which partition or
   disk to install to or if you wish to encrypt user data.

�E Advanced: select this mode if you wish to specify the installation
   partition or disk, use GPT partitioning, encrypt user data, disable the
   FreeBSD boot menu, or specify the filesystem to use and the layout of that
   filesystem.

�E FreeBSD Expert: select this mode if you prefer to drop down to a shell to
   manually enter the commands to setup your disk.

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.

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

3.4.1 Basic Mode

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

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.

Figure 3.4c: Select a Disk or Partition

[Installer3b]

Once you have selected the disk and partition, click ?Next? to see the screen shown in Figure 3.4d.

Figure 3.4d: Encrypt Data Screen

[Installer3c]

If you wish to encrypt the data in your home directory, check the box labelled ?Encrypt user data?. This option will automatically encrypt all of the data stored in /usr, including the home directories of all of the users that you create. If you decide to encrypt, review the section if you encrypted a filesystem for instructions on how to enter your passphrase at system bootup.

If you check this box, enter and confirm a passphrase. You will be prompted to enter this passphrase whenever you boot into PC-BSD?. This means that if someone else boots your computer, they will not be able to boot into PC-BSD? if they do not know your passphrase. However, if you forget your passphrase, you will not be able to access PC-BSD? either. For these reasons, it is important to choose a good passphrase that other users will not guess and which you will not forget. Passphrases are case-sensitive and can contain spaces. The passphrase should be memorable to you, such as a line from a song or piece of literature, but hard to guess in that people who know you should not be able to guess your favorite line from a song or piece of literature.

NOTE: be careful if you have changed your keyboard variant and layout. At this time, the GELI encryption framework only supports QWERTY passphrases, so do not use any characters not found on a QWERTY keyboard in your passphrase. DO NOT set a passphrase with accents or special characters which are not found on a US keyboard. This is a limitation in FreeBSD as the keymap is not loaded until after the passphrase is entered, meaning that such a passphrase will render that partition as inaccessible.

It is important to remember to make a backup copy of your keys either to another system or to a removable media such as a USB thumb drive. You should do so after your first boot into PC-BSD?. The keys are located in /boot/keys/, so that is the directory that you should backup.

Once you click ?Next?, the wizard will 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.

3.4.2 Advanced Mode

If you select advanced mode, the wizard will again display the screen shown in Figure 3.4c. This time, that screen has the addition of a checkbox:

Partition disk with GPT: GPT 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. It has been reported that some Linux distros do not understand UFS partitions that use GPT. When in doubt, leave this box unchecked.

NOTE: if you plan to dual boot with LILO or legacy GRUB, do not check the GPT box. These bootloaders do not support the GPT format.

After making your selections click ?Next? to access the filesystem selection screen shown in Figure 3.4e.

This screen allows you to choose from the following filesystem types:

�E UFS: the Unix File System is the original filesystem used by BSD systems.
   This is the default selection on systems with less than 2GB of RAM.

�E ZFS: this filesystem was originally developed by Sun and adds many
   features. You can learn more about ZFS at Wikipedia and the FreeBSD
   Handbook. This is the default selection on systems with more than 2GB of
   RAM and, due to ZFS RAM requirements, is not available for selection on
   systems with less than 2GB of RAM.

Figure 3.4e: Selecting the Filesystem

[Installer3f]

This screen also provides the following checkbox:

�E Install bootable MBR: this option displays the FreeBSD boot manager when
   the system boots. This is a simple and non-configurable boot manager which
   may or may not detect other operating systems installed on the computer. If
   you plan to only boot into PC-BSD? or to configure an alternate boot
   manager, you can uncheck this box.

The rest of this section demonstrates how to customize the UFS or ZFS layout.

3.4.2.1 UFS Layout

If you select UFS and click ?Next?, the default UFS layout will be displayed, as seen in the example in Figure 3.4f. In this example, a 12GB disk has four partitions with mount points for /, SWAP, /var, and /usr. The actual sizes of the partitions created by the default layout will vary, depending upon the size of the disk, but always follow this logic:

�E the default size of / (root) will be 2 GB; this partition holds the root
   user's home directory as well as the files needed by the operating system.
   You should not use a size less than 1 GB. Do not store large files in the
   root user's home directory as the root partition is meant to be reserved
   for the operating system files.

�E the default size of the swap partition will be RAM (physical memory) size
   times 2 up to a maximum of 4GB. You can increase this if you want a larger
   swap partition (also known as a paging file or virtual memory in Windows),
   though this is not necessary as PC-BSD? has a built-in Swap Extender Daemon
   (swapexd) that monitors how much swap space is available on the system.
   When the operating system is running out of swap space, swapexd attempts to
   create a new, larger swap file. When the operating system no longer needs
   so much swap space, swapexd decreases the size of the swap file.

NOTE: if your hardware uses a solid state drive instead of a hard drive (e.g. an Asus Eee Netbook), do not create a swap partition as swap will shorten the life of the solid state drive. swapexd will not create a swap file if you do not create one during installation.

�E the default size of /var will be 2 GB. This partition holds data that
   varies such as logs, printer queues, and the FreeBSD packages database. You
   can safely increase the size of this partition, though this is usually not
   needed on a desktop system.

�E the rest of the disk space will go to /usr. This partition holds everything
   else, such as users' home directories and installed applications.

Figure 3.4f: Default UFS Layout

[Installer3h]

The UFS+SUJ means that this version of UFS adds a light version of journaling to soft updates as described in this technical paper. This is the default filesystem type as it virtually eliminates the need to run fsck. In practical terms, this means that even if the system is not cleanly shutdown (e.g. because of a power outage), it will still boot up quickly without losing any data.

If you right-click any partition other than /, you can select to "Enable Encryption". A pop-up box will prompt for the passphrase. When the system boots, you will be prompted for the passphrase for each partition that you encrypt, so be sure to remember the passphrases and to backup your encryption keys as described in the Basic Mode section.

Three buttons are provided should you wish to modify the default layout:

�E Add: this button will remain greyed out as long as there is no free space
   to work with. If free space is available, this button can be used to add a
   partition. It will prompt you for the name of the mount point and size of
   the new partition.

�E Resize: allows you to decrease or increase (if free space is available) the
   size of the highlighted partition.

�E Remove: will delete the highlighted partition. This can be used to create
   free space in order to recreate that partition at a smaller size or to
   increase the size of the remaining partitions.

If you decide to change the default partitions, keep the following points in mind:

�E You must have a / partition to hold the operating system; make sure it is
   at least 1 GB in size.

�E Unless your system has a solid state drive, you want a swap partition.

�E You can have one big root partition (plus a swap partition). If you decide
   to do this, the installation will create /var and /usr directories as they
   are needed by applications. This is often discouraged on server systems,
   but is an option on desktop systems.

�E You can remove /usr and divide the newly created free space into multiple
   partitions. For example, some users like to create separate partitions to
   hold their video files, artwork, work files, etc. When creating multiple
   partitions, use names that makes sense to you (e.g. /usr1, /usr2 or /video,
   /work) and set sizes that makes sense for the amount of content each
   partition will hold. If you decide to take this approach, you should still
   make a good sized /usr (otherwise it will be placed on root which will
   quickly fill up the / partition). The size of /usr should be sufficient to
   store any software you install.

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.

3.4.2.2 ZFS Overview

ZFS is a combined filesystem and logical volume manager originally designed by Sun Microsystems. It was ported to FreeBSD and has been part of the operating system since FreeBSD 7.0.

ZFS provides many features including: support for high storage capacities, snapshots and copy-on-write clones, 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 provides an excellent starting point to learn about its features. These resources are also useful to bookmark and refer to as needed:

�E ZFS Evil Tuning Guide

�E FreeBSD ZFS Tuning Guide

�E ZFS Best Practices Guide

�E ZFS Administration Guide

�E Becoming a ZFS Ninja (video)

�E blog post explaining how ZFS simplifies the storage stack

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 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 disks, creating a redundant copy should one 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 can not 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.

3.4.2.3 ZFS Layout

If you select ZFS and click ?Next?, the disk setup wizard allows you to configure your ZFS layout. The default layout is seen in Figure 3.4g.

Figure 3.4g: ZFS Configuration

[Zfs2a]

If you wish to format the hard drive or partition that you selected in Figure 3.4c with ZFS, leave the "Enable ZFS mirror/raidz mode" box unchecked and click "Next" to go to the "Encrypt user data" screen shown in Figure 3.4d. Unlike UFS, which only encrypts /usr/, selecting encryption for ZFS encrypts the entire pool. In other words, it encrypts the entire selected disk or partition, except for a small, UFS /boot partition.

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.4g, the system has 7 disks, all of which are the same size. The first disk, ada0, was pre-selected in Figure 3.4c 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. At this time, encryption is not supported for multiple disk configurations.

If you have never configured a RAIDZ before, take the time to read the RAIDZ Configuration Requirements and Recommendations 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 decrease storage capacity and performance of the ZFS system.

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

�E mirror: requires a minimum of 2 disks.

�E RAIDZ1: requires a minimum of 3 disks. For best performance, 3, 5, or 9
   disks are recommended.

�E RAIDZ2: requires a minimum of 4 disks. For best performance, 4, 6, or 10
   disks are recommended.

�E 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.4h.

Figure 3.4h: Default ZFS Layout

[Installer3g]

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

You can use the ?Add? button to add additional mount points. You will only be prompted for the name of the mount point as, unlike UFS, 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.

NOTE: do not remove any of the default mount points as they are used by PC-BSD?.

If you right-click any mount point (other than /swap), you can toggle between enabling or disabling any of the following ZFS properties. For performance reasons, the PC-BSD? installer will not allow you to remove or modify /swap.

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

�E canmount: if set to ?off?, the filesystem can not be mounted.

�E checksum: automatically verifies the integrity of the data stored on disks.
   Setting this property to ?off? is highly discouraged.

�E compression: if set to ?on?, automatically compresses stored data to
   conserve disk space.

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

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

3.5 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 20 and 40 minutes.

Figure 3.5a: Installation Progress Screen

[Installer4]

3.6 Installation Finished Screen

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.

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

[Installer5a]

4 Post Installation Configuration and Installation Troubleshooting

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

If you are dual-booting PC-BSD?, you may need to first add an entry to your boot loader menu. The section on Dual Booting describes how to add a PC-BSD? entry to the GAG, GRUB, and EasyBCD boot loader programs.

The first time PC-BSD? boots, a background script checks the PC-BSD? mirror servers and automatically configures the system to use the fastest mirror. If you find that you have connectivity issues using AppCafe? or Update Manager, it may mean that your default mirror is temporarily unavailable. You can change the mirror setting in System Manager ? Mirrors.

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.

�E Booting Into PC-BSD?

�E Language Screen

�E Time Zone Selection Screen

�E Set Root Password Screen

�E Create a User Screen

�E Connect to a Wireless Network

�E Post Install Finished Screen

�E Logging In

�E Installation Troubleshooting

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

Unless you unchecked the ?Install bootable MBR? option in the advanced mode of the disk setup wizard, you will see a FreeBSD boot menu similar to this one when you first boot up:

F1 FreeBSD

F6 PXE Boot: F1

Your FreeBSD boot menu may vary if other operating systems are installed on the computer or if your system does not support PXE booting. By default, the computer will automatically boot into PC-BSD? (FreeBSD) after a few seconds unless you press another function key listed in the boot menu.

NOTE: if another boot manager is installed on the system, see the section on Dual Booting for instructions on how to add a PC-BSD? entry to the GAG, GRUB, or EasyBCD boot menu programs.

After a few seconds, the boot should continue and you will be presented with the graphical PC-BSD? boot menu, shown in Figure 4.1a.

If you press any key, this screen will pause, allowing you to read and select the desired options. Otherwise, it will pause for a few seconds then continue to load PC-BSD? with the default options.

There are 6 boot options and 4 actions to choose from:

1 Disable ACPI: ACPI controls power management but may be problematic on some hardware. Select this option if you are unable to boot into PC-BSD?.

2 Enable Safe Mode: select this option if the installation hangs when probing your hardware. 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) disable the use of ACPI and APICs.

3 Enter single user mode: advanced users can use this option to fix critical system failures.

4 Enable 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 a piece of hardware.

5 Run X in VESA mode: select this option if PC-BSD? is unable to load your video driver. PC-BSD? will default to VESA mode which should work on any system with a video card.

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

Press the number of an option to select that option. As you make a selection, the FreeBSD bobble-head icon will be filled in, indicating that that option has been selected. To de-select an option, press its number again.

Figure 4.1a: PC-BSD? Graphical Boot Menu

[Boot1]

Once you have made your selection(s), you can choose from the following actions:

B Boot PC-BSD? with above options: starts PC-BSD? with the selected options enabled.

D Restore default options: clears your selections.

L Escape to loader prompt: advanced users can select this option to perform advanced operations, such as changing kernels or loading kernel modules. This prompt provides a limited set of commands which are described here.

R Reboot: reboots the computer.

As the system continues to boot, the PC-BSD? splash screen will appear. If you prefer to watch the boot messages, press any key.

4.1.1 If You Encrypted a Filesystem

If you checked the box ?Encrypt user data? during PC-BSD? installation, the boot process will pause, waiting for you to input your passphrase. Press enter at the splash screen so that you can see the message, similar to the one shown in Figure 4.1b, in order to type your passphrase.

Figure 4.1b: Prompt to Enter Passphrase

[Encrypt]

A * should appear for each character that you type, so type slowly and make sure that each keystroke is accepted. If you do not enter the passphrase correctly, this message indicates that you should try again:

GEOM_ELI: Wrong key for ada01se. Tries left: 2.

Once the correct passphrase is entered, you will see a message similar to the following and the boot sequence will proceed.

GEOM_ELI: Device ada01se.eli created. GEOM_ELI: Encryption: AES-XTS 128 GEOM_ELI: Crypto: software

4.1.2 If Your Display is Not Automatically Detected

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 now play a short video. You can press Esc to skip the video and move on to the Language screen of the post-installation process.

If you instead select ?No?, or if for some reason the installer is unable to find the optimal display settings, you will instead see the ?Display Settings? screen shown in Figure 4.1c.

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.

Figure 4.1c: Display Settings Wizard

[Display1]

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

fastboot_enable="YES" fastboot_earlyrc="/etc/rc.d/netif /etc/rc.d/moused /etc/rc.d/dhclient /etc/rc.d/pf /etc/rc.d/routing /etc/rc.d/devd /usr/local/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, remove the path to that service in the fastboot_earlyrc line of /etc/rc.conf, 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 changing the "YES" to a "NO" in the fastboot_enable line of /etc/rc.conf.

4.1.4 Creating a Custom Boot Theme

If you would like to change the image in the graphical boot loader, create a PCX image file. It is important that the file is saved in .pcx format as that is the only image format that the boot loader understands. Additionally, the image must be 640 x 480 pixels and 16 colors. The RGB colors that will be available in the menu text will be taken from the image's palette.

The default PC-BSD? graphical boot theme is found in /boot/themes/default/. To create your own theme, create a new directory in /boot/themes/ (e.g. mkdir / boot/themes/mytheme) and copy your PCX file to that new subdirectory.

Next, copy /boot/themes/default/theme.conf to your new subdirectory. Open the copied file and edit this line to point to the location of your PCX file:

theme_background="/boot/themes/default/bglogo.pcx"

You can change the theme's colors by editing the RGB values in this file. You can also change the font by modifying the theme_font path to point to the font to use. Finally, you can change the locations of the list of options and the actions menu. These are defined with the *_xy settings in the configuration file. The value must be two numbers which specify the X and Y coordinates in pixels, relative to the upper left corner.

To enable your theme, modify this line in /boot/loader.conf to point to the location of your theme.conf file:

beastie_theme="/boot/themes/default/theme.conf"

4.2 Language Screen

Once the system has completed its boot, an introductory video will play. You can press the Escape key if you wish to skip the video. If you wish to watch the video at a later time, it is located in /usr/local/share/pcbsd/movies/.

Once the video finishes, the language selection screen will again be displayed, as seen in Figure 4.2a.

Figure 4.2a: Language Selection Screen

[Installer6]

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.

4.3 Time Zone Selection Screen

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.

Figure 4.3a: Select Time Zone

[Installer7]

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

4.4 Set Root Password Screen

This configuration screen, seen in Figure 4.4a, requires you to set the root or administrative password.

The system password, also known as the root, superuser, or administrative password, is required for system administration tasks such as installing server software, setting up your printer, or changing settings that affect all users. You will need to remember this password for the times that you are prompted for it. 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

[Installer8]

4.5 Create a User Screen

This screen is used to create the user account that you will use to login to your system.

NOTE: do not login to the system using the root user account. The system has been designed to prompt your user account for the administrative password when it 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:

�E Name: this value will be displayed in the login screen. It can be your full
   name and can contain capital letters and spaces.

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

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

Figure 4.5a: User Creation Screen

[Installer9]

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

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.

Figure 4.6a: Connect to a Wireless Network

[Connect]

4.7 Post Install Finished Screen

The screen in Figure 4.7a indicates that the post-installation setup is complete. Click the ?Finish? button to access the login menu.

Figure 4.7a: Setup is Complete

[Installer10]

4.8 Logging In

Once you have finished setting up your system, you will be presented with the login screen seen in Figure 4.8a:

Figure 4.8a: PC-BSD? Login Screen

[Login1]

The Username that you created in the Create a User Screen will be listed (in this example, it is dru).

NOTE: while the GDM login manager will let you do it, logging in as the root user is STRONGLY DISCOURAGED. If you do login as root, you run the risk of overflowing the / filesystem and will be required to type in the full path of binaries. Instead, login as the user account that you created and input the administrative 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 the administrative password before performing a task that requires root permissions. PC-BSD? will have its own login manager in version 9.2 which will prevent users from logging in as the root user.

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.

Figure 4.8b: Universal Access Preferences

[Login3]

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.

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

Figure 4.8c: Login Menu with User Selected

[Login2]

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 the ?System Packages? tab of System Manager.

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

4.8.1 Welcome & Getting Started

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

Figure 4.8d: PC-BSD? Getting Started Screen

[Start1]

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.

4.9 Installation Troubleshooting

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

4.9.1 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 to the Support mailing list.

4.9.2 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 can not 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

[Welcome]

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.

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

4.9.4 Getting Help

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

5 Advanced Installation Topics

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

�E Install a Server

�E Dual Booting

�E Multiple Boot Environments

�E Upgrading PC-BSD?

�E Creating an Automated Installation with pc-sysinstall

5.1 Install a Server

The System Selection screen of the PC-BSD? installer can be used to install a FreeBSD-based server operating system, rather than a PC-BSD? desktop operating system. This screen provides two server options:

�E FreeBSD Server: installs a basic, vanilla installation of FreeBSD. While
   the installation routine is different, the end result is the same as if one
   had installed FreeBSD from a FreeBSD media as it results in a minimal,
   command-line only FreeBSD server installation.

�E 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 of additional shells and
   utilities.

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

�E the ability to easily configure ZFS during installation

�E the ability to configure encryption during installation

�E the ability to configure ZFS multiple boot environments

�E 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, click the left arrow until either FreeBSD or TrueOS is selected. In the example shown as in Figure 5.1a, the user has selected TrueOS? and the FreeBSD option is to the left of the selection.

Figure 5.1a: Selecting to Install TrueOS?

[Freebsd1c]

Once selected, press ?Next? to start the ?Server Setup Wizard?. The wizard is the same for either a FreeBSD or a TrueOS? installation. Click ?Next? to see the screen shown in Figure 5.1b.

Input and confirm the root password which will be used for administrative or superuser access to the server, then click ?Next? to proceed to the screen shown in Figure 5.1c.

Figure 5.1b: Set the Root Password

[Freebsd1b]

Figure 5.1c: Create the Primary User Account

[Freebsd2a]

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:

�E Name: can contain capital letters and spaces.

�E Username: the name used when logging in. Can not contain spaces and is case
   sensitive (e.g. Kris is a different username than kris).

�E Password: the password used when logging in. You must type it twice in
   order to confirm it.

�E 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.1d.

Figure 5.1d: Set the Hostname

[Freebsd3a]

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

Figure 5.1e: Configure the Network

[Freebsd4a]

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

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

�E AUTO-DHCP: will configure every active interface for DHCP and for IPv4

�E IPv6-SLAAC: will configure every active interface for DHCP and for 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.1f.

Figure 5.1f: Install Source or Ports

[Freebsd5a]

If you wish to install FreeBSD source or ports, check the associated box(es) then click ?Finish? to exit the wizard.

If you are installing TrueOS?, you can use the ?Customize? button to install server meta-packages. This screen, shown in Figure 5.1g, can be used to install packages such as MySQL, PostgreSQL, Samba, PHP, VirtualBox, Apache, and Lighttp.

When you have saved your selections, click ?Next? to proceed to the Disk Selection screen in order to configure the system's disk(s).

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 is an excellent reference for performing common FreeBSD server tasks.

Figure 5.1g: Installing Server Applications into TrueOS?

[Apps]

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

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

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

�E a backup of any existing data. This backup should not be stored on your
   computer's hard drive but on another computer or on a 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.

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

If you install PC-BSD? on a computer that already contains an operating system, the first time you reboot, your computer will automatically boot into the previous operating system. You will need to configure a boot loader utility to recognize all of the operating systems that are installed and to provide you with a boot menu where you can select which operating system to boot into.

5.2.2 Choosing a Boot Manager

When selecting a boot manager, choose the one that best suits your needs or which is already installed on the computer.

If GRUB is already installed on the system, review the GRUB section before installing PC-BSD? in order to determine which version of GRUB is installed. Legacy GRUB does not support GPT or ZFS. Depending upon your hardware, the installer may automatically select GPT or ZFS for you. You will need to change your layout to UFS and make sure that the "Partition disk with GPT" checkbox is unchecked while in the Disk Selection Screen of the installer. If GRUB version 2 is installed, you can select the installer's default partitioning layout as GRUB version 2 supports all of the disk options available during a PC-BSD? installation.

If you will be dual booting with Windows, EasyBCD is easy to install graphical application for configuring a customized boot menu. This boot manager supports all of the disk options available during a PC-BSD? installation, including ZFS and GPT. EasyBCD has also been localized into 13 languages, making it a good choice for localized boot menus.

GAG provides an easy to configure boot manager for loading any operating system. However, it does not support GPT or ZFS. This means that you will need to change your layout to UFS and make sure that the "Partition disk with GPT" checkbox is unchecked while in the Disk Selection Screen of the installer.

The rest of this section will demonstrate how to configure the GAG, GRUB, and EasyBCD boot loaders.

5.2.3 GAG, The Graphical Boot Manager

GAG is a versatile boot manager, capable of booting many different operating systems. Once you have finished installing all of your operating systems, you can configure GAG to present you with a boot menu containing an entry for each operating system.

After downloading and unzipping GAG, burn the cdrom.iso file to a CD. Insert the CD and reboot the system to configure GAG. You will be presented with the initial GAG screen, shown in Figure 5.2a.

NOTE: your mouse will not work in GAG. Instead, use the key representing the number or letter of the option that you wish to select.

Press 4 in order to ?Install GAG?. The next screen will prompt you to choose your keyboard type by pressing the associated number key. The next screen will prompt you to choose your language by pressing the associated number or letter key. Once your selections have been made, you will see a screen similar to Figure 5.2b.

Figure 5.2a: Initial GAG Screen

[Gag1]

Figure 5.2b: Press the S Key to Configure GAG

[Gag4]

Press S to ?Setup GAG? and see the screen shown in Figure 5.2c.

Figure 5.2c: GAG's Main Configuration Menu

[Gag5]

Press A to ?Add a new Operating System?. GAG will display an entry for each operating system installed on the computer.

NOTE: if you are dual-booting with Linux, GAG will not find the Linux installation unless GRUB or lilo is installed in the / or /boot partition of the Linux system.

Press the letter associated with the operating system name. Your PC-BSD? entry will probably be displayed as ?A5h FreeBSD?. When you press the associated letter, a pop-up menu will prompt you to type a description which will be shown in the boot menu. Type in something that is useful to you, such as ?PC-BSD? 9.1?. When you press enter, you will be prompted to type in a password or to press return for no password. If you decide to type in a password, you will need to input this password whenever you wish to boot into that operating system.

Once you press enter, you will see the screen shown in Figure 5.2d.

Press the letter representing the icon that you wish to associate with the operating system--it will be displayed next to the description in the boot menu. For example, you could press F to associate the FreeBSD Beastie icon next to the ?PC-BSD? 9.1? description. Once you press enter, you will be returned to the main menu. Press A again to add another operating system and repeat this process for each operating system that you wish to boot.

When you are finished, press H to ?Save in Hard disk?. You should receive a pop-up message indicating that ?GAG installed successfully?. You can now press R to ?Return to main menu?. Note that the screen shown in Figure 5.2b now contains the entries for the operating systems that you added. Remove the CD and press the key associated with the operating system that you wish to boot.

Now, whenever you reboot your system, this same menu will appear. It will always contain the S option so that you can add or delete operating system entries, set the boot passwords, or set the boot timer.

Figure 5.2d: Selecting an Icon for the Boot Menu Entry

[Gag7]

5.2.4 GRUB

Many Linux distros use GRUB as the boot loader. This section shows you how to add PC-BSD? to an existing GRUB menu.

There are two versions of GRUB that are in use. To see which version your Linux distro is using, boot into the Linux system and use the --version option to the grub command line tool:

sudo grub grub> grub --version

If the version number is less than 1, you are using legacy GRUB; otherwise you are using GRUB version 2.

If you are using GRUB version 2, run the ls command within grub to determine the names of the disks and partitions that can be seen by GRUB. This will help you determine which drive options to use when setting the root option in the examples shown in Adding PC-BSD? to GRUB Version 2. The output of this command will vary depending upon your disk layout and the naming scheme used by the Linux distro. When you are finished using grub, type quit to leave the utility.

grub> ls grub> quit

5.2.4.1 Adding PC-BSD? to Legacy GRUB

NOTE: legacy GRUB does not support the GPT format. When you are in the Disk Selection screen of the PC-BSD? installer, select Advanced Mode and make sure that the ?Partition disk with GPT? checkbox is unchecked.

Here is an example of adding a PC-BSD? entry to a Linux distro that is using legacy GRUB:

title PCBSD 9.1 root (hd0,1) kernel /boot/loader

�E title: this will be the text that is shown in the boot menu and can be
   anything that makes sense to you.

�E root: the root of the partition containing PC-BSD?, as determined by the ls
   command described in the previous section. In this example, PC-BSD? is
   installed on the first hard disk hd0 and on the second partition ,1.
   Depending upon your distro and where you installed PC-BSD?, the ouput of ls
   on your system may differ.

�E kernel: used to load the primary boot image. For FreeBSD and PC-BSD?,
   always use /boot/loader.

For more information about legacy GRUB, refer to the GRUB Legacy Manual.

5.2.4.2 Adding PC-BSD? to GRUB Version 2

GRUB version 2 supports both the MBR and GPT formats.

In this example, PC-BSD? is installed on the third primary partition of the first hard drive using the MBR format:

menuentry "PCBSD 9.1" { insmod ufs2 set root=(hd0,2,a) kfreebsd /boot/loader }

Where:

�E menuentry: the text between the quotes will be displayed in the boot menu
   and can be anything that makes sense to you.

�E insmod: some distros require this instruction to load the UFS2 kernel
   module.

�E set root: the root of the partition containing PC-BSD?, as determined by
   the ls command described in the previous section. Always add the a at the
   end to refer to the BSD boot partition on the specified disk and partition.

�E kfreebsd: used to load the primary boot image. For FreeBSD and PC-BSD?,
   always use /boot/loader.

The entry for the same installation (third partition on first drive), but with the GPT box checked, will differ slightly in the set root line.

menuentry "PCBSD 9.1" { insmod ufs2 set root=(hd0,msdos2,bsd1) kfreebsd /boot/loader }

If you installed PC-BSD? onto the second hard drive, you need to invoke the map and chainloader commands in order to boot from the second disk. In this example, PC-BSD? is installed in the first partition of the second drive and the box to partition disk with GPT was not checked.

menuentry "PC-BSD? 9.1" { map (hd0) (hd1) map (hd1) (hd0) map --hook chainloader (hd0,0)/boot0 boot }

The entry if the GPT box was checked looks like this:

menuentry "PC-BSD? GPT" { map (hd0) (hd1) map (hd1) (hd0) map --hook chainloader (hd0,0)/pmbr boot }

If you installed ZFS, several modules need to be loaded. Here is a sample entry with the GPT box checked:

menuentry "PC-BSD? 9.1" {

        insmod zfs
        search -s -l tank0
        kfreebsd /freebsd@/boot/kernel/kernel
        kfreebsd_module_elf /freebsd@/boot/kernel/opensolaris.ko
        kfreebsd_module_elf /freebsd@/boot/kernel/zfs.ko
        kfreebsd_module /freebsd@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache
        set kFreeBSD.vfs.root.mountfrom=zfs:tank0/freebsd

}

After a GRUB2 configuration change you need to run a command to update the configuration. This command varies by distro:

�E sudo update-grub on a Debian-based system

�E grub2-mkconfig -o /boot/grub2/grub.cfg as the superuser under Fedora 16 or
   Gentoo

�E grub-mkconfig -o /boot/grub/grub.cfg when using Sabayon

For more information please refer to the GNU GRUB Manual.

5.2.5 Dual Boot with Windows Using EasyBCD

EasyBCD was developed by the non-profit NeoSmart Technologies to make it easy to add other operating system entries to the the Windows boot loader. EasyBCD allows you to add entries for multiple Windows installations as well as Linux, BSD, and Mac OS X. EasyBCD provides both a paid version and a free version for limited, non-commercial use.

After booting into Windows, download and install the latest version of EasyBCD. Once installed, launch EasyBCD. The initial screen will show the current Windows bootloader. As seen in the example in Figure 5.2e, it will be set to boot Windows only.

Click the ?Add New Entry? button to add an entry for your PC-BSD? installation. In the ?Linux/BSD? tab, click the ?Type? drop-down menu and select FreeBSD/ PC-BSD? from the list. Type in something useful in the ?Name? field; whatever you type here will show up in the boot menu. Click the ?Device? drop-down menu and select the partition holding your PC-BSD? installation. It will have a filesystem type of 0xA5 rather than a drive letter or NTFS. The entry will also show its size so you can find it if you have other non-Windows partitions. An example is seen in Figure 5.2f.

Figure 5.2e: Viewing the Windows Boot Loader Entries Using EasyBCD

[Easybsd1]

Figure 5.2f: Adding an Entry for PC-BSD? to the Windows Boot Loader

[Easybsd2a]

Once you have made your selections, click the ?Add Entry? button. If you then click on the ?View Settings? button, you should see a new entry for your PC-BSD? installation.

Now that you have an entry, you can click the ?Edit Boot Menu? button to set the order of the entries in the boot menu, the default operating system to boot, and the boot menu selection timeout before booting into the default operating system. This screen is shown in Figure 5.2g.

Figure 5.2g: Viewing the New Entry in EasyBCD

[Easybcd3]

Once you reboot, a simple boot menu will appear containing entries for Windows and PC-BSD?. A sample menu is shown in Figure 5.2h. Use your arrow key to select the operating system you wish to boot into.

Figure 5.2h: Sample Boot Menu Created by EasyBCD

[Easybcd4]

5.2.6 Recovering Windows Boot loader After Installing PC-BSD?

If you accidentally overwrite your Windows boot loader, you will be unable to boot into Windows after installing PC-BSD?. Depending upon the version of Windows, the PC-BSD? boot loader may or may not automatically provide an entry to boot into Windows. However, assuming you have not accidentally installed PC-BSD? into the Windows partition, your Windows installation is still there and it is possible to restore the Windows boot loader. How to do so varies by the version of Windows:

�E How to Reinstall XP Bootloader

�E How to Restore Vista Boot Manager

�E How to Manually Repair Windows 7 Boot Loader Problems

Once the Windows boot loader is recovered, you can use EasyBCD to add an entry for PC-BSD? to the Windows boot loader.

5.3 Multiple Boot Environments

Beginning with version 9.1, PC-BSD? supports multiple boot environments (BEs) on systems that were formatted with ZFS during installation. In 9.1, this feature is managed from the command line. Version 9.2 will provide a graphical interface for managing boot environments.

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:

�E if you are making software changes to a boot environment, you can take a
   snapshot of that environment at any stage during modifications by using the
   beadm create command. A snapshot is a read-only image of a boot environment
   at a given point in time. A snapshot is not bootable but you can create a
   boot environment, based on that snapshot, by using the beadm create -e
   command followed by the beadm activate command to specify that this boot
   environment will become the default boot environment on the next reboot.

�E you can create custom names for each snapshot to identify when or why that
   snapshot was created. You can use the beadm list -s command to view the
   available snapshots for a boot environment.

�E you can save multiple boot environments on your system and perform various
   updates on each of them as needed. For example, you can clone a boot
   environment by using the beadm create command. A clone is a bootable copy
   of a boot environment. You can install, test, and update different software
   packages on the original boot environment and on its clone.

�E although only one boot environment can be active at a time, you can mount
   an inactive boot environment using the beadm mount command. You could then
   chroot into the mount point in order to update specific packages on the
   mounted environment.

�E you can move a boot environment to another machine, physical or virtual, in
   order to check hardware support.

NOTE: for boot environments to work properly, do not change the default ZFS layout 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.

5.3.1 Managing Boot Environments

Boot environments are managed with the beadm command which must be run as the superuser. The following example creates a BE named beforeupgrade. The new BE is a clone of the current BE, the ZFS environment that you booted into.

beadm create beforeupgrade

Created successfully

To view all BEs, use the list command

beadm list BE Active Mountpoint Space Policy Created default NR / 6.05G static 2012-07-09 05:06 beforeupgrade - - 1K static 2012-07-10 12:25

The possible flags in the ?Active? field are as follows:

�E R: active on reboot

�E N: active now

�E -: inactive

In this example, the current BE is called default, it is active now and at next reboot, and is mounted. The newly created beforeupgrade BE exists, but is inactive and unmounted. To activate the new BE:

beadm activate beforeupgrade Activated successfully beadm list BE Active Mountpoint Space Policy Created default N / 64.5K static 2012-07-09 05:06 beforeupgrade R - 6.05G static 2012-07-10 12:25

The flags now indicate that the system is currently booted into default, but at next boot the system will boot into beforeupgrade. Only one boot environment can be active at a time.

5.4 Upgrading PC-BSD?

PC-BSD? makes it easy to upgrade from an earlier version of 9.x (including beta and RC versions) to the latest version of PC-BSD?. When the upgrade is finished, simply reboot to access the new version of your PC-BSD? operating system. The upgrade can be performed using the graphical Update Manager or from the command line.

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

�E it is not recommended to update between major branches: for example, from a
   7.x or 8.x version to a 9.x version of PC-BSD?. Instead, backup your data
   and do a fresh install of the new version.

�E it is not possible to upgrade from FreeBSD to PC-BSD?.

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

�E before performing any upgrade, always back up your important data to an
   external backup device, such as a removable USB drive, or to another system
   using a utility such as Life Preserver. While it is unlikely that something
   will go wrong, you will be glad that you made that backup just in case.

�E when you do an upgrade, programs installed via FreeBSD ports or packages
   will be removed. If you want to preserve these across system updates, you
   should install these within a ports jail using Warden?. Better yet, request
   that your favorite port/package is made into a PBI as PBIs are preserved
   during an upgrade.

�E an upgrade will preserve the data in the home directories, any installed
   PBIs, and user accounts. It also preserves common configuration files--you
   can view the list of files which are excluded from the upgrade in
   upgrade-excludes. The upgrade process will also merge any customizations
   you have made into the new versions of the following files: boot/
   loader.conf, /etc/rc.conf, and /etc/sysctl.conf.

5.4.1 Using Update Manager

To start Update Manager, make sure that your Internet connection is active and go to Control Panel ? Update Manager or type pc-su pc-updategui from a terminal. After inputting the administrative password, Update Manager will look for updates and inform you if a newer version of the operating system is available. In the example shown in Figure 5.4a, the current operating system is 9.0 and Update Manager is indicating that the upgrade to 9.1 is available.

Figure 5.4a: Using Update Manager to Upgrade the Operating System

[Upgrade1a]

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 "System Upgrade" entry and click the "Install selected updates" button. A progress bar will indicate:

�E the download status of the PCBSD.tbz upgrade file

�E the download status of the software packages that are installed with the
   operating system and which have newer available versions

How long these downloads take depends upon the speed of your network connection: for example, it can take an hour or so over a DSL connection. You can continue to use your PC-BSD? system while Update Manager downloads the files it needs to /usr/local/tmp/.

Once the downloads are finished, a pop-up message will indicate that the system is now ready to reboot in order to finish the upgrade. PC-BSD? will not automatically reboot the system, giving you the opportunity to close any applications that you have open before you reboot the system yourself.

NOTE: it is very important that once you reboot, you do not interrupt the upgrade process. This process may take up to 30 minutes, so plan your reboot for a time when you do not need immediate access to your system.

After rebooting, a console message will appear similar to this one:

A system update to PC-BSD is ready to be installed. This may take 30 minutes or more. If you wish to postpone the update, type 'skip' and press enter. You will be prompted again during the next system boot. The update will begin automatically in 20 seconds.

Since this portion of the updating process can make your system unavailable for as long as half an hour, this message allows you to skip completing the update for now if you need to reboot into the system. If you are ready to leave the system alone while it completes the update, do not do anything and the update will begin in 20 seconds. It is important to not reboot the system until this portion of the upgrade completes.

Cleaning old system pkgs..... Extracting updated world environment...DONE! Extracting kernel and boot environment...DONE Cleaning up old files...DONE Rebooting for stage 2 of upgrade...Shutdown NOW!

The system will automatically reboot into the new operating system and continue with the application updates.

Installing system packages... Cleaning up...DONE Update finished! Rebooting...

Your system will now reboot into the newly-installed operating system.

5.4.2 Using the Command Line

To start a system upgrade from the command line, become the superuser and use the following command to check to see if an update is available:

pc-updatemanager check The following updates are available:
NAME: System Update to 9.1 TYPE: SYSUPDATE VERSION: 9.1 DATE: 2012-12-03 TAG: release-9.1 DETAILS: http://www.pcbsd.org To install this update run "/usr/local/bin/pc-updatemanager install release-9.1"

Follow the instructions to install the update:

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.

5.5 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:
�E /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.
�E /usr/share/pc-sysinstall/backend-partmanager/ contains the scripts which
   are used by the installer to create and delete partitions.
�E /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.
�E /usr/share/pc-sysinstall/components/ contains FreeBSD ports and src and the
   PBIs for chromium, firefox, opera, and thunderbird.
�E /usr/share/pc-sysinstall/conf/ contains the configuration file
   pc-sysinstall.conf. It also contains a file indicating which localizations
   are available (avail-langs), a list of files which are not touched during
   an upgrade (exclude-from-upgrade), and a license/ subdirectory containing
   text files of applicable licenses (e.g. bsd-en.txt and nvidia-en.txt).
�E /usr/share/pc-sysinstall/doc/ contains the help text that is seen if you
   run pc-sysinstall without any arguments.
�E /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.
�E /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 or installation server.
These steps are discussed in more detail below.

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

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

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

disk0=da0 partition=all bootManager=none commitDiskPart

disk1=da1 partition=all bootManager=none commitDiskPart

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 commitDiskLabel

disk1-part=UFS+S 1024 /usr/src disk1-part=UFS+S 4096 /usr/local disk1-part=UFS+S 0 /usr/ports 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 installType=FreeBSD installMedium=ftp ftpPath=http://pkgbuilder.mydomain.com/images/freebsd/8.2/ packageType=tar

rootPass=root

userName=demo userComment=Demo User userPass=demo userShell=/bin/sh userHome=/home/demo commitUser

runCommand=cp /usr/share/zoneinfo/EST5EDT /etc/localtime runCommand=touch /etc/wall_cmos_clock runCommand=adjkerntz -a

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

runCommand=fetch -o /tmp/vmtools.tar.gz http://pkgbuilder.mydomain.com/images/freebsd/vmware-freebsd-tools.tar.gz runCommand=zcat /tmp/vmtools.tar.gz | tar -C /tmp -xvf - runCommand=/tmp/vmware-tools-distrib/vmware-install.pl -d runCommand=rm -rf /tmp/vmware-tools-distrib runCommand=/usr/local/sbin/sysrc puppet_enable=YES runCommand=/usr/local/bin/puppet agent -t

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 the equals sign.

Table 5.5b.: Additional Variables for Automated Installations

�� Variable �� Options �� Description �� pc_config ��URL or /path/to/file��location of customized �� pc-sysinstall.conf �� should be set to yes, otherwise �� confirm_install ��yes or no ��booting the wrong disk will result in �� a system wipe �� good idea to run a shutdown, but can �� shutdown_cmd ��e.g. shutdown -p now��be any command/script you wish to �� execute post-install �� dhcp-all or ��will attempt dhcp on all found NICs �� nic_config ��<interface name> <IP��until the installation file can be �� address> <subnet ��fetched or will setup specified �� mask> ��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_config: http://pkgbuilder.mydomain.com/images/freebsd/pc-sysinstall.cfg

confirm_install: no

shutdown_cmd: shutdown -r now

nic_config: em1 172.16.80.250 255.255.240.0

nic_dns: 172.16.80.1

nic_gateway: 172.16.80.1

5.5.3 Create a Custom Installation Media or Installation Server

pc-sysinstall supports the following installation methods:
�E from a CD, DVD, or USB media
�E 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 cd 'd into a directory where you would like to copy the contents of the ISO. In the following examples, /tmp/custominstall/ was created 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:
�E 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)
�E runCommand= make sure the command exists in the specified path
�E runScript= make sure the script exists in the specified path
�E 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.

6 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 System Manager .

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

These desktops are fully supported, meaning that all of the PC-BSD? utilities are integrated into the desktop environment:
�E GNOME2
�E KDE4
�E LXDE
�E XFCE4
By default, three PC-BSD? icons will appear on these desktops:

[Appcafel]

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

[Controlp]

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

[Acrobat]

PC-BSD? Handbook: a PDF version of the PC-BSD? 9.1 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:
�E Awesome
�E Enlightenment
�E evilwm
�E Fluxbox
�E FVWM
�E i3
�E IceWM
�E Openbox
�E Ratpoison
�E spectrwm
�E WindowLab
�E Window Maker
Advanced users can also install other desktops using the FreeBSD ports and packages collection. You can browse the 180+ available desktops in the x11-wm category at Freshports.

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

6.1 GNOME2

GNOME2 is a popular desktop environment that provides many built-in utilities.

NOTE: GNOME3 has not yet been ported to FreeBSD. Once it has, it may be added as a desktop component in the PC-BSD? installer.

Figure 6.1a shows a screenshot of GNOME2 on a PC-BSD? 9.1 system with the ?Applications? menu open:

Figure 6.1a: GNOME2 on PC-BSD?

[GNOME2-2]

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:
�E Eye of GNOME: image viewer found in Graphics ? Image Viewer.
�E Epiphany: web browser found in Internet ? Epiphany Web Browser.
�E Brasero: CD/DVD burning software found in Multimedia ? Brasero Disk Burner.
�E Totem: movie player found in Multimedia ? Movie Player.
�E Evolution: email client with address book and calendar. Found in Office ?
   Evolution Mail and Calendar.
�E Nautilus: file manager found in Utilities ? File Browser.
NOTE: some games, such as Gnibbels, 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 ? System Manager ? System Packages ? Desktops ? GNOME.

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

6.2 KDE4

The KDE 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.1 with the ?Applications? menu open.

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:
�E Gwenview: image viewer found in Graphics ? Image Viewer.
�E Digikam: photo management program found in Graphics ? Photo Management
   Program.
�E Konqueror: file manager, web browser, and SSH client found in Internet ?
   Web Browser.
�E KMPlayer: media player found in Multimedia ? Media Player. Plays most MPEG/
   VOB, AVI, Ogg/OGM, VIVO, ASF/WMA/WMV, QT/MOV/MP4, RealMedia, Matroska, NUT,
   NuppelVideo, FLI, YUV4MPEG, FILM, RoQ, PVA files, supported by many native,
   XAnim, and Win32 DLL codecs. You can watch VideoCD, SVCD, DVD, 3ivx, DivX 3
   /4/5, WMV and even H.264 movies.
�E Okular: document viewer and annotator found in Office - Document Viewer.
   Supports PDF, OpenOffice, and Postscript files.
�E KOrganizer: organizer utility and reminder daemon found in Office ?
   Personal Organizer.
�E Dolphin: 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.
Figure 6.2a: Applications Menu of KDE4

[KDE4]

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 ? System Manager ? System Packages ? 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 includes descriptions and screenshots of all of KDE's applications as well as links to their handbooks.

kde-look.org contains additional themes and wallpapers.

6.3 LXDE

LXDE 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

[LXDE]

In addition to the PC-BSD? utilities, LXDE provides the following utilities:
�E LXPanel: 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.
�E PCManFM: found in Accessories ? File Manager. 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.
�E GPicView: fast image viewer found in Accessories ? Image Viewer.
�E Leafpad: a light-weight graphical text editor found in Accessories ?
   Leafpad.
�E LXTerminal: terminal emulator found in Accessories ? LXTerminal
�E Xarchiver: archiver utility that supports the 7z, ARJ, bzip2, gzip, lzma,
   RAR, RPM, DEB, tar, and ZIP file formats. Found in Accessories ? Xarchiver.
�E Midori: a lightweight web browser found in Internet ? Midori.
�E epdfview: a PDF viewer found in Office ? ePDFViewer.
�E LXTask: task manager and system monitor found in System Tools ? Task
   Manager.
�E LXAppearance: a theme switcher for customizing the widgets, colors, icons,
   mouse cursors, and sound effects used by applications. Found in Preferences
   ? Customize Look and Feel.
�E LXInput: a tool to configure your keyboard and mouse found in Preferences ?
   Keyboard and Mouse.
�E Openbox: the window manager used by LXDE. You can configure settings such
   as themes, appearance, mouse, and margins by going to Preferences ? Openbox
   Configuration Manager.
6.4 XFCE4

Xfce 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 message shown in Figure 6.4a:

Figure 6.4a: Panel Welcome Message

[Welcomepanel]

In XFCE, a panel 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:
�E 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 the desktop.
�E Use default config: this option will install a large panel across the top
   and a small, minimal panel centered on the bottom. The application launcher
   menu may be accessed by the fireball icon in the lower left, or by a
   right-click on the desktop.
�E 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 shows a screenshot of XFCE4 running on a PC-BSD? 9.1 with the application menu open.

Figure 6.4b: XFCE with Complete Panel Migrated From Old Config

[XFCE4-2]

Figure 6.4c: XFCE with Minimal Panel Using Default Config

[XFCE4]

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

[SettingsEd]

In addition to the PC-BSD? utilities, XFCE provides the following utilities:
�E Xdesktop: 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.
�E Xfwm4: window manager found in Settings ? Window Manager. It provides
   window decorations, virtual desktops, multiscreen mode, transparency and a
   keyboard shorcuts editor.
�E Ristretto: fast and light-weight picture viewer found in Graphics ?
   Ristretto Photo Viewer.
�E Midori: light-weight graphical browser found in Internet ? Midori.
�E Xfburn: CD/DVD burning tool found in Multimedia ? Xfburn.
�E Orage: calendar and reminder daemon found in Office ? Orage Calendar.
�E Thunar: file manager found in System ? Thunar File Manager.
�E Task Manager: graphical task manager found in System ? Task Manager.
A list of recommended applications for XFCE can be found on the XFCE Wiki.

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

Figure 6.4e: Using alacarte to Customize Applications Menu

[Alacarte]

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

6.4.2 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. If you find a plugin that is not available within AppCafe?, this README 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? screen shown in Figure 6.4f.

Figure 6.4f: Adding a Plugin to the Panel

[Addtopanel-2]

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

6.5 Awesome

Awesome 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.1. The user has right-clicked the desktop in order to launch the awesome application manager.

Figure 6.5a: Awesome Window Manager on PC-BSD?

[Awesome2]

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 or use the pbi_* commands to manage software from the command line.

6.6 Enlightenment

Enlightenment is a lean, fast, modular, and extensible window manager. It provides a desktop for launching applications, managing windows, and doing other system tasks like suspending, reboots, and managing files.

The first time you run Enlightenment, you will be prompted to select your Language, then either a touchscreen or a standard computer profile. You will then be prompted to select the size of title bars, the type of window focus, and whether or not to use compositing. If in doubt, you can select the defaults by pressing "Next" at each initial configuration screen.

Figure 6.6a shows a screenshot of Enlightenment running a standard computer profile on PC-BSD? 9.1. The icon on the far left of the iBar has been clicked in order to access the applications menu.

Enlightenment is very customizable. The e17 User Guide describes how to configure windows, shelves, menus, wallpaper, and much more.

Figure 6.6a: Enlightenment Running on PC-BSD?

[Enlightenment1]

6.7 evilwm

evilwm is an extremely light window manager. It does not support window decorations or icons and uses keyboard shortcuts to access xterms in order to run applications from the command line.

Figure 6.7a shows a screenshot of evilwm running on PC-BSD? 9.1.

Notice that there are no icons, nor is there a system tray, an application panel, or window buttons. An xterm has been opened using Ctrl+Alt+Enter and shows the output of the ps command.

The keyboard shortcuts for manipulating windows are listed here.

To exit evilwm and return to the login screen, type killall evilwm within an xterm.

[Evilwm]

6.8 Fluxbox

Fluxbox 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.8a 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.

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

Figure 6.8a: Fluxbox on PC-BSD?

[Fluxbox3]

To ease some aspects of configuration, the Fluxconf PBI, available in AppCafe?, adds the following graphical tools:
�E fluxbare: seen in Figure 6.8b, provides a tiny toolbar allowing you to
   launch the next three utilities. Type fluxbare within an xterm to open the
   toolbar.
�E fluxconf: seen in Figure 6.8c, is used for managing window placement.
�E fluxkeys: seen in Figure 6.8d, is used to define and manage keyboard
   shortcuts.
�E fluxmenu: seen in Figure 6.8e, is used to add or remove entries from the
   Fluxbox menu.
Figure 6.8b: Fluxbare Toolbar

[Fluxbare]

Figure 6.8c: Configuring Window Placement with fluxconf

[Flluxconf]

Figure 6.8d: Managing Keyboard Shortcuts with fluxkeys

[Fluxkeys2]

Figure 6.8e: Editing the Menu Using fluxmenu

[Fluxmenu]

The following resources are useful when customizing Fluxbox:
�E Creating the Perfect Fluxbox Desktop on Linux
�E Fluxconf How-To at Tux Magazine
�E Fluxbox wiki
�E FAQ
�E How tos
6.9 FVWM

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

When you install FVWM on PC-BSD?, it also installs FVWM-Crystal. Both window managers will be added to the login menu.

Figure 6.9a 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.9a: FVWM Running on PC-BSD?

[Fvwm]

Figure 6.9b 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 provides a good overview of the features and configurable options for FVWM-Crystal.

The FVWM Documentation provides further information about configuring FVWM.

Figure 6.9b: FVWM-Crystal Running on PC-BSD?

[Fvwm-crystal]

6.10 i3

i3 is a lightweight, tiling window manager. Keyboard shortcuts are provided to open xterms in order to start applications from the command line.

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

Figure 6.10a shows a screenshot of i3 running on PC-BSD? 9.1.

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 contains the default key bindings and instructions for customizing i3.

Figure 6.10a: i3 Window Manager on PC-BSD?

[I3a]

6.11 IceWM

IceWM is a light-weight window manager.

Figure 6.11a 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 for more information about configuration, customization, and keyboard shortcuts.

Figure 6.11a: IceWM on PC-BSD?

[Icewm2]

6.12 Openbox

Openbox 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.12a 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.12b.

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

Figure 6.12a: Openbox on a PC-BSD? System

[OpenBox]

Figure 6.12b: Openbox Configuration Manager

[Openbox-config]

6.13 Ratpoison

Ratpoison is a simple window manager with no fat library dependencies, no fancy graphics, or window decorations.

Figure 6.13a provides a screenshot of Ratpoison running on a PC-BSD? system:

Figure 6.13a: Ratpoison on a PC-BSD? System

[I3a]

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 contains an FAQ and tips for setting keyboard shortcuts.

6.14 spectrwm

spectrwm, 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. If you have not used spectrwm before, spend some time reading through its man page first.

Figure 6.14a provides a screenshot of spectrwm running on a PC-BSD? system.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.

Figure 6.14a: spectrwm on a PC-BSD? System

[Spectrwm]

6.15 WindowLab

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

Figure 6.15a 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.

Figure 6.15a: WindowLab Running on PC-BSD?

[Windowlab1]

6.16 Window Maker

Window Maker is a light-weight window manager that was designed to reproduce the elegant look and feel of the NEXTSTEP user interface.

Figure 6.16a 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.

In addition to the PC-BSD? utilities, Window Maker provides the following applications:
�E 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.
�E wmakerconf: 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.15b shows wmakerconf with the ?Menu? button
   selected.
Figure 6.16a: Window Maker on PC-BSD?

[Windowmaker1]

Figure 6.16b: Editing the Application Menu Using wmakerconf

[Wmakerconf1]

6.16.1 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.16c demonstrates how to configure an icon for AppCafe?.

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 users. The application name for AppCafe? is appcafe and for Control Panel it is pc-controlpanel..

Figure 6.16c: Configuring an Icon

[Wmakerconf2]

6.16.2 DockApps

Window Maker supports dockapps 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 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. 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.

7 Installing Applications and Keeping PC-BSD? Updated

In PC-BSD?, software is divided into PBIs, meta-packages, and package sets:
�E PBIs are single applications, such as web browsers or multimedia utilities.
   PBIs are installed and managed using AppCafe?. Update Manager will
   automatically notify you when newer versions of installed PBIs become
   available.
�E Meta-packages are installable software collections that can be considered
   the same as system components. Meta-packages are selected during
   installation and include supported and unsupported desktops, development
   utilities, hardware drivers, and miscellaneous applications such as MythTV
   or XBMC. After installation, your initial meta-package choices can be
   modified using System Manager. Warden? also supports meta-packages,
   allowing you to install system components into a jail.
�E Package sets include the default packages that get installed with any
   PC-BSD? system, plus the meta-packages which are selected for installation
   by the user. The list of packages which are installed with the 9.1 PC-BSD?
   operating system are listed in the base-system ports-list. You can also
   view the package list for each meta-package here. Update Manager will
   automatically notify you when a new package set is ready--typically this
   occurs every week or two, making it easy to keep the software that came
   with the operating system up-to-date.
NOTE: users are highly discouraged from using FreeBSD packages or ports or upgrade tools such as portupgrade or portversion from the PC-BSD? command line as Update Manager will remove your manually installed applications and upgrades. If you wish to practice using these tools, instead use Warden? to create a ports jail. If you think an application belongs in the base system (e.g. an add-on to a desktop meta-package), suggest that it be added using one of the resources in the Finding Help section.

This section demonstrates the following PC-BSD? tools for managing software on your PC-BSD? system:
�E AppCafe? to install PBI software using a graphical application.
�E PBI Manager to manage PBI software using command line utilities.
�E Update Manager to install newer versions of PBIs or package sets and to
   apply security patches using a graphical application.
�E Meta Package Manager to manage meta-packages from the command line.
It also describes how to create your own package repository of custom PBIs.

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

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 the installed PBI will be that large. 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 most of the applications that users require, such as web browsers, games, mail clients, and productivity 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 root password. This is to prevent a regular user from installing server software.

When a regular user installs an application, they have the option to ?Install Menu Icons (All Users)?, meaning that an application only needs to be installed once on a multi-user system.

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

NOTE: at this time, AppCafe? does not keep a copy of the downloaded .pbi file. If you would like to retain a copy of this file on disk, use pbi_add -R to download a copy of the PBI to the current directory.

PBIs are the recommended software installation method on PC-BSD?. Update Manager will automatically notify you when newer versions of software installed through the PBI system are available. PBIs will also be preserved over system upgrades and system meta-package changes.

7.1.1 Installing and Uninstalling PBI 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? tab in AppCafe? can be used to browse for available software, as seen in Figure 7.1a:

Figure 7.1a: Browsing for Software Using AppCafe?

[Appcafe1e]

In the example shown in Figure 7.1a, 1021 PBIs are available and 3 are currently installed on this system.

If you know the name of the application you would like to install, type its name into the ?Search? bar. Alternately, you can click on a software category (for example, ?Archivers?) to browse for available software. Use the back arrow or home icon to navigate within the browser. In the example shown in Figure 7.1b, the user searched for the ?gimp? application then clicked on the ?Gimp? search result.

Figure 7.1b: Browsing the Information Available for a PBI

[Appcafe3d]

Figure 7.1b shows an example of the information that is available for each PBI:
�E Name and icon of the application; in this example, it is Gimp.
�E A hyperlink to the application's website; in this example, clicking on ?The
   GIMP Team? will open gimp.org in the user's default web browser.
�E Either a Download icon (if the application is not currently installed) or
   an Installed icon if it is already installed.
�E The version of the application.
�E The platform (i386 for 32-bit applications and amd64 for 64-bit
   applications). If you are on a 64-bit system and there is only a 32-bit
   application, AppCafe? will install the 32-bit application and PC-BSD? will
   still be able to run the program.
�E The type will indicate whether the application is graphical or text
   (command line).
�E Whether or not the installation requires the root (administrative)
   password.
�E The license used by the software.
�E The size of the initial download of the PBI.
�E A description of the application.
Once you find a PBI that you would like to install, click on its Download icon. AppCafe? will automatically detect your PC-BSD? version and architecture and install the correct PBI for you. When the installation is complete, the new PBI will be displayed in the ?Installed? tab. Figure 7.1c shows a screenshot of this tab from a system with several PBIs installed.

Figure 7.1c: Viewing the List of Installed PBIs in AppCafe?

[Appcafe4c]

If you right-click an installed PBI you can:
�E View details: Figure 7.1d shows an example of a PBI's details. In addition
   to the information usually available for a PBI in the ?Browse? tab, the
   details will indicate that the PBI is installed and a checkbox is added for
   ?Automatic Updating?. Check this box if you would like Update Manager to
   automatically update this PBI, rather than just notify you that a newer
   version is available.
�E Install PATH links: select this option if you will be starting the
   application from the command line as it will add the command's location to
   your $PATH.
�E Install PATH links (All Users): adds the command's location to the $PATH of
   all users so that they can start the application from the command line. 
   Requires the administrative password.
�E Uninstall: will uninstall the PBI. Once the PBI removal is complete, it
   will be removed from the Installed list.
If you highlight a PBI and click the ?More? button, the following actions will be added to that list of options:
�E Install Desktop Icons: will create a shortcut to the application on the
   user's desktop.
�E Install Menu Icons: will add an entry for the application to the supported
   desktop's application menu.
�E Install Menu Icons (All Users): will add an entry for the application to
   the application menu of every user. Requires the adminstrative password.
Figure 7.1d: Viewing an Installed PBI's Details

[Appcafe5c]

7.1.2 Updating Installed PBIs

The ?Installed? tab will also 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 PBI that has a newer version available.

In this example, the currently installed version of Firefox is 16.0.1_1 and version 16.0.2 is available. To upgrade this PBI, highlight its entry and click the ?Update? button. Alternately, if updates are available for multiple PBIs and you wish to upgrade them all, click the ?Update All? button. If the PBI ?Requires Root?, it will prompt you for the administrative 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.

Figure 7.1e: Using the Installed Tab to Upgrade Installed PBIs

[Pbiupdate1]

7.1.3 Preferences

If you click File ? Preferences, you will see the screen shown in Figure 7.1f.

By default, an icon is added to the desktop (for window managers that support icons) whenever you install a PBI. Uncheck the box ?Create desktop icons at install? to disable desktop icon creation. You can still elect to install a desktop icon on a per-PBI basis by right-clicking the PBI and selecting ?Install Desktop Icons? as shown in Figure 7.1c.

Figure 7.1f: AppCafe? Preferences

[Preferences]

7.1.4 Repositories

If you click Repositories ? Configure Repository from within AppCafe?, you will see the screen shown in Figure 7.1g:

Figure 7.1g: Managing Available Repositories

[Appcafe2a]

This screen will list the official PC-BSD? repositories. AppCafe? reads this list, in order, when connecting to the software repository. You can use the up and down arrows to reorder the list. If you have created your own software repository of PBIs, use the ?Add? button to add the URL of the repository.

If you have created your own .rpo file using the pbi_makerepo command, you can use Repositories ? Add Repository to browse to the location of the .rpo file. This is the equivalent of manually running the pbi_addrepo command.

7.2 PBI Manager

PBI Manager is a suite of command line utilities which can be used to install, remove, create and manage PBIs. These utilities also allow administrators and PBI builders to create and manage their own repositories of PBIs.

NOTE: PBI files created for PC-BSD? 7.x or 8.x will not work with PBI Manager as it was designed for 9.x PBIs.

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

7.2.1 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.2a. 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.2a: pbi_add Options

�� 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 �� display information about specified PBI; if combined with -v�� -i ��, 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�� remote fetch installation file from update server; the �� -r ��system architecture and 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 on a 32-bit system:

pbi_add -r alpine Downloading ftp://ftp.pcbsd.org/pub/mirror/PBI/mail/alpine/9/x32/alpine-2.00_3-i386.pbi /usr/pbi/.alpine-2.00_3-i386.pbi 100% of 11 MB 295 kBps 00m00s Verifying Checksum...OK Extracting to: /usr/pbi/alpine-i386 Installed: Alpine-2.00_3

PBI Manager will automatically detect the architecture and install the appropriate PBI. If only a 32-bit version is available and you are on a 64-bit system, 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-i386.pbi

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

7.2.3 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.2b summarizes this command's options:

Table 7.2b: pbi_autobuild Options

�� Switch �� Description �� mandatory; specify the directory containing the PBI �� configuration modules; any found pbi.conf files will be �� -c confdir ��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 �� if your build hardware has the CPU and disk I/O to support �� -p num ��concurrent build processes, specify the number of concurrent �� builds �� -32 ��include when building a 32-bit PBI on a 64-bit system �� when building a new PBI, check for archived copies and �� --genpatch ��generate smaller patch updates to the new version (*.pbp �� files) �� when building new PBIs, keep <num> copies of past versions of �� --keep num ��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 ��digitally sign the PBI file with the specified openssl private�� keyfile ��key file ��

7.2.4 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.2c summarizes the available options.

Table 7.2c: pbi_browser Options

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

7.2.5 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.2d lists the supported variables.

Table 7.2d: pbi_conf Variables

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

7.2.6 pbi_create(1)

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.2d lists the supported variables.

Table 7.2d: pbi_conf Variables

�� Switch �� Description �� PBID_REFRESH ��wakeup time in seconds for pbid to run its checks �� number of hours representing how often pbid refreshes �� PBI_INDEXREFRESH ��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 ��

7.2.7 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 so they can be added to the PC-BSD? PBI repository and made available to other PC-BSD? users.

Table 7.2e summarizes the available options:

Table 7.2e: pbi_create Options

�� 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 �� specify the metadata configuration directory; while not �� -c confdir ��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 ��digitally sign the PBI file with the specified openssl private�� keyfile ��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:

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.

7.2.8 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.2f summarizes its options:

Table 7.2f: pbi_delete Options

�� Switch �� Description �� -v ��enable verbose output �� perform a full cleaning of the shared hash directory, removing�� --clean-hdir��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

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

7.2.10 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-compliant to understand a PBI's icon and mime settings. Table 7.2g summarizes this command's options:

Table 7.2g: pbi_icon Options

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

7.2.11 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.2h summarizes the available options:

Table 7.2h: pbi_indextool Options

�� Command �� Switch �� Description �� add ��-b vers ��mark previous versions as having a binary diff �� patch (.pbp file used for upgrading) available �� add ��-f pbifile ��mandatory, name of PBI being added to the target �� INDEX file �� add ��-k num ��number of previous versions of this PBI to keep in�� the INDEX file �� add ��-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) �� rem ��-n pbiname ��mandatory name of PBI being removed from the INDEX�� file �� rem ��-v version ��mandatory, version of the PBI being removed from �� the INDEX file ��

7.2.12 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.2i summarizes the available options:

Table 7.2i: pbi_info Options

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

7.2.13 pbi_listrepo(1)

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

Table 7.2j: pbi_listrepo Options

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

7.2.14 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.2k summarizes the available options:

Table 7.2k: pbi_makepatch Options

�� Switch �� Description �� -o outdir ��save the resulting *pbp file to the specified directory �� --sign ��use the specified openssl key to digitally sign the patch file�� keyfile �� --tmpfs ��can reduce building time for large PBIs ��

7.2.15 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. How to create a PBI using this command is discussed in more detail here.

NOTE: the pbi_makeport command has support for using ccache 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.2l summarizes the available options:

Table 7.2l: pbi_makeport Options

�� Switch �� Description �� -B ��build-only; generally used with -k to build a port before �� running pbi_create manually �� specify the metadata configuration directory; while not �� -c confdir ��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 �� disable auto-pruning of non-REQUIREDBY ports after the compile�� --no-prune ��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 �� automatically create and mount a tmp filesystem and use it for�� --tmpfs ��WRKDIRPREFIX; can speed up port compiles on systems with �� available RAM �� --sign ��digitally sign the PBI file with the specified openssl private�� keyfile ��key file ��

7.2.16 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.2m summarizes the available options.

Table 7.2m: pbi_makerepo Options

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

7.2.17 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.2n summarizes the available options:

Table 7.2n: pbi_metatool Options

�� Command �� Switch �� Description �� add or rem��--cat ��indicates that a new category is being added to or�� removed from the target metafile �� add or rem��--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 �� add ��-c category ��name of new category to add to the target metafile�� add ��-d desc ��mandatory description of PBI or category being �� added �� add ��-i icon ��mandatory URL to 64x64 .png icon of PBI or �� category being added �� add ��-k keywords ��comma delimited list (with no spaces) of search �� keywords �� add ��-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) �� add ��-u URL ��website of application being added �� add ��-r ��include if application needs to be installed as �� the superuser ��

7.2.18 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.2o.

Table 7.2o: pbi_patch Options

�� 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 �� display any custom scripts used in the installation/removal of�� --checkscript ��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 ��

7.2.19 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.2p summarizes the available options.

Table 7.2p: pbi_update Options

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

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

7.2.21 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.2q:

Table 7.2q: pbid Options

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

7.3 Update Manager

Update Manager provides a graphical interface that is used for updating the version of PC-BSD? and for applying security updates. It is also used to update installed PBIs, installed system components, and Warden? meta-packages. The 9.x series of PC-BSD? uses the GENERIC FreeBSD kernel in order to facilitate upgrading the operating system itself.

This section describes how to use the Update Manager GUI to update PBIs or Warden? meta-packages and to apply system updates. Upgrading PC-BSD? demonstrates how to start an operating system upgrade from the GUI.

Advanced users can use the following command line utilities to achieve the same results:
�E pbi_update: used to update installed PBIs
�E pc-metapkgmanager: used to update installed system components
�E pc-updatemanager: used to update the operating system
An icon located in the system tray lets you determine at a glance if any of your installed PBIs are out-of-date or if a system update is available. This icon has several possible states:

[Updated1]

your system is up-to-date.

[Working1]

the system is currently checking for updates and patches; this happens automatically whenever you boot your system.

[Sysupdat]

your operating system is out-of-date and system update(s) or patch(es) are available.

[Pbiupdat]

newer versions of installed PBI(s) are available; click this icon to open AppCafe? so that you can update the PBI(s).

[Connecte]

the system was unable to check for updates, meaning you should check your Internet connection.

[Updating]

the system is currently updating. You should see this icon once you click the ?Install selected updates? button.

[Restart]

the system needs to restart in order for the newly installed update to take effect. You will not be able to use Update Manager again until the system is rebooted.

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

If you right-click the icon, you will see the menu shown in Figure 7.3a. If updates are available for installed PBIs, AppCafe? will also open to the ?Installed? tab so that you can view the new versions which are available.

Figure 7.3a: Right-click Menu for Update Manager

[Update1c]

Selecting ?Start the Update Manager? from the right-click menu will open Update Manager so that you can review the available system update(s).

Figure 7.3b shows a screenshot of Update Manager:

Figure 7.3b: Update Manager

[Update2a]

If any updates are available, they will be listed; if your system is fully up-to-date, there will not be any entries.

If you hover over a listed update, a pop-up menu will provide some details about the update.

To install an update, check the update(s) that you wish to install and click the ?Install selected updates? button. You can watch the progress of the update, as seen in Figure 7.3c.

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.

Figure 7.3c: Installing a System Update

[Update3b]

7.4 Meta Package Manager

pc-metapkgmanager is the back-end command line utility used by the PC-BSD? installer, System Manager, Update 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.

Beginning with version 9.1, PC-BSD? uses metapkgsets to determine which system components are available and which applications are installed with each system component. Currently, two metapkgsets are available: pcbsd which defines the available desktop components, and warden which defines the components available when creating a jail with Warden? or installing a PC-BSD? server. You can view the contents of these metapkgsets on trac.

The pc-metapkgmanager command can be used at the command line to install or delete meta-packages, update to the latest package set, or to change the default metapkgset. 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
                          <loc> should be a FTP / HTTP url where pkg_add
                          can fetch packages, or an absolute path to
                          location of pkg files on disk.
checkup                 -- Check for updates to pkgs
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
update pkg,pkg2 <loc>  -- Update system packages. Can use 'all' or <pkg,pkg2>.
                          <loc> should be a FTP / HTTP url where pkg_add
                          can fetch packages, or an absolute path to
                          location of pkg files on disk.
--pkgset <pkgset>       -- Change default pkgset we are using
--chroot <dir>  -- Operate on the directory specified using chroot
7.4.1 Finding, Installing, and Uninstalling Meta-Packages

To determine which meta-packages are available:

pc-metapkgmanager list |more Meta Package: Awesome
Description: A highly configurable, next generation framework window manager Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Awesome/pkg-icon.png Parent: Unsupported-Desktops Desktop: YES Required Packages: awesome-3.4.13 Meta Package: Compiz
Description: Compiz - OpenGL compositing manager Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Compiz/pkg-icon.png Parent: Misc Desktop: NO Required Packages: compiz-fusion-0.8.4_2 Meta Package: Desktops
Description: Supported Desktop Environments for your PC-BSD system. Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Desktops/pkg-icon.png Desktop: NO Category Entry Meta Package: Development
Description: Development tools and utilities for your Desktop Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Development/pkg-icon.png Desktop: NO
More--(byte 989)

To view which meta-packages are available in an alternate metapkgset, specify the metapkgset name. For example, to view the available warden meta-packages from your desktop, use this command:

pc-metapkgmanager --pkgset warden list | more Meta Package: Apache
Description: The Apache Web Server Icon: /var/db/pc-metapkgmanager/pkgsets/warden/Apache/pkg-icon.png Parent: Web-Servers Desktop: NO Required Packages: apache-2.2.22_6 Meta Package: BigBlueButton
Description: BigBlueButton enables universities and colleges to deliver a high-quality learning experience to remote students. Icon: /var/db/pc-metapkgmanager/pkgsets/warden/BigBlueButton/pkg-icon.png Parent: Web-Apps Desktop: NO Required Packages: mysql-server-5.5.27 bigbluebutton-0.71_3 Meta Package: Database-Servers
Description: Database Server Software Icon: /var/db/pc-metapkgmanager/pkgsets/warden/Database-Servers/pkg-icon.png Desktop: NO Category Entry Meta Package: Development
Description: Development tools and utilities Icon: /var/db/pc-metapkgmanager/pkgsets/warden/Development/pkg-icon.png
More--(byte 989)

To permanently change the default metapkgset between pcbsd and warden, modify the PCBSD_METAPKGSET variable in /usr/local/etc/pcbsd.conf.

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. If you do not specify the URL, the default mirror will be used. If you receive an error when downloading the package, you can change the default mirror in Control Panel ? System Manager ? Mirrors.

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 Package source: NET Preparing to add: Awesome... Checking for updates to old packages... Installing Meta-Package: Awesome Getting package list... Pending package changes: 6 Downloading package: awesome-3.4.13 //usr/local/tmp/awesome-3.4.13.txz 100% of 704 kB 637 kBps Downloading package: libev-4.11,1 //usr/local/tmp/libev-4.11,1.txz 100% of 117 kB 361 kBps Downloading package: libxdg-basedir-1.1.1 //usr/local/tmp/libxdg-basedir-1.1.1.txz 100% of 11 kB 130 kBps Downloading package: xcb-util-image-0.3.8 //usr/local/tmp/xcb-util-image-0.3.8.txz 100% of 18 kB 141 kBps Downloading package: xcb-util-keysyms-0.3.8 //usr/local/tmp/xcb-util-keysyms-0.3.8.txz 100% of 8040 B 72 kBps Downloading package: xcb-util-wm-0.3.8 //usr/local/tmp/xcb-util-wm-0.3.8.txz 100% of 35 kB 148 kBps Installing package: awesome-3.4.13 Skipping installed package: libev-4.11,1 Skipping installed package: libxdg-basedir-1.1.1 Skipping installed package: xcb-util-image-0.3.8 Skipping installed package: xcb-util-keysyms-0.3.8 Skipping installed package: xcb-util-wm-0.3.8 The meta-pkg Awesome is installed 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 Getting package list... Pending package changes: 66 Removing: awesome-3.4.13 Skipping Meta-Required: giflib-4.2.0_2 Removing: libev-4.11,1 Removing: libxdg-basedir-1.1.1 Removing: xcb-util-image-0.3.8 Removing: xcb-util-keysyms-0.3.8 Removing: xcb-util-wm-0.3.8 Skipping Required: bitstream-vera-1.10_5 Skipping Required: cairo-1.10.2_4,2 <snip output of other required packages> The meta-pkg Awesome is not installed Meta-Package changes finished!

7.4.2 Upgrading Meta-Packages

pc-metapkgmanager can also be used to determine if any meta-packages are out of date and to update meta-packages. To determine if any meta-packages have newer versions:

pc-metapkgmanager checkup All packages are up to date!

In this example, all meta-packages are at their latest versions. If any were out of date, you would instead receive the message ?The following package updates are available:? followed by the names of the out-of-date meta-packages.

To update a meta-package, use the pc-metapkgmanager update command followed by the name of the specific meta-package or the word all to update all out-of-date meta-packages.

pc-metapkgmanager records any error messages to /tmp/.pc-metamanager.log. This log file automatically rotates whenever it reaches 5MB in size.

7.5 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:
�E create the OpenSSL signing key which will be used to sign custom PBIs
�E generate a repository file and populate it with custom PBIs
�E generate the meta-data for the PBIs which are available within the
   repository
This section describes these steps in more detail.

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

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

7.5.3 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 EasyPBI 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 EasyPBI, 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?.

7.5.4 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:
�E 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.
�E 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.
�E 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.
�E 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.
8 Control Panel

Beginning with version 9.0, 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.

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 can be seen in Figure 8.a.

If you know what you would like to configure but not which control panel icon to use, use the search bar in the upper right corner.

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

NOTE: your user account must be a member of the wheel group in order to use the superuser password. If your account is not a member of this group, you will not see the configuration utilities that require superuser access in the Control Panel. 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.

Figure 8.a: PC-BSD? Control Panel

[Controlpanel1a]

Control Panel includes a desktop selector menu which allows you to load the configuration utilities from KDE3 and 4, GNOME2, XFCE3 and 4, and LXDE. Figure 8.b shows the desktop selector menu. In this example, the user is currently logged into the LXDE desktop but they have chosen to view the GNOME utilities. You can tell that this is the case as the icon is the GNOME foot and the menu indicates that LXDE is ?(current)?.

NOTE: if you select another desktop or ?All?, you will see which additional utilities are available. However, if that desktop is not currently installed, no additional icons will be added to Control Panel. You can install additional desktops using System Manager.

Figure 8.b: Desktop Selector Menu

[Controlpanel2a]

This section demonstrates how to use the following utilities which are found in the Control Panel of a PC-BSD? system, regardless of the desktop that is installed:

Software and updates
�E EasyPBI
System management
�E About
�E Active Directory & LDAP
�E Hardware Compatibility
�E GDM Configuration
�E Service Manager
�E System Manager
�E User Manager
Hardware
�E Bluetooth Manager
�E Mount Tray
�E Sound Configuration
�E Display
�E Printing
�E Scanner
Networking
�E Network Configuration
�E Firewall Manager
Tools
�E Adobe Flash Player preferences
�E Life Preserver
�E Warden?
8.1 EasyPBI

EasyPBI is a graphical application that makes it easy to build a PBI module from a FreeBSD port. Beginning with PC-BSD? 9.1, EasyPBI ships with PC-BSD? and can be found in the Control Panel.

This section demonstrates how to use this utility to convert an existing FreeBSD port into a PC-BSD? PBI. You may wish to skim the section on how to Create PBIs first, as well as refer to that Guide should you have trouble creating a PBI or wish to create a more complex PBI.

To start EasyPBI, double-click its icon in Control Panel or type EasyPBI from within an X terminal as your regular user account.

If the ports collection is not installed, you will receive the message shown in Figure 8.1a the first time you start EasyPBI.

Figure 8.1a: Ports Must be Installed to Use EasyPBI

[Easypbi1d]

If multiple users will be using the EasyPBI utility, go to Control Panel ? System Manager ? Tasks and click the ?Fetch Ports Tree? button. Alternately, use the following command as the superuser: portsnap fetch extract. Either of these methods will install the ports collection into /usr/ports.

If you are the only user who will be using the EasyPBI utility, click OK to launch the main EasyPBI screen, shown in Figure 8.1b. Click File ? Get Ports which will download the ports collection to the EasyPBI subdirectory located in your home directory.

Figure 8.1b: EasyPBI Graphical Interface

[Easypbi1b]

If the ports collection was already installed or was installed using System Manager or portsnap, the message in the bottom area of the screen will instead indicate ?To get started, please push the ?New Module?? button.

8.1.1 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 section of trac. Existing modules are listed alphabetically, according to their category in the ports collection.

To create a new module, click the ?New Module? button and use the browser to select the desired port from the FreeBSD ports tree. Once a port is selected, EasyPBI will attempt to automatically supply the port information for the PBI and display the results in the GUI. In the example shown in Figure 8.1c, the net/trickle port has been selected and the fields have been auto-filled in.

Figure 8.1c: Review the New Module

[Easypbi1c]

You should review these fields for accuracy. If you click ?Get Port Info? FreshPorts.org will open in the default web browser so that you can view additional information about the port.

A generic icon will be supplied for the module; you can change the default icon by clicking the ?Choose Icon? button. When using a custom icon, use a 64x64 .png file with a transparent background.

Check the ?Create Desktop/Menu Entries? if you wish the program's icon to be available on the desktop and in the desktop's application menu.

Once the port information is complete, click the ?Create Module? button and EasyPBI will produce the PBI module. The module will be named after the port and will be stored in a subdirectory of the EasyPBI/Modules directory in your home directory. In this example, the module is located in EasyPBI/Modules/ trickle.

8.1.2 Build the Module

Creating the module itself is very quick and takes less than a minute. However, you still need to build and test the module to make sure that the application works as expected. Depending upon the complexity of the application, you may have to edit the initial module then rebuild and retest it until you are satisfied with the PBI for the application.

Once the module is created, you are ready to build a PBI from the module. Click on the ?Build PBI? tab and click the ?Select Module? button to browse to the module you created. Figure 8.1d shows this tab with our example PBI selected.

Figure 8.1d: The Build PBI Tab

[Easypbi3b]

The top half of this screen contains modifiable settings which are used when building PBIs:

Save Settings as Defaults: the settings in this section revert back to the default settings when you exit EasyPBI. This allows you to override the default settings for a particular build. If you wish your changes to be permanent, click this button.

Output Directory: specifies the directory to store the built module. By default, it is the EasyPBI/PBI subdirectory of the user's home directory. Click the ?Change Directory? button to select another location.

Digital Signature File: the PBIs available from the PC-BSD? repositories are digitally signed by the PC-BSD? project's signature file. If you are creating your own repository, click the ?Change File? button to select your own digital signature file. Create Your Own PBI Repository provides instructions for creating a signature file.

Use TMPFS: if your build system has a lot of RAM, selecting this option can speed up the build.

Use Package Caching: this setting is recommended as it reuses previously built packages to speed up subsequent builds.

The rest of this screen is used to build the specified module:

Select Module: select the previously created module to build.

Build PBI: starts the build of the PBI module. It will prompt you for the superuser password and requires a working Internet connection in order to build the PBI. This process may take quite a while, depending upon the port selected and the speed of your computer. The build messages will be displayed in the window at the bottom of the tab. EasyPBI will inform you when the PBI build is finished, and whether it was successful or not.

Stop Build: stops the build process. Click the ?Build PBI? button to resume the build.

Save Build Log: useful if the build fails. Will prompt you to select the location to store build.log which can be read with any ASCII text editor.

You can produce additional modules from the ?Create Module? tab while a PBI build is running.

If the PBI build fails for some reason, you may need to modify the module as described in the next section. Use the build log to determine the error and modify the module as needed. If you are unsure how to fix the module, send the build.log for the failure to the pbi-dev mailing list.

8.1.3 Test and Fine-Tune the Module

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 the ?Output 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 trickle-1.07_2_amd64.pbi trickle-1.07_2_amd64.pbi.sha256 pbi_add --no-checksig trickle-1.07_2_amd64.pbi Verifying Checksum...OK Extracting to: /usr/pbi/trickle-amd64 Installed: trickle-1.07_2

If the module installs successfully, perform the following tests:
�E if you checked the box ?Create Desktop/Menu Entries?, 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.
�E 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.
�E for GUI applications, go through the various menus to see if they produce
   any errors.
�E 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.
The ?Module Editor? tab, seen in Figure 8.1e, can be used to modify the module's settings. Use the ?Select Module? button to browse to the location of the module and to ungrey out the settings in this screen.

Several tabs are provided, allowing you to customize the PBI module. It should be noted that most PBI modules do not require you to make any configuration changes in the ?Module Editor? tab. This tab allows the creation of more complex PBI modules that require additional FreeBSD ports or scripts which are not provided by the default FreeBSD port.

The rest of this section describes the actions available within each tab. If you modify any settings in the PBI module, rebuild it then test again to see if the changes fixed the PBI.

Figure 8.1e: EasyPBI Module Editor

[Easypbi4a]

8.1.3.1 pbi.conf

Typically the ?Program Name?, ?Program Website?, and ?Program Author? are left at their default values. If this information is incorrect, you should email the FreeBSD port maintainer shown in the ?Program Au2.5.17

Last modified: 2013-04-08

Post-it: New Post-it (help)

editorX

handbook_ja_ver9_1

Menu

Search

Recent change