This Walkthrough is a Continuation of Part 1 of the InstallFest How-To Guide

Follow the link here for part 1

Updated: August 14, 2020

Step 2.1: Package Installation

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

Step 2.2: Desktop Configuration

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.

Step 2.3: FreeBSD Update and Package

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

Step 2.4: Setting up Jails

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 (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="" -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

Step 2.5: Poudriere

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


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

Step 2.6: Updating Poudriere

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


$ 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

Some Additional Useful Commands:

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


$ sudo shutdown –r now

Log Out:

$ exit

$ logout

Directory Navigation

Display present work directory:

$ pwd

List contents of current directory:

$ ls


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 -


Additional Resources: 


FreeBSD Foundation:


Mailing Lists:


FreeBSD Handbook: