DOCSEARCHbyAlgolia
Submit Docs

pkdns

repository·master·Indexed 41 days ago

https://github.com/pubky/pkdns

A DNS server providing self-sovereign and censorship-resistant domain names by resolving records hosted on the Mainline DHT. It includes the pkdns-cli (v0.7.1) for generating seeds, publishing DNS records (supporting A, AAAA, TXT, CNAME, and MX), and resolving public key domains. The server supports DNS-over-HTTPS (DoH) and can be configured via TOML or command-line flags for ICANN fallback resolution.

Tokens
13.9K
Snippets
71
Records
85
Agent score
42%

What's inside pkdns

  1. Verify Public Key Domain lookups

    master

    After announcing records, you can verify them using the following methods:

    1. Web Interface: Lookup the domain ID on pkdns.net.
    2. nslookup: Query the hosted pkdns server directly using nslookup. Replace the IP with the current hosted server IP (e.g., 34.65.109.99) and the domain ID.
    nslookup 8qhdp5s8jjmxmqam3bpg9kzeg7x8teztuwrfgxw5ikn9z5bt15uy 34.65.109.99

  3. Use a hosted DoH server in your browser

    master

    You can enable Public Key Domains (PKD) in your web browser without changing your system DNS by using a hosted DNS-over-HTTPS (DoH) server.

    1. Select a DoH URL from the project's public servers.txt list.
    2. Configure your browser (Firefox, Chrome, Brave, or Edge) to use that URL.
    3. Verify the connection by visiting: http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/.
    http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/

  4. Enable DoH in pkdns via a reverse proxy

    master

    To enable DNS-over-HTTPS (RFC8484) using your own pkdns instance, you must set up a reverse proxy (like NGINX) to handle HTTPS, as pkdns listens for plain HTTP requests on its DoH socket.

    1. Configure pkdns.toml to listen on a specific local address: Set dns_over_http_socket = "127.0.0.1:3000". This makes pkdns listen for HTTP requests at http://127.0.0.1:3000/dns-query.
    2. Use a reverse proxy (e.g., NGINX) to provide an HTTPS layer.
    3. Configure the reverse proxy to forward requests to the pkdns socket. For NGINX, use a location block to set the X-Forwarded-For header and proxy_pass to the local pkdns address.
    4. Configure your browser to use your new HTTPS DoH URL.
    5. Verify the setup by visiting: http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/.
    # pkdns.toml
dns_over_http_socket = "127.0.0.1:3000"
    # NGINX configuration example
location / {
	proxy_set_header X-Forwarded-For $remote_addr;
	proxy_pass http://127.0.0.1:3000;
}

  5. Publish DNS records using pkdns-cli

    master

    You can publish DNS records to the DHT by providing a seed file and a DNS zone file (without an SOA record) to the publish command.

    Note on Caching: pkdns caches DHT packets for at least 60 seconds to improve latency. If you are testing and need immediate updates, run your own pkdns instance with the --max-ttl 0 flag to disable caching.

    ./pkdns-cli publish seed.txt pkarr.zone

  7. Verify pkdns is working

    master

    You can verify your pkdns installation by performing nslookup queries for both pkdns domains and standard ICANN domains. Replace PKDNS_SERVER_IP with your actual server IP (e.g., 127.0.0.1).

    Verify PKDNS Domains

    Check if the server resolves self-sovereign domains:

    nslookup 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy PKDNS_SERVER_IP

    Verify ICANN Domains

    Check if the server resolves regular internet domains:

    nslookup example.com PKDNS_SERVER_IP

    Troubleshooting ICANN resolution: If regular domains fail to resolve, you may need to set a fallback ICANN DNS server using the -f flag (e.g., pkdns -f 8.8.8.8).

    # Verify PKDNS domain
nslookup 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy 127.0.0.1

# Verify ICANN domain
nslookup example.com 127.0.0.1

  8. Enable DynDNS with pkdns-cli

    master

    You can use pkdns-cli to implement Dynamic DNS (DynDNS), allowing you to assign a fixed domain name to a device with a dynamic IP address.

    When publishing a zone file (e.g., pkarr.zone) using the CLI, the tool automatically detects your current external IP addresses and replaces the following variables within the zone file:

    • {external_ipv4}: Replaced with your actual external IPv4 address.
    • {external_ipv6}: Replaced with your actual external IPv6 address.

    To ensure your Public Key Domain (PKD) always points to the correct IP address even if your ISP changes it, you should publish your PKD every 60 minutes (e.g., via a cron job).

    # Example usage concept
# The CLI replaces these variables in your zone file:
# {external_ipv4}
# {external_ipv6}

  9. Generate a seed for pkdns records

    master

    To announce records on the mainline DHT, you first need a 64-character hex-encoded seed. You can generate a new seed using the generate command in the pkdns-cli tool and redirecting the output to a file.

    ./pkdns-cli generate > seed.txt

  11. Install pkdns using pre-built binaries

    master

    To run pkdns locally using pre-built binaries:

    1. Download the latest release for your platform from the GitHub releases page.
    2. Extract the tar file (e.g., tar -xvf tarfile.tar.gz).
    3. Run the binary with the --verbose flag: pkdns --verbose.
    4. Once running, your local DNS server will be available at 127.0.0.1.
    tar -xvf tarfile.tar.gz
./pkdns --verbose

  12. Build pkdns from source

    master

    If you have the Rust toolchain installed, you can build and run pkdns directly from the repository:

    1. Clone the repository: git clone https://github.com/pubky/pkdns.git.
    2. Enter the directory: cd pkdns.
    3. Run the package using cargo: cargo run --package=pkdns.
    4. The server will be available at 127.0.0.1.
    git clone https://github.com/pubky/pkdns.git
cd pkdns
cargo run --package=pkdns