NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION FILES
BUGS
AUTHOR
COPYRIGHT
IDENTITIES OF AUTHORS
yabddnsd - Yet another bash dynamic DNS daemon
yabddnsd
[--domain-name
domainName]
[--auth-token-ipv4 authenticationTokenForIPv4]
[--auth-token-ipv6 authenticationTokenForIPv6]
[--config-file sourcedConfigurationFile]
[--detect-public-addr-ipv4
method[@@argument][,method[@@argument]]...]
[--detect-public-addr-ipv6
method[@@argument][,method[@@argument]]...]
[--dns-server dnsServer]
[--dns-server-ipv4 dnsServerForIPv4]
[--dns-server-ipv6 dnsServerForIPv6]
[--one-shot]
[--sleep-time sleepingTimeBetweenIterations]
[--update-protocol updateProtocol]
[--verbose]
yabddnsd --help
yabddnsd --version
yabddnsd --list-functions
yabddnsd [other options]...
--call-function function [functionArguments...]
For regular functionality an update protocol, a domain name and at least one authentication token are required.
Periodically
checks which IP addresses are listed in the given domain
name’s DNS record, and which public IP address this
system has.
If the system’s public IP address isn’t among
the DNS record’s IP addresses, the DNS record is
updated to the system’s public IP address.
--auth-token-ipv4 authenticationTokenForIPv4
The authentication token to use
when updating the IPv4 address (DNS A record).
If no IPv4 authentication token is specified the
domain’s IPv4 address will not be maintained.
--auth-token-ipv6 authenticationTokenForIPv6
The authentication token to use
when updating the IPv6 address (DNS AAAA record).
If no IPv6 authentication token is specified the
domain’s IPv6 address will not be maintained.
--call-function function [functionArguments...]
Call the given function and
exit with the function’s return code. See
--list-functions for available functions.
May be used in combination with other options and
particularly with configuration files; that way one can test
one’s own custom functions or function overrides, see
section CONFIGURATION FILES.
Everything after this option is considered to be function
arguments, which means any other option(s) must be supplied
before this option.
Please note that there is little or no input validation at
all for the function arguments, and some of the regular
arguments that precede --call-function will not be
validated either.
--config-file sourcedConfigurationFile
The configuration file to use,
see section CONFIGURATION FILES.
This option may be specified more than once; all specified
configuration files will be sourced in order of declaration.
For global configuration files see section CONFIGURATION
FILES.
--detect-public-addr-ipv4 method[@@argument][,method[@@argument]]...
The method(s) that should be
used to detect this host’s public IPv4 address, given
as a comma-separated list, or, if the option is specified in
a configuration file, as a bash array.
This script comes with these IPv4 address detection methods:
• File@@path - extract the public IPv4
address from the given text file
• NetDev[@@deviceName] - read the
public IPv4 address from all network devices, or, if a
network device name is given as method argument, from that
specific network device
• Upnp - use UPnP to determine the public IPv4
address
• Url@@url - extract the public IPv4
address from the web site or plain text at the given web
address, such as https://icanhazip.com/ or
https://wtfismyip.com/text
The default methods for IPv4 address detection are
NetDev,Upnp if the program upnpc is
available, if it isn’t only NetDev is used.
The host’s public IPv4 address cannot be read from its
network device(s) if it is behind a router that uses network
address translation (NAT), which is usually the case for
private internet connection setups.
For each declared method
MethodX[@@argument] a function
getIpv4AddrOfThisHostFromMethodX
[argument] is called once, in the order as the
methods are declared.
When one of them prints a result to STDOUT and returns with
code 0, that result is assumed to be this host’s
public IPv4 address, and any subsequent methods will not be
tried.
It is entirely possible to declare a custom such function in
a configuration file, e.g.
getIpv4AddrOfThisHostFromCustom, and then
include the corresponding method (Custom in this
example) into the array of methods.
The function isPublicIpv4Addr IPv4Address may
come in handy to filter out private/special addresses.
--detect-public-addr-ipv6 method[@@argument][,method[@@argument]]...
The method(s) that should be
used to detect this host’s public IPv6 address, just
like --detect-public-addr-ipv4.
This script comes with these IPv6 address detection methods:
• File@@path - extract the public IPv6
address from the given text file
• NetDev[@@deviceName] - read the
public IPv6 address from all network devices, or, if a
network device name is given as method argument, from that
specific network device
• Url@@url - extract the public IPv6
address from the web site or plain text at the given web
address, such as https://icanhazip.com/ or
https://wtfismyip.com/text
The default method for IPv6 address detection is
NetDev.
--dns-server dnsServer
The DNS server to use instead of the system default DNS server.
--dns-server-ipv4 dnsServerForIPv4
The DNS server to use when looking up the domain’s current IPv4 addresses, in case a special DNS server should be used for IPv4 address lookups only.
--dns-server-ipv6 dnsServerForIPv6
The DNS server to use when
looking up the domain’s current IPv6 addresses, in
case a special DNS server should be used for IPv6 address
lookups only.
Some routers filter DNS responses that point to IP addresses
within the local network as a safety measure against DNS
rebinding attacks. For IPv4 with network address translation
(NAT) this is uncritical as the DNS record points to the
router’s public IPv4 address, but without NAT, such as
is usually the case with IPv6, this protective measure may
prevent lookups of the domain name’s IP address.
If you are affected by this, the first thing you should
check is whether your router offers a whitelist for domain
names that should not be subject to the DNS rebinding attack
protection. In case it doesn’t, specifying some other
public IPv6 DNS server using this option may enable you to
work around the issue.
--domain-name domainName
The domain name whose IP address(es) to maintain, such as "your-domain.mooo.com".
|
--help |
Print a help message to STDOUT and exit with code 0. |
--list-functions
Print information about the functions in this script to STDOUT and exit with code 0.
--one-shot
"One-shot" mode of operation, i.e. terminate after attempting at most a single addresses update.
--sleep-time sleepingTimeBetweenIterations
The duration of the pause
between iterations, default is "2m", i.e. 2
minutes. Must be something that is understood by the
sleep command.
The reasoning for such a pause is that it does not make much
sense to immediately check the current DNS record(s) after
an update has been issued to the dynamic DNS service
provider, because it may very well take a few minutes for
the updated DNS record to be propagated to the world’s
DNS servers.
--update-protocol updateProtocol
The update protocol to use when
updating the domain name’s DNS record.
This application comes with these update protocols:
• DuckDns - Duck DNS update protocol
(www.duckdns.org)
• FreeDnsV1 - FreeDNS update protocol, version 1
(freedns.afraid.org)
• FreeDnsV2 - FreeDNS update protocol, version 2
([v6.]sync.afraid.org)
• DeSec - deSEC update protocol
(update.dedyn.io)
Custom update protocols for updating IPv4 or IPv6 addresses,
or for updating both types of addresses in a single request,
can be implemented in configuration files by declaring
custom functions updateIpv4AddrWithCustom,
updateIpv6AddrWithCustom, or
updateAddrsWithCustom, respectively.
--verbose
Enable verbose output, which causes additional lines prefixed with DEBUG to be printed to STDERR.
--version
Print the version string to STDOUT and exit with code 0.
Apart from providing arguments one can also set the various options through configuration files that are sourced by yabddnsd.
Insofar as they exist yabddnsd first reads these configuration files, in this order, wildcards expanded alphabetically:
•
/usr/lib/yabddnsd/yabddnsd.d/*.conf
• /usr/lib/yabddnsd/yabddnsd.conf
• /etc/yabddnsd/yabddnsd.d/*.conf
• /etc/yabddnsd/yabddnsd.conf
• /run/yabddnsd/yabddnsd.d/*.conf
• /run/yabddnsd/yabddnsd.conf
• ˜/.config/yabddnsd/yabddnsd.d/*.conf
• ˜/.config/yabddnsd/yabddnsd.conf
After that yabddnsd scans the arguments array for the --config-file argument and sources the so given configuration file. This argument may be given multiple times if multiple configuration files should be read; they are read in the order as they occur in the arguments.
As is the case with sourcing, subsequent files may overwrite options that have been set by their predecessors. Also, after the --config-file files have been sourced, the other arguments are evaluated and in turn take precedence over anything that has been set in a configuration file.
In configuration
files, options are set by globally setting an option’s
corresponding variable to the desired value.
The variables are "camelCased" derivations of
their respective long --command-line-argument:
•
domainName for argument --domain-name
• authTokenIpv4 for argument
--auth-token-ipv4
• verbose for argument --verbose
• (...)
To set e.g. your-domain.mooo.com as domain name one would put this into a configuration file:
domainName=’your-domain.mooo.com’
Likewise for the other options that expect a non-boolean single value. For boolean options such as --verbose the only allowed values are "true" and "false", and options that take multiple values at once, such as --detect-public-addr-ipv4, must be declared as a bash array, for example:
detectPublicAddrIpv4=( ’Upnp’ ’Url@@https://some-url.net/’ )
Configuration files also enable you to implement certain bash functions to your liking, such as custom public IP address detection methods for the options --detect-public-addr-ipv4 and --detect-public-addr-ipv6, as well as these reserved functions that are used if they are declared:
getIpv4AddrsOfDomainCustom domainName [dnsServerIpv4]
getIpv6AddrsOfDomainCustom domainName [dnsServerIpv6]
getTxtRecordsOfDomainCustom domainName [dnsServerTxt]
If such a
function returns with a code of 0, then its result takes
precedence over the script’s own means of resolving
the domain name’s IP addresses (or retrieving its DNS
TXT records). The result is expected to be a
newline-terminated list of the given domain name’s
current IP addresses / TXT record lines.
An empty list is a valid result; this means that the domain
name currently does not have any IP addresses / TXT
records.
You generally may override any of this script’s functions provided you know what you are doing, see --list-functions.
Should you decide to implement or override a function be aware that this script uses the bash options nounset, noclobber, pipefail and errexit combined with inherit_errexit.
No bugs, this is
perfect code.
Just kidding, there are bound to be some bugs around, it
just seems nobody has found any particular ones yet.
eomanis
E-Mail: eomanis@web.de
PGP key fingerprint: F576 37E9 E5C2 8F91 EE64 277B 603E EF8F
E0A9 9498
Copyright 2014-2020, 2023 eomanis
yabddnsd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
yabddnsd 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 yabddnsd. If not, see <http://www.gnu.org/licenses/>.
Should it be required to ascertain the identity of an author, the person who can prove to be in possession of the secret master key of an author’s PGP key is to be considered the respective author.
In case an author’s PGP key has been replaced by another PGP key, the person who can prove the key supersession in the most convincing manner is to be considered the respective author. For example, an author may document the existence of a properly signed key supersession declaration at a certain point in time in a provably tamper-proof way, such as embedding the declaration or a cryptographically secure hash of it in an irreversible blockchain.