Quick Start

This page describes the OxiDNS installation paths and the shortest path from download to first successful start.

Which install path should I choose?

Linux servers: the one-command installer, release archives, or .deb packages
OpenWrt routers: the luci-app-oxidns LuCI app
Containerized environments: the Docker image
Local development or debugging: build from source with Cargo
macOS / Windows: the one-command installer or release archives

1. One-Command Install

The installer detects the current platform. On Linux / macOS / Windows, it downloads the matching OxiDNS GitHub Release archive, extracts oxidns / oxidns.exe, config.yaml, and webui/, then installs and starts OxiDNS as a system service by default. On OpenWrt, it downloads and installs the luci-app-oxidns LuCI app.

Linux / macOS
Windows
OpenWrt

curl -fsSL https://oxidns.org/install.sh | sudo sh

irm https://oxidns.org/install.ps1 | iex

curl -fsSL https://oxidns.org/install.sh | sh

If curl is not installed:

wget -O- https://oxidns.org/install.sh | sh

Default install locations:

Platform	Default install directory	PATH behavior
Linux / macOS service install with `sudo`	`/opt/oxidns`	Creates `/usr/local/bin/oxidns`, then installs and starts the system service
Windows service install from elevated PowerShell	`%ProgramFiles%\OxiDNS`	Adds the install directory to the Machine PATH, then installs and starts the service
Linux / macOS portable install	`~/.oxidns`	Set `OXIDNS_INSTALL_SERVICE=0`; creates `~/.local/bin/oxidns`
Windows portable install	`%LOCALAPPDATA%\OxiDNS`	Set `OXIDNS_INSTALL_SERVICE=0`; adds the install directory to the user PATH
OpenWrt / LuCI app install	Managed by `opkg` / `apk`	Installs `luci-app-oxidns` and the optional Chinese translation package; install the OxiDNS core from LuCI afterward

In Linux / macOS / Windows archive install mode, running the installer again updates the binary and webui/. If config.yaml already exists in the install directory, the installer keeps it and writes the release default config as config.yaml.example.

On OpenWrt, running the installer again reinstalls the selected luci-app-oxidns release package. OxiDNS core version upgrades still use the built-in LuCI / WebUI / API / CLI upgrade flow.

Install A Specific Version

Linux / macOS
Windows

curl -fsSL https://oxidns.org/install.sh | sudo env OXIDNS_VERSION=v1.0.1 sh

$env:OXIDNS_VERSION = "v1.0.1"; irm https://oxidns.org/install.ps1 | iex

Common environment variables:

Variable	Purpose
`OXIDNS_VERSION`	Release tag, defaults to `latest`
`OXIDNS_INSTALL_DIR`	Override the install directory
`OXIDNS_BIN_DIR`	Override the command-link directory on Linux / macOS
`OXIDNS_TARGET`	Override the release target, for example `x86_64-unknown-linux-musl`
`OXIDNS_BUNDLE`	Select the release build bundle, default `full`; Linux x86_64 / ARM64 musl can use `minimal` or `standard`
`OXIDNS_NO_PATH=1`	Do not create a command link or update PATH
`OXIDNS_INSTALL_SERVICE=0`	Skip system service installation and use portable install mode
`OXIDNS_START_SERVICE=0`	Install the service but do not start it immediately
`OXIDNS_OPENWRT_INSTALL`	OpenWrt branch switch, defaults to `auto`; set `0` to force normal Linux archive installation
`OXIDNS_OPENWRT_REPO`	LuCI app repository, defaults to `svenshi/luci-app-oxidns`
`OXIDNS_OPENWRT_VERSION`	LuCI app release tag, defaults to `latest`
`OXIDNS_OPENWRT_I18N`	Whether to install the Simplified Chinese translation package, defaults to `auto`; set `0` to skip it

Portable install:

Linux / macOS
Windows

curl -fsSL https://oxidns.org/install.sh | env OXIDNS_INSTALL_SERVICE=0 sh

$env:OXIDNS_INSTALL_SERVICE = "0"; irm https://oxidns.org/install.ps1 | iex

After a portable install, start OxiDNS with:

Linux / macOS
Windows

oxidns start -c ~/.oxidns/config.yaml -d ~/.oxidns

oxidns.exe start -c "$env:LOCALAPPDATA\OxiDNS\config.yaml" -d "$env:LOCALAPPDATA\OxiDNS"

Port permissions

The default config includes a :53 listener. On Linux / macOS, portable installs run by regular users usually cannot bind port 53; for local evaluation, remove udp_server_53 first or use the default system service install.

Uninstall

The uninstall script removes the binary, webui/, and PATH entry while keeping config.yaml by default. On OpenWrt, it removes luci-app-oxidns / the translation package and cleans the LuCI-installed /usr/bin/oxidns and /usr/share/oxidns/webui; OxiDNS config, the working directory, and LuCI settings are kept by default.

Linux / macOS
OpenWrt
Windows

curl -fsSL https://oxidns.org/uninstall.sh | sudo sh

curl -fsSL https://oxidns.org/uninstall.sh | sh

If curl is not installed:

wget -O- https://oxidns.org/uninstall.sh | sh

irm https://oxidns.org/uninstall.ps1 | iex

If you installed with sudo or a custom OXIDNS_INSTALL_DIR, use the same privilege level and directory variable when uninstalling. OpenWrt uninstall requires root.

Remove the install directory and config too:

Linux / macOS
OpenWrt
Windows

curl -fsSL https://oxidns.org/uninstall.sh | sudo env OXIDNS_PURGE=1 sh

curl -fsSL https://oxidns.org/uninstall.sh | env OXIDNS_PURGE=1 sh

If curl is not installed:

wget -O- https://oxidns.org/uninstall.sh | env OXIDNS_PURGE=1 sh

$env:OXIDNS_PURGE = "1"; irm https://oxidns.org/uninstall.ps1 | iex

Purge removes configuration

Setting OXIDNS_PURGE=1 deletes the configuration file. For archive installs it removes the full install directory; on OpenWrt it removes OxiDNS config, the working directory, and LuCI settings. Back up config.yaml before running it.

Common uninstall variables:

Variable	Purpose
`OXIDNS_INSTALL_DIR`	Override the uninstall target; keep it aligned with the install command
`OXIDNS_BIN_DIR`	Override the command-link directory on Linux / macOS
`OXIDNS_NO_PATH=1`	Do not remove the command link or user PATH entry
`OXIDNS_UNINSTALL_SERVICE=1`	Force operating-system service uninstall; by default this is attempted automatically as root / administrator
`OXIDNS_PURGE=1`	For archive installs, remove the full install directory; on OpenWrt, remove OxiDNS config, the working directory, and LuCI settings
`OXIDNS_OPENWRT_UNINSTALL`	OpenWrt uninstall branch switch, defaults to `auto`; set `0` to force normal Linux archive uninstall
`OXIDNS_OPENWRT_CONFIG_PATH`	Override the OpenWrt config path; when omitted, reads UCI `config_path`, then falls back to `/etc/oxidns/config.yaml`
`OXIDNS_OPENWRT_WORKING_DIR`	Override the OpenWrt working directory; when omitted, reads UCI `working_dir`, then falls back to `/var/lib/oxidns`

2. Build From Source

This path is suitable for debugging, code changes, or cases where packaged builds are not used.

Requirements:

A stable Rust toolchain
A working Cargo build environment

Build and run:

git clone https://github.com/svenshi/oxidns.git
cd oxidns

cargo build --release
./target/release/oxidns check -c config.yaml
./target/release/oxidns start -c config.yaml

Run with debug logging:

cargo run -- check -c config.yaml
cargo run -- start -c config.yaml -l debug

3. Install From GitHub Release Archives

The release workflow generates standalone binaries for multiple platforms. Each full archive includes:

oxidns or oxidns.exe
config.yaml
LICENSE
webui/

Linux x86_64 / ARM64 musl also get minimal and standard slim archives. minimal only includes oxidns, config.yaml, and LICENSE; standard also includes WebUI static files, query_recorder, and the upgrade capability. See Custom Build for the full capability differences between preset bundles.

Release page:

https://github.com/svenshi/oxidns/releases

Supported Archive Targets

Non-Windows targets use .tar.gz:

oxidns-x86_64-unknown-linux-gnu.tar.gz
oxidns-x86_64-unknown-linux-musl.tar.gz
oxidns-aarch64-unknown-linux-gnu.tar.gz
oxidns-aarch64-unknown-linux-musl.tar.gz
oxidns-i686-unknown-linux-musl.tar.gz
oxidns-arm-unknown-linux-musleabihf.tar.gz
oxidns-x86_64-apple-darwin.tar.gz
oxidns-aarch64-apple-darwin.tar.gz
oxidns-x86_64-unknown-freebsd.tar.gz

Linux musl slim archives use a bundle prefix:

oxidns-minimal-x86_64-unknown-linux-musl.tar.gz
oxidns-minimal-aarch64-unknown-linux-musl.tar.gz
oxidns-standard-x86_64-unknown-linux-musl.tar.gz
oxidns-standard-aarch64-unknown-linux-musl.tar.gz

Windows targets use .zip:

oxidns-x86_64-pc-windows-msvc.zip
oxidns-i686-pc-windows-msvc.zip
oxidns-aarch64-pc-windows-msvc.zip

How To Choose The Right Release Asset

When the correct asset is unclear, use this mapping:

System / Environment	Recommended release asset	Notes
Linux x86_64	`oxidns-x86_64-unknown-linux-musl.tar.gz`	Safer default for broad compatibility
Linux ARM64	`oxidns-aarch64-unknown-linux-musl.tar.gz`	Safer default for broad compatibility
Debian / Ubuntu x86_64 service install	`*_amd64.deb`	Best fit for systemd-based deployment
Debian / Ubuntu ARM64 service install	`*_arm64.deb`	Best fit for systemd-based deployment
OpenWrt / LuCI	`.ipk` / `.apk` packages from `luci-app-oxidns`	Install the LuCI app first; LuCI then downloads and installs the OxiDNS Linux musl core
Alpine Linux x86_64	`oxidns-x86_64-unknown-linux-musl.tar.gz`	Prefer musl on Alpine
Alpine Linux ARM64	`oxidns-aarch64-unknown-linux-musl.tar.gz`	Static-friendly build
Confirmed glibc Linux requiring a dynamic build	`oxidns-x86_64-unknown-linux-gnu.tar.gz` / `oxidns-aarch64-unknown-linux-gnu.tar.gz`	Only choose this when the target environment is clearly compatible
32-bit ARM Linux	`oxidns-arm-unknown-linux-musleabihf.tar.gz`	Fits some Raspberry Pi and older ARM boards
macOS Intel	`oxidns-x86_64-apple-darwin.tar.gz`	Intel Macs
macOS Apple Silicon	`oxidns-aarch64-apple-darwin.tar.gz`	M1 / M2 / M3 / M4 Macs
Windows x64	`oxidns-x86_64-pc-windows-msvc.zip`	Most PCs
Windows 32-bit	`oxidns-i686-pc-windows-msvc.zip`	Only for 32-bit Windows
Windows ARM64	`oxidns-aarch64-pc-windows-msvc.zip`	ARM-based Windows devices
FreeBSD x86_64	`oxidns-x86_64-unknown-freebsd.tar.gz`	FreeBSD hosts

To verify the platform first, run:

uname -s
uname -m

Common output mapping:

Linux + x86_64: default to x86_64-unknown-linux-musl; use x86_64-unknown-linux-gnu only when a glibc dynamic build is explicitly required
Linux + aarch64: default to aarch64-unknown-linux-musl; use aarch64-unknown-linux-gnu only when a glibc dynamic build is explicitly required
Linux + armv7l: use arm-unknown-linux-musleabihf
Darwin + x86_64: use x86_64-apple-darwin
Darwin + arm64: use aarch64-apple-darwin

On Windows PowerShell, run:

(Get-CimInstance Win32_OperatingSystem).OSArchitecture

Map X64, Arm64, and X86 to the x86_64, aarch64, and i686 Windows assets respectively.

Linux / macOS Example

Replace TAG below with the actual release tag, for example v0.1.0. The Linux example below uses x86_64-unknown-linux-musl as the default choice:

curl -L -o oxidns.tar.gz \
  https://github.com/svenshi/oxidns/releases/download/TAG/oxidns-x86_64-unknown-linux-musl.tar.gz

mkdir -p oxidns
tar -xzf oxidns.tar.gz -C oxidns
cd oxidns

chmod +x oxidns
./oxidns check -c config.yaml
./oxidns start -c config.yaml

When the target machine's glibc compatibility is unclear, or when running Alpine Linux, prefer a *-linux-musl archive instead of defaulting to gnu.

Windows Example

Download the matching .zip, extract it, then run:

.\oxidns.exe start -c .\config.yaml

4. Install From Debian Packages

The release workflow currently builds .deb packages for:

x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu

Install on Debian / Ubuntu:

sudo dpkg -i oxidns_*_amd64.deb

Or on ARM64 Debian / Ubuntu:

sudo dpkg -i oxidns_*_arm64.deb

Default installed paths:

Binary: /usr/bin/oxidns
Config: /etc/oxidns/config.yaml
Runtime-relative path base: /var/lib/oxidns
WebUI: /var/lib/oxidns/webui symlinked to /usr/share/oxidns/webui

