Docker on FreeBSD
Docker is a popular container tool and ecosystem, comparable to FreeBSD Container & Jail tools, used to simplify and speed-up the creation, deployment and management of isolated application environments.
Work is currently in-progress to develop a FreeBSD Containers: Jail runtime implementation ("runj") and FreeBSD OCI Container Specification necessary to integrate FreeBSD support into the broader Docker ecosystem.
runj is officially supported by containerd, supports Linux Jails and experimental network support, see runj for more detail.
Contact
- IRC: #freebsd-docker and #bhyve channels on Libera Chat.
Current status
Currently, Docker needs VirtualBox installed and configured.
The sysutils/docker-machine port will create a new VirtualBox machine running Linux, and then docker will create containers inside that virtual machine.
You will need to install and configure VirtualBox as described in the FreeBSD handbook, including adding vboxnet_enable="YES" to /etc/rc.conf, and setting permissions for the intended user to access /dev/vboxnetctl.
Also create or edit /usr/local/etc/vbox/networks.conf and either make sure it allows the 192.168.99.1/24 network range used by docker-machine:
* 192.168.99.1/24
(note the asterisk in front matters!), or configure docker-machine to use whichever other network range VirtualBox does allow. The VirtualBox manual describes the format of that file.
Install sysutils/docker-machine and create a virtual machine to run Docker containers:
$ docker-machine create default
Then install sysutils/docker, and use the usual docker commands to build, pull and run Docker containers.
Dockerbox
Alternatively, you can use dockerbox as the dockerd-running VM, which is basically the same concept as the above Virtualbox dockerd VM, but running in bhyve. After installing dockerbox, mangage dockerbox with service and connect to it on 10.0.0.3.
$ service dockerbox start $ export DOCKER_HOST=10.0.0.3 $ docker run helloworld
Please note that this is still a work-in-progress. See more in dockerbox.
Past Work
A FreeBSD Docker port was originally made available in 2015, relying on ZFS, Jails and 64bit support for the Linux compatibility layer introduced in June that year. A genuine Docker, it supported containers from the official docker.io repository.
github: kvasdopil/docker (Original Docker FreeBSD Port)
FreeBSD Port: sysutils/docker-freebsd (Deleted: Jan 2020)
At last update, Docker (docker-freebsd port) was marked broken due to the following build error:
.gopath/src/github.com/docker/docker/pkg/system/mknod.go:12:22: cannot use dev (type int) as type uint64 in argument to syscall.Mknod
A code review was opened in 2019 updating Docker to a later versions, but progress stalled.
Requirements
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.
FreeBSD 11.1-RELEASE or newer, specifically any version after preliminary support for x86-64 Linux binaries was added.
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
sqlite3: 3.8.10.2
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 startIf 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 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 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
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
920bc5fbb45c centos "/bin/bash" 9 seconds ago Up 8 seconds jolly_poincare
# jls
JID IP Address Hostname Path
3 172.17.0.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 NAME USED AVAIL REFER MOUNTPOINT zroot 55K 3.75G 19K /zroot # zpool list NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT 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% /
Networking
# docker run -t -i centos ping -c2 8.8.8.8 WARNING: setsockopt(ICMP_FILTER): Protocol not available WARNING: your kernel is veeery old. No problems. PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data. 64 bytes from 8.8.8.8: icmp_seq=1 ttl=56 time=15.0 ms 64 bytes from 8.8.8.8: icmp_seq=2 ttl=56 time=14.1 ms ... # docker run -t -i centos /bin/bash echo "nameserver 8.8.8.8" >> /etc/resolv.conf ... ping sun.com PING sun.com (156.151.59.35) 56(84) bytes of data. 64 bytes from lb-legacy-sun-cms-ucf.oracle.com (156.151.59.35): 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 https://index.docker.io/v1/search?q=centos: x509: failed to load system roots and no roots provided
The "ca_root_nss" package is not installed.
VBoxManage: error: Code E_ACCESSDENIED (0x80070005) - Access denied (extended info not available) VBoxManage: error: Context: "EnableStaticIPConfig(Bstr(pszIp).raw(), Bstr(pszNetmask).raw())" at line 242 of file VBoxManageHostonly.cpp
You either don't have permissions to access /dev/vboxnetctl, or VirtualBox isn't allowing the IP address and netmask wanted by docker-machine. Edit /usr/local/etc/vbox/networks.conf as described earlier, and populate the correct addresses, or configure docker-machine to use a different address and netmask which VirtualBox allows.
Related
Operating-system level virtualization, including Application Containers and Jails
External References
Codebases
FreeBSD on Docker Hub
lexaguskov/freebsd: container image (hub.docker.com)
kazuyoshi/freebsd-minimal: container image (hub.docker.com)