Skip to content

Instantly share code, notes, and snippets.

@chr-lei

chr-lei/controld-dnsproxy.md

Last active March 18, 2023 21:39
Show Gist options
  • Save chr-lei/94fd21bdcde3075f3cc29669fd7dd8f6 to your computer and use it in GitHub Desktop.
Save chr-lei/94fd21bdcde3075f3cc29669fd7dd8f6 to your computer and use it in GitHub Desktop.
Download ZIP
Deploying dnsproxy for ControlD using a config.yaml file
Raw
controld-dnsproxy.md

Deploying dnsproxy for ControlD using a config.yaml file

Prerequisites

  • You've got a config.yaml file built. Check out the sample file provided by AdGuard here, or a ControlD-specific sample here.
    • You can also run dnsproxy without a config.yaml file and use command-line switches. I prefer a config.yaml file since it means you don't need to change any startup scripts or re-create the Docker/Podman container if you need to update a value, but any arguments in the config.yaml file can be passed to the command line as well. Check out the dnsproxy readme for more information on additional functions.
  • If you want to use Docker/Podman, this assumes you have either installed and have a basic level of knowledge on either platform. Unfortunately, I am not an expert in either myself and there are many better guides out there on how to stand these up.
    • I run on a Unifi Dream Machine, so I started with boostchicken's work and modified the AdGuard Home process to use a dnsproxy container instead.

Method 1: Running dnsproxy natively

If you just want to run a dnsproxy instance natively on a Windows/Mac/Linux system, these steps should get you off the ground with a basic proxy to service a small (< 50 devices) network.

  1. Download the dnsproxy binaries for your operating system from the dnsproxy GitHub Releases page.
  2. Extract the archive to a folder of your choice.
  3. Create a config.yaml file in the same folder (for simplicity) and add any configurations that you require.
  4. Open a command prompt/terminal and run dnsproxy with the --config-path=config.yaml parameter.
    • Example on Windows: C:\\dnsproxy\\dnsproxy.exe --config-path=config.yaml
    • Example on MacOS/Linux: /opt/dnsproxy/dnsproxy --config-path=config.yaml
  5. If you need to customize the listener address or ports you can add listen-addrs or listen-ports arguments to your config.yaml as well. Keep in mind that, if you intend to point your network devices to this proxy, you'll want to use the standard port 53.
  6. Test the proxy via nslookup (Windows) or dig (Mac/Linux)
    • Windows: nslookup www.google.com 192.168.1.1 (where 192.168.1.1 is the address of your dnsproxy instance)
    • MacOS/Linux: dig @192.168.1.1 www.google.com (where 192.168.1.1 is the address of your dnsproxy instance)
  7. Configure your network devices to use your dnslookup proxy as their DNS server (for example, via DHCP or manually setting the address).

Method 2: Using docker/podman

Note: These instructions will focus on Docker on Linux. However, if you are using Podman or are running Windows/MacOS, most of this will be the same, you'll just have to change things like how paths are defined, etc.

I am going to show the setup using vmstan's dnsproxy Docker image, which is available for Intel/AMD 64-bit and ARM architectures. You could use other dnsproxy images but their syntax may be different. The steps below should work, in general, if adjusted to use the syntax of another image for things like passing the config file argument.

  1. Create a folder to house your config.yaml file - I use /opt/dnsproxy.

  2. Create a config.yaml file in /opt/dnsproxy and add any configurations that you require.

  3. To start the container using the host network, use the below command to expose ports 53/tcp and 53/tcp and mount the /opt/dnsproxy volume (which in turn allows the dnsproxy instance to read your config.yaml file) and then pass the config file to dnsproxy as the only command line option.

    • docker run -d -p 53:53/udp -p 53:53/tcp -v /opt/dnsproxy:/opt/dnsproxy:ro -e "CONFIG=--config-path=/opt/dnsproxy/config.yaml" --restart=always docker.io/vmstan/dnsproxy

    If you are using a more complex Docker network setup (e.g., using Macvlan to create a separate "dns" network as outlined in boostchicken's guide for the Unifi products) your commands may be able to omit the -p arguments and instead may need the --network argument instead, like this:

    • docker run -d --network dns -v /opt/dnsproxy:/opt/dnsproxy:ro -e "CONFIG=--config-path=/opt/dnsproxy/config.yaml" --restart=always docker.io/vmstan/dnsproxy

  4. Test the proxy from another machine via nslookup (Windows) or dig (Mac/Linux)

    • Windows: nslookup www.google.com 192.168.1.1 (where 192.168.1.1 is the address of your dnsproxy instance)
    • MacOS/Linux: dig @192.168.1.1 www.google.com (where 192.168.1.1 is the address of your dnsproxy instance)

  5. Configure your network devices to use your dnslookup proxy as their DNS server (for example, via DHCP or manually setting the address).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment