In this guide, we’ll use the xine video player to set up basic video playback on a fresh FreeBSD install. The xine multimedia player relies on the XWindow system and the XVideo extension to provide a graphical video playback interface.

Xorg supports a wide variety of video cards, but not all are supported or offer good video playback performance.

It is a good idea to have a short MPEG test file for evaluating various players and options. Since some DVD applications look for DVD media in /dev/dvd by default, or have this device name hardcoded in them, it might be useful to make a symbolic link to the proper device:

Due to the nature of devfs(5), manually created links will not persist after a system reboot. In order to recreate the symbolic link automatically when the system boots, add the following line to /etc/devfs.conf:

There are several possible ways to display video under Xorg and what works is largely hardware dependent. This guide will focus on the Xvideo extension which allows video to be directly displayed, even on low-end machines.

Start by installing the X Window System:

Once the package has been fully installed, the X Window System can be started with:

To check whether the Xvideo extension is running, use xvinfo:

If XVideo is supported, the result will look similar to the example below and may include screen and video card information.

XVideo is likely unsupported by the video card if the result instead look like:

The display may be unable to meet the demands of rendering video playback if XVideo is unsupported (though this is not always the case).

xine is a free multimedia player. It plays back CDs, DVDs, BluRays and VCDs. It also decodes multimedia files like AVI, MOV, WMV, and MP3 from local disk drives, and displays multimedia streamed over the Internet. Get started by installing the package:

In practice, xine requires either a fast CPU or support for the XVideo extension. The xine video player performs best on XVideo interfaces. If in the previous step, the Xvideo extension was unsupported, issues may occur.

The xine player starts a graphical user interface (GUI) and the menus can be used to navigate to multimedia files.

Alternatively, xine may be directly invoked from the command line by specifying the name of the file to play:

You now have a simple way to play a variety of multimedia files on your FreeBSD system! To find out more about the xine player, refer to the SourceForge page.

Follow the link here for part 1

Updated: August 14, 2020

Packages can be downloaded in bulk by adding them to the same command line. Try this by installing the GNOME desktop environment, sudo, the vim editor, and Firefox in one line:

$ pkg install -y gnome3 vim-console firefox

The -y flag in the previous command assumes a pre-confirmation to the installation process, so installation will start instantly.

Gnome requires /proc to be mounted, in order to do this, run

$ vim /etc/fstab

This time we use the vim editor, Vi iMproved, and to begin typing you need to be in “insert mode” and must press ‘i‘ to enter insert mode and begin typing in text. Type in the following one-line configuration:

proc      /proc      procfs      rw      0      0

Exit vim by pressing “Esc” on the keyboard, then type ZZ or :wq followed by Enter/Return. At this point the virtual machine desktop can be started with the following command:

Change to regular user by holding down “control” and pressing “d” on the keyboard which will log out the current user.  Log in again, this time as the regular user account that was created and type the following commands.

$ echo "exec /usr/local/bin/gnome-session" > ~/.xinitrc

$ startx

Here is how to open a local copy of the handbook we installed in the Final Configuration:

Right click on: Desktop > Applications > Firefox Web Browser

Open Firefox and navigate to the following URL: file:///usr/local/share/doc/freebsd/handbook/index.html

This is a local copy of the FreeBSD Handbook, and it will always be available as it doesn’t require an active internet connection. That’s all it takes to install FreeBSD. The next recommended step is to choose a firewall and configure it. Also recommend you pick up a copy of the book “BSD Hacks” to get more familiar with the tcsh shell as well as to acquire several new skills.

Navigate back to Applications and open the terminal.

In the open terminal, run:

$ sudo -i

$ env PAGER=cat freebsd-update fetch install

We’re using env PAGER=cat to modify the value of the PAGER variable which is used by the freebsd-update shell script. If you open up the shell script you will see the default value of PAGER is set to less. You can find the location of the freebsd-update shell script by typing which freebsd-update. By setting the value of PAGER to cat, freebsd-update will not stop to display the list of file to be updated, instead the cat command will only display the list of files and won’t stop to wait for you to read. If you only type freebsd-update fetch install, you’ll need to use the following to get through the prompts

‘Page Down‘ & ‘q‘ should get you through the prompts. If the screen shows END press ‘q‘, use ‘Page Down‘ for the other screens. You can also use ‘q’ for every screen.

Now that FreeBSD itself is up to date, we should also update the packages.

$ pkg update

$ pkg upgrade -y

Set UTF-8 as the locale for this host:

$ vim /etc/login.conf

Change the line with :umask=022: to look like the following:

:umask=022:\ :charset=UTF-8:\ :lang=en_US.UTF-8:

Save and quit the editor then run the following:

$ cap_mkdb /etc/login.conf

$ logout

Log in as root and type the following to verify UTF-8 locale has been set

$ locale

Install iocage

$ pkg install -y py37-iocage

The following command assumes your zpool is named zroot adjust as necessary. Type zpool status to see the current name of your zpool.

$ iocage activate zroot

$ iocage list

We should now see an empty table as the output of iocage list, we’ll do some additional housekeeping below to improve performance of iocage. There are many things you can do to optimize performance of various applications. One way to learn several new tips and tricks is to read the supurb collection of FreeBSD Mastery books available at https://MWL.io (In fact, the following performance optimization trick was in the book FreeBSD Mastery: Jails)

$ mount -t fdescfs null /dev/fd

$ vi /etc/fstab

Add the following line to the file and exit when finished. ‘i‘ for insert mode, ‘ESC‘ then ‘ZZ‘ to save and quit the file. Press ‘TAB‘ between each of the fields for the fstab file rather than using spaces to separate fields.

fdescfs /dev/fd fdescfs rw 0 0

Download a Release branch of FreeBSD first

$ iocage fetch

We used [Enter] to fetch the default release iocage wants to provide. Verify the download with the following command

$ iocage list -r

View the help documentation

$ iocage --help

Any sub-commands can also have the –help flag appended

$ iocage create --help

Create a base jail

$ iocage create -T -n JAILNAME ip4_addr="10.0.2.16" -r 12.1-RELEASE

List current jails

$ iocage list

Startup jail-one and jump into the console

$ iocage console JAILNAME

The console command will start the jail if it isn’t already started. To manually start a jail use this:

$ iocage start JAILNAME

Similarly to stop a jail issue

$ iocage stop JAILNAME

Verify networking is working

$ pkg

Say yes to the pkg bootstrap prompt. Exit the jail console with ctrl + d.

To delete a jail:

$ iocage destroy JAILNAME

The following commands will work on the virtual machine we’ve been using so far, but it will take a long time to compile all the packages.

We’re going to use the cloned virtual machine we created earlier to explore Poudriere.

Start up the cloned VM.

Execute the following commands as the root user:

$ pkg install -y poudriere vim-console

$ mkdir /usr/ports/distfiles

$ mkdir /usr/local/poudriere

$ vim /usr/local/etc/poudriere.conf

poudriere.conf content to modify

ZPOOL=zroot FREEBSD_HOST=https://download.freebsd.org

Continue executing:

$ poudriere jail -c -j amd64-12-1 -v 12.1-RELEASE

$ poudriere jail -l

$ poudriere ports -cp head

$ poudriere ports -l

Get together a list of packages to build. I ran pkg query -e '%a=0' %o on my laptop and a large list appeared. pkg query on my VM was much shorter. To learn more about pkg query issue the command pkg help query to see help text for the query subcommand. Most commands support some form of help (-h, –help, or simply reading the man page with man PROGRAM) For this tutorial we will just build a shorter list of packages. The command to export the current packages installed on the system to a file called pkglist is:

$ pkg query -e ‘%a=0’ %o | tee pkglist

$ editors/vim-console

$ ports-mgmt/pkg

$ ports-mgmt/poudriere

Note: tee writes output to a file and also to stdout. Also the following two bits of information are optional for this tutorial and are included to show you how to customize packages.

Two ways to configure custom options for packages, manually and with the normal make config screen. FYI: Manually looks like this:

$ vim /usr/local/etc/poudriere.d/amd64-12-1-make.conf

$ DEFAULT_VERSIONS += ssl=libressl

To customize a package one can use the normal package configuration screens, which will appear when issuing the following command

$ poudriere options -j amd64-12-1 -p head -f pkglist

For this tutorial we’ll just actually build the packages with the default options to get the hang of Poudriere by issuing the following:

$ poudriere bulk -j amd64-12-1 -p head -f pkglist

$ cd /usr/local/poudriere

This directory contains logs related to Poudriere builds. There are even a few different website files generated at /data/logs/bulk/.html/ with information about the builds. You can open the website in Firefox using the URL file:///data/logs/bulk/.html/index.html to check on the status of a current Poudriere build. You can also press ctrl + t on the command line where you issued the poudriere bulk command to issue a SIGINFO to Poudriere which is configured to print out the current status of the Poudriere build while the command is still processing. This trick works on many other commands as well to show you the status. For instance if you were using scp to download a large file and wanted to see how far along the download was SIGINFO would print out the status on the command line to show you. Another example is if you were decompressing a zip file and wanted to know the status of the extraction process.

Once Poudriere has finished, the packages that were built are available at

$ /data/packages/amd64-12-1-head

Create a pkg repository

$ mkdir -p /usr/local/etc/pkg/repos

Disable the main FreeBSD repo by creating a file to override the default settings found in the default FreeBSD repository file /etc/pkg/FreeBSD.conf

$ vim /usr/local/etc/pkg/repos/FreeBSD.conf

Type in the following configuration with enabled set to no

FreeBSD: {
        enabled: no
}

Create a new configuration file for your local Poudriere package repository similar to the FreeBSD.conf file to hold the repository configuration

$ vim /usr/local/etc/pkg/repos/amd64-12-1.conf

Add the following configuration

amd64-12-1: {
        url: “file:///data/packages/amd64-12-1-head”,
        enabled: yes,
}

To reinstall all packages using the new repo

$ pkg upgrade -fy

NOTE: A good Systems Administration practice is to add comments to your configs to let the future you know what the config options do and why there were put there in the first place. That way when you revisit a config file after some time, you’ll have some context as to why those options were chosen.

$ vim /usr/local/etc/poudriere.conf

# by default Poudriere builds all packages in the pkglist by default, these two lines tell Poudriere to look at each package individually

CHECK_CHANGED_OPTIONS=verbose CHECK_CHANGED_DEPS=yes

$ poudriere jail -j amd64-12-1 -u

$ poudriere ports -p head -u

$ poudriere bulk -j amd64-12-1 -p head -f pkglist

You can now install the updated packages:

$ pkg update

Avoiding Issues

Terminate current command:

$ ^C (Ctrl-C)

Clear to start of line:

$ ^U (Ctrl-U)

Finding Information:

Manual page for the “cmd” command, replace with any other command to access its manual page:

$ man cmd

Rebooting / Shutting Down

Power Down:

$ sudo shutdown –p now

Reboot:

$ sudo shutdown –r now

Log Out:

$ exit

$ logout

Directory Navigation

Display present work directory:

$ pwd

List contents of current directory:

$ ls

Files

Create file if it does not exist:

$ touch filename

Delete file:

$ rm filename

Rename a file:

$ mv oldname newname

Search for a file: (full filename is not needed)

$ locate filename

File editing

$ vi filename

$ ee filename

Change to your home directory

$ cd

$ cd ~

Change to parent directory

$ cd ..

Change to previous directory

$ cd -

Website: www.freebsd.org

FreeBSD Foundation: archive.freebsdfoundation.org

GitHub: github.com/freebsd  

Mailing Lists: https://lists.freebsd.org/mailman/listinfo

Forums: https://forums.freebsd.org

FreeBSD Handbook: https://www.freebsd.org/doc/handbook/

Updated: June 15, 2022

Start by opening up the terminal, found under Applications > Utilities > Terminal. Then use the code:

sysctl -n machdep.cpu.brand_string

This will return a string identifying the computer’s processor. Running a web search for this processor will take you to the manufacturers website, which should list the processor’s stats as well as whether it is 32-bit or 64-bit.

Navigate to “Control Panel → System and Security → System” and look for the highlighted information to determine whether your system is 32-bit or 64-bit.

Visit the VirtualBox downloads website, and in the highlighted area, select the platform package binary that applies to your operating system. VirtualBox is available on Windows, macOS, Linux, and Solaris.

Opening the downloaded file will start the installation walkthrough. Once it finishes, you’ll be able to launch the application.

Visit the official FreeBSD releases page. The disk images are listed in order of release date, so the most recent release can be found at the top of the page as highlighted.

After clicking the link, you will be redirected to a file directory containing multiple formats and versions of the FreeBSD installer.

For Virtual Machines, the format you are looking for is the file ending in -disk.iso as shown above. Click this file and it will start downloading the installer.

Once the FreeBSD installer has been downloaded in the last step, run VirtualBox to start hard disk configuration. Select the “New” button on the top left of the window to open the configuration window. 

Name your operating system as “FreeBSD”, then select FreeBSD from the dropdown menu as well as the version (32 or 64 bit).

Choose the defaults options for disc setup until you reach the memory allocation section

After the hard disk has been configured, boot up the operating system with the “Start” button. VirtualBox will start up a virtual machine and ask for a virtual optical disk file. This will be the .iso file that you downloaded through the FreeBSD website. Navigate to this file by clicking the small file symbol next to the drop-down menu. Once selected, the booting process will continue and the FreeBSD installer will start.

The FreeBSD booting system will automatically start once VirtualBox starts the virtual machine. While this how-to will provide a detailed installation guide, the FreeBSD handbook’s installation guide can also be used. When in doubt, use the default options provided, as they can be reconfigured later if necessary.

While the FreeBSD installation process has been completed, there a few more configuration options that need to be set before booting into the newly installed system.

Once FreeBSD has been properly configured, a window will appear asking to reboot. Select “yes” and wait until the FreeBSD booting page appears again. Once this happens, manually close the virtual machine window and select “Power off the machine”.

On the main VirtualBox application, click the the section (on the lower right side of the window) that says “Storage”. A new window should appear showing the storage options.

Under the main “Controller: IDE” there will be two options. One will be the hard disk that VirtualBox created for the system (it will have a square blue hard drive icon) and the other is the original FreeBSD download (with a light blue disk icon). Right click the sub-storage with the disk icon and select “Remove” from the drop-down menu.

Once it is removed, the window should resemble the one pictured above.

Use the Snapshots menu in VirtualBox to Clone the VM. Check the box “Reinitialize the MAC address of all network cards”. We could choose either a Full clone or a Linked clone. We’ll use the Full clone option. Later on in the installfest we’ll use this cloned VM.

Click “Start” with the original VM selected, and the FreeBSD virtual machine should now boot in its configured form. In order to download packages you need to be logged into, or emulate the root user. After logging into the previously created user, enter the following command in the terminal:

$ su

Install the VirtualBox guest addition packages, and configure the startup service configuration:

$ pkg install emulators/virtualbox-ose-additions

$ sysrc vboxguest_enable=YES

$ sysrc vboxservice_enable=YES

sysrc is a pre-packaged command that allows rc.conf (system configuration to be read on boot) to be edited from the command line, without using a text editor.

Before installing a desktop environment, a graphical user interface (GUI) is needed. The X Window System is an open source GUI that supports FreeBSD and offers a ton of customization and user tools.

To install the Xorg binary package and configure the X Window System:

$ pkg install -y xorg

$ ee /boot/loader.conf

ee(1) is the first text editor we will be using, the following line can be added simply by typing it:

kern.vty=vt

Escape and then hit Enter twice to save changes and exit the ee(1) editor:

$ ee /usr/local/etc/X11/xorg.conf.d/driver-vboxvideo.conf

Use the same method above and add the following content to the new file:

Section “Device”

        Identifier "Card0"

        Driver "vboxvideo"

EndSection

Enter the following commands:

$ sysrc dbus_enable=YES

$ sysrc hald_enable=YES

$ dbus-uuidgen > /etc/machine-id

$ pkg install -y sudo

$ visudo

(we will use another text editor, the vi editor, to edit sudo )

Within the sudo config type /wheel press Enter and uncomment the line below to allow all members of the wheel group to use sudo (in vi you can type the following to accomplish this task: j0xxZZ) ( pressing j moves down, 0 moves to the beginning of a line, x deletes one character, ZZ is saves and quits)

$ reboot

Follow the link here

The next part will include installing a desktop environment, updating FreeBSD, setting up a FreeBSD jail, as well as using Ansible and Poudriere.

A wireless networking card is required to use a wireless network, FreeBSD will also need to be configured to the correct wireless network support. The correct module will need to be modified, depending on the type of networking card. The most commonly used wireless devices are those that use parts made by Atheros. These devices are supported by ath(4) and require the following line to be added to /boot/loader.conf:

If unsure about the device, you can identify many common wireless adaptors through the use of the  sysctl(8) net.wlan.devices variable:

To load support for a different type of wireless device, specify the module for that device. This example is for devices based on the Intersil Prism parts (wi(4)) driver:

Note: A list of available wireless drivers and supported adapters can be found in the FreeBSD Hardware Notes, available on the Release Information page of the FreeBSD website.

In addition, the modules that implement cryptographic support for the security protocols to use must be loaded. These are intended to be dynamically loaded on demand by the wlan(4) module. To load these modules at boot time, add the following lines to /boot/loader.conf:

Information about the wireless device should appear in the boot messages, like this:

Directly connecting to an unsecure network, while not recommended, is extremely common. It’s also a very simple process on FreeBSD. In this example I’ll beconnecting to the John F Kennedy International Airport’s free WiFi.

Start by finding the name of the network:

This will look for available networks and return a list, In this case, we want to connect to the JFK free wifi so we’ll use:

Hopefully you will see that it’s joined, and running ifconfig ath0 will show that it’s associated. You can then get an address with:

Most home/private networks will rely on these security protocols. Connecting a computer to an existing WPA/WPA2/Personal wireless network is a very common situation.

FreeBSD can act as an Access Point (AP) in order to act as a gateway or to eliminate the need to purchase AP hardware. Before an Access Point can be set up, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. This mode is only supported by native FreeBSD wireless drivers.

After setting up wireless networking, you can check if the device supports host-based access point mode:

This output displays the card’s capabilities. The HOSTAP word confirms that this wireless card can act as an AP.

The wireless device can only be put into hostap mode during the creation of the network pseudo-device, so a previously created device must be destroyed first:

then regenerated with the correct option before setting the other parameters:

Use ifconfig(8) again to see the status of the wlan0 interface:

The hostap parameter indicates the interface is running in the host-based access point mode.

The interface configuration can be done automatically at boot time by adding the following lines to /etc/rc.conf:

Once the AP is configured, initiate a scan from another wireless machine to find the AP.

Many cellphones can share data connection over USB, FreeBSD provides support through a variety of protocols:

Before attaching a device, load the appropriate driver into the kernel:

Once the device is attached ue0 will be available for use like a normal network device. Be sure that the “USB tethering” option is enabled on the mobile device.

To make this change permanent and load the driver as a module at boot time, place the appropriate line of the following in /boot/loader.conf:

Before attaching a Bluetooth device, determine which Bluetooth driver it uses. A broad variety of Bluetooth USB dongles are supported by ng_ubt(4). Broadcom BCM2033 based Bluetooth devices are supported by the ubtbcmfw(4) and ng_ubt(4) drivers. The 3Com Bluetooth PC Card 3CRWB60-A is supported by the ng_bt3c(4) driver. Serial and UART based Bluetooth devices are supported by sio(4), ng_h4(4), and hcseriald(8). For example, if the device uses the ng_ubt(4) driver:

If the Bluetooth device will be attached to the system during system startup, the system can be configured to load the module at boot time by adding the driver to /boot/loader.conf:

Once the driver is loaded, plug in the USB dongle. If the driver load was successful, output similar to the following should appear on the console and in /var/log/messages:

To start and stop Bluetooth, use the driver’s startup script.

FreeBSD uses hccontrol(8) to find and identify Bluetooth devices within RF proximity.

One of the most common tasks is discovery of Bluetooth devices within RF proximity. This operation is called inquiry. Inquiry and other HCI related operations are done using hccontrol(8). To display a list of devices that are in range use:

Note: only devices that are set to discoverable mode will be listed.

The BD_ADDR is the unique address of a Bluetooth device, similar to the MAC address of a network card. This address is needed for further communication with a device. To to obtain the human readable name that was assigned to the remote device:

The Bluetooth system provides a point-to-point connection between two Bluetooth units, or a point-to-multipoint connection which is shared among several Bluetooth devices. The following example shows how to create a connection to a remote device:

create_connection accepts BT_ADDR as well as host aliases in /etc/bluetooth/hosts.

The following example shows how to obtain the list of active baseband connections for the local device:

While a Bluetooth device can choose to require authentication, communication is normally not authenticated, so any Bluetooth device can talk to any other device. If the device requires authentication, the PIN code must be entered on both devices, the devices will then generate a link key. After that, the link key can be stored either in the devices or in a persistent storage. This procedure is called pairing.

The hcsecd(8) daemon is responsible for handling Bluetooth authentication requests. The default configuration file is /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with the PIN code set to 1234 is shown below:

The only limitation on PIN codes is length. Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. The -d switch forces hcsecd(8) to stay in the foreground, so it is easy to see what is happening. Set the remote device to receive pairing and initiate the Bluetooth connection to the remote device. The remote device should indicate that pairing was accepted and request the PIN code. Enter the same PIN code listed in hcsecd.conf. Now the computer and the remote device are paired.

The following line can be added to /etc/rc.conf to configure hcsecd(8) to start automatically on system start:

Updated: June 15, 2022

With FreeBSD’s ongoing migration to git from subversion, the system for updating FreeBSD from source has adapted. This guide will cover getting sources from git, updating them, and how to bisect those sources. It is meant as an introduction to the new mechanics for general users.

To begin, the source tree must be downloaded. This can be done quite simply. First step: cloning a tree. This downloads the entire tree. There are two ways to download. By default, git will do a deep clone, which matches what most people want. However, there are times that you may wish to do a shallow clone.

The branch names in the new git repository are similar to the subversion names. For the stable branches, they are stable/X where X is the major release number (like 12 or 13). The development branch for -CURRENT in the new repository is main.

Note: The main branch is the default branch if you omit the -b branch options below.

The hashes are different between them. For migrating from the old repository to the new one, please refer to https://github.com/freebsd/freebsd-legacy/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf

Use the repository of choice in place of $URL in the following commands.

Before cloning the tree, git will need to be installed. The simplest way of doing so is through packages.

# pkg install git

There are also git-lite and git-tiny, two packages with only essential dependencies available. They are sufficient for the commands in this article.

A deep clone pulls in the entire tree, as well as all the history and branches. It’s the easiest to do. It also allows you to use git’s worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository.

% git clone $URL -b branch [dir]

is how you make a deep clone. branch should be one of the branches listed in the section 1.1, if omitted, it will be the depository’s default: main. Dir is an optional directory to place it in (the default will be the name of the repository you are clone (src). For example:

% git clone https://git.freebsd.org/src.git

You’ll want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. It’s the easiest to keep up to date as well. If you are interested in the history, but are working with only one branch and are short on space, you can also use
--single-branch to only download the one branch (though some merge commits will not reference the merged-from branch which may be important for some users who are interested in detailed versions of history).

A shallow clone copies just the most current code, but none or little of the history. This can be useful when you need to build a specific revision of FreeBSD, or when you are just starting out and plan to track the tree more fully. You can also use it to limit history to only so many revisions.

% git clone -b branch --depth 1 $URL [dir]

An example using the default branch:

% git clone --depth 1 https://git.freebsd.org/src.git

This clones the repository, but only has the most recent revision in the repository. The rest of the history is not downloaded. Should you change your mind later, you can do git fetch --unshallow to get the complete history.

After cloning the FreeBSD repository, the next step is to build from source. The process of building remains relatively unchanged, using make and install. Git and offer git pull and git checkout for updating and selecting specific branches or revisions.

Building can be done as described in the handbook [3], eg:

% cd src
% make buildworld
% make buildkernel
% make installkernel
% make installworld

Note that you can specify -j to make to speed up with parallelism.

The following command will update both types of trees. This will pull all revisions since the last update.

% git pull --ff-only

This will update the tree. In git, a fast forward merge is one that only needs to set a new branch pointer and doesn’t need to re-create the commits. By always doing a fast forward merge/pull, you’ll ensure that you have an identical copy of the FreeBSD tree. This will be important if you want to maintain local patches.

See below for how to manage local changes. The simplest is to use:

% git pull --autostash

but more sophisticated options are available.

In git, the git checkout command can be used to checkout a specific revision as well as branches. Git’s revisions are the long hashes rather than a sequential number.

When you checkout a specific revision, just specify the hash you want on the command line (the git log command can help you decide which hash you might want):

% git checkout 08b8197a74

However, as with many things git, it’s not so simple. You’ll be greeted with a message similar to the following:

where the last line is generated from the hash you are checking out and the first line of the commit message from that revision. Hashes can also be abbreviated. That’s why you’ll see them have different lengths in different commands or their outputs. These super long hashes are often unique after some characters, depends on the size of the repository so git lets you abbreviate and is somewhat inconsistent about how it presents them to users. git rev-parse --short <full-hash> will show the short hash which has the enough length to distinguish in the repository. The current length of FreeBSD src repository is 12.

Sometimes, things go wrong. The last revision worked, but the one you just updated to does not. A developer may ask to bisect the problem to track down which commit caused the regression.

If you’ve read the last section, you may be thinking to yourself “How the heck do I bisect with crazy revision numbers like that?” then this section is for you. It’s also for you if you didn’t think that, but also want to bisect.

Fortunately, git offers the git bisect command. Here’s a brief outline in how to use it. For more information, I’d suggest https://git-scm.com/docs/git-bisect for more details. The man page is good at describing what can go wrong, what to do when revisions won’t build, when you want to use terms other than good and bad, etc, none of which will be covered here.

git bisect start will start the bisection process. Next, you need to tell a range to go through. git bisect good XXXXXX will tell it the working revision and git bisect bad XXXXX will tell it the bad revision. The bad revision will almost always be HEAD (a special tag for what you have checked out). The good revision will be the last one you checked out.

A quick aside: if you want to know the last revision you checked out, you should use git reflog:

shows me moving the working tree to the master branch (a816…) and then updating from upstream (to 5ef0…). In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. As you can see from the output, HEAD@{1} also often works, but isn’t foolproof if you’ve done other things to your git tree after updating, but before you discover the need to bisect.

Back to git bisect. Set the good revision first, then set the bad (though the order doesn’t matter). When you set the bad revision, it will give you some statistics on the process:

% git bisect start
% git bisect good a8163e165c5b
% git bisect bad HEAD

You’d then build/install that revision. If it’s good you’d type git bisect good otherwise git bisect bad. You’ll get a similar message to the above each step. When you are done, report the bad revision to the developer (or fix the bug yourself and send a patch). git bisect reset will end the process and return you back to where you started (usually tip of main). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.

The doc tree is the first repository converted to git. There is only one development branch in the repository, main, which contains the source of https://www.freebsd.org and https://docs.freebsd.org.

The ports tree operates a similar way. The branch names are different and the repos are in different locations.

As with ports, the latest development branch is main. The quarterly branches are named the same as in FreeBSD’s svn repo. They are used by the latest and quarterly branches of the pkg.

Here’s a small collection of topics that are more advanced for the user tracking FreeBSD. If you have no local changes, you can stop reading now (it’s the last section and OK to skip).

One item that’s important for all of them: all changes are local until pushed. Unlike svn, git uses a distributed model. For users, for most things, there’s very little difference. However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD. All changes that you’ve not pushed are local and can easily be modified (git rebase, discussed below does this).

The simplest way to keep local changes (especially trivial ones) is to use git stash. In its simplest form, you use git stash to record the changes (which pushes them onto the stash stack). Most people use this to save changes before updating the tree as described above. They then use git stash apply to re-apply them to the tree. The stash is a stack of changes that can be examined with git stash list. The git-stash man page (https://git-scm.com/docs/git-stash) has all the details.

This method is suitable when you have tiny tweaks to the tree. When you have anything non trivial, you’ll likely be better off keeping a local branch and rebasing. It is also integrated with the git pull command: just add
––autostash to the command line.

It’s much easier to keep a local branch with git than subversion. In subversion you need to merge the commit, and resolve the conflicts. This is manageable, but can lead to a convoluted history that’s hard to upstream should that ever be necessary, or hard to replicate if you need to do so. Git also allows one to merge, along with the same problems. That’s one way to manage the branch, but it’s the least flexible.

Git has a concept of ‘rebasing’ which you can use to avoid these issues. The git rebase command will basically replay all the commits relative to the parent branch at a newer location on that parent branch. This section will briefly cover how to do this, but will not cover all scenarios.

Let’s say you want to make a hack to FreeBSD’s ls(1) command to never, ever do color. There’s many reasons to do this, but this example will use that as a baseline. The FreeBSD ls(1) command changes from time to time, and you’ll need to cope with those changes. Fortunately, with git rebase it usually is automatic.

% cd src
% git checkout main
% git checkout -b no-color-ls
% cd bin/ls
% vi ls.c # hack the changes in
% git diff # check the changes

% # these look good, make the commit...
% git commit ls.c

The commit will pop you into an editor to describe what you’ve done. Once you enter that, you have your own local branch in the git repo. Build and install it like you normally would, following the directions in the handbook. git differs from other revision control systems in that you have to tell it explicitly which files to use. Here it’s done on the commit command line, but you can also do it with git add which many of the more in depth tutorials cover.

When it’s time to bring in a new revision, it’s almost the same as w/o the branches. You would update like you would above, but there’s one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. It’s important to start rebasing operations with a clean tree (git usually requires this).

% git checkout main
% git pull
% git rebase -i main no-color-ls

This will bring up an editor that lists all the commits in it. For this example, don’t change it at all. This is typically what you are doing while updating the baseline (though you also use the git rebase command to curate the commits you have in the branch).

Once you’re done with the above, you’ve moved the commits to ls.c forward from the old revision of FreeBSD to the newer one.

Sometimes there’s merge conflicts. That’s OK. Don’t panic. You’d handle them the same as you would any other merge conflicts. To keep it simple, I’ll just describe a common issue you might see. A pointer to a more complete treatment can be found at the end of this section.

Let’s say this includes changes upstream in a radical shift to terminfo as well as a name change for the option. When you updated, you might see something like this:

which looks scary. If you bring up an editor, you’ll see it’s a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted):

The new code is first, and your code is second. The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:

save the file. The rebase was interrupted, so you have to complete it:

% git add ls.c
% git rebase --cont

which tells git that ls.c has changed and to continue the rebase operation. Since there was a conflict, you’ll get kicked into the editor to maybe update the commit message.

If you get stuck during the rebase, don’t panic. git rebase –abort will take you back to a clean slate. It’s important, though, to start with an unmodified tree.

For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment. It goes into a lot of cases I didn’t cover here for simplicity that are useful to know since they come up from time to time.

Let’s say you want to main the jump from FreeBSD stable/12 to FreeBSD current. That’s easy to do as well, if you have a deep clone.

% git checkout main
% # build and install here...

and you are done. If you have a local branch, though, there’s one or two caveats. First, rebase will rewrite history, so you’ll likely want to do something to save it. Second, jumping branches tends to encounter more conflicts. If we pretend the example above was relative to stable/12, then to move to main, I’d suggest the following:

% git checkout no-color-ls
% git checkout -b no-color-ls-stable-12 # create another name for this branch
% git rebase -i stable/12 no-color-ls --onto main

What the above does is checkout no-color-ls. Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. Then you rebase onto the main branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a placeholder name).

[1] Using Git, FreeBSD Handbook, https://docs.freebsd.org/en/books/handbook/mirrors/#git

[2] Git, FreeBSD wiki, https://wiki.freebsd.org/Git

[3] Updating FreeBSD from Source, FreeBSD Handbook, https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld

Updated: June 15, 2022

FreeBSD relies on the continued contributions of its user base to survive. Becoming involved is simple and there are a wide variety of tasks that users can contribute to.

A large and growing number of international contributors, of various ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated.

The FreeBSD project is responsible for the entire FreeBSD operating system environment, meaning a wide range of TODO tasks exist. To help contributing to the FreeBSD documentation, check out this guide on submitting and updating documentation.

This guide will focus on how programmers can contribute to the project. Please read through the following selection of tasks that may be needed.

Most of the tasks listed here require a considerable investment of time, an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for “weekend hackers”.

FreeBSD users can submit requests for enhancement and bug reports through to FreeBSD PR (problem report) database. The database contains many active programmer and non-programmer tasks, though not all tasks are required to be logged there. Look through the open problem reports, and see if anything there takes your interest. There is a wide range of tasks that may range from simple code reviews to much more complex requests that may not readily contain a fix.

Start with open problem reports that have not been assigned to anyone else. If there is an active PR that is assigned to someone else, but looks like something you would like to work on, email the person assigned to the task and ask if you can assist or take over the PR. They may already have a patch that they need to test, or benefit from your suggestions.

The Ports Collection contains a massive amount of content and as such, is always a perpetual work in progress. People are constantly needed to keep the collection up to date, and filled with high quality third party software.

Anyone can get involved, and there are lots of different ways to contribute. Contributing to ports is an excellent way to help “give back” something to the project. Whether you are looking for an ongoing role or a fun challenge for a rainy day, the project would love to have your help!

There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order:

The FreeBSD ideas page is regularly updated with items for programmers. Anyone looking to contribute to the FreeBSD Project can check it for tasks that they can assist with.

After identifying a task to work on, there are a few ways to assist with the operating system itself.

If you are submitting a specific change, you can submit the patch by using the bug submission form. This how to guide provides a step-by-step walkthrough for submitting a bug report.

If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. When patches are a lot larger than 20KB, consider compressing them prior to uploading them.

An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as “FreeBSD-CURRENT” which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT.

Working from older sources, unfortunately, means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the FreeBSD announcements mailing list and the FreeBSD-CURRENT mailing list lists, where discussions on the current state of the system take place.

Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the diff(1) command.

The preferred diff(1) format for submitting patches is the unified output format generated by diff -u.

% diff -u oldfile newfile

or

% diff -u -r -N olddir newdir

will generate a set of unified diffs for the given source file or directory hierarchy.

Once you have a set of diffs (which you may test with the patch(1) command), you should submit them for inclusion with FreeBSD as a bug report. Because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report.

If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to Core Team <core@FreeBSD.org> directly rather than submitting as a bug report. The Core Team <core@FreeBSD.org> reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary.

NOTE: Please refer to intro(9) and style(9) for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code.

In the case of a significant contribution, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or a publicly accessible git branch or repository. Running these large changes through Phabricator is also recommended.

When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. Copyleft licenses such as GPLv2 are sometimes permitted. The complete listing can be found on the core team licensing policy page.

Creating a port is a once-off task. Ensuring that a port is up to date and continues to build and run requires an ongoing maintenance effort. Maintainers are the people who dedicate some of their time to meeting these goals.

The foremost reason ports need maintenance is to bring the latest and greatest in third party software to the FreeBSD community. An additional challenge is to keep individual ports working within the Ports Collection framework as it evolves.

Taking over unmaintained ports is a great way to get involved. Unmaintained ports are only updated and fixed when somebody volunteers to work on them. There are a large number of unmaintained ports. A good idea is to start by adopting a port that you use regularly.

Unmaintained ports have their MAINTAINER set to ports@FreeBSD.org. A list of unmaintained ports and their current errors and problem reports can be seen at the FreeBSD Ports Monitoring System.

Some ports affect a large number of others due to dependencies. Generally, we want people to have some experience before they maintain these ports.

There are two really good places to find a port that needs some attention.

You can use the web interface to the Problem Report database to search through and view unresolved PRs. The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the sw-bug class is a good place to start).

The other place is the FreeBSD Ports Monitoring System. In particular look for unmaintained ports with build errors and ports that are marked BROKEN. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem.

Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. Otherwise create a new PR. Your changes will be reviewed and, if everything checks out, committed.

First, make sure you understand your responsibilities as a maintainer. Also read the Porter’s Handbook. Please do not commit yourself to more than you feel you can comfortably handle.

You may request maintainership of any unmaintained port as soon as you wish. Simply set MAINTAINER to your own email address and send a problem report (PR) with the change. If the port has build errors or needs updating, you may wish to include any other changes in the same PR. This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. Submitting PRs that fix build errors or update ports are the best ways to establish one.

File your PR with category ports and class change-request. A committer will examine your PR, commit the changes, and close the PR.

This section outlines the process to follow to keep your ports up to date.

This is an overview. More information about upgrading a port is available in the Porter’s Handbook.

FreeBSD only guarantees that the Ports Collection works on the -STABLE branches. In theory, you should be able to get by with running the latest release of each stable branch but if you can run the branch, that is even better.

Since the majority of FreeBSD installations run on PC-compatible machines (what is termed the i386 architecture), we expect you to keep the port working on that architecture. We prefer that ports also work on the amd64 architecture running native. It is completely fair to ask for help if you do not have one of these machines.

The usual failure modes for non–x86 machines are that the original programmers assumed that, for instance, pointers are ints, or that a relatively lax older gcc compiler was being used. More and more, application authors are reworking their code to remove these assumptions — but if the author is not actively maintaining their code, you may need to do this yourself.

These are the tasks you need to perform to ensure your port is able to be built:

FreeBSD-specific bugs are generally caused by assumptions about the build and runtime environments that do not apply to FreeBSD. You are less likely to encounter a problem of this type, but it can be more subtle and difficult to diagnose.

These are the tasks you need to perform to ensure your port continues to work as intended:

Part of being a maintainer is providing support — not for the software in general — but for the port and any FreeBSD-specific quirks and problems. Users may contact you with questions, suggestions, problems and patches. Most of the time their correspondence will be specific to FreeBSD.

Occasionally you may have to point users seeking general support to the appropriate resources. Less frequently you will encounter a person asking why the RPMs are not up to date or how can they get the software to run under Foo Linux. Take the opportunity to tell them that your port is up to date, and suggest that they try FreeBSD.

Sometimes users and developers will spend time assisting you and your port. They may:

In these cases, your main obligation is to respond in a timely manner. Again, the timeout for non-responsive maintainers is 14 days. After this period changes may be committed unapproved. They have taken the trouble to do this for you; so please try to at least respond promptly. Then review, approve, modify or discuss their changes with them as soon as possible.

The Porter’s Handbook is your hitchhiker’s guide to the ports system. Keep it handy!

The Problem Report database.

The FreeBSD Ports Monitoring System can show you cross-referenced information about ports such as build errors and problem reports. If you are a maintainer you can use it to check on the build status of your ports. As a contributor you can use it to find broken and unmaintained ports that need to be fixed.

The FreeBSD Ports distfile scanner can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their MASTER_SITES updated.

ports-mgmt/poudriere is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. Documentation is located at the poudriere github repository

portlint(1) is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. portlint is a simple heuristic application, so you should use it only as a guide. If portlint suggests changes which seem unreasonable, consult the Porter’s Handbook or ask for advice.

The FreeBSD ports mailing list is for general ports-related discussion. It is a good place to ask for help. You can subscribe, or read and search the list archives. Reading the archives of the FreeBSD ports bugs mailing list and the SVN commit messages for the ports tree for head/ may also be of interest.

If you are looking for something interesting to get started, the FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started.

The Junior Jobs page lists current projects that may interest people new to FreeBSD, these can be great way to acquaint oneself with the project.

Updated: February 5, 2022

Quality documentation is crucial to the success of FreeBSD, submitting documentation is one of the easiest ways to contribute to the project and anyone is welcome to submit! Willingness to contribute is the only membership requirement.

The first step to contribute is to subscribe to the FreeBSD documentation project mailing list. This is a fantastic resource for any questions or problems involving the documentation.

The working copy is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats.

FreeBSD documentation for commands and configuration files can be found within the manual page collection. These consist of two repositories: doc for books and articles, and src for operating system and manual pages. These repositories can contain multiple versions of documentation and source code.

In order to edit manual pages, src will need to be checked out separately.

FreeBSD documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user’s home directory.

A download of a working copy from the repository is called a clone, this can be done with git clone. For example, to checkout the latest version (head) of the documentation tree.

% git clone https://git.freebsd.org/doc.git ~./doc

And to checkout the source code for manual pages:

% git clone https://git.freebsd.org/src.git ~./src

The FreeBSD repository is frequently updated, even a short time after the initial checkout, changes may have already been made creating differences between the local working copy and the main FreeBSD repository. To update the local version, use git pull on the directory containing the local working copy. Getting into the habit of doing this often before editing document files will be helpful.

% cd ~/doc
% git pull --ff-only

Sometimes it turns out that changes were unnecessary, or the writer wants to start over. git restore can “reset” files to their unchanged form

% git restore filename

After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These diff files are produced by redirecting the output of git diff into a file:

% cd ~/doc
% git diff > filename

Give the file a meaningful name that identifies the contents. Thhttps://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/working-copy.htmlis will be important for identifying what type of change was made, and to what part of the tree.

If the diff file is to be submitted with the web “Submit a FreeBSD problem report” interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text.

Different types of output can be produced from a single AsciiDoc source file.

These are the tools used to build and install the FDP documentation.

There are three main types of Makefiles in the FreeBSD Documentation Project tree.

These Makefiles usually take this form: (Some contents have been removed for simplicity sake):

These Makefiles share a similar format to documentation Makefiles, however, no languages tag is used.

Here is an example of the second half of a website Makefile:

Most FDP documentation is written with AsciiDoc. This chapter explains what that means, how to read and understand the documentation source, and the techniques used. To get a complete reference of the AsciiDoctor capabilities please consult the Asciidoctor documentation. Some of the examples have been taken from the AsciiDoc Syntax Quick Reference.

AsciiDoctor supports six headings levels. If the document type is article only one level 0 (=) can be used. If the document type is book then there can be multiple level 0 (=) headings.

This is an example of headings in an article.

Paragraphs don’t require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. To create a new paragraph leave one blank line.

For example, this is a heading with two paragraphs.

AsciiDoctor supports a few types of lists, the most common are ordered and unordered. To get more information about lists, see AsciiDoc Syntax Quick Reference.

To create an ordered list use the . character.

For example, this is an ordered list.

And this would be rendered as.

To create an unordered list use the * character.

For example, this is an unordered list.

And this would be rendered as.

To point to another website the link macro should be used.

To point to another book or article the AsciiDoctor variables should be used. For example, if we are in the cups article and we want to point to ipsec-must these steps should be used.

We hope this guide has served as a brief introduction to the process of submitting documentation, programmers should also check out our guide on Contributing to FreeBSD as a Programmer.