3. Install

This chapter describes how to use the graphical installer to install a graphical desktop directly onto a hard drive or into a virtual machine using virtualization software such as VirtualBox.

To begin the TrueOS® installation, insert the prepared boot media and boot the system. If the computer boots into an existing operating system instead of the installer, reboot and check the computer’s BIOS program to ensure the drive containing the installation media is listed first in the boot order. Save any BIOS changes and reboot.

Once the system boots it displays the menu shown in Figure 3.1. Press Enter or simply wait a few moments and this menu automatically prompts the system to continue booting.


Fig. 3.1 Initial Boot Menu


See BSD Boot Loader for a detailed description of this menu.

If a key other than Enter is pressed, this screen pauses to provide additional time to review the options. If this screen is not paused, it automatically boots into the Boot Multi User option, displaying the first graphical installer screen, shown in the Language install section.

The rest of this chapter describes the screens of the graphical installer. If any problems arise with booting into the graphical installer, please refer to the Installation Troubleshooting section of this handbook.

3.1. Language

The first graphical installer screen, seen in Figure 3.1.1, indicates the installer successfully loaded and is ready to present its options.


Fig. 3.1.1 Welcome and Language Selection Screen

On the bottom-left side of the screen are several icons and buttons to help with the installation, explained in Table 3.1.1:

Table 3.1.1 Installer icons
Icon Function
System with wrench Access hardware compatibility information to quickly determine if the system’s video card, Ethernet card, wireless device, and sound card are compatible with TrueOS®.
Light Bulb Read a screen’s Help text.
Keyboard Use the onscreen keyboard.
“L” key and U.S. Flag Switch between the US keyboard layout and a user selected layout.
Blue and White Orb Opens the Network Manager in order to configure system networking during the installation process.
Command Prompt Window Access the emergency shell described in Using the System Utilities Menu.
Abort Cancel the installation.
Next Navigate to the next or previous screen.

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


The default keyboard layout can be changed at this point, during the post-installation Choose a Language screen, when Logging In, or during an active session using the included fcitx utility.

There is also an option to Load config from USB. If the configuration from a previous installation has been saved, it can be loaded at this time from a FAT formatted USB stick.

By default, TrueOS® menus display in English, unless another language is selected in the drop-down menu in this screen. The menus in TrueOS® are being continuously translated to other languages. To view the availability of a specific language, navigate to the TrueOS® Translation Site. A language may show less than 100% translation, indicating not all of the menus are translated. Any untranslated menus are displayed in English. Refer to Translation to assist in translating the graphical menus.


Small screens may not display the entire installer window, resulting in buttons at the bottom of the window being hidden and inaccessible. In this situation, either press Alt while dragging the window with the mouse or press Alt+N to select the next button of the window.

When finished reviewing this screen, click Next to move on to the next installation screen.

3.2. System Selection

The System Selection screen installs a graphical desktop or a console-based server operating system, as seen in Figure 3.2.1. It also can be used for Restore from Life Preserver backup. This chapter concentrates on a desktop installation. Refer to the Server Installation instructions for installing a command-line only server.


Fig. 3.2.1 System Selection Screen

By default, TrueOS Desktop (graphical interface) is selected. The Lumina® Desktop is installed with TrueOS, but additional software can be installed later using AppCafe.

To install the desktop, click Next.


When installing to an existing PC-BSD® or TrueOS® system, a pop-up window asks to install to the existing pool without reformatting it. Press OK to keep the existing pool. Clicking Cancel formats the existing pool and all of its data. Refer to the Upgrading from PC-BSD® 10.x to TrueOS® section for more information about this option.

3.3. Optional Packages

By default, TrueOS® loads only two graphics drivers during the installation: VESA (for MBR) and SCFB (for UEFI). TrueOS® provides the option to further choose your graphics driver as part of the Figure 3.3.1 screen.


Fig. 3.3.1 Optional Installation Packages

When installing TrueOS®, it detects the onboard graphics solution and displays a list of drivers you can use for TrueOS®. Additionally, VirtualBox is automatically detected, populating the list with Virtual Environment Drivers.

Expand the desired list of drivers and choose one which is compatible with your hardware, then click Next to continue.

3.4. Disk Selection

The Disk Selection screen, seen in Figure 3.4.1, summarizes the default disk configuration.


Fig. 3.4.1 Disk Selection Screen


By default, TrueOS® assumes the user wants to install on the entire first disk. When installing TrueOS® as the only operating system on the computer, click Next to start the installation. However, if this is not intended, review the rest of this section to determine how to layout the disk. If TrueOS® is to be booted with another operating system, please review the section on Dual Booting.

To select the disk or partition to install TrueOS®, click Customize Disk Settings to start the TrueOS® Disk Wizard, shown in Figure 3.4.2.


Fig. 3.4.2 TrueOS® Disk Wizard

The wizard provides two modes of operation:

  • Basic: (default) Select this mode if to specify the installation partition or disk.
  • Advanced: Select this mode to specify the installation partition or disk, use MBR partitioning, change the default ZFS pool name, force the block size used by ZFS, configure a multi-disk installation, add a log or cache device, encrypt the disk, or specify the filesystem layout.


Regardless of the selected mode, once the disk wizard completes and Next is chosen at the Disk Selection screen, a pop-up window asks to start the installation. Be sure to review the Summary area before clicking Yes and starting the installation. The Disk Selection screen is the very last chance to ensure the system is correctly configured. After clicking Yes, the selected hard drive or partition is formatted, losing any existing data.

Once finished configuring the disk, you can save your choices for later use. Insert a FAT32 or MSDOSFS formatted USB stick and click Save Config to USB.

3.4.1. Basic Mode

Select Basic and the wizard displays the screen shown in Figure 3.4.3.


Fig. 3.4.3 Disk or Partition Selection

The first hard disk is typically selected. To install on a different disk, use the Disk drop-down menu to select the install disk.

By default, the entirety of the selected disk is formatted. If the disk is divided into partitions or there is an area of free space, use the Partition drop-down menu to choose the desired partition.


TrueOS® only installs into a primary MBR partition, a GPT partition, or an area of free space. TrueOS® cannot install into a secondary or an extended partition. To create an area of free space for installation, refer to Creating Free Space.

For EFI/UEFI systems, you can choose to Install rEFInd. The rEFInd boot manager is used to provide a menu of boot options to the user when the computer boots. It is required by TrueOS® when Dual Booting.


rEFInd is a boot manager which functions separately from the FreeBSD bootloader.

Once the disk and partition are selected, click Next to view a Summary screen to review your choices. To make additional changes, press Back to return to a previous screen. Otherwise, click Finish to leave the wizard. Click Next then Yes to start the installation.

3.4.2. Advanced Mode

After selecting advanced mode, the wizard displays the screen shown in Figure 3.4.4.


Fig. 3.4.4 Advanced Mode Options

This screen has several options:

  • Disk: Choose the install disk.
  • Partition: Select the desired partition or area of free space.


TrueOS® onlys install into a primary MBR partition, a GPT partition, or an area of free space. TrueOS® cannot install into a secondary or an extended partition. To create an area of free space for installation, refer to Creating Free Space.

  • Partition Scheme: The default GPT (Best for new hardware) is a partition table layout supporting larger partition sizes than the traditional MBR (Legacy) layout. If the installation disk or partition is larger than 2 TB, the GPT option must be selected. Since some older motherboards do not support GPT, if the installation fails, try again with MBR (Legacy) selected. When in doubt, use the default selection.


The Partition Scheme section does not appear if a partition other than Use entire disk is chosen in the Partition drop-down menu.

  • ZFS pool name: To use a pool name other than tank (default), check this box and type the name of the pool in the text window. Root is reserved and can not be used as a pool name.
  • Force ZFS 4k block size: This option is only used if the disk supports 4k, even though the disk may lie and report its size as 512b. Use with caution as it may cause the installation to fail.
  • Install rEFInd: For EFI/UEFI systems, you can choose to Install rEFInd. The rEFInd boot manager is used to provide a menu of boot options to the user when the computer boots. It is required by TrueOS® when Dual Booting.

After making any selections, click Next to access the ZFS configuration screens. The rest of this section provides a ZFS overview and then demonstrates how to customize the ZFS layout. ZFS Overview

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

If new to ZFS, the Wikipedia entry on ZFS provides an excellent starting point to learn about its features. Additionally, FreeBSD Mastery: ZFS by Michael W Lucas and Allan Jude is a helpful ZFS resource as it is implemented in FreeBSD.

These resources are also useful to bookmark and peruse as needed:

Table 3.4.1 is a brief glossary of terms used by ZFS:

