Skip to content
FreeBSD Jail Starter Kit
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

FreeBSD Starter Kit

"It's dangerous to go alone! Take this."

Welcome to the FreeBSD Starter Kit! This document is designed to help you be successful in your use and adoption of the FreeBSD operating system.

This document begins with a brand-new FreeBSD 11.2 system deployed by a cloud provider (AWS, DigitalOcean, Vultr, etc.) Manual installation is not covered in this document.

The latest version of this document can always be found at the FreeBSD Starter Kit.


Upon creating and logging into a system for the first time there are three commands I suggest running. The first will silence login banner messages, the second will apply the latest patches. Finally, a reboot to apply the changes.

touch .hushlogin
freebsd-update fetch install

After the first reboot is complete, run the install command once again.

freebsd-update install

Pro-tip: subscribe to this mailing list for FreeBSD security notifications (low volume). Anytime you recieve an email from this list, re-run freebsd-update fetch install.

UTF-8 (recommended)

If you would like to make use of UTF-8 character encoding you'll need to apply a small patch to the /etc/login.conf.


--- /etc/login.conf.sample	2018-06-22 04:34:52.000000000 +0000
+++ /etc/login.conf		2018-08-28 01:40:53.905324000 +0000
@@ -46,7 +46,9 @@
-	:umask=022:
+	:umask=022:\
+	:charset=UTF-8:\
+	:lang=en_US.UTF-8:

Rebuild the login database after patching the file:

cap_mkdb /etc/login.conf


FreeBSD provides a binary packaging service, available in quarterly (default) and latest options. These binary packages are built from the FreeBSD ports tree, which follows a rolling-release model. This means up-to-date packages are often available and follow upstream release versions.

To use the binary package manager, bootstrap it by running pkg for the first time:

pkg bootstrap
root@freebsd:~ # pkg bootstrap
The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y
Bootstrapping pkg from pkg+, please wait...
Verifying signature with trusted certificate done
[freebsd] Installing pkg-1.10.5_1...
[freebsd] Extracting pkg-1.10.5_1: 100%
root@freebsd:~ #

Note: this bootstrapping step can be automated using the following command:

env ASSUME_ALWAYS_YES=YES pkg bootstrap
root@freebsd:~ # env ASSUME_ALWAYS_YES=YES pkg bootstrap
Bootstrapping pkg from pkg+, please wait...
Verifying signature with trusted certificate done
[freebsd] Installing pkg-1.10.5_1...
[freebsd] Extracting pkg-1.10.5_1: 100%
root@freebsd:~ #


If you take a closer look at the first line of output after the bootstrap command you'll notice that the last part of the URL says quarterly. This subscribes the system to the "Quarterly" release cycle for binary packages. For most systems this is adequate (and more stable).

No changes are needed to subscribe to the quarterly repo.


To use the latest binary packages, providing you with essentially a rolling-release model for binary updates, update the pkg URL to use the latest suffix instead.

A simple way to override the default settings is to create a new repo file but with the updated URL.

For example:

mkdir -p /usr/local/etc/pkg/repos
echo 'FreeBSD: { url: 'pkg+\$\{ABI\}/latest', enabled: yes }' > /usr/local/etc/pkg/repos/FreeBSD.conf

Package Basics

In this section you'll learn the basics of using the package manager, and install a few creature comforts. FreeBSD's binary package manager works much like others you might be familiar with. Just remember, this isn't your father's FreeBSD. No compiling required.


pkg install vim-console git-lite zsh ca_root_nss 

The above pkg install command will add the vim-console, git-lite, zsh and ca_root_nss (CA certificates) from the quarterly/latest repositories. Naturally you can replace zsh with bash (or another shell of your choice).

pkg search nginx

You may also search the pkg repository for named packages. pkg search foo will match packages including foo.

Note: if you're ever unsure a binary package name, check out

pkg info

The pkg info will show you info on installed packages. Without any flags or options it will show you the name, version and description of each installed package.

pkg remove zsh

As you've probably assumed, pkg remove removes (uninstalls) an installed package.

pkg help

You can always find help and a list of other options using pkg help.

pkg help install

Also available, more in-depth help on each option. pkg help install, for example, will show help on the install sub-command.




ezjail-admin is a command-line utility written to automate the creation and patching of FreeBSD Jails. I have used ezjail-admin for a number of years, and continue to use it. It is very lightweight and does a reliable job.

To install ezjail-admin, use pkg to install:

pkg install ezjail

Once installed you'll need to bootstrap the latest FreeBSD release. This is done using the ezjail-admin install command. This command is usually run once in the lifetime of an ezjail system.

ezjail-admin install

Once the installation completes downloading base.txz, lib32.txz, etc you'll be able to create jails.

ezjail-admin create -c zfs -s 2G -f base hostname IP

Yes, it's that easy. The first two flags, -c and -s are technically optional. These two tell ezjail to use ZFS-based storage and set the quota to 2G. Otherwise all you need to create a jail is a unique hostname and an IP.

Regarding the networking...

There are a couple of ways to do networking within FreeBSD containers. My preferred method (in most cases) is the loopback network. This means creating a cloned loopback interface and attaching containers to private (RFC1918) IP addresses.

To create a cloned loopback interface, use the following commands:

sysrc cloned_interfaces="lo1"


This jail management tool is a newer addition to the ports tree. This is/was maintained by the FreeNAS team last I looked. It is written in Python3 and has a bunch of features.

iocage is a jail/container manager amalgamating some of the best features and technologies the FreeBSD operating system has to offer. It is geared for ease of use with a simple and easy to understand command syntax.


This is my contender in this arena. Release pending.

Bastille is written in Go, which allows it to be a zero-dependency drop-in container manager.

Differentiating features:

  • pkg, sysrc, cmd, pf, cp and fstab sub-commands.
  • container targeting system.
  • firewall integration.
  • DNS integration.
  • template-based automation syntax.
  • git-based checkout of container templates.
  • pre, post, pkg, sysrc, cmd, pf, and fstab hooks (create).

Additional Resources:

You can’t perform that action at this time.