pkdns

A DNS server providing self-sovereign and censorship-resistant domain names. It resolves records hosted on the Mainline DHT, the biggest DHT on the planet with ~15M nodes that services torrents since 15 years.

• How Censorship-Resistant is Mainline DHT?
• How Censorship-Resistant are Public Key Domains
• How to publish a Public Key Domain Website?

Getting Started

Hosted DNS

Use one of the hosted DNS servers to try out pkdns quickly.

• Verify the server is working.
• Configure your system dns.
• Browse the self-sovereign web.

Pre-Built Binaries

1. Download the latest release for your plattform.
2. Extract the tar file. Should be something like tar -xvf tarfile.tar.gz.
3. Run pkdns -f 8.8.8.8.
4. Verify the server is working. Your dns server ip is 127.0.0.1.
5. Configure your system dns.
6. Browse the self-sovereign web.

Build It Yourself

Make sure you have the Rust toolchain installed.

1. Clone repository git clone https://github.com/pubky/pkdns.git.
2. Switch directory cd pkdns.
3. Run cargo run --package=pkdns -- -f 8.8.8.8.
4. Verify the server is working. Your server ip is 127.0.0.1.
5. Configure your system dns.
6. Browse the self-sovereign web.

Guides

Change your System DNS

Follow one of the guides to change your DNS server on your system:

• MacOS guide
• Ubuntu guide
• Windows guide

Verify your server with this domain http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy./.

Verify pkdns is working

Pkarr Domains

Verify the server resolves pkarr domains. Replace PKDNS_SERVER_IP with your pkdns server IP address.

nslookup 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy PKDNS_SERVER_IP

Troubleshooting If this does not work then the pkdns server is likely not running.

ICANN Domains

Verify it resolves regular ICANN domains. Replace PKDNS_SERVER_IP with your pkdns server IP address.

nslookup example.com PKDNS_SERVER_IP

Troubleshooting If this does not work then you need to change your ICANN fallback server with pkdns -f REGULAR_DNS_SERVER_IP. Or use the Google DNS server: pkdns -f 8.8.8.8.

Browse the Self-Sovereign Web

Here are some example pkarr domains:

• http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy./
• http://pkdns.7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy./

Hint: Always add a ./ to the end of a pkarr domain. Otherwise browsers will search instead of resolve the website.

Address already in use

Other services might occupy the port 53 already. For example, Docker Desktop uses the port 53 on MacOS. systemd-resolved is using it on Ubuntu. Make sure to free those.

Options

Usage: pkdns [OPTIONS]

Options:
  -f, --forward <forward>
          ICANN fallback DNS server. IP:Port [default: 8.8.8.8:53]
  -s, --socket <socket>
          Socket the server should listen on. IP:Port [default: 0.0.0.0:53]
  -v, --verbose
          Show verbose output.
      --min-ttl <min-ttl>
          Minimum number of seconds a value is cached for before being refreshed. [default: 60]
      --max-ttl <max-ttl>
          Maximum number of seconds before a cached value gets auto-refreshed. [default: 86400]
      --cache-mb <cache-mb>
          Maximum size of the pkarr packet cache in megabytes. [default: 100]
      --query-rate-limit <query-rate-limit>
          Maximum number of queries per second one IP address can make before it is rate limited. 0 is disabled. [default: 0]
      --query-rate-limit-burst <query-rate-limit-burst>
          Short term burst size of the query-rate-limit. 0 is disabled. [default: 0]
      --dht-rate-limit <dht-rate-limit>
          Maximum number of queries per second one IP address can make to the DHT before it is rate limited. 0 is disabled. [default: 5]
      --dht-rate-limit-burst <dht-rate-limit-burst>
          Short term burst size of the dht-rate-limit. 0 is disabled. [default: 25]
  -h, --help
          Print help
  -V, --version

For extended logs, see here.

Announce Your Own Records

Use the pkdns-cli to inspect and announce your pkarr records on the Mainline DHT. Download the latest release for your plattform.

The cli currently only supports A, AAAA, TXT, CNAME, NS, and MX records.

Inspect records by public key List all records published by a public key.

./pkdns-cli resolve 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy

Generate seed Generate a zbase32 seed to publish your own records.

./pkdns-cli generate > seed.txt

Publish your own records Create a dns zone file and publish its content. See example for more details.

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

⚠️ pkdns caches DHT packets for at least 5 minutes to improve latency. Run your own instance with pkdns --max-ttl 0 to disable caching.

Limitations

Recursion

pkdns does only partially support recursive lookups. Recursion only works

• For a CNAME pointing directly to another record in the same pkarr packet.
• For a NS delegating the whole pkarr zone to a name server.

For anything more fancy than simple A and TXT records, it is recommended to use a bind9 name server and point your zone to there @ NS {BIND9IP}. bind9 is a fully fledged name server and should be able to handle recursion and all record types.

Record Types

Currently, pkdns only supports A, AAAA, TXT, CNAME, and MX records. For any other types, use bind9.

---

May the power ⚡ be with you. Powered by pkarr.