2. Pre-Install

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 section on Dual Booting.
  • Is your important data 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.

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.

This section discusses the TrueOS® hardware requirements, how to prepare the system for installation, and how to obtain and prepare the installation media.

2.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 your TrueOS® experience, use a system exceeding the minimum or recommended system requirements.

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


  • 64-bit processor
  • 1 GB RAM
  • 20 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:


  • 64-bit processor
  • 4 GB of RAM
  • 50 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.

More RAM is always recommended, so install as much as you can afford. 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.

2.2. Supported Hardware

Check the FreeBSD Hardware Notes to ensure your system hardware is supported before installing TrueOS®. Another good option is to start the installer and click the Hardware Compatibility icon.

While most hardware “just works” with TrueOS®, it is possible to run across a piece of hardware which does not. Since TrueOS® is essentially FreeBSD, any hardware that works on FreeBSD also works on TrueOS®. If problems occur with a device, begin with a web search for the term “FreeBSD” plus the type and model of the hardware. This search shows any known issues with the device. If there are too many search results, concentrate on the most recent hits, as oftentimes previously problematic hardware has since been fixed or the missing driver will be available in an upcoming release of FreeBSD. If a problem occurs with a device thought to work but does not, or there are no existing problem reports for your hardware, please help improve hardware support for all FreeBSD and TrueOS® users by reporting the bug so the issue can be addressed by the developers.

The rest of this section is a brief overview of the different supported hardware.

2.2.1. 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. The FreeBSD Hardware Notes - amd64 lists the amd64 processors known to work.

2.2.2. 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 is the major graphic vendor support:

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.

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

Optimus: At this time 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 on hardware. If a blank screen shows after installation, check the BIOS to see if it has 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.

2.2.3. 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 can have lockups when 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 anything changes.

2.2.4. Laptops

Many TrueOS® users successfully run TrueOS® on their laptops. However, some issues may occur, depending upon the model of laptop. These typically deal with:

  • 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 your particular laptop model. If the laptop is a ThinkPad, 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, go into 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.

2.3. Creating Free Space

To dual-boot TrueOS® with an existing operating system, first make sure there is either a free partition or an area of free space to use. For example, if the system is currently running a Windows operating system, it usually occupies the entire hard drive. The partition with the current operating system needs to shrink to make room to install TrueOS®. Shrinking is an operation which retains the current operating system while reducing the size of its partition. This section demonstrates how to create free space within Windows 10.


Before shrinking a partition, be sure to back up any valuable data to an external media such as a removable USB drive!

To shrink the drive, right-click the Start menu and click Disk Management. In the example shown in Figure 2.3.1, the Windows system has three partitions: a 450 MB recovery partition, a 237.93 GB data partition, and a 100 MB system partition.


Fig. 2.3.1 Disk Layout in Disk Management

Since the three Windows partitions fill the entire disk, the data partition must be shrunk to create space to install TrueOS®. Right-click the data partition (in this example, the (C:) partition), and select Shrink Volume, as shown in Figure 2.3.2.


Fig. 2.3.2 Shrink Volume Menu Selection

Wait as the volume is queried for available shrink space. The results are shown in Figure 2.3.3.


Fig. 2.3.3 Available Shrink Space

Here, 119307 MB of space is available. This is the maximum amount Windows can shrink this particular partition. Accept that number, or choose a smaller number for a smaller TrueOS® partition. Click Shrink to begin the shrinking process. This procedure can take several minutes to complete. When finished, the newly created free space is displayed as seen in Figure 2.3.4.


Fig. 2.3.4 Disk with Free Space


It is important to not choose to install TrueOS® into any of the three Windows partitions at the Disk Selection screen of the installer. It is a good idea to write down the sizes of all of the partitions so the free space is recognizable when the TrueOS® installer displays the current partitions.

2.4. Download and Prepare to Install

TrueOS® uses a rolling release model rather than versioned releases. There are two primary options of TrueOS® install: STABLE and UNSTABLE:

  1. STABLE is meant to be less frequently updated and synchronized with FreeBSD. This means users see less experimental work and generally have a smoother experience. However, users on STABLE also typically wait longer for bugfixes and patches to be available. While some TrueOS® development may be backported to STABLE early, FreeBSD patches and port synchronization is done on a six-month schedule.
  2. UNSTABLE is the full leading edge of TrueOS and FreeBSD development. Patches are very frequent, but can incorporate experimental work from both the TrueOS® and FreeBSD projects. UNSTABLE is recommended for users who need the absolute latest work from FreeBSD or TrueOS® and are willing to tolerate breakage or less system stability. It is also recommended for users who want to test and contribute patches to FreeBSD or TrueOS®.

Periodically, the SysAdm Update Manager provides patches to update the operating system. By default, users who install STABLE receive updates from the STABLE track, and UNSTABLE users are on the UNSTABLE track. It is possible to switch update tracks post-installation. See the Updating TrueOS section for instructions on switching update repositories.

Installation files can be downloaded from the TrueOS® website or the PC-BSD® CDN.

