GDNSDCTL(8)

📦
version 3.8.3 · 7 versions
, in debian trixie, ubuntu questing

💖 GDNSDCTL 💖

okay bestie, gather round, because we're talking about gdnsdctl — the control socket client for gdnsd, and it's from section 8 of the manual, which means it's a sysadmin tool and it's iconic for it 💅

✨ NAME ✨

gdnsdctl — Control socket client for gdnsd 🎀

🦋 SYNOPSIS 🦋

Usage: gdnsdctl [-c /etc/gdnsd] [-s <IP:port>] [-D] [-l] [-t 47] [-o] [-i] <action> [...]
  -c - Configuration directory (def /etc/gdnsd), for finding UNIX control socket path
  -s - TCP control socket address
  -D - Enable verbose debug output
  -l - Send logs to syslog rather than stderr
  -t - Timeout in seconds (def 47, range 5 - 300)
  -o - One-shot mode: do not retry soft failures (comms errors, replace-in-progress)
  -i - Ignore lack of a running daemon for stop, reload-zones, replace,
       and acme-dns-01-flush, reporting success instead of failure in those cases.
Actions:
  stop - Stops the running daemon
  reload-zones - Reload the running daemon's zone data
  replace - Ask daemon to spawn a takeover replacement of itself (updates code, config, zone data)
  status - Checks the running daemon's status
  stats - Dumps JSON statistics from the running daemon
  states - Dumps JSON monitored states
  acme-dns-01 - Create ACME DNS-01 payloads from additional arguments:
                <name> <payload> <name> <payload> ... [max %u payloads]
  acme-dns-01-flush - Flush (remove) all ACME DNS-01 payloads added above

so yeah, that's the whole vibe of the thing up top. keep scrolling, there's lore 👇

🌸 DESCRIPTION 🌸

gdnsdctl is the canonical control socket client for gdnsd. all of the operations listed above are synchronous, and they tell you how it went by exiting with status zero for success, or non-zero for failure. no vibes-based guessing, it's literally just the exit code 🫶

in general, gdnsd and gdnsdctl support concurrent execution of disparate actions from multiple actors against a single daemon, and everything should eventually faithfully report success without any bugs caused by races, as long as there are no other issues. like, it's built for that 💅

which is to say — for example — things should be reliable if your configuration management is routinely executing gdnsdctl replace for configuration updates, and another tool is independently routinely executing gdnsdctl reload-zones as it updates zonefile data, while a third set of tooling is doing gdnsdctl acme-dns-01 commands, even if all 3 commands collide with near-perfect timing. eventually all 3 gdnsdctl commands will exit, and the resulting state will have all of the configuration, zone data, and challenge updates. slay ✨

this is also true of multiple independent and overlapping executions of the same action, such as multiple reload-zones requests proceeding in parallel, or multiple acme-dns-01 requests. no cap. 🔥

👑 COMMANDLINE OPTION FLAGS 👑

  • -c — sets the configuration directory, defaulting to /etc/gdnsd. it's used to find the main daemon's configuration file and parse it, just in case it sets a non-default run_dir, which would change the location of the daemon's UNIX control socket path. sneaky little indirect thing, but there it is 🎀
  • -s — this tells gdnsdctl to connect to the daemon over a TCP control socket instead of the usual local UNIX domain socket. if you wanna know about configuring the server side of this, go read the gdnsd.config(5) docs about tcp_control. iykyk 🦋
  • -D — enables additional debug-level log output as appropriate. turn it on when you need to see the receipts 🔍
  • -l — sends log output to syslog rather than the default stderr. pick your destination, bestie ✨
  • -t — sets the timeout in seconds (default 47) for the entire execution. this is enforced via a process-level SIGALRM timer, but heads up: it can run slightly over time in corner cases. so like, approximately 47, don't come for her 💀
  • -o — one-shot mode. normally, gdnsdctl will persistently retry to execute the action under soft failure conditions. those soft failure conditions happen when the daemon is in the midst of a replace operation, or when a communications error occurs after the connection is initially established (which could be the racy result of catching bad timing with the old daemon shutting down during a replace operation). this flag disables the retries and upgrades all soft (retryable) errors to hard (immediately-fatal) errors. so yeah, one shot, no takebacks 😭
  • -i — ignore-dead-daemon mode. normally, all actions fail if no daemon is currently running. with this flag set, if the daemon is not currently running, but the action is one of the limited set where the intent would be accurately reflected by a future start of the daemon, gdnsdctl will return a successful exit value in spite of the lack of a running daemon. basically: "she's not here right now but it's fine, i got you" 🫶