The project also ships systemd packaging metadata, so Debian-family systems are a good fit for service-based deployment. The default service explicitly passes ExecStart ... -d /var/lib/oxidns as the runtime-relative path base.

After changing the default config, validate it before starting the service:

oxidns check -c /etc/oxidns/config.yaml -d /var/lib/oxidns

Verify service status:

sudo systemctl status oxidns

If the service is not running yet:

sudo systemctl enable --now oxidns

5. OpenWrt / LuCI App

OpenWrt users should use the OxiDNS installer script to install luci-app-oxidns. It adds Services -> OxiDNS pages to LuCI for installing the OxiDNS core, managing the init service, editing configuration, and viewing logs.

curl -fsSL https://oxidns.org/install.sh | sh

If curl is not installed:

wget -O- https://oxidns.org/install.sh | sh

When the script detects OpenWrt, it reads the latest luci-app-oxidns release, selects .ipk or .apk for the system package manager, installs the main package and optional Simplified Chinese translation package, and restarts rpcd.

Manual LuCI App Install

Download the matching LuCI package from the luci-app-oxidns Release, then install it:

opkg install ./luci-app-oxidns_*.ipk
# Optional Simplified Chinese translation
opkg install ./luci-i18n-oxidns-zh-cn_*.ipk

On OpenWrt systems using apk:

apk add --allow-untrusted --no-network ./luci-app-oxidns_*.apk
# Optional Simplified Chinese translation
apk add --allow-untrusted --no-network ./luci-i18n-oxidns-zh-cn_*.apk

After installation, open Services -> OxiDNS -> Core and click Install Core. LuCI downloads and verifies the official OxiDNS Linux musl release archive for the current CPU architecture; offline environments can upload an official .tar.gz archive or a single oxidns binary.

See OpenWrt LuCI App for the full flow.

6. Run With Docker

The repository publishes a Docker image at:

GitHub

ghcr.io/svenshi/oxidns

Docker Hub

svenshi/oxidns

The Docker workflow builds:

linux/amd64
linux/arm64

Pull and run:

docker pull svenshi/oxidns:latest

docker run -d \
  --name oxidns \
  --restart unless-stopped \
  -p 53:53/udp \
  -p 53:53/tcp \
  -p 9199:9199/tcp \
  -v "$(pwd)/config.yaml:/etc/oxidns/config.yaml:ro" \
  svenshi/oxidns:latest

Port binding

On Linux, port 53 is privileged. Regular users usually get the needed permission through the Docker daemon. Portable non-root installs should use :5353.

When the default-branch image is published, the latest tag is also available.

The image entrypoint effectively runs:

oxidns start -c /etc/oxidns/config.yaml -d /etc/oxidns

The container exposes:

53/udp
53/tcp
9199/tcp

Docker Compose Example

For Compose-based port mapping and config management, use this docker-compose.yml:

services:
  oxidns:
    image: svenshi/oxidns:latest
    container_name: oxidns
    restart: unless-stopped
    ports:
      - "53:53/udp"
      - "53:53/tcp"
      - "9199:9199/tcp"
    volumes:
      - ./config.yaml:/etc/oxidns/config.yaml:ro

Start it with:

docker compose up -d

Follow logs with:

docker compose logs -f oxidns

7. Selection Guide

Fastest evaluation path: use the one-command installer for the latest release, or download a release archive manually
Long-running Linux service: prefer the Debian package
OpenWrt / LuCI management: use luci-app-oxidns
Container platforms: use the GHCR Docker or Docker Hub image
Development or custom builds: compile from source

8. Next Reading

After the first successful start, continue with:

1. One-Command Install​

Install A Specific Version​

Uninstall​

2. Build From Source​

3. Install From GitHub Release Archives​

Supported Archive Targets​

How To Choose The Right Release Asset​

Linux / macOS Example​

Windows Example​

4. Install From Debian Packages​

5. OpenWrt / LuCI App​

Manual LuCI App Install​

6. Run With Docker​

GitHub​

Docker Hub​

Docker Compose Example​

7. Selection Guide​

8. Next Reading​

1. One-Command Install

Install A Specific Version

Uninstall

2. Build From Source

3. Install From GitHub Release Archives

Supported Archive Targets

How To Choose The Right Release Asset

Linux / macOS Example

Windows Example

4. Install From Debian Packages

5. OpenWrt / LuCI App

Manual LuCI App Install

6. Run With Docker

GitHub

Docker Hub

Docker Compose Example

7. Selection Guide

8. Next Reading