Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Handbook
1. Introduction
Written by users of the TrueOS® operating system. Maintained and edited by Dru
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.
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
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
While started as an independent project, TrueOS® has been financially backed and
October 2006.
1.1. Features
TrueOS® provides many features:
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:
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.
Term Description
A form of RAID where all data is mirrored onto two or more disks,
Mirror
creating a redundant copy should a disk fail.
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.
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
● 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.
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.
Note
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
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
Note
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.3provides some common examples:
In TrueOS®, the
directories containing
the startup scripts do
/etc/init.d/ for operating
not link to runlevels as
system rc0.d/, r c1.d/,
there are no runlevels.
and/usr/local/etc/init.d/ etc.
System startup scripts
for applications
are separated from
third-party application
scripts.
Terminals configured in
ttys and rc.conf indicate
/etc/ttys and /etc/rc.conf 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
There are many articles and videos which provide additional information about some
of the differences between BSD and Linux:
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.
Here are a few resources that go into greater detail examining the differences
between Windows and BSD:
1.3. Virtualization
A virtualized environment allows a user to test drive an operating system without
overwriting the current operating system. This is an excellent way to practice
installation, determine whether the hardware is supported, or to try multiple versions
of different operating systems. Virtualization software creates a virtual machine,
which is essentially a computer environment created entirely in software that allows
the installation and use of an operating system. The only limitation to virtualization is
the hardware, as each virtual machine uses real resources, the CPU and RAM.
Depending on the amount of CPU and RAM available on the host computer, the
operating system installed as a guest in the virtual environment may run slowly. If the
host computer slows down, closing other non-essential applications to free up
CPU/RAM may help.
1.3.1. bhyve
bhyve (pronounced bee hive) is a type-2 hypervisor that runs natively on TrueOS®
and originally developed on FreeBSD. bhyve runs FreeBSD 9+, OpenBSD, NetBSD,
Linux, and Windows guests. Current development efforts aim at widening support for
other operating systems for the x86-64 architecture. The FreeBSD Handbook
Virtualization section has in-depth instructions about bhyve features and use. bhyve,
while very powerful, is still under active development and may not have a complete
user experience yet.
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
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.
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
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 Storagehyperlink 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).
Before beginning, there are a few things to check to ensure the system is ready 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 notneed to be manufactured by AMD in
order to be supported. Even 64-bit Intel CPUs are sometimes referred to as amd64.
TheFreeBSD 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®:
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:
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 theDisk 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
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.
● .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.
Note
Only one of the checksums needs to be verified. The TrueOS website lists .MD5,
SHA256, and .SIG files. The TrueOS websitehas 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.
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
To use the OpenPGP .sig file, use your preferred utility to verify the signature. The
OpenPGP website has numerous recommendations for verification utilities.
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
Linux or
Brasero
*BSD
FreeBSD/P
C-BSD/True growisofs
OS
● 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:
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 .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
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
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
theLanguage 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
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, whenLogging 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.
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.
Note
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.
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.
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.
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.
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.
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.
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
Note
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
Modescreen and select GPT (Best for new hardware). Once that box is
checked, input a strong passphrase twice into the Passwordfields. It is
recommended to create a long and memorable password, but something difficult to
guess.
Danger
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.
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.
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.
rEFInd displays any installed operating systems, booting into the default choice after
a few seconds. Press any key other thanEnter 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.
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.
Tip
The first time the system boots, no additional environments are available. This menu
populates as boot environments are created.
● 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.
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.
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 theDisplay Settings screen in order for the
user to select another driver. Once satisfied with the settings, click Yes when
prompted to accept them.
Note
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:
Once the selection is made, click Next to move to the next configuration screen.
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.
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.
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 onPEFS 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
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.
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.
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.
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.
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.
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.
The toolbar across the bottom of the screen allows several options to be selected on
a per-login basis:
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
Once any selections are made, input the password associated with the selected user
and press Enter or click the blue arrowto login.
3. Dual Boot
This chapter discusses the necessary steps to dual boot.
Warning
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
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.
● An EFI or UEFI partitioning scheme. TrueOS® does not support the older
MBR partition scheme, opting instead to use rEFIndfor 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.
Note
Danger
Once installed, the system boots into the rEFInd menu seen in Figure 3.3.1.
rEFInd displays any installed operating systems and boots into the default choice
after a few seconds. Press any key other thanEnter 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
If the intent is to install a graphical desktop using the graphical installer, refer instead
For a server installation, using the TrueOS® installer rather than the FreeBSD
installer offers several benefits:
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.
Use the Network Interface drop-down menu to choose the desired interface:
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.
If installing the server to a system with ZFS already installed, you can choose to
Install to disk or Install into boot Environment.
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 Noto 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.
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 Restoreshown 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.
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.
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.
“fresh”, “upgrade”,
installMode= sets the installation type
“extract”, or “zfsrestore”
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)
defaults to “round-robin” if
“load”, “prefer”,
mirrorbal= the mirrorbal method is not
“round-robin”, or “split”
specified
location of directory
localPath= /path/to/files
containing installation files
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.
location of customized
pc_config URL or /path/to/file
pc-sysinstall.conf
running a shutdown is
shutdown_cm recommended, but this can be any
e.g. shutdown -p now
d command/script to execute
post-install
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
Alternately, if an installation CD or DVD is inserted, mount the media and copy its
contents to the desired directory
Adding extra files may be necessary if certain variables are set in the custom
configuration file:
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
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
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.
These next sections describe each element of TrueOS® that is managed by Lumina®
and provides links to the relevant section of the Lumina handbook.
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.
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.
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.
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.
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.
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, checkAssign 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.
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.
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
●
● 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
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.
● 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, clickPublic servers to
select a public DNS server.
● IPv6 DNS 2: The IPv6 address of the secondary DNS server used on the
IPv6 network.
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.
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.
Figure 5.2.16 shows the configuration screen if Setup Access Point is selected.
Fig. 5.2.16 Access Point Basic Setup
● 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.
The settings in this screen are optional and allow for fine-tuning the access point’s
configuration:
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
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:
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® 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.
System Management
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.
http://linuxg.net/how-to-install-emelfm2-0-8-2-1-o
emelfm2 emelfm2
n-ubuntu-linux-mint-and-elementary-os/
https://projects.gnome.org/nautilus/screenshots.h
nautilus nautilus
tml
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
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.
smb4k smb4k-kde4
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
addnginx_enable="YES"
start on
bootup.
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.
Note
No OpenRC runlevels are executed if the system is booted into single-user mode
(see Figure 2.9.3.)
Note
OpenRC allows users to add services in the prefix location to the boot runlevel.
These services are started before the /usrfilesystem is mounted. Finally, there is a
shutdown runlevel reserved for a few services like savecore or pc-updatemanager,
which installs updates at shutdown.
[tmoore@Observer] ~% ls /libexec/rc/init.d/
daemons exclusive inactive scheduled starting wasinactive
depconfig failed options softlevel stopping
deptree hotplugged prefix.lock started tmp
depend() {
need net
after bootmisc
keyword -shutdown
}
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.
For more creation options for OpenRC compatible init scripts, type man
openrc-run in a CLI.
5.5.3. RC Defaults
Note
# 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"
FreeBSD RC Defaults
#!/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.
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
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
Notifies /etc/init.d/abi
linux_enable=”YES” service to enable the Linux /etc/conf.d/abi
compatability during boot
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
Note
#!/bin/sh
if [ ! -e /etc/rc.conf ] ; then
exit 0
fi
. /etc/rc.conf
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.
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}
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}
Note
#!/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
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.
% nspluginwrapper -v -a -i
In this example, Flash is configured and ready for use with the Firefox browser. To
confirm Flash is usable, open Firefox and typeabout: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 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 autounmountdservice 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 .desktopfile 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:
Note
# cd /usr/ports
# git pull
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.
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.
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
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 Devicescreen (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.
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 isXSane, 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.
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”.
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
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.
● 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 Appssection 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.
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.
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
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
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.
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.
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
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.
Tip
● 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.
Once all these components are assembled, it’s time to configure the Pico Server®.
Note
These commands will ensure the Pico Server® automatically starts and remains
active when the system is booted. Typepicoserver 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:
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
If the server does not support video acceleration or to avoid any potential security
vulnerabilities on the Pico network, editpicoserver.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.
[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.
After the .img file is written to the microSD card; connect the Pico Client® to the
Pico Server®:
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.
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.
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®.
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.
newcomers. If help is needed, there are many ways to get in touch with the TrueOS®
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:
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 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 selectshell 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.
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
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:
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:
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:
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.
My first approach was to use the SysAdm™ Client (see the Life Preserver section for
more details).
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 thelpreserver command line. So I
issued these commands:
It turned out there were a number of child sets. I logged into the FreeNAS (luna) and
issued this command as root:
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:
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, usesysctl -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:
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 theSystem 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
Environmentand 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.
Telegram maintains a full archive of the chat history. This means lengthy
conversations about hardware issues or workarounds are always available for
reference.
● 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.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:
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.
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.
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:
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.
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.
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:
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.
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.
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.
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.
If assistance is needed with either a translation or the Weblate system, ask for help
in the TrueOS Community channel.
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.
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.
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
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.
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
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 (seeFreeBSD Ports).
# 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:
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.
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.
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.
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.
● 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!
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.
Open the desired chapter file by clicking its entry in the list.
Tip
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
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.
These instructions are designed for users running TrueOS®. Actual commands and
workflow may change when using a different operating system.
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.
Press y if prompted to continue installing the package. Next, install the
py27-sphinxcontrib-httpdomain package:
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.
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:
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.
This sets the global user name and email for git. Remove –global from the
command to set the value only for the trueos-docsproject 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.
● 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.
● 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:
Tip
It is also recommended to open one of the handbook .rst files for reference.
70
Certain elements like a
character Start a new line every 70 characters.
long link or code block.
lines
PNG
All images are in the .png format. N/A
images
Update port-files/pkg-plist
Update plist whenever theimages/ directory is N/A
changed.
menuselecti
Menu selections and paths Select Foo ‣ Bar
on
Locate the
file File, volume, and dataset names
/etc/rc.conf file.
[user@samp] ~% ls
samp Command line representations
/etc
Table 7.4.5 provides a basic reference for some of the often used elements of the
reStructuredText markup language. See theSphinx 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.
Nested List Nested lists are separated from the parent items by blank lines.
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.
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:
.. _example1:
.. figure:: images/example1.png
:option: [value]
Admonition Boxes
These are the specific admonition boxes used by TrueOS® documentation:
Tip
Note
Warning
Danger
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:
Note
● The OpenDirectory
● FreeBSD Search (includes mailing list archives, man pages, and web
pages)
● FreeBSD News
● About BSD
● BSD Guides
● Slashdot BSD
● DistroWatch
● LinuxBSDos
ZFS Resources
Graphical elements:
buttons, icons, fields, Click the Import CA button.
columns and boxes
A command line
[tmoore@example] ls /etc
example
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.
TrueOS Pico®, Pico Server®, and Pico Client® are trademarks of iXsystems.
Asus® and Eee PC® are registered trademarks of ASUSTeK® Computer Inc.
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.
Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other
countries.
Twitter is a trademark of Twitter, Inc. in the United States and other countries.
UNIX® is a registered trademark of The Open Group.
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.