Docker on FreeBSD


by ross at 23:40:26 on July 26, 2017

There are two approaches to running Docker on FreeBSD. Fisrt one was created back in 2015 and it was a native port of Docker engine to FreeBSD. It was an ambitious project but nobody stepped forward to continuously port the never-ending flow of upstream code to FreeBSD. So the port still exists (sysutils/docker-freebsd) but it wasn't updated since 2015 and it is Docker v1 (it is v17 as of 2017).

The other approach is to use official way of running Docker on platforms other than Linux. Well, somewhat official as Docker still does not support FreeBSD as a host officially. This is docker-machine tool which in turn will use VirtualBox to run a virtual machine with Linux and Docker engine. docker utility on the host will communicate with the engine inside VB where all the work will be done. This article describes what needs to be done to start using it.


Before we begin you need VirtualBox installed. Do not skip adding /boot/loader.conf and /etc/rc.conf lines mentioned on that page.

You won't need user inteface or anything, docker-machine will do all the work, just make sure VirtualBox is present and ready to be used.


# pkg install docker docker-machine docker-compose

That is all for root. Docker will be used by a regular user so run the following commands as this user.

Docker will store its stuff in ~/.docker. You might not want the virtual machine image files to live in your home, in this case just create a symlink:

> mkdir ~/.docker
> ln -s /storage/docker ~/.docker/machine

With the command above all the files will go to /storage/docker (give your user write permissions).

Create the machine

> docker-machine create --driver virtualbox \
    --virtualbox-memory 2048 \
    --virtualbox-cpu-count 2 \
    --virtualbox-disk-size 102400 \
    --virtualbox-hostonly-cidr "" \

Here's the example. We are creating machine named docker1. It is using VirtualBox driver, the vm has 2G of memory, 2 cores and 100G of disk space. docker-machine setups VirtualBox to use host-only network adapter (it will create vboxnet0 interface on the host automatically) and we are instructing it to use as the address of this adapter — change it to what suits your needs or omit this flag (default is

And basically that is all. Check if it is running:

> docker-machine ls
NAME      ACTIVE   DRIVER       STATE     URL                     SWARM   DOCKER        ERRORS
docker1   -        virtualbox   Running   tcp://           v17.06.0-ce

If you do open VirtualBox interface you will find a virtual machine named docker1 running. You can start/stop/whatever your machine using docker-machine utility.

Connect to the machine

docker utility by default tries to talk to Docker engine running on the same host. However with specific environment variables you can instruct it to talk to other host. docker-machine can export these variables for you.

> eval `docker-machine env docker1`

This will import into your current shell session variables needed for docker utility to talk to the machine docker1. From now on you just run docker command as usual:

> docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b04784fba78d: Pull complete 
Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:

For more examples and ideas, visit:

Everything docker-related should work now. But it is a new port so there might be bugs, for one I wasn't able to ping anything but 172.17.x.x from a running Docker container, although TCP does work (apt-get in Debian containers worked out of the box).


why it need VBox?
-- metoo
Tuesday, November 7, 2017, 14:10:33
Because Docker is not supported natively in FreeBSD (officially). It uses VBox to run Docker vm which is a Linux distro actually.
-- ross
Wednesday, November 8, 2017, 4:41:55
Not working when using pf firewall, please describe firewall config

-- Tony
Friday, February 23, 2018, 11:36:45
If someone have the same problems try to add

pass in on $vbox_if proto tcp from any to any
pass out on $vbox_if proto tcp from any to any

to your pf.conf
-- Tony
Friday, February 23, 2018, 12:09:47
If you get

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

error after running `docker run hello-world`

Then change you output of

#eval 'docker-machine env docker1'
export DOCKER_HOST="tcp://"
export DOCKER_CERT_PATH="/root/.docker/machine/machines/docker1"
export DOCKER_MACHINE_NAME="docker1"

setenv DOCKER_HOST "tcp://"
setenv DOCKER_CERT_PATH "/root/.docker/machine/machines/docker1"
setenv DOCKER_MACHINE_NAME "docker1"

as `export` command was not found on my system
-- Tony
Friday, February 23, 2018, 12:38:21
And run each line with setenv command
-- tony
Friday, February 23, 2018, 12:39:17
You'll receive this "error" if you are using a non-bash shell such as csh or tcsh. They have different commands for setting environment variables.
Friday, September 28, 2018, 22:41:39
Sry, my english is not that good. I went to the instructions and get the following error message:

Unable to start the VM: /usr/local/bin/VBoxManage startvm docker1 --type headless failed:
VBoxManager: error: The virtual machine 'docker1' has terninated unexpectedly during startup with exit code 1 (0x1)
VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component MachineWrap, interface IMachine
-- onotop
Sunday, January 20, 2019, 17:38:41
Thank you SO MUCH... Having working docker on GhostBSD (FreeBSD based) is great !!
-- sponix
Thursday, January 24, 2019, 7:17:16
Excellent instructions! Confirmed for new install of 12.0-RELEASE. Thanks!
-- sean
Tuesday, May 7, 2019, 11:03:35
guys, when I run docker-machine create like above, I can never get an IP address:
(docker1) Check network to re-create if needed...
(docker1) Found a new host-only adapter: "vboxnet1"
(docker1) Waiting for an IP...
Error creating machine: Error in driver during machine creation: Too many retries waiting for SSH to be available. Last error: Maximum number of retries (60) exceeded

I run the command as a standard user with pf disabled. When I run it with "doas", same thing happens.
Please advise!
-- BBKing
Wednesday, August 7, 2019, 13:20:45