Table 3.4.1 ZFS Terms
Term Description
Pool A collection of devices providing physical storage and data replication managed by ZFS. This pooled storage model eliminates the concept of volumes and the associated problems of partitions, provisioning, wasted bandwidth, and stranded storage. Thousands of filesystems can draw from a common storage pool, each one consuming only its required space. The combined I/O bandwidth of all devices in the pool is available at all times to all filesystems. The Storage Pools Recommendations of the ZFS Best Practices Guide provides detailed recommendations for creating the storage pool.
Mirror A form of RAID where all data is mirrored onto two or more disks, creating a redundant copy should a disk fail.
RAIDZ ZFS software solution equivalent to RAID5, as it allows one disk to fail without losing data. Requires at least 3 disks.
RAIDZ2 Double-parity ZFS software solution similar to RAID6, as it allows two disks to fail without losing data. Requires a minimum of 4 disks.
RAIDZ3 Triple-parity ZFS software solution. RAIDZ3 offers three parity drives and can operate in degraded mode if up to three drives fail with no restrictions on which drives can fail.
Dataset Once a pool is created, it can be divided into datasets. A dataset is similar to a folder as it supports permissions. A dataset is also similar to a filesystem since properties such as quotas and compression can be set.
Snapshot A read-only, point-in-time copy of a filesystem. Snapshots can be created quickly and, if little data changes, new snapshots take very little space. For example, a snapshot with no changed files takes 0 MB of storage, but a changed 10 GB file will store both old and new versions. Snapshots provide a clever way of keeping a history of files, should an older copy or even a deleted file need to be recovered. For this reason, many administrators snapshot often (e.g. every 15 minutes), store them for a period of time (e.g. for a month), and store them on another system. Such a strategy allows the administrator to roll the system back to a specific time, or if there is a catastrophic loss, an off-site snapshot can restore the system up to the last snapshot interval (e.g. within 15 minutes of the data loss). Snapshots can be cloned or rolled back, but the files on the snapshot can not be accessed independently.
Clone A writable copy of a snapshot which can only be created on the same ZFS volume. Clones provide an extremely space efficient way to store many copies of mostly-shared data such as workspaces, software installations, and diskless clients. Clones do not inherit the properties of the parent dataset, but rather inherit the properties based on where the clone is created in the ZFS pool. Because a clone initially shares all its disk space with the original snapshot, its used property is initially zero. As changes are made to the clone, it uses more space.
ZIL A filesystem journal that manages writes. The ZIL is a temporary storage area for sync writes until they are written asynchronously to the ZFS pool. If the system has many sync writes, such as from a database server, performance can be increased by adding a dedicated log device known as a SLOG (Secondary LOG). If the system has few sync writes, a SLOG will not speed up writes. When creating a dedicated log device, it is recommended to use a fast SSD with a supercapacitor or a bank of capacitors able to handle writing the contents of the SSD’s RAM to the SSD. If a dedicated log device is needed, the SSD should be half the size of system RAM, as anything larger is unused capacity. Note a dedicated log device can not be shared between ZFS pools, and the same device cannot hold both a log and a cache device.
L2ARC ZFS uses a RAM cache to reduce read latency. If an SSD is dedicated as a cache device, it is known as an L2ARC and ZFS uses it to store more reads which can increase random read performance. However, adding a cache device will not improve a system with too little RAM and actually decreases performance, as ZFS uses RAM to track the contents of L2ARC. RAM is always faster than disks, so always add as much RAM as possible before determining if the system would benefit from a L2ARC device. If a lot of applications do large amounts of random reads on a dataset small enough to fit into the L2ARC, read performance may be increased by adding a dedicated cache device. SSD cache devices only help if the working set is larger than system RAM, but small enough that a significant percentage of it fits on the SSD. Note a dedicated L2ARC device can not be shared between ZFS pools. ZFS Layout

In Advanced Mode, the disk setup wizard allows configuring the ZFS layout. The initial ZFS configuration screen is seen in Figure 3.4.5.


Fig. 3.4.5 ZFS Configuration

If the system contains multiple drives to be used to create a ZFS mirror or RAIDZ*, check Add additional disks to storage pool, which enables this screen. Any available disks are listed in the box below the ZFS Virtual Device Mode drop-down menu. Select the desired level of redundancy from the ZFS Virtual Device Mode drop-down menu, then check the box for each disk to add to the configuration.


The TrueOS® installer requires entire disks (not partitions) when adding more disks to the pool.

While ZFS allows using disks of different sizes, this is discouraged as it decreases storage capacity and ZFS performance.

The TrueOS® installer supports multiple ZFS configurations:

  • mirror: Requires a minimum of 2 disks.
  • RAIDZ1: Requires a minimum of 3 disks. For best performance, a maximum of 9 disks is recommended.
  • RAIDZ2: Requires a minimum of 4 disks. For best performance, a maximum of 10 disks is recommended.
  • RAIDZ3: Requires a minimum of 5 disks. For best performance, a maximum of 11 disks is recommended.
  • stripe: Requires a minimum of 2 disks.


A stripe does NOT provide ANY redundancy. If any disk fails in a stripe, all data in the pool is lost!

