Skip to content

Install and run

This page covers installing Conduit from GitHub release assets on Ubuntu 22.04 or 24.04 (amd64). For the smallest config after install, see Minimal configuration.

Release artifacts

Each stable release publishes:

Asset Purpose
conduit-<version>-amd64.tar.gz Production: stripped binaries
conduit-<version>-amd64-debug.tar.gz Debug: unstripped binaries
conduit_<version>_amd64.deb Production Debian package (stripped)
conduit-dbg_<version>_amd64.deb Debug Debian package (unstripped)
SHA256SUMS Checksums for the files above
conduit-<version>.spdx.json Software bill of materials (SBOM)
conduit-<version>.image-digest.txt Container image reference and content digest

Every tarball and package includes four binaries:

  • conduit — DNS dataplane (the service)
  • conduitctl — control plane CLI (validate offline; apply, export, reload, trace, and health when control is enabled)
  • conduit-dnstap-tracer — development/troubleshooting dnstap listener (decodes export to stdout). Not part of the production systemd service; use only for debugging dnstap sinks.
  • conduit-otlp-metrics-tracer — lab OTLP HTTP metrics receiver (/v1/metrics). Not part of the production systemd service; use for OTLP push smoke labs and the performance harness.

Production vs debug differs only by stripped vs unstripped binaries. Use production artifacts on servers; use debug artifacts when you need symbols for gdb or postmortem analysis.

Verify downloads:

sha256sum -c SHA256SUMS

If a rebuild is published, delete old assets from the release page before maintainers re-run the artifact workflow (uploads fail when assets already exist).

Container image

Each stable release publishes a server image to GitHub Container Registry (GHCR):

VERSION=0.20.0   # replace with the release you want
# Image path uses the lowercase GitHub owner, e.g. ghcr.io/egon1024/dnsconduit
docker pull "ghcr.io/<owner>/dnsconduit:${VERSION}"

The same image is also mirrored to Docker Hub under egon1024/dnsconduit (docker pull egon1024/dnsconduit:${VERSION}) — the contents and content digest match GHCR. The latest tag points at the newest stable release of the highest stable major version; pin an explicit ${VERSION} (or a digest) for reproducible interop or production rolls rather than relying on latest.

Pin by digest for reproducibility. The release asset conduit-<version>.image-digest.txt records the image reference and digest. Example run:

docker run --rm -p 53:53/udp -p 53:53/tcp \
  -v "$PWD/conduit.yaml:/etc/conduit/conduit.yaml:ro" \
  "ghcr.io/<owner>/dnsconduit:${VERSION}"

Local development builds (no registry required):

docker build -t conduit:local -f Dockerfile .

The interop correctness harness pins this image; see Interop correctness matrix.

Install from tarball

VERSION=0.13.0   # replace with the release you downloaded
tar xzf "conduit-${VERSION}-amd64.tar.gz"
cd "conduit-${VERSION}"
ls -l

The directory contains conduit, conduitctl, conduit-dnstap-tracer, conduit-otlp-metrics-tracer, LICENSE, and an examples/ tree (minimal and reference YAML plus guide lab configs).

Run with a config file (first argument is the YAML path only):

./conduit examples/conduit.minimal.yaml

Edit the pool backend address in the minimal file before expecting successful forwarding. For a full field reference, see examples/conduit.reference.yaml and Reference: config schema. Guide walkthroughs that ship a primary lab config also appear under examples/<guide>/ (for example examples/backend-health/).

Install from .deb (production)

VERSION=0.13.0
sudo dpkg -i "conduit_${VERSION}_amd64.deb"
# if dependencies are missing:
sudo apt-get -f install -y

The package:

  • Installs binaries to /usr/bin/
  • Creates system user and group conduit
  • Installs /etc/conduit/conduit.yaml (conffile — preserved on upgrade; copy of the minimal example)
  • Installs examples under /usr/share/doc/conduit/examples/ — minimal and reference YAML plus primary lab configs for the Guides that ship a full runnable sample (see examples/README.md in that directory)
  • Enables conduit.service but does not start it

Edit the config, then start the service:

sudo editor /etc/conduit/conduit.yaml
sudo systemctl start conduit
sudo systemctl status conduit

The unit runs /usr/bin/conduit /etc/conduit/conduit.yaml as user conduit with CAP_NET_BIND_SERVICE so non-root processes can bind to privileged ports (for example port 53).

Debug .deb (optional)

For unstripped binaries on a troubleshooting host:

sudo dpkg -i "conduit-dbg_${VERSION}_amd64.deb"

This overwrites /usr/bin/conduit, conduitctl, conduit-dnstap-tracer, and conduit-otlp-metrics-tracer with unstripped builds. Install the production package first on servers that use systemd; use -dbg only when you need debug symbols.

Build from source

Requires Rust 1.78+ (see workspace rust-version in Cargo.toml):

git clone https://github.com/egon1024/DNSConduit.git
cd DNSConduit
cargo build --release -p conduit -p conduitctl -p conduit-dnstap-tracer -p conduit-otlp-metrics-tracer

Binaries are in target/release/. Packaged example configs (minimal, reference, and guide labs) live in packaging/examples/ and are what release tarballs and the production .deb install under examples/.

Validate before run

conduitctl validate --file /etc/conduit/conduit.yaml

On success the command prints ok.