FreeBSD Manual Pages

home | help

GDNSDCTL(8) gdnsd GDNSDCTL(8)

NAME
gdnsdctl - Control socket client for gdnsd

SYNOPSIS
Usage: gdnsdctl [-c /usr/local/etc/gdnsd] [-s <IP:port>] [-D] [-l] [-t 47] [-o] [-i] <action> [...]
-c - Configuration directory (def /usr/local/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

DESCRIPTION
gdnsdctl is the canonical control socket client for gdnsd. All operations
described above are synchronous and report success by exiting with exit
status zero, or failure by non-zero.

In general gdnsd and gdnsdctl support concurrent execution of disparate ac-
tions from multiple actors against a single daemon, and everything should
eventually faithfully report success without any bugs caused by races, if
there are no other issues.

That is to say, for example, things should be reliable if your configura-
tion 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.

This is also true of multiple independent and overlapping executions of the
same action, such as multiple "reload-zones" requests proceeding in paral-
lel, or multiple "acme-dns-01" requests.

COMMANDLINE OPTION FLAGS
-c Set the configuration directory, defaults to /usr/local/etc/gdnsd.
This is used to find the main daemon's configuration file and parse it,
in case it sets a non-default "run_dir", which would change the loca-
tion of the daemon's UNIX control socket path.

-s This tells gdnsdctl to connect to the daemon over a TCP control socket
instead of the usual local UNIX domain socket. See the gdnsd.config(5)
docs about "tcp_control" for more information about configuring the
server side of this.

-D Enables additional debug-level log output as appropriate.

-l Sends log output to syslog rather than the default stderr.

-t Sets the timeout in seconds (default 47) for the entire execution.
This is enforced via a process-level SIGALRM timer, but it can run
slightly over time in corner cases.

-o One-shot mode. Normally, gdnsdctl will persistently retry to execute
the action under soft failure conditions. The 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 dis-
ables the retries and upgrades all soft (retryable) errors to hard (im-
mediately-fatal) errors.

-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.

The set of commands which currently honor "-i" are: "reload-zones",
"stop", "acme-dns-01-flush", and "replace".

Actions
stopSynchronously stops the running daemon. Exit status zero means the
daemon was observed to stop as commanded.

With "-i", exit status zero can also mean the daemon was already not
running, which makes "gdnsdctl -i stop" an idempotent stop.

reload-zones
Synchronously reloads the daemon's zonefiles. Exit status zero indi-
cates the operation completed successfully and the new data is visible
to clients.

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 after-
wards.

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-dae-
mon 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 ser-
vice is unavailable. The control socket itself is handed off synchro-
nously: 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 con-
nection 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 initi-
ated 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-chang-
ing gdnsdctl actions to immediately fail during the critical replace
window.

Normally, this command will fail if there is no running daemon. How-
ever, with "-i", exit status zero can also mean the daemon was not run-
ning (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 con-
currently execute several "gdnsdctl replace" commands, one will proceed
first and the rest will wait in retry loops to each take their turn re-
placing the daemon serially until they've all done so successfully, un-
less their gdnsdctl "-t" timeout expires first (each new daemon will
take some time to start, depending on the zonefile count and configura-
tion complexity).

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

stats
Dumps JSON statistics from the running daemon to stdout.

states
Dumps JSON monitored states from any configured service health moni-
tors.

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 au-
thority.

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 al-
phanumeric 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.exam-
ple.org.".

Challenge payload responses injected by this command automatically ex-
pire after a short time. The default is 10 minutes, and is config-
urable via the config option "acme_challenge_ttl". The actual DNS TTL
emitted with the "TXT" responses defaults to zero (which is highly rec-
ommended!) and is controlled by the separate option "acme_chal-
lenge_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 ap-
pears, if ever).

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), mul-
tiple TXT records will be emitted. If there is any statically-config-
ured 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 zone-
file RRs which have a first label of "_acme-challenge" will automati-
cally have their TTLs forced to the "acme_challenge_dns_ttl" regardless
of the TTL specified in the zonefile. This was the easiest way to en-
sure that we never serve mixed TTL values in a single RR-set of TXT
records, which is forbidden by RFC 2181.

The data injected by this mechanism persists through daemon "replace"
operations, but not through a full "stop" of the daemon. It also per-
sists through zone data reloads, and in the case that data is injected
for a non-existent zone which then comes into existence through a re-
load, 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 outstand-
ing 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.

EXIT STATUS
In general, all operations exit with status zero if and only if the opera-
tion is successful. Errors and most other output go to stderr, except in
the case of JSON data dumps, which go to stdout.

SEE ALSO
gdnsd(8), gdnsd.config(5), gdnsd.zonefile(5)

The gdnsd manual.

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 de-
tails.

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

gdnsd 3.8.0 2026-08-01 GDNSDCTL(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gdnsdctl&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages