2 Introduction

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.

Where:

•menuentry: the text between the quotes will be displayed in the boot menu and can be anything that makes sense to you.
•insmod: some distros require this instruction to load the UFS2 kernel module.
•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.
•kfreebsd: used to load the primary boot image. For FreeBSD and PC-BSD®, always use /boot/loader.

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:

•.sudo update-grub on a Debian-based system

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

•.grub-mkconfig -o /boot/grub/grub.cfg when using Sabayon

For more information please refer to the GNU GRUB Manual.

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

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

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

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

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

•.How to Reinstall XP Bootloader

•.How to Restore Vista Boot Manager

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

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

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

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

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

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

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

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

•.R: active on reboot

•.N: active now

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

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

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

•.it is not possible to upgrade from FreeBSD to PC-BSD®.

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

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

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

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

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

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:

•.the download status of the PCBSD.tbz upgrade file

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

# PC-BSD System Upgrade

# Updating to 9.1

# Please do NOT reboot the system until the update is finished

##############################################################

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.

# PC-BSD System Upgrade

# Updating to 9.1

# Please do NOT reboot the system until the update is finished

##############################################################

Installing system packages...

Cleaning up...DONE

Update finished! Rebooting...

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

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

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.

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

•./usr/share/pc-sysinstall/backend/ contains the scripts used by the PC-BSD® installer. Scripts have been divided by function, such as functions-bsdlabel.sh and functions-installcomponents.sh. If you have ever wondered how the PC-BSD® installer works, read through these scripts. This directory also contains the parseconfig.sh and startautoinstall.sh scripts which pc-sysinstall uses to parse the configuration file and begin the installation.

•./usr/share/pc-sysinstall/backend-partmanager/ contains the scripts which are used by the installer to create and delete partitions.

•./usr/share/pc-sysinstall/backend-query/ contains the scripts which are used by the installer to detect (e.g. detect-nics.sh) and configure (e.g. enable-net.sh) hardware.

•./usr/share/pc-sysinstall/components/ contains FreeBSD ports and src and the PBIs for chromium, firefox, opera, and thunderbird.

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

•./usr/share/pc-sysinstall/doc/ contains the help text that is seen if you run pc-sysinstall without any arguments.

•./usr/share/examples/pc-sysinstall/ contains several example configuration files for different scenarios (e.g. upgrade, fbsd-netinstall). The README file in this directory should be considered as mandatory reading before using pc-sysinstall.

•./usr/sbin/pc-sysinstall this is the script that is used to perform a customized installation.

To create a custom installation, perform the following steps:

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

These steps are discussed in more detail below.

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

Table 5.4a: Available Variables for Customizing a PC-BSD® Installation

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

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

# Sample configuration file for an installation using pc-sysinstall

installMode=fresh

installInteractive=no

hostname=myhost.mydomain.com

# Set the disk parameters - 1st disk

# Set the disk parameters - 2nd disk

# Setup the disk label - 1st disk

# All sizes are expressed in MB

# Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP

disk0-part=UFS+S 1024 /

disk0-part=SWAP.eli 2048 none

disk0-part=UFS+S 1024 /tmp

disk0-part=UFS+S 1024 /var

disk0-part=UFS+S 0 /usr

# Size 0 means use the rest of the slice size

# Do it now!

commitDiskLabel

# Setup the disk label - 2nd disk

# All sizes are expressed in MB

# Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP

disk1-part=UFS+S 1024 /usr/src

disk1-part=UFS+S 4096 /usr/local

disk1-part=UFS+S 0 /usr/ports

# Size 0 means use the rest of the slice size

netMask=255.255.240.0

netNameServer=172.16.80.1

netDefaultRouter=172.16.80.1

netSaveDev=em0 em1

netSaveIP_em0=192.168.101.42

netSaveIP_em1=172.16.80.156

netSaveMask_em0=255.255.252.0

netSaveMask_em1=255.255.240.0

netSaveNameServer=172.16.80.1

netSaveDefaultRouter=192.168.100.1

# Set if we are installing via optical, USB, or FTP

installType=FreeBSD

installMedium=ftp

ftpPath=http://pkgbuilder.mydomain.com/images/freebsd/8.2/

packageType=tar

# List our components to install

#installComponents=ports,src

userComment=Demo User

runCommand=cp /usr/share/zoneinfo/EST5EDT /etc/localtime

runCommand=touch /etc/wall_cmos_clock

runCommand=adjkerntz -a

# Install packages required for VMware Tools installation/configuration

runCommand=pkg_add -r compat6x-amd64

runCommand=pkg_add -r perl

runCommand=pkg_add -r pcre

runCommand=pkg_add -r puppet

runCommand=pkg_add -r sysrc

# Fetch/install VMware Tools

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

runCommand=zcat /tmp/vmtools.tar.gz | 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

# Generate the certificate to be signed by the master

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
confirm_install	yes or no	should be set to yes, otherwise booting the wrong disk will result in a system wipe
shutdown_cmd	e.g. shutdown -p now	good idea to run a shutdown, but can be any command/script you wish to execute post-install
nic_config	dhcp-all or <interface name> <IP address> <subnet mask>	will attempt dhcp on all found NICs until the installation file can be fetched or will setup specified interface
nic_dns	IP address	DNS server to use
nic_gateway	IP address	default gateway to use

Here is a ample pc-autoinstall.conf file:

# pc-autoinstall.conf example

# Usage: Modify these variables, and copy the file to

# /boot/pc-autoinstall.conf on your PC-BSD installation medium

# The conf will then be read at bootup, and your automated

# install will take place

##################################################################

# Where the pc-sysinstall main config is located

# Can be either a file on the booted CD / DVD / USB media,

# or a remote file on http / ftp

# The value %%NIC_MAC%% is special, and will be substituted with

# the macaddress of the enabled NIC from DHCP or manually set

# with 'nic_config:'

##################################################################

# Examples:

# pc_config: ftp://192.168.0.2/cust-install.cfg

# pc_config: http://192.168.0.2/cust-install.cfg

# pc_config: http://192.168.0.2/%%NIC_MAC%%.cfg

# pc_config: /boot/cust-install.cfg

pc_config:

http://pkgbuilder.mydomain.com/images/freebsd/pc-sysinstall.cfg

# Set this to yes if we should confirm before doing an install

# This should normally be set to yes, otherwise booting the wrong

# disk will result in a system wipe

confirm_install: no

# Set the command to run post-install, usually best to run shutdown

# but this can be replaced with any other command / script you wish

# to execute post-install

shutdown_cmd: shutdown -r now

# Options for the network setup, should the cfg need to be fetched

# from a remote location, only necessary when using ftp or http

##################################################################

# Special option, will attempt dhcp on all found NICs

# until the file can be fetched, or we run out of interfaces

# nic_config: dhcp-all

# Line to be passed to the "ifconfig" command to bring up an interface

nic_config: em1 172.16.80.250 255.255.240.0

# DNS server to use

nic_dns: 172.16.80.1

# Default router / gateway

nic_gateway: 172.16.80.1

6.5.3 Create a Custom Installation Media or Installation Server

pc-sysinstall supports the following installation methods:

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

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

mdconfig -a -t vnode -f PCBSD9.0-x86-DVD.iso -u 1

mount -t cd9660 /dev/md1 /mnt

Make sure you have 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:

•.installComponents= make sure that any extra components you wish to install exist in extras/PBI/ (if they end in the .pbi extension) or extras/components/ (if they end in .tbz)

•.runCommand= make sure the command exists in the specified path

•.runScript= make sure the script exists in the specified path

•.runExtCommand= make sure the command exists in the specified path

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

cd /tmp/custominstall

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

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

To begin an installation that requires user interaction:

pc-sysinstall -c /path_to_your_config_file

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

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

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

•.GNOME2

•.KDE4

•.LXDE

•.XFCE4

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

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

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

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:

•.Awesome
•.Enlightenment

•.evilwm

•.Fluxbox

•.FVWM

•.i3

•.IceWM

•.Openbox

•.Ratpoison

•.spectrwm

•.WindowLab

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

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

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:

•.Eye of GNOME: image viewer found in Graphics ➜ Image Viewer.

•.Epiphany: web browser found in Internet ➜ Epiphany Web Browser.

•.Brasero: CD/DVD burning software found in Multimedia ➜ Brasero Disk Burner.

•.Totem: movie player found in Multimedia ➜ Movie Player.

•.Evolution: email client with address book and calendar. Found in Office ➜ Evolution Mail and Calendar.

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

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

•.Gwenview: image viewer found in Graphics ➜ Image Viewer.

•.Digikam: photo management program found in Graphics ➜ Photo Management Program.

•.Konqueror: file manager, web browser, and SSH client found in Internet ➜ Web Browser.

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

•.Okular: document viewer and annotator found in Office - Document Viewer. Supports PDF, OpenOffice, and Postscript files.

•.KOrganizer: organizer utility and reminder daemon found in Office ➜ Personal Organizer.

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

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.

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

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

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

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

•.GPicView: fast image viewer found in Accessories ➜ Image Viewer.

•.Leafpad: a light-weight graphical text editor found in Accessories ➜ Leafpad.

•.LXTerminal: terminal emulator found in Accessories ➜ LXTerminal

•.Xarchiver: archiver utility that supports the 7z, ARJ, bzip2, gzip, lzma, RAR, RPM, DEB, tar, and ZIP file formats. Found in Accessories ➜ Xarchiver.

•.Midori: a lightweight web browser found in Internet ➜ Midori.

•.epdfview: a PDF viewer found in Office ➜ ePDFViewer.

•.LXTask: task manager and system monitor found in System Tools ➜ Task Manager.

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

•.LXInput: a tool to configure your keyboard and mouse found in Preferences ➜ Keyboard and Mouse.

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

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

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:

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

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

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

Figure 6.4c: XFCE with Minimal Panel Using Default Config

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

Figure 6.4d: Using Settings Editor to Reset Panel

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

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

•.Xfwm4: window manager found in Settings ➜ Window Manager. It provides window decorations, virtual desktops, multiscreen mode, transparency and a keyboard shorcuts editor.

•.Ristretto: fast and light-weight picture viewer found in Graphics ➜ Ristretto Photo Viewer.

•.Midori: light-weight graphical browser found in Internet ➜ Midori.

•.Xfburn: CD/DVD burning tool found in Multimedia ➜ Xfburn.

•.Orage: calendar and reminder daemon found in Office ➜ Orage Calendar.

•.Thunar: file manager found in System ➜ Thunar File Manager.
•.Task Manager: graphical task manager found in System ➜ Task Manager.

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

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

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

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

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

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

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.

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

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

Figure 6.7a: evilwm Running on PC-BSD®

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

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

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

•.fluxconf: seen in Figure 6.8c, is used for managing window placement.

•.fluxkeys: seen in Figure 6.8d, is used to define and manage keyboard shortcuts.

•.fluxmenu: seen in Figure 6.8e, is used to add or remove entries from the Fluxbox menu.

Figure 6.8b: Fluxbare Toolbar

Figure 6.8c: Configuring Window Placement with fluxconf

Figure 6.8d: Managing Keyboard Shortcuts with fluxkeys

Figure 6.8e: Editing the Menu Using fluxmenu

The following resources are useful when customizing Fluxbox:

•.Creating the Perfect Fluxbox Desktop on Linux

•.Fluxconf How-To at Tux Magazine

•.Fluxbox wiki

•.FAQ

•.How tos

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

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®

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

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

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

Figure 6.12b: Openbox Configuration Manager

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

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.

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

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

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

•.WPrefs: located in Appearance ➜ Preferences Utility. Allows you to configure window focus, window placement, menu alignment, icons, keyboard actions, mouse, fonts, and various other window manager settings.

•.wmakerconf: 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®

Figure 6.16b: Editing the Application Menu Using wmakerconf

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

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

8 Installing Applications and Keeping PC-BSD® Updated

In PC-BSD®, software is divided into PBIs, meta-packages, and package sets:

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

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

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

•.AppCafe® to install PBI software using a graphical application.

•.PBI Manager to manage PBI software using command line utilities.

•.Update Manager to install newer versions of PBIs or package sets and to apply security patches using a graphical application.

•.Meta Package Manager to manage meta-packages from the command line.

It also describes how to create your own package repository of custom PBIs.

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

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

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

Figure 7.1b shows an example of the information that is available for each PBI:

•.Name and icon of the application; in this example, it is Gimp.

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

•.Either a Download icon (if the application is not currently installed) or an Installed icon if it is already installed.

•.The version of the application.

•.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.
•.The type will indicate whether the application is graphical or text (command line).

•.Whether or not the installation requires the root (administrative) password.

•.The license used by the software.

•.The size of the initial download of the PBI.

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

If you right-click an installed PBI you can:

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

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

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

•.Install Desktop Icons: will create a shortcut to the application on the user's desktop.

•.Install Menu Icons: will add an entry for the application to the supported desktop's application menu.

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

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

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

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

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.

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

8.2.1 pbi_add(1)

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
-i	display information about specified PBI; if combined with -v, will display all of the files that will be installed with the PBI
-l	display license for specified PBI
-o outdir	specify the directory to use when extracting the PBI with -e
-r	remote fetch installation file from update server; the system 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

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

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

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

8.2.6 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
PBI_INDEXREFRESH	number of hours representing how often pbid refreshes 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

8.2.7 pbi_create(1)

Table 7.2d: pbi_conf Variables

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

8.2.8 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
-c confdir	specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
-d portsdir	specify an alternative ports directory; defaults to /usr/ports/
-i icon	specify a default icon, relative to pbidir/
-n name	specify a name for this PBI
-o outdir	place the finished .pbi file into the specified directory; defaults to $HOME
-p port	use the given port to get PBI name and version
-r version	specify a version for this PBI
-u weburl	specify a website URL for the PBI
--no-hash	disable using the shared hash directory which uses hard links to share files between applications
--sign keyfile	digitally sign the PBI file with the specified openssl private key file

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

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

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

# Files to be symlinked into the default LOCALBASE

# One per-line, relative to %%PBI_APPDIR%% and LOCALBASE

# Defaults to keeping any existing files in LOCALBASE

# Use bin-files/ for binaries that need wrapper functionality

# TARGET LINK IN LOCALBASE ACTION

bin/myapp bin/myapp binary,nocrash

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

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

8.2.9 pbi_delete(1)

Table 7.2f: pbi_delete Options

Switch	Description
-v	enable verbose output
--clean-hdir	perform a full cleaning of the shared hash directory, removing any unused files; should only be required after a system crash or failure in removing a PBI

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

pbi_info | grep ntop

ntop-4.0.1_1-i386

pbi_delete -v ntop-4.0.1_1-i386

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

Removing: /usr/pbi/ntop-i386

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

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

8.2.11 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

8.2.12 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

8.2.13 pbi_info(1)

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

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

8.2.15 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 keyfile	use the specified openssl key to digitally sign the patch file
--tmpfs	can reduce building time for large PBIs

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

8.2.17 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 description	required; description of the repo to be shown in the repo list
--key keyfile	required; OpenSSL public key used to verify the digital signature of PBIs installed from this repo
--mirror URL	required; URL in http://, https://, or ftp:// format to download PBIs and updates from
--url URL	required; URL in http://, https://, or ftp:// format to use when downloading the master INDEX file of available PBIs

8.2.18 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

8.2.19 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
--checkscript	display any custom scripts used in the installation/removal of this PBI file; recommended if the PBI file is suspect in any way
--no-checksig	skip the openssl signature verification of the PBI data
--no-hash	disable using the shared hash directory which uses hard links to share files between applications

8.2.20 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

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

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

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

•.pbi_update: used to update installed PBIs

•.pc-metapkgmanager: used to update installed system components

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

your system is up-to-date.

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

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

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

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

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

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

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

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

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

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

Description: Compiz - OpenGL compositing manager

Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Compiz/pkg-icon.png

Parent: Misc

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

Meta Package: Development

Category Entry

Description: Development tools and utilities for your Desktop

Icon: /var/db/pc-metapkgmanager/pkgsets/pcbsd/Development/pkg-icon.png

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:

--More--(byte 989)

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

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

Meta Package: Database-Servers

Description: Database Server Software

Icon: /var/db/pc-metapkgmanager/pkgsets/warden/Database-Servers/pkg-icon.png

Meta Package: Development

Category Entry