{{refheading}} <!-- This can be swapped for <references/> if necessary -->

{{refheading}} <!-- This can be swapped for <references/> if necessary -->

{{GroupListHeading|group=tables}}

{{GroupListHeading|group=tables}}

−

<languages/><!-- curious what this will do here -->

|-

|-

|}

|}

−

{{DISPLAYTITLE:<span id="firstHeading" style=" display:inherit !important;">{{FULLPAGENAME}}</span>}}<!-- counteracts part of navheader -->[[category:administrative]]<!-- the '<noinclude> tags around the Navheader help to exclude those headers from this page -->

+

{{DISPLAYTITLE:<span id="firstHeading" style=" display:inherit !important;">{{FULLPAGENAME}}</span>}}<!-- counteracts part of navheader -->[[category:administrative]]<!-- the '<noinclude> tags around the Navheader help to exclude those headers from this page --><languages/>

[{{fullurl:Flat_html|action=pdfbook}} download this page as a PDF book]

[{{fullurl:Flat_html|action=pdfbook}} download this page as a PDF book]

Introduction

Goals and Features

PC-BSD® provides the following features:

Easy installation: to install either a graphical desktop or command-line server version of PC-BSD®, simply insert the installation media, reboot the system to start the installer, and answer a few questions in the installation menus.

Lots of software available: in addition to its own software, PC-BSD® can install software that has been ported to FreeBSD (currently over 24,400 applications).

Easy to update: PC-BSD® provides a built-in Update Manager that will notify you of available updates and allow you to apply operating system security fixes, bug fixes and system enhancements as well as upgrade to newer versions of the operating system or installed software.

Virus-free: PC-BSD® is not affected by viruses, spyware, or other malware.

No defragmentation: PC-BSD® hard drives do not need to be defragmented and do not slow down over time. PC-BSD® uses ZFS[1] which is a self-healing filesystem.

What's New in 9.2

PC-BSD® Releases

PC-BSD® for Linux Users

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

Filesystems

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

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

Table Is there no version? a: Filesystem Support on PC-BSD® [Tables 1]

Filesystem

Native to

Type of non-native support

Usage notes

Btrfs

Linux

none

exFAT

Windows

none

EXT2

Linux

r/w support loaded by default

EXT3

Linux

r/w support loaded by default

since EXT3 journaling is not supported, you will not be able to mount a filesystem requiring a journal replay unless you fsck it using an external utility such as e2fsprogs[6].

EXT4

Linux

r/o support loaded by default

EXT3 journaling, extended attributes, and inodes greater than 128-bytes are not supported; EXT3 filesystems converted to EXT4 may have better performance

check if your Linux distro provides ufsutils;r/w support on Mac;UFS Explorer[8] can be used on Windows

changed to r/o support in Mac Lion

ZFS

PC-BSD®, FreeBSD

Device Names

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

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

Feature Names

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

Table Is there no version? b: Names for BSD and Linux Features [Tables 2]

PC-BSD®

Linux

Description

PF

iptables

default firewall

/etc/rc.d/ for operating system and /usr/local/etc/rc.d/ for applications

rc0.d/, rc1.d/, etc.

in PC-BSD® the directories containing the startup scripts do not link to runlevels as there are no runlevels; system startup scripts are separated from third-party application scripts

/etc/ttys and /etc/rc.conf

telinit and init.d/

terminals are configured in ttys and rc.conf indicates which services will start at boot time

Commands

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

Table Is there no version? c: Common BSD and Linux Commands [Tables 3]

Command

Used to:

dmesg

discover what hardware was detected by the kernel

sysctl dev

display configured devices

pciconf -l -cv

show PCI devices

dmesg | grep usb

show USB devices

kldstat

list all modules loaded in the kernel

kldload <module>

load a kernel module for the current session

pbi_add -r <pbiname>

install software from the command line

sysctl hw.realmem

display hardware memory

sysctl hw.model

display CPU model

sysctl hw.machine_arch

display CPU Architecture

sysctl hw.ncpu

display number of CPUs

uname -vm

get release version information

gpart show

show device partition information

fuser

list IDs of all processes that have one or more files open

Additional Resources

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

Logging In

Installation Troubleshooting

Advanced Installation Topics

Install a Server

Dual Booting

Multiple Boot Environments

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

if you are making software changes to a boot environment, you can take a snapshot of that environment at any stage during 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.

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.

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.

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

Upgrading PC-BSD®

Creating an Automated Installation with pc-sysinstall

Desktops

GNOME2

KDE4

LXDE

XFCE4

Awesome

Enlightenment

Enlightenment[18] 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.

Figure 6.6a: Enlightenment Running on PC-BSD®

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.2. The icon on the far left of the iBar has been clicked in order to access the applications menu.

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

evilwm

evilwm[20] 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.2.

Figure 6.7a: evilwm Running on PC-BSD®

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.

IceWM

Openbox

Ratpoison

spectrwm

WindowLab

Window Maker

Installing Applications and Keeping PC-BSD® Updated

Using AppCafe®

This page or its content was moved. The handbook portion of the wiki now primarily focuses on two versions, the most recent release and the upcoming (work-in-progress). This is an imperfect solution to a recurring problem which may not always be solved by the provided links below.

Meta Package Manager

Create Your Own PBI Repository

Control Panel

EasyPBI

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

This section demonstrates how to use this utility to convert an existing FreeBSD port into a PC-BSD® PBI.

Figure 8.1b: EasyPBI Graphical Interface

You may wish to skim the section on how to Create PBIs first, as well as refer to that Guide should you have trouble creating a PBI or wish to create a more complex PBI.

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

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

Figure 8.1a: Ports Must be Installed to Use EasyPBI

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

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

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

Creating a PBI Module

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

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

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

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

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

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

Figure 8.1c: Review the New Module

Build the Module

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

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

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

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

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

Digital Signature File: the PBIs available from the PC-BSD® repositories are digitally signed by the PC-BSD® project's signature file. If you are creating your own repository, click the Change File button to select your own digital signature file.

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

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

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

Select Module: select the previously created module to build.

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

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

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

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

Test and Fine-Tune the Module

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

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

if you checked the box Create Desktop/Menu Entries, verify that a desktop icon was created (from a desktop that supports icons), that an entry was added to that desktop's application menu, and that the application successfully launches from the application menu. If you used a custom icon, verify that the icon was used.

start the application from the command line to determine if there are any error messages at application launch. When starting the application, specify the full path to the application's binary to make sure that you are testing the PBI's binary.

for GUI applications, go through the various menus to see if they produce any errors.

if you encounter any error messages in either starting or using the application, record them. If the fix for resolving the error messages is not clear to you, send the error report the pbi-dev mailing list[25].

The Module Editor tab, seen in Figure 8.1e, can be used to modify the module's settings. Use the Select Module button to browse to the location of the module and to un-grey-out the settings in this screen.

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

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

pbi.conf

Typically the Program Name, Program Website, and Program Author are left at their default values. If this information is incorrect, you should email the FreeBSD port maintainer shown in the Program Author field so that the information can be corrected in the FreeBSD port.

If you choose to replace the Program Icon, use a 64x64 .png file with a transparent background.

Figure 8.1f: PBI Module Resource Configuration

If your PBI requires a dependency that is not provided by the FreeBSD port, use the + button next to Make Port Before to select the needed port.

If you wish an additional port to be included with your PBI, use the + button next to Make Port After to select the desired port.

The Make Options field lets you specify a space separated list of options. The available options and their default settings will be listed in the OPTIONS= section of the port's Makefile.

If the resulting PBI needs to be run as the root user, check the Require Root Permissions box.

Resources

This tab, shown in Figure 8.1f, is used to add additional files to the PBI module.

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

Another example would be when you wish to use a custom script to start the application rather than starting the application binary directly. A custom script could also be used to verify that the service is enabled or to generate a custom configuration file.

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

Desktop/Menu Entries

This tab, shown in Figure 8.1g, is used to fine-tune the desktop icon and the application menu entry for the application.

Figure 8.1g: Customizing the PBI's Desktop and Menu Entries

If the Create Desktop/Menu Entries box was checked when creating the module and EasyPBI detects that the application is graphical, the default entries for the application will be listed. In our PBI example, trickle is a command line application so no entries were created by default. If your application is graphical but EasyPBI did not detect it, you can manually add the desired entries using the Remove Desktop Entry and Remove Menu Entry buttons.

Under Executable, the drop-down menu will display all of the binaries that came with the application. Select the binary that should launch when the user clicks the desktop icon or selects the application from the application menu. Alternately, you can select Custom Binary and input the path to the desired executable.

The Entry Label field allows you to customize the name that will appear with the icon and application menu entry.

The Icon drop-down menu allows you to select the .png file to use for the icon. This file must exist in ~/EasyPBI/Modules/PBI_name/resources in order to appear in the drop-down menu. Use the Select Module button to re-select the module if you add the icon after loading the module.

The Menu Category drop-down menu is used to select the category the application menu entry will be added to.

To add a desktop entry, select an Executable, input an Entry Label, and click the + Add Desktop Entry button. This will generate the .desktop file to be used by XDG-compliant desktops. The entry will appear under Current Desktop Entries.

To add an application menu entry, select an Executable, input an Entry Label, and click the + Add Menu Entry button. The generated .desktop file will appear under Current Menu Entries.

External-Links

This tab, shown in Figure 8.1h, is used to customize how the specified binary starts.

Figure 8.1h: Configuring Custom Links for the PBI

To customize how a binary starts, highlight it and click the Action drop-down menu. The possible actions are:

binary: indicates that this is an executable. EasyPBI will automatically create the necessary wrapper and PATH links for you.

linux: indicates that this is a Linux executable. EasyPBI will automatically create the necessary Linux wrapper and PATH links for you.

keep: instructs the PBI to not overwrite an existing binary when linking a file into the LOCALBASE. By default, LOCALBASE is set to /usr/local.

replace: instructs the PBI to overwrite an existing binary when linking a file into the LOCALBASE.

nocrash: disables the crashhandler GUI from running on this PBI. Note that the glue for the crash handler is not built into the base system yet.

If you select an Action, use the up arrow to add it. If you change your mind, click the Clear Changes button.

Submit the Module

Once you are satisfied with the PBI, go to the "Module Editor" tab and use the "Select Module" button to select the PBI's module. Then click the "Package Module" button. A pop-up window will indicate that the module has been compressed and that a .tar.gz file has been added to the PBI module directory. The file name for our example PBI is ~dru/EasyPBI/Modules/trickle.tar.gz.

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

Warden®

Using Warden®, it is possible to create multiple, isolated virtual instances of FreeBSD which can be used to run services such as Apache, PHP, or MySQL in a secure manner. Each jail is considered to be a unique FreeBSD operating system and whatever happens in that jail will not affect your operating system or other jails running on the PC-BSD® system.

Some of the features in Warden® include the ability to:

create three types of jails: a traditional FreeBSD jail for running network services, a (less secure) ports jail for safely installing and running FreeBSD ports/packages from your PC-BSD® system, and a Linux jail for installing Linux

set multiple IPv4 and IPv6 addresses per jail

quickly install common network server applications on a per-jail basis

update installed software on a per-jail basis

manage user accounts on a per-jail basis

manage ZFS snapshots on a per-jail basis

export a jail which can be then be imported into the same or a different jail

Creating a Jail using the GUI Version of Warden®

Warden® can be started by clicking on its icon in Control Panel or by typing pc-su warden gui from the command line. You will be prompted for your password as administrative access is needed to create and manage jails. The initial Warden® configuration screen is shown in Figure Is there no version? a.

To create your first jail, click the "New Jail" button or go to File ➜ New Jail. A jail creation wizard, seen in Figure Is there no version? b, will launch.

Figure Is there no version? b: Creating the New Jail

The first screen in the jail creation wizard will prompt you for the following information:

Hostname: you can change the default of "Jailbird" to another value. The hostname must be unique on your network and can not contain a space. Use a hostname that reminds you of the type of jail and your reason for creating it.

IPV4 Address: input the IPv4 address to be used by the jail and access its contents. Choose an address on your network that is not already in use by another computer or jail and which will not conflict with the address range assigned by a DHCP server.

IPv6 Address: if you plan to access the jail and its contents using IPv6, check the "IPv6 Address" box and input an IPv6 address that is not already in use by another computer or jail on your network.

When finished, click "Next" to select the type of jail, as shown in Figure Is there no version? c:

Figure Is there no version? c: Select the Type of Jail

There are three types of jails supported by Warden®:

Traditional Jail: select this type if you are creating the jail in order to install and run network services. For example, this type of jail is appropriate if you wish to run a web server or a database which is accessible to other systems on a network or over the Internet. This is the most secure type of jail as it is separate from the PC-BSD® host and any other jails that you create using Warden®. By default, FreeBSD's next generation of package management, known as pkgng, and the command line versions of the PC-BSD® utilities are added to a default FreeBSD installation. If you do not plan to use these tools, uncheck the box “Install PKGNG and PC-BSD utilities”. If you have already created a jail template, select the desired operating system version from the “Jail Version” drop-down menu.

Ports Jail: select this type of jail if your intention is to install software using FreeBSD packages and ports and you wish to have access to that software from your PC-BSD® system or if you plan to install any GUI applications within the jail. This type of jail is less secure then a traditional jail as applications are shared between the jail and the PC-BSD® system. This means that you should not use this type of jail to install services that will be available to other machines over a network.

Linux Jail: select this type of jail if you would like to install a Linux operating system within a jail. Linux jail support is considered to be experimental and is limited to 32-bit.

The remaining screens will differ depending upon the type of jail that you select.

Traditional or Ports Jail

If you select "Traditional Jail", you will be prompted to set the root password as seen in Figure Is there no version? d.

Figure Is there no version? d: Setting the Traditional Jail's Root Password

Input and confirm the password then press "Next" to see the screen shown in Figure Is there no version? e. If you instead select to create a "Ports Jail", you will go directly to Figure Is there no version? e.

Figure Is there no version? e: Select the Jail Options

This screen allows you to install the following options:

Include system source: if you check this box, make sure that /usr/src/ exists on the PC-BSD system as the source is copied to the jail from this location. If it is not installed, use Control Panel ➜ System Manager ➜ Tasks ➜ Fetch PC-BSD System Source to install it.

Include ports tree: if you check this box, the latest version of the ports tree will be downloaded into /usr/ports/ of the jail. This will allow you to compile FreeBSD ports within this jail.

Start jail at system bootup: if this box is checked, the jail will be started (become available) whenever you boot your main system. If the box is not checked, you can manually start the jail whenever you wish to access it using Warden®.

Once you have made your selections, click the "Finish" button to create the jail. Warden® will display a pop-up window containing status messages as it downloads the files it needs and creates and configures the new jail.

Once Warden® is finished creating the jail, a message should appear at the bottom of the pop-up window indicating that the jail has been successfully created. Click the "Close" button to return to the main screen.

Linux Jail

If you select the "Linux Jail" and click "Next", you will be prompted to set the root password as seen in Figure Is there no version? d. After inputting the password, the wizard will prompt you to select a Linux install script, as seen in Figure Is there no version? f.

Figure Is there no version? f: Select the Linux Distribution to Install

The installation script is used to install the specified Linux distribution. At this time, installation scripts for Debian Wheezy and Gentoo are provided.

A Linux installation script is simply a shell script which invokes a Linux network installation. In the case of Debian Wheezy, it invokes the debootstrap command.

Once you select the install script, the wizard will ask if you would like to start the jail at boot time as seen in Figure Is there no version? g.

Figure Is there no version? g: Linux Jail Options

Click the "Finish" button to begin the Linux installation.

Configuring Existing Jails From the GUI

Once a jail is created, an entry for the jail will be added to the "Installed Jails" box and the tabs within Warden® will become available. Each entry indicates the jail's hostname, whether or not it is currently running, and whether or not any updates are available for the meta-packages installed within the jail. The buttons beneath the "Installed Jails" box can be used to start/stop the highlighted jail, configure the jail, add a new jail, or delete the highlighted jail.

If you highlight a jail and click "Jail Configuration", the screen shown in Figure Is there no version? h will open.

Figure Is there no version? h: Jail Configuration Options

The Options tab has one checkbox for enabling or disabling VNET/VIMAGE support. This option provides that jail with its own, independent networking stack. This allows the jail to do its own IP broadcasting, which is required by some applications. However, it breaks some other applications. If an application within a jail is having trouble with networking, try changing this option to see if it fixes the issue.

The IPv4 tab is shown in Figure Is there no version? i.

Figure Is there no version? i: Jail IPv4 Options

This screen allows you to configure the following:

IPv4 Address: uncheck this box if you do not want the jail to have an IPv4 address.

IPv4 Bridge Address (Requires VNET): if this box is checked, an IP address is input, and the "IPv4 Default Router" box is left unchecked, the bridge address will be used as the default gateway for the jail. If the "IPv4 Default Router" address is also configured, it will be used as the default gateway address and the bridge address will be used as just another address that is configured and reachable. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

IPv4 Default Router: check this box and input an IP address if the jail needs a different default gateway address than that used by the PC-BSD® system. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

The IPv6 tab is shown in Figure Is there no version? j.

Figure Is there no version? j: Jail IPv6 Options

This screen allows you to configure the following:

IPv6 Address: check this box if you want the jail to have an IPv6 address.

IPv6 Bridge Address (Requires VNET): if this box is checked, an IPv6 address is input, and the "IPv6 Default Router" box is left unchecked, the bridge address will be used as the default gateway for the jail. If the "IPv6 Default Router" address is also configured, it will be used as the default gateway address and the bridge address will be used as just another address that is configured and reachable. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

IPv6 Default Router: check this box and input an IPv6 address if the jail needs a different default gateway address than that used by the PC-BSD® system. This option requires the "Enable VNET/VIMAGE support" checkbox to be checked in the Options tab.

The Aliases tab is shown in Figure Is there no version? k.

Figure Is there no version? k: Jail Aliases Options

Click the drop-down menu to see all of the options shown in Figure Is there no version? k. An alias allows you to add additional IP addresses to an interface. Select the type of address you would like to add an alias to, click the Add button, type in the IP address to add and click OK.

The Permissions tab is shown in Figure Is there no version? l. This screen can be used to easily enable or disable the sysctl values that are available for jails.

Figure Is there no version? l: Jail Permissions

Info Tab

The "Info" tab, as seen in the example in Figure Is there no version? m, provides an overview of a jail's configuration. If you have created multiple jails, the "Info" tab displays the configuration of the currently highlighted jail.

Figure Is there no version? m: Info Tab of Warden®

In the example shown in Figure Is there no version? m, three jails have been created: a traditional jail, a ports jail, and Debian Squeeze has been installed into a Linux jail.

The "Info" tab contains the following information:

Jail Type: will indicate if the jail is a Traditional, Ports, or Linux jail.

Size on Disk: indicates the amount of space being used by the jail. The jail itself takes up about 300MB of space, source is about 300MB, and ports are about 850MB.

Start at boot: a status of "Enabled" indicates that the jail will automatically start when the system reboots. "Disabled" means that you will manually start the jail as needed.

Active Connections: will list the number of active connections to the jail (e.g. through ssh or one of the running services).

IPs: lists the jail's IP address as well as any configured aliases.

Listening on Ports: indicates which ports are currently listening for connections.

You can sort the jail listing by clicking on the "Jail", "Status", or "Updates" header name. The "Updates" column will indicate if a software or system update is available for a jail.

Tools Tab

The "Tools" tab, shown in Figure Is there no version? n, allows you to manage common configuration tasks within a jail.

Make sure that the desired jail is highlighted when using the "Tools" tab.

Figure Is there no version? n: Tools Tab for the Highlighted Jail

This tab provides the following buttons:

AppCafe: opens AppCafe® so that you can install packages within the specified traditional or ports jail. Software installed using this method will be tracked by Update Manager, meaning that Warden® will be notified when updates are available for the installed software. Since BSD-based packages are not available for Linux jails, this button is not available if a Linux jail is highlighted.

User Administrator: opens User Manager so that you can manage the highlighted jail's user accounts and groups. The title bar will indicate that you are "Editing Users for Jail:Jailname". Note that any users and groups that you have created on your PC-BSD® system will not be added to a traditional jail as each traditional jail has its own users and groups. However, a ports jail has access to the users and groups that exist on the PC-BSD® system, yet the users you create on a ports jail will only be available within the ports jail. This button is not available if a Linux jail is highlighted.

Service Manager: opens Service Manager so that you can view which services are running in the jail and configure which services should start when the jail is started. Note that this button is not available if a Linux jail is highlighted.

Launch Terminal: opens a terminal with the root user logged into the jail. This allows you to administer the jail from the command line. This button will be greyed out if the highlighted jail is not running. You can start a jail by right-clicking its entry and selecting "Start this Jail" from the menu or by clicking "Start Jail".

Check for Updates: launches Update Manager to determine if any system updates are available to be installed into the jail. If an update is found, the text "Updates available!" will appear in the "Updates" column for that jail. Note that this button is not available if a Linux jail is highlighted.

Export Jail: launches a pop-up window prompting you to choose the directory in which to save a backup of the jail (and all of its software, configuration, and files) as a .wdn file. Creating the .wdn file may take some time, especially if you have installed src, ports, or software.

Snapshots Tab

The “Snapshots” tab, shown in Figure Is there no version? o, is used to create and manage ZFS snapshots within the currently highlighted jail. The ZFS snapshot feature can be used to make point in time filesystem backups of jails. A snapshot is essentially a picture of what the filesystem looked like at that point in time. Snapshots are space efficient in that they take up zero space when created and the snapshot only grows in size as files contained within the snapshot are modified after the snapshot was taken. In other words, ZFS manages the changes between snapshots, providing a way to return to what a file looked like at the time a snapshot was taken.

Since jails share the filesystem used by PC-BSD®, any type of jail, including a Linux jail, can take advantage of this ZFS feature.

Figure Is there no version? o: Snapshots Tab for the Highlighted Jail

To create a snapshot of the jail, click the "+Add" button. A snapshot indicating the date and time will be added to the slider bar. If you create multiple snapshots at different times, use the slider bar to select a snapshot.

Once you have created a snapshot, the following actions can be used to manage the snapshot. Make sure that the desired snapshot is highlighted in the slider bar before clicking these buttons:

Restore: returns the system to what it looked like at the time the snapshot was taken. Think about what you wish to accomplish before using this option as any changes to files that occurred after the snapshot was taken will be lost.

Add: use this button to create additional snapshots.

Remove: use this button to remove the highlighted snapshot.

This screen also allows you to schedule automatic snapshots. To enable this feature, check the box "Scheduled Snapshots". Use the drop-down menu to set the frequency to daily or hourly. You can also type in or use the arrows to configure the number of days to keep each snapshot.

Configure Menu

To refresh the settings for all jails, use Configure ➜ Refresh Jails.

To configure Warden®, click Configure ➜ Settings which will open the screen shown in Figure Is there no version? p.

Figure Is there no version? p: Warden® Configuration

This screen allows you to configure the following:

Jail Network Interface: all jails created within Warden® share the same physical interface. Use the drop-down menu to select the network interface to be used by the jails. Note that your jails may not work if the wrong interface is configured.

Jail Directory: contains all of the created jails where each jail has its own sub-directory named after its IP address. By default, it is /usr/jails. If you change this directory, make sure the location has sufficient space to hold the jails.

Temp Directory: used when exporting and importing jails. Make sure that the directory has sufficient space to create a tar file of the jail and its contents.

Right-Click Menu

If you highlight a jail, its right-click menu contains the following options:

Start or Stop this Jail: allows you to start a jail (if it is currently not running) or to stop a jail (if it is currently running). You will not be able to access a jail that has not been started. The icon next to the jail will change to indicate the current status.

Toggle Autostart: toggles a jail's Autostart between "Disabled" (does not automatically start when the PC-BSD® system is booted) and "Enabled" (will start the jail when the PC-BSD® system is booted). The "Info" tab will be updated to indicate the new "Start at boot" status. Note that toggling autostart will not affect the current running status of the jail (i.e. it does not start or stop the jail right now) as autostart is only used when the system boots.

Export jail to .wdn file: allows you to save the jail (and all of its software, configuration, and files) as a .wdn file. This allows you to quickly clone a pre-configured jail to a new jail on either the same or another PC-BSD® system. The exported jail will end with a .wdn extension and the filename will be the IP address of the jail. When exporting a jail, a pop-up window will prompt you to choose the directory in which to store the backup. A progress bar will indicate that the export is in progress. Creating the .wdn file may take some time, especially if you have installed src, ports, or software.

You should close all network connections to the jail before exporting it as Warden® will need to stop the jail in order to back it up. If your jail is running services (e.g. a webserver), export the jail at a time that will least impact network connections to the jail.

Clone this Jail: creates an instantaneous copy of the specified jail. It will prompt for a hostname for the new jail. Highlight the new clone and click “Jail Configuration” to set the addressing information for the new jail.

Delete Jail: removes the jail and all of its contents from the PC-BSD® system. You will be prompted to confirm this action.

Bold text

Importing a Jail

The "File" menu can be used to create a new jail, import a jail, create templates, or exit Warden®.

If you click File ➜ Import Jail you will be prompted to browse to the location of a previously created .wdn file. After selecting the file, you will then see the screen shown in Figure Is there no version? q.

Figure Is there no version? q: Importing a Jail

Input a name for the new jail. If you are creating a new jail on the same system that still has the original jail installed, check the "IPv4 Address" box and input an unused IP address for the new jail. Then, check the box "Hostname" and input an unused hostname for the new jail. However, if you have deleted the original jail or need to restore that same jail on another computer (for example, there was a hardware failure on the system containing the original jail), you can choose to leave both boxes unchecked and to reuse the same IP address and hostname. Once you press OK, Warden® will recreate the jail with all of the original settings. Whether or not those settings include the original IP address and hostname depends upon your selections.

Using Template Manager

The built-in template manager can be used to create and manage jail templates. Once created, templates can be used when installing a new jail. A template specifies the version and architecture of FreeBSD to be used as the operating system running in the jail. Templates have been tested from FreeBSD versions 4.1.1 to FreeBSD-CURRENT. Until you create your own templates and specify them during jail creation, the default version and architecture of the operating system used in the jail will be the same as that running on the PC-BSD® system.

To create a template, click File ➜ Template Manager to see the screen shown in Figure Is there no version? r.

Figure Is there no version? r: Template Manager

The default icon will indicate the version of TrueOS® used by the underlying PC-BSD® system. To create a new template, click the + button. In the "System Type" drop-down menu select either:

TrueOS: adds the command line versions of the PC-BSD® utilities to the FreeBSD base.

FreeBSD: uses only the FreeBSD base without any of the PC-BSD® utilities.

Press OK to see the screen shown in Figure Is there no version? s.

Figure Is there no version? s: Select the Operating System Version

If desired, change the 10.0 in this example to the release number to use. If you selected FreeBSD as the system type, a list of available release numbers can be found on this FreeBSD webpage[27]. If you selected TrueOS, the list of available release numbers is currently limited to 9.0, 9.1, 9.2, 9.3, 10.0, and 10.1.

Press OK. In the "System Architecture" drop-down menu, select either amd64 (for 64-bit) or i386 (for 32-bit). Press OK and input a nickname for the template. Click OK and the files needed for that version will be downloaded. Once the template is created, it will appear in the Template Manager as seen in the example in Figure Is there no version? t.

Figure Is there no version? t: New Template Added

To delete a template, highlight it and click the - button. Note that Warden® will not let you delete a template if any jails exist which are using the template.

To use the template when creating a new jail, click the "Jail Version" drop-down menu shown in Figure Is there no version? c and select the desired template.

Using the Command Line Version of Warden®

The Warden® GUI is based on a Bourne shell script. This script can be manually run from the command line on a PC-BSD® server or by users who prefer using the command line. Advanced users can also refer to the command line version in their own scripts.

If you type warden at the command line, you will receive a summary of its usage:

Each command has its own help text that describes its parameters and provides a usage example. For example, to receive help on how to use the warden create command, type:

warden help create

Warden version 1.4

---------------------------------
Help create
Creates a new jail, with options for system source, ports and autostarting.
Available Flags:
-32 Create 32bit jail on 64bit system
--autoipv4 Use the next available IPv4 address from the pool
--ipv4=<ip/mask> Set primary IPv4 address for jail
--ipv6=<ip/mask> Set primary IPv6 address for jail
--archive <tar> Use specified tar file for BSD jail creation
--bulk <number> Create <number> of new jails, using default IP4 pool
or address pool specified with --ip4pool
--ip4pool <address> Starting IPv4 address to use when creating jails in bulk
--linuxjail <script> Make this a linux jail and use supplied script for installation
--linuxarchive <tar> Use specified tar file for Linux jail creation
--pluginjail Make this a pluginjail
--ports Includes the ports tree
--portjail Make this a portjail
--src Includes /usr/src system source
--startauto Start this jail at system boot
--template <string> Specify a jail template to build with
--vanilla Don't install PC-BSD pkgng repo and utilities
--version <string> Use this instead of /etc/version
Usage:
warden create <JAILNAME> <flags>
Example:
warden create jailbird --ipv4=192.168.0.25/24 --src --ports --startauto

You do not need superuser access to use the view commands but will for any commands that create or manage a jail. The warden command will display an error message if a command requires superuser access and you currently are not the superuser. On PC-BSD®, you can put pc-su at the beginning of the warden command to be prompted for your password. On a FreeBSD server, you can type su to become superuser, then repeat the warden command.

Creating and Accessing a Jail

Before creating a jail, verify the network settings in /usr/local/etc/warden.conf:

#!/bin/sh
# Configuration options for the Warden
######################################################################
# Network Interface for the jails to use
NIC:
# Directory to use for compressing / decompressing files
WTMP: /usr/jails
# Location of the jails
JDIR: /usr/jails
# When automatically creating jails with unspecified IPv4 addresses, use this
# address at the starting point for new addresses
IP4POOL: 192.168.0.220

You can either specify the FreeBSD interface name to use in the NIC field or specify the IP address range starting point with the IP4POOL field. When using IP4POOL on a network containing a DHCP server, ensure that the DHCP server has reserved the range of addresses to be used by jails in order to prevent IP address conflicts.

To create a jail, specify a unique IP address and hostname for the jail:

As the jail starts, the SSH host keys will be generated and sshd will start. At this point, you can use the warden chroot command to access the jail from the host system. Alternately, to access the jail over the network using ssh, you will need to first create a user account.

To access the jail in order to create that user:

warden chroot jail1

Started shell session on jail1 . Type exit when finished.

adduser

Follow the prompts of the adduser script in order to create a user. When you get to the following prompt, do not press enter. Instead type in wheel so that the user can use the su command to become the superuser within the jail.

Login group is username. Invite username into other groups? [] wheel

When you are finished creating the user, you can type exit to exit the jail. Test that ssh works by specifying the username that you created:

ssh username@jail1

To create multiple jails simultaneously, use the --bulk <number> and --ip4pool <starting address> options to specify the number of jails and the starting IP address. Alternately, instead of –ip4pool, use the --autoipv4 option as it automatically assigns the next available IP address from the pool, as defined by the IP4POOL option in /usr/local/etc/warden.conf.

Managing Jails from the Command Line

Table a shows the command line equivalents to the graphical options provided by the Warden® GUI. To get usage examples for each command, insert help into the command. For example, to get help on the auto command, type warden help auto. Note that some options are only available from the command line.

Table Is there no version? a: Command Line and GUI Equivalents [Tables 4]

Command Line

GUI

Description

auto

right-click highlighted jail and click Autostart

toggles the jail's autostart between Enabled and Disabled

bspkgng

in the GUI, this happens automatically during jail creation unless "Install PKGNG and PC-BSD utilities" is unchecked

adds the PC-BSD® utilities to an existing jail

checkup

in the GUI, update checks occur automaticaly and any un-applied updates are shown in the Updates column

checks for updates to either the specified jail or all jails

chroot

Tools ➜ Launch Terminal

opens a terminal with the root user logged into the jail

create

"+" button or File ➜ New Jail

creates a new jail with specified attributes

details

Info tab

provides an overview of specified jail's configuration

delete

"-" button or right-click jail ➜ Delete Jail

deletes the specified jail

export

right-click ➜ Export jail to .wdn file

saves the specified jail and all of its software, configuration, and files as a .wdn file.

fbsdupdate

Tools ➜ Check for Updates

upgrades FreeBSD world with security fixes as well as any package updates

fbsdupgrade

Tools ➜ Check for Updates

upgrades FreeBSD to new version

fstab

opens the jail's /etc/fstab in an editor

get

configure (wrench) icon for highlighted jail

lists the various IP addresses used by the jail

import

File ➜ Import Jail

import a previously created .wdn file

list

"Installed Jails" section of GUI

list all jails

pkgupdate

Tools ➜ Check for Updates

update all packages in specified jail

pkgs

Tools ➜ AppCafe

lists packages installed into specified jail

pbis

lists PBIs installed into specified jail

set

right-click jail

used to set options, addresses, aliases, and permissions in specified jail

start

right-click jail ➜ Start this Jail

starts the specified jail

stop

right-click jail ➜ Stop this Jail

stops the specified jail

type

"Jail Type" during jail creation

types differ as choices are pbibox, portjail, pluginjail, or standard; to create a Linux jail, instead use the linuxjail option with the create command

Java, Flash, and Fonts

Multimedia

Files and File Sharing

MythTV

XBMC

Windows Emulation

Remote Desktop

Thin Client

ownCloud

ownCloud[28] is open source software that allows you to create your own cloud storage. This allows you to share data, contacts, and calendars with other devices and users.

Figure 9.9a: Install ownCloud

In PC-BSD®, you can create your own private cloud service by installing ownCloud either into a traditional jail that you created using Warden® or into a TrueOS® installation. For security reasons, installing ownCloud directly onto a desktop installation is not recommended, as the web and database services it requires may expose the desktop to security vulnerabilities. If you are installing ownCloud on a PC-BSD® system, create a traditional jail as it isolates the software installed into the jail from your desktop operating system. This section demonstrates how to install and configure ownCloud using Warden®.

Install and Start the Required Services

First, create a traditional jail using these instructions. Once the jail is created, make sure that the jail has been started, then go to the “Tools” tab of the jail and click the “Package Manager” button as seen in the example in Figure 9.9a.

Check the boxes for databases ➜ mysql56-server and www ➜ owncloud, then click the “Apply” button to install these packages.

Once installed, go to Tools ➜ Service Manager which will open the screen shown in Figure 9.9b. Highlight the apache22 service and click the "Enable Service" button and then the "Start" button. Repeat for the mysql service.

Verify that you can reach the web server by typing the IP address of the jail into a web browser. You should receive an "It works!" message. You will need to first allow incoming TCP port 80 on the jail interface using Firewall Manager if you use a web browser on a different computer.

Configuring ownCloud

THIS HAS CHANGED

You are now ready to configure ownCloud. Click the “Launch Terminal” button to access the shell of the jail. Then, configure the MySQL database, substituting ocuser and mypass with the username and password that you wish to use:

Test your changes from a web browser by adding "owncloud" to the end of the IP address of the jail. For example, type http://10.0.0.1/owncloud/. You should see the setup screen shown in Figure 9.9c.

Figure 9.9d: ownCloud Interface

Input the name of the user and password that will be used to administer ownCloud, then click the "
"Advanced" button. In the advanced settings, click the "MySQL" tab and input the MySQL username, password, and database name that you configured previously. Click the “Finish setup” button to save your changes and enter your new cloud interface -- shown in Figure 9.9d.

Click the left panel of the interface to access a type of media. For example, if you click "Files" and then the "New" button, you can upload a file, folder, or from a URL. If you click "Contacts", you can add a contact or import/export the address book.

Click the "Settings" icon at the bottom of the left panel to add users, configure applications, change the administrative configuration, and to access "Help".

Supporting PC-BSD®

Become a Beta Tester

Become a Translator

Become a Developer

Flat htmlProtection (edit): Edited by: Tigersharke

Introduction

If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the developers mailing list[31]. Once you have signed up, feel free to browse the active tickets in the PC-BSD® Bug database[32]. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.

Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.

Getting the Source Code and Development Tools

The PC‑BSD® source code is available from github and git needs to be installed in order to download the source code. When using PC‑BSD®, git is included in the base install.

To download the source code, cd to the directory to store the source and type:

git clone git://github.com/pcbsd/pcbsd.git

This will create a directory named pcbsd/ which contains the local copy of the repository. To keep the local copy in sync with the official repository, run git pull within the pcbsd directory.

PC‑BSD® graphical applications use Qt version 5 and their source is located in pcbsd/src-qt5/. In order to compile the applications in this directory, install the "PC-BSD Build ToolChain" PBI using AppCafe®. To instead install this PBI from the command line, type pbi add devel/pcbsd-toolchain.

Most of the PC‑BSD® source code is divided into two sub-categories:

src-sh/ contains shell and C programs which do not include GUIs. These are the command line utilities used in TrueOS® and PC-BSD® and which are installed by the FreeBSD ​sysutils/pcbsd-utils port.

src-qt5/ contains the Qt5-based GUIs seen in PC-BSD® and which are installed by the ​FreeBSD sysutils/pcbsd-utils-qt5 port

To compile the command line utilities:

cd src-sh

make

To compile the graphical utilities:

cd src-qt4

/usr/local/lib/qt5/bin/qmake

make

Several Qt IDEs are available in AppCafe®. The "QtCreator[33] PBI is a full featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. Qt Designer[34] is lighter weight as it is only a .ui file editor and does not provide any other IDE functionality. It can be installed as the "qt5-designer" raw package using AppCafe® or pkg install.

If you plan to submit changes so that they can be included in PC-BSD®, fork the repository using the instructions at Fork a repo[35]. Make your changes to the fork, then submit them by issuing a git pull request[36]. Once your changes have been reviewed, they will be committed or sent back with suggestions.

Basic Guidelines for Writing a PC‑BSD® Utility

PC‑BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC‑BSD®. Going forward, we aim to present a unified design so that programs feel "familiar" to users. As an example, while programs could have "File", "Main", or "System" as their first entry on the "File menu", we want to present one option, "File", as it is the accepted norm for the first category on the menu bar.

Figure Is there no version? a: AppCafe® File Menu

This section describes a small list of guidelines to menu and program design in PC‑BSD®. Since most programs designed for the last couple of decades have followed this structure, it makes sense for us to follow the same standard.

File Menus

Any graphical program that is a full-featured utility, such as Warden® or AppCafe®, should have a file menu. However, file menus are not necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most PC‑BSD® utilities do not need more than two or three items on the file menu. An example of a well laid out "File" menu is AppCafe®, shown in Figure Is there no version? a.

"Configure" is our adopted standard for the category that contains "Settings" or other configuration related settings. If additional categories are needed, check to see what other PC‑BSD® utilities are using.

File Menu Icons

File menu icons are taken from the KDE "Oxygen" theme located in /usr/local/share/icons/oxygen. Use these file menu icons so we do not have a bunch of different icons used for the same function. Table Is there no version? a lists the commonly used icons and their default file names.

Table Is there no version? a: Commonly Used File Menu Icons [Tables 5]

Function

File Menu Icon

File Name

Quit

row 1, cell 2

window-close.png

Settings

row 2, cell 2

configure.png

Buttons

PC‑BSD® utilities use these buttons as follows:

Apply: applies settings and leaves the window open.

Close: closes program without applying settings.

OK: closes dialogue window and saves settings.

Cancel: closes dialogue window without applying settings.

Save: saves settings and closes window.

Fully functional programs like AppCafe® and Warden® do not use close buttons on the front of the application. Basically, whenever there is a "File" menu, that and an x in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule. A good example of a widget program would be Update Manager.

Keyboard Shortcuts

Many users benefit from keyboard shortcuts and we aim to make them available in every PC‑BSD® utility. Qt makes it easy to assign keyboard shortcuts. For instance, to configure keyboard shortcuts that browse the "File" menu, put &File in the text slot for the menu entry when making the application. Whichever letter has the & symbol in front of it will become the hot key. You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key. Be careful not to duplicate hot keys or shortcut keys. Every key in a menu and submenu should have a key assigned for ease of use and accessibility. Tables Is there no version? b and Is there no version? c summarize the commonly used shortcut and hot keys.

Saving Settings in a Qt Application

When saving an application's settings, the QSettings class should be used if possible. There are two different "organizations", depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization for applications that run with user permissions and "PCBSD-root" for applications that are started with root permissions via sudo. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples Is there no version? a and Is there no version? b demonstrate how to use the QSettings class for each type of permission.

Resources

Report Bugs

Have you found a bug in PC-BSD®? If so, please take the time to read through this section to ensure that your bug gets reported to the correct group and is resolved in a timely fashion.

First, determine the type of bug that you are encountering. Is it a bug that is preventing you from properly installing and running PC-BSD® (a system bug), or is it an issue with an installed software package such as FireFox (an application bug)?

An application bug can fall into a few different categories.

Application Packaging Bug

The first is a packaging bug, which is when you can not install the application or it simply crashes on startup. Please report these types of bugs by logging into the Bugs Database[40] and creating a new "PBI Packaging" issue. Select/enter the operating system version you are using. Use descriptive words in the "Summary". In the "Description", provide as much detail as possible about the bug, such as:

the name of the program

a detailed description of the bug, including any error messages and which commands or menus you used to generate the error

If you would like to include a screenshot of the error or a log that includes error messages, check the box "I have files to attach to this ticket" to browse to the location of the attachment. Use the "Preview" button to read through your ticket to make sure that the information is clear to the person who will resolve the issue. When finished, click the "Create ticket" button to submit your bug report.

Application Runtime Bug

An application runtime bug occurs when an application installs and is able to start successfully, but during use, it crashes or exhibits some other type of undesired behavior. An example would be OpenOffice failing to import a type of document properly or a chat client unable to keep a connection to a network.

If you installed the application using AppCafe® and you think that the problem is related to how the PBI was packaged, report the bug on the PBI Discussion Forum[41]. If you suspect that the problem is with the underlying FreeBSD port, you can use FreshPorts.org to determine the email address of the port maintainer. If you do email the port maintainer, indicate the name of the port, any error messages that you receive and how to reproduce the bug, and indicate if you are able to assist the maintainer in testing any patches to the port. Once the port is fixed, let the PBI Discussion Forum know so that the PBI can be rebuilt using the fixed port.

System Driver Bugs

A system bug is any bug which prevents the initial installation of PC-BSD®, or causes issues with hardware. Some examples would be a non-bootable system, failed installation, missing drivers for your hardware, or a non-functional desktop after installation. To report this type of issue please follow the instructions below for your type of system bug.

An example of a system driver bug would be a missing network driver, no sound output, or no disk drives detected. Most of these types of issues are directly related to the FreeBSD base upon which PC-BSD® is built, and are best fixed by discussing them with the FreeBSD team directly. Reporting a bug to FreeBSD can be done using the Send PR[42] page. You should also search the FreeBSD mailing lists as other users may have already discovered the bug or have a work-around for your particular hardware. Below are some of the related mailing lists:

Purchase PC-BSD® Swag

Host a Mirror

NOTE: In late 2013 PC-BSD switched to a CDN for its file-distribution.

Seed a Torrent

PC-BSD® is also distributed as a torrent[49] and you can increase download speeds for other users by seeding, especially during the first two weeks after a new release. If you are new to seeding, read through the GotBSD FAQ[50] first.

The Network-P2P category of AppCafe® provides several torrent utilities including: