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 Freenode, join the #trueos channel and 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 login menu, allowing the user to select their environment.
  • The TrueOS® installer supports configuring ZFS and encryption during installation.
  • TrueOS® provides both a graphical and command line software management system.
  • TrueOS® provides many graphical utilities for 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, and the TrueOS® Update Manager automatically adds a new boot environment to the boot menu before updating the operating system or software. With this functionality, if an update fails the system can reboot into the previous version of the operating system, before the update installed.

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

1.1. Typographic Conventions

The TrueOS® User Guide uses several typographic conventions. Table 1.1.1 provides a simple reference for these conventions:

Table 1.1.1 Text Formatting Examples
Item Visual Example
Graphical elements: buttons, icons, fields, columns and boxes Click the Import CA button.
Menu selections Click System Information.
CLI Command name Use scp.
A command line example [tmoore@example] ls /etc
Files, volume and dataset names, and directories Locate the /etc/rc.conf file.
Keyboard keys Press the Enter key.
Important points This is important.
Values entered into fields, or device names Enter in the address field.

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

    Currently, users can choose to follow one of two “tracks” for updates: UNSTABLE and STABLE. UNSTABLE updates are the “bleeding edge” of TrueOS development, for those users who want to test bugfixes and new features. STABLE updates are less frequent, but more reliable. These updates benefit from the testing and patches submitted by our UNSTABLE testers.

  • Virus-free: TrueOS® is unaffected by viruses, spyware, or other malware (see Security).

  • No defragmentation: 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. Also, the rolling release model of TrueOS® provides an environment to quickly add support for new hardware.

  • Secure environment: TrueOS® provides a pre-configured firewall and an inbuilt host-based Intrusion Detection System.

  • Easy system administration: TrueOS® provides many graphical tools for performing system administration.

  • Localization: TrueOS® supports a variety of native languages and locales.

  • Vibrant community: TrueOS® has a friendly and helpful community.

1.4. TrueOS® Comparisons

As TrueOS® grows and evolves, many users appreciate comparisons with other operating systems. These comparisons are intended to help new users deciding to install and try TrueOS®, with accuracy being the chief concern.

1.4.1. FreeBSD and PC-BSD

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


PC-BSD® and FreeBSD are placed together as both are very similar “under the hood”. 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 to start services in parallel. This results in dramatically improved system boot times for TrueOS®. OpenRC is also used to improve general service management, in addition to adding the functionality to automatically run when new elements are introduced to the system, such as plugging in an ethernet cable. Use of OpenRC introduces a new level of differentiation from FreeBSD as TrueOS® now uses some different system services. These differences are listed in Table 1.4.1

    Table 1.4.1 Different system services between 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 Different system services between TrueOS® and FreeBSD table is updated as development continues on the TrueOS® implementation of OpenRC. For a complete list of all available services through OpenRC, see Services and runlevels.

  • A TrueOS® installation installs the Lumina® Desktop. Additional window managers can be installed using AppCafe®.

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

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

    • AppCafe
    • Update Manager
    • Boot Environment Manager
    • Life Preserver
    • Firewall Manager
    • User Manager
    • Network Manager
  • 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 native resolution and is a good solution for newer Intel drivers that have not been ported yet to FreeBSD. Before selecting this driver, check the BIOS and ensure the CSM module is disabled. This driver does not support a dual-head configuration, such as an external port for presentations, or suspend and resume.

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

  • These new utilites are available in the SysAdm Client: Managing Remote Connections and Task Manager.

  • The graphical and command line versions of PBI Manager and Warden are removed.

  • pc-thinclient is removed as it is deprecated.

1.4.2. Linux and TrueOS®

TrueOS® is based on FreeBSD, meaning it is not a Linux distribution. If you have used Linux before, you may find some features you are used to have different names on a BSD system and some commands are different. This section covers some of these differences.

BSD and Linux use different filesystems during installation. Many Linux distros use EXT2, EXT3, EXT4, or ReiserFS, while TrueOS® uses OpenZFS. This means if you wish to dual-boot with Linux or access data on an external drive formatted with another filesystem, you will want to research if the data is accessible to both operating systems.

Table 1.4.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. See the section on Files and File Sharing for a comparison of some graphical file manager utilities.

Table 1.4.2 Filesystem Support on TrueOS®
Filesystem Native to Non-native support type Usage notes
Btrfs Linux none  
exFAT Windows none requires a license from Microsoft
EXT2 Linux r/w support loaded by default  
EXT3 Linux r/w support loaded by default since EXT3 journaling is not supported, you will not be able to mount a filesystem requiring a journal replay unless you fsck it using an external utility such as e2fsprogs
EXT4 Linux r/o support loaded by default EXT3 journaling, extended attributes, and inodes greater than 128 bytes are not supported; EXT3 filesystems converted to EXT4 may have better performance
FAT16 Windows r/w support loaded by default  
FAT32 Windows r/w support loaded by default  
HFS+ Mac OS X none older Mac versions might work with hfsexplorer
JFS Linux none  
NTFS5 Windows full r/w support loaded by default  
NTFS6 Windows r/w support loaded by default  
ReiserFS Linux r/o support is loaded by default  
UFS2 FreeBSD check if a Linux distro provides ufsutils; r/w support on Mac; UFS Explorer can be used on Windows changed to r/o support in Mac Lion
ZFS TrueOS®, FreeBSD    

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

  • In Linux, Ethernet interfaces begin with eth. With BSD, interface names indicate the name of the driver. For example, an Ethernet interface may be listed as re0, indicating it uses the Realtek re driver. The advantage of this convention is you can read the man 4 page for the driver (e.g. type man 4 re) to see which models and features are provided by the driver.
  • BSD disk names differ from Linux. IDE drives begin with ad and SCSI and USB drives begin with da.

Some of the features used by BSD have similar counterparts to Linux, but the name of the feature is different. Table 1.4.3 provides some common examples:

Table 1.4.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.4.4 lists some common commands and what they are used for.

Table 1.4.4 Common BSD and Linux Commands
Command Used
dmesg discover what hardware was detected by the kernel
sysctl dev display configured devices
pciconf -l -cv show PCI devices
dmesg | grep usb show USB devices
kldstat list all modules loaded in the kernel
kldload <module> load a kernel module for the current session
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
fuser list IDs of all processes with one or more files open

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

1.4.3. TrueOS and Windows

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


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

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