the set of commands which currently honor -i are: reload-zones, stop, acme-dns-01-flush, and replace. those four, and only those four, bestie 👑

fr fr: don't just slap -i on everything and assume it'll paper over a dead daemon. it's a limited set for a reason 💅

✨ Actions ✨

Okay bestie, this is the whole menu of things you can actually ask the daemon to do. Each one is its own little vibe. Let's go 💅

🌸 stop

Synchronously stops the running daemon. Exit status zero means the daemon was observed to stop as commanded. That's it, that's the whole thing — clean, no drama, she simply left 🫶

With -i, exit status zero can also mean the daemon was already not running, which makes gdnsdctl -i stop an idempotent stop. Idempotent, meaning you can spam it and it just keeps being fine. Iconic behavior honestly.

🌸 reload-zones

Synchronously reloads the daemon's zonefiles. Exit status zero indicates the operation completed successfully and the new data is visible to clients. Fresh zones, zero cap ✨

With -i, exit status zero can also mean the daemon was not running (if it's started in the future, the recently-updated zonefiles would be in effect).

🌸 replace

Asks the running daemon to spawn a replacement instance of itself. This can be used for daemon code upgrades and/or configuration changes. The replace sequence is intended to have minimal operational impact from most points of view: it's race-free, requests are not lost or dropped and there is no pause in processing requests. Stats data is handed off seamlessly from the old instance to the new one, as is any ephemeral ACME DNS-01 challenge data. The control socket remains available for new connections at all times, but the actual processing of new connections is delayed for a short span of time.

Commands from already-connected control socket clients (like gdnsdctl) can be denied with a soft failure response during critical time windows of the replace sequence, but gdnsdctl will wait and retry them afterwards. She's patient like that 💖

The replacement daemon is initially executed as a child of the running daemon and thus inherits many attributes of its execution environment. The old and new daemons coordinate a handoff process over an inter-daemon control socket connection. The handoff process does its best to ensure that if the new daemon fails at any stage of startup, the old daemon can continue operations as it was before.

DNS listening sockets are handed off in an overlapped fashion: there will be a brief window of time where client requests can be routed to either daemon randomly, but there should never be a window where service is unavailable. The control socket itself is handed off synchronously: the old daemon stops accepting new connections before the new daemon begins accepting them, and the old daemon re-starts accepting if the new daemon fails to succeed completely.

Once the old daemon claims the replacement process was successful, gdnsdctl will monitor the old daemon's exit and then make a fresh connection to the control socket of the new daemon and check its status. If all of this is successful, the replace command will finally exit with status zero. It will exit with a non-zero status if any part of this operation fails for any reason, which should in most conceivable cases leave the existing daemon fully functional.

All other daemon-state-changing gdnsdctl operations (anything but the readonly actions status, stats, and states) which might be initiated separately and concurrently are explicitly blocked by the daemon while the critical part of the replace handoff sequence is in progress. gdnsdctl will, by default, retry an action repeatedly until the replace finishes and lets the action through or it reaches the -t timeout. The -o flag disables these retries, which will cause the state-changing gdnsdctl actions to immediately fail during the critical replace window.

Normally, this command will fail if there is no running daemon. However, with -i, exit status zero can also mean the daemon was not running (if it's started in the future, the recently-updated configuration or binary that triggered wanting to execute the replace request would then be in effect).

The retry system works for replace vs replace as well: if you concurrently execute several gdnsdctl replace commands, one will proceed first and the rest will wait in retry loops to each take their turn replacing the daemon serially until they've all done so successfully, unless their gdnsdctl -t timeout expires first (each new daemon will take some time to start, depending on the zonefile count and configuration complexity). Queue up besties, everyone gets a turn 👑

🌸 status

Checks the running daemon's status, reporting its PID and version to stderr.

Heads up: it goes to stderr, not stdout. Not a typo, not a glitch, that's just the assignment 🎀

🌸 stats

Dumps JSON statistics from the running daemon to stdout. Number-crunching girlies rise up 🔥

🌸 states

Dumps JSON monitored states from any configured service health monitors.

🌸 acme-dns-01

Injects temporary ACME DNS-01 challenge response payloads as defined by <https://tools.ietf.org/html/draft-ietf-acme-acme-14> into the running daemon. This is intended for integration with scripts or services which generate signed certificates from an ACME-capable certificate authority. Certificates, but make it automated 💜

Two or more additional commandline arguments are required, in pairs of name and payload, where name is a valid domainname and payload is the challenge response payload (which, as a SHA-256 output encoded in base64url encoding, should be 43 bytes long and consist of only alphanumeric characters plus - and _). A maximum of 100 separate payloads can be specified in a single gdnsdctl invocation.

This example...

gdnsdctl acme-dns-01 example.org 0123456789012345678901234567890123456789012 www.example.org ABCDEFGHIJKLMNOPQRSTUVWXYZ-abcdefghijklmnop

... causes the daemon to temporarily respond to TXT requests for the name _acme-challenge.example.org. with the first payload above, and similarly with the second payload for _acme-challenge.www.example.org..

Challenge payload responses injected by this command automatically expire after a short time. The default is 10 minutes, and is configurable via the config option acme_challenge_ttl. The actual DNS TTL emitted with the TXT responses defaults to zero (which is highly recommended!) and is controlled by the separate option acme_challenge_dns_ttl.

Injecting responses for domainnames that are not within the scope of one of the statically-configured zones will succeed, but the response to such queries will still be REFUSED (until such a zone later appears, if ever). So like, you can, but the universe will not cooperate yet 🌈

If more than one payload is configured for a given name (in the same command, or in separate commands less than the TTL window apart), multiple TXT records will be emitted. If there is any statically-configured TXT data from zonefiles at a conflicting _acme-challenge name, the static TXT RRs will also be served alongside any data from this mechanism.

As an implementail detail (quirk?) of this mechanism, any static zonefile RRs which have a first label of _acme-challenge will automatically have their TTLs forced to the acme_challenge_dns_ttl regardless of the TTL specified in the zonefile. This was the easiest way to ensure that we never serve mixed TTL values in a single RR-set of TXT records, which is forbidden by RFC 2181. Respect the RFC or she will simply not participate 🙈

The data injected by this mechanism persists through daemon replace operations, but not through a full stop of the daemon. It also persists through zone data reloads, and in the case that data is injected for a non-existent zone which then comes into existence through a reload, the challenge will begin working after the reload.

🌸 acme-dns-01-flush

Immediately flushes all injected payload data from above ahead of its natural expiry. Mostly useful for testing or for clearing up mistakes, but some integrations with spiky large volumes of challenges may wish to flush data explicitly at points in time when there are no outstanding DNS-01 challenges.

This is another command that honors the -i flag: if -i is specified and the daemon is not running, this command will report success, as a dead daemon has no challenge data to flush. Ghost town, nothing to clean, success reported anyway 💀✨

🌟 EXIT STATUS 🌟

In general, all operations exit with status zero if and only if the operation is successful. Errors and most other output go to stderr, except in the case of JSON data dumps, which go to stdout. Zero means slay, non-zero means investigate, that's the whole system 🫶

🔗 SEE ALSO 🔗

The gdnsd manual. Go read the whole cinematic universe, bestie 📚

Copyright (c) 2012 Brandon L Black <blblack@gmail.com>

This file is part of gdnsd.

gdnsd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

gdnsd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gdnsd. If not, see <http://www.gnu.org/licenses/>.

And that's a wrap on GDNSDCTL(8) from gdnsd 3.8.3, dated 2025-02-16 🎀 Copyright said 2012 and the page is still serving looks in 2025, that's longevity, that's main character energy, that's a legacy 💖 Go forth and control your daemon, bestie. You've got this fr fr 🌸🦋

📦 where this page comes from