7. Help and Support¶
The TrueOS® Project strives to make using TrueOS® as easy as possible for newcomers. If help is needed, there are many ways to get in touch with the TrueOS® community. This chapter describes the available resources for troubleshooting TrueOS®.
As a teacher may have said, “there is no such thing as a stupid question”. However, there are ways to ensure a productive exchange for all parties involved. The two articles below describe how and why it is important to follow certain protocols when requesting help:
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.
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
to manually configure and test Xorg. Once a working configuration is
found, save it to
/etc/X11/xorg.conf. Then, remove the temporary
line shown above from
/etc/rc.conf and start PCDM with
service pcdm start.
If the graphics white-out after a suspend or resume, run
sysctl hw.acpi.reset_video=1 as the superuser.
If the problem is fixed, carefully add
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
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.
Installing TrueOS® is usually very simple. However, sometimes problems occur. This section examines solutions to the most common installation problems.
The TrueOS® installer creates a log which keeps a record of all the
completed steps, as well as any errors. When an installation error
occurs, the TrueOS® installer asks to generate an error report. If
Yes is chosen, a pop-up message asks to save the error log
to a USB stick. Type
y and insert a FAT formatted USB thumb drive
to copy the log.
While in the installer, read this log to see what went wrong. Click the
black Emergency Shell and Utilities icon, then select
shell from the |trueos| Utility Menu. Read the
log by typing
If the error can not be fixed or you believe an installation bug exists, include the log saved on the USB stick in your bug report by following the instructions in Report a bug.
If the installer does not arrive at the initial GUI installer screen, try unplugging as many devices as possible, such as webcams, scanners, printers, USB mice and keyboards. If this solves the problem, plug in one piece of hardware at a time, then reboot. This helps pinpoint which device is causing the problem.
Additionally, you may need to enable EFI in Virtualbox by navigating
Settings → System → Motherboard and checking
Enable EFI (special OSes only).
If the computer freezes while probing hardware and unplugging extra devices does not fix the problem, it is possible that the installation media is corrupt. If the Data Integrity Check on the downloaded file is correct, try burning the file again at a lower speed.
If the system freezes and the video card is suspected to be the cause, review the system’s BIOS settings. If there is a setting for video memory, set it to its highest value. Also, check to see if the BIOS is set to prefer built-in graphics or a non-existent graphics card. On some systems this is determined by the order of the devices listed; in this case, be sure the preferred device is listed first. If the BIOS settings are invisible, move a jumper or remove a battery to make it revert to the default built-in graphics; check the manual or contact the card manufacturer for details.
A common cause for problems is the LBA (Logical Block Addressing) setting in the BIOS. If the PC is not booting before or after installation, check the BIOS and turn LBA off (do not leave it on automatic).
If the SATA settings in the BIOS are set to compatibility mode, try changing this setting to AHCI. If the system hangs with a BTX error, try turning off AHCI in the BIOS.
If the USB keyboard is non-functional, check if there is an option in the BIOS for legacy support in relation to the keyboard, USB, or both. Enabling this feature in the BIOS may solve this issue.
If the installer boots and a mountroot> command prompt appears, this
may be due to a change in the location of the boot device. This can
occur when the enumeration of a card reader changes. The solution is
ufs:/dev/da1 at the prompt. Depending on the exact
location of the boot media, it may be different from
? 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.
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.
/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.
Unlike Linux interface driver names, FreeBSD/TrueOS®
interface driver names indicate the type of chipset. Each driver name
has an associated manual page where you can learn which devices use
that chipset and if there are any configuration options or
limitations for the driver. When reading the man page, do not include
the interface number. For the above example, read
man em and
/etc/wpa_supplicant.conf is used by wireless interfaces and
contains the information needed to connect to a WPA network. If this
file does not already exist, it is created when entering the
Configuration screen of a wireless interface.
The command ifconfig shows the current state of the interfaces. When reading through its output, ensure the desired interface is listed, has a status of active, and has an IP address. Here is a sample ifconfig output showing the entries for an re0 Ethernet interface and a run0 wireless interface:
re0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=389b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_UCAST,WOL_MCAST,WOL_MAGIC> ether 60:eb:69:0b:dd:4d inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 media: Ethernet autoselect (100baseTX <full-duplex>) status: active run0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 2290 ether 00:25:9c:9f:a2:30 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g status: associated wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:25:9c:9f:a2:30 media: IEEE 802.11 Wireless Ethernet autoselect (autoselect) status: no carrier ssid "" channel 10 (2457 MHz 11g) country US authmode WPA1+WPA2/802.11i privacy ON deftxkey UNDEF txpower 0 bmiss 7 scanvalid 60 protmode CTS wme roaming MANUAL bintval 0
In this example, the ethernet interface (re0) is active and has an IP address. However, the wireless interface (run0, which is associated with wlan0) has a status of no carrier and does not have an IP address. In other words, it has not yet successfully connected to the wireless network.
The dmesg command lists the hardware probed during boot time and indicates if the associated driver was loaded. To search the output of this command for specific information, pipe it to grep as seen in this example:
dmesg | grep Ethernet re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem 0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8 re0: Ethernet address: 60:eb:69:0b:dd:4d dmesg |grep re0 re0: <RealTek 8168/8111 B/C/CP/D/DP/E PCIe Gigabit Ethernet> port 0xc000-0xc0ff mem 0xd0204000-0xd0204fff,0xd0200000-0xd0203fff irq 17 at device 0.0 on pci8 re0: Using 1 MSI messages re0: Chip rev. 0x28000000 re0: MAC rev. 0x00000000 miibus0: <MII bus> on re0 re0: Ethernet address: 60:eb:69:0b:dd:4d re0: [FILTER] re0: link state changed to DOWN re0: link state changed to UP dmesg | grep run0 run0: <1.0> on usbus3 run0: MAC/BBP RT3070 (rev 0x0201), RF RT2020 (MIMO 1T1R), address 00:25:9c:9f:a2:30 run0: firmware RT2870 loaded
If the desired interface does not show up with ifconfig or dmesg, it is possible a driver for this card is not provided with the operating system. If the interface is built into the motherboard of the computer, use the pciconf command to discover the type of card:
pciconf -lv | grep Ethernet device = 'Gigabit Ethernet NIC(NDIS 6.0) (RTL8168/8111/8111c)' pciconf -lv | grep wireless device = 'Realtek RTL8191SE wireless LAN 802.11N PCI-E NIC (RTL8191SE?)'
In this example, there is a built-in Ethernet device using a driver which supports the RTL8168/8111/8111c chipsets. As we saw earlier, the driver is re0. The built-in wireless device was also found but the ? indicates a driver for the RTL8191SE chipset was not found. A web search for FreeBSD RTL8191SE gives an indication if a driver exists or is being developed.
The FreeBSD Handbook chapter on Wireless Networking provides a good overview of how wireless works and offers additional troubleshooting suggestions.
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
Adminstration → Modify Printerfor 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_login 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.
This is a recreation of the user submitted article: Forcibly resetting ZFS replication using the command line lpreserver. A special “thank you!” to TrueOS® user VulcanRidr for providing this article.
ZFS replication can be somewhat complex, and keeping all the fiddly bits aligned can be fraught with danger.
I recently had both of my TrueOS® machines start failing to replicate.
My desktop is called defiant and it has two pools: NX74205 and
NCC1764. My laptop is named yukon with a single pool,
NCC74602. I am replicating to my FreeNAS server, named luna, to
NX80101/archive/<FQDN>. I will focus on what I did
to get yukon working again in this document.
220.127.116.11. Original Indications¶
The SysAdm™ client tray icon was pulsing red. Right-clicking on the icon and clicking Messages showed the message:
FAILED replication task on NCC74602 -> 192.168.47.20: LOGFILE: /var/log/lpreserver/lpreserver_failed.log
This was lifted from
/var/log/lpreserver/lastrep-send.log shows very little
send from @auto-2017-07-12-01-00-00 to NCC74602/ROOT/12.0-CURRENT-up-20170623_120331@auto-2017-07-14-01-00-00 total estimated size is 0 TIME SENT SNAPSHOT
And no useful errors were being written to the
18.104.22.168. Repairing Replication¶
My first approach was to use the SysAdm™ Client (see the Life Preserver section for more details).
Figure 7.1.1 shows my Life Preserver Replication tab:
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.
I was working with and want to give special thanks to Gitter Chat users @RodMyers and @NorwegianRockCat. They suggested I use the lpreserver command line. So I issued these commands:
sudo lpreserver replicate init NCC74602 192.168.47.20 sudo lpreserver replicate run NCC74602 192.168.47.20
Unfortunately, the replication failed again, with these messages:
Fri Jul 14 09:03:34 EDT 2017: Removing NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT - re-created locally cannot unmount '/mnt/NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT': Operation not permitted Failed creating remote dataset! cannot create 'NX80101/archive/yukon.sonsofthunder.nanobit.org/ROOT': dataset already exists
It turned out there were a number of child sets. I logged into the FreeNAS (luna) and issued this command as root:
# zfs destroy -r NX80101/archive/defiant.sonsofthunder.nanobit.org
Then I ran the replicate init and replicate run commands again from the TrueOS® host. Replication now works and continues to work, at least until the next fiddly bit breaks.
Type mixer from the command line to see the current sound settings
mixer Mixer vol is currently set to 0:0 Mixer pcm is currently set to 100:100 Mixer speaker is currently set to 100:100 Mixer mic is currently set to 50:50 Mixer rec is currently set to 1:1 Mixer monitor is currently set to 42:42 Recording source: monitor
If any of these settings are set to 0, set them to a higher value by specifying the name of the mixer setting and a percentage value up to 100:
mixer vol 100 Setting the mixer vol from 0:0 to 100:100.
To make the change permanent, create a file named
the home directory containing the corrected mixer setting.
If only one or two mixer settings are available, the default mixer
channel needs to change. As the superuser, use
sysctl -w hw.snd.default_unit=1 to alter the mixer channel.
To see if the mixer has changed to the correct channel, type mixer again. If there are still only one or two mixer settings, try setting the sysctl value to 2, and, if necessary, 3.
Once all of the mixer settings appear and none are set to 0, sound typically works. If it still does not, these resources can help pinpoint the problem:
7.2. The TrueOS® Community¶
The TrueOS® community has grown and evolved since the project’s inception. A wide variety of chat channels and forum options are now available for users to interact with each other, contributors to the project, and the core development team.
7.2.1. Gitter Chat¶
The TrueOS® Project uses Gitter to provide real-time chat and collaboration with TrueOS® users and developers. Gitter does not require an application to use, but does require a login using either an existing GitHub or Twitter account.
To access the TrueOS Gitter community, point a web browser to https://gitter.im/trueos.
Gitter also maintains a full archive of the chat history. This means lengthy conversations about hardware issues or workarounds are always available for reference. To access the Gitter archive, navigate to the desired TrueOS® room’s archive. For example, here is the address of the TrueOS Lobby archive: https://gitter.im/trueos/Lobby/archives.
It is not required to log in to Gitter to browse the archive.
Gitter is a great way to chat with other users and get answers to questions. Here are few things to keep in mind when asking a question on the Gitter channel:
- Most of the regular users are always logged in, even when they are away from their computer or are busy doing other things. If no one responds immediately, do not get mad, leave the channel, and never come back again. Stick around for a while to see if anyone responds.
- Users represent many different time zones. It is quite possible it is late at night or very early in the morning for some users when asking a question.
- Do not post large error messages in the channel. Instead, use a pasting service such as https://pastebin.com/ and refer to the URL on channel.
- Be polite and do not demand a response from others.
- It is considered rude to “Chat Privately” with someone who does not know you without first asking their permission. If no one answers the question, do not start chatting privately with unkown people in the room.
- The first time joining the channel, it is okay to say “hi” and introduce yourself. If a new person joins the channel, feel free to welcome them and to make them feel welcome.
7.2.2. TrueOS® Subreddit¶
The TrueOS® Project also has a Subreddit for users who prefer to use Reddit to ask questions and to search for or post how-tos. A Reddit account is not required in order to read the Subreddit, but it is necessary when submitting new posts or commenting on existing posts.
TrueOS® also has a Discourse forum managed concurrently with the Subreddit. Functionally similar to the Subreddit, a new user needs to sign up with Discourse in order to create posts, but it is possible to view the current posts without an account.
Like many open source projects, TrueOS® has an Internet Relay Chat (IRC) channel so users can chat and get help in real time. To get connected, use this information in your IRC client:
- Server name: irc.freenode.net
- Channel name: #trueos (note the
AppCafe® has an IRC category where you can find IRC client software. If you do not wish to install an IRC client, you can use the web interface to view #trueos: https://webchat.freenode.net/
IRC is a great way to chat with other users and get answers to your questions. Here are a few things to keep in mind if you ask a question on IRC:
- Most of the regular users are always logged in, even when they are away from their computer or are busy doing other things. If you do not get an answer right away, do not get mad, leave the channel, and never come back again. Stick around for a while to see if anyone responds.
- IRC users represent many different time zones. It possibly late at night or very early in the morning for some users when you ask a question.
- Do not post error messages in the channel as the IRC software can kick you out for flooding and it is considered to be bad etiquette. Instead, use a pasting service such as pastebin and refer to the URL on channel.
- Be polite and do not demand that others answer your question.
- It is considered rude to DM (direct message) someone who does not know you. If no one answers your question, do not start DMing people you do not know.
- The first time you join a channel, it is okay to say “hi” and introduce yourself.
7.3. Contributing to TrueOS®¶
Many in the TrueOS® community have assisted in its development, providing valuable contributions to the project. TrueOS® is a large project with many facets, meaning there is ample opportunity for a wide variety of skill sets to easily improve the project.
7.3.1. Report a bug¶
One of the most effective ways to assist the TrueOS® Project is by reporting problems or bugs encountered while using TrueOS®. Anyone can report a TrueOS® bug. Here is a rundown of the TrueOS® bug reporting tools:
- TrueOS® uses a GitHub repository to manage bugs. A GitHub account is required before bugs can be reported. Navigate to https://github.com/, fill in the required fields, and click Sign up for GitHub to create a new GitHub account.
The GitHub issues tracker uses email to update contributors on the status of bugs. Please use a valid and frequently used email address when creating a GitHub account.
- The TrueOS® code is organized into many repositories representing the Lumina® desktop, the graphical utilities, SysAdm™, and various other applications. When reporting a bug, select the trueos-core repository. If the bug is specific to Lumina®, use the lumina repository. Documentation bugs are tracked in their respective -docs repositories. Issues with any project website are tracked in trueos-website.
- After clicking a repository’s Issues tab, use the search bar to confirm no similar bug report exists. If a similar report does exist, add any additional information to the report using a comment. While it is not required to log in to search existing bugs, adding a comment or creating a new report does require signing into GitHub.
- To create a new bug report, navigate to the desired repository and
Issues → New Issue. Figure 7.3.1 shows the creation of a new bug report.
Here are some basic guidelines for creating useful bug reports:
The ideal title is clear, concise, and informative. Here are some recommendations for creating a title:
- Be objective and clear (and refrain from using idioms or slang).
- Include the application name if the issue is related to an application.
- Include keywords from any error messages you receive.
- Avoid using vague language such as “failed”, “useless”, or “crashed”.
Here are some examples to show the difference between a helpful title and a non-helpful title:
Example 1: Non-Helpful: Lumina-FM crashed. Helpful: Lumina-FM crashed after clicking on a directory name. Example 2: Non-Helpful: Extracting an archive doesn't work. Helpful: Lumina-Archiver shows the error "file not supported" when opening a .cab file.
Like with the title, being clear and concise is extremely helpful. Many people feel they must fill this area with lots of information. While listing a lot of information seems helpful, specific details are often more useful in issue resolution.
The most important pieces of information to include are:
- What happened.
- What you expected to happen.
- (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.
- 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.
- 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.bootis also helpful, as this file shows the hardware probed the last time the TrueOS® system booted. Finally, including the output of
uname -ais 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.
Please do not think you are unable to file your bug ticket without additional information. Providing the listed information above is the most important information for contributors to know. Providing logs does not help as much as those five pieces of information. In some cases, only providing logs to an otherwise empty bug report results in our being unable to resolve your issue.
Additionally useful information may include:
- Screen captures of the error. Lumina Screenshot is a useful tool to quickly screenshot any errors in progress.
- Command Line Output Logs
- Truss Logs
- Debugger Backtrace Logs
After describing the issue, click Submit new issue to create the issue. The bug tracker attaches a unique number to the report and sends update messages to your registered email address whenever activity occurs with the bug report.
7.3.2. Become a Beta Tester¶
If you enjoy tinkering with operating systems and have a bit of spare time, one of the most effective ways to assist the TrueOS® community is reporting problems you encounter while using TrueOS®.
If a spare system or virtual machine is available, you can also download and test the latest UNSTABLE patches (see Updating TrueOS). Having as many people as possible using TrueOS® on many different hardware configurations assists the Project in finding and fixing bugs. The end result is more polished and usable OS for the entire community.
If you wish to become a tester, join the Gitter TrueOS® Lobby. 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.
If interested in translating TrueOS® into your native language, start by choosing which of the three translation areas to work in:
- Translate the graphical menus within the TrueOS® operating system.
- Translate the documentation published with TrueOS®.
- Translate the TrueOS® website.
This section describes each of these translation areas in more detail and how to begin as a translator.
Regardless of the type of desired translation, you should first join the TrueOS® Lobby. 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.
22.214.171.124. Interface Translation¶
TrueOS® uses Weblate for managing localization of the menu screens used by the installer and the TrueOS® utilities. Weblate makes it easy to find out if your native language has been fully localized for TrueOS®. It also makes it easy to verify and submit translated text, as it provides a web editor and commenting system. This means translators can spend more time making and reviewing translations rather than learning how to use a translation tool.
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.3.3.
In the screen shown in Figure 7.3.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.
If the language you wish to translate is missing from the “Translated languages” menu, request its addition in the TrueOS® Lobby.
Next, click Projects at the top of the screen to select a localization project. In the example shown in Figure 7.3.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.
To start translating, click a component name. In the screen shown in Figure 7.3.6, select a language and click Translate.
In the example shown in Figure 7.3.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® Lobby.
126.96.36.199. Documentation Translation¶
The source for the TrueOS® Users Handbook is stored in the
TrueOS® github repository.
This allows the documentation and its translations to be built with
the operating system. Documentation updates are automatically pushed
to the TrueOS® website and, when the system is updated using the
SysAdm™ Update Manager, the doc updates
are installed to a local copy named
/usr/local/share/trueos/handbook/trueos.html. This keeps an
updated local copy of the handbook available on every user’s system.
The TrueOS® build server provides the HTML version of the TrueOS® Users Handbook. Instructions for building your own HTML, PDF, or EPUB version can be found in this README.md.
The documentation source files are integrated into the Weblate translation system so the TrueOS® documentation can be translated using a web browser. The process is similar to Interface Translation except trueos-guide must be selected from the Projects drop-down menu shown in Project Selection.
It is important to be aware of a few elements when translating the documentation:
Do not remove the formatting as this can break the documentation build for that language.
In Formatting Characters - Do Not Remove, it is fine to translate the phrase “Using the Text Installer”, but care must be taken to avoid removing any of the surrounding colons and backticks, or to change the text of the ref tag. In More Formatting Characters, the asterisks are used to bold the words bare minimum. It is fine to translate bare minimum, but do not remove the asterisks.
To build a local HTML copy that includes the latest translations, either for personal use or to visualize the translated Guide, type these commands from the command line in TrueOS®:
sudo pkg install trueos-toolchain rehash git clone git://github.com/trueos/trueos-docs cd trueos-docs/trueos-handbook sudo make i18n make html ls _build doctrees html-es html-tr trueos-handbook-i18n.txz html html-fr html-uk html-da html-id locale html-de html-pt_BR locale-po
This makes an HTML version of the Guide for each of the available
translations. In this example, translations are available for English
html), Danish, German, Spanish, French, Indonesian,
Brazilian Portuguese, Turkish, and UK English. To update the HTML at a
cd ~/trueos-docs git pull cd trueos-docs/trueos-handbook sudo make i18n sudo make html
188.8.131.52. Website Translation¶
Currently, the website is being translated into several languages, including: Dutch, French, German, Polish, Spanish, Swedish, and Turkish.
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.
184.108.40.206. Getting the Source Code¶
The TrueOS® source code is available from GitHub. The code is organized into repositories which represent the Lumina® desktop, the graphical utilities, SysAdm™, and various other applications. git needs to be installed in order to download the source code. When using TrueOS®, git is included in the base install.
To download the source code, cd to the directory to store the source code and specify the name of the desired repository. In this example, the user is downloading the source for the graphical utilities:
~% cd Projects ~/Projects% git clone git://github.com/trueos/trueos-utils-qt5
This creates a directory with the same name as the repository.
To keep the local copy in sync with the official repository,
git pull within the directory.
Before compiling any source, ensure the Ports Collection is installed. At this time, git is used to fetch and update ports (see FreeBSD Ports).
Fetching ports for the first time (as root):
# git clone http://github.com/trueos/freebsd-ports.git /usr/ports
Update an existing
ports directory (as root):
# cd /usr/ports # git pull
Then, cd to the directory containing the source to build and
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
mkport.sh. This example determines the name of the
port directory, changes to it, and then builds the port. Since this
system is already running the TrueOS® graphical utilities,
reinstall is used to overwrite the current utilities:
grep port= mkport.sh port="sysutils/trueos-utils-qt5" cd /usr/ports/sysutils/trueos-utils-qt5 make reinstall
If you plan to make source changes, several Qt IDEs are available in
the SysAdm™ AppCafe. The
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.
220.127.116.11. Design Guidelines¶
TrueOS® is a community driven project relying on the support of developers in the community to help in the design and implementation of new utilities and tools for TrueOS®. The project aims to present a unified design so programs feel familiar to users. As an example, while programs could have File, Main, or System as their first entry in a menu bar, File is used as the accepted norm for the first category on the menu bar.
This section describes a small list of guidelines for menu and program design in TrueOS®.
Any graphical program that is a fully featured utility, such as Life Preserver, should have a File menu. However, file menus are not necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most TrueOS® utilities do not need more than two or three items on the file menu.
Configure is our adopted standard for the category containing settings or configuration-related settings. If additional categories are needed, check to see what other TrueOS® utilities are using.
File menu icons are taken from the KDE Oxygen or material-design
themes located in
/usr/local/share/icons/oxygen. Use these file
menu icons so there are not too many different icons for the same
function. Table 7.3.1 lists some commonly used
icons and their default file names.
|Function||File Menu Icon||File Name|
|Quit||row 1, cell 2||window-close.png|
|Settings||row 2, cell 2||configure.png|
TrueOS® utilities use these buttons:
- Apply: Executes settings changes and leaves the window open.
- Close: Exits program without applying settings.
- OK: Closes dialogue window and saves settings.
- Cancel: Closes dialog window without applying settings.
- Save: Keeps the current settings and closes the window.
Fully functional programs like Life Preserver do not use close buttons on the front of the application. Basically, whenever there is a File menu, that and an x in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule.
Many users benefit from keyboard shortcuts and we aim to make them
available in every TrueOS® utility. Qt makes it easy to assign
keyboard shortcuts. For instance, to configure keyboard shortcuts for
browsing the File menu, put &File in the text slot for the menu
entry when making the application. Whichever letter has the
symbol in front of it becomes the hot key. You can also make a shortcut
key by clicking the menu or submenu entry and assigning a shortcut key.
Be careful not to duplicate hot keys or shortcut keys. Every key in a
menu and submenu should have a key assigned for ease of use and
accessibility. Table 7.3.2 and
Table 7.3.3 summarize the commonly used shortcut and
|CTRL + Q||Quit|
|Alt + Q||Quit|
|Alt + S||Settings|
|Alt + I||Import|
|Alt + E||Export|
|ALT + F||File Menu|
|ALT + C||Configure Menu|
|ALT + H||Help Menu|
When saving an application’s settings, use the QSettings class whenever possible. There are two different organizations, depending whether the application is running with root or user permissions. Use TrueOS as the organization for applications which run with user permissions and TrueOS-root for applications which are started with root permissions via sudo. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples 1 and 2 demonstrate how to use the QSettings class for each type of permission.
Example 1: User Permission Settings
(user application - C++ code): QSettings settings("TRUEOS", "myapplication");
Example 2: Root Permission Settings
(root application - C++ code): QSettings settings("TRUEOS-root", "myapplication");
These resources are also helpful for developers:
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!
18.104.22.168. Make a Simple Documentation Change¶
These instructions are for simple modifications of the TrueOS® handbook, but they also apply to the Lumina® and SysAdm™ documentation! Lumina® documentation lives in the lumina-docs repository and SysAdm™ guides are in sysadm-docs.
Making a documentation change can be as simple as using a web browser. A GitHub account is required to submit patches to TrueOS®, so open a web browser and log in to GitHub. Making an account is also a simple process, but be sure to use an often checked email address, as all communication regarding patches and pull requests are sent to this address.
Navigate to the trueos-docs
GitHub repository. Click on the
trueos-handbook directory to
view all the documentation files. Open the
corresponding to the chapter needing an update. The chapter names are
reflected in the title of the
Figure 7.3.10 shows the trueos-docs repository and
the contents of the
Open the desired chapter file by clicking its entry in the list.
trueos.rst is the primary index file and should be
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.3.11 shows.
If making a simple change, it is recommended to avoid adjusting the specific formatting elements and instead work within or around them.
Once satisfied, scroll to the bottom of the page and write a detailed commit summary of the new changes. Click Propose file change (green button), then Create pull request to submit the changes to the project. GitHub then does an automated merge check. Click Create pull request again to submit the change to the repository. The final step is for a developer or project committer to review the changes, merging or asking for more changes as necessary.
Housekeeping: Once the pull request is merged, delete the now obsolete patch branch.
22.214.171.124. Advanced Documentation Changes¶
These instructions are designed for users running TrueOS®. Actual commands and workflow may change when using a different operating system.
Advanced changes to the TrueOS® documentation require an understanding of the underlying tools and markup language. This section covers downloading and installing the required tools and source files to build a local copy of the documentation. It also discusses the reStructured Text markup language and some of the specific conventions TrueOS® uses in its documentation. It is recommended the contributor be familiar with using TrueOS and/or FreeBSD before following these instructions.
There are a few packages to install before making a local copy of the documentation. Sphinx and its relevant extensions are the most important.
Open AppCafe® or a command-line and download the py27-sphinx package:
[user@example] sudo pkg install py27-sphinx
y if prompted to continue installing the package. Next,
install the py27-sphinxcontrib-httpdomain package:
[user@example] sudo pkg install py27-sphinxcontrib-httpdomain
Be sure git is installed. TrueOS® installs this by default. A GitHub account is also required to follow these instructions. Open a web browser pointed to https://github.com/ to create an account.
The last critical item to have on hand is a configurable text editor.
Lumina Text Editor
is a simple plaintext editor built in to TrueOS® which works very well
.rst files, but other editors like kate
and scite also function well.
Preparing a local copy of the GitHub repository
Once ready with Sphinx and extensions installed, navigate to the trueos-docs repository and fork it by clicking the Fork button in the upper-right corner of the repository. This creates a copy of the repository on the user’s personal GitHub account, allowing the user to create patches and submit pull requests to the upstream (or base) repository.
Now there are two repositories to track on GitHub, the primary
trueos-docs and the user’s forked version on their personal
In the command line, use git clone to clone the forked repository:
[user@example] git clone https://github.com/[github_user]/trueos-docs.git
cd into the newly downloaded
to continue configuring this cloned repo.
Set up the local clone of the forked repository to point to the upstream repository:
[user@example] ~/trueos-docs% git remote -v origin https://github.com/[github_user]/trueos-docs.git (fetch) origin https://github.com/[github_user]/trueos-docs.git (push) [user@example] ~/trueos-docs% git remote add upstream https://github.com/trueos/trueos-docs.git [user@example] ~/trueos-docs% git remote -v origin https://github.com/[github_user]/trueos-docs.git (fetch) origin https://github.com/[github_user]/trueos-docs.git (push) upstream https://github.com/trueos/trueos-docs.git (fetch) upstream https://github.com/trueos/trueos-docs.git (push)
This configuration allows changes made in a fork to be synced to the original repository and changes in the original synced to the fork:
[user@example] ~/trueos-docs% git fetch upstream [user@example] ~/trueos-docs% git merge upstream/master [user@example] ~/trueos-docs% git push origin master
One last element to configure is to set the account identity:
[user@example] ~/trueos-docs% git config --global user.email "[firstname.lastname@example.org]" [user@example] ~/trueos-docs% git config --global user.name "[Your Name]"
This sets the global user name and email for git. Remove
–global from the command to set the value only for the
trueos-docs project directory.
It can be very useful to have two local copies of the documentation. One to pull in changes from “upstream” and one to make local changes and build test. This helps prevent merge conflicts where the local changes accidentally override brand new patches added to the upstream repository.
Basic Git commands
Once the local
trueos-docs copy is configured, there are a few
general git commands to remember when working in the
- 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.
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.
The Sphinx Project documentation is very robust and is recommended to browse or reference it when making advanced changes to the TrueOS® documentation. The Sphinx reStructuredText Primer is also highly recommended.
The TrueOS® implementation of Sphinx uses a few management files and
directories to handle and build the
.rst source files:
trueos.rst: The master index file for the handbook. This file governs how the Table of Contents is constructed and which
.rstfiles 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.
imagesdirectory: All images used in the documentation are stored in this directory. Every image is
.pngformat, and adding or removing an image to this directory requires updating the
themesdirectory: Houses the currently used trueos_style theme. This theme includes
.cssfiles, 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.
Once all the repository forking and configuration is done, the actual workflow to make and submit documentation changes is straightforward:
- cd into the local copy:
[user@example] ~% cd /trueos-docs/trueos-handbook
- Use git pull upstream master to download any changes from the upstream repository. Then type git merge upstream/master to add those changes to the local copy of the forked repository. Finally, use git push origin master sync these changes from the upstream repository the online forked repository.
- Make any changes to the
.rstfiles using a plaintext editor.
- Build test the changes with make html. The builder output
posts messages if any errors are detected. The built
htmlfiles are viewable by opening them in a web browser:
[user@example] ~/trueos-docs/trueos-handbook% firefox _build/html/trueos.html &
- Clean the
_builddirectory with make clean. The contents of this directory are not needed in the online repositories, only when conducting build tests.
- Stage a changed file for commit with git add [path/to_file].
- Continue changing, testing, and staging files as desired, then make the patch to push to the online forked repository with git commit. Be sure to add a descriptive commit message about the changes.
- git push origin master to send the patch to the online forked repository.
- Open a browser and navigate to the forked
trueos-docsrepository. Look for the message saying “This branch is 1 commit ahead of trueos:master” and click the Pull request button on the same line. GitHub checks if the branches can be automatically merged, displaying a green checkmark if everything looks good. Click Create pull request, add any more details to the commit message, if necessary, then click Create pull request again.
- Finished! The patch is submitted for a developer or project maintainer to review and merge.
Update translation files
Once the initial patch is submitted, it is recommended to submit another patch to update the translation files:
- cd into the local copy and run make i18n.
- Once the command is finished, type make clean. This removes a number of unnecessary files. Type git status to view the newly updated translation files.
- Commit all these files to a patch with git commit -a. Use the same commit message as the last non-translation change, but add :TRANSLATIONS to the title. This allows the project contributors to more easily track when and which translation files are updated.
- Follow the same git push and GitHub website instructions listed above to submit the patch to the upstream repository.
126.96.36.199. Documentation Conventions¶
This section is intended to provide references for the specific conventions of TrueOS® documentation. Table 7.3.4 provides specific conventions of the TrueOS® project:
It is also recommended to open one of the handbook
files for reference.
|70 character lines||Start a new line every 70 characters.||Certain elements like a long link or code block.|
|Archive old images||Replaced images are moved to
|PNG images||All images are in the
|Whitespace||Remove any unnecessary whitespace.||Empty lines and at the end of lines.|
|guilabel||Graphical elements: buttons, icons, fields, columns, and boxes.||Click Ok|
|menuselection||Menu selections and paths||Select
|command||Commands||Use the lcp command|
|file||File, volume, and dataset names||Locate the
|kbd||Keyboard keys||Press the
|Bold||Important points||This is important.|
|Italic||Device names or values entered into fields||Enter 127.0.0.1 in the address field.|
|samp||Command line representations||
|code-block||Multi-line code examples.||
|External links||Hyperlink to website outside the built documentation.||Check Google|
|Internal Links||Hyperlink to an internal section of the documentation||See Documentation|
|Paragraph||Test separated by one or more blank lines. All lines of the same paragraph must be left-aligned to the same level of indentation.|
|Inline||One asterisk around text is italics.|
|Inline||Two asterisks around text is bold.|
|Inline||Two backquotes around text is a code sample.|
|Inline role||Interpreted text roles: syntax is :rolename:`content`.|
|Nested List||Nested lists are separated from the parent items by blank lines.|
|Quoted par.||Add indentation.|
|Comment||Start line with .. and a whitespace. End the comment by adding an empty line, then starting the next line at the same level of indentation.|
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 are referenced using the numref role and internal marker:
:numref:`Image %s <example1>` is the example syntax to introduce a new image. .. _example1: .. figure:: images/example1.png :option: [value] Caption for Example1.png
These are the specific admonition boxes used by TrueOS® documentation:
A trivial shortcut or efficiency.
Useful information or reminder for accurate command use.
Caution about potential problems introduced by the procedure or its misuse.
Extreme caution. Data loss or system damage can occur.
Love TrueOS®? Why not tell your family, friends, fellow students and colleagues about it? You are not the only individual who prefers a virus-free, feature-rich, and no-cost operating system. Here are some suggestions for getting started:
- Burn a couple of DVDs and give them away.
- Consider giving a presentation about TrueOS® at a local community event, conference, or online. Let us know about it through our The TrueOS® Community channels and we can help spread the word!
- Write a personal blog detailing your journey from your first TrueOS® install experience to your most recent accomplishment. The blog could also be used to teach or explain how to perform tasks on TrueOS®. A regional language blog may help build the community in your area and to find others with similar interests.
7.4. Additional Resources¶
Need more information? A number of useful resources that may aid in using TrueOS® are available.
7.4.1. FreeBSD Handbook and FAQ¶
TrueOS® uses FreeBSD as its underlying operating system, so nearly everything in the FreeBSD Handbook and FreeBSD FAQ applies to TrueOS® as well. Both documents are comprehensive and cover nearly every possible task to accomplish on a FreeBSD system. They are also an excellent resource for learning how things work under the hood of a TrueOS® system.
Some configurations described in the FreeBSD Handbook already “just work” on a TrueOS® system as they have been pre-configured. In these instances, reading the FreeBSD Handbook section can help to learn how the system is configured and why it works.
7.4.2. Search and Portals¶
Many BSD related search portals exist. If unable to find an answer from the forums or mailing lists, try searching these websites:
7.4.3. More Resources¶
Many BSD sites and resources may also contain useful information:
- The FreeBSD Diary
- TrueOS® YouTube channel
- BSD YouTube channel
- BSD Talk
- BSD Now
- BSD Magazine (free, monthly download)
- FreeBSD Journal (bi-monthly magazine)
- BSD Hacks (book)
- The Best of FreeBSD Basics (book)
- Definitive Guide to PC-BSD® (book)