pkarr-publisher

Keep your PKARR records alive on the DHT

A lightweight Rust service that automatically publishes and republishes PKARR DNS records to the Mainline DHT. Run it once, forget about it.

The Problem

Mainline DHT records expire after a few hours. If you're using PKARR public keys as self-sovereign identifiers, your records will disappear unless you keep republishing them.

The Solution

This service runs in the background and keeps your records alive on a configurable interval. It supports two modes:

Publisher Mode (Secret Key)

Use your secret key to sign and publish DNS records you define in the config.

Republisher Mode (Public Key Only)

Use only a public key to fetch existing records from the DHT and republish them. This is useful when you want to:

• Help keep someone else's records alive
• Keep your own records alive without exposing the secret key

Features

• Multiple keypairs - manage several PKARR identities from one config
• Publisher + Republisher modes - full control or public-key-only republishing
• All common DNS record types - A, AAAA, CNAME, TXT
• Docker-ready - production-ready with secrets support
• Zero dependencies at runtime - single static binary

Quick Start

Publisher Mode (with Secret Key)

1. Generate your identity

openssl rand -hex 32

Save this 64-character hex string. It's your Ed25519 secret key.

2. Configure

cp config.example.toml config.toml

[settings]
interval_seconds = 3600  # republish every hour

[[keys]]
secret_key = "your-64-char-hex-secret-key"

[[keys.records]]
type = "CNAME"
name = "@"
value = "mysite.example.com"
ttl = 3600

[[keys.records]]
type = "TXT"
name = "_dnslink"
value = "dnslink=/ipfs/Qm..."
ttl = 3600

3. Run

cargo run --release

Your public key will be logged at startup. That's your PKARR identifier.

Republisher Mode (Public Key Only)

To keep existing records alive without the secret key:

[settings]
interval_seconds = 3600

[[public_keys]]
public_key = "yqrx81zchh6aotjj85s96gdqbmsoprxr3ks6ks1wuozk761dr5k"

[[public_keys]]
public_key = "cb7xxx5gdp7wyosjpurzcp87tsehaed5o8cgw81g9k16qgashuo"

The daemon will fetch the existing packets from the DHT and republish them periodically.

Docker

docker compose up -d

Or manually:

docker build -t pkarr-publisher .
docker run -v $(pwd)/config.toml:/config/config.toml:ro pkarr-publisher

Production: Using Secrets

Don't hardcode keys in config files. Use file references:

[[keys]]
secret_key_file = "/run/secrets/my_pkarr_key"

Configuration Reference

Settings

Field	Default	Description
interval_seconds	3600	Republish interval in seconds
max_retries	3	Maximum retry attempts for failed publishes
retry_delay_seconds	5	Base delay between retries (exponential backoff)

Keys (Publisher Mode)

Field	Description
secret_key	Hex-encoded 32-byte Ed25519 secret key
secret_key_file	Path to file containing the secret key

Use secret_key OR secret_key_file, not both.

Records (for Keys)

Field	Default	Description
type	required	A, AAAA, CNAME, or TXT
name	required	@ for apex, or subdomain name
value	required	IP, hostname, or text content
ttl	3600	Time-to-live in seconds

Public Keys (Republisher Mode)

Field	Description
public_key	Public key in z-base-32 format (with or without pk: prefix)

Environment Variables

Variable	Default	Description
CONFIG_PATH	./config.toml	Config file location
RUST_LOG	info	Log level (debug, info, warn, error)

Verify Your Records

Once published, verify your records are live:

Method	How
Web UI	app.pkarr.org
Browser	Install pkdns-resolver-extension and navigate to http://YOUR_PUBLIC_KEY
CLI	dig YOUR_PUBLIC_KEY @pkarr.pubky.org

How It Works

Publisher Mode

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   config.toml   │────▶│  pkarr-publish  │────▶│  Mainline DHT   │
│   (keys+records)│     │  (sign & push)  │     │  (distributed)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

1. Reads your keypairs and DNS records from config
2. Signs records with your Ed25519 secret key
3. Publishes to the Mainline DHT
4. Repeats on the configured interval

Republisher Mode

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   config.toml   │────▶│  pkarr-publish  │◀───▶│  Mainline DHT   │
│  (public_keys)  │     │ (fetch & push)  │     │  (distributed)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

1. Reads public keys from config
2. Fetches existing packets from the DHT (no secret key needed)
3. Republishes the same packets to keep them alive
4. Repeats on the configured interval

Related Projects

• pkarr - Public Key Addressable Resource Records
• pkdns-resolver-extension - Browser extension to resolve PKARR domains
• pubky - The Pubky protocol

License

MIT