Signed-off-by: Erik Hollensbe <email@example.com>
|11 months ago|
|cmd||1 year ago|
|config||1 year ago|
|dnsdb||1 year ago|
|proto||11 months ago|
|service||1 year ago|
|version||1 year ago|
|.gitignore||1 year ago|
|.golangci.yml||1 year ago|
|LICENSE||1 year ago|
|Makefile||11 months ago|
|README.md||1 year ago|
|VERSION||1 year ago|
|box-release.rb||11 months ago|
|box.rb||1 year ago|
|do_mkcert.sh||1 year ago|
|entrypoint.sh||1 year ago|
|example.conf||1 year ago|
|go.mod||1 year ago|
|go.sum||1 year ago|
|ldnsd_test.go||1 year ago|
|release-entrypoint.sh||1 year ago|
|task.yml||1 year ago|
|tinyci.yml||1 year ago|
ldnsd: Light DNSd: a small, 0 ttl A record store that is remotely programmable.
Light DNSd is largely designed for testing & small environments, providing an
easy to manage DNS service that serves the minimum necessary to deliver name
services centrally. Compare with a remotely programmable
/etc/hosts file that
lives in a central location. ldnsd comes with
ldnsctl which can handle the
programming, or use/generate GRPC-compliant clients from our protobuf
definitions to program it inside of your tools directly.
Light DNSd is backed by sqlite3 and provides very few features:
- No recursion
- No caching (although this may be added soon, see Potential Issues)
- No forwarding
- All records are 0 TTL
Since not all clients are very happy with how ldnsd sees the world (simply), it is strongly advised that you front it with a caching, recursive, standards-compliant nameserver like coredns, bind, dqcache/dnscache, etc, especially for the purposes of servicing client resolvers. Think of ldnsd more as a companion to your DNS stack instead of replacing it.
Installing a release is your best choice. Otherwise, you can still
go get github.com/erikh/ldnsd/...
and get the desired result in your
If you wish to use Docker to power ldnsd, you can use our
version-tagged images. Running with
--net=host is advisable to avoid the UDP
proxy docker provides as it tends to drop packets under high load.
# start the service $ docker run -it -d --name ldnsd --net=host erikh/ldnsd:0.1.0 # configure some hosts $ docker exec -it ldnsd ldnsctl set myhost 126.96.36.199 $ dig myhost.internal. @127.0.0.1
If you'd like to build in a container or build the release version, just make
sure to have
docker installed; box will
be installed as root as a part of the process during the first run while
creating the shell image.
To create a release tarball:
$ make shell # <inside the container> $ make release # out comes the tarball in the CWD
Make a CA
You'll need a CA. I strongly recommend installing
mkcert and trying this script to
generate the CA, one server cert, and one client cert in
/etc/ldnsd (you may
need to be root to write to this directory):
This will only make the service available on
localhost/127.0.0.1 through this
cert. All other attempts will be rejected.
Note if you change the directories, you will need to adjust the configuration file, which is discussed below.
export CAROOT="/etc/ldnsd" mkcert -install mkcert -ecdsa -cert-file /etc/ldnsd/server.pem -key-file /etc/ldnsd/server.key localhost 127.0.0.1 mkcert -ecdsa -client -cert-file /etc/ldnsd/client.pem -key-file /etc/ldnsd/client.key localhost 127.0.0.1
ldnsd takes one argument, the configuration filename. It is a basic YAML
document that covers certificate management and network listening information.
Here is an example. If in doubt, all options have defaults:
# vim: ft=yaml --- certificate: ca: "/etc/ldnsd/rootCA.pem" cert: "/etc/ldnsd/server.pem" key: "/etc/ldnsd/server.key" # grpc listening port grpc: "localhost:7847" # dns listening port (udp only!) listen: "localhost:53" # TLD for domains. domain: "internal"
Launching and Utilization
ldnsd my.conf to launch the service, it does not daemonize so be sure to run
it in the background if you need to. Also, since :53 is privileged port, you
will need to run this process as root.
ldnsctl can be used to query and manipulate the service. To resolve hosts, use DNS:
dig bar.internal. @127.0.0.1
"Set", "List" and "Delete" operations go through
ldnsctl. To review how to
use those operations, please review the
ldnsctl help command's output.
sqlite3 (and the way we use it) under a lot of contention could cause slow responses, which could lead to dropped queries. There are benchmarks at the root of the repository, if you are able to produce this behavior with them please let us know.
On a 12 thread / 6 core intel 9xxx processor, the erikh/dnsserver package delivers 7000ns/op for a similar test that ldnsd delivers in 30000ns/op, suggesting that (understandably) sqlite3 is slower than map access. That said, extended "burn-in" benchmarks have shown no delivery issues so far.
For most other bugs, please see the Issues pages.
Erik Hollensbe firstname.lastname@example.org