Skip to main content

Search

Customising Docker Canaries

Overview

This page describes environment options for customising the behaviour of Docker Canaries. These environment variables affect the behaviour of the container and are independent of the container orchestrator.

Passing in environment variables

Specifying the environment variables will depend on your container orchestrator. For example, in a Kubernetes Pod specification, your environment variables are provided in the configuration file:

apiVersion: v1
kind: Pod
metadata:
  name: canarypod
  namespace: default
spec:
  containers:
    - name: canarydocker
      image: thinkstcanary/dockercanary@sha256:...
      imagePullPolicy: Always
      env:
      - name: CONSOLE_PUBLIC_KEY
        value: "..."
      - name: LISTEN_DOMAIN
        value: "..."
      - name: AUTOCOMMISSION_TOKEN
        value: "..."

On the other hand, if you're launching directly from the CLI with Docker: you might use something like:

$ docker run -e LISTEN_DOMAIN=... -e CONSOLE_PUBLIC_KEY=... -e AUTOCOMMISSION_TOKEN=... thinkstcanary/dockercanary@sha256:...

Required Environment Variables

These variables are required and your Docker bird will fail to start if they're not supplied. In the generated configurations for Kubernetes and the Docker CLI, these are always included:

  • CONSOLE_PUBLIC_KEY
  • LISTEN_DOMAIN

Please do not modify these values, if you do so then your Docker bird will be unable to communicate with its Console. Poor bird!

Optional Environment Variables

The following variables are optional and are not required.

  • AUTOCOMMISSION_TOKEN 
  • INITIAL_PROFILE
  • INITIAL_SETTINGS
  • NODE_ID_SEED
  • VOLUME_MOUNT

Below we describe each in more detail.

AUTOCOMMISSION_TOKEN

This variable defines the auto commission token for a specific Flock. If present and valid, when the container is launched the new bird will be automatically placed into the target Flock without any intervention required.

The token is a random string. A sample configuration would look like this:

AUTOCOMMISSION_TOKEN=f2d5c7e2ea9aec23df5d

See the Auto Commission page for more information on how to enable this feature.

NODE_ID_SEED

Note: This variable is reliant on the AUTOCOMMISSION_TOKEN to be present in your launch commands.

The NODE_ID_SEED variable will ensure that your container bird is persistent across stops and starts, even when moved across nodes in a Kubernetes cluster. It makes the container's identifier (node_id) deterministic, which is necessary for persistence. When a container Canary with both a NODE_ID_SEED and a valid AUTOCOMMISSION_TOKEN restarts, it will load its previous configuration from the console as part of the initialisation process.
NODE_ID_SEED is any valid integer value, but must be unique per running Canary. A sample configuration would look like this:

NODE_ID_SEED=1

Requires Docker Canary version 3.7.4 or higher

INITIAL_PROFILE

Other platform types require Canaries to first check-in with the Console, before settings are pushed from the Console. The INITIAL_PROFILE variable lets the Docker administrator launch the Canary using a built-in profile. Simply set it as follows to use, say, the CUPS profile:

INITIAL_PROFILE=cups

The currently supported list of profiles names is:

  • bare
  • canon-image-runner-2525-multifunction-printer
  • centos7basic
  • checkpoint-mobile-vpn
  • cisco-router
  • cisco-voip
  • cisco-vpn
  • citrix-gateway
  • cups
  • dell-idrac
  • dell-switch
  • diskstation-nas
  • f5-gateway
  • hpilo
  • jboss
  • jenkins
  • joomla
  • kibana
  • linux-db
  • linux-proxy
  • linux-std
  • merry-christmas
  • oracle-linux-6
  • oracle-linux-7
  • oracle-linux-8
  • paloalto-firewall
  • pulsevpn
  • sonicwall-firewall
  • splunk-linux
  • splunk-windows
  • vmware-server
  • zos-mainframe

The INITIAL_PROFILE configuration option can be used in conjunction with INITIAL_SETTINGS (see below for more details).

INITIAL_SETTINGS

Other platform types require Canaries to first check-in with the Console, before settings are pushed from the Console. The INITIAL_SETTINGS variable lets the Docker administrator define Canary settings directly at launch.

