Docker on FreeBSD

Docker is a popular application containment environment on GNU/Linux that is available on FreeBSD as of June, 2015. Docker on FreeBSD relies heavily on ZFS, jail and the 64bit Linux compatibility layer that was introduced in June, 2015. Docker on FreeBSD is genuine Docker and retrieves containers from the official repository. Consult the official Docker documentation and resources for further assistance.


Docker on FreeBSD is experimental.

Limitations of the 64bit Linux compatibility subsystem will impact some Linux ABI containers and your testing and feedback is appreciated to help resolve any such issues.

The freebsd-virtualization mailing list, as well as the IRC channels #freebsd-docker and #bhyve on are good places to participate.


FreeBSD 11.1-RELEASE or newer, specificially any version after preliminary support for x86-64 Linux binaries was addded.

Repository contains the port of Docker for FreeBSD.

sysutils/docker-freebsd contains the FreeBSD port for Docker. Docker port.

Installation and Use

The following steps, executed with root privileges, should provide a working Docker environment:

# pkg install docker-freebsd ca_root_nss
New packages to be INSTALLED:
        docker-freebsd: 06252015
        ca_root_nss: 3.19.1_1
        bash: 4.3.39_2
        indexinfo: 0.2.3
        gettext-runtime: 0.19.4
        go: 1.4.2,1
        readline: 6.3.8

The process will require 155 MiB more space.
26 MiB to be downloaded.
You will need to create a ZFS dataset on /usr/docker

# zfs create -o mountpoint=/usr/docker <zroot>/docker 

And lastly enable the docker daemon
# sysrc -f /etc/rc.conf docker_enable="YES"
# service docker start

If you're not already using ZFS, you will need to create a raw disk, otherwise follow the above steps as instructed in the package message.

Using Docker as a normal user

In order to use Docker as a non-root/non-super user account, your user must be in the operator group:

# pw usermod <you> -G operator

After changing your user's group membership, log out and back in. Once logged back in docker ps should be usable (for example) as a non-superuser.

% docker version
Client version: 1.7.0-dev
Client API version: 1.19
Go version (client): go1.4.2
Git commit (client): 582db78
OS/Arch (client): freebsd/amd64
Server version: 1.7.0-dev
Server API version: 1.19
Go version (server): go1.4.2
Git commit (server): 582db78
OS/Arch (server): freebsd/amd64

% docker search centos
NAME                      DESCRIPTION                     STARS   OFFICIAL   AUTOMATED
centos                    The official build of CentOS.   1122    [OK]
ansible/centos7-ansible   Ansible on Centos7              45      [OK]

% docker pull centos
latest: Pulling from centos
f1b10cd84249: Pull complete 
c852f6d61e65: Pull complete 
7322fbe74aa5: Already exists 
centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.
Digest: sha256:57554136c655abb33ecb7bb790b1db0279668d3763c3b81f31bc6c4e60e4a1f3
Status: Downloaded newer image for centos:latest

% docker images
centos            latest   7322fbe74aa5   4 weeks ago   172.2 MB

% docker run -t -i centos /bin/bash
[root@ /]# uname -a
Linux  2.6.32 FreeBSD 11.0-CURRENT #5 r285594: Tue Jul 14 23:30:11 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux

From another terminal:

% docker ps
920bc5fbb45c  centos  "/bin/bash"  9 seconds ago  Up 8 seconds         jolly_poincare

# jls
   JID  IP Address   Hostname   Path
     3              /usr/docker/zfs/graph/920bc5fbb45c

# zfs list
zroot/docker                                                                         119M   107G  6.02M  /usr/docker
zroot/docker/03a7a57df9197f242484375c4bc2149248ded5aaafc4feb8e472d6774d495530          8K   107G   112M  legacy
zroot/docker/03a7a57df9197f242484375c4bc2149248ded5aaafc4feb8e472d6774d495530-init   128K   107G   112M  legacy

# mount
x220i/docker on /usr/docker (zfs, local, noatime, nfsv4acls)
x220i/docker/d03bcd7082d91179f58c8738f598f5af4db00307a47b5db255aefd30790e8bdc on /usr/docker/zfs/graph/d03bcd7082d9 (zfs, local, noatime, nfsv4acls)
linprocfs on /usr/docker/zfs/graph/d03bcd7082d9/proc (linprocfs, local)
linsysfs on /usr/docker/zfs/graph/d03bcd7082d9/sys (linsysfs, local)
devfs on /usr/docker/zfs/graph/d03bcd7082d9/dev (devfs, local, multilabel)

Creation of a ZFS root using raw disk

These steps are only necessary if you're not already using ZFS.

The following steps allocate a 4G ZFS root file system using a raw disk, it allows you to test quickly.

# kldload zfs
# dd if=/dev/zero of=/usr/local/dockerfs bs=1024K count=4000
# zpool create -f zroot /usr/local/dockerfs
# zfs list
zroot    55K  3.75G    19K  /zroot
# zpool list                                                                                                                                                                             
zroot  3.88G  11.8M  3.86G     0%         -     0%  1.00x  ONLINE  -
# zfs create -o mountpoint=/usr/docker zroot/docker

FreeBSD under Docker

# docker search freebsd
NAME                      DESCRIPTION                STARS   OFFICIAL   AUTOMATED
lexaguskov/freebsd        FreeBSD operating system   0

# docker pull lexaguskov/freebsd
Status: Downloaded newer image for lexaguskov/freebsd:latest

# docker run -t -i lexaguskov/freebsd /bin/csh
# df -h
Filesystem                                                                      Size   Used   Avail Capacity  Mounted on
zroot/docker/485f9654f69d5e9909344dd823dd0608f3734c433b667e9ec04492cc61ddbcfa   107G   176M   107G  0%        /


# docker run -t -i centos ping -c2
WARNING: setsockopt(ICMP_FILTER): Protocol not available
WARNING: your kernel is veeery old. No problems.
PING ( 56(84) bytes of data.
64 bytes from icmp_seq=1 ttl=56 time=15.0 ms
64 bytes from icmp_seq=2 ttl=56 time=14.1 ms

# docker run -t -i centos /bin/bash
echo "nameserver" >> /etc/resolv.conf
PING ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=244 time=51.5 ms

Common Errors

Missing /usr/docker! Please create / mount a ZFS dataset at this location.

The "docker" dataset needs to be created.

Error response from daemon: Get x509: failed to load system roots and no roots provided

The "ca_root_nss" package is not installed.

External References


FreeBSD on Docker Hub

FreeBSD Docker on News and Article

Docker (last edited 2017-08-12 02:21:54 by LiWenHsu)