pot installation guide¶
This is a guide to prepare your FreeBSD installation to use the
pot jail framework.
Many operations need
root privileges. In this guide, we consider to be logged in as
ZFS is mandatory, so if you don't know what it is or you don't have a ZFS pool, please consider to read this quick guide.
pot is usually developed on CURRENT, but it's mainly tested and used on 12.1. It should work also on 11.3, even if the kernel has to be rebuild, to activate
VNET(9), via the
VIMAGE option. If you want to use FreeBSD 11.3, please follow the instruction reported on the handbook to build a custom kernel with the
VIMAGE option enabled.
pot is available as package or port.
The suggested way is to install
pot is to use the package:
# pkg install -y pot
If you want to install it using ports, you can
# cd /usr/ports/sysutils/pot # make install clean
A dependency of
potnet is written in Rust. If you install
potnet via ports, the build dependencies will be built as well, and it can take really long time (depending on the power of you system, it could be several hours).
Enable the resource limit database¶
One really useful feature, needed to improve the isolation between jails, is the resource limit database. This feature is normally disabled (it seems it causes a performance penalty in previous FreeBSD versions), and it can be enabled only at boot. To do so:
# echo kern.racct.enable=1 >> /boot/loader.conf # reboot
An issue with the
vtnet driver can cause poor performance on the network card. If
pot is installed on a VM based on
vtnet, the following command avoids the performance penalty:
# echo hw.vtnet.lro_disable=1 >> /boot/loader.conf
This setting needs a reboot to take effect.
pot framework configuration¶
Under the folder
/usr/local/etc/pot you'll find two files:
pot.default.conf contains all the default values and it shouldn't be touched. All needed changes can be made in the
pot.conf file. This configuration file provide already a brief explanation for all parameters, but here we go deep, explaining them one by one
File system parameters¶
pot is based on ZFS. In the configuration file, 2 parameters are used to let
pot use your ZFS pool correctly.
This parameter is the ZFS dataset that will be used by
pot to store whatever will be needed: jails file systems, bases, and so on. If the dataset doesn't exist, it will be created by the initialization command (See the last chapter).
This parameter is the mountpoint for the
POT_ZFS_ROOT dataset. You shouldn't use a mountpoint that exists and contains file, otherwise the content will become unreachable.
This parameter specifies the mountpoint of the dataset
POT_ZFS_ROOT/cache. This dataset is used only to store
pot images for the
import and the
preparecommand. The default value is the suggested one.
In order to use network types like
private-bridge, some configuration parameters are needed.
pot assumes that all the network traffic is going through one physical network interface. This parameter configures
pot to use the specified network interface.
POT_EXTIF_ADDR (default empty)¶
0.12.0 In case the
POT_EXTIF has multiple addresses,
private-bridge setup will use the first not alias IPv4 address for NAT and redirection. The parameter
POT_EXTIF_ADDR can be used to specify which IPv4 address (assigned to
POT_EXTIF) is the one to be used for NAT and redirection.
0.11.0 This parameter configures the network stack that a
pot will set when created. There are three possible values
pots will use IPv4 only
pots will use IPv6 only
pots will have dual stack support, both IPv4 and IPv6
As explained here, this variable is only used as default value when a
pot is created or cloned and no specific option is provided..
This parameter specifies the IPv4 address of you internal virtual network and is used by the
public-bridge network type only. It's wise to choose a private network segment that doesn't conflict with your current network setup. The default address space is huge, however you can choose the network range that match your needs.
This parameter specifies the netmask relative to the
POT_NETWORK. Theoretically, the netmask can be derived from the
POT_NETWORK. For now, this is not the case, so you have to provide a netmask consistent with the network specified in
This parameter specifies the IP address that will be used as default gateway in your internal virtual network. It has to be part of the network specified in
POT_NETWORK and it will be used as default gateway for all
pots attached to the internal virtual network (
public-bridge network type).
POT_EXTRA_EXTIF (default empty)¶
In case your host has multiple network interfaces connected to multiple network segments, this option allows your
pots to access those network segments. For example, let's say that you have 2 vlan interfaces, called
vlan20is configured as 10.0.20.4/24
vlan30is configured as 10.0.30.8/24
To make those segments accessible, the configuration file should look like:
POT_EXTRA_EXTIF=vlan20 vlan30 POT_NETWORK_vlan20=10.0.20.0/24 POT_NETWORK_vlan30=10.0.30.0/24
alias. All other network types are supported
If you want to check that your network configuration is valid, you can use the utility
# potnet config-check
0.10.4 Every time
pot is invoked, its activity is logged via
syslogd(8). By default, the facility used is
local2, but this parameter can be used to change it.
There are other parameters that are used by some experimental features.
If your host system is using a VPN to reach some network segments, you can add some parameters in order to be able to connect your internal virtual network to those networks
POT_VPN_EXTIF: the name of the network interface of the VPN software tunnel; default:
POT_VPN_NETWORKS: a list of all network segments served by the VPN; default:
If you have multiple network segments, you have to list them all. For instance:
POT_VPN_NETWORKS="192.168.0.0/24 192.168.10.0/24 10.10.0.0/16"
An experimental feature is to provide an internal dns service running in a
pot attached to the internal virtual network. The dns is still a work in progress, however two parameters are already present for this feature:
POT_DNS_NAME: this parameter specifies the name of the
potthat will run the dns; default =>
POT_DNS_IP: this parameter specifies the IP (internal to the
POT_NETWORKthat the "dns
pot" will have; default =>
Initialize the environment¶
The initialization of the environment will:
- Create the ZFS datasets
- Validate the network parameters
pf(4)to be aware of the internal virtual network
If you are already using
pf, I suggest to make a backup of you
pf configuration file.
When ready, you can initialize the environment with the command (use the flag
-v if you want a bit more of verbosity):
# cp /etc/pf.conf /etc/pf.conf.bak # pot init -v
Initialize and test the internal virtual network¶
The internal virtual network is not always active, but it's automatically activated if a
pot configured to use it get started. However, a command is provided to activate the virtual network:
# pot vnet-start
From your host, you can now ping the virtual network default gateway (always reachable from the host):
# ping 10.192.0.1
In order to remove the
pot from your system, a command is provided to make it easy:
# pot de-init
potand it cannot be undone.
Even if not mandatory, it would be nice to know why you removed it. Please, consider to write a feedback email to pizzamig at FreeBSD dot org
- What's wrong with
- What's the missing feature I really need?
- How bad is to use it? How can it be more user-friendly?