Several types of files are available for download. Any file with the naming convention TrueOS-<year>-<month>-<day>-x64-[DVD/USB].[iso/img] are STABLE or UNSTABLE installation files, depending on the download directory:

  • STABLE: Files in the master/amd64 directory are the STABLE version of TrueOS®.
  • UNSTABLE: Files in the unstable/amd64 directory are the UNSTABLE version of TrueOS®.
  • “latest” files: These entries are symlinks to their related install files and are generally ignored.

Install files following the above naming conventions can also end with a variety of extensions:

  • .iso: If the file has an .iso extension, it should be burned to a DVD media.
  • .img: If it has a img extension, it should be burned to a USB stick.
  • .md5, .sha256, and .sig: Depending upon the current operating system and its tools, use the value in any of these files to determine the integrity of the download, as described in Data Integrity Check.
  • .torrent: If a torrent is available, a file with the same name and a .torrent extension will be visible.

To install a graphical desktop, download the file ending in DVD.iso or USB.img. Then, depending on the file type, either burn it to a DVD media or write it to a removable USB device.

If installing a command-line only server is preferred, download and begin installing TrueOS® in the same manner as the desktop, but choose the Server option in the installer.

Refer to Burning the Installation Media for instructions on how to burn the downloaded file to bootable media.

2.4.1. Data Integrity Check

After downloading the desired file, it is a good idea to check the file is exactly the same as the one on the TrueOS® download server. While downloading, a portion of the file may get damaged or lost, making the installation file unusable. Each TrueOS® installation file has an associated MD5 and SHA256 checksum. If a checksum of the downloaded file matches, the download was successful. If a checksum does not match, try downloading the file again. In order to verify a checksum, use a checksum verification utility.


Only one of the checksums needs to be verified. The TrueOS website lists .MD5, SHA256, and .SIG files. The TrueOS website has all file types while the PC-BSD® CDN lists both the .md5 and the .sha256 checksum files.

If using a Windows system, download and install a utility such as Raymond’s MD5 & SHA Checksum Utility. This utility can be used to simultaneously check the MD5, SHA-1, SHA-256, and SHA-512 checksums of any file. Once installed, launch the program and use Browse, shown in Figure 2.4.1, to browse to the location of the downloaded file.


Fig. 2.4.1 Checksum Verification

Once the file is selected, click Open to calculate the checksums. It may take a minute or so, depending upon the size of the downloaded file.

On Linux and BSD systems, use the built-in md5 or md5sum command line tool to display the MD5 checksum. In this example, the user types md5 to view the sum of a .img file located in the Downloads directory. Then, using the built-in cat command line tool, the user compares the sum to the contents of the related .md5 file:

~% md5 Downloads/TrueOS-2017-04-21-x64-USB.img
MD5 (Downloads/TrueOS-2017-04-21-x64-USB.img) =

~& cat Downloads/TrueOS-2017-04-21-x64-USB.img.md5

To use the OpenPGP .sig file, use your preferred utility to verify the signature. The OpenPGP website has numerous recommendations for verification utilities.

2.4.2. Burning the Installation Media

Once the installation file is downloaded and its checksum verified, burn it to a media. The media you use depends upon the file downloaded:

  • Files ending with .iso can be burned to a DVD or used in a Virtual Machine (VM).
  • Files ending in img must be burned to a USB stick.

To burn to a DVD, use either a burning utility packaged with the operating system on the system with the burner or a separate burning application. Table 2.4.1 lists some freely available burning utilities.

Table 2.4.1 Free Burning Utilities
Operating System Utility
Windows InfraRecorder utility
Windows Disk Burner
Linux or *BSD K3B
Linux or *BSD Brasero
FreeBSD/PC-BSD/TrueOS growisofs
Mac OS X Disk Utility

2.4.3. Writing to a USB Device

There are a few requirements to write the img file to a USB device:

  • A utility capable of writing the image to a USB media; the available utilities depend on the installed operating system.
  • A USB thumb drive or hard drive large enough to hold the image.


If there is a card reader on the system or the USB drive is connected using a USB dongle, device enumeration may be affected. For example, with the USB card reader dongle as the destination, the device name could be /dev/da1 instead of /dev/da0.

To write the .img file to a flash card or removable USB drive on a BSD or Linux system, use the dd command line utility. On a FreeBSD system, the superuser can use this command to write the file to the first plugged in USB device:

[user@exmpl] dd if=TrueOS-Desktop-2016-08-11-x64.img of=/dev/da0 bs=1m
1415+1 records in
1415+1 records out
1483990016 bytes transferred in 238.552250 secs (6220818 bytes/sec)

When using the dd command:

  • if= designates the input file to be written.
  • of= refers to the output file (the device name of the flash card or removable USB drive). Increment the number in the name if it is not the first USB device.
  • bs= refers to the block size.


On Linux, type mount with the USB stick inserted to see two or more device nodes corresponding to the USB stick. For example, /dev/sdc and /dev/sdc1, where /dev/sdc1 corresponds to the primary partition of the USB stick. Before using dd, ensure the USB stick is unmounted. Then, remember to use /dev/sdc (the device node without the number) as the option for the output file of=. Once dd completes, the USB stick may not be mountable on Linux as it has very limited support for UFS (BSD filesystem created on the USB stick).

To burn the image file on a Windows system, use win32-image-writer. When downloading win32-image-writer, download the latest version ending in -binary.zip and use a utility such as Windows Explorer or 7zip to unzip the executable.

Launch win32-image-writer.exe to start the Win32 Disk Imager utility, shown in Figure 2.4.2. Use browse to browse to the location of the .img file. Insert a USB thumb drive and select its drive letter (in this example, drive D). Click Write and the image will be written to the USB thumb drive.


Fig. 2.4.2 Write an Image using Win32 Disk Imager

To burn the .img file on Mac OS X, insert a USB stick and open Terminal. Run diskutil list to discover the device name of the USB disk, unmount the USB disk, then use dd to write the image to the raw disk (rdisk). In this example, an 8 GB USB stick has a device name of /dev/disk1 and a raw device name of /dev/rdisk1:

diskutil list
0: GUID_partition_scheme *500.1 GB disk0
1: EFI 209.7 MB disk0s1
2: Apple_HFS Macintosh HD 499.2 GB disk0s2
3: Apple_Boot Recovery HD 650.0 MB disk0s3
0: FDisk_partition_scheme *8.0 GB disk1
1: DOS_FAT_32 UNTITLED 8.0 GB disk1s1

diskutil unmountDisk /dev/disk1
Unmount of all volumes on disk1 was successful

sudo dd if=/Users/dru/Downloads/TrueOS-Desktop-2016-08-11-x64.img of=/dev/rdisk1 bs=4m
1415+1 records in
1415+1 records out
1483990016 bytes transferred in 238.552250 secs (6220818 bytes/sec)

2.5. 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 effectively creates windows (known as virtual machines) to install and use an operating system. The only limitation to virtualization is the hardware, as each virtual machine uses CPU and RAM. Depending upon the amount of CPU and RAM in the computer, the installed operating system using virtualization software may run slowly. If the computer slows down, try closing other applications running on the computer to free up some RAM.

To run virtualization software on TrueOS®, search for virtualbox within the SysAdm AppCafe and install the VirtualBox open source virtualization program and the VirtualBox Guest Additions. The guest additions add mouse pointer integration, shared folders between the host and guest, better video support, and a shared clipboard.


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

If the computer is running another operating system, download the binary for the specific operating system from the VirtualBox Downloads page. VirtualBox runs on Windows, Linux, Macintosh, and OpenSolaris. It supports a large number of virtual machine installable operating systems.

This section describes how to prepare VirtualBox for an installation of TrueOS® using an .iso file.

2.5.1. Creating a Virtual Machine for an ISO File

Once the TrueOS® ISO is downloaded and VirtualBox installed on the current system, create a virtual machine and use the ISO to install TrueOS® into the virtual machine. The virtual machine must meet several minimum requirements and this section will demonstrate how to configure these:

  • 1024 MB base memory size.
  • A virtual disk at least 20 GB in size for a server installation or at least 50 GB in size for a desktop installation.
  • A bridged adapter.

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


Fig. 2.5.1 VirtualBox Menu

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


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

Enter a name for the virtual machine; it can be anything which makes sense to you. 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 2.5.3.


Fig. 2.5.3 Virtual Machine Reserved Memory

The base memory size must be changed to at least 1024 MB. If the 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 slow down the computer too much. When finished, click Next to see the screen in Figure 2.5.4.


Fig. 2.5.4 Virtual Hard Drive - New or Existing

This screen is used to create the virtual hard drive, or the amount of disk space available to the virtual machine. If this is your first virtual machine, keep the default of Create a virtual hard drive now and click Create to go to the screen shown in Figure 2.5.5. If you have created a virtual machine in the past and wish to reuse its disk space, select Use an existing virtual hard drive file from the drop-down menu. Create as many virtual machines as desired. However, if the computer is getting low on disk space, consider reusing existing virtual hard drives to prevent the physical hard drive from being used up by old virtual machines.


Fig. 2.5.5 Hard Drive Type

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


Fig. 2.5.6 Storage Type

Now choose whether to have Dynamically allocated or Fixed size storage. The first option uses disk space as needed until it reaches the maximum size set in the next screen. The second option creates a 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 2.5.7 displays.


Fig. 2.5.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® into 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 support it. Use the folder icon to browse to a directory on disk with sufficient space to hold the virtual machine.

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


Fig. 2.5.8 New Virtual Machine “test”

In order to use the network card, configure bridging 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 interface from the Name drop-down menu. In the example shown in Figure 2.5.9, the Intel Pro/1000 Ethernet card is attached to the network and has a device name of re0.


Fig. 2.5.9 VirtualBox Bridged Adapter Configuration

Before starting the virtual machine, configure it to use the installation media. Click the Storage hyperlink in the right frame to access the storage screen seen in Figure 2.5.10.


Fig. 2.5.10 Virtual Machine Storage Settings

Double-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 it if the location is 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. Highlight the virtual machine and click on the green Start icon. A 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 your virtual machine, you may need to enable EFI in Virtualbox by navigating Settings System Motherboard and checking Enable EFI (special OSes only).