For example, if you wish your Docker Canary to start up with the SSH and Redis modules running, INITIAL_SETTINGS will be of interest to you.

It's important to note that these settings are only applied at container launch. Once the Docker bird is running, it's still possible to push settings from the Console to the Docker bird. In this way, settings can diverge over time from the container's INITIAL_SETTINGS.

The format of INITIAL_SETTINGS is a collection of key-value configuration pairs in JSON-format, encoded as Base64. For example, to start a Canary with SSH enabled and a specific SSH banner (it defaults to disabled), the configuration pairs in JSON are:

{ "ssh.enabled": true, "ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4" }

Converting this to Base64 gives us:

eyAic3NoLmVuYWJsZWQiOiB0cnVlLCAic3NoLnZlcnNpb24iOiAiU1NILTIuMC1PcGVuU1NIXzUuMXAxIERlYmlhbi00IiB9Cg==

Finally, assign this to the INITIAL_SETTINGS environment variable in your container orchestrator:

INITIAL_SETTINGS=eyAic3NoLmVuYWJsZWQiOiB0cnVlLCAic3NoLnZlcnNpb24iOiAiU1NILTIuMC1PcGVuU1NIXzUuMXAxIERlYmlhbi00IiB9Cg==

A sample of possible configuration values is available here.

When both INITIAL_PROFILE and INITIAL_SETTINGS are specified, INITIAL_PROFILE is applied first, and INITIAL_SETTINGS are applied afterwards. Therefore INITIAL_SETTINGS can override any settings configured by INITIAL_PROFILE.

VOLUME_MOUNT

Containers do not have persistent storage by default. Persistent storage is heavily dependent on the container environment, and even the notion of persistence varies (e.g. whether it survives a node failure or not).

Our Docker Canaries do not assume persistence by default. Each time the container is launched it expects that it's a fresh bird.

You can alter this behaviour by mapping in a volume to the running container, and telling the Canary about it with the VOLUME_MOUNT variable. If VOLUME_MOUNT is defined, the Docker bird will write its data to the volume, and rely on the container environment to ensure it's persisted.

If you want persistent volumes, we recommend mapping the directory /data to a persistent volume, as /data is guaranteed to not clash with other directory names in the Docker Canary.

Here's a very basic example in Kubernetes land. Assuming a PersistentVolume (e.g. canary-pv-volume) and PersistentVolumeClaim (e.g. canary-pv-volume-claim) have already been defined, you can configure a Docker bird to use them with:

apiVersion: v1
kind: Pod
metadata:
  name: canarypod
  namespace: default
spec:
  volumes:
    - name: canary-pv-volume
      persistentVolumeClaim:
        claimName: canary-pv-volume-claim
  containers:
    - name: canarydocker
      image: thinkstcanary/dockercanary@sha256:...
      imagePullPolicy: Always
      env:
        ...
      - name: VOLUME_MOUNT
        value: "/data"
      volumeMounts:
        - mountPath: "/data"
          name: canary-pv-volume

Running container birds as part of a deployment

In a Kubernetes Deployment specification, replicas can be configured for a more robust experience

A sample deployment configuration can be found below:

# deployment.yaml

apiVersion: v1
kind: Secret
metadata:
  name: canarydockercreds
  namespace: default
data:
  .dockerconfigjson: ey..==
type: kubernetes.io/dockerconfigjson
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: thinkst-deployment
  labels:
    app: canary
spec:
  replicas: 3
  selector:
    matchLabels:
      app: canary
  template:
    metadata:
      labels:
        app: canary
    spec:
      containers:
      - name: canarydocker
        image: docker.io/thinkstcanary/dockercanary@sha256:ee..2c
        imagePullPolicy: Always
        env:
        - name: CONSOLE_PUBLIC_KEY
          value: "..."
        - name: LISTEN_DOMAIN
          value: "abc123456xyz.cnr.io"
        - name: AUTOCOMMISSION_TOKEN
          value: "aabbcc112233" # Canaries will be automatically commissioned into the Default Flock flock
        - name: NODE_ID_SEED
          value: "2" # Make the Canary persistent across container restarts. Use a unique value for each individual container.
      imagePullSecrets:
      - name: canarydockercreds
Was this article helpful?
1 out of 1 found this helpful
Return to top