Cloudflared

This repository is archived. Cloudflare announced the removal of the cloudflared proxy-dns command from all new releases starting February 2, 2026, citing a security vulnerability in an underlying DNS library. There is no point maintaining a docker image that wraps a command that no longer exists in current upstream releases.

The image on Docker Hub isn't going anywhere and existing releases of cloudflared made before February 2, 2026 will keep working, but there won't be any new releases or maintenance. If you're setting something up fresh, consider dnscrypt-proxy via the klutchell/dnscrypt-proxy-docker image instead. Read the full write-up on my blog.

a docker container which runs the cloudflared proxy-dns at port 5054 based on alpine with some parameters to enable DNS over HTTPS proxy which can be used in combination with different DNS based adblocker;

• pi-hole
• blocky
• ...

Originally based on tutorials from Oliver Hough and Scott Helme but overtime I switched my setup towards blocky

run

$ docker run --name cloudflared --rm -p 5054:5054/udp visibilityspots/cloudflared:latest

run with docker-compose

$ docker-compose up

custom upstream DNS service

$ docker run --name cloudflared --rm -p 5054:5054/udp -e UPSTREAM1=https://dns.google/dns-query visibilityspots/cloudflared:latest

custom port

$ docker run --name cloudflared --rm -p 5053:5053/udp -e PORT=5053 visibilityspots/cloudflared:latest

dualstack ipv4/ipv6

$ docker run --name cloudflared --rm -p 5054:5054/udp -e ADDRESS=:: visibilityspots/cloudflared:latest

limit connections to upstream dns servers

$ docker run --name cloudflared --rm -p 5054:5054/udp -e MAX_UPSTREAM_CONNS=5 visibilityspots/cloudflared:latest

test

$ dig +short @10.0.0.2 -p 5054 visibilityspots.org
13.225.238.129
13.225.238.53
13.225.238.9
13.225.238.61

build

Build against pinned upstream release

$ docker build -t visibilityspots/cloudflared:latest .

Build against a specific upstream release

$ docker build -t visibilityspots/cloudflared:latest . --build-arg UPSTREAM_RELEASE_TAG=2021.5.10

buildx

$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
$ docker buildx build -t visibilityspots/cloudflared:latest --platform linux/amd64,linux/arm/v6,linux/arm/v7 --push .

dgoss

I wrote some tests in a goss.yaml file which can be executed by dgoss to test the created image

$ dgoss run visibilityspots/cloudflared:latest
INFO: Starting docker container
INFO: Container ID: 792bc39d
INFO: Sleeping for 0.2
INFO: Container health
INFO: Running Tests
User: cloudflared: exists: matches expectation: true
Process: cloudflared: running: matches expectation: true
Command: uname -a: exit-status: matches expectation: 0
Command: cloudflared --version: exit-status: matches expectation: 0
Command: cloudflared --version: stdout: matches expectation: ["cloudflared version 2023.8.2 (built September 2023)"]
Package: ca-certificates: installed: matches expectation: true
DNS: visibilityspots.org: resolvable: matches expectation: true


Total Duration: 0.092s
Count: 7, Failed: 0, Skipped: 0
INFO: Deleting container

act

using act for local testing of the written github actions makes my life and commit history a lot easier;

$ act -l
Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    test      CI             main.yaml      push
1      buildx  buildx    CI             main.yaml      push

$ act -j test
[CI/test] 🚀  Start image=catthehacker/ubuntu:act-latest
.
.
.
[CI/test]   ✅  Success - Main Execute Goss tests
[CI/test] 🏁  Job succeeded

License

Distributed under the MIT license