The installer does not allow a configuration choice in which the system does not meet the required number of disks. When selecting a configuration, a message indicates how many more disks are required.

When finished, click Next to choose cache and log devices, shown in Figure 3.4.6.


Fig. 3.4.6 L2ARC and ZIL

This screen can be used to specify an SSD as an L2ARC read cache or as a secondary log device (ZIL). Any available devices are listed in the boxes in this screen.


A separate SSD is needed for each type of device.

Refer to the descriptions for ZIL and L2ARC in the ZFS Overview to determine if the system would benefit from any of these devices before adding them in this screen. When finished, click Next to move to the encryption options, shown in Figure 3.4.7.


Fig. 3.4.7 Encryption

This screen can be used to configure full-disk encryption. This is meant to protect the data on the disks should the system itself be lost or stolen. This type of encryption prevents the data on the disks from being available during bootup unless the correct passphrase is typed at the bootup screen. Once the passphrase is accepted, the data is unencrypted and can easily be read from disk.

To configure full-disk encryption, check Encrypt disk with GELI. This option will be greyed out if GPT (Best for new hardware) is not selected as GELI does not support MBR partitioning. If needed, use Back to go back to the Advanced Mode screen and select GPT (Best for new hardware). Once that box is checked, input a strong passphrase twice into the Password fields. It is recommended to create a long and memorable password, but something difficult to guess.


This passphrase is required to decrypt the disks. If the passphrase is lost or forgotten, all access will be lost to the encrypted data!

When finished, click Next to move to the mount point screen shown in Figure 3.4.8.


Fig. 3.4.8 Default ZFS Layout

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


Do not remove any of the default mount points. These are all used by TrueOS®.

Use Add to add additional mount points. The system will ask for the name of the mount point as size is not limited at creation time. Instead, the data on any mount point can continue to grow as long as space remains within the ZFS pool.

To set the swap size, click Swap Size. This prompts you to enter a size in MB. If a RAIDZ* or mirror exists, a swap partition of the specified size is created on each disk and mirrored between the drives. For example, if a 2048 MB swap size is specified, a 2 GB swap partition is created on all the specified disks, but the total swap size is 2GB because of redundancy.

Right-click any mount point to toggle between enabling or disabling many ZFS properties:

  • atime: When set to on, controls whether the access time for files is updated when they are read. When set to off, this property avoids producing write traffic when reading files. This can result in significant performance gains, though it may confuse mailers and other utilities.
  • canmount: If set to off, the filesystem is unmountable.
  • casesensitivity: The default is sensitive, as UNIX filesystems use case-sensitive file names. For example, “kris” is different from “Kris”. To tell the dataset to ignore case, select insensitive.
  • checksum: Automatically verifies the integrity of the data stored on disks. Turning this property off is highly discouraged.
  • compression: If set to on, automatically compresses stored data to conserve disk space.
  • exec: If set to off, processes can not be executed from within this filesystem.
  • setuid: If set to on, the set-UID bit is respected.

After clicking Next, the wizard shows a summary of the selections. To make further changes, use Back to return to a previous screen. Otherwise, click Finish to leave the wizard and return to the Disk Selection screen.

3.5. Installation Progress

Once Yes is selected to start the installation, a progress screen, seen in Figure 3.5.1, updates the user on the installation progress.


Fig. 3.5.1 Installation Progress

How long the installation takes depends upon the speed of the hardware and the installation type selected. A typical installation takes between 5 and 15 minutes.

3.6. Installation Finished

The Installation Finished screen, shown in Figure 3.6.1, appears once the installation is complete.


Fig. 3.6.1 TrueOS® Installation Complete

Click Finish to complete the TrueOS® installation. The system immediately begins the reboot process. Once the system is fully shut down, remove the installation media to ensure the system boots from the freshly installed local drive.

3.7. Advanced Installation Topics

This section covers these advanced installation topics:

If your intent is to install a graphical desktop using the graphical installer, refer instead to the primary Install section.

3.7.1. Server Installation

The System Selection screen of the TrueOS® installer can be used to install a FreeBSD-based command-line server operating system rather than a graphical desktop operating system. A TrueOS® server installation includes the SysAdm™ API and SysAdm™ Client for managing the server locally or remotely.

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

  • The ability to easily configure ZFS during installation.
  • The ability to configure multiple boot environments.
  • A wizard (described in this section) is provided during installation to configure the server for first use.

To perform a server installation, start the TrueOS® installation as usual. At the System Selection screen of the installer, select TrueOS Server (console interface only).

Click Next to start the Server Setup Wizard, then click Next again to see the screen shown in Figure 3.7.1.


Fig. 3.7.1 Root Password Creation

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


Fig. 3.7.2 Primary User Account Creation

For security reasons, do not login as the root user. The wizard requires creating a primary user account for logging into the server. This account is automatically added to the wheel group, allowing the user to su to the root account when administrative access is required.

Create an account by filling in these fields:

  • Name: Can contain capital letters and spaces.
  • Username: The name to use for logging in. It cannot contain spaces and is case sensitive (e.g. Kris is a different username than kris).
  • Password: The password to use for logging in. Type it twice to confirm it.
  • Default shell: Use the drop-down menu to select the csh, tcsh, sh, or bash login shell.

When finished, click Next to proceed to Figure 3.7.3.


Fig. 3.7.3 Hostname Creation

Input the system’s hostname. If using ssh to connect to the system, check Enable remote SSH login. Click Next to proceed to the network configuration screen shown in Figure 3.7.4.


Fig. 3.7.4 Network Configuration

Use the Network Interface drop-down menu to choose the desired interface:

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

Alternately, use the drop-down menu to select the device name for the interface and manually configure and input the IPv4 and/or IPv6 addressing information. When finished, click Next to access the screen shown in Figure 3.7.5.


Fig. 3.7.5 Optional Install Features

To install the FreeBSD ports collection, check Install ports tree then click Finish to exit the wizard and access the summary screen shown in Disk Selection.

If installing the server to a system with ZFS already installed, you can choose to Install to disk or Install into boot Environment.

When installing to disk, click Customize Disk Settings to configure the system’s disk(s). When installing into a Boot Environment, you can select the ZFS Pool for installation using the drop-down menu.

To save the install configuration for re-use at a later time, insert a MSDOSFS or FAT32 formatted USB stick and click Save Config to USB.

When ready to continue, click Next. A new window asks if you are ready to begin the installation. Click Yes to continue or No to continue modifying the install configuration.

Once the system is installed, it boots to a command-line login prompt. Login using the primary user account configured during installation. Now the server can be configured like any other FreeBSD server installation. The FreeBSD Handbook is an excellent reference for performing common FreeBSD server tasks.

3.7.2. Restore from Life Preserver backup

If you have replicated the system’s snapshots to a remote backup server, you can use a TrueOS® installation media to perform an operating system restore or to clone another system. Start the installation as usual and select to Restore from Life Preserver backup in the System Selection Screen.

Before you can perform a restore, the network interface must be configured. Click the Network Connectivity (blue circle) icon in order to determine if the network connection was automatically detected. If not, refer to the instructions in the Network Manager section of this handbook and ensure networking is functional before continuing.

Once you are ready, click Restore from Life Preserver backup and Next. This starts the Restore Wizard. In the SSH Restore shown in Figure 3.7.6, type the IP address of the backup server and the name of the user account that replicated the snapshots. If the server is listening on a non-standard SSH port, change the SSH port number.


Fig. 3.7.6 : Beginning a SSH Restore

Click Next and the wizard provides a summary of your selections. If correct, click Finish. Otherwise, click Back to correct them.

Once the connection to the backup server succeeds, you can select which host to restore. After making your selection, click Next. The restore wizard provides a summary of which host it restores from, the name of the user account associated with the replication, and the hostname of the target system. Click Finish and the installer proceeds to the Disk Selection Screen. At this point, you can click Customize to customize the disk options. However, any ZFS datasets will be greyed out as they are to be recreated from the backup during the restore. Once you are finished with any further customizations, click Next to perform the restore.

3.7.3. Dual Booting

A TrueOS® installation assumes there is an existing GPT or primary partition for installation. If the computer has only one disk and TrueOS® is the only operating system, it is fine to accept the default partitioning scheme. However, if TrueOS® is to share space with other operating systems, ensure TrueOS® is installed into the correct partition, or an existing operating system may be overwritten.


As adjusting the partitions/spacing on active disks can be a complicated and difficult process, it is recommended to partition your disk for dual booting before installing any operating systems.

Dual booting with TrueOS® has several requirements:

  • An EFI or UEFI partitioning scheme. TrueOS® does not support the older MBR partition scheme, opting instead to use rEFInd for managing or booting into operating systems. TrueOS still uses the BSD boot loader, as it provides native support for ZFS boot environments. Be sure to select Install rEFInd when installing TrueOS® (see Disk or Partition Selection).
  • A partition for each operating system. Many operating systems, including TrueOS®, can only be installed into a primary or GPT partition. See Creating Free Space for an example of shrinking a disk in Windows to allow for dual booting with TrueOS®.
  • Back up any existing data! It is recommended to store this backup on a different computer, removable media such as a USB drive or DVD media.

When installing TrueOS® onto a computer meant to contain multiple operating systems, carefully select the correct partition in the Disk Selection screen. On a system containing multiple partitions, each partition is listed.


Avoid selecting a partition containing an operating system or essential data.

Highlight the desired partition and click Customize. Clicking Next without customizing the disk layout results in the installer overwriting the contents of the primary disk.

Once installed, the system boots into the rEFInd menu seen in Figure 3.7.7.


Fig. 3.7.7 rEFInd Boot Manager

rEFInd displays any installed operating systems, booting into the default choice after a few seconds. Press any key other than Enter to pause automatic booting, then use the arrow keys to select the desired operating system. Press Enter to continue booting.

3.7.4. Using the System Utilities Menu

The System Utilities menu is available from the “Emergency Shell” icon (see Installer icons) in the various TrueOS® installer screens. Once opened, you’ll see the menu shown in Figure 3.7.8.


Fig. 3.7.8 System Utilities Menu

This screen provides several options:

  • shell: This option is useful when troubleshooting a TrueOS® system that no longer boots. It opens a shell with administrative access, including the base FreeBSD utilities. Advanced users can use this shell to identify a problem, create a backup or copy essential files to another system, or alter configuration files with an editor like ee or vi. When finished using the shell, type exit to return to the System Utilities Menu.
  • zimport This option displays the names of available ZFS pools. Type the name of an available pool and the utility imports the pool then displays the available boot environments (BEs). Type the name of the desired BE and zimport mounts the BE then offers to open a chroot shell so the environment’s contents can be viewed and edited as needed in order to perform maintenance on the boot environment. When finished, type exit to leave the boot environment and return to the System Utilities Menu.
  • fixgrub: This option is scheduled for removal as GRUB is no longer supported by TrueOS®.
  • exit: This option returns the user to the main TrueOS® Installation Menu.

3.7.5. Upgrading from PC-BSD® 10.x to TrueOS®


If any user account uses PersonaCrypt, please be sure to save any encryption keys to a safe place (e.g. a thumb drive) before beginning the upgrade process. Loss of encryption keys may result in being unable to import the home directory after the upgrade is complete.

If the system is using PC-BSD® 10.x, the option to update to TrueOS® does not appear in the Control Panel version of Update Manager. This is because a new installation is required in order to migrate to TrueOS®. However, the TrueOS® installer allows the user to keep all their existing data and home directories as it provides the ability to install TrueOS® into a new boot environment. In other words, the new operating system and updated applications are installed while the ZFS pool and any existing boot environments are preserved. Since the new install is in a boot environment, the option to boot back into the previous PC-BSD® installation remains.


This option overwrites the contents of /etc. If any custom configurations exist, save them to a backup or the home directory first. Alternately, use the SysAdm Boot Environment Manager post-installation to mount the previous PC-BSD® boot environment to copy over any configuration files which may not have been backed up.

To perform the installation to a new boot environment, start the TrueOS® installation as described earlier in the chapter. In the System Selection screen, choose to install either a desktop or a server. Press Next to view the Disk Selection screen, shown in Figure 3.7.9.


Fig. 3.7.9 Disk Selection

TrueOS® automatically detects if the drive has an existing boot environment, filling in the data as necessary. If no boot environments are detected, Install into Boot Environment is invisible. To upgrade, select Install into Boot Environment and choose which existing pool to install into from the drop-down menu. In the Disk Selection Screen, the user is installing into the existing tank pool. Press Next when ready.


Be sure Install into Boot Environment is checked before proceeding, or data can be lost.

A pop-up will appear, asking to start the default Full-Disk installation. Click Yes to begin the installation.

Once the installation is complete, reboot the system and remove the installation media. The post-installation screens run as described in the Post-Install section to help configure the new installation.


During the Create a User process, recreate the primary user account using the same user name and user id (UID) from the previous PC-BSD® system. This allows TrueOS® to associate the existing home directory with that user. Once logged in, use the SysAdm User Manager to recreate any other user accounts or to reassociate any PersonaCrypt accounts.

3.7.6. Automated Installations

TrueOS® provides a set of Bourne shell scripts to allow advanced users to create automatic or customized TrueOS® installations. pc-sysinstall is the name of the master script. The script reads a customizable configuration file and uses dozens of backend scripts to perform the installation. Read more about this utility by typing man pc-sysinstall.

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

  • /usr/local/share/pc-sysinstall/backend/ contains the scripts used by the TrueOS® installer. Scripts have been divided by function, such as functions-bsdlabel.sh and functions-installcomponents.sh. To learn more about how the TrueOS® 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/local/share/pc-sysinstall/backend-query/ contains the scripts used by the installer to detect and configure hardware.
  • /usr/local/share/pc-sysinstall/conf/ contains the configuration file pc-sysinstall.conf. It also contains a file indicating which localizations are available (avail-langs), an exclude-from-upgrade file, and a licenses/ subdirectory containing text files of applicable licenses.
  • /usr/local/share/pc-sysinstall/doc/ contains the help text seen if pc-sysinstall is run without any arguments.
  • /usr/local/share/pc-sysinstall/examples/ contains several example configuration files for different scenarios (e.g. upgrade and fbsd-netinstall). The README in this directory should be considered as mandatory reading before using pc-sysinstall.
  • /usr/sbin/pc-sysinstall is the script used to perform a customized installation.

This section discusses the steps needed to create a custom installation.

First, determine which variables to customize. A list of possible variables can be found in /usr/local/share/pc-sysinstall/examples/README and are summarized in Table 3.7.1.


This table is meant as a quick reference to determine which variables are available. The README in /usr/local/share/pc-sysinstall/examples/ contains more complete descriptions for each variable.

Table 3.7.1 Customizing a TrueOS® Installation
Variable Options Description
hostname= should be unique for the network optional as installer will auto-generate a hostname if empty
installMode= “fresh”, “upgrade”, “extract”, or “zfsrestore” sets the installation type
installLocation= /path/to/location used only when installMode is extract and should point to an already mounted location
installInteractive= “yes” or “no” set to “no” for automated installs without user input
netDev= “AUTO-DHCP” or FreeBSD interface name type of network connection to use during the installation
netIP= IP address of interface used during installation only use if netDev is set to an interface name
netMask= subnet mask of interface only use if netDev is set to an interface name
netNameServer= IP address of DNS server only use if netDev is set to an interface name
netDefaultRouter= IP address of default gateway only use if netDev is set to an interface name
netSaveDev= AUTO-DHCP or FreeBSD interface name(s) (multiple allowed separated by spaces) type of network configuration to enable on the installed system; can set multiple interfaces
netSaveIP= IP address of interface 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 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”, or “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”, or “split” defaults to “round-robin” if the mirrorbal method is not specified
bootManager= “none” or “bsd”  
image= /path/to/image /mountpoint will write specified image file
commitDiskPart   this variable is mandatory and must be placed at the end of each diskX section; create a diskX section for each disk you wish to configure.
encpass= password value at boot time, system will prompt for this password in order to mount the associated GELI encrypted partition
commitDiskLabel   this variable is mandatory and must be placed at the end of disk’s partitioning settings; see the README for examples on how to set the <File System Type> <Size> <Mountpoint> entries for each disk
installMedium= “dvd”, “usb”, “ftp”, “rsync”, or “image” source to be used for installation
localPath= /path/to/files location of directory containing installation files
installType= “PCBSD” or “FreeBSD” determines whether this is a desktop or a server install
installQuiet “yes” or “no” set to “yes” for automatic installations
installFile= e.g. “fbsd-release.tbz” only set if using a customized installer archive
packageType= “tar”, “uzip”, “split”, “dist”, or “pkg” the archive type on the installation media
distFiles= e.g. “base src kernel” list of FreeBSD distribution files to install when using packageType=dist
ftpPath= ftp://ftp_path location of the installer archive when using installMedium=ftp
rsyncPath= e.g. “life-preserver /back-2011-09-12T14_53_14” location of the rsync data on the remote server when using installMedium=rsync
rsyncUser= username set when using installMedium=rsync
rsyncHost= IP address of rsync server set when using installMedium=rsync
rsyncPort= port number set when using installMedium=rsync
installComponents= e.g. “amarok, firefox, ports” components must exist in /PCBSD/pc-sysinstall/components/; typically, installPackages= is used instead
installPackages= e.g. “Xorg cabextract list of traditional or pkg packages to install; requires pkgExt=
pkgExt= ”.txz” specify the extension used by the type of package to be installed
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 new user
userComment= description description text can include spaces
userPass= password of user  
userEncPass encrypted string set user password to specified encrypted string
userShell= e.g. “/bin/csh” path to default shell
userHome= e.g. “/home/username” path to home directory
defaultGroup= e.g. “wheel” default group
userGroups= e.g. “wheel, operator” comma separated (no spaces) list of additional groups
commitUser   mandatory, must be last line in each user block
runCommand= full path to command run the specified command within chroot of the installed system, after the installation is complete
runScript= full path to script runs specified script within chroot of the installed system, after the installation is complete
runExtCommand= full path to command runs a command outside the chroot
runPrePkgCommand= full path to command runs the specified command before starting the pkg installation
runPrePkgScript= full path to command runs the specified sript before starting the pkg installation
runPrePkgExtCommand= full path to command runs the specified command before extracting the pkg
runPreExtractCommand= full path to command runs the specified command before extracting
runPreExtractScript= full path to command runs the specified command before starting the pkg installation
runPreExtractExtCommand= full path to command runs the specified command before starting the pkg installation
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 log in automatically without entering a password
sshHost= hostname or IP address the address of the remote server when using installMode=zfsrestore
sshPort= e.g “22” the SSH port number of the remote server when using installMode=zfsrestore
sshUser= username the username on the remote server when using installMode=zfsrestore
sshKey= e.g. “/root/id_rsa” path to the SSH key file on the remote server when using installMode=zfsrestore
zfsProps= e.g. ”.lp-props -tank#backups#mybackup” location of dataset properties file created by Life Preserver during replication when using installMode=zfsrestore
zfsRemoteDataset= e.g. “tank/backups/ mybackup” location of remote dataset to restore from when using installMode=zfsrestore

