1. Introduction

Written by users of the TrueOS® operating system. Maintained and edited by Dru Lavigne and Tim Moore.

Welcome to TrueOS®!

This Handbook covers the installation and use of TrueOS®. This Handbook is a work in progress and relies on the contributions of many individuals. To assist with the Handbook, refer to the documentation README. If using IRC, join the #trueos channel on the Freenode network to converse with many other TrueOS® users. Gitter is another popular option for users.

TrueOS® (formerly known as PC-BSD®) began in 2005 when Kris Moore presented the first beta version of a FreeBSD operating system pre-configured for desktop use. Since then, TrueOS® has matured into a polished, feature-rich, free-of-charge, open source operating system that meets the desktop or server needs of the beginner to the advanced user alike.

TrueOS® is essentially a customized installation of FreeBSD, not a forked derivative. Since the underlying FreeBSD system is kept intact, you have a fully functional FreeBSD system under the hood. TrueOS® provides an easy-to-use installer which can be used to install a desktop or a server version of FreeBSD. Other differences from FreeBSD include:

  • TrueOS® pre-configures the BSD-licensed Lumina® desktop environment during a desktop installation. Additional desktop environments can be installed and appear in the graphical login menu, allowing the user to select their preferred environment.
  • The TrueOS® installer supports configuring ZFS and encryption during installation.
  • TrueOS® provides both a graphical and a command line software management system.
  • TrueOS® provides many graphical utilities for system configuration and management. These utilities have both a command line equivalent and a REST and WebSocket API so they can also be used to manage multiple systems.
  • TrueOS® comes pre-configured with a number of automatic scripts for performing tasks like connecting digital cameras or USB memory sticks.
  • The TrueOS® boot menu supports boot environments or snapshots of the operating system. The TrueOS® Update Manager automatically adds a new boot environment to the boot menu before updating the operating system. With this functionality, if an update fails, the system can be rebooted into the previous version of the operating system before the update was installed. This allows for easy recovery if any issues happen during the update process.

While started as an independent project, TrueOS® has been financially backed and supported by the enterprise-class hardware solutions provider iXsystems since October 2006.

1.1. Features

TrueOS® provides many features:

  • Easy installation: To install either a graphical desktop or command-line server, simply insert the installation media, reboot the system to start the installer, and answer a few questions in the installation menus.
  • Automatically configured hardware: Video, sound, network, and other devices are configured automatically during installation.
  • Customizable desktop interface: TrueOS® installs the Lumina® desktop but additional desktop environments can be installed to support day-to-day computing needs.
  • Easy software management: With the SysAdm AppCafe, installing, upgrading, and uninstalling software is safe and easy.
  • Lots of software available: AppCafe® is used to install software ported to FreeBSD (currently over 26,100 applications).
  • Easy to update: TrueOS® (with SysAdm) provides a built-in Update Manager which provides notifications of available updates. This utility makes it easy to apply operating system security fixes, bug fixes, and system enhancements. Additionally, the Update Manager is used to upgrade the operating system or update installed software.
  • No fragmentation: TrueOS® hard drives never need defragmenting and are formatted with OpenZFS, a self-healing filesystem.
  • Laptop support: Provides power saving, swap space encryption, and automatic switching between wired and wifi network connections. The rolling release model of TrueOS® provides an environment to quickly add support for new hardware.
  • Easy system administration: TrueOS® provides many graphical tools for performing system administration.
  • Localization: TrueOS® supports a variety of native languages and locales out of the box.
  • Vibrant community: TrueOS® has a friendly and helpful community.

1.1.1. Security

The TrueOS® system is secure by default. This section describes an overview of the built-in security features. Additional information about increasing the security of the installed system beyond the configured defaults are also provided in this section.

The security features built into TrueOS® include:

  • Naturally immune to viruses and other malware: Most viruses are written to exploit the Windows operating system and are incompatible with the binaries and paths found on a TrueOS® system. Antivirus software is still available in the Security section of AppCafe®, as this is useful when sending or forwarding email attachments to users running other operating systems.
  • Potential for serious damage is limited: Privilege separation between users and root (the administrator account) are built in to TrueOS®. Files and directories can only be modified by the owning user, any specified groups, and root (depending on permissions). Any programs or scripts executed are only granted the permissions of that user. This means that a malicious program will only be able to affect the files and directories owned by that user and not core operating system files. Only users that are a member of the wheel and/or operator groups can gain administrative access and are not allowed to list the contents of a directory or access files outside of the “user” and “group” permissions that have been set.
  • Built-in firewall: The default firewall ruleset allows access to the Internet and the shares available on the network, but does not allow any inbound connections to the computer.
  • Very few services are enabled by default: The list of services that are started at boot time can be viewed by reading through the output of rc-update via the command line, or by using Service Manager in the SysAdm GUI. Service Manager also allows services to be started and stopped and also allow a service to be enabled or disabled at boot.
  • SSH is disabled by default: SSH can only be enabled by the superuser (also referred to as ‘root’ or the administrator user). This setting prevents bots and other users from trying to access the system. If SSH access is required and was not enabled during installation, add sshd_enable=YES to the /etc/rc.conf. The service can then be started by typing the service sshd start on the command line, or using the Service Manager in the SysAdm GUI. A firewall rule will also need to be added using the SysAdm Firewall Manager to allow SSH connections through the default SSH TCP port 22.
  • SSH root logins are disabled by default: If SSH is enabled, login as a regular user and use su or sudo when administrative actions are required. Do not change this setting, as it prevents an unwanted user from having complete access to the system.
  • sudo is installed: sudo is configured to allow users in the wheel group permission to run an administrative command after typing the user password, not the root password. By default, the first user created during installation is added to the wheel group. Use the SysAdm User Manager to add other users to the wheel group to allow that user administrative access. To change the default sudo configuration, always use the visudo as root. This command verifies there are no syntax errors, which could inadvertently prevent root access.
  • AES instruction set (AESNI) support is loaded by default for the Intel Core i5/i7 processors that support this encryption set. This support speeds up AES encryption and decryption.
  • Automatic notification of security advisories: The SysAdm Update Manager automatically checks for any updates that are available as the result of a security advisory affecting TrueOS®. This allows the administrator to keep the operating system fully patched against vulnerabilities with just the click of a mouse.
  • The TrueOS® operating system and its available software packages are built with LibreSSL, which has fewer vulnerabilities than OpenSSL.
  • PersonaCrypt allows a user to use a removable, encrypted device for the user’s home directory.
  • Tor Mode can be used to anonymously access Internet sites as it automatically forwards all Internet traffic through the Tor Project’s transparent proxy service.

To learn more about security on FreeBSD and TrueOS® systems, man security is a good place to start. These resources provide more information about security on FreeBSD based operating systems:

1.1.2. 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 1.1.1 is a brief glossary of terms used by ZFS:

Table 1.1.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 the old and new versions. Snapshots provide a clever way of keeping a history of files, which allows an older copy or even a deleted file to be recovered. For this reason, many administrators take snapshots often (e.g. every 15 minutes), store them for a period of time (e.g. for a month), and store them on another system. Such a strategy allows an administrator to roll a system back to a specific time, or in the event of 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, and individual files within a snapshot may be opened/copied (but unaltered) as needed.
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 that is 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 available 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 be used for 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 then known as an L2ARC. ZFS will then use the L2ARC to store more reads which can increase random read performance. 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 the L2ARC. RAM is always faster than disks, so always add as much RAM as possible before determining if the system would benefit from an L2ARC device. If a lot of applications do large amounts of random reads on a dataset that is small enough to fit into the L2ARC, read performance may be increased by adding a dedicated cache device. SSD cache devices will only help if the working set is larger than available system RAM, but small enough that a significant percentage of the data fits on the SSD. Note: A dedicated L2ARC device cannot be shared between ZFS pools.


The Insight file manager has the ability to mount snapshots and work with individual files in that snapshot. Individual files within a snapshot cannot be permanently deleted due to the built-in redundancy of ZFS. To wipe a file completely from disk, the entirety of every snapshot containing the file must be pruned.

1.2. TrueOS® Comparisons

As TrueOS® grows and evolves, many users appreciate comparisons with other operating systems. These comparisons are intended to help new users understand the abilities and features available when deciding to install TrueOS®. Accuracy is a chief concern.

1.2.1. FreeBSD and PC-BSD

These features or enhancements were introduced with TrueOS® and now separate TrueOS® from PC-BSD®:


PC-BSD® and FreeBSD are placed together as both are very similar “under the hood”. The differences for either OS to TrueOS® are listed here.

  • Based on FreeBSD-CURRENT.

  • The GRUB bootloader has been replaced by the FreeBSD bootloader, which now provides both GELI and boot environment support.

  • Quick boot times with OpenRC: TrueOS® is using OpenRC as part of the init process which allows services to be started in parallel. This results in dramatically improved system boot times for TrueOS®. OpenRC also improves general service management. One example is the ability to automatically run when new elements are introduced to the system, such as plugging in an Ethernet cable. Using OpenRC allows TrueOS® to use some system services that are different from FreeBSD. These differences are listed in Table 1.2.1

    Table 1.2.1 Differences between system services in TrueOS® and FreeBSD
    TrueOS® Service Started From FreeBSD Service
    openntpd Ports ntpd
    network Base netif
    wpa_supplicant Ports; Start with network wpa_supplicant (from Base)
    dhcpcd Ports dhclient


    The Differences between system services in TrueOS® and FreeBSD table is updated as development continues on the TrueOS® implementation of OpenRC. For a complete list of all available services in OpenRC, see Services and runlevels.

  • A TrueOS® installation includes the Lumina® Desktop. Additional window managers and desktop environments can be installed using the AppCafe®. Meta packages are available for popular desktop environments to allow easy installation of all required packages.

  • The SysAdm™ Client and Server has replaced Control Panel. Most of the utilities from Control Panel are rewritten to use the SysAdm middleware. Under the hood, SysAdm provides REST and WebSocket APIs for securely managing local or remote FreeBSD and TrueOS® systems.

  • Many utilities have been converted to the SysAdm API and many more are available through SysAdm:

    • AppCafe
    • Update Manager
    • Boot Environments
    • Devices
    • Firewall
    • Mouse Settings
    • Services
    • System Controls
    • Tasks
    • Users
    • Life Preserver
  • The functionality provided by the About utility is incorporated into Lumina Information.

  • The functionality provided by the Service Manager (pc-servicemanager) is integrated into SysAdm.

  • The Active Directory & LDAP utility (pc-adsldap) is deprecated.

  • Login Manager (pc-dmconf) is replaced by pcdm-config).

  • System Manager (pc-sysmanager) is deprecated.

  • freebsd-update is retired in favor of using pkg for system updates.

  • The option to use the scfb display driver is added to the installer. This driver is suitable for newer UEFI laptops as it automatically detects the native resolution. This is a good solution for newer Intel hardware that would otherwise require drivers that have not been ported to FreeBSD. Before selecting this driver, check the BIOS and ensure the CSM module is disabled.


Depending on the system hardware, the scfb driver may not support a dual-head configuration, for example, using an external port for presentations. Some hardware will support multi-monitors using the scfb driver but is dependant on how the graphics are embedded onto the hardware and which ports are attached to which video card(s). Support for suspend and resume is also dependant on manufacture implemenatation. See man 4 scfb and man 4 acpi for additional information.

  • Customize is removed from the System Selection screen in order to reduce the size of the installation media. Additional software can be installed post-installation using AppCafe®.
  • The Boot to console (Disable X) option has been added to the graphical boot menu.
  • The graphical and command line versions of PBI Manager and Warden are removed.
  • pc-thinclient is removed as it is deprecated.

1.2.2. Linux and TrueOS®

TrueOS® is based on FreeBSD, meaning it is not a Linux distribution. While there are many similarities with Linux, some features have different names and some commands have different flags or output on a BSD based system. This section will cover some of these differences.

BSD and Linux use different filesystems. Many Linux distros use EXT2, EXT3, EXT4, or BTRFS, while TrueOS® uses UFS or OpenZFS. In order to dual-boot with Linux or access data on an external drive formatted with another filesystem, it is imperative to research if the filesystem used is accessible to both operating systems.

Table 1.2.2 summarizes the various filesystems commonly used by desktop systems. TrueOS® automatically mounts several filesystems: FAT16, FAT32, EXT2, EXT3 (without journaling), EXT4 (read-only), NTFS5, NTFS6, and XFS.


A comparison of some popular graphical file management utilities available in TrueOS® can be found in the Files and File Sharing section.

Table 1.2.2 Filesystem Support on TrueOS®
Filesystem Native OS Non-native OS support Usage notes
Btrfs Linux none A modern copy on write (CoW) filesystem for the Linux OS. Btrfs is similar in nature to ZFS, and shares many of the same ideas with how a file system should work. Btrfs
EXT2 Linux r/w support loaded by default The successor to EXT. EXT2 was designed following the principles put forth in BSD’s Fast File System (FFS). The first commercial grade filesystem in Linux. The maximum supported volume size is 2TB - 32TB and the file size is 6GB - 2TB.
EXT3 Linux r/w support loaded by default EXT3 is EXT2 with the added benefit of journaling, online filesystem growth, and HTree indexing for larger directories. Journaling is not supported in BSD. Filesystems requiring a journal replay are unable to be mounted in BSD unless a fsck is run using an external utility such as the program package e2fsprogs The max volume size and file size is the same as EXT2.
EXT4 Linux r/o support loaded by default EXT4 is the succesor to EXT3 including enhancements to journaling, extended attributes, and journal checksumming (among many others) on linux. Using inodes greater than 128 bytes are not supported. Converting EXT3 default filesystems to EXT4 may have experience better performance. EXT4 increases the maximum volume size to 1EB and the maximum file size to 16GB to 16TB.
JFS Linux none Journaled File System is a 64-bit journaling file created by IBM. The maximum volume size is 32 PB and the maximum file size is 4PB.
ReiserFS Linux r/o support is loaded by default A general-purpose journaling file system that has fallen out of favor in recent years. The maximum volume size is 16TB, and maximum file size is 8TB.
FAT16 Windows r/w support loaded by default Max partition sizes up to 4GB. Cluster sizes vary from 2kb to 64kb, depending on partition size. Rarely used due to partition size limitations.
FAT32 Windows r/w support loaded by default Replaced FAT16. Maximum partition size of 2TB and a maximum file size of 4GB. 4KB clusters are used on partition sizes up to 8GB. For partitions larger than 8GB, the cluster size grows up to 32KB.
NTFS Windows full r/w support loaded by default The maximum volume size is 16EB -1kB and the maximum file size is 16TB -64kB. Unlike FAT32, the cluster size stays at 4KB regardless of the volume size used.
NTFS5 Windows r/w support loaded by default In addition to the NTFS features, NTFS5 also supports encryption, disk quotas, and sparse files. Other features may be available, but are beyond the scope of this handbook. Support for advanced features may not be supported in TrueOS® and should not be expected or relied on to work.
exFAT Windows r/w support using the fusefs-exfat package A file system optimized for flash memory such as USB flash drives and SD Cards. Use of this file system requires a license from Microsoft. The maximum volume size is 64ZB and the maximum file size is 16EB.
HFS+ Mac OS X none A file system developed by Apple Inc. HFS+ was developed to replace HFS. The max volume and file size is “slightly less” than 8EB. Older Mac versions may work using the GUI GUI application dedicated to HFS called hfsexplorer
UFS2 FreeBSD Linux support through ufsutils. r/w support on Mac. UFS Explorer can be used in Windows

Unix File System, also called Berkley Fast File System or FFS, is used by mnay Unix and Unix-like operating systems. UFS is a distant descendant of the original file system used by Version 7 Unix. UFS2 has a maximum volume size of 512ZB and a maximum maximum file size of 512GB - 32PB, depending on the implementation.

Note: As of Mac Lion, UFS has r/o support only.

ZFS TrueOS®, FreeBSD  

TrueOS has been using OpenZFS as its exclusive file system for several years, ensuring advanced OpenZFS functionality is heavily tested and 100% production-ready. ZFS was originally designed by Sun Microsystems, and has since been succeeded by the Open ZFS project which is jointly developed by developers from illumos, FreeBSD, Linux, and OS X to name a few.

See the ZFS Overview section of the handbook for an in-depth list of features and benefits of using ZFS and why it’s the default filesystem used by TrueOS®. The Open ZFS website has additional details on its implementation and use. The maximum volume size is 256ZB and maximum file size is 16EB.


exFAT partitions can be mounted read/write on FreeBSD using the fusefs-exfat package. Due to the Microsoft license used for exFAT, the package cannot come pre-installed by the OS. The user must manually install the fusefs-exfat package using AppCafe® or pkg install fusefs-exfat on the command line. When complete, the TrueOS® automount systems are already aware of exFAT and are able to automatically mount/access the devices as needed.

Linux and BSD use different naming conventions for devices. Here are some examples:

  • Linux Ethernet interfaces begin with eth, while BSD interface names indicate the name of the driver used to make the device function. An Ethernet interface named re0 indicates it uses the Realtek re driver. One advantage of this convention is the easy ability to find the respective man page. For the re driver issuing man 4 re will open the man page for the re driver which will list which models and features are provided by the driver. This convention applies to all drivers. man 4 wlan will open the wlan man page containing all wlan driver information.
  • BSD disk names differ from Linux. IDE drives begin with ada and SCSI and USB drives begin with da. Following the convention of informative device names, BSD applies this to disk drives as well. da0p1 is the 1st partition on the 1st USB/SCSI drive. da0p2 is the 2nd partition on the 1st USB/SCSI drive.


This convention continues with subsequent drives. da1p3 would be the 3rd partition on the 2nd USB/SCSI drive and ada4p6 would be the 6th partition on the 5th IDE drive. Physical drive numbering begins at 0, while the partition numbers on the drive start at 1.

Some of the features used by BSD have similar counterparts to Linux but the name of the feature may differ. Table 1.2.3 provides some common examples:

Table 1.2.3 BSD and Linux Feature Names
TrueOS Linux Description
IPFW iptables Default firewall
/etc/init.d/ for operating system and /usr/local/etc/init.d/ for applications rc0.d/, rc1.d/, etc. In TrueOS®, 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, init.d/ Terminals configured in ttys and rc.conf indicate which services start at boot time.

Users comfortable with the command line may find some of the common Linux commands have different names on BSD. Table 1.2.4 lists some common BSD commands and what they are used for.

Table 1.2.4 Common BSD and Linux Commands
Command Used
about Show useful information about the TrueOS® install. Very useful when trying to obtain help with issues.
dmesg Discover what hardware was detected by the kernel and and other system related information.
sysctl dev | less Display configured devices.
pciconf -l -cv Show PCI devices.
dmesg | grep usb Show USB devices.
kldstat List all modules currently loaded in the kernel.
kldload <module> Load a kernel module for the current session.
pkg install <pkgname> 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.

There are many articles and videos which provide additional information about some of the differences between BSD and Linux:

1.2.3. TrueOS and Windows

TrueOS® uses several similar, but different elements to their counterparts on Windows. Table 1.2.5 highlights a few of these:


This table isn’t meant to be an exhaustive listing of applications but simply provides a few TrueOS/FreeBSD equivalents for users familiar with their previous operating system.

Table 1.2.5 TrueOS/Windows equivalents
Element Windows TrueOS
Office Applications Microsoft Office LibreOffice
Image editing Photoshop GIMP
PDF viewing Acrobat Okular
Media Player Windows Media VLC Media Player
Internet Browsing Internet Explorer and many options Chromium, Firefox and many options

Here are a few resources that go into greater detail examining the differences between Windows and BSD:

1.3. Virtualization

A virtualized environment allows a user to test drive an operating system without overwriting the current operating system. This is an excellent way to practice installation, determine whether the hardware is supported, or to try multiple versions of different operating systems. Virtualization software creates a virtual machine, which is essentially a computer environment created entirely in software that allows the installation and use of an operating system. The only limitation to virtualization is the hardware, as each virtual machine uses real resources, the CPU and RAM. Depending on the amount of CPU and RAM available on the host computer, the operating system installed as a guest in the virtual environment may run slowly. If the host computer slows down, closing other non-essential applications to free up CPU/RAM may help.

1.3.1. bhyve

bhyve (pronounced bee hive) is a type-2 hypervisor that runs natively on TrueOS® and originally developed on FreeBSD. bhyve runs FreeBSD 9+, OpenBSD, NetBSD, Linux, and Windows guests. Current development efforts aim at widening support for other operating systems for the x86-64 architecture. The FreeBSD Handbook Virtualization section has in-depth instructions about bhyve features and use. bhyve, while very powerful, is still under active development and may not have a complete user experience yet.

For a more user-friendly virtualization experience, many users prefer VirtualBox.

1.3.2. VirtualBox

VirtualBox is a popular virtualization software available in TrueOS®. Installing VirtualBox through the SysAdm AppCafe or typing pkg install virtualbox-ose on the command line will install all required dependencies. If installing TrueOS® inside a virtual machine, referred to as a “guest”, installing the virtualbox-ose-additions package (also known as VirtualBox Guest Additions) will greatly improve the performance of TrueOS® or any other guest operating system. The guest additions add mouse pointer integration, shared folders between the host and guest (depending on the guest OS), improved video support, and a shared clipboard.


VirtualBox does not currently support the shared folders feature with a TrueOS® guest. To share files between the host and a TrueOS® guest, use an NFS share.

Please see the VirtualBox website for additional information. The VirtualBox Guest Additions page has information about what is supported and how to use these additions.


The first time running VirtualBox on a TrueOS® system, a background script automatically gives the user account that started VirtualBox the permissions required to run the application. This might break existing shortcuts to VirtualBox. To fix the shortcut, log out and in again.

1.3.3. Creating a Virtual Machine for a TrueOS® install

How to prepare VirtualBox for an installation of TrueOS® using an .iso file.

Once a TrueOS® ISO is downloaded and VirtualBox installed on the host system, create a new virtual machine to install TrueOS® as a guest OS. The virtual machine must meet several minimum requirements in order to be useable. This section will demonstrate how to configure the virtual machine for a TrueOS® guest.

  • A minimum of 1024MB of memory.
  • A virtual disk of 10-15 GB for a server installation or 20-30 GB for a desktop installation should be a useable starting point. The actual size of a virtual disk depends on the virtual machine’s intended use, and what applications need to be installed for example but these sizes should suit the average user’s needs.
  • A bridged adapter.

To create the virtual machine, start VirtualBox to see the screen shown in Figure 1.3.1.


Fig. 1.3.1 VirtualBox Menu

Click New to start the new virtual machine wizard and display the screen in Figure 1.3.2.


Fig. 1.3.2 Create Virtual Machine - Name, Type, and Version

Enter a name for the virtual machine; anything can be entered but something descriptive is recommended. Click the Operating System drop-down menu and select BSD. In the Version drop-down menu, select FreeBSD (64 bit). Click Next to see the screen in Figure 1.3.3.


Fig. 1.3.3 Virtual Machine Reserved Memory

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


Fig. 1.3.4 Virtual Hard Drive - New or Existing

This section is used to create the virtual hard drive, or the amount of disk space available to the guest OS installed in the virtual machine. If this is the first virtual machine, the default offered by the Create a virtual hard drive now utility should be fine, then click Create to go to the screen shown in Figure 1.3.5. If there are existing virtual machines already on the host system, reusing an existing virtual disk by selecting Use an existing virtual hard drive file from the drop-down menu. Create as many virtual machines as desired. If the host system is getting low on disk space, consider reusing existing virtual hard drives to prevent wasting space on the physical hard drive by old unsed virtual machines.


Fig. 1.3.5 Hard Drive Type

Select VDI and click Next to see the screen in Figure 1.3.6.


Fig. 1.3.6 Storage Type

Next, choose whether to have Dynamically allocated or Fixed size storage. Dynamically allocated uses disk space as needed until it reaches the maximum size set in the next screen. The Fixed size option creates a virtual disk the same size as that specified amount of disk space, whether it is used or not. Choose the first option if disk space is a concern; otherwise choose the second option as it allows VirtualBox to run slightly faster. Once Next is selected, the screen in Figure 1.3.7 displays.


Fig. 1.3.7 Virtual Disk - File Name and Size

This screen is used to set the size (or upper limit) of the virtual machine. If planning to install TrueOS® as the guest OS on the virtual machine, increase the size to at least 20 GB or an error will display during the TrueOS® installation. If planning to install KDE, GNOME, multiple desktop managers, or applications within the virtual machine, choose at least 50 GB. Whatever size is set, be sure the computer has enough free disk space to accommodate the size chosen. Use the folder icon to browse to a directory on disk with sufficient space to hold the virtual machine.

Once the selections are made, click Create to finish using the wizard. The virtual machine will now show up in the left box, as seen in the example in Figure 1.3.8.


Fig. 1.3.8 New Virtual Machine “test”

In order to use the network card, configure bridged network on the virtual machine. To do this, go to Settings ‣ Network. In the Attached to drop-down menu select Bridged Adapter, then select the name of the physical network interface from the Name drop-down menu. In the example shown in Figure 1.3.9, the Intel Pro/1000 Ethernet card is attached to the network and has a device name of re0.


Fig. 1.3.9 VirtualBox Bridged Adapter Configuration

Before starting the virtual machine, configure it to use the ISO installation media downloaded previously. Click the Storage hyperlink in the right frame to access the Storage screen seen in Figure 1.3.10.


Fig. 1.3.10 Virtual Machine Storage Settings

Click the word Empty, which represents the DVD reader. To access the TrueOS® installer from the DVD reader, double-check the Slot is pointing to the correct location (e.g. IDE Secondary Master) and use the drop-down menu to change the location if incorrect.

If using an ISO stored on the hard disk is preferred, click the DVD icon then Choose a virtual CD/DVD disk file to open a browser menu to navigate to the location of the ISO. Highlight the desired ISO and click Open. The name of the ISO will now appear in the Storage Tree section.

TrueOS® is now ready to be installed into the virtual machine as a guest OS. Highlight the virtual machine and click on the green Start icon. A new window opens, indicating the virtual machine is starting. If a DVD is inserted, it should audibly spin and the machine will start to boot into the installation program. If it does not or if using an ISO stored on the hard disk, press F12 to select the boot device when the message to do so appears, then press c to boot from CD-ROM. Proceed through the installation as described in the Install section.


If the installer GUI doesn’t appear to load after configuring the virtual machine, EFI may need to be enabled in Virtualbox by navigating Settings ‣ System ‣ Motherboard and checking Enable EFI (special OSes only).

1.4. Supported Hardware

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

Before beginning, there are a few things to check to ensure the system is ready to install TrueOS®.

  • Dual-booting or installing over the entire drive? If dual-booting, please ensure a primary partition is available. Refer to the chapter on Dual Booting.
  • Ensure important data is backed up! Any irreplaceable data, such as emails, bookmarks, or important files and documents should always be backed up to an external media, such as a removable drive or another system, before installing or upgrading any operating system. Accidents happen, and losing important data can be avoided.

To determine if the chosen hardware is detected by TrueOS®, start a new installation and click the Hardware Compatibility icon in the lower left corner of the Language screen.

If any problems arise with the installation, refer to the Troubleshooting section of this handbook.

1.5. Hardware Requirements and Supported Hardware

This section discusses the TrueOS® hardware requirements and some supported hardware.

1.5.1. Minimum Requirements

TrueOS® has moderate hardware requirements and typically uses less resources than its commercial counterparts. Before installing TrueOS®, make sure the hardware or virtual machine meets at least the minimum requirements. To get the most out of the TrueOS® experience, use a system exceeding the minimum or recommended system requirements.

At a bare minimum, these requirements must be met in order to install TrueOS®:

Minimum Requirements

  • 64-bit processor
  • 1 GB RAM
  • 10 - 15 GB of free hard drive space on a primary partition for a command-line server installation.
  • Network card

Here are the recommended requirements. More RAM and available disk space improves the computing experience:

Recommended Requirements

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

TrueOS® does not require 50 GB for its installation. The minimum recommendation is to provide sufficient room for the installation of applications and to store local ZFS snapshots and boot environments. These can be used to retrieve earlier versions of files, rollback the operating system to an earlier point in time, or clone the operating system.

There is no such thing as too much RAM. ZFS thrives on systems with lots of RAM. To play modern video games, use a fast CPU. To create a collection of music and movies on the computer, sufficient disk space is required.

1.5.2. Processor

TrueOS® installs on any system containing a 64-bit (also called amd64) processor. Despite the name, a 64-bit processor does not need to be manufactured by AMD in order to be supported. Even 64-bit Intel CPUs are sometimes referred to as amd64. The FreeBSD Hardware Notes - amd64 lists the amd64 processors known to be compatible.

1.5.3. Graphics

Like many open source operating systems, TrueOS® uses X.org drivers for graphics support. TrueOS® automatically detects the optimal video settings for supported video drivers. Verify the graphics hardware is supported by clicking the Hardware Compatibility icon within the installer.

Here are the major graphic vendors supported in TrueOS®:

NVIDIA: 3D acceleration on NVIDIA is provided by native FreeBSD drivers. If an NVIDIA video card is detected, an nVidia settings icon will be added to Browse Applications for managing NVIDIA settings.

Intel: 3D acceleration on most Intel graphics is supported. This includes Skylake, Haswell, Broadwell, and ValleyView chipsets.

ATI/Radeon: 3D acceleration on most ATI and Radeon cards is supported.

Optimus: Currently, there is no switching support between the two graphics adapters provided by Optimus. Optimus implementations vary, so TrueOS® may or may not be able to successfully load a graphics driver to support this hardware. If a blank screen shows after installation, check the BIOS to see if there is an option to disable one of the graphics adapters or to set discrete mode. If the BIOS does not provide a discrete mode, TrueOS® defaults to the 3D Intel driver and disables NVIDIA. This will change in the future when the NVIDIA driver supports Optimus.

1.5.4. Wireless

TrueOS® has built-in support for most wireless networking cards. TrueOS® automatically detects available wireless networks for supported wireless devices. Verify the device is supported by clicking the Hardware Compatibility icon within the installer. If it is an external wireless device, insert it before running the installer.

Certain Broadcom devices, typically found in less expensive laptops, are buggy and lockup unexpectedly while in DMA mode. If the device freezes, try switching to PIO mode in the BIOS. Alternately, add hw.bwn.usedma=0 to /boot/loader.conf and reboot to see if that resolves the issue.


Some wifi adapters are not configured during installation, but after first boot. Just because an adapter does not show up during installation does not mean it is unsupported.

1.5.5. Laptops

Many TrueOS® users successfully run TrueOS® on their laptops. However, some issues may occur, depending upon the model of laptop. Some typical laptop issues:

  • Sleep/suspend: Unfortunately, Advanced Configuration and Power Interface (ACPI) is not an exact science, meaning experimentation with various sysctl variables may be required to achieve successful sleep and suspend states on some laptops. For ThinkPad laptops, the ThinkWiki is an excellent resource. For other types of laptops, try reading the SYSCTL VARIABLES section of man 4 acpi and check to see if there is an ACPI man page specific to the laptop’s vendor by typing apropos acpi. The Tuning with sysctl(8) section of the FreeBSD Handbook demonstrates how to determine the current sysctl values, modify a value, and make a modified value persist after a reboot.

  • Synaptics: Disabling the system’s touchpad may be dependant upon the hardware. This forum post describes how to enable Synaptics and some of the sysctl options this feature provides.

    The SysAdm Mouse Settings also has options for disabling a system’s touchpad, if one is detected.

To test the laptop’s hardware, use the Hardware Compatibility icon in the Language screen before continuing with the installation.

To install TrueOS® onto an Asus Eee PC, review the FreeBSD Eee page first.

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

With regards to specific hardware, the ThinkPad T420 may panic during install. If it does, enter the BIOS and set the video mode to “discrete”, which should allow the installation to complete. Some Thinkpads have a BIOS bug preventing them from booting from GPT-labeled disks. If unable to boot into a new installation, restart the installer and go into Advanced Mode in the Disk Selection screen. Make sure GPT (Best for new hardware) is unchecked. If it was checked previously, redo the installation with the box unchecked.