Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

KyDNS manual

Local DNS and service discovery for homes, homelabs and small teams, with blacklist filtering, optional built-in DHCP and sealed recovery backups. It is not an internet-facing recursive DNS service by default.

Start with Getting started, then Everyday tasks. Use Troubleshooting when something fails. Reference links the detailed configuration, recovery and security documents for this product.

This manual describes the checked-out product and its documented limits. Release availability, real-device support and production qualification must be checked for the version you install. Roadmap and design documents describe proposals unless the product documentation says they shipped.

Getting started

Install safely

Follow the package, Docker or Raspberry Pi installation path in the product reference. Preserve configuration, database and keys across updates. Set the private domain and the LAN query allow-list before directing clients at the resolver.

Register a service

For example, kydns service add kypost --address 192.168.1.20 --alias webmail --check https://kypost.home.arpa/health creates names in the configured private domain. Substitute your own address and health URL. Point one test client at KyDNS and confirm both service and ordinary upstream resolution.

Do not enable built-in DHCP alongside an existing DHCP service without planning the change. Configure the recovery key and a destination before relying on scheduled backups.

Everyday tasks

Names and services

Add a service address and optional aliases, then verify them from a client using this resolver. A DNS name only resolves an address: HTTPS routing and a certificate for that name still belong to the reverse proxy/application setup.

Filtering and upstreams

Review built-in and operator-managed blocklists and opt-outs. Configure the documented upstream encryption mode and test resolution after changing it. Keep query access scoped to the intended LAN; widening allow_query requires deliberate network review.

DHCP and replication

The built-in DHCP service and replication have their own setup and primary-failure behavior in the product reference. Verify those paths before moving clients. A second node is not a substitute for tested backups.

Backups

Settings → Disaster recovery pins/pairs a suite public key and shows destinations, schedule and newest local copy. Preserve the key pin. Restore needs the sealed capsule and enough custodian cards, entered through stdin according to the runbook.

Troubleshooting

  • Name resolves on the server but not a client: check which resolver the client actually uses, its cache and the query allow-list.
  • Name resolves but HTTPS fails: inspect the proxy route and certificate for that hostname; DNS alone does not configure them.
  • Clients lose addresses: check for competing DHCP servers and the configured scope before changing DNS data.
  • Unexpected block: inspect the matched filtering list and the intended opt-out.
  • Container permission failure after upgrade: follow the non-root ownership migration in the product reference.
  • Backup has no destination: a pinned key alone is insufficient. Configure a local directory or pair KyRecovery.

When reporting a problem, include the product version, platform, failed task and a redacted error. Exclude pairing links, device secrets, recovery codes, custodian shares and private content.

Reference and security

Product reference

The repository README links the current installation commands, environment reference and supported deployment/distribution paths. Read the version matching your installation. The links below open repository documents and need network access.

Detailed product guides

Privacy and vulnerability reports

Read SECURITY.md for this product’s security model, known limits and private reporting route. Follow that policy for suspected vulnerabilities. Do not publish credentials or private data in a public issue.

Versions

Use the release record and, where present, the repository changelog. A successful build is not proof of a published or qualified release.

Development and documentation

Contributing

Read CONTRIBUTING.md before changing the product. It owns the contribution process, build prerequisites and required product checks. Read the repository’s AGENTS.md chain when working with an agent. Native builds and tests require their documented operating systems, SDKs and devices.

Build this manual

Install mdBook 0.5.4 and Python 3. From the repository root:

mdbook build docs
python3 docs/check-links.py

Open docs/book/index.html to read the generated manual. Search and the printable whole-book view are built in. Run the same two commands after editing chapters or links. The generated docs/book/ directory is ignored; commit the Markdown sources and configuration.

Documentation checks

The documentation workflow builds the book, checks generated local links and anchors, then uploads the complete book as a documentation-book artifact. It does not publish a public website. After extracting the artifact, open index.html.

Add chapters to docs/src/SUMMARY.md. Keep user instructions consistent with current behavior and update the related reference guides when a workflow changes. External reference URLs are not fetched by the local-link check.

Licence

Read the project’s licence text. Third-party components keep their own licences; consult the repository and application acknowledgements for their notices.