TrueOS

Handbook

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:

● FreeBSD Security Information

● Security Section in the FreeBSD Handbook
● Hardening FreeBSD

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:

● ZFS Evil Tuning Guide

● FreeBSD ZFS Tuning Guide
● ZFS Best Practices Guide
● ZFS Administration Guide
● Becoming a ZFS Ninja (video)
 ● Blog post explaining how ZFS simplifies the storage stack

Table 1.1.1​ is a brief glossary of terms used by ZFS:

Term Description

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

A form of RAID where all data is mirrored onto two or more disks,
Mirror
creating a redundant copy should a disk fail.

ZFS software solution equivalent to RAID5, as it allows one disk to fail

RAIDZ
without losing data. Requires at least ​3​ disks.

Double-parity ZFS software solution similar to RAID6, as it allows two

RAIDZ2
disks to fail without losing data. Requires a minimum of ​4​ disks.

Triple-parity ZFS software solution. RAIDZ3 offers three parity drives

RAIDZ3 and can operate in degraded mode if up to three drives fail with no
restrictions on which drives can fail.

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
Dataset
a filesystem since properties such as quotas and compression can be
set.
 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
Snapsho this reason, many administrators take snapshots often (e.g. every 15
t 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.

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

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,
ZIL
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.
 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
L2ARC
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.

Note

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​®​:

Note
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

● TrueOS​® ● Started ● FreeBSD

Service From Service

● openntpd ● Ports ● ntpd

● network ● Base ● netif

● Ports;
● wpa_supplica
Start
● wpa_supplicant nt (from
with
Base)
network
 ● dhcpcd ● Ports ● dhclient

● Note
● 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.

Note

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

Note

A comparison of some popular graphical file management utilities available in

TrueOS​®​ can be found in the ​Files and File Sharing​ section.

Filesyste Native Non-nati Usage notes

m OS ve OS
support
 A modern copy on write (CoW) filesystem
for the Linux OS. Btrfs is similar in nature
Btrfs Linux none to ZFS, and shares many of the same
ideas with how a file system should work.
Btrfs

The successor to EXT. EXT2 was

r/w
designed following the principles put forth
support
in BSD’s Fast File System (FFS). The first
EXT2 Linux loaded
commercial grade filesystem in Linux. The
by
maximum supported volume size is 2TB -
default
32TB and the file size is 6GB - 2TB.

EXT3 is EXT2 with the added benefit of

journaling, online filesystem growth, and
HTree indexing for larger directories.
r/w
Journaling is ​not​ supported in BSD.
support
Filesystems requiring a journal replay are
EXT3 Linux loaded
unable to be mounted in BSD unless a
by
fsck​ is run using an external utility such as
default
the program package ​e2fsprogs​ The max
volume size and file size is the same as
EXT2.

EXT4 is the succesor to EXT3 including

enhancements to journaling, extended
attributes, and journal checksumming
r/o
(among many others) ​on linux​. Using
support
inodes greater than 128 bytes are ​not
EXT4 Linux loaded
supported. Converting EXT3 default
by
filesystems to EXT4 may have experience
default
better performance. EXT4 increases the
maximum volume size to 1EB and the
maximum file size to 16GB to 16TB.

Journaled File System is a 64-bit

journaling file created by IBM. The
JFS Linux none
maximum volume size is 32 PB and the
maximum file size is 4PB.
 r/o
A general-purpose journaling file system
support
that has fallen out of favor in recent years.
ReiserFS Linux is loaded
The maximum volume size is 16TB, and
by
maximum file size is 8TB.
default

r/w
Max partition sizes up to 4GB. Cluster
support
sizes vary from 2kb to 64kb, depending on
FAT16 Windows loaded
partition size. Rarely used due to partition
by
size limitations.
default

r/w Replaced FAT16. Maximum partition size

support of 2TB and a maximum file size of 4GB.
FAT32 Windows loaded 4KB clusters are used on partition sizes up
by to 8GB. For partitions larger than 8GB, the
default cluster size grows up to 32KB.

full r/w
The maximum volume size is 16EB -1kB
support
and the maximum file size is 16TB -64kB.
NTFS Windows loaded
Unlike FAT32, the cluster size stays at
by
4KB regardless of the volume size used.
default

In addition to the NTFS features, NTFS5

also supports encryption, disk quotas, and
r/w
sparse files. Other features may be
support
available, but are beyond the scope of this
NTFS5 Windows loaded
handbook. Support for advanced features
by
may not be supported in TrueOS​®​ and
default
should not be expected or relied on to
work.

r/w A file system optimized for flash memory

support such as USB flash drives and SD Cards.
using the Use of this file system requires a license
exFAT Windows
fusefs-ex from Microsoft. The maximum volume size
fat is 64ZB and the maximum file size is
package 16EB.
 A file system developed by Apple Inc.
HFS+ was developed to replace HFS. The
Mac OS max volume and file size is “slightly less”
HFS+ none
X than 8EB. Older Mac versions may work
using the GUI GUI application dedicated to
HFS called ​hfsexplorer

Unix File System, also called Berkley

Fast File System or FFS, is used by
Linux
support mnay Unix and Unix-like operating
through systems. UFS is a distant descendant
ufsutils. of the original file system used by
r/w Version 7 Unix. UFS2 has a maximum
FreeBS support
UFS2 volume size of 512ZB and a maximum
D on Mac.
UFS maximum file size of 512GB - 32PB,
Explorer depending on the implementation.
can be
used in
Windows
Note: As of Mac Lion, UFS has r/o
support only.

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
TrueOS​® Microsystems, and has since been
,
ZFS succeeded by the Open ZFS project
FreeBS
D 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.

Note

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

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:

TrueOS Linux Description

IPFW iptables Default firewall

/etc/init.d/​ for operating
system
and​/usr/local/etc/init.d/
for applications
In TrueOS​®​, the
directories containing
the startup scripts do
not link to runlevels as
rc0.d/​, r​ c1.d/​,
there are no runlevels.
etc.
System startup scripts
are separated from
third-party application
scripts.

/etc/ttys​ and ​/etc/rc.conf
Terminals configured in
ttys​ and ​rc.conf​ indicate
telinit​, ​init.d/
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.
 Command Used

Show useful information about the

about TrueOS​®​ install. Very useful when
trying to obtain help with issues.

Discover what hardware was

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

List all modules currently loaded in

kldstat
the kernel.

Load a kernel module for the

kldload <module>
current session.

Install software from the command

pkg install <pkgname>
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:

● Comparing BSD and Linux

● FreeBSD Quickstart Guide for Linux® Users
● BSD vs Linux
● Why Choose FreeBSD?
● Interview: BSD for Human Beings
● Video: BSD 4 Linux Users
● Why you should use a BSD style license for your Open Source Project
● A Sysadmin’s Unixersal Translator (ROSETTA STONE)

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:

Note

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.

Element Windows TrueOS

 Office Applications Microsoft Office LibreOffice

Image editing Photoshop GIMP

PDF viewing Acrobat Okular

Media Player Windows Media VLC Media Player

Internet Explorer and Chromium, Firefox and

Internet Browsing
many options many options

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

● FreeBSD is NOT Windows

● General ​Comparison of Operating Systems
● Open Source Alternatives

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.

Note

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.

Note

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.

Note

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

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.
2. 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​.

2.1. 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 synchronized with FreeBSD. This means users see less

experimental work and generally have a smoother experience. However,
users on STABLE 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
TrueOS​®​, FreeBSD, and other Open Source projects and contributions.
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 follow 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​.

Figure 2.1.1​ below shows the TrueOS​®​ website, and how to download a STABLE or
UNSTABLE version of TrueOS​®​. It also shows a drop down menu containing the
different types of install files available for download.

Fig. 2.1.1 UNSTABLE or STABLE Download Screen

 To install a graphical desktop, download the TrueOS​®​ Desktop option. Then,
depending on the file chosen, 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

the TrueOS​®​ Server option.

Install files can 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.

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

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

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

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.1.2​, to browse to the location of the
downloaded file.

Fig. 2.1.2 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) =
3eb6adef0ad171f6c5825f0f820557f5

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

3eb6adef0ad171f6c5825f0f820557f5

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

2.1.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.1.1​ lists some
freely available burning utilities.

Operating Utility
System

Windows InfraRecorder utility

Windows Disk Burner

 Linux or
K3B
*BSD

Linux or
Brasero
*BSD

FreeBSD/P
C-BSD/True growisofs
OS

Mac OS X Disk Utility

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

Warning

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

Note

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.1.3​. 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.1.3 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
/dev/disk0
#: TYPE NAME SIZE IDENTIFIER
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
/dev/disk1
#: TYPE NAME SIZE IDENTIFIER
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

Password:
1415+1 records in
1415+1 records out
1483990016 bytes transferred in 238.552250 secs (6220818 bytes/sec)

2.2. TrueOS​®​ Installation

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 2.2.1​. Press ​Enter​ or
simply wait a few moments and this menu automatically prompts the system to
continue booting.
 Fig. 2.2.1 Initial Boot Menu

Note

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.

2.3. Language
The first graphical installer screen, seen in ​Figure 2.3.1​, indicates the installer
successfully loaded and is ready to present its options.
Fig. 2.3.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 2.3.1​:

Icon Function

Access hardware compatibility information to quickly

determine if the system’s video card, Ethernet card,
System with wrench
wireless device, and sound card are compatible with
TrueOS​®​.

Light Bulb Read a screen’s Help text.

 Keyboard Use the onscreen keyboard.

Switch between the US keyboard layout and a user

“L” key and U.S. Flag
selected layout.

Opens the ​Network Manager​ in order to configure

Blue and White Orb
system networking during the installation process.

Access the emergency shell described in ​Using the

Command Prompt Window
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.

Note

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.

Note

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.

2.4. System Selection

The ​System Selection​ screen installs a graphical desktop or a console-based
server operating system, as seen in ​Figure 2.4.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. 2.4.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​.

Note

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.

2.5. 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 2.5.1​ screen.

Fig. 2.5.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.

2.6. Disk Selection

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

Fig. 2.6.1 Disk Selection Screen

Warning

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 2.6.2​.

Fig. 2.6.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.

Warning

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

2.6.1. Basic Mode

Select ​Basic​ and the wizard displays the screen shown in ​Figure 2.6.3​.
 Fig. 2.6.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.

Note
 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​.

Note

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.

2.6.2. Advanced Mode

After selecting advanced mode, the wizard displays the screen shown in ​Figure
2.6.4​.
 Fig. 2.6.4 Advanced Mode Options

This screen has several options:

● Disk:​ Choose the install disk.

● Partition:​ Select the desired partition or area of free space.

Note

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.

Note

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.

2.6.2.1. ZFS Layout

In ​Advanced Mode​, the disk setup wizard allows configuring the ZFS layout. The
initial ZFS configuration screen is seen in ​Figure 2.6.5​.
 Fig. 2.6.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.

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

Danger

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 2.6.6​.
 Fig. 2.6.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.

Note

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 2.6.7​.

Fig. 2.6.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.

Danger

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 2.6.8​.
 Fig. 2.6.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.

Warning

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.

2.7. Installation Progress

Once ​Yes​ is selected to start the installation, a progress screen, seen in ​Figure
2.7.1​, updates the user on the installation progress.
Fig. 2.7.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.

2.8. Installation Finished

The ​Installation Finished​ screen, shown in ​Figure 2.8.1​, appears once the
installation is complete.
Fig. 2.8.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.

2.9. Booting Into TrueOS​®

After installation, TrueOS​®​ reboots and displays a boot menu. The first menu
displayed depends on whether or not rEFInd is installed or the user customized the
boot loader during the installation.

2.9.1. rEFInd Boot Manager

For EFI or UEFI systems, the user can choose to install rEFInd. This is a boot
manager that is useful when ​Dual Booting​. ​Figure 2.9.1​ shows the initial rEFInd
screen.

Fig. 2.9.1 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.

There are a number of options in rEFInd aside from choosing an operating system:
 ● About rEFInd:​ This option displays the version and copyrights of rEFInd.
It also shows the EFI Revision, Platform, Firmware, and Screen Output.
● Shut Down Computer
● Reboot Computer
● Reboot to Computer Setup Utility:​ Not recommended for use with
TrueOS​®​.

Additional boot options for an operating system are available by highlighting the OS
and pressing ​F2​ or ​Insert​.

Once TrueOS​®​ is chosen in rEFInd, the next boot screen displays.

2.9.2. BSD Boot Loader

A system with a default or “BSD” install option for the boot loader loads the boot
menu seen in ​Figure 2.9.2​.

Note

This menu is modified from the one seen when booting into the ​installer​. While the
options are the same, they are rearranged slightly to prevent confusion and
unnecessary clutter.
Fig. 2.9.2 TrueOS​®​ Boot Menu

This menu provides several options. Pause this menu by pressing any key except for
Enter​. To select an option, press either the bolded number or key for that option.
Once any selections are made, press ​Enter​ to boot using the specified options.

● 1. Boot TrueOS [Enter]​: This is the default option for booting

TrueOS​®​. The system automatically uses this option either after pausing
for a moment or if ​Enter​ is pressed while the boot menu is displayed.
● 2. Configure Boot Options​: Press either ​2​ or ​o​ to see the boot
options screen, shown in ​Figure 2.9.3​. To change an option, press either
the bolded number or key for the option to toggle through its available
settings. When finished, press either ​1​ or ​Backspace​ to return to the
TrueOS​®​ boot menu.
● 3. Select Boot Environment​: In TrueOS​®​, boot environments are
automatically created when the system updates. They can also be
manually created using the ​Boot Environment Manager​. This allows the
system to boot to the point of time before an update occurred and can be
 used to recover from a failed update. Press either ​3​ or ​e​ to view the
available boot environments.

Tip

The first time the system boots, no additional environments are available. This menu
populates as boot environments are created.

Fig. 2.9.3 Boot Options Menu

Several boot options are available in the Boot Options Menu:

● 3. Boot Single User​: Advanced users can select this option to fix
critical system failures.
● 4. Verbose​: Select this option to see more detailed messages during the
boot process. This can be useful when troubleshooting a piece of
hardware.
 ● 5. Kernel​: This option indicates how many kernels are available. Press
either ​5​ or ​k​ to toggle between available kernels. This option is available
to the user if they have created a custom kernel, but wish to have a
kernel.old​ boot option available in case the custom primary kernel fails.
● 6. Escape to loader prompt​: Advanced users can select this option
to perform advanced operations, such as loading kernel modules.

2.9.3. Encrypted Disks

If ​Encrypt disk with GELI​ was selected during installation, physical access to
the TrueOS​®​ system when it boots is required. As the system starts to boot, it
displays a message similar to the one shown in ​Figure 2.9.4​.

Fig. 2.9.4 Master Key Decryption

The boot process will wait for the password created in the installation screen shown
in ​Configure Encryption​. If the correct password is typed, the system calculates the
GELI encryption key then continues to boot.

2.10. Display Detection

When booting for the first time, TrueOS​®​ shows a ​Display Settings​ screen,
reproduced in ​Figure 2.10.1​.
Fig. 2.10.1 Display Settings

Use this screen to view the detected video card and choose a graphics driver from
the expanding menu. TrueOS​®​ also suggests a driver.

The ​vesa​ driver always works but provides sub-optimal performance. Click on the
drop-down menu to select the driver most closely matching your video card name.

When finished, click ​Apply​ for the settings to be tested. If anything goes wrong
during testing, the system returns to the​Display Settings​ screen in order for the
 user to select another driver. Once satisfied with the settings, click ​Yes​ when
prompted to accept them.

Note

The ​Advanced​ tab is disabled and scheduled for removal.

2.11. Choose a Language

Figure 2.11.1​ shows the language selection screen.

Fig. 2.11.1 Language Selection

This allows for the selection of the language used to access the installed system. It
also contains three icons from the installer screens to enable:

● Light Bulb​: Reading the screen’s ​Help​ text.

● Keyboard​: Use the onscreen keyboard.
 ● Key with US and Brazilian Flag​: Choose a different keyboard layout
other than the default US style.

Once the selection is made, click ​Next​ to move to the next configuration screen.

2.12. Time Zone Selection

The timezone select screen, shown in ​Figure 2.12.1​, allows selection of the timezone
and configuring the system’s host and domain names.

Fig. 2.12.1 Time Zone Selection

Use the drop-down menu to select the city closest to the system’s location. If the
system is connected to the Internet, the installer automatically attempts to detect the
correct timezone.

If the system is dual booting and the other operating system expects the BIOS to use
UTC, also check ​Set BIOS to UTC time​.

A default system hostname is created. Change the name by typing the desired
hostname in the ​System Hostname​ field. If the computer is a member of a DNS
domain, the ​Domain Name​ is also an option.

When finished, click ​Next​ to proceed to the next screen.

2.13. Set the Root Password

This screen, seen in ​Figure 2.13.1​, ​requires​ setting the root (administrative)
password.
Fig. 2.13.1 Root Password Creation

The password must be a minimum of ​4​ characters and typed twice to confirm the
password. Try to create a complex, but memorable password, as this is used
whenever the system indicates administrative access is required. Click ​Next​ when
finished.

2.14. Create a User

This screen is used to create the primary user account used to login to the system.

Figure 2.14.1​ shows the configuration screen used to create the initial user account.
Fig. 2.14.1 User Creation

The ​User Details​ tab is used to create a login user. This screen requires
completing several fields:

● Name:​ This value displays in the login screen. It can be the user’s full
name and can contain both capital letters and spaces.
● Username:​ This is the name used when logging in. It can ​not​ contain
spaces and ​is​ case sensitive (e.g. ​Kris​ is a different username from ​kris​).
● Password:​ This is the password to use when logging in. It must be typed
twice for confirmation.
● Specify UID:​ By default, the user is assigned the next available User ID
(UID). If a specific UID is required, it can be set here. A UID can not be set
 lower than 1001, and a UID already in use by another account is also
unavailable.

TrueOS​®​ provides the ability to use a removable device, such as a USB stick, as the
user’s encrypted home directory. This is useful in a multi-user or multi-computer
environment, as it provides the user with secure access to their encrypted files.
When a user initializes ​PersonaCrypt​ with their account, their username only
appears in the login menu if the removable media associated with that TrueOS​®
system is inserted. They must input the password associated with the removable
device in order to log in.

When a user is configured to use a PersonaCrypt device, that user cannot log in
using an unencrypted session on the same system. In other words, the
PersonaCrypt username is reserved only for PersonaCrypt use. If necessary to login
to both encrypted and unencrypted sessions on the same system, create two
different user accounts; one for each type of session.

Note

Encryption is also possible without requiring removable devices using ​PEFS​. Refer
to the SysAdm​™​ handbook section on​PEFS Encryption​ for more detailed instructions
to initialize a user with ​PEFS​.

Figure 2.14.2​ shows the ​PersonaCrypt​ tab. This is used to initialize PersonaCrypt
for the user.
 Fig. 2.14.2 User’s PersonaCrypt Initialization

Check ​Initialize PersonaCrypt Device​, insert a removable media device large

enough to hold a user’s home directory, then click ​Select​.

Warning

Ensure there are no desired files on the removable media. Initializing the media for
PersonaCrypt formats the device with ZFS and then encrypts it with GELI, deleting
any existing data.

Input and repeat the ​Device Password​ to associate with the device. A pop-up
window indicates the current contents of the device will be wiped. Click ​Yes​ to
initialize the device.
To share the computer with other users, create additional login and ​PersonaCrypt
accounts using the SysAdm​™​ ​User Manager​. After creating at least one user, click
Next​ to continue.

2.15. Configure Audio Output

Figure 2.15.1​ shows the Audio Output screen, where you can choose the output
device and test it.

Fig. 2.15.1 Configure Audio Output

Click the ​Output Device​ drop-down menu to select the desired sound device.
Click ​Test​ to verify the setting. If the device works, a test sound plays. The
Testing Volume​ slider is also used to set the default system volume level.
 All these settings can be viewed and edited at any time using the instructions in
Sound Mixer Tray​.

2.16. Connect to a Wireless Network

Note

The network card must be supported by FreeBSD. Refer to ​Supported Hardware​ for
links to FreeBSD support and a list of known issues with different hardware.

If the system has an active wireless interface, a screen similar to ​Figure 2.16.1
indicates which wireless networks are automatically detected. Available networks are
ordered by signal strength.
Fig. 2.16.1 Wireless Network Connections

To set the default wireless connection, click the desired network in the ​Available
Wireless Networks​ area. If the network requires a password, a window appears
requesting the password and indicating the security type used by the desired
network. If the desired network is not visible in the ​Available Wireless
Networks​ area, click ​Rescan​. If unable to connect or to configure the connection
later, refer to ​Network Manager​ for more detailed instructions.

2.17. Enable Optional Services

Figure 2.17.1​ shows a few optional system services you can toggle.
 Fig. 2.17.1 Optional Services

Check ​Disable IPV6 (Requires Reboot)​ to reconfigure the system to only

support IPv4 addresses. By default, the system supports both IPv4 and IPv6, and
IPv6 is preferred over IPv4.

Tip

Altering this setting does not take affect until the next system reboot.

Enable Intel HDA polling​ enables the audio driver polling mode. It is used in
TrueOS​®​ to support additional Intel audio devices that would not function without
polling. However, it is recommended to ​not​ enable unless you are having extensive
audio device issues, or your Intel device requires polling mode enabled. See the
FreeBSD Manual Page​ for more details.

Enable Realtek Wireless​ activates the Realtek wireless networking drivers.

If ​Enable SSH​ is checked, the SSH service both starts immediately and is
configured to start on system boot. This option also creates the firewall rules needed
to allow incoming SSH connections to the TrueOS​®​ system.

Danger

Do not​ check this box if SSH connections to the system are undesired.

Enable Verbose Boot​ is the same option as in ​Boot Options Menu​. Select this
option to see more detailed messages during the boot process. This can be useful
when troubleshooting a piece of hardware.
When finished choosing optional services, click ​Next​. The screen in ​Figure 2.17.2
indicates the post-installation setup is complete. Click ​Finish​ to access the login
menu.

Fig. 2.17.2 Setup Complete

2.18. Logging In
Once finished setting up the system, the PCDM (PC-BSD​®​ Display Manager)
graphical login screen displays. An example is seen in ​Figure 2.18.1​.
 Fig. 2.18.1 TrueOS​®​ Login

The hostname of the system is displayed at the top of the login window. In this
example, it is ​trueos-5026​. This login screen has several configuration options:

● User:​ Upon first login, the created ​username​ (from ​Create a User​) is the
only available login user. If additional users are created using the
SysAdm​™​ ​User Manager​, they are added to the drop-down menu for more
login choices. PCDM does not allow logging in as the ​root​ user. Instead,
whenever a utility requires administrative access, TrueOS​®​ asks for the
password of the login account.
● Password:​ Input the password associated with the selected user.
● Desktop:​ If any additional desktops are installed using ​AppCafe​, use the
drop-down menu to select the desktop to log into.

Note
If a PersonaCrypt user is active, insert the PersonaCrypt device in order to log in. As
seen in ​Figure 2.18.2​, this adds an extra field to the login screen so the password
associated with the PersonaCrypt device can be typed.

Fig. 2.18.2 TrueOS​®​ PersonaCrypt Login

The toolbar across the bottom of the screen allows several options to be selected on
a per-login basis:

● Locale:​ If the localization was not set during installation, or needs to be

changed, click this icon to set the locale for this login session.
● Keyboard Layout:​ Click this icon to change the keyboard layout for this
login session. This opens the window seen in ​Figure 2.18.3​.
 Fig. 2.18.3 Keyboard Settings

Click the ​Keyboard model​ drop-down menu to select the type of keyboard.

Note

The default model of ​Generic 104-key PC​ does ​not​ support special keys such
as multimedia or Windows keys. Choose another model to enable support for hot
keys.

This screen also allows selection of the ​Key Layout​ and ​Variant​. After making
any selections, test them by typing some text into the ​you may type into the
space below…​ field.
Tip

It is possible to change keyboard layouts during an active desktop session using the
included ​fcitx​ utility

● Restart/Shut Down:​ To restart or shutdown the system without logging in,

click the ​Power Button​ icon in the lower-right corner of the screen. This
icon also allows you to ​Change DPI​, ​Refresh PCDM​, and ​Change
Video Driver​.

Once any selections are made, input the password associated with the selected user
and press ​Enter​ or click the ​blue arrow​to login.
 3. Dual Boot
This chapter discusses the necessary steps to dual boot.

3.1. 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, a system running
the Windows operating system 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.

Warning

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 3.1.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. 3.1.1 Disk Layout in Disk Management

This image shows all three Windows partitions filling 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 3.1.2​.
Fig. 3.1.2 Shrink Volume Menu Selection

Wait as the volume is queried for available shrink space. The results are shown in
Figure 3.1.3​.
 Fig. 3.1.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 3.1.4​.

Note

The minimum requirement for a TrueOS​®​ install is 20 GB. It is recommended to have

50 GB.
 Fig. 3.1.4 Disk with Free Space

Warning

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.

3.2. Requirements for Dual Booting

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.

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

Note

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.

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.

Danger

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.3.1​.

Fig. 3.3.1 rEFInd Boot Manager

rEFInd displays any installed operating systems and boots 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.
4. Advanced Installation Topics
The topics discussed in this chapter are intended for users that have a sound

understanding with installing and manipulating open source software.

If the intent is to install a graphical desktop using the graphical installer, refer instead

to the ​Install​ section.

4.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 4.1.1​.
Fig. 4.1.1 Root Password Creation

Input and confirm the root password then click ​Next​ to proceed to the screen shown
in ​Figure 4.1.2​.
Fig. 4.1.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 4.1.3​.

Fig. 4.1.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 4.1.4​.

Fig. 4.1.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 4.1.5​.

Fig. 4.1.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.

4.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 4.2.1​, 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. 4.2.1 : 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.

4.3. 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 4.3.1​.
Fig. 4.3.1 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​.

4.4. 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 4.4.1​.

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

Variable Options Description

optional as installer will

should be unique for
hostname= auto-generate a hostname
the network
if empty

“fresh”, “upgrade”,
installMode= sets the installation type
“extract”, or “zfsrestore”

used only when

installMode​ is extract and
installLocation= /path/to/location
should point to an already
mounted location

set to “no” for automated

installInteractive= “yes” or “no”
installs without user input

“AUTO-DHCP” or type of network connection

netDev= FreeBSD interface to use during the
name installation

IP address of interface only use if ​netDev​ is set to

netIP=
used during installation an interface name

subnet mask of only use if ​netDev​ is set to

netMask=
interface an interface name

IP address of DNS only use if ​netDev​ is set to

netNameServer=
server an interface name
 IP address of default only use if ​netDev​ is set to
netDefaultRouter=
gateway an interface name

AUTO-DHCP or
type of network
FreeBSD interface
configuration to enable on
netSaveDev= name(s) (multiple
the installed system; can
allowed separated by
set multiple interfaces
spaces)

only use if ​netSaveDev​ is

IP address of interface set to an interface name or
netSaveIP=
or “DHCP” a list of interface names
(repeat for each interface)

only use if ​netSaveDev​ is

subnet mask of set to an interface name or
netSaveMask=
interface a list of interface names
(repeat for each interface)

only use if ​netSaveDev​ is

IP address of DNS set to an interface name or
netSaveNameServer= server (multiple allowed a list of interface names
separated by spaces) (do not repeat for each
interface)

only use if ​netSaveDev​ is

set to an interface name or
IP address of default
netSaveDefaultRouter= a list of interface names
gateway
(do not repeat for each
interface)

FreeBSD disk device see ​README​ for

disk0=
name, (e.g. ​ad0​) examples

“all”, “free”, “s1”, “s2”, see ​README​ for

partition=
“s3”, “s4”, or “image” examples
partscheme= “MBR” or “GPT” partition scheme type

FreeBSD disk device sets the target disk for the

mirror=
name (e.g. ​ad1​) mirror (i.e. the second disk)

defaults to “round-robin” if
“load”, “prefer”,
mirrorbal= the ​mirrorbal​ method is not
“round-robin”, or “split”
specified

bootManager= “none” or “bsd”

/path/to/image will write specified image

image=
/mountpoint file

this variable is mandatory

and must be placed at the
end of each ​diskX​ section;
commitDiskPart
create a ​diskX​ section for
each disk you wish to
configure.

at boot time, system will

prompt for this password in
encpass= password value order to mount the
associated GELI encrypted
partition

this variable is mandatory

and must be placed at the
end of disk’s partitioning
settings; see the
commitDiskLabel README​for examples on
how to set the <File
System Type> <Size>
<Mountpoint> entries for
each disk
 “dvd”, “usb”, “ftp”, source to be used for
installMedium=
“rsync”, or “image” installation

location of directory
localPath= /path/to/files
containing installation files

determines whether this is

installType= “PCBSD” or “FreeBSD” a desktop or a server
install

set to “yes” for automatic

installQuiet “yes” or “no”
installations

only set if using a

installFile= e.g. “fbsd-release.tbz” customized installer
archive

“tar”, “uzip”, “split”, the archive type on the

packageType=
“dist”, or “pkg” installation media

list of FreeBSD distribution

distFiles= e.g. “base src kernel” files to install when using
packageType=dist

location of the installer

ftpPath= ftp://ftp_path archive when using
installMedium=ftp

e.g. “life-preserver location of the rsync data

rsyncPath= /back-2011-09-12T14_ on the remote server when
53_14” using ​installMedium=rsync

set when using

rsyncUser= username
installMedium=rsync
 IP address of rsync set when using
rsyncHost=
server installMedium=rsync

set when using

rsyncPort= port number
installMedium=rsync

components must exist in

/PCBSD/pc-sysinstall/com
e.g. “amarok, firefox,
installComponents= ponents/​; typically,
ports”
installPackages=​ is used
instead

list of traditional or pkg

installPackages= e.g. “Xorg cabextract packages to install;
requires ​pkgExt=

specify the extension used

pkgExt= “.txz” by the type of package to
be installed

specify if you wish to keep

upgradeKeepDesktopProfi your existing user’s
“yes” or “no”
le= desktop profile data during
an upgrade

set the root password of

rootPass= password the installed system to the
specified string

set root password to

rootEncPass= encrypted string
specified encrypted string

create a separate block of

userName= case sensitive value user values for each new
user
 description text can include
userComment= description
spaces

userPass= password of user

set user password to

userEncPass encrypted string
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

comma separated (no

userGroups= e.g. “wheel, operator” spaces) list of additional
groups

mandatory, must be last

commitUser
line in each user block

run the specified command

within chroot of the
runCommand= full path to command
installed system, after the
installation is complete

runs specified script within

chroot of the installed
runScript= full path to script
system, after the
installation is complete

runs a command outside

runExtCommand= full path to command
the chroot
 runs the specified
runPrePkgCommand= full path to command command before starting
the pkg installation

runs the specified sript

runPrePkgScript= full path to command before starting the pkg
installation

runs the specified

runPrePkgExtCommand= full path to command command before extracting
the pkg

runs the specified

runPreExtractCommand= full path to command
command before extracting

runs the specified

runPreExtractScript= full path to command command before starting
the pkg installation

runs the specified

runPreExtractExtComman
full path to command command before starting
d=
the pkg installation

location must exist in

e.g.
timeZone= /usr/share/zoneinfo
“America/New_York”
/

enableNTP= “yes” or “no” enable/disable NTP

sets the system console

localizeLang= e.g. “en” and Desktop to the target
language
 updates the system’s Xorg
localizeKeyLayout= e.g. “en” config to set the keyboard
layout

updates the system’s Xorg

localizeKeyModel= e.g. “pc104” config to set the keyboard
model

updates the Xorg config to

localizeKeyVariant= e.g. “intl”
set the keyboard variant

user will log in

autoLoginUser= username automatically without
entering a password

the address of the remote

sshHost= hostname or IP address server when using
installMode=zfsrestore

the SSH port number of

the remote server when
sshPort= e.g “22”
using
installMode=zfsrestore

the username on the

sshUser= username remote server when using
installMode=zfsrestore

path to the SSH key file on

the remote server when
sshKey= e.g. “/root/id_rsa”
using
installMode=zfsrestore

e.g. “.lp-props location of dataset

zfsProps= -tank#backups#myback properties file created by
up” Life Preserver during
replication when
 using​installMode=zfsrestor
e

location of remote dataset

e.g. “tank/backups/
zfsRemoteDataset= to restore from when using
mybackup”
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 4.4.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.

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

Variable Options Description

location of customized
pc_config URL or /path/to/file
pc-sysinstall.conf

should be set to “yes”, or booting

confirm_install “yes” or “no” the wrong disk will result in a
system wipe

running a shutdown is
shutdown_cm recommended, but this can be any
e.g. ​shutdown -p now
d command/script to execute
post-install

“dhcp-all” or <interface attempts DHCP on all found NICs

nic_config name> <IP address> until the installation file is fetched
<subnet mask> 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.

5. Using TrueOS​®
This chapter discusses using TrueOS​®​ for many common tasks. Because TrueOS

incorporates the Lumina​®​ desktop environment and SysAdm​™​ system management

utility, those projects are used for a variety of user customization tasks such as

theming, user management, and system backups. As each of these projects have

their own documentation, links to the Lumina​®​ and SysAdm​™​ client handbooks are

provided.

5.1. Lumina​®
The Lumina Desktop Environment (Lumina​®​ for short) is a lightweight,
XDG-compliant, BSD-licensed desktop environment focused on streamlining work
efficiency with minimal system overhead. It is specifically designed for TrueOS​®​ and
FreeBSD, but has also been ported to many other BSD and Linux operating
systems. It is based on the Qt graphical toolkit and the Fluxbox window manager,
and uses a small number of X utilities for various tasks, such as ​numlockx​ and
xscreensaver​.

Lumina​®​’s features include:

● Very little system overhead.

 ● Does not require any of the desktop implementation frameworks such as
DBUS, policykit, consolekit, systemd, or HALD.
● Provides many ​utilities​ for configuring the desktop environment.
● Provides an interface design based on ​plugins​. The user can make their
desktop as light or heavy as they wish by choosing which plugins to have
running on their desktop and panels. This plugin-based system is similar to
Android or other modern operating systems.
● A single, easy-to-use ​Lumina Configuration​ utility controls all the different
configuration options for the desktop in one location.
● Intelligent ​favorites​ system for creating quick shortcuts to applications,
files, and directories.
● ZFS file restore functionality with ​Insight File Manager​.
● Multi-monitor support includes the ​Lumina Xconfig​ graphical utility for
adding or removing monitors from the Lumina​®​session.
● Simple ​system controls​ through the system tray for configuring audio
volume, screen brightness, battery status/notifications, and workspace
switching.
● Total system search capabilities through the resource friendly ​Lumina
Search​ utility.
● Screenshot functionality through ​Lumina Screenshot​, which is tied to the
Print Screen​ key by default.

Refer to the ​Lumina Handbook​ for detailed descriptions of every element of

Lumina​®​.

These next sections describe each element of TrueOS​®​ that is managed by Lumina​®
and provides links to the relevant section of the Lumina handbook.

5.1.1. Desktop Configuration

The ​Lumina Configuration​ utility allows the user to customize virtually every aspect
of the desktop. It is opened by right-clicking the desktop, then selecting ​Preferences
‣ All Desktop Settings​. These are the configurable elements using this utility:

Appearance​: Adjust theming, wallpapers, and windows. Theming includes default

font and size, theme template, color scheme, icon pack, and mouse cursors. There
is also an option to adjust the application themes, either manually or by applying a
downloaded theme engine.

Modifying windows includes effects, compositing, and default settings. An

Advanced Editor​ is also provided for the user to manually modify any existing
value.

Desktop Defaults​: Customize which applications are associated with specific

filetypes, the default file manager, virtual terminal, web browser, and e-mail client.
Choose packages to autostart when the system boots. Also adjust the default
keyboard shortcuts for the system.

Interface Configuration​: Customize widgets for the Desktop, the appearance and
options in the right-click Menu, and appearance, number, and options for any system
panels.

System Settings​: Central location for all configurable system utilities. Lumina​®
updates this category as new utilities are added and removed.

User Settings​: General settings for the user’s desktop session. Includes adjusting
time/date, user icons, chime options, and all localization options.

5.1.2. Utilities included with TrueOS

To provide a simple, but fully featured user experience immediately “out of box”,
TrueOS​®​ includes several utilities built directly into Lumina​®​.

Archiver​: Provides file compression and decompression services.

Calculator​: Basic calculator with scientific options and advanced functions.

Insight File Manager​: Browse and modify files on a per-directory basis.

File Information​: Displays specific information about a specified file or directory,

including permissions, ownership, size, and date of last modification.

Information​: Provides more information about the installed version of Lumina​®​.

Open​: This utility assists the user in finding programs to open specific files or URLs.
It can also be used to set the default application for specific file types.

Screenshot​: A very simple utility to take screenshots of the desktop, single windows,
or designated areas of a screen. Screenshots can be saved as ​.png​ files.

Search​: Find and launch applications or quickly search for files and directories.

Text Editor​: Plain text editor with customizable settings and built in rules for specific
file types.

Xconfig​: Graphical front-end to the ​xrandr​ command line utility. Manages attached
monitors, allowing the user to add, alter the position, and configure screens.

5.2. Network Manager

During installation, TrueOS​®​ configures any connected Ethernet interfaces to use
DHCP and provides a screen to ​Connect to a Wireless Network​. In most cases, this
means connected interfaces should “just work” whenever using a TrueOS​®​ system.

After installation, a wireless configuration icon appears in the system tray if TrueOS​®
detects a supported wireless card. Hover over the wireless icon shown in ​Figure
5.2.1​ to see an indication if the interface is associated and more information
regarding the IP address, IPv6 address, SSID, connection strength, connection
speed, MAC address, and type of wireless device.

Fig. 5.2.1 System Tray Wireless Information

If you right-click the wireless icon, a list of detected wireless networks displays. Click
the name of a network to associate with it. The right-click menu also provides options
to configure the wireless device, start the Network Manager, restart the network
(useful to renew your DHCP address), route the network connection through Tor (to
browse the Internet anonymously as described in ​Tor Mode​), and close the Network
Monitor so the icon no longer shows in the system tray.

To view or manually configure a network interface, click ​Start the Network

Manager​ within SysAdm​™​ or type​sudo pc-netmanager​. If a new device has
been inserted, such as a USB wireless interface, a pop-up message opens when
Network Manager starts. This message indicates the name of the new device and
asks if you want to enable it. Click ​Yes​ and the new device is displayed with the list
of network interfaces that TrueOS​®​ recognizes. In the example seen in ​Figure 5.2.2​,
the system has one Intel Ethernet interface that uses the ​em​ driver and an Intel
wireless interface that uses the ​wlan​ driver.
Fig. 5.2.2 Network Manager

The rest of this section describes each tab of the Network Manager utility and
demonstrates how to view and configure the network settings for both Ethernet and
wireless devices.

5.2.1. Network Devices

If you highlight an Ethernet interface in the ​Devices​ tab and either click
Configure​ or double-click the interface name, the screen shown in ​Figure 5.2.3
appears.
Fig. 5.2.3 Network Settings for an Ethernet Interface

There are two ways to configure an Ethernet interface:

1. Use DHCP:​ This method assumes your Internet provider or network router
assigns addressing information automatically using the DHCP protocol.
Most networks are built in this manner. This method is recommended as it
should “just work”.
 2. Manually type in the IP addressing information:​ This method requires
an understanding of the basics of TCP/IP addressing or knowledge of
which IP address to use on your network. If you do not know which IP
address or subnet mask to use, ask your Internet provider or network
administrator.

By default, TrueOS​®​ attempts to obtain an address from a DHCP server. If you wish
to manually type in your IP address, check​Assign static IP address​. Type in
the IP address, using the right arrow key or the mouse to move between octets.
Then, double-check the subnet mask (​Netmask​) is the correct value. If not, change it
again.

If the Ethernet network uses 802.1x authentication, check ​Enable WPA

authentication​, which enable the ​Configure WPA​button. Click this button to
select the network and input the authentication values required by the network.

By default, ​Disable this network device​ is unchecked. If this checkbox is

filled, TrueOS​®​ immediately stops the interface from using the network. The interface
remains inactive until this checkbox is unchecked.

The ​Advanced​ tab, seen in ​Figure 5.2.4​, allows advanced users to manually input
a ​MAC address​ or ​IPv6 address​. Both boxes should remain checked in order to
automatically receive these addresses, unless you are an advanced user with
reason to change the default MAC or IPv6 address and an understanding of how to
input an appropriate replacement address.
Fig. 5.2.4 Ethernet Interface Network Settings - Advanced

The ​Info​ tab, seen in ​Figure 5.2.5​, displays the current network address settings
and some traffic statistics.
Fig. 5.2.5 Ethernet Interface Network Settings - Info

If any changes are made within any of the tabs, click ​Apply​ to activate them. Click
OK​ when finished to return to the main Network Manager window.

Repeat this procedure for each desired network interface.

5.2.2. Wireless Adapters

If the wireless interface does not automatically associate with a wireless network, the
wireless profile containing the security settings required by the network will need to
be configured. Double-click the wireless icon in the system tray or highlight the
wireless interface displayed in the ​Devices​ tab of Network Manager and click
Configure​. ​Figure 5.2.6​ demonstrates this system’s wireless interface is currently
associated with the wireless network listed in the ​Configured Network
Profiles​section.

Fig. 5.2.6 Wireless Configuration

To associate with a wireless network, click ​Scan​ to view a list of connectable

wireless networks. Highlight the desired network to associate with and click ​+Add
Selected​. If the network requires authentication, a pop-up window prompts you for
the authentication details. Input the values required by the network, then click
Close​. TrueOS​®​ then adds an entry for the network in the ​Configured Network
Profiles​ section.

If the network is hidden, click ​+Add Hidden​, input the name of the network in the
pop-up window, and click ​OK​.

If multiple networks are added, use the arrow keys to place them in the desired
connection order. TrueOS​®​ attempts to connect to networks in order from first to last
in the connection list. When prioritizing connections, click ​Apply​. A pop-up message
then indicates TrueOS​®​ is restarting the network. Next, an IP address and status of
associated​ appears when hovering over the wireless icon in the system tray. If this
does not happen, double-check for errors in the configuration values and read the
Troubleshooting section on ​Network​.

TrueOS​®​ supports the types of authentication shown in ​Figure 5.2.7​. Access this
screen and change authentication settings by highlighting an entry in the
Configured Network Profiles​ section and clicking ​Edit​.
Fig. 5.2.7 Configuring Wireless Authentication Settings

This screen provides configuration of different types of wireless security:

● Disabled:​ If the network is open, no additional configuration is required.

● WEP:​ This type of network can be configured to use either a hex or a
plaintext key and Network Manager will automatically select the type of
detected key. If ​WEP​ is pressed, then ​Configure​, the screen in ​Figure
5.2.8​ appears. Type the key into both ​Network Key​ boxes. If the key is
complex, check ​Show Key​ to ensure the passwords are matching and
correct. Uncheck this box when finished to replace the characters in the
key with bullets. A wireless access point using WEP can store up to 4 keys
and the number in the ​key index​ indicates which desired key to use.
●
● Fig. 5.2.8 WEP Security Settings
● WPA Personal:​ This type of network uses a plaintext key. If you click
WPA Personal​ then ​Configure​, the screen shown in ​Figure 5.2.9
appears. Type in the key twice to verify it. If the key is complex, check
Show Key​ to ensure the passwords match.

●
● Fig. 5.2.9 WPA Personal Security Settings
● WPA Enterprise:​ If you click ​WPA Enterprise​ then ​Configure​, the
screen shown in ​Figure 5.2.10​ appears. Select the ​EAP
Authentication Method​, input the EAP identity, browse for the CA
 certificate, client certificate and private key file, and input and verify the
password.

●
● Fig. 5.2.10 WPA Enterprise Security Settings

Note

If unsure which type of encryption is being used, ask the person who setup the
wireless router. They should also be able to provide the value of any settings seen in
these configuration screens.
To disable this wireless interface, check ​Disable this wireless device​ in the
General​ tab for the device. This setting is helpful when temporarily preventing the
wireless interface from connecting to untrusted wireless networks.

The ​Advanced​ tab, seen in ​Figure 5.2.11​, allows configuring several options:

● Custom MAC address:​ This setting is for advanced users and requires
Use hardware default MAC address​ to be unchecked.
● Interface receiving IP address information:​ If the network contains a
DHCP server, check ​Obtain IP automatically (DHCP)​. Otherwise,
input the IP address and subnet mask to use on the network.
● Country code:​ This setting is not required if in North America. For other
countries, check ​Set Country Code​ and select your country from the
drop-down menu.
Fig. 5.2.11 Wireless Interface - Advanced

The ​Info​ tab, seen in ​Figure 5.2.12​, shows the current network status and statistics
for the wireless interface.
Fig. 5.2.12 Wireless Interface - Info

5.2.3. Network Configuration (Advanced)

The ​Network Configuration (Advanced)​ tab of the Network Manager is
seen in ​Figure 5.2.13​. The displayed information is for the currently highlighted
interface. To edit these settings, ensure the interface to configure is highlighted in
the ​Devices​ tab.

Fig. 5.2.13 Network Configuration - Advanced

If the interface receives its IP address information from a DHCP server, this screen
allows viewing of the received DNS information. To override the default DNS settings
or set them manually, check ​Enable Custom DNS​. You can then set:

● DNS 1:​ The IP address of the primary DNS server. If unsure which IP
address to use, click ​Public servers​ to select a public DNS server.
● DNS 2:​ The IP address of the secondary DNS server.
● Search Domain:​ The name of the domain served by the DNS server.
 To change or set the default gateway, check ​Enable Custom Gateway​ box and
input the IP address of the desired gateway.

Several settings can be modified in the IPv6 section:

● Enable IPv6 support:​ If this box is checked, the specified interface can
participate in IPv6 networks.
● IPv6 gateway:​ The IPv6 address of the default gateway used on the IPv6
network.
● IPv6 DNS 1:​ The IPv6 address of the primary DNS server used on the
IPv6 network. If unsure which IP address to use, click​Public servers​ to
select a public DNS server.
● IPv6 DNS 2:​ The IPv6 address of the secondary DNS server used on the
IPv6 network.

The ​Misc​ section has more options to configure:

● System Hostname:​ The name of your computer. It must be unique on

your network.
● Domain Name:​ If the system is in a domain, specify it here.
● Enable wireless/wired failover via lagg0 interface:​ This interface allows
seamless switching between using an Ethernet interface and a wireless
interface. Check the box to enable this functionality.

Note

Some users experience problems using lagg. If you have problems connecting to a
network using an interface which previously worked, uncheck this box and remove
any references to ​lagg​ from ​/etc/rc.conf​.

If any changes are made within this window, click ​Apply​ to save them.
5.2.4. Proxy Settings
The ​Proxy​ tab, shown in ​Figure 5.2.14​, is used when the network requires going
through a proxy server to access the Internet.

Fig. 5.2.14 Proxy Settings Configuration

Check ​Proxy Configuration​ to activate the settings. Some settings can be

configured in this screen:

● Server Address:​ Enter the IP address or hostname of the proxy server.

● Port Number:​ Enter the port number used to connect to the proxy server.
 ● Proxy Type:​ Choices are ​Basic​ (sends the username and password
unencrypted to the server) and ​Digest​ (never transfers the actual
password across the network, but instead uses it to encrypt a value sent
from the server). Do not select ​Digest​ unless the proxy server supports it.
● Specify a Username/Password:​ Check this box and input the username
and password if they are required to connect to the proxy server.

Proxy settings are saved to the ​/etc/profile​ and ​/etc/csh.cshrc​ files so they
are available to both the TrueOS​®​ utilities and any application using ​fetch​.

Applications not packaged with the operating system, such as web browsers, may
require configuring proxy support using that application’s configuration utility.

If you apply any changes to this tab, a pop-up message warns the user may have to
log out and back in for the proxy settings to take effect.

5.2.5. Configuring a Wireless Access Point

Right-click the entry for a wireless device, as seen in ​Figure 5.2.15​, and choose
Setup Access Point​.
Fig. 5.2.15 Setup Access Point

Figure 5.2.16​ shows the configuration screen if ​Setup Access Point​ is selected.
Fig. 5.2.16 Access Point Basic Setup

The ​Basic Setup​ tab of this screen contains two options:

● Visible Name:​ This is the name appearing when users scan for available
access points.
● Set Password:​ Setting a WPA password is optional, though
recommended to only allow authorized devices to use the access point. If
used, the password must be a minimum of 8 characters.

Figure 5.2.17​ shows the ​Advanced Configuration (optional)​ screen.

Fig. 5.2.17 Access Point Advanced Setup

The settings in this screen are optional and allow for fine-tuning the access point’s
configuration:

● Base IP:​ The IP address of the access point.

● Netmask:​ The associated subnet mask for the access point.
● Mode:​ Available modes are ​11g​ (for 802.11g), ​11ng​ (for 802.11n on the
2.4-GHz band), or ​11n​ (for 802.11n).
● Channel:​ Select the channel to use.
● Country Code:​ The two letter country code of operation.

5.2.6. Tor Mode

Tor mode uses ​Tor​, ​socat​, and a built-in script which automatically creates the
necessary firewall rules to enable and disable Tor mode at the user’s request. While
in Tor mode, the firewall redirects all outgoing ​port 80​ (HTTP), ​443​ (HTTPS), and
DNS traffic through the Tor transparent proxy network.

To start Tor mode, right-click the network icon in the system tray and check ​Route
through TOR​. Enter your password via the pop-up shown in ​Figure 5.2.18​. If
activated correctly, TrueOS​®​ opens a new browser window directed to
https://check.torproject.org

Fig. 5.2.18 Enabling Tor Mode

If you have never used the Tor network before, it is recommended to review the ​Tor
FAQ​.

The system remains in Tor mode until manually disabled. To disable Tor mode,
right-click the network icon and uncheck ​Route through Tor​.

To enable and disable Tor mode from the command line or on a desktop with no
system tray, use these commands:

● sudo enable-tor-mode​ enables tor mode.

● sudo disable-tor-mode​ disables tor mode.
5.3. SysAdm​™
Beginning with TrueOS​®​ 11, most of the system management utilities previously
available in the PC-BSD​®​ Control Panel have been rewritten to use the SysAdm​™
API​. This API is designed to simplify managing any FreeBSD, TrueOS​®​ desktop, or
TrueOS​®​server system over a secure connection from any operating system with the
SysAdm​™​ application installed. SysAdm​™​ is built into TrueOS​®​ as the ​SysAdm:
Control Panel​.

The SysAdm​™​ ​Client Handbook​ is recommended for new TrueOS​®​ users, while the
Server​ and ​API Reference​ guides are available for advanced users.

The rest of this section describes the elements of TrueOS controlled by SysAdm,
providing links to the relevant SysAdm documentation:

Application Management

AppCafe​ is a graphical interface for installing and managing FreeBSD packages.

These are pre-built applications tested for use with a FreeBSD-based operating
system. Open AppCafe​®​ by clicking the ​Start​ button (lower-left), then ​Control
Panel ‣ AppCafe​.

AppCafe​®​ breaks popular applications into a few categories and provides search
functionality for users looking for a specific application. Users can also browse
through a list of all currently installed applications and view more details or delete
them from the system.

Update Manager​ is a graphical interface for keeping both TrueOS​®​ and its installed
applications up to date. Users can check for updates, switch between the STABLE
and UNSTABLE tracks of TrueOS, configure automatic updating, and view the log
files of previous updates.
See ​Updating TrueOS​ for more details about using the ​Update Manager​.

SysAdm Server Settings

Managing Remote Connections​ provides instructions to create and manage SSL

keys or certificate bundles.

System Management

SysAdm​™​ provides the “core” for managing TrueOS​®​:

Boot Environment Manager​: Create and manage ZFS Boot Environments (BEs).
Boot Environments provide a “point-in-time” backup for the system and are highly
recommended. Options to ​create​, ​clone​, ​delete​, ​rename​, ​mount​, ​unmount​, and
activate​ a BE are available.

Mouse Settings​: Tool for adjusting the settings of a connected mouse. Acceleration,
DPI, right or left hand, drift, button emulation, and scrolling are all adjustable.

Firewall Manager​: This is used to configure all ports and firewalls for TrueOS​®​.
Options to ​open​ and ​close​ ports are available, including adjusting the firewall’s
autostart settings.

Service Manager​: This allows viewing and configuring all the system’s installed
services. There are options to ​start​, ​stop​, and ​restart​ services. Additional tunables to
adjust automatic starting of services are provided.

Task Manager​: A graphical window into system resource usage and a list of all
running applications. This provides details about what is currently happening on the
system and allows the user to stop any currently running process.
User Manager​: This utility controls users and groups. There are ​Standard​ and
Advanced​ views for both users and groups, and all options for creating new users
and groups are provided.

PersonaCrypt​ security can also be added to user accounts. This encrypts a user
account so it only becomes accessible with the proper password or by plugging in an
associated USB drive.

Utilities

Life Preserver​ is the only utility currently included with TrueOS​®​. This utility is used
for system backups with ​ZFS​ snapshots. ​Life Preserver​ provides easy
management, replication, and scheduling of ZFS snapshots.

5.4. Files and File Sharing

Several file managers are available for installation using AppCafe​®​. ​Table 5.4.1
provides an overview of several popular file managers. To launch an installed file
manager, type its name as it appears in the ​Application​ column. To install the file
manager, use AppCafe​®​ to install the package name listed in the ​Install​ column.
To research a file manager’s capabilities, start with the URL listed in its
Screenshot​ column.

Application Install Screenshots

dolphin kde-baseapps https://userbase.kde.org/Dolphin

http://linuxg.net/how-to-install-emelfm2-0-8-2-1-o
emelfm2 emelfm2
n-ubuntu-linux-mint-and-elementary-os/

caja caja http://mate-desktop.org/gallery/1.6/

 mucommande mucommande
http://www.mucommander.com/index.html
r r

https://projects.gnome.org/nautilus/screenshots.h
nautilus nautilus
tml

pcmanfm pcmanfm https://wiki.lxde.org/en/PCManFM

thunar thunar http://docs.xfce.org/xfce/thunar/start

http://roland65.free.fr/xfe/index.php?page=scree
xfe xfe
nshots

When working with files on a TrueOS​®​ system, save your files to your home
directory. Since most of the files outside your home directory are used by the
operating system and applications, you should not delete or modify any files outside
of your home directory unless confident in what you are doing.

Table 5.4.2​ summarizes the directory structure found on a TrueOS​®​ system. ​man
hier​ explains this directory structure in more detail.

Directory Contents

Pronounced as “root” and represents the beginning

/
of the directory structure

Applications (binaries) that were installed with the

/bin/
operating system

Stores the startup code, including kernel modules

/boot/
(like hardware drivers)
/compat/linux/ Linux software compatibility files

Files which are used by the operating system to

/dev/
access devices

/etc/ Operating system configuration files

/etc/X11/ The ​xorg.conf​ configuration file

/etc/rc.d/ Operating system startup scripts

Subdirectories for each user account; each user

/home/
should store their files in their own home directory

/lib/ Operating system libraries needed for applications

/libexec/ Operating system libraries and binaries

Mount point for storage media such as DVDs and

/media/
USB drives

/mnt/ Another mount point

The proc filesystem required by some Linux

/proc/
applications

/rescue/ Emergency recovery programs

/root/ Administrative account’s home directory

 Operating system applications; typically only the
/sbin/
superuser can run these applications

Temporary file storage; files stored here may

/tmp/
disappear when the system reboots

Contains most of the command line programs

/usr/bin/
available to users

Contains the binaries, libraries, startup scripts,

/usr/local/ documentation, and configuration files used by
applications installed from ports or packages

/usr/local/share/fonts/ System wide fonts for graphical applications

/usr/local/share/icons/ System wide icons

/usr/ports/ Location of system ports tree (if installed)

/usr/share/ System documentation and man pages

/usr/sbin/ Command line programs for the superuser

/usr/src/ Location of system source code (if installed)

Files that change (vary), such as log files and print

/var/
jobs

TrueOS​®​ provides built-in support for accessing Windows shares, meaning you only
have to decide which utility you prefer to access existing Windows shares on your
network.
Table 5.4.3​ summarizes some of the available utilities.

Application Install How to Access Existing Shares

In the left frame, click ​Network ‣ Samba

Shares​, then the Workgroup name; if the
network requires a username and password to
dolphin kde-baseapps browse for shares, set this in ​System
Settings ‣ Sharing​ while in KDE or type
systemsettings​ and click S ​ haring​ while in
another desktop

smb4k smb4k-kde4

Click ​Go ‣ Connect to server ‣ SMB​; input

mucommande mucommande the NETBIOS name of server, name of share,
r r name of domain (or workgroup), and the
share’s username and password

nautilus nautilus Click ​Browse Network ‣ Windows Network

In the left frame, click ​Network ‣ Windows

thunar thunar
Network

5.5. Managing System Services and Daemons

TrueOS​®​ now uses ​OpenRC​ to manage system services. OpenRC is an integral
component of the TrueOS​®​ operating system, and is a major point of difference
between TrueOS​®​ and FreeBSD. This section is intended to provide detailed
information about system service management in TrueOS​®​.

5.5.1. OpenRC in TrueOS​®​ compared with rc

Table 5.5.1​ serves as a quick summary and series of working examples contrasting
the FreeBSD ​rc​ system and OpenRC in TrueOS​®​.
Compo FreeBSD TrueOS​®
nent or
action

Base
system
/etc/rc.d /etc/init.d
rc script
location

Ports rc
script /usr/local/etc/rc.d /usr/local/etc/init.d
location

/etc/rc.conf
or​/etc/rc.conf.local OpenRC prefers
Service /etc/conf.d/servicename​,
configur but can use ​/etc/rc.conf​ or
ation /etc/rc.conf.local​ Each service
All services are configured in has its own configuration file.
a central location.

Starting
e.g. the
$ service nginx start $ service nginx start
nginx
service

Configur
ing e.g.
Edit ​/etc/rc.conf​ and
nginx​ to $ rc-update add nginx default
add​nginx_enable="YES"
start on
bootup.

Check $ rc-update show default |

$ service nginx rcvar
to see if grep nginx
a
service
 is If the service is enabled, the If the service is enabled, the
enabled. result is: result is:

nginx_enable="YES" nginx | default

Warning

The user may find leftover RC files during the TrueOS​®​ migration to OpenRC. These
files do not work with OpenRC and are intended to be removed both from the source
tree and via ​pc-updatemanager​ when all functionality is successfully migrated. If
discovered, ​do not​ attempt to use these leftover files.

5.5.2. Service Management in OpenRC

5.5.2.1. Runlevels
Traditionally, FreeBSD operates in single- and multi-user modes. However, OpenRC
offers the ability to define ​runlevels​. An OpenRC ​runlevel​ is a grouping of services,
nothing more. Any number of system services can be associated with a given
runlevel. In TrueOS​®​, there are two main preconfigured runlevels: ​boot​ and ​default​.
The ​default​ runlevel is analogous to the FreeBSD multi-user mode, and is
associated with the ​Normal Bootup​ option of the TrueOS​®​ bootloader.

Note

No OpenRC runlevels are executed if the system is booted into single-user mode
(see ​Figure 2.9.3​.)

Runlevels are defined by subdirectories of ​/etc/runlevels​; all associations

between services and runlevels can be shown by running the command:
 $ rc-update show -v

