How to run Enclave inside a Docker container, with host networking¶

This guide will tell you how to run Enclave from within a docker container, while providing access to the Enclave network from the host system. This can make it easy to update Enclave and control the resources assigned to it, while still giving you access to the network.

Note

This guide is written for Docker Community Edition 19.03.5.

Install Docker¶

To follow this guide, you will need to have Docker already installed on your local system. This guide is based on running Docker (version 19.03.5) on a fresh installation of Ubuntu 18.04 LTS.

sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt update
sudo apt install docker-ce -y

The Enclave Docker Container¶

We publish the Enclave docker container as enclavenetworks/enclave on DockerHub. The synology-compat tag should be used in almost all cases, unless you want to try the latest beta builds, in which case you can use the unstable tag.

The published dockerfile multi-arch, and is compatible with arm32, arm64 and x64 docker hosts.

Note

You can download our Dockerfile (if you want to inspect it or create your own) from github.

Run the container interactively¶

Run the container to start Enclave. In this command we set the following options:

--cap-add NET_ADMIN and --device /dev/net/tun allows Enclave to create the virtual tap0 adapter, which provides access to the Enclave network.
--net=host allows docker to present the tap0 interface created by Enclave inside the container out to the host operating system, without installing Enclave onto the host.
-e ENCLAVE_ENROLMENT_KEY='XXXXX-XXXXX-XXXXX-XXXXX-XXXXX' sets the ENCLAVE_ENROLMENT_KEY environment variable, and is how you provide your enrolment key to Enclave the first time it runs. Replace the placeholder with an actual enrolment key from the portal.
enclave-config:/etc/enclave/profiles will auto-create a docker volume that stores the Enclave configuration between container executions. Delete the enclave-config volume to "reset" Enclave.

sudo docker run -it \
        --name fabric \
        --cap-add NET_ADMIN \
        --device /dev/net/tun \
        --net=host \
        -e ENCLAVE_ENROLMENT_KEY='XXXXX-XXXXX-XXXXX-XXXXX-XXXXX' \
        -v enclave-config:/etc/enclave/profiles \
        enclavenetworks/enclave:latest

Note

The ENCLAVE_ENROLMENT_KEY environment variable only needs to be provided the first time Enclave is run.

You can run commands against the enclave instance in the docker container using docker exec:

$ docker exec fabric enclave status

Local identity: R899Q

   Release version . . : 2021.1.1.532
   Profile name. . . . : Universe
   Profile location. . : /etc/enclave/profiles/Universe.profile
   Certificate . . . . : CN=R899Q Expires=Never (Perpetual Issue)
   Binding address . . : 0.0.0.0:37873
   Local nameserver. . : listening on 100.110.213.200:53
   Virtual adapter . . : tap0 (#2) BE:18:63:A5:3A:2D
   Virtual address . . : 100.110.213.200
   Virtual network . . : 100.64.0.0/10 (255.192.0.0)
   Capabilities. . . . : enclave\fakearp   active pri=4096 local rewrites=0 peer discards=0
                       : enclave\unicast   active pri=8192 tap eth=0 ipv4=0 ipv6=0 - partners total=0 spoofed origin discards=0
                       : enclave\multicast active pri=8200 igmp membership packets ipv4=0 ipv6=0

Peer: discover.enclave.io

   Peer state. . . . . : Up
   Certificate . . . . : CN=discover.enclave.io Expires=08/06/2024 09:59:59
   Endpoint. . . . . . : Tcp/161.35.171.235:443

While this container is running, your host operating system will be able to communicate with connected peers. Use this container to administer the Enclave network.

Use tap0 on the host operating system¶

Using ifconfig check to see if the tap0 interface is present on the host adapter, any applications on the host operating system will transparently be able to communicate with partners on the Enclave network. Use docker ps and docker attach to reconnect to the Enclave container and administer the network as required.

$ ifconfig

tap0: flags=67<UP,BROADCAST,RUNNING>  mtu 2800
        inet 100.90.154.224  netmask 255.192.0.0  broadcast 0.0.0.0
        inet6 fe80::605f:16ff:fe90:20a8  prefixlen 64  scopeid 0x20<link>
        ether 62:5f:16:90:20:a8  txqueuelen 1000  (Ethernet)
        RX packets 98  bytes 17732 (17.7 KB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 18  bytes 1412 (1.4 KB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Having problems? Contact us at support@enclave.io or get help and advice in our community support channels.

Last updated Aug 19, 2021