Next, create a customized configuration. One way to create a customized configuration file is to read through the configuration examples in /usr/local/share/pc-sysinstall/examples/ and follow the most relevant example. Copy the file to any location and customize it so it includes the desired variables and values in the installation.

An alternate way to create this file is to start an installation, configure the system as desired, and save the configuration to a USB stick (with or without actually performing the installation). Use the saved configuration file as-is, or customize it to meet an installation’s needs. This method may prove easier when performing complex disk layouts.

To perform a fully automated installation which does not prompt for any user input, review /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf and place a customized copy of the file into /boot/pc-autoinstall.conf on the installation media.

Table 3.7.2 summarizes the additional variables available for fully automatic installations. More detailed descriptions can be found in the /usr/local/share/pc-sysinstall/examples/pc-autoinstall.conf file.


The variables in this file use a different syntax than those in Customizing a TrueOS® Installation as the values follow a colon (:) and a space rather than an = sign.

Table 3.7.2 Automated Installation Variables
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”, or booting the wrong disk will result in a system wipe
shutdown_cmd e.g. shutdown -p now running a shutdown is recommended, but this can be any command/script to execute post-install
nic_config “dhcp-all” or <interface name> <IP address> <subnet mask> attempts DHCP on all found NICs until the installation file is fetched or will setup a specified interface
nic_dns IP address DNS server to use
nic_gateway IP address default gateway to use

Finally, create a custom installation media or installation server. pc-sysinstall supports two installation methods:

  1. From CD, DVD, or USB media.
  2. From an installation directory on an HTTP, FTP, or SSH+rsync server.

The easiest way to create a custom installation media is to modify an existing installation image. For example, if an ISO for the TrueOS® version to customize is downloaded, the superuser can access the contents of the ISO with a few commands:

[name@example] mdconfig -a -t vnode -f TrueOS-Desktop-2016-08-11-x64-DVD.iso.md5 -u 1

[name@example] mount -t cd9660 /dev/md1 /mnt

Make sure to cd into the desired destination directory for the copied ISO contents. In the next examples, /tmp/custominstall/ was created for this purpose:

[name@example] cd /tmp/custominstall

[name@example] tar -C /mnt -cf - . | tar -xvf -

[name@example] umount /mnt

Alternately, if an installation CD or DVD is inserted, mount the media and copy its contents to the desired directory

[name@example] mount -t cd9660 /dev/cd0 /mnt

[name@example] cp -R /mnt/* /tmp/custominstall/

[name@example] umount /mnt

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

Copy the customized configuration file to /tmp/custominstall/. Double-check the installMedium= variable in the customized configuration file is set to the correct installation media.

Adding extra files may be necessary if certain variables are set in the custom configuration file:

  • installComponents= Any extra components to install must exist in extras/components/.
  • runCommand= The command must exist in the specified path.
  • runScript= Make sure the script exists in the specified path.
  • runExtCommand= Ensure the command exists in the specified path.

If the installation media is a CD or DVD, create a bootable media containing the files in the directory. To create a bootable ISO:

[name@example] cd /tmp/custominstall

[name@example] mkisofs -V mycustominstall -J -R -b boot/cdboot -no-emul-boot -o myinstall.iso

Use a preferred burning utility to burn the ISO to the media.

To begin an installation that requires user interaction, type pc-sysinstall -c /path_to_your_config_file

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

If using an HTTP, FTP, or SSH server as the installation media, untar or copy the required files to a directory on the server accessible to users. Be sure to configure the server so installation files are accessible to the systems to install.