Skip to content
This repository has been archived by the owner on May 5, 2022. It is now read-only.

Latest commit

 

History

History
163 lines (119 loc) · 6.05 KB

README.md

File metadata and controls

163 lines (119 loc) · 6.05 KB
Raw

The Docker ACAP

This is the ACAP packaging of the Docker Engine to be run on Axis devices with container support.

Compatability

The Docker ACAP requires a container capable device. You may check the compatibility of your device by running:

ssh root@<axis_device_ip> 'command -v containerd >/dev/null 2>&1 && echo Compatible with Docker ACAP || echo Not compatible with Docker ACAP'

Installing

The recommended way to install this acap is to use the pre-built docker hub image:

docker run --rm axisecp/docker-acap:latest-<ARCH> <camera ip> <rootpasswd> install

Where <ARCH> is either "armv7hf" or "aarch64" depending on camera architecture.

It's also possible to build and use a locally built image. See the Building the Docker ACAP section for more information.

Securing the Docker ACAP using TLS

The Docker ACAP can be run either unsecured or in TLS mode. The Docker ACAP uses TLS as default. Use the "Use TLS" dropdown in the web interface to switch between the two different modes. It's also possible to toggle this option by calling the parameter management API in VAPIX (accessing this documentation requires creating a free account) and setting the root.dockerdwrapper.UseTLS parameter to "yes" or "no".

Note that the dockerd service will be restarted every time TLS is activated or deactivated. Running the ACAP using TLS requires some additional setup, see TLS Setup. Running the ACAP without TLS requires no further setup.

TLS Setup

TLS requires a few keys and certificates to work, which are listed in the subsections below. For more information on how to generate these files, please consult the official docker documentation. Most of these keys and certificates need to be moved to the camera. There are multiple ways to achieve this, for example by using scp to copy the files from a remote machine onto the camera. This can be done by running the following command on the remote machine:

scp ca.pem server-cert.pem server-key.pem root@<axis_device_ip>:/usr/local/packages/dockerdwrapper/

The Certificate Authority (CA) certificate

This certificate needs to be present in the dockerdwrapper package folder on the camera and be named "ca.perm". The full path of the file should be "/usr/local/packages/dockerdwrapper/ca.pem".

The server certificate

This certificate needs to be present in the dockerdwrapper package folder on the camera and be named "server-cert.perm". The full path of the file should be "/usr/local/packages/dockerdwrapper/server-cert.pem".

The private server key

This key needs to be present in the dockerdwrapper package folder on the camera and be named "server-key.perm". The full path of the file should be "/usr/local/packages/dockerdwrapper/server-key.pem".

Client keys and certificates

All the clients also need to have their own private keys. Each client also needs a certificate which has been authorized by the CA. These keys and certificates shall be used when running docker against the dockerd daemon on the camera. See below for an example:

docker --tlsverify \
       --tlscacert=ca.pem \
       --tlscert=cert.pem \
       --tlskey=key.pem \
       -H=<axis_device_ip>:2376 \
       version

Using an SD card as storage

An SD card might be necessary to run the Docker ACAP correctly. Docker containers and docker images can be quite large, and putting them on an SD card gives more freedom in how many and how large images can be stored. Switching between storage on the SD card or internal storage is done by toggling the "SD card support" dropdown in the web interface. It's also possible to toggle this option by calling the parameter management API in VAPIX (accessing this documentation requires creating a free account) and setting the root.dockerdwrapper.SDCardSupport parameter to "yes" or "no".

Toggling this setting will automatically restart the docker daemon using the specified storage. The default setting is to use the internal storage on the camera.

Note that dockerdwrapper requires that Unix permissions are supported by the file system. Examples of file systems which support this are ext4, ext3 and xfs. It might be necessary to reformat the SD card to one of these file systems, for example if the original file system of the SD card is vfat.

Using the Docker ACAP

The Docker ACAP does not contain the docker client binary. This means that all calls need to be done from a separate machine. This can be achieved by using the -H flag when running the docker command.

The port used will change depending on if the Docker ACAP runs using TLS or not. The Docker ACAP will be reachable on port 2375 when running unsecured, and on port 2376 when running secured using TLS. Please read section Securing the Docker ACAP using TLS for more information. Below is an example of how to remotely run a docker command on a camera running the Docker ACAP in unsecured mode:

docker -H=<axis_device_ip>:2375 version

See Client keys and certificates for an example of how to remotely run docker commands on a camera running a secured Docker ACAP using TLS.

Building the Docker ACAP

armv7hf

./build.sh armv7hf

aarch64

./build.sh aarch64

Installing a locally built Docker ACAP

Installation can be done in two ways. Either by using the locally built docker image:

docker run --rm docker-acap:1.0 <camera ip> <rootpasswd> install

Or by manually navigating to device GUI by browsing to the following page (replace <axis_device_ip> with the IP number of your Axis video device)

http://<axis_device_ip>/#settings/apps

Go to your device web page above > Click on the tab App in the device GUI > Add (+) sign and browse to the newly built Docker_Daemon_1_1_0_.eap > Click Install > Run the application by enabling the Start switch.