OpenRC has a few ordered runlevels in TrueOS​®​. In order of execution:

1. sysinit​: Used for OpenRC to initialize itself.

2. boot​: Starts most base services from ​/etc/init.d/​.
3. default​: Services started by ports are added here.

Note

Services added by ports cannot be added to ​boot​ or ​sysinit​.

OpenRC allows users to add services in the prefix location to the ​boot​ runlevel.
These services are started before the ​/usr​filesystem is mounted. Finally, there is a
shutdown​ runlevel reserved for a few services like ​savecore​ or ​pc-updatemanager​,
which installs updates at shutdown.

When a service is added to a runlevel, a symlink is created in ​/etc/runlevels​.

When a service is started, stopped, or changed to another state, a symlink is added
to ​/libexec/rc/init.d/​, as seen in this example:

[tmoore@Observer] ~% ls /libexec/rc/init.d/
daemons exclusive inactive scheduled starting wasinactive
depconfig failed options softlevel stopping
deptree hotplugged prefix.lock started tmp

5.5.2.2. Services and Runlevels

OpenRC includes options to ​start​, ​stop​, ​add​, or ​delete​ services from runlevels as
seen in ​Table 5.5.2​. Most of these actions can be accomplished using the ​Service
Manager​ built into SysAdm​™​. Individuals familiar with the FreeBSD ​service
command may notice some similarities between some of these commands.
 Command Description

service nginx start Start nginx from ​/usr/local/etc/init.d/nginx​.

Restart nginx from

service nginx restart
/usr/local/etc/init.d/nginx​.

service nginx stop Stop nginx from ​/usr/local/etc/init.d/nginx​.

service nginx status View the status of the ​nginx​ service.

rc-status View the status of all running services.

Views all runlevels. Used in conjunction with service

rc-update names to add or delete services from the default
runlevel.

rc-update add nginx

Adds the ​nginx​ service to the default runlevel.
default

rc-update delete nginx

Removes ​nginx​ from the default runlevel.
default

5.5.2.3. Writing OpenRC Services

OpenRC has a dependency based init system. As an example, examine the SysAdm
service, which needs ​network​. Here are the contents of the
/usr/local/etc/init.d/sysadm​ ​depend​ section:

depend() {
need net
after bootmisc
keyword -shutdown
}

SysAdm requires ​network​ (​need net​), which is the nickname of the

/etc/init.d/network​ service defined by ​provide in network​. SysAdm also starts
after​ ​bootmisc​. If you don’t want the restarting ​network​ to restart SysAdm, then ​net​ is
unnecessary. To start SysAdm after ​network​, then add ​network to the actual name of
the script in **after bootmisc*​.

Here are the contents of ​/etc/init.d/network​:

depend()
{
provide net
need localmount
after bootmisc modules
keyword -jail -prefix -vserver -stop
}

The ​provide​ option sets the service nickname to ​net​. ​Need​ means restarting
localmount​ restarts ​network​. ​After​ indicates the service starts after ​bootmisc​ and
modules​. For example, the keyword ​-jail​ option says this service doesn’t run in a jail,
prefix, or any of the other options shown.

There is also a cache directory under ​/libexec/rc​. This keeps a dependencies

cache that is only updated when those dependencies change. Several other
directories exist for other binaries and special binaries used by OpenRC functions.

For more creation options for OpenRC compatible init scripts, type ​man
openrc-run​ in a CLI.

5.5.3. RC Defaults
Note

RC Defaults are subject to change during development.

TrueOS​®​ and FreeBSD now have very different rc defaults.

TrueOS OpenRC Defaults

The entire ​TrueOS rc.conf file​ is viewable on GitHub.

# Global OpenRC configuration settings

# Set to "YES" if you want the rc system to try and start services
# in parallel for a slight speed improvement. When running in parallel
# we prefix the service output with its name as the output will get
# jumbled up.
# WARNING: whilst we have improved parallel, it can still potentially
# lock the boot process. Don't file bugs about this unless you can
# supply patches that fix it without breaking other things!
#rc_parallel="NO"

# Set rc_interactive to "YES" and you'll be able to press the I key

# during boot so you can choose to start specific services. Set to "NO"
# to disable this feature. This feature is automatically disabled if
# rc_parallel is set to YES.
#rc_interactive="YES"

# If we need to drop to a shell, you can specify it here.

# If not specified we use $SHELL, otherwise the one specified in
# /etc/psswd, otherwise /bin/sh

FreeBSD RC Defaults

The entire ​FreeBSD rc.conf file​ is available online.

#!/bin/sh
# This is rc.conf - a file full of useful variables that you can set
# to change the default startup behavior of your system. You should
# not edit this file! Put any overrides into one of the
# ${rc_conf_files} instead and you will be able to update these
# defaults later without spamming your local configuration information.
#
# The ${rc_conf_files} files should only contain values which override
# values set in this file. This eases the upgrade path when defaults
# are changed and new features are added.
#
# All arguments must be in double or single quotes.
#
# For a more detailed explanation of all the rc.conf variables, please
# refer to the rc.conf(5) manual page.
#
# $FreeBSD$

##############################################################

The TrueOS​®​ ​rc.conf​ file is smaller because ​rc.conf​ is now primarily used for
tuning OpenRC behavior. By default, TrueOS​®​uses 3 elements, documented in
Table 5.5.4​.

Table 5.5.3​ lists services and their default runlevels in TrueOS​®​.

Service Runlevel

abi boot

adjkerntz boot

automount default

bootmisc boot
bridge boot

cron boot

cupsd default

dbus default

devd boot

dumpon boot

fsck boot

hostid boot

hostname boot

ipfw boot

default
local
nonetwork

localmount boot

lockd default

loopback boot
modules boot

motd boot

moused default

netmount default

network boot

newsyslog boot

openntpd default

pcdm default

root boot

rpcbind default

savecache shutdown

savecore boot

statd default

staticroute boot

swap boot
 sysadm default

syscons boot

sysctl boot

syslogd boot

trueosinit default

urandom boot

zfs boot

zvol boot

5.5.4. Tuneables
Tunable Description

Starts all services in parallel

rc_parallel=”YES”
(experimental).

rc_logger=”YES” Enables logging

Defines the location for logging rc

rc_log_path=”/var/log/rc.log”
activity

Table 5.5.5​ shows all other tunables enabled on a clean TrueOS​®​ installation. Many
of these tunables continue to work in​/etc/rc.conf​ to ensure a smoother migration
 for existing users to upgrade. The eventual target locations for these services are
also listed.

Note

These migration targets are estimates and subject to change.

Tunable Description Migration Target

Notifies ​/etc/init.d/abi
linux_enable=”YES” service to enable the Linux /etc/conf.d/abi
compatability during boot

Auto-obtain IP address on the /etc/conf.d/netw

ifconfig_re0=”DHCP”
re0​ device. ork

ifconfig_re0_ipv6=”inet /etc/conf.d/netw
Configure IPv6.
6 accept_rtadv” ork

hostname=”trueos-484 /etc/conf.d/host
Set the system hostname.
3” name

TrueOS specific. Allows

kldload_i915kms=”i915 loading an individual module /etc/conf.d/mod
kms” via the installer post ules
installation.

zfs_enable=”YES” Obsolete, marked for removal None

wlans_iwm0=”wlan 0 Configure iwm wireless with /etc/conf.d/netw

DHCP” DHCP. ork
 ifconfig_wlan0_ipv6=”i Configure iwm wireless with /etc/conf.d/netw
net6 accept_rtadv” IPv6. ork

5.5.5. OpenRC Install Scripts

There are number of scripts used for older TrueOS​®​ systems and new installations.
These are listed below.

5.5.5.1. One-time Migration Script

A one time migration script is available for TrueOS​®​ installations dated 10-28-16 or
older still using the legacy FreeBSD ​rc​system:

Note

This block is truncated from the ​original file

#!/bin/sh

if [ ! -e /etc/rc.conf ] ; then
exit 0
fi

. /etc/rc.conf

for var in `set | grep "_enable="`

do
key=`echo $var | cut -d '=' -f 1 | sed 's|_enable||g'`
val=`echo $var | cut -d '=' -f 2`
if [ "$val" != "YES" ] && [ "$val" != "NO" ] ; then continue; fi
if [ "$val" = "NO" ] && [ -e "/etc/runlevels/default/$key" ] ; then
echo "Deleting OpenRC service for $key to default runlevel..."
rc-update delete $key default
fi
if [ -e "/etc/init.d/$key" -o -e "/usr/local/etc/init.d/$key" ] ; then
if [ -e "/etc/runlevels/default/$key" ] ; then
echo "OpenRC service for $key already enabled, skipping.."
 With this migration, ​rc.conf.trueos​, located in ​/etc/​, has been phased out of
TrueOS​®​ and is automatically removed from legacy installs dated 10-28-16 and older
by ​pc-updatemanger​:

This script defines a list of services such as ​PCDM​ designated to boot by default on
a desktop. It also defines what drivers to load on a desktop. This is now
accomplished when the ​trueos-desktop​ or ​trueos-server​ package is installed using
sysrc​ or other methods. Now there is no need to keep an extra overlay file to
accomplish this behaviour.

5.5.5.2. TrueOS​®​ Desktop pkg-install Script

Note

This is an excerpt from the TrueOS​®​ Desktop ​pkg-install​ file, available online:
https://github.com/trueos/trueos-desktop/blob/master/port-files/pkg-install

#!/bin/sh
# Script to install preload.conf

PREFIX=${PKG_PREFIX-/usr/local}

if [ "$2" != "POST-INSTALL" ] ; then

exit 0
fi

# If this is during staging, we can skip for now

echo $PREFIX | grep -q '/stage/'
if [ $? -eq 0 ] ; then
exit 0
fi

# REMOVEME - Temp fix to ensure i915kms is loaded on upgraded systems

# 8-29-2016
if [ -e "/etc/rc.conf.trueos" ] ; then
set +e
 grep -q "i915kms" /etc/rc.conf.trueos

5.5.5.3. TrueOS Server pkg-install script

Note

This is an excerpt from the TrueOS​®​ Server ​pkg-install​ file, available on GitHub:
https://github.com/trueos/trueos-server/blob/master/port-files/pkg-install

#!/bin/sh
# Script to install preload.conf

PREFIX=${PKG_PREFIX-/usr/local}

if [ "$2" != "POST-INSTALL" ] ; then

exit 0
fi

# If this is during staging, we can skip for now

echo $PREFIX | grep -q '/stage/'
if [ $? -eq 0 ] ; then
exit 0
fi

# Copy over customizations for TrueOS

install -m 644 ${PREFIX}/share/trueos/conf/loader.conf.trueos /boot/loader.conf.trueos
install -m 644 ${PREFIX}/share/trueos/conf/brand-trueos.4th /boot/brand-trueos.4th
install -m 644 ${PREFIX}/share/trueos/server-defaults/etc/conf.d/modules
/etc/conf.d/modules/

The typical ​nginx_enable=”YES”​ is no longer used to enable services. Instead,

rc-update​ adds or deletes services from runlevels. The one time migration script
automatically adds previously defined user services to the OpenRC default runlevel.
Leftover lines can be removed after migration.

5.5.6. Updating a Port’s Makefile

 There are many required updates to adjust each port’s ​Makefile​ to the new format,
USE_OPENRC_SUBR=​. However, these are to be changed only when each service
file has the new OpenRC ready format:

Note

This is an excerpt from the TrueOS​®​ ​openrc-dbus.in​ file, which is available on

the TrueOS​®​ ​freebsd-ports GitHub repository

#!/sbin/openrc-run
# Copyright (c) 2007-2015 The OpenRC Authors.
# See the Authors file at the top-level directory of this distribution
# and https://github.com/OpenRC/openrc/blob/master/AUTHORS
#
# This file is part of OpenRC. It is subject to the license terms in
# the LICENSE file found in the top-level directory of this
# distribution and at
# https://github.com/OpenRC/openrc/blob/master/LICENSE.
# This file may not be copied, modified, propagated, or distributed
# except according to the terms contained in the LICENSE file.

command=/usr/local/bin/dbus-daemon
pidfile=/var/run/dbus/pid
command_args="${dbusd_args---system}"
name="Message Bus Daemon"

depend()
{
need localmount
after bootmisc
}

Here is an example from FreeBSD of ​dbus​ using the legacy rc script format:

Note
This is an excerpt from the legacy FreeBSD ​dbus.in​ file, which is available online:
https://github.com/freebsd/freebsd-ports/blob/master/devel/dbus/files/dbus.in

#!/bin/sh
#
# $FreeBSD$
#
# PROVIDE: dbus
# REQUIRE: DAEMON ldconfig
#
# Add these lines to /etc/rc.conf to enable the D-BUS messaging system:
#
# dbus_enable="YES"
#

. /etc/rc.subr
. %%GNOME_SUBR%%

dbus_enable=${dbus_enable-${gnome_enable}}
dbus_flags=${dbus_flags-"--system"}

name=dbus
rcvar=dbus_enable

Several developers are working on the thousands of instances as quickly as

possible. Anyone can begin transitioning to defining all service configurations in
/etc/conf.d/​, if desired. All configuration files should reside in that directory with
the name of the service for the configuration file itself. For example, ​nginx​ is
/etc/conf.d/nginx​.

Generally, usage of ​/etc/rc.conf​ is minimized. Tweaking the default OpenRC

configuration parameters is recommended only for advanced users. It is still possible
to use service configurations through ​/etc/rc.conf​, but this file is unusable for
enabling or disabling services for startup.
5.6. Flash Plugin
TrueOS​®​ supports using a Flash plugin for those browsers/applications that use
Flash. To begin using this plugin, search for and install “linux-flashplayer” using
AppCafe​®​. Alternately, type ​[samp@examp] ~% sudo pkg install
linux-flashplayer​ in a command line and enter the root password when requested.

The “nspluginwrapper” is also required when using Flash. Install it with AppCafe​®​ or
by typing​[samp@examp] ~% sudo pkg install nspluginwrapper​ in a
command line.

Once ​linux-flashplayer​ and ​nspluginwrapper​ are installed, configure them by opening

a command line and typing this command:

% nspluginwrapper -v -a -i

Auto-install plugins from /usr/local/lib/browser_plugins

Looking for plugins in /usr/local/lib/browser_plugins
Auto-install plugins from /usr/local/lib/browser_plugins/linux-flashplayer
Looking for plugins in /usr/local/lib/browser_plugins/linux-flashplayer
Install plugin /usr/local/lib/browser_plugins/linux-flashplayer/libflashplayer.so
into /usr/home/tmoore/.mozilla/plugins/npwrapper.libflashplayer.so
Auto-install plugins from /usr/home/tmoore/.mozilla/plugins
Looking for plugins in /usr/home/tmoore/.mozilla/plugins

In this example, Flash is configured and ready for use with the Firefox browser. To
confirm Flash is usable, open Firefox and type​about:plugins​ in the address bar. An
Installed plugins​ page displays, listing ​Shockwave Flash​ an installed plugin. See
Figure 5.6.1​ as an example of Firefox with Flash installed.
 Fig. 5.6.1 “​about:plugins​” Example

5.7. Automounter
Tip

The ​Mount Tray​ has been replaced by the new ​Automounter​.

The automounter, based on the ​devd​ and ​automount​ utilities, facilitates mounting
and unmounting USB storage devices and optical media. It also conforms to an ​XDG
standard to allow the addition of new features. The automounter is part of the default
TrueOS​®​ installation, but is generally invisible until a new device is attached to the
system.

Currently, the automounter ignores internal hard drives (sata, ide) and networking
shares. It does support many different filesystems:

● cd9660
● exFAT (Requires ​mount.exfat-fuse​. Possible intermittent detection
issues.)
 ● ext2
● ext4 (Requires ​ext4fuse​)
● FAT32
● MSDOSFS
● MTPfs (Requires ​simple-mtpfs​)
● NTFS (Requires ​ntfs-3g​)
● ReiserFS
● UDF
● UFS
● XFS

Warning

Linux based filesystems may have some limitations. See ​Table 1.2.2​ for more
details.

To engage the automounter, attach a USB storage device or insert optical media to
the system. The automounter detects the device by ID and adds icons to the
desktop, as seen in ​Figure 5.7.1​:
 Fig. 5.7.1 USB icons added to desktop via the automounter.
Hovering over the icon displays the actual device name and
filesystem type.

Tip

The appearance of these icons do ​not​ mean the device is mounted. Devices are
only mounted when the user begins to interact with the device.

Either navigating to a device or beginning copy operations mounts the device. The
device is unmounted by the ​autounmountd​service after the user navigates away
and/or file copy operations stop.

For example, the above image shows USB drive “FreeNAS” attached to the system.
After double-clicking the desktop icon, “Insight File Manager” opens to the device’s
location, ​autofs/da0​. While ​Insight​ opens, the automounter mounts the device.
 After closing ​Insight​, the device is also unmounted and safe to remove from the
system.

In the CLI, the automounter adds a ​.desktop​ file to ​/media​ when a new
USB/Optical device is added. Open the ​.desktop​file with ​xdg-open​ or
lumina-open​. When the device is removed, the symlink is immediately removed
from ​/media​.

Note

