There's no reason to be limited to either hardware,Virtual, or Cloud birds, you can run Canaries in Docker containers too! This brings a bunch of interesting properties, including the ability to have your container orchestrator preload settings on your birds, and maintain a fixed number of Canaries no matter the performance of any individual node in your container cluster.
Of course, they are also the perfect way to get a heads up when someone compromises one container and is snooping around the other pods.
This page outlines the requirements for Docker birds, explains how to enable them for your Console, provides instructions on running them, and highlights the differences between Docker birds and regular birds.
Requirements for Docker Birds
There are very few requirements to run Docker birds. Your Console will need to have Docker enabled by our support team, and you need to have a container environment capable of running standard Docker images. Docker birds are known to run in these environments:
- Kubernetes 1.18
- Kubernetes 1.22
- Docker Desktop for Mac 20.10.8
- Docker Engine 18.09.6, 20.10.8
These are only the environments in which Docker birds were tested; it is very likely that the birds will run in additional environments where Docker is the underlying container engine. The birds are shipped in V2 (schema version 2) format, which was introduced in 2016 with the release of Docker 1.10.
Enabling Docker Birds
In contrast to the various Cloud platforms, we don't need any information from you except your consent and a willingness to explore. Give us the word, and we'll get your Docker birds added to your Console. Once our Support team confirms that Docker is enabled for your Console, you're good to go.
Where are the images hosted?
The Docker images are hosted in a private repo at Docker Hub. When we enable Docker Canaries for you, we generate unique Docker Hub credentials for your Console, which allow you to pull our private images.
Launching Docker Birds
After Docker birds have been enabled on your Console, head over to How do I launch a Docker Canary? for a step-by-step guide.
Customising your Docker Bird
Docker Canaries have a few tricks up their sleeves. You can pass in configuration data that lets the bird launch with services already enabled (in contrast to other bird types where you need to wait for the device to first be commissioned on the Console.) You can also persist configuration across container restarts in certain circumstances.
For these and more, see the Customising Docker Birds page.
Limitations
Docker Canaries run inside a container, so they do not have the same level of control over their network stack as hardware, virtual and cloud Canaries. As a result, Docker Canaries do not currently support IP Stack fingerprinting, Windows personalities, the firewall module, the portscan module, Windows File Share module, or remote webroot uploads as well as DNS over HTTPS (DoH).
How do I update my Docker Canary?
Docker Canaries continue running their existing image until the container is recreated with a newer version.
We recommend using thinkstcanary/dockercanary:latest in your deployment configuration, so you don’t need to change the image reference for each release. Repository credentials and deployment examples are available in the Add New Docker Canary flow in your Canary Console.
To update:
- Docker CLI: Pull the latest image, stop the existing container and recreate it.
- Kubernetes: Use imagePullPolicy: Always and replace the existing Pod to fetch the latest image.
Keep your existing environment variables, networking settings, port mappings and other settings when updating.
If your deployment already uses NODE_ID_SEED and AUTOCOMMISSION_TOKEN, keep the same seed and supply a valid auto-commission token for the target Flock. This allows the replacement Canary to retain its identity and retrieve its previous configuration from the Canary Console.
Each running Canary must have a unique seed, so stop the old instance before starting its replacement.
See Customising Docker Canaries for more configuration options when launching container Birds.