Running with Docker

This page explains the additional features and differences compared to running Krill with Cargo that you need to be aware of when running Krill with Docker.

Get Docker

If you do not already have Docker installed, follow the platform specific installation instructions via the links in the Docker official “Supported platforms” documentation.

Fetching and Running Krill

The docker run command will automatically fetch the Krill image for your CPU architecture the first time you use it, and so there is no installation step in the traditional sense. The docker run command can take many arguments and can be a bit overwhelming at first.


The CPU architectures supported by the Krill Docker image are shown on the Docker Hub Krill page per Krill version (aka Docker “tag”) in the OS/ARCH column.

The command below runs Krill in the background and shows how to configure a few extra things like log level and volume mounts (more on this below).

$ docker run -d --name krill -p \
  -e KRILL_LOG_LEVEL=debug \
  -e \
  -e KRILL_AUTH_TOKEN=correct-horse-battery-staple \
  -e TZ=Europe/Amsterdam \
  -v krill_data:/var/krill/data/ \
  -v /tmp/krill_rsync/:/var/krill/data/repo/rsync/ \


The Docker container by default uses UTC time. If you need to use a different time zone you can set this using the TZ environment variable as shown in the example above.

Admin Token

By default Docker Krill secures itself with an automatically generated admin token. You will need to obtain this token from the Docker logs in order to manage Krill via the API or the krillc CLI tool.

$ docker logs krill 2>&1 | fgrep token
docker-krill: Securing Krill daemon with token <SOME_TOKEN>

You can pre-configure the token via the auth_token Krill config file setting, or if you don’t want to provide a config file you can also use the Docker environment variable KRILL_AUTH_TOKEN as shown above.

Running the Krill CLI


Using a Bash alias with <SOME_TOKEN> you can easily interact with the locally running Krill daemon via its command-line interface (CLI):

$ alias krillc='docker exec \
  -e KRILL_CLI_TOKEN=correct-horse-battery-staple \
  nlnetlabs/krill krillc'

$ krillc list -f json
  "cas": []


The Docker image can also be used to run krillc to manage remote Krill servers. Using a shell alias simplifies this considerably:

 $ alias krillc='docker run --rm \
   -e KRILL_CLI_TOKEN=correct-horse-battery-staple \
   -v /tmp/ka:/tmp/ka nlnetlabs/krill krillc'

$ krillc list -f json
   "cas": []

Note: The -v volume mount is optional, but without it you will not be able to pass files to krillc which some subcommands require, e.g.

$ krillc roas update --ca my_ca --delta /tmp/

Service and Certificate URIs

The Krill service_uri and rsync_base config file settings can be configured via the Docker environment variable KRILL_FQDN as shown in the example above. Providing KRILL_FQDN will set both service_uri and rsync_base.


Krill writes state and data files to a data directory which in Docker Krill is hidden inside the Docker container and is lost when the Docker container is destroyed.


To protect the data you can write it to a persistent Docker volume which is preserved even if the Krill Docker container is destroyed. The following fragment from the example above shows how to configure this:

docker run -v krill_data:/var/krill/data/


Some of the data files written by Krill to its data directory are intended to be shared with external clients via the rsync protocol. To make this possible with Docker Krill you can either:

Mounting the data in a host directory:

docker run -v /tmp/krill_rsync:/var/krill/data/repo/rsync

Sharing via a named volume:

docker run -v krill_rsync:/var/krill/data/repo/rsync


Krill logs to a file by default. Docker Krill however logs by default to stderr so that you can see the output using the docker logs command.

At the default warn log level Krill doesn’t output anything unless there is something to warn about. Docker Krill however comes with some additional logging which appears with the prefix docker-krill:. On startup you will see something like the following in the logs:

docker-krill: Securing Krill daemon with token ba473bac-021c-4fc9-9946-6ec109befec3
docker-krill: Configuring /var/krill/data/krill.conf ..
docker-krill: Dumping /var/krill/data/krill.conf config file
docker-krill: End of dump

Environment Variables

The Krill Docker image supports the following Docker environment variables which map to the following krill.conf settings:

Environment variable

Equivalent Krill config setting




service_uri and rsync_base





To set these environment variables use -e when invoking docker, e.g.:

docker run -e KRILL_FQDN=

Using a Config File

Via a volume mount you can replace the Docker Krill config file with your own and take complete control:

docker run -v /tmp/krill.conf:/var/krill/data/krill.conf

This will instruct Docker to replace the default config file used by Docker Krill with the file /tmp/krill.conf on your host computer.

Running as a non-root user

The Krill Docker image supports running Krill as the non-root user “krill” (UID 1012, GID 1012) but for backward compatibility runs by default as user “root”.

One can specify that Krill should run as user “krill” like so:

docker run -u krill

Running as a different username, UID and/or GID requires building the Docker image yourself, e.g.:

cd path/to/krill/git/clone
docker build -t mykrill \
  --build-arg RUN_USER=myuser \
  --build-arg RUN_USER_UID=1234 \
  --build-arg RUN_USER_GID=5678 \


If running Krill inside the container as a non-root user and mounting the host filesystem or a Docker volume under the Krill data directory you must ensure that the Krill data directory and subdirectories are writable by Krill.