The ​/.autofs/*​ directories are not cleaned when the device is removed. However,
after device removal the directories are no longer associated with the device in the
backend. For this reason, ​/media​ is more useful to identify which devices are
attached to the system.

Alternately, all device names are added to the ​/.autofs​ directory. Attached devices
are also accessed by navigating to​/.autofs/<devicename>​.

Known limitations:

● UFS permissions. These permissions are preserved on USB media. To

allow multiple users access to files from a UFS stick, those files’
permissions need to be set to ​read/write by any user​ (777).
● ZFS pools are not yet supported. This is under investigation to ascertain if
it can ever work with ​automount​.
● Optical Media links are not yet created on the desktop. Optical media is
accessible by navigating to ​/.autofs​.
● Any file system with limited FreeBSD support (HFS or EXT) remain at the
same level of limited support.
● exFAT detection issues are being investigated.
 Coming soon:

● Optical media support for the desktop

● Android device support
● Possible support for ZFS pools

5.8. FreeBSD Ports

Use ​git​ to fetch the FreeBSD ports tree on a local system. Specifically, the TrueOS​®
branch of the FreeBSD ports tree is pulled, which is regularly updated against the
base FreeBSD ports tree.

Note

These commands must be run as the superuser or ​root​.

When fetching ports for the first time:

# git clone http://github.com/trueos/freebsd-ports.git /usr/ports

To update an existing local ports directory:

# cd /usr/ports
# git pull

5.9. Printing and Scanning

Like many open source operating systems, TrueOS​®​ uses the Common Unix
Printing System (​CUPS​) to manage printing.

CUPS provides an easy-to-use utility for adding and managing printers. Whether or
not it automatically detects a printer depends upon how well the printer is supported
by an open source print driver. This section walks you through a sample
configuration for a HP DeskJet 36xx series printer. Your specific printer may “just
work”, which simplifies this process immensely. If your printer configuration does not
work, read this section more closely for ideas on locating correct drivers for your
printer.

5.9.1. Researching your Printer

Before configuring your printer, see if a driver already exists for your particular
model, and if so, which driver is recommended. If you are planning to purchase a
printer, this is definitely good information to know beforehand. Look up the vendor
and model of the printer in the ​Open Printing Database​, which indicates if the model
is supported and if there are any known caveats with the print driver. Once the model
is selected, click ​Show this printer​ to see the results.

For the HP DeskJet model example, the HPLIP driver is recommended. In TrueOS​®​,
the HPLIP driver is available as an optional package called ​hplip​. Use AppCafe​®​ to
search if the driver is installed, and install it if not.

5.9.2. Adding a Printer

Once printer support is determined, ensure the printer is plugged into your computer
or, if the printer is a network printer, both your computer and the printer are
connected to the network. Then, open a web browser and enter the address
127.0.0.1:631/admin​. This opens the CUPS configuration, shown in ​Figure 5.9.1​.
Fig. 5.9.1 Printer Configuration

To add a new printer, click ​Add Printer​. CUPS will pause for a few seconds as it
searches for available printers. When finished, a screen similar to ​Figure 5.9.2​ is
shown.
Fig. 5.9.2 Print Device Selection

In this example, the wizard has found the HP DeskJet 3630 printer on both the USB
port (first entry) and the wireless network (second entry). Click the desired
connection method then click ​Continue​. CUPS then attempts to load the correct
driver for the device. If successful, a screen shown in ​Figure 5.9.3​ is shown.
Fig. 5.9.3 Describe Printer

This screen automatically fills out the printer model series, a description, and the
type of connection. If desired, add a descriptive ​Location​. If sharing the printer on
a network, check ​Sharing​.

Once you click ​Continue​, the next screen, shown in ​Figure 5.9.4​, displays a
summary of the selected options and offers the ability to select another driver. For
now, leave the detected driver and click ​Add Printer​. If the printer does not work
using the default driver, read the Troubleshooting ​Printer​ section, which describes
how to use this screen in more detail.
Fig. 5.9.4 Viewing the Default Driver

The next screen, shown in ​Figure 5.9.5​, can be used to modify the properties of the
printer.
Fig. 5.9.5 Modify Print Properties

It is recommended to take a few minutes to review the settings in the ​General​,

Banners​, and ​Policies​ tabs, as these allow configuration options such as print
banners, permissions, the default paper size, and double-sided printing. The
available settings can vary depending on the capabilities of the print driver. When
finished, click ​Set Default Options​ to save the options. This opens the
Printers​ tab with the new printer displayed. An example is shown in ​Figure 5.9.6​.

Fig. 5.9.6 Manage Printer

Print a test page to ensure the printer is working. Verify the printer has paper and
click ​Maintenance -> Print Test Page​. If a test page does not print, refer to the
Printer​ of this handbook.
5.9.3. Manually Adding a Driver
If the print configuration fails, double-check the printer is supported as described in
Researching your Printer​ and HPLIP is installed if it is a HP printer. Also check the
printer is plugged in and powered on.

If the wizard is unable to even detect the device, try to manually add the information
for the print device. In the ​Select Device​screen (​Print Device Selection​), select
the type of connection to the printer and input all necessary information. The type of
information depends upon the type of connection:

USB:​ This entry only appears if a printer is plugged into a USB port and the number
of entries vary depending on the number of USB ports on the system. If there are
multiple USB entries, highlight the one representing the USB port your printer is
plugged into.

IPP:​ Select this option if connecting to a printer cabled to another computer (typically
running a Microsoft operating system) sharing the printer using IPP. Input the IP
address of the printer and the name of the print queue. To use IPP over an
encrypted connection, select “ipps” instead.

HTTP:​ This option allows you to manually type in the URI to the printer. A list of
possible URIs is available on the ​CUPS site​. To use HTTP over an encrypted
connection, select ​https​ instead.

AppSocket/HP JetDirect:​ Select this option if connecting to an HP network printer.

Input the IP address of the printer. Only change the port number if the printer is using
a port other than the default of ​9100​.
 LPD/LPR:​ Select this option if connecting to a printer which is cabled to a Unix
computer using LPD to share the printer. Input the hostname and queue name of the
Unix system.

After inputting the connection information, continue to add the printer and test the
connection by printing a test page as described in ​Adding a Printer​.

If the default driver is not working, try re-adding the printer. At the ​Viewing the
Default Driver​ screen, try selecting a different driver.

Alternately, if you have a PPD driver from the manufacturer’s website or on the CD
packed in with the printer, click ​Choose File​ to browse to the location of the PPD
file. PPD (PostScript Printer Description) is a driver created by the manufacturer
ending in a ​.ppd​ extension. Sometimes the file ends with a ​.ppd.gz​ extension,
indicating it is compressed.

5.9.4. Scanning
While no scanning applications are included with TrueOS​®​, there are a few options
available via AppCafe​®​. One good option is​XSane​, a graphical utility for managing
scanners. The rest of this section describes using ​XSane​ for scanning.

To use your scanner, make sure the device is plugged into the TrueOS​®​ system and
click ​Browse Applications ‣ Scanner​ or type ​xsane​ from the command line. A
pop-up message indicates XSane is detecting devices and prompts you to accept
the XSane license if a device is detected. If a device is not detected, search for your
device at the list of ​supported scanners​.

Note
If the scanner is part of an HP All-in-One device, make sure the “hplip” package is
installed. Use AppCafe​®​ to see if the driver is installed, and install it if not.

Figure 5.9.7​ shows the XSane interface running on a TrueOS​®​ system attached to
an HP DeskJet Printer/Scanner.

Fig. 5.9.7 XSane Interface

The ​XSane documentation​ contains details on how to perform common tasks such
as saving an image to a file, photocopying an image, and creating a fax. It also
describes all of the icons in the interface and how to use them.

By default, XSane uses the default browser when clicking ​F1​ to access its built-in
documentation. Configuring the default browser varies by window manager so an
Internet search may be necessary to set the default browser setting.

5.10. Fonts
TrueOS​®​ installs with ​Google Noto​ which provides multi-lingual Sans and Serif fonts.
Many other fonts are available from AppCafe​®​. Typically, fonts installed using
AppCafe​®​ do not require any additional configuration to “just work”.

If you have downloaded or purchased a collection of font, TrueOS​®​ can be

configured to also use those fonts. Become the superuser and copy the downloaded
font to the ​/usr/local/share/fonts/​ directory. Then, run ​fc-cache -f -v
/usr/local/share/fonts/name_of_font​ to refresh the fonts cache.

5.11. Sound Mixer Tray

TrueOS​®​ includes a graphical utility for managing the sound card’s mixer settings.
The utility is accessed by clicking the​speaker​ icon in the system tray.

Figure 5.11.1​ shows an example of highlighting the ​Output​ option after opening the
Sound Mixer. If the system has one audio output, the ​Output​ submenu is not
displayed. Clicking an option in this submenu does not set the default audio device.
It only changes it to the selected output for the current session. The next reboot
reverts audio output back to the default.
Fig. 5.11.1 Output Options

Figure 5.11.2​ shows the ​Mixer​ menu:

Fig. 5.11.2 Mixer Controls

The ​Mixer Controls​ screen provides sliders to modify the left and right channels
that control volume, pcm (the sound driver), the speaker, the microphone, the
recording level, the input level, and the output level. Each control can be muted or
unmuted by clicking ​Mute​ or ​Unmute​, depending on its current mute state.
Figure 5.11.3​ shows the ​System Configuration​ tab of the ​Mixer​.

Fig. 5.11.3 System Sound Configuration

This tab contains several options:

● Recording Device:​ Use the drop-down menu to select the device to use
for recording sound.
● Default Tray Device:​ Use the drop-down menu to set the default slider to
display in the system tray.
● Audio Output Channel:​ Use the drop-down menu to change the sound
device and use ​Test​ to determine if sound is working. This is sometimes
necessary when changing audio devices. For example, when connecting a
USB headset, TrueOS​®​detects the new device and automatically changes
the audio device to the USB input. However, when inserting a headset into
an audio jack, the system may not detect this new input, meaning the
default device has changed manually. ​Set as Default​ sets the currently
selected audio output channel as the system default.
 The ​Disable PulseAudio​ disables all PulseAudio support.

The ​File​ menu can be used to quit this mixer screen or to close both this screen and
remove the icon from the system tray.

Note

To re-add the mixer icon after removing it, type ​pc-mixer &​ in a command line.
Alternately, open this application without adding it back to the system tray by typing
pc-mixer -notray​.

TrueOS​®​ provides full ​PulseAudio​ support, which can be configured using the
Configuration​ menu in the ​Mixer​. There are options for accessing the
PulseAudio Mixer​ and ​PulseAudio Settings​, as well as an option for
restarting PulseAudio. These utilities can be used to configure discoverable network
sound devices and mixer levels.

5.12. Multimedia
TrueOS​®​ is pre-configured to support most multimedia formats and makes it easy to
install most open source media applications using AppCafe​®​.

After installing a web browser, most media formats become playable, including
YouTube™ videos, Internet radio, and many trailer and movie sites. When
encountering a file unplayable in a web browser or media player, it is likely in a
proprietary format which requires a licensing fee or restricts distribution of the codec
required to play the media format.

Note
When troubleshooting Java™ or Flash® for your browser, please refer to the
FreeBSD browser​ documentation, which has more complete instructions for
installing Java™ and Flash® plugins with specific browsers.

AppCafe​®​ contains several dozen applications for playing and editing multimedia. It
includes these popular applications:

● aTunes​: Full-featured audio player and manager which can play mp3, ogg,
wma, wav, flac, mp4 and radio streaming, allowing users to easily edit
tags, organize music and rip audio CDs.
● Audacity​: Multilingual audio editor and recorder.
● DeaDBeeF​: Music player supporting most audio formats.
● Decibel​: Audio player built around a highly modular structure which lets the
user completely disable unneeded features. Able to play CDs directly.
● gtkpod​: Graphical user interface for the Apple iPod.
● Miro​: HD video player which can play almost any video file and offers over
6,000 free Internet TV shows and video podcasts.
● SMPlayer​: Universal media player which can handle any media format and
play audio CDs, DVDs, (S)VCDs, TV/radio cards, YouTube™ and
SHOUTcast™ streams.
● VLC media player​: Open Source cross-platform multimedia player capable
of playing most multimedia files, DVD and CD formats, and some
streaming protocols.
● Kodi,formerly known as XBMC​: GPL-licensed software media player and
entertainment hub for digital media. It can play most audio and video
formats, CDs and DVDs from a disk or image file, and even files inside ZIP
and RAR archives.
● Plex Home Theater​: Centralized media playback system. The central Plex
Media Server streams media to many Plex player Apps which are used to
view your media library and watch shows.
5.13. Windows Emulation
Wine​ is an application which allows the creation of a Windows environment for
installing Windows software. This can be useful if your favorite Windows game or
productivity application has not yet been ported to Linux or BSD.

Wine is not guaranteed to work with every Windows application. You can search for
desired applications in the ​Browse Apps​section of the ​Wine application database​.
The ​Wine wiki​ contains resources to get started and troubleshooting reference
material if problems are encountered with a Windows application.

Wine can be installed using AppCafe​®​. After installing, it can be started by typing
winecfg​ in the command line. The first time running this utility, it may prompt to
install additional required packages. If prompted, click ​Install​ in the pop-up menu.

The initial Wine configuration menu is shown in ​Figure 5.13.1​.

Fig. 5.13.1 Wine Configuration Menu

Click ​Add application​ to browse to the application’s installer file. By default, the
contents of the hard drive will be listed under ​drive_c​. If the installer is on a CD/DVD,
use the drop-down menu to browse to the ​home directory ‣ *.wine ‣ dosdevices
folder. The contents of the CD/DVD should be listed under ​d:​. If they are not, the
most likely reason is your CD/DVD was not automatically mounted by the desktop.
To mount the media, type ​mount -t cd9660 /dev/cd0 /cdrom​ as the superuser.

The system then accesses the media and you can now select the installer file. Once
selected, click ​Apply​ then ​OK​ to exit the configuration utility.
 To install the application, type ​winefile​ to see the screen shown in ​Figure 5.13.2​.

Fig. 5.13.2 Installing the Application Using winefile

Click the button representing the drive which contains the installer and double-click
on the installation file (e.g. ​setup.exe​). The installer then launches to allow
installing the application as on a Windows system.

Note

You may need need to unmount a CD/DVD before it ejects. As the superuser, type
umount /mnt​.

Once the installation is complete, browse to the application’s location. ​Figure 5.13.3
shows an example of running Internet Explorer within ​winefile​.
Fig. 5.13.3 Running the Installed Application

5.14. Updating TrueOS

The TrueOS project is organized around two update tracks: STABLE and
UNSTABLE. Updating is handled through the SysAdm​™​Update Manager; refer to the
SysAdm ​Update Manager​ documentation for more details about using the Update
Manager. This section only contains simple instructions to switch between update
tracks.

To view or adjust the current update track for TrueOS, click ​Start Menu ‣ Control
Panel ‣ Update Manager ‣ Settings​. The ​Settings​ tab, seen in ​Figure 5.14.1​,
allows you to adjust ​when​ and ​where​ to perform system updates.
 Fig. 5.14.1 Update Manager Settings

While both STABLE and UNSTABLE tracks are rolling releases based on
FreeBSD-CURRENT, there are a few key differences between them.

Warning

Users with UNSTABLE installed before 7/14/2017 need to run ​pc-updatemanager

syncconf​ in a command line in order to switch to the new UNSTABLE repository
added on that day. Alternately, switch from UNSTABLE to STABLE in the Update
Manager and click ​Save​. Then, switch back to UNSTABLE and click ​Save​ again.

5.14.1. TrueOS STABLE

As its name implies, STABLE refers to the more solid version of TrueOS. STABLE
updates are released infrequently, but are much more tested and polished. All
TrueOS installation files are created from the STABLE track, and fresh TrueOS
installations only look to the STABLE track for updates.

The STABLE track is recommended for those users who want a more predictable
experience with fewer regressions, and are willing to wait longer for bugfixes and
new utilities or ports.

5.14.2. TrueOS UNSTABLE

The UNSTABLE track is the bleeding edge of TrueOS development. Experimental
fixes, upstream patches from the FreeBSD project, and testing new utilities and
applications all happen first with the UNSTABLE track.

UNSTABLE is recommended for power users, those with custom hardware

unsupported with STABLE, and project contributors who wish to help test patches
committed to TrueOS and/or FreeBSD-CURRENT.

To switch to the UNSTABLE track, open the SysAdm Update Manager and navigate
to the ​Settings​ tab, seen in ​Update Manager Settings​. Check ​UNSTABLE
Repository​, then click ​Save Settings​.

Alternately, you can edit ​/usr/local/etc/trueos.conf​ to change update tracks

without using SysAdm. Here is an example​trueos.conf​:

# TrueOS Configuration Defaults

# Default package set to pull updates from

PACKAGE_SET: <STABLE, UNSTABLE, or CUSTOM>
PACKAGE_URL: <CUSTOM url>

# Default type of CDN to use

# IPFS - Use IPFS
# HTTP - Use a standard HTTP connection (default)
# CDN_TYPE: HTTP

# Set the number of automatic boot-environments to create / keep

MAXBE: 5
AUTO_UPDATE: disabled
AUTO_UPDATE_REBOOT: disabled

Rolling back from UNSTABLE to STABLE is done by switching tracks back to the
STABLE branch, checking for updates, and rebooting once the previous STABLE
update is installed.
 6. TrueOS Pico​®
Warning

As a result of TrueOS using OpenRC and other changes, an update to these

instructions, especially server initialization, is forthcoming.

TrueOS Pico​®​ is an initiative to connect multiple small ARM device thin clients to a
single TrueOS​®​ system. Similar to the SysAdm​™​ project, TrueOS Pico​®​ utilizes two
primary pieces of software: Pico Server​®​ and Pico Client​®​.

The goal for the TrueOS Pico​®​ is to provide a low-cost solution for users who wish to
have a central server provide resources to multiple low-cost, low-power systems. In
effect, TrueOS Pico​®​ allows one system to provide all the processing power and
graphical “muscle” for as many computers the user wishes to add on the network.
For example, three or four users can log into their thin clients and open utilities,
browse the Internet, or even play games while one central server dynamically
provides the needed resources for each of these tasks.

Pico Server​®​ is available through ​pkg​ and in AppCafe​®​. Configure the server
software before downloading the client software or initializing the Pico Client​®​.

To download the Pico Client​®​ software, visit the TrueOS​®​ ​download page​. A
separate computer is required to unpack and transfer the ​.img​ file to a microSD
card for insertion into the thin client.

Currently, the TrueOS Pico​®​ software is functional for TrueOS​®​ and the Raspberry Pi
2 model B v1.1. The bulk of development efforts are being directed toward ensuring
graphics and sound functionality. Future development goals include supporting a
 wider variety of ARM devices and potential thin clients, and building cross-platform
support for the server software.

6.1. TrueOS Pico​®​ Initialization

To create a TrueOS Pico​®​ network, several elements are required:

● A TrueOS​®​ system with both an internet and local network connection to

download the necessary files and be used as the Pico Server​®​. For this
system, it is recommended to use strong hardware to provide the
smoothest experience for each connected client.

Tip

For best performance, it is recommended to have wired network connections from

the Pico Server​®​ to all connected clients.

● An ARM device to act as the thin client (as many as the user wants or the
server can support). Currently, only the Raspberry Pi 2 model B v1.1 is
supported, with up to five simultaneous connections on one Pico Server​®​.
● A microSD card for each thin client.

Note

Using a microSD card larger than 4 GB in size is largely unnecessary, as the server
stores almost all created data.

● Adapter or connector for microSD cards to connect to the Pico Server​®

(Ex. a USB to microSD card reader).

Each thin client will need:

 ● HDMI monitor. Currently, 1920x1080 is the maximum supported resolution
and the monitor should have integrated speakers for audio to function
properly.
● Network cable.
● USB mouse.
● USB keyboard.
● Power adapter.

Once all these components are assembled, it’s time to configure the Pico Server​®​.

6.2. Pico Server​®

Installing and configuring the Pico Server​®​ is done via the command prompt, with
superuser permissions (​su​ or ​sudo <rest of command>​). Open a terminal and
download the Pico Server​®​ package with ​sudo pkg install picoserver​ (also
available in AppCafe​®​). Next, enable the Pico Server​®​ using ​sysrc -f /etc/rc.conf
picoserver_enable=yes​. Finally, start the Pico Server​®​ with ​service picoserver
start​.

Note

These commands will ensure the Pico Server​®​ automatically starts and remains
active when the system is booted. Type​picoserver onestart​ to run the server for the
current session only.

Once the Pico Server​®​ starts, a new ​picoserver.ini​ file is created on the system,
found in ​/usr/local/etc​. This ​.ini​ file holds the initialization settings for the Pico
Server​®​ and has three sections, seen in ​Table 6.2.1​:

SSH Video Audio

 enablesound=tru
cipher enablevgl=true
e

compression=<1-9
>

Note

The ​Configuration Settings​ Table will expand as more options are developed and
added to ​picoserver.ini​.

Set the ​compression​ setting to any number from 1 to 9. The default setting is
recommended as turning up the compression can introduce performance issues on
the Pico Client​®​.

Pico uses ​Virtual GL​ (VGL) for graphics hardware acceleration. VGL works with any
OpenGL​ supported graphics card, but Nvidia cards are generally recommended at
this time.

Warning

Turning on VGL may introduce security vulnerabilities on a network with untrusted

clients.

If the server does not support video acceleration or to avoid any potential security
vulnerabilities on the Pico network, edit​picoserver.ini​ and change ​enablevgl=​ to
false​.
 Currently, audio only functions over the HDMI connection port on the Raspberry Pi,
meaning audio will only work on monitors with built-in audio capabilities. Change
true​ to ​false​ to disable all audio.

Once satisfied with the settings in ​picoserver.ini​, new user accounts/logins may
need to be created for the client systems. See the ​User Manager​ section of the
SysAdm​™​ handbook for detailed instructions on creating new users on a TrueOS​®
system.

After any necessary accounts are created, the next step is to initialize the client.

6.3. Starting the Pico Client​®

The process of initializing a Pico Client​®​ begins on a separate TrueOS​®​ system. On
this system, navigate to the TrueOS​®​website’s ​download page​ and download the
latest ​<pico>.img.xz​ file. This file is compressed with ​xz​; decompress the file
before burning it to a microSD card. Using the command line, navigate to the file’s
location to use ​unxz​ to unpack the file:

[tmoore@Observer] ~% cd Downloads/
[tmoore@Observer] ~/Downloads% unxz TrueOS-pico-rpi2-2016-10-29.img.xz

It may take a few moments for the system to decompress the file.

Once the file is decompressed to a ​.img​ file, insert a microSD card into the system.
An adapter might be necessary if the system has no microSD card slots. As the
superuser, use the ​dd​ command line utility to write the ​.img​ file to the card:

Warning
Be sure the ​dd if=​ command points to the correct storage device. In the example
below, the microSD card is connected to a USB adapter, identified as ​da0​ on the
system.

[tmoore@Observer] ~/Downloads% dd if=TrueOS-pico-rpi2-2016-10-29.img of=/dev/da0 bs=4m

512+0 records in
512+0 records out
2147483648 bytes transferred in 426.140554 secs (5039379 bytes/sec)

This command may take some time to process.

After the ​.img​ file is written to the microSD card; connect the Pico Client​®​ to the
Pico Server​®​:

● Insert the microSD card into the thin client.

● Attach the network cable. Be sure the client is wired into the same network
as the Pico Server​®​.
● Plug in the USB Mouse and Keyboard.
● Attach the monitor’s HDMI cable.
● Plug in the ARM device’s power cable. This should always be the ​last
step.

For the Raspberry Pi, inserting the power cable will generally turn on the client
device. The Pico Client​®​ then searches for and connects to any Pico Server​®​ on the
network, bringing the user to the TrueOS​®​ login screen. The Pico Client​®​ is now
ready for use.

6.4. Using the Pico Client​®

There are a few differences in TrueOS​®​ when using a Pico Client​®​.

If the server uses the Lumina​®​ Desktop Environment, hovering over the ​Network
Status Icon​ in the System Tray displays the client’s IP address, the server’s IP
address, and the client’s unique ​pico_auth​ number, seen in ​Image 6.4.1​. This is
intended to efficiently provide relevant network information for simplified server
administration.

Fig. 6.4.1 Pico Client​®​ IP display

When logging out with the Pico Client​®​, several processes begin. The client clears
the session, then restarts the discovery and connection processes. The server will
destroy the previous user’s ​temp​ file, along with the previously assigned ​pico_auth
#​. These processes prepare the server for a new connection and user login from the
same Pico Client​®​.

6.4.1. VGL Graphics Acceleration

VirtualGL (VGL) is the toolkit used by the TrueOS Pico​®​ to provide 3D hardware
acceleration to the Pico Client​®​. VGL redirects OpenGL commands and data to the
GPU in the Pico Server​®​, then pulls back the rendered 3D images to the client. For
further information about this open-source project, please refer to the ​VirtualGL
website

VirtualGL also has an extensive ​user guide​ to help guide new users through the
various features of this useful toolkit.

On a Pico Client​®​, test VGL functionality by opening the command line and typing
/usr/local/VirtualGL/bin/vglrun glxgears​. A window will popup, displaying several
moving gears, as seen in ​Image 6.4.2​. The terminal also displays the framerate of
the gears, and updates periodically.

Fig. 6.4.2 VirtualGL Gears Test

6.4.2. Pulse Audio

Pulse Audio​ is the preferred audio solution for the Pico Client​®​. Pulse Audio allows a
Pico Client​®​ play audio sent from the server. The Pulse Audio user ​documentation
provides a wealth of information on configuring Pulse Audio, including streaming
audio over the network. Advanced controls for Pulse Audio are available in
AppCafe​®​ with the ​pavucontrol​ multimedia application.

6.5. Pico Server​®​ Administration

Once the Pico Server​®​ and thin clients are installed and ready to use, there are a
number of administrative commands available, seen in ​Table 6.5.1​. Any new
commands will be added to this table:
 Command Description

Primary Pico command. All commands begin with

pico-server
pico-server​ and a space.

Displays all connected clients, as either “pico_auth <#>”

-list
or the specific logins (“testuser_pico”)

-kill pico_auth <#> Immediately reboots the specified client.

7. Help and Support
The TrueOS​®​ Project strives to make using TrueOS​®​ as easy as possible for

newcomers. If help is needed, there are many ways to get in touch with the TrueOS​®

community. This chapter describes the available resources for troubleshooting

TrueOS​®​.

As a teacher may have said, “there is no such thing as a stupid question”. However,

there are ways to ensure a productive exchange for all parties involved. The two

articles below describe how and why it is important to follow certain protocols when

requesting help:

● How to Ask Smart Questions (PDF)

● How To Ask Questions The Smart Way

7.1. Troubleshooting
This section contains instructions to troubleshoot user discovered issues with
TrueOS​®​. These instructions are not exhaustive, but can serve as a starting point
when encountering problems with TrueOS​®​. If the particular issue is missing from
this section, see the section about the ​The TrueOS® Community​ for instructions
about asking for help from the wider community.

7.1.1. Display
If problems exist with the display settings and manually editing
/etc/X11/xorg.conf​ or running ​Xorg --config​ is necessary, first tell the
TrueOS​®​ system to not automatically start X. To do this, add ​pcdm_enable="NO"
temporarily to ​/etc/rc.conf​, then reboot the system.
The system reboots to a login prompt. After logging in, follow the instructions in the
FreeBSD ​Handbook​ to manually configure and test Xorg. Once a working
configuration is found, save it to ​/etc/X11/xorg.conf​. Then, remove the
temporary line shown above from ​/etc/rc.conf​ and start PCDM with ​service
pcdm start​.

If the graphics white-out after a suspend or resume, run ​sysctl

hw.acpi.reset_video=1​ as the superuser.

If the problem is fixed, carefully add ​hw.acpi.reset_video=1​ to

/etc/sysctl.conf​.

If the monitor goes blank and does not come back, run ​xset -dpms​ as the regular
user account.

If the problem is fixed, add ​xset -dpms​ to the ​.xprofile​ file in the user’s home
directory.

If any display settings change, click ​Apply​ for the settings to be tested. If anything
goes wrong during testing, the system returns to the ​Display Settings​ screen for
the user to try another setting. Once satisfied with the tested setting, click ​“Yes​ to
save the setting and proceed. Alternately, click ​Skip​ to configure the display settings
later.

7.1.2. Installation
Installing TrueOS​®​ is usually very simple. However, sometimes problems occur. This
section examines solutions to the most common installation problems.

The TrueOS​®​ installer creates a log which keeps a record of all the completed steps,
as well as any errors. When an installation error occurs, the TrueOS​®​ installer asks
to generate an error report. If ​Yes​ is chosen, a pop-up message asks to save the
error log to a USB stick. Type ​y​ and insert a FAT formatted USB thumb drive to copy
the log.

While in the installer, read this log to see what went wrong. Click the black
Emergency Shell and Utilities​ icon, then select​shell​ from the ​|trueos|
Utility Menu​. Read the log by typing ​more /tmp/.SysInstall.log​.

If the error can not be fixed or you believe an installation bug exists, include the log
saved on the USB stick in your bug report by following the instructions in ​Report a
bug​.

If the installer does not arrive at the initial GUI installer screen, try unplugging as
many devices as possible, such as webcams, scanners, printers, USB mice and
keyboards. If this solves the problem, plug in one piece of hardware at a time, then
reboot. This helps pinpoint which device is causing the problem.

Additionally, you may need to enable ​EFI​ in Virtualbox by navigating ​Settings ‣

System ‣ Motherboard​ and checking ​Enable EFI (special OSes only)​.

If the computer freezes while probing hardware and unplugging extra devices does
not fix the problem, it is possible that the installation media is corrupt. If the ​Data
Integrity Check​ on the downloaded file is correct, try burning the file again at a lower
speed.

If the system freezes and the video card is suspected to be the cause, review the
system’s BIOS settings. If there is a setting for video memory, set it to its highest
value. Also, check to see if the BIOS is set to prefer built-in graphics or a
non-existent graphics card. On some systems this is determined by the order of the
devices listed; in this case, be sure the preferred device is listed first. If the BIOS
settings are invisible, move a jumper or remove a battery to make it revert to the
default built-in graphics; check the manual or contact the card manufacturer for
details.

A common cause for problems is the ​LBA​ (Logical Block Addressing) setting in the
BIOS. If the PC is not booting before or after installation, check the BIOS and turn
LBA​ off (do not leave it on automatic).

If the SATA settings in the BIOS are set to ​compatibility​ mode, try changing this
setting to ​AHCI​. If the system hangs with a BTX error, try turning off ​AHCI​ in the
BIOS.

If the USB keyboard is non-functional, check if there is an option in the BIOS for
legacy support​ in relation to the keyboard, USB, or both. Enabling this feature in the
BIOS may solve this issue.

If the installer boots and a ​mountroot>​ command prompt appears, this may be due to
a change in the location of the boot device. This can occur when the enumeration of
a card reader changes. The solution is to enter ​ufs:/dev/da1​ at the prompt.
Depending on the exact location of the boot media, it may be different from ​da1​.
Type ​?​ at the prompt to display the available devices.

If none of the above has fixed the problem, the ​The TrueOS® Community​ is a
valuable resource to assist in tracking down and solving the issue.

7.1.3. Network
While networking usually “just works” on a TrueOS​®​ system, users sometimes
encounter problems, especially when connecting to wireless networks. Sometimes
the problem is due to a configuration error or sometimes a driver is buggy or
unavailable. This section is meant to help pinpoint the problem, so you can either
 personally fix it or give the developers the information they need to fix or create a
driver.

When troubleshooting the network configuration, use these files and commands.

The ​/etc/rc.conf​ file is read when the system boots up. In order for the system to
configure an interface at boot time, an entry must exist for it in this file. Entries are
automatically created during installation for each active interface. An entry is added
(if it does not exist) or modified (if it already exists) when configuring an interface
using the ​Network Manager​.

Here is an example of the ​rc.conf​ entries for an ethernet driver (​em0​) and a
wireless driver (​run0​):

ifconfig_em0="DHCP"
wlans_iwm0="wlan0"
ifconfig_wlan0="WPA SYNCDHCP"

When reading your own file, look for lines beginning with ​ifconfig​. For a wireless
interface, also look for lines containing ​wlans​.

Note

Unlike Linux interface driver names, FreeBSD/TrueOS​®​ interface driver names

indicate the type of chipset. Each driver name has an associated manual page
where you can learn which devices use that chipset and if there are any
configuration options or limitations for the driver. When reading the man page, do not
include the interface number. For the above example, read ​man em​ and ​man iwm​.
/etc/wpa_supplicant.conf​ is used by wireless interfaces and contains the
information needed to connect to a WPA network. If this file does not already exist, it
is created when entering the ​Configuration​ screen of a wireless interface.

The command ​ifconfig​ shows the current state of the interfaces. When reading
through its output, ensure the desired interface is listed, has a status of ​active​, and
has an IP address. Here is a sample ​ifconfig​ output showing the entries for an ​re0
Ethernet interface and a ​run0​ wireless interface:

re0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500

options=389b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_UCAST,WOL_MCAST,WOL_MAGI
C>
ether 60:eb:69:0b:dd:4d
inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
media: Ethernet autoselect (100baseTX <full-duplex>)
status: active

run0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 2290

ether 00:25:9c:9f:a2:30
media: IEEE 802.11 Wireless Ethernet autoselect mode 11g
status: associated

wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500

ether 00:25:9c:9f:a2:30
media: IEEE 802.11 Wireless Ethernet autoselect (autoselect)
status: no carrier
ssid "" channel 10 (2457 MHz 11g)
country US authmode WPA1+WPA2/802.11i privacy ON deftxkey UNDEF
txpower 0 bmiss 7 scanvalid 60 protmode CTS wme roaming MANUAL bintval 0

In this example, the ethernet interface (​re0​) is active and has an IP address.
However, the wireless interface (​run0​, which is associated with ​wlan0​) has a status
of ​no carrier​ and does not have an IP address. In other words, it has not yet
successfully connected to the wireless network.
The ​dmesg​ command lists the hardware probed during boot time and indicates if the
associated driver was loaded. To search the output of this command for specific
information, pipe it to ​grep​ as seen in this example:

dmesg | grep Ethernet

re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem
0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8
re0: Ethernet address: 60:eb:69:0b:dd:4d

dmesg |grep re0

re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem
0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8
re0: Using 1 MSI messages
re0: Chip rev. 0x28000000
re0: MAC rev. 0x00000000 miibus0: <MII bus> on re0
re0: Ethernet address: 60:eb:69:0b:dd:4d
re0: [FILTER]
re0: link state changed to DOWN
re0: link state changed to UP

dmesg | grep run0

run0: <1.0> on usbus3
run0: MAC/BBP RT3070 (rev 0x0201), RF RT2020 (MIMO 1T1R), address 00:25:9c:9f:a2:30
run0: firmware RT2870 loaded

If the desired interface does not show up with ​ifconfig​ or ​dmesg​, it is possible a
driver for this card is not provided with the operating system. If the interface is built
into the motherboard of the computer, use the ​pciconf​ command to discover the
type of card:

pciconf -lv | grep Ethernet

device = 'Gigabit Ethernet NIC(NDIS 6.0) (RTL8168/8111/8111c)'

pciconf -lv | grep wireless

device = 'Realtek RTL8191SE wireless LAN 802.11N PCI-E NIC (RTL8191SE?)'
In this example, there is a built-in Ethernet device using a driver which supports the
RTL8168/8111/8111c​ chipsets. As we saw earlier, the driver is ​re0​. The built-in
wireless device was also found but the ​?​ indicates a driver for the ​RTL8191SE
chipset was not found. A web search for ​FreeBSD RTL8191SE​ gives an indication if
a driver exists or is being developed.

The FreeBSD Handbook chapter on ​Wireless Networking​ provides a good overview

of how wireless works and offers additional troubleshooting suggestions.

7.1.4. Printer
Here are some solutions to common printing problems:

● A test page prints but it is all garbled:​ This typically means the system
is using the wrong driver. If your specific model was not listed, click
Adminstration ‣ Modify Printer​ for the printer in the ​Printers​ tab. In
the screen shown in ​Viewing the Default Driver​, try choosing another
driver close to your model number. If trial and error does not fix the
problem, see if there are any suggestions for your model in the ​Open
Printing database​. A web search for ​freebsd​ followed by the printer model
name may also help you find the correct driver to use.
● Nothing happens when you try to print:​ In this case, type ​tail -f
/var/log/cups/error_log​ in a console and then try to print a test page.
Any error messages will appear in the console. If the solution is not
obvious from the error messages, try a web search for the error message.
If you are still stuck, post the error, the model of your printer, and your
version of TrueOS​®​ as you ​Report a bug​.

7.1.5. Replication
This is a recreation of the user submitted article: ​Forcibly resetting ZFS replication
using the command line​ ​lpreserver​. A special ​“thank you!”​ to TrueOS​®​ user
VulcanRidr​ for providing this article.

ZFS​ replication can be somewhat complex, and keeping all the fiddly bits aligned
can be fraught with danger.

I recently had both of my TrueOS​®​ machines start failing to replicate. My desktop is

called ​defiant​ and it has two pools: ​NX74205​ and ​NCC1764​. My laptop is named
yukon​ with a single pool, ​NCC74602​. I am replicating to my FreeNAS server, named
luna​, to the dataset ​NX80101/archive/<FQDN>​. I will focus on what I did to
get ​yukon​ working again in this document.

7.1.5.1. Original Indications

The SysAdm​™​ client tray icon was pulsing red. Right-clicking on the icon and clicking
Messages​ showed the message:

FAILED replication task on NCC74602 -> 192.168.47.20: LOGFILE:

/var/log/lpreserver/lpreserver_failed.log

This was lifted from ​/var/log/lpreserver/lpreserver.log​.

/var/log/lpreserver/lastrep-send.log​ shows very little information:

send from @auto-2017-07-12-01-00-00 to

NCC74602/ROOT/12.0-CURRENT-up-20170623_120331@auto-2017-07-14-01-00-00
total estimated size is 0
TIME SENT SNAPSHOT

And no useful errors were being written to the ​lpreserver_failed.log​.

7.1.5.2. Repairing Replication

First Attempt:

My first approach was to use the SysAdm​™​ Client (see the ​Life Preserver​ section for
more details).

Figure 7.1.1​ shows my Life Preserver Replication tab:

Fig. 7.1.1 Attempt 1: GUI Replication Repair

I clicked on the dataset in question, then clicked ​Initialize​. I waited for a few
minutes, then clicked ​Start​. I was immediately rewarded with a pulsing red icon in
the system tray and received the same messages as noted above.

Second Attempt:
I was working with and want to give special thanks to users ​@RodMyers​ and
@NorwegianRockCat​. They suggested I use the​lpreserver​ command line. So I
issued these commands:

sudo lpreserver replicate init NCC74602 192.168.47.20

sudo lpreserver replicate run NCC74602 192.168.47.20

Unfortunately, the replication failed again, with these messages:

Fri Jul 14 09:03:34 EDT 2017: Removing NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT

- re-created locally
cannot unmount '/mnt/NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT': Operation not
permitted
Failed creating remote dataset!
cannot create 'NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT': dataset already
exists

It turned out there were a number of child sets. I logged into the FreeNAS (​luna​) and
issued this command as ​root​:

# zfs destroy -r NX80101/archive/defiant.sonsofthunder.nanobit.org

Then I ran the ​replicate init​ and ​replicate run​ commands again from the TrueOS​®
host. Replication now works and continues to work, at least until the next fiddly bit
breaks.

7.1.6. Sound
Type ​mixer​ from the command line to see the current sound settings

mixer
Mixer vol is currently set to 0:0
Mixer pcm is currently set to 100:100
Mixer speaker is currently set to 100:100
Mixer mic is currently set to 50:50
Mixer rec is currently set to 1:1
Mixer monitor is currently set to 42:42
Recording source: monitor

If any of these settings are set to ​0​, set them to a higher value by specifying the
name of the mixer setting and a percentage value up to ​100​:

mixer vol 100

Setting the mixer vol from 0:0 to 100:100.

To make the change permanent, create a file named ​.xprofile​ in the home
directory containing the corrected mixer setting.

If only one or two mixer settings are available, the default mixer channel needs to
change. As the superuser, use​sysctl -w hw.snd.default_unit=1​ to alter the mixer
channel.

To see if the mixer has changed to the correct channel, type ​mixer​ again. If there
are still only one or two mixer settings, try setting the ​sysctl​ value to ​2​, and, if
necessary, ​3​.

Once all of the mixer settings appear and none are set to ​0​, sound typically works. If
it still does not, these resources can help pinpoint the problem:

● FreeBSD Handbook Sound Section

● FreeBSD Sound Wiki

If sound issues persist, consider asking the ​The TrueOS® Community​ for help or
Report a bug​. When reporting an issue, be sure to include both the version of
TrueOS​®​ and name of the sound card.
 7.2. Upgrading from PC-BSD​®​ 10.x to TrueOS​®
Warning

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.

Note

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 7.2.1​.
 Fig. 7.2.1 Disk Selection

TrueOS​®​ automatically detects if the drive has an existing boot environment and fills
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.

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

A pop-up will appear and ask to start the default Full-Disk installation. Click ​Yes​ to
begin the installation.

When the installation is complete, reboot the system and remove the installation
media. The post-installation screens run as described in the ​Booting Into TrueOS
section to help configure the new installation.

Warning

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.

7.3. The TrueOS​®​ Community

The TrueOS​®​ community has grown and evolved since the project’s inception. A
wide variety of chat channels and forum options are now available for users to
interact with each other, contributors to the project, and the core development team.

7.3.1. Telegram Community

The TrueOS​®​ Project uses ​Telegram​ to provide real-time chat and collaboration with
TrueOS​®​ users and developers. Telegram is available in a web browser or as
downloadable applications for Android, macOS, and PC/Mac/Linux.
To access the TrueOS Telegram community, point a web browser to
https://web.telegram.org​. Sign in with a valid phone number and join the ​TrueOS
Community channel​.

Telegram maintains a full archive of the chat history. This means lengthy
conversations about hardware issues or workarounds are always available for
reference.

Here are some tips about the community channel:

● Most of the regular users are always logged in, even when they are away
from their computer or are busy doing other things. If no one responds
immediately, do not get mad, leave the channel, and never come back
again. Stick around for a while to see if anyone responds.
● Users represent many different time zones. It is quite possible it is late at
night or very early in the morning for some users when asking a question.
● Do not post large error messages in the channel. Instead, use a pasting
service such as ​https://pastebin.com/​ and refer to the URL on channel.
● Be polite and do not demand a response from others.
● It is considered rude to “Chat Privately” with someone who does not know
you without first asking their permission. If no one answers the question,
do not start chatting privately with unkown people in the room.
● The first time joining the channel, it is okay to say “hi” and introduce
yourself. If a new person joins the channel, feel free to welcome them and
to make them feel welcome.

7.3.2. TrueOS​®​ Subreddit

The TrueOS​®​ Project also has a ​Subreddit​ for users who prefer to use Reddit to ask
questions and to search for or post how-tos. A Reddit account is not required in
order to read the Subreddit, but it is necessary when submitting new posts or
commenting on existing posts.
7.3.3. Discourse
TrueOS​®​ also has a ​Discourse forum​ managed concurrently with the Subreddit.
Functionally similar to the Subreddit, a new user needs to sign up with Discourse in
order to create posts, but it is possible to view the current posts without an account.

7.3.4. IRC
Like many open source projects, TrueOS​®​ has an Internet Relay Chat (IRC) channel
so users can chat and get help in real time. To get connected, use this information in
your IRC client:

● Server name: irc.freenode.net

● Channel name: #trueos (note the ​#​ is required)

AppCafe​®​ has an IRC category where you can find IRC client software. If you do not
wish to install an IRC client, you can use the web interface to view #trueos:
https://webchat.freenode.net/

IRC is a great way to chat with other users and get answers to your questions. Here
are a few things to keep in mind if you ask a question on IRC:

● Most of the regular users are always logged in, even when they are away
from their computer or are busy doing other things. If you do not get an
answer right away, do not get mad, leave the channel, and never come
back again. Stick around for a while to see if anyone responds.
● IRC users represent many different time zones. It possibly late at night or
very early in the morning for some users when you ask a question.
● Do not post error messages in the channel as the IRC software can kick
you out for flooding and it is considered to be bad etiquette. Instead, use a
pasting service such as ​pastebin​ and refer to the URL on channel.
● Be polite and do not demand that others answer your question.
 ● It is considered rude to DM (direct message) someone who does not know
you. If no one answers your question, do not start DMing people you do
not know.
● The first time you join a channel, it is okay to say “hi” and introduce
yourself.

7.3.5. Social Media

The TrueOS​®​ project maintains several social media sites to help users keep
up-to-date with what is happening and to provide venues for developers and users to
network with each other. Anyone is welcome to join.

● Official TrueOS® Blog

● TrueOS® Project on Twitter
● TrueOS® Facebook Group
● TrueOS® LinkedIn Group

7.4. Contributing to TrueOS​®

Many in the TrueOS​®​ community have assisted in its development, providing
valuable contributions to the project. TrueOS​®​ is a large project with many facets,
meaning there is ample opportunity for a wide variety of skill sets to easily improve
the project.

7.4.1. Report a bug

One of the most effective ways to assist the TrueOS​®​ Project is by reporting
problems or bugs encountered while using TrueOS​®​. Anyone can report a TrueOS​®
bug. Here is a rundown of the TrueOS​®​ bug reporting tools:

● TrueOS​®​ uses a ​GitHub repository​ to manage bugs. A GitHub account is

required before bugs can be reported. Navigate to ​https://github.com/​, fill
 in the required fields, and click ​Sign up for GitHub​ to create a new
GitHub account.

Note

The GitHub issues tracker uses email to update contributors on the status of bugs.
Please use a valid and frequently used email address when creating a GitHub
account.

● The TrueOS​®​ code is organized into many repositories representing the

Lumina​®​ desktop, the graphical utilities, SysAdm​™​, and various other
applications. When reporting a bug, select the ​trueos-core​ repository. If the
bug is specific to Lumina​®​, use the ​lumina​ repository. Documentation bugs
are tracked in their respective ​-docs​ repositories. Issues with any project
website are tracked in ​trueos-website​.
● After clicking a repository’s ​Issues​ tab, use the ​search​ bar to confirm no
similar bug report exists. If a similar report does exist, add any additional
information to the report using a comment. While it is not required to log in
to search existing bugs, adding a comment or creating a new report does
require signing into GitHub.
● To create a new bug report, navigate to the desired repository and click
Issues ‣ New Issue​. ​Figure 7.4.1​ shows the creation of a new bug
report.
Fig. 7.4.1 Creating a Bug Report

Here are some basic guidelines for creating useful bug reports:

Title Area

The ideal title is clear, concise, and informative. Here are some recommendations for
creating a title:

● Be objective and clear (and refrain from using idioms or slang).

● Include the application name if the issue is related to an application.
● Include keywords from any error messages you receive.
● Avoid using vague language such as “failed”, “useless”, or “crashed”.

Here are some examples to show the difference between a helpful title and a
non-helpful title:

Example 1:

Non-Helpful:
Lumina-FM crashed.
Helpful:
Lumina-FM crashed after clicking on a directory name.

Example 2:

Non-Helpful:
Extracting an archive doesn't work.
Helpful:
Lumina-Archiver shows the error "file not supported" when opening a
.cab file.

Comment Area

Like with the ​title​, being clear and concise is extremely helpful. Many people feel
they must fill this area with lots of information. While listing a lot of information seems
helpful, specific details are often more useful in issue resolution.

The most important pieces of information to include are:

1. What happened.
2. What you expected to happen.
3. (​Critical​) Steps to reproduce the issue. Please provide the exact steps
you can take to produce this issue from a fresh boot. If the issue is
application specific, provide the exact steps from a fresh start of the
application.
4. List any changes you may have made to your system from its initial install.
In most cases, this does not need to be extremely detailed. It is very
helpful for contributors to know if you have installed or removed any major
applications or if you have changed any OS settings. If you are unsure of
all your changes, list what comes to mind.
5. List the hardware of the system where the issue occurred. If you are using
an OEM laptop or desktop, listing the brand or model is usually sufficient.
If the issue is wireless related, please check the system manufacturer’s
 website for your brand or model and let us know what wireless cards may
be shipped in your laptop. If you are using a custom built desktop, all we
primarily need to know is CPU, RAM, and GPU. If you happen to know the
motherboard model, please include it too. Attaching a copy of
/var/run/dmesg.boot​ is also helpful, as this file shows the hardware
probed the last time the TrueOS​®​system booted. Finally, including the
output of ​uname -a​ is helpful.

Being clear and direct with your report and answers is very helpful. As we are not
watching you use your computer and do not see what you see, we are totally
dependent on your explanation. We only know what you tell us. Some users worry
they have not provided enough information when they file a ticket. In most cases,
providing the information for these five items is sufficient. If more information is
required, you may see questions posted to your bug report.

Additional Information

Please do not think you are unable to file your bug ticket without additional
information. Providing the listed information above is the most important information
for contributors to know. Providing logs does not help as much as those five pieces
of information. In some cases, only providing logs to an otherwise empty bug report
results in our being unable to resolve your issue.

Additionally useful information may include:

● Screen captures of the error. ​Lumina Screenshot​ is a useful tool to quickly

screenshot any errors in progress.
● Command Line Output Logs
● Truss Logs
● Debugger Backtrace Logs
After describing the issue, click ​Submit new issue​ to create the issue. The bug
tracker attaches a unique number to the report and sends update messages to your
registered email address whenever activity occurs with the bug report.

7.4.2. Become a Beta Tester

If you enjoy tinkering with operating systems and have a bit of spare time, one of the
most effective ways to assist the TrueOS​®​community is reporting problems you
encounter while using TrueOS​®​.

If a spare system or virtual machine is available, you can also download and test the
latest UNSTABLE patches (see ​Updating TrueOS​). Having as many people as
possible using TrueOS​®​ on many different hardware configurations assists the
Project in finding and fixing bugs. The end result is more polished and usable OS for
the entire community.

If you wish to become a tester, join the Telegram ​TrueOS Community channel​.
Updates are typically announced announced here. You can also see any problems
other testers are finding and can check to see if the problem exists on your hardware
as well.

Anyone can become a beta tester. If you find a bug while testing, be sure to
accurately describe the situation when ​Reporting a bug​ so it can be fixed as soon as
possible.

7.4.3. Translation
If interested in translating TrueOS​®​ into your native language, start by choosing
which of the three translation areas to work in:

1. Translate the graphical menus within the TrueOS​®​ operating system.

2. Translate the documentation published with TrueOS​®​.
 3. Translate the TrueOS​®​ website.

This section describes each of these translation areas in more detail and how to
begin as a translator.

Regardless of the type of desired translation, you should first join the ​TrueOS
Community channel​. The first time joining the channel, introduce yourself and
indicate which language(s) and which type(s) of translations you can assist with. This
allows you to meet other volunteers and stay informed of any notices or updates
affecting translators.

7.4.3.1. Interface Translation

TrueOS​®​ uses ​Weblate​ for managing localization of the menu screens used by the
installer and the TrueOS​®​ utilities. Weblate makes it easy to find out if your native
language has been fully localized for TrueOS​®​. It also makes it easy to verify and
submit translated text, as it provides a web editor and commenting system. This
means translators can spend more time making and reviewing translations rather
than learning how to use a translation tool.

To assist with a localization, open the ​TrueOS® translation projects​ in a web

browser. An example is seen in ​Figure 7.4.2​.
Fig. 7.4.2 TrueOS​®​ Weblate Translation System

Before editing a translation, first create a a login account and verify the activation
email. Once logged in, click ​Manage your languages​, shown in ​Figure 7.4.3​.

Fig. 7.4.3 Weblate Dashboard

In the screen shown in ​Figure 7.4.4​, use the ​Interface Language​ drop-down
menu to select the language for the Weblate interface. Then, in ​Translated
languages​, use the ​arrows​ to add or remove the languages you wish to
translate. Once any selections are made, click ​Save​.
 Fig. 7.4.4 Manage Languages

Note

If the language you wish to translate is missing from the “Translated languages”
menu, request its addition in the ​TrueOS Community channel​.

Next, click ​Projects​ at the top of the screen to select a localization project. In the
example shown in ​Figure 7.4.5​, the user has selected the ​trueos-utils-qt5​ project,
which represents the localization of the TrueOS​®​ graphical interface. This screen
shows the components of the project and the current progress of each component’s
translation. The green bar indicates the localization percentage. If a component is
not at 100%, this means its untranslated menus will instead appear in English.
Fig. 7.4.5 Project Selection

To start translating, click a component name. In the screen shown in ​Figure 7.4.6​,
select a language and click ​Translate​.

Fig. 7.4.6 Translation Languages

In the example shown in ​Figure 7.4.7​, the user has selected to translate the
pc-installgui​ component into the Spanish language. The English text is displayed in
the ​Source​ field and the translator can type the Spanish translation into the
Translation​ field. Use the ​arrows​ near the ​Strings needing action​ field to
navigate between strings to translate.

Fig. 7.4.7 Translation Editor

If assistance is needed with either a translation or the Weblate system, ask for help
in the ​TrueOS Community channel​.

7.4.3.2. Documentation Translation

The source for the TrueOS​®​ Users Handbook is stored in the ​TrueOS® github
repository​. This allows the documentation and its translations to be built with the
operating system. Documentation updates are automatically pushed to the TrueOS​®
website and, when the system is updated using the SysAdm​™​ ​Update Manager​, the
doc updates are installed to a local copy
 named​/usr/local/share/trueos/handbook/trueos.html​. This keeps an
updated local copy of the handbook available on every user’s system.

The TrueOS​®​ build server provides the HTML version of the TrueOS​®​ Users
Handbook. Instructions for building your own HTML, PDF, or EPUB version can be
found in this ​README.md​.

The documentation source files are integrated into the Weblate translation system so
the TrueOS​®​ documentation can be translated using a web browser. The process is
similar to ​Interface Translation​ except ​trueos-guide​ must be selected from the
Projects​ drop-down menu shown in ​Project Selection​.

It is important to be aware of a few elements when translating the documentation:

At this time, some formatting tags are still displayed in raw text, as seen in the
examples in ​Figure 7.4.8​ and ​Figure 7.4.9​.

Danger

Do not remove the formatting as this can break the documentation build for that
language.

In ​Formatting Characters - Do Not Remove​, it is fine to translate the phrase “Using

the Text Installer”, but care must be taken to avoid removing any of the surrounding
colons and backticks, or to change the text of the ​ref​ tag. In ​More Formatting
Characters​, the asterisks are used to bold the words ​bare minimum​. It is fine to
translate ​bare minimum​, but do ​not​ remove the asterisks.
Fig. 7.4.8 Formatting Characters - Do Not Remove

Fig. 7.4.9 More Formatting Characters

To build a local HTML copy that includes the latest translations, either for personal
use or to visualize the translated Guide, type these commands from the command
line in TrueOS​®​:

sudo pkg install trueos-toolchain

rehash
git clone git://github.com/trueos/trueos-docs
cd trueos-docs/trueos-handbook
sudo make i18n
make html
ls _build
doctrees html-es html-tr trueos-handbook-i18n.txz
html html-fr html-uk
html-da html-id locale
html-de html-pt_BR locale-po

This makes an HTML version of the Guide for each of the available translations. In
this example, translations are available for English (in ​html​), Danish, German,
Spanish, French, Indonesian, Brazilian Portuguese, Turkish, and UK English. To
update the HTML at a later time:

cd ~/trueos-docs
git pull
cd trueos-docs/trueos-handbook
sudo make i18n
sudo make html

7.4.3.3. Website Translation

If you are interested in translating the TrueOS​®​ website, introduce yourself in the
TrueOS Community channel​ or open a new topic in our ​Discourse forum

Currently, the website is being translated into several languages, including: Dutch,
French, German, Polish, Spanish, Swedish, and Turkish.
 7.4.4. Development
If you like programming, and especially coding on FreeBSD, we would love to see
you join the TrueOS​®​ team as a TrueOS​®​contributor. Developers who want to help
improve the TrueOS​®​ codebase are always welcome! To participate in core
development, introduce yourself in the ​TrueOS® Discourse forum​. Feel free to
browse the ​Issues​ in the ​TrueOS® repository​. If you see something you want to
work on, or have a proposal for a project to add to TrueOS​®​, mention it and
someone will be happy to help you get started.

Most of the TrueOS​®​ specific GUI tools are developed in C++ using Qt libraries and
other non-GUI development is done using standard Bourne shell scripts. There may
be cases where other languages or libraries are needed, but those are evaluated on
a case-by-case basis.

7.4.4.1. Getting the Source Code

The TrueOS​®​ source code is available from ​GitHub​. The code is organized into
repositories which represent the Lumina​®​desktop, the graphical utilities, SysAdm​™​,
and various other applications. ​git​ needs to be installed in order to download the
source code. When using TrueOS​®​, ​git​ is included in the base install.

To download the source code, ​cd​ to the directory to store the source code and
specify the name of the desired repository. In this example, the user is downloading
the source for the graphical utilities:

~% cd Projects
~/Projects% git clone git://github.com/trueos/trueos-utils-qt5

This creates a directory with the same name as the repository.

Note
To keep the local copy in sync with the official repository, periodically run ​git pull
within the directory.

Before compiling any source, ensure the Ports Collection is installed. At this time, ​git
is used to fetch and update ports (see​FreeBSD Ports​).

Fetching ports for the first time (as root):

# git clone http://github.com/trueos/freebsd-ports.git /usr/ports

Update an existing ​ports​ directory (as root):

# cd /usr/ports

# git pull

Then, ​cd​ to the directory containing the source to build and run the ​mkport.sh
script. In this example, the developer wants to compile the graphical utilities:

cd trueos-utils-qt5

./mkport.sh /usr/ports/

This creates a port which can then be installed. The name of the port is located in
mkport.sh​. This example determines the name of the port directory, changes to it,
and then builds the port. Since this system is already running the TrueOS​®​ graphical
utilities, ​reinstall​ is used to overwrite the current utilities:

grep port= mkport.sh

port="sysutils/trueos-utils-qt5"
cd /usr/ports/sysutils/trueos-utils-qt5
make reinstall

If you plan to make source changes, several Qt IDEs are available in the SysAdm​™
AppCafe​. The ​QtCreator​ application is a full-featured IDE designed to help new Qt
users get up and running faster while boosting the productivity of experienced Qt
developers. ​Qt Designer​ is lighter weight as it is only a ​.ui​ file editor and does not
provide any other IDE functionality.

If planning to submit changes for inclusion in TrueOS​®​, fork the repository using the
instructions in ​fork a repo​. Make your changes to the fork, then submit them by
issuing a ​git pull request​. Once your changes have been reviewed, they can either
be committed or returned with suggestions for improvement.

7.4.4.2. Design Guidelines

TrueOS​®​ is a community driven project relying on the support of developers in the
community to help in the design and implementation of new utilities and tools for
TrueOS​®​. The project aims to present a unified design so programs feel familiar to
users. As an example, while programs could have ​File​, ​Main​, or ​System​ as their
first entry in a menu bar, ​File​ is used as the accepted norm for the first category on
the menu bar.

This section describes a small list of guidelines for menu and program design in
TrueOS​®​.

Any graphical program that is a fully featured utility, such as ​Life Preserver​, should
have a ​File​ menu. However, file menus are not necessary for small widget programs
or dialogue boxes. When making a file menu, a good rule of thumb is ​keep it simple​.
Most TrueOS​®​ utilities do not need more than two or three items on the file menu.
Configure​ is our adopted standard for the category containing settings or
configuration-related settings. If additional categories are needed, check to see what
other TrueOS​®​ utilities are using.

File menu icons are taken from the ​KDE Oxygen​ or ​material-design​ themes located
in ​/usr/local/share/icons/oxygen​. Use these file menu icons so there are
not too many different icons for the same function. ​Table 7.4.1​ lists some commonly
used icons and their default file names.

Functio File Menu Icon File Name

n

Quit row 1, cell 2 window-close.png

Settings row 2, cell 2 configure.png

TrueOS​®​ utilities use these buttons:

● Apply:​ Executes settings changes and leaves the window open.

● Close:​ Exits program without applying settings.
● OK:​ Closes dialogue window and saves settings.
● Cancel:​ Closes dialog window without applying settings.
● Save:​ Keeps the current settings and closes the window.

Fully functional programs like ​Life Preserver​ do not use close buttons on the front of
the application. Basically, whenever there is a ​File​ menu, that and an ​x​ in the top
right corner of the application are used instead. Dialogues and widget programs are
exceptions to this rule.

Many users benefit from keyboard shortcuts and we aim to make them available in
every TrueOS​®​ utility. Qt makes it easy to assign keyboard shortcuts. For instance,
to configure keyboard shortcuts for browsing the ​File​ menu, put ​&File​ in the text slot
for the menu entry when making the application. Whichever letter has the ​&​ symbol
in front of it becomes the hot key. You can also make a shortcut key by clicking the
menu or submenu entry and assigning a shortcut key. Be careful not to duplicate hot
keys or shortcut keys. Every key in a menu and submenu should have a key
assigned for ease of use and accessibility. ​Table 7.4.2​ and ​Table 7.4.3​ summarize
the commonly used shortcut and hot keys.

Shortcut Key Actio

n

CTRL + Q Quit

F1 Help

Hot Action
Key

Alt + Q Quit

Alt + S Settings

Alt + I Import

Alt + E Export

ALT +
File Menu
F
 ALT +
Configure Menu
C

ALT +
Help Menu
H

When saving an application’s settings, use the ​QSettings​ class whenever possible.
There are two different ​organizations​, depending whether the application is running
with ​root​ or ​user​ permissions. Use ​TrueOS​ as the ​organization​ for applications which
run with user permissions and ​TrueOS-root​ for applications which are started with
root permissions via ​sudo​. Proper use prevents the directory where settings files are
saved from being locked down by ​root​ applications, allowing user applications to
save and load their settings. Examples ​1​ and ​2​ demonstrate how to use the
QSettings​ class for each type of permission.

Example 1: User Permission Settings

(user application - C++ code):

QSettings settings("TRUEOS", "myapplication");

Example 2: Root Permission Settings

(root application - C++ code):

QSettings settings("TRUEOS-root", "myapplication");

These resources are also helpful for developers:

● Qt 5.4 Documentation
● C++ Tutorials

7.4.5. Documentation
 TrueOS​®​ is always looking for documentation contributions from its users. The
project currently has a large amount of documentation, and the community is
instrumental in keeping the information up to date and providing tips and instructions
to solve specific problems. However, the sheer amount of documentation available
coupled with the specific documentation tools can make contributing appear
daunting. Actually, the reverse is true: ​contributing to the documentation is easy!

7.4.5.1. Make a Simple Documentation Change

Tip

These instructions are for simple modifications of the TrueOS​®​ handbook, but they
also apply to the Lumina​®​ and SysAdm​™​documentation! Lumina​®​ documentation
lives in the ​lumina-docs​ repository and SysAdm​™​ guides are in ​sysadm-docs​.

Making a documentation change can be as simple as using a web browser. A

GitHub account is required to submit patches to TrueOS​®​, so open a web browser
and log in to GitHub. Making an account is also a simple process, but be sure to use
an often checked email address, as all communication regarding patches and pull
requests are sent to this address.

Navigate to the ​trueos-docs​ GitHub repository. Click on the ​trueos-handbook

directory to view all the documentation files. Open the ​.rst​ file corresponding to the
chapter needing an update. The chapter names are reflected in the title of the
.rst​files. ​Figure 7.4.10​ shows the trueos-docs repository and the contents of the
trueos-handbook​ directory.
 Fig. 7.4.10 Contents of ​trueos-handbook

Open the desired chapter file by clicking its entry in the list.

Tip

trueos.rst​ is the primary index file and should be ignored.

Begin editing the file by clicking the ​Pencil​ icon in the upper right corner above the
file’s text. The file moves to ​edit​ mode, where it is now possible to make any
necessary changes, as ​Figure 7.4.11​ shows.
 Fig. 7.4.11 Editing ​install.rst​ with GitHub

If making a simple change, it is recommended to avoid adjusting the specific

formatting elements and instead work within or around them.

Once satisfied, scroll to the bottom of the page and write a detailed commit summary
of the new changes. Click ​Propose file change​ (green button), then ​Create
pull request​ to submit the changes to the project. GitHub then does an automated
merge check. Click ​Create pull request​ again to submit the change to the
repository. The final step is for a developer or project committer to review the
changes, merging or asking for more changes as necessary.

Tip

Housekeeping: Once the pull request is merged, delete the now obsolete patch
branch.

7.4.5.2. Advanced Documentation Changes

Note

These instructions are designed for users running TrueOS​®​. Actual commands and
workflow may change when using a different operating system.

Advanced changes to the TrueOS​®​ documentation require an understanding of the

underlying tools and markup language. This section covers downloading and
installing the required tools and source files to build a local copy of the
documentation. It also discusses the reStructured Text markup language and some
of the specific conventions TrueOS​®​ uses in its documentation. It is recommended
the contributor be familiar with using TrueOS and/or FreeBSD before following these
instructions.

Required Applications

There are a few packages to install before making a local copy of the documentation.
Sphinx and its relevant extensions are the most important.

Open AppCafe​®​ or a command-line and download the ​py27-sphinx​ package:

[user@example] sudo pkg install py27-sphinx

Press ​y​ if prompted to continue installing the package. Next, install the
py27-sphinxcontrib-httpdomain​ package:

[user@example] sudo pkg install py27-sphinxcontrib-httpdomain

Be sure ​git​ is installed. TrueOS​®​ installs this by default. A GitHub account is also
required to follow these instructions. Open a web browser pointed to
https://github.com/​ to create an account.
 The last critical item to have on hand is a configurable text editor. The ​Lumina Text
Editor​ is a simple plaintext editor built in to TrueOS​®​ which works very well when
editing ​.rst​ files, but other editors like ​kate​ and ​scite​ also function well.

Preparing a local copy of the GitHub repository

Once ready with Sphinx and extensions installed, navigate to the ​trueos-docs
repository and ​fork​ it by clicking the ​Fork​ button in the upper-right corner of the
repository. This creates a copy of the repository on the user’s personal GitHub
account, allowing the user to create patches and submit pull requests to the
upstream​ (or ​base​) repository.

Now there are two repositories to track on GitHub, the primary ​trueos-docs​ and
the user’s forked version on their personal account.

In the command line, use ​git clone​ to clone the ​forked​ repository:

[user@example] git clone

https://github.com/[github_user]/trueos-docs.git

cd​ into the newly downloaded ​/trueos-docs/​ directory to continue configuring

this cloned repo.

Set up the local clone of the ​forked​ repository to point to the ​upstream​ repository:

Tip

GitHub also documents this procedure in two steps: ​Configuring a remote for a fork
and ​Syncing a fork​.

[user@example] ~/trueos-docs% git remote -v

origin https://github.com/[github_user]/trueos-docs.git (fetch)
 origin https://github.com/[github_user]/trueos-docs.git (push)
[user@example] ~/trueos-docs% git remote add upstream
https://github.com/trueos/trueos-docs.git
[user@example] ~/trueos-docs% git remote -v
origin https://github.com/[github_user]/trueos-docs.git (fetch)
origin https://github.com/[github_user]/trueos-docs.git (push)
upstream https://github.com/trueos/trueos-docs.git (fetch)
upstream https://github.com/trueos/trueos-docs.git (push)

This configuration allows changes made in a fork to be synced to the original

repository and changes in the original synced to the fork:

[user@example] ~/trueos-docs% git fetch upstream

[user@example] ~/trueos-docs% git merge upstream/master
[user@example] ~/trueos-docs% git push origin master

One last element to configure is to set the account identity:

[user@example] ~/trueos-docs% git config --global user.email "[you@example.com]"

[user@example] ~/trueos-docs% git config --global user.name "[Your Name]"

This sets the ​global​ user name and email for ​git​. Remove ​–global​ from the
command to set the value only for the ​trueos-docs​project directory.

Tip

It can be very useful to have two local copies of the documentation. One to pull in
changes from “upstream” and one to make local changes and build test. This helps
prevent merge conflicts where the local changes accidentally override brand new
patches added to the upstream repository.

Basic Git commands

 Once the local ​trueos-docs​ copy is configured, there are a few general ​git
commands to remember when working in the directory:

● git pull​: Update the local copy from the forked GitHub repository.
● git add [path/to_file]​: Designate a local file to stage for commit to the
forked repository.
● git status​: Display a message showing what is staged for commit and
other relevant information.
● git commit​: Create a patch for the forked repository. Writing a commit
message describing the changes is always recommended.
● git push​: Send the patch created using ​git commit​ upstream to the user’s
forked repository.

GitHub provides a variety of ​introductory guides​ for users new to its unique workflow.
It is recommended to use these guides if confused about any stage of the
commit/push/pull request process.

Sphinx Structure

TrueOS​®​ uses the ​Sphinx Documentation Generator​ for all its documentation.
Sphinx uses ​reStructuredText​ source files to generate a variety of output formats,
including HTML, LaTeX, and ePub. The Sphinx builder also tests the markup as it
builds, notifying the user of errors and approximate locations in the file. Sphinx also
supports numerous extensions and customizable elements, including the output
theme, configuration file, and other open-source options.

Note
The ​Sphinx Project documentation​ is very robust and is recommended to browse or
reference it when making advanced changes to the TrueOS​®​ documentation. The
Sphinx ​reStructuredText Primer​ is also highly recommended.

The TrueOS​®​ implementation of Sphinx uses a few management files and

directories to handle and build the ​.rst​ source files:

● trueos.rst​: The master index file for the handbook. This file governs how
the Table of Contents is constructed and which​.rst​ files to include when
starting a build.
● conf.py​: The Python configuration file for the Sphinx project. After the
initial setup and some customization, this file is generally static.
● images​ directory: All images used in the documentation are stored in this
directory. Every image is ​.png​ format, and adding or removing an image
to this directory requires updating the
trueos-docs/port-files/pkg-plist​ file.
● themes​ directory: Houses the currently used ​trueos_style​ theme. This
theme includes ​html​, ​.js​, and ​.css​ files, plus a custom font. These files
govern how the documents look after an ​html​ build.
● Makefile​: This file houses all the specific Sphinx ​make​ commands.

Documentation Workflow

Once all the repository forking and configuration is done, the actual workflow to
make and submit documentation changes is straightforward:

● cd​ into the local copy: ​[user@example] ~% cd

/trueos-docs/trueos-handbook
● Use ​git pull upstream master​ to download any changes from the
upstream repository. Then type ​git merge upstream/master​to add those
changes to the local copy of the forked repository. Finally, use ​git push
 origin master​ sync these changes from the upstream repository the
online forked repository.
● Make any changes to the ​.rst​ files using a plaintext editor.
● Build test the changes with ​make html​. The builder output posts
messages if any errors are detected. The built ​html​ files are viewable by
opening them in a web browser:​[user@example]
~/trueos-docs/trueos-handbook% firefox
_build/html/trueos.html &
● Clean the ​_build​ directory with ​make clean​. The contents of this
directory are not needed in the online repositories, only when conducting
build tests.
● Stage a changed file for commit with ​git add [path/to_file]​.
● Continue changing, testing, and staging files as desired, then make the
patch to push to the online forked repository with ​git commit​. Be sure to
add a descriptive commit message about the changes.
● git push origin master​ to send the patch to the online forked repository.
● Open a browser and navigate to the forked ​trueos-docs​ repository.
Look for the message saying “This branch is 1 commit ahead of
trueos:master” and click the ​Pull request​ button on the same line.
GitHub checks if the branches can be automatically merged, displaying a
green checkmark​ if everything looks good. Click ​Create pull request​,
add any more details to the commit message, if necessary, then click
Create pull request​ again.
● Finished! The patch is submitted for a developer or project maintainer to
review and merge.

Update translation files

Once the initial patch is submitted, it is recommended to submit another patch to

update the translation files:

● cd​ into the local copy and run ​make i18n​.

 ● Once the command is finished, type ​make clean​. This removes a number
of unnecessary files. Type ​git status​ to view the newly updated translation
files.
● Commit all these files to a patch with ​git commit -a​. Use the same commit
message as the last non-translation change, but add ​:TRANSLATIONS​ to
the title. This allows the project contributors to more easily track when and
which translation files are updated.
● Follow the same ​git push​ and GitHub website instructions listed above to
submit the patch to the upstream repository.

7.4.5.3. Documentation Conventions

This section is intended to provide references for the specific conventions of
TrueOS​®​ documentation. ​Table 7.4.4​ provides specific conventions of the TrueOS​®
project:

Tip

It is also recommended to open one of the handbook ​.rst​ files for reference.

Conventio Description Exceptions/Examples

n

70
Certain elements like a
character Start a new line every 70 characters.
long link or code block.
lines

Archive old Replaced images are moved to the

N/A
images archived_images​ directory.

PNG
All images are in the ​.png​ format. N/A
images
 Update ​port-files/pkg-plist
Update plist whenever the​images/​ directory is N/A
changed.

Empty lines and at the

Whitespace Remove any unnecessary whitespace.
end of lines.

Graphical elements: buttons, icons,

guilabel Click ​Ok
fields, columns, and boxes.

menuselecti
Menu selections and paths Select ​Foo ‣ Bar
on

command Commands Use the ​lcp​ command

Locate the
file File, volume, and dataset names
/etc/rc.conf​ file.

kbd Keyboard keys Press the ​Enter​ key.

Bold Important points This is important.

Device names or values entered into Enter ​127.0.0.1​ in the

Italic
fields address field.

[user@samp] ~% ls
samp Command line representations
/etc

code-block Multi-line code examples. .. code-block:: json

External Hyperlink to website outside the built

Check ​Google
links documentation.
 Internal Hyperlink to an internal section of the
See ​Documentation
Links documentation

Table 7.4.5​ provides a basic reference for some of the often used elements of the
reStructuredText markup language. See the​Sphinx reStructuredText Primer​ for a
more complete reference.

Markup Description
Type

Test separated by one or more blank lines. All lines of the same
Paragraph
paragraph must be left-aligned to the same level of indentation.

Inline One asterisk around text is ​italics​.

Inline Two asterisks around text is ​bold​.

Inline Two backquotes around text is a code sample.

Inline role Interpreted text roles: syntax is ​:rolename:`content`​.

Bullet List Use ​*​ for bullet list entries.

Number List Use ​1.​, 2

​ .​, … for a numbered list.

Nested List Nested lists are separated from the parent items by blank lines.

Quoted par. Add indentation.

Line blocks Use ​|​ on the left side to preserve a quote’s line breaks.
 Start line with ​..​ and a whitespace. End the comment by adding an
Comment empty line, then starting the next line at the same level of
indentation.

Escape Use a ​\​ (backslash).

Tables

Tables are all built as grid tables. Here is an example table to copy, paste, and
rework when necessary:

+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+

Images

Images are referenced using the numref role and internal marker:

:numref:`Image %s <example1>` is the example syntax to introduce a

new image.

.. _example1:
.. figure:: images/example1.png
:option: [value]

Caption for Example1.png

Admonition Boxes
 These are the specific admonition boxes used by TrueOS​®​ documentation:

Tip

A trivial shortcut or efficiency.

Note

Useful information or reminder for accurate command use.

Warning

Caution about potential problems introduced by the procedure or its misuse.

Danger

Extreme caution. Data loss or system damage can occur.

7.4.6. Advocacy
Love TrueOS​®​? Why not tell your family, friends, fellow students and colleagues
about it? You are not the only individual who prefers a virus-free, feature-rich, and
no-cost operating system. Here are some suggestions for getting started:

● Burn a couple of DVDs and give them away.

● Consider giving a presentation about TrueOS​®​ at a local community event,
conference, or online. Let us know about it through our ​The TrueOS®
Community​ channels and we can help spread the word!
● Write a personal blog detailing your journey from your first TrueOS​®​ install
experience to your most recent accomplishment. The blog could also be
used to teach or explain how to perform tasks on TrueOS​®​. A regional
 language blog may help build the community in your area and to find
others with similar interests.

7.5. Additional Resources

Need more information? A number of useful resources that may aid in using
TrueOS​®​ are available.

7.5.1. FreeBSD Handbook and FAQ

TrueOS​®​ uses FreeBSD as its underlying operating system, so nearly everything in
the ​FreeBSD Handbook​ and ​FreeBSD FAQ​applies to TrueOS​®​ as well. Both
documents are comprehensive and cover nearly every possible task to accomplish
on a FreeBSD system. They are also an excellent resource for learning how things
work under the hood of a TrueOS​®​ system.

Note

Some configurations described in the FreeBSD Handbook already “just work” on a

TrueOS​®​ system as they have been pre-configured. In these instances, reading the
FreeBSD Handbook section can help to learn how the system is configured and why
it works.

7.5.2. Search and Portals

Many BSD related search portals exist. If unable to find an answer from the forums
or mailing lists, try searching these websites:

● The OpenDirectory
● FreeBSD Search​ (includes mailing list archives, man pages, and web
pages)
● FreeBSD News
● About BSD
● BSD Guides
 ● Slashdot BSD
● DistroWatch
● LinuxBSDos

7.5.3. More Resources

Many BSD sites and resources may also contain useful information:

● The FreeBSD Diary

● TrueOS® YouTube channel
● BSD YouTube channel
● BSD Talk
● BSD Now
● BSD Magazine​ (free, monthly download)
● FreeBSD Journal​ (bi-monthly magazine)
● BSD Hacks​ (book)
● The Best of FreeBSD Basics​ (book)
● Definitive Guide to PC-BSD®​ (book)

ZFS Resources

● ZFS Evil Tuning Guide

● FreeBSD ZFS Tuning Guide
● ZFS Best Practices Guide
● ZFS Administration Guide
● Becoming a ZFS Ninja (video)
● Blog post explaining how ZFS simplifies the storage stack
8. Appendix A: Conventions & Legal
This section contains the necessary legal information. It also contains a helpful table

to understand some of the conventions used throughout this document.

8.1. Typographic Conventions

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

Item Visual Example

Graphical elements:
buttons, icons, fields, Click the ​Import CA​ button.
columns and boxes

Menu selections Click ​System ‣ Information​.

CLI Command name Use ​scp​.

A command line
[tmoore@example] ls /etc
example

Files, volume and

dataset names, and Locate the ​/etc/rc.conf​ file.
directories
 Keyboard keys Press the ​Enter​ key.

Important points This is important.

Values entered into

Enter ​127.0.0.1​ in the address field.
fields, or device names

8.2. Copyright & Trademarks

Copyright © 2005-2017, iXsystems

The TrueOS​®​ User Guide is freely available for sharing and redistribution under the
terms of the ​Creative Commons Attribution License​. This means you have
permission to copy, distribute, translate, and adapt the work, as long as you attribute
the TrueOS​®​Project as the original source of the Guide.

TrueOS​®​ and the TrueOS​®​ logo are registered trademarks of ​iXsystems​. To use the
TrueOS​®​ logo in your own works, please ask for permission first from
marketing@ixsystems.com​.

Lumina​®​ and the Lumina​®​ logo are registered trademarks of ​iXsystems​. To use the
Lumina​®​ logo in your own works, please ask for permission first from
marketing@ixsystems.com​.

SysAdm​™​ is a trademark of ​iXsystems​.

TrueOS Pico​®​, Pico Server​®​, and Pico Client​®​ are trademarks of ​iXsystems​.

AMD is a trademark of Advanced Micro Devices, Inc.

Apache is a trademark of The Apache Software Foundation.

AppCafe​®​ is a registered trademark of ​iXsystems​.

Asus® and Eee PC® are registered trademarks of ASUSTeK® Computer Inc.

Facebook® is a registered trademark of Facebook Inc.

Flash® is a registered trademark of Adobe Systems Incorporated in the United

States and/or other countries.

FreeBSD® is a registered trademark of the ​FreeBSD Foundation​.

FreeNAS​®​ is a registered trademark of ​iXsystems​.

Intel, the Intel logo, Pentium Inside, and Pentium are trademarks of Intel Corporation
in the U.S. and/or other countries.

Java™ is a trademark of Oracle America and/or its affiliates in the United States and
other countries.

LinkedIn® is a registered trademark of LinkedIn Corporation.

Linux® is a registered trademark of Linus Torvalds.

Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other
countries.

NVIDIA® is a trademark and/or registered trademark of NVIDIA Corporation in the

U.S. and other countries.

ThinkPad® is a registered trademark of Lenovo.

Twitter is a trademark of Twitter, Inc. in the United States and other countries.
UNIX® is a registered trademark of The Open Group.

VirtualBox® is a registered trademark of Oracle.

VMWare® is a registered trademark of VMWare, Inc.

Windows® is a registered trademark of Microsoft Corporation in the United States

and other countries.

8.3. Ethical Advertising Policy

For many years, users have wanted to give back to the TrueOS​®​ project. Generally,
we encouraged users to donate or actively contribute to the FreeBSD project to
ensure FreeBSD continues to be successful in the future. Because TrueOS​®​ is open
source software, we have included a minimal number of ads as a simple method for
users to give back to the project, if they wish.

The primary consideration for these ads is to avoid detracting from the user
experience as much as possible. To this end, any ads in the Handbook will be limited
to the navigation sidebar, and only in a predefined space underneath all other
navigation options. We are resolved to protect user privacy and security, and do not
collect user information, with the exception of click-throughs. Furthermore, we do not
collect any data for targeted ads, and are committed to only show high quality ads
pertaining to our user base.

Cookie Policy

Clicking on a Newegg ad directs users through an affiliate link that gives the
TrueOS​®​ project a modest commission based on any items purchased within 24
hours. This is a simple time tracking cookie used to ensure the TrueOS​®​ project is
afforded its commission. To ask questions about our Ethical Advertising policy,
please contact ​joshms@trueos.org​ for more information.