Updated: May 20, 2021

A collection of FreeBSD desktop distributions that have taken the FreeBSD operating system in a new direction while still relying on the incredibly powerful and stable base operating system of FreeBSD. From integrated desktop environments, portable USB-based systems, to data recovery tools, FreeBSD has been used by a wide variety of open-source projects. This page hopes to highlight just a few of these projects:

Project Website

“MidnightBSD is a BSD-derived operating system developed with desktop users in mind. It includes all the software you’d expect for your daily tasks — email, web browsing, word processing, gaming, and much more.”

Project Website

“GhostBSD is a simple, user-friendly operating system, based on the legendary security and stability of the FreeBSD operating system. GhostBSD provides all the benefits of the FreeBSD operating system combined with a focus on simplicity for newcomers.”

Project Website

“NomadBSD is a persistent live system for USB flash drives, based on FreeBSD. Together with automatic hardware detection and setup, it is configured to be used as a desktop system that works out of the box, but can also be used for data recovery, for educational purposes, or to test FreeBSD’s hardware compatibility.”

Project Website

“hello (also known as helloSystem) is a desktop system for creators with a focus on simplicity, elegance, and usability. Its design follows the “Less, but better” philosophy. It is intended as a system for “mere mortals”, welcoming to switchers from the Mac. FreeBSD is used as the core operating system.”

Updated: June 2, 2021

One of the easiest ways to get involved with the FreeBSD Project is through the submission of bug reports. A bug report can be about any component of FreeBSD, including problems with the operating system programs, a mistake in the documentation, or a new feature that the submitter wishes to see incorporated.

General ideas and suggestions should be sent to the FreeBSD technical discussions mailing list. Bugs and specific changes can be submitted through the bug submission form.

This guide will focus on the process of using the Bugzilla form to report bugs and changes.

Before submitting a bug report, make sure that a bug report is the right course of action. There are still many cases where submitting a problem report is clearly not the right course of action, and will only serve to frustrate both the submitter and the developers. Below are a couple examples of cases which may not be worth a bug report:

As a general rule, the problem is not a bug if it can be expressed as a question (“How do I do X?” or “Where can I find Y”). While some cases might be worthy of a bug report, consider using the FreeBSD general questions mailing list to pose the question before submitting a bug report. This will help make sure that questions are filtered through the correct channels.

While submitting bug reports for ports or software not part of FreeBSD itself, consider the following:

While running into a bug that cannot be reproduced can be annoying, these rarely can be fixed. If the bug only occurred once and you cannot reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. Often these kinds of bugs are caused by a failing hard drive or overheated processor, try to rule these out before submitting a bug report.

The software that makes up FreeBSD is a collection of several different elements, making sure that the bug report is sent to the correct developers to ensure it is fixed quickly.

It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs. The Security Officer team maintains the list of supported versions.

Always do a background search before submitting a bug report. The bug may have already been reported or is being discussed on a mailing list. Therefore, you should check these places before submitting. These include:

Bug reports will use the bugzilla web form. To submit a bug report, an account will need to be created. Select the category that the bug falls under, then fill out the form.

The following fields will need to be filled out:

Once the problem report has been filed, you will receive a confirmation by email which will include the tracking number that was assigned to your problem report and a URL you can use to check its status. With a little luck, someone will take an interest in your problem and try to address it, or, as the case may be, explain why it is not a problem. You will be automatically notified of any change of status, and you will receive copies of any comments or patches someone may attach to your problem report’s audit trail.

If someone requests additional information from you, or you remember or discover something you did not mention in the initial report, please submit a follow up. The number one reason for a bug not getting fixed is lack of communication with the originator. The easiest way is to use the comment option on the individual PR’s web page, which you can reach from the PR search page.

If the problem report remains open after the problem has gone away, just add a comment saying that the problem report can be closed, and, if possible, explaining how or when the problem was fixed.

Sometimes there is a delay of a week or two where the problem report remains untouched, not assigned or commented on by anyone. This can happen when there is an increased problem report backlog or during a holiday season. When a problem report has not received attention after several weeks, it is worth finding a committer particularly interested in working on it.

There are a few ways to do so, ideally in the following order, with a few days between attempting each communication channel:

Remember that these people are volunteers, just like maintainers and users, so they might not be immediately available to assist with the problem report. Patience and consistency in the follow-ups is highly advised and appreciated. With enough care and effort dedicated to that follow-up process, finding a committer to take care of the problem report is just a matter of time.

A brief introduction to some of the commands and functionality of the FreeBSD operating system. This guide will cover the commands that a new user will need to initially start working with FreeBSD as well as how to use the FreeBSD manual pages for more information.

FreeBSD is configured to log users into the system console, this is identified as (ttyv0). System messages will be displayed in this console by default, occasionally causing issues if the user is entering commands.

FreeBSD also supports multiple virtual consoles to help with this problem. By default these consoles can be accessed by a combination of the alt and F-keys. For example, alt+F2 will open the first virtual console, alt+F3 will open the second, and so on. To re-access the system console use alt+F1.

Virtual Consoles can be used to create the feeling of having multiple screens that can be used. In addition, commands that have been entered on one console will continue to run even when the user switches to a different console.

The FreeBSD video mode is extremely versatile and easy to configure. The video mode can be adjusted to any size supported by the graphics card.

To configure the video mode, first load the VESA module:

$ kldload vesa

Next, you’ll need to determine which video modes are supported. The vidcontrol command can be used to output a list of available modes:

$ vidcontrol -i mode

The list of supported modes will number the video modes as well as containing a brief description of the video mode. To switch the video mode, specify the number of the mode you would like to use, the following is an example for switching to mode 279:

$ vidcontrol MODE_279

The vidcontrol command used in the last section is an extremely powerful system utility and can be further used to configure the system and virtual consoles.

Navigate to the vidcontrol manual page. Manual pages contain information on commands, as well as instructions for proper use. For example, in the last section we used the vidcontrol command but applied the “-i mode” option. This told the system to list possible video modes that are supported.

Play with the vidcontrol command a bit until you are comfortable with applying parameters to commands. To start off, try to enable the mouse pointer on the console:

$ vidcontrol -m  on

The first part of the code is the command, in this case vidcontrol, followed by the command option “-m” instructing the system that the user is applying a change to the mouse pointer. In this case, the -m option has two possible arguments “on” and “off”. Play around further with the command and see if you can change the text color and background.

Some commands will require superuser, often referred to as “root”, privileges in order to execute. The superuser account has no limitations so it is not recommended to use the account for common commands as a typo or mistake could destroy the operating system. To avoid this, you should only access the superuser account when executing commands that require extra privileges. 

While a user could log into the root account on startup, the recommended method is to use the sucommand to access the root account. In order to run this command the user must be in the wheel group. After entering the command, the system will prompt the user to enter the root password:

$ su

Once the user is done with the command, the superuser session can be ended by using the exit command:

$ exit

A variety of user utilities are included in the FreeBSD operating system. The primary ones will be covered in this section.

$ adduser

The adduser command starts an interactive user-setup that you may recognize from the initial installation of FreeBSD. It is the recommended tool for setting up new accounts because it creates a home directory for the new user.

$ rmuser jru

The rmuser command is the recommended tool for removing accounts and cleaning up the processes and directories associated with the user. The example above is removing the user “jru”.

$ passwd jru

The passwd command can be used to change and set a new password for accounts. 

$ pw groupmod wheel -m jru

The pw command is an extremely powerful user group utility. In this example, we are using it to add “jru” to the wheel group. It is recommended to read the manual page for this command as it is quite a bit more complicated than the other commands in this section.

FreeBSD comes with a simple, yet limited, text editor “ee“, or easy editor. This utility opens an editor display and lists the available commands at the top. The following example is how a user would edit the rc.conf file with easy editor:

$ ee /etc/rc.conf

Once the command has been executed, the display opens and allows you to make changes to the chosen file. The “^” symbol used in the command represents Ctrl and the utility can be quit using the Esc key.

While easy editor is a great utility for a new user, many more experienced users will find the utility to be limited and time-consuming to use.

Another text editor that FreeBSD includes is the extremely versatile vi command. Executing the command starts a text-based editor that allows users to directly view and edit text files. The vi editing options are not listed in the same way as the ee commands, however, more experienced users will find that once they become more experienced with vi, text editing becomes much easier and less time-consuming. Much like the last section, to edit the rc.conf text file using the vi command:

$ vi /etc/rc.conf

Arrow keys can be used to navigate the text file. The editing options can be found listed on the command’s manual page if you scroll down to the second section. These commands can be entered by first hitting the Esc key, followed by the command.

For example, if a user is trying to add text directly after the cursor the user would first hit the Esc key to exit the previous command, then hit the a key. They would then be able to enter the text they wish to add. 

Because the sheer number of text-editing options, users should read through the manual page before using the vi command.

For FreeBSD, at system boot, /etc/rc reads /etc/rc.conf and /etc/defaults/rc.conf to determine which services are to be started. The specified services are then started by running the corresponding service initialization scripts located in /etc/rc.d/ and /usr/local/etc/rc.d/.

The scripts found in /etc/rc.d/ are for applications that are part of the “base” system, such as cron(8), sshd(8), and syslog(3). The scripts in /usr/local/etc/rc.d/ are for user-installed applications such as Apache and Squid.

User-installed applications are not considered to be part of the “base” system and are generally installed using Packages or Ports. In order to keep them separate from the base system, user-installed applications are installed under /usr/local/. Therefore, user-installed binaries reside in /usr/local/bin/ and configuration files are in /usr/local/etc/.

Services are enabled by adding an entry for the service in /etc/rc.conf. The system defaults are found in /etc/defaults/rc.conf and these default settings are overridden by settings in /etc/rc.conf. Refer to rc.conf(5) for more information about the available entries. When installing additional applications, review the application’s install message to determine how to enable any associated services.

The following entries in /etc/rc.conf enable sshd(8), enable Apache 2.4, and specify that Apache should be started with SSL:

Once a service has been enabled in /etc/rc.conf, it can be started without rebooting the system:

# service sshd start
# service apache24 start

If a service has not been enabled, it can be started from the command line using onestart:

$ service sshd onestart

The most comprehensive documentation on FreeBSD is in the form of manual pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and available arguments. These manuals can be viewed using man:

$ man command

where command is the name of the command to learn about. For example, to learn more about ls(1), type:

$ man ls

Manual pages are divided into sections which represent the type of topic. In FreeBSD, the following sections are available:

In some cases, the same topic may appear in more than one section of the online manual. For example, there is a chmod user command and a chmod() system call. To tell man(1) which section to display, specify the section number:

$ man 1 chmod

This will display the manual page for the user command chmod(1). References to a particular section of the online manual are traditionally placed in parenthesis in written documentation, so chmod(1) refers to the user command and chmod(2) refers to the system call.

If the name of the manual page is unknown, use man -k to search for keywords in the manual page descriptions:

$ man -k mail

This command displays a list of commands that have the keyword “mail” in their descriptions. This is equivalent to using apropos(1).

To read the descriptions for all of the commands in /usr/sbin, type:

$ cd /usr/sbin
$ man -f * | more

FreeBSD offers two primary methods of downloading applications and system tools: packages and ports. Users will have to choose between the two collections when installing these tools. Packages are pre-compiled binary packages, typically smaller in size than full port installations and they do not require compilation time. However, ports are a much more customizable option, allowing users to directly interact with the build process and configure the application to their preference. Additionally, installing an application from a port can help a user understand how the application is compiled, configured, and finally built into a binary. It can be a very rewarding process!

For this guide, we will be compiling irssi, a powerful and modular text-based Internet Relay Chat (IRC) client, from the Ports Collection.

NOTE: ensure that you run all the following commands as the root user by running $ sudo su once.

Before we start, ensure you have a working installation of FreeBSD. If you do not, you can follow these installation walkthroughs:

Once you have FreeBSD installed, start up your machine and boot into FreeBSD. If you installed FreeBSD or a similar variant (e.g. PC-BSD, TrueOS, etc.), powering your machine on will automatically boot into the operating system. 

To do this on VirtualBox, open the application, select your FreeBSD machine, and click “Start”:

You’ll see a FreeBSD boot menu pop up: let it automatically boot and bring you to the login screen.

Then, after logging in, you should see a welcome screen and a shell prompt appear similar to this:

You are now ready to get started!

To begin installing ports on our FreeBSD system, we must first download the Ports Collection. The following command will download the latest compressed snapshot of the Ports Collection and extract it into the /usr/ports directory:

Later on, if we want to update our snapshot of the Ports Collection, we can run:

Now that the Ports Collection has been installed, we need to be able to find applications that we want to install on our system. The Ports Collection contains directories for software categories, and inside each category are subdirectories for individual applications. We will determine the relevant information necessary to navigate to the irssi port.

In our example, the category name is “irc” and the package name is “irssi”, so you would type:

Now that we are inside the directory for the irssi port, we can begin understanding the installation process. This application directory, called the port skeleton, contains a set of files that tells FreeBSD how to compile and install the program. Each port skeleton includes these files and directories:

NOTE: The port does not include the actual source code, also known as a distfile. The “extract” portion the build process will automatically download and save the compressed source code in the /usr/ports/distfiles directory.

To install the port (and clean the directory to remove any temporary files afterward), type

Notice that a screen similar to the following will show up:

This is a good example of one of the benefits of compiling irssi from the Ports Collection! It allows you to precisely configure which additional features you want to bundle with the final application binary. Some defaults are already chosen for us, but let’s add “truecolor” support in case we want full bit-depth color when using irssi in a compatible terminal emulator. Navigate to the option using the arrow keys and press “<Space>”. Once you are satisfied with the configuration, navigate to the “OK” option and press “<Enter>”.

You now have irssi installed on your system! Before running it, we’ll do a few things first:

To run the application, simply type $ irssi. You should see a screen like this:

For further information on how to use irssi, type in /help in the “status” line. Now you’ll be able to chat with people over IRC!

As you can see, compiling and installing an application from the Ports Collection is a satisfying process. However, we just scratched the surface of this process, so for more information, check out the following links:

BONUS:  The Ports Collection includes games too! Try using this guide to install 2048, a clone of the popular 2048 game implemented with a command-line interface. This is a great way to explore all the options available for fine-tuning your application build process.