ddupdate.8

.TH DDUPDATE "8" "Last change: Apr 2022" "ddupdate" "System Administration Utilities"
.SH NAME
.P
\fBddupdate\fR - Update DNS data for dynamic IP addresses
.SH SYNOPSIS
.B ddupdate
[\fIoptions\fR]
.SH DESCRIPTION
A tool to update dynamic IP addresses typically obtained using DHCP with
dynamic DNS service providers such as changeip.com, duckdns.org or no-ip.com.
It makes it possible to access a machine with a fixed
name like myhost.duckdns.org even if the ip address changes.
.P
The tool has a plugin structure with plugins for obtaining the actual
address (typically hardware-dependent) and to update it (service
dependent).
.P
The normal usecase is to specify all commandline options in the config
file.
However, all options in this file could be overridden by actual command line
options e. g., while testing.
.P
Using service providers and possibly also firewalls requires use of
username/password credentials.
For these, either the netrc(5) or the system keyring is used.
.P
\fBddupdate\fR is distributed with systemd support to run at regular intervals,
and with NetworkManager templates to run when interfaces goes up or down. It
fully supports ipv6 addresses and also using proxies (see ENVIRONMENT).
.PP

.SH OPTIONS

Options for normal operation, typically defined in config file:

.TP 4
\fB-H, --hostname\fR <\fIhostname\fR>
Hostname to update,  typically fully qualified. Defaults to the not really
usable host.nowhere.net

.TP 4
\fB-s, --service-plugin\fR <\fIplugin\fR>
Plugin used to update the dns data for the address obtained
from the address-plugin. Defaults to dry-run, which just prints the
address. Use \fI\-\-list-services\fR to list available
plugins.

.TP 4
\fB-a, --address-plugin\fR <\fIplugin\fR>
Plugin used to obtain the actual ip address. Defaults to default-if,
which localizes the default interface using /usr/sbin/ip and uses it's
primary address. Use \fI\-\-list-addressers\fR to list available
plugins.

.TP 4
\fB-C, --auth-plugin <\fIplugin\fR>
Plugin providing authentication credentials, either \fInetrc\fR or
\fIkeyring\fR

.TP 4
\fB-v, --ip-version\fR <\fIv4\fR|\fIv6\fR|\fIall\fR>
The kind of ip addresses to register. The addresses obtained by the
address-plugin could be either v6, v4 or both. However, the actual addresses
sent to the service plugin is filtered using this option so for example
an unused ipv6 address not becomes an official address to the host.
Defaults to \fIv4\fr.

.TP 4
\fB-L, --loglevel\fR [\fIlevel\fR]
Determine the amount of logging information. \fIlevel\fR is a symbolic
syslog level: \fIerror\fR,\fIwarning, \fIinfo\fR,
or \fIdebug\fR.
It defaults to \fIwarning\fR.

.TP 4
\fB-o, --service-option\fR <\fIplugin option\fR>
Option interpreted by service plugin, documented in \fI--help <plugin>\fR.
May be given multiple times as required.
Any option on the command line will clear the list of options as of the
config file.
See PLUGIN OPTIONS.

.TP 4
\fB-O, --address-option\fR <\fIplugin option\fR>
Option interpreted by address-plugin.
See \fI\-\-service-option\fR and PLUGIN OPTIONS.

.P
Other options:

.TP 4
\fB-c, --config-file\fR <\fIpath\fR>
File containing default values for all command line options.
The path must be absolute.
An example file is distributed with the sources.
See [FILES] below.

.TP 4
\fB-f, --force\fR
Force \fBddupdate\fR to run even if the cached value is still valid.

.TP 4
\fB-e, --execute-section <section>\fR
Only run the given section in configuration file.
Use \fI\-\-list-sections\fR to list available sections.

.TP 4
\fB-h, --help [plugin]  \fR
Print help. If given a plugin argument, prints help for this plugin.

.TP 4
\fB-S, --list-services\fR
List service provider plugins.

.TP 4
\fB-A, --list-addressers\fR
List plugins providing one or more ip addresses

.TP 4
\fB-P, --list-auth-plugins\fR
List plugins for storing credentials like \fInetrc\fR and \fIkeyring\fR.

.TP 4
\fB-E, --list-sections\fR
List available sections in configuration file.

.TP 4
\fB-V, --version\fR
Print \fBddupdate\fR version.

.SH PLUGIN OPTIONS
The plugin options are generally just handed to the plugins without
any further interpretation.
An option is either a single keyword or a \fIkey=value\fR
string.
No whitespace is allowed in \fIkey\fR or \fIvalue\fR.

.SH PLUGIN LOADING
\fBddupdate\fR looks for a directory named \fIplugins\fR and tries to load
plugins from all files in this directory. The search for \fIplugins\fR
is done, in descending priority:
.IP \(bu 4
The directory \fIplugins\fR in the same directory as the main.py module.
This is the development case, and the highest priority.
.IP \(bu 4
User plugins are searched in \fI~/.local/share/ddupdate/plugins\fR.
Setting the XDG_DATA_HOME environment relocates this to
\fI$XDG_DATA_HOME/ddupdate/plugins\fR
.IP \(bu 4
The directories listed in the XDG_DATA_DIRS environment variable,
by default \fI/usr/local/share:/usr/share\fR, are searched for
\fIddupdate/plugins\fR.

.SH EXAMPLES
.P
Please note that the command line options are normally stored
in \fI~/.config/ddupdate.conf\fR, allowing an invocation without command line
options.
.P
Update on dyndns.com using the external address as seen from the
internet, displaying the address used:

.nf
	ddupdate -a default-web-ip -s dtdns.com -H myhost.dyndns.org -l info
.fi
.P
Make a debug run without actually updating, displaying the address
on the local, default interface:

.nf
	ddupdate -a default-if -s dry-run --loglevel info -H host.dyndns.org
.fi

.SH ENVIRONMENT
\fBddupdate\fR respects the data paths defined by freedesktop.org.

.TP 4
.B XDG_CACHE_HOME
Locates the cached addresses files. See FILES.

.TP 4
.B XDG_DATA_HOME
Locates user plugins. See PLUGIN LOADING.

.TP 4
.B XDG_DATA_DIRS
Involved in system plugins, see PLUGIN LOADING.

.TP 4
.B XDG_CONFIG_HOME
User configuration file parent directory location, defaults to
\fI~/.config\fR.
.P
\fBddupdate\fR also accepts the standard proxy environment:

.TP 4
.B http_proxy, https_proxy
URL to used proxies for http and https connections. The systemd service
files distributed has provisions to define these as required.


.SH FILES
.TP 4
.B ~/.netrc
When configured with the \fInetrc\fR authentication backend, this file is
used to store username and password for logging in to service providers.
See netrc(5) for the format used.
The file must have restricted permissions like 600 to be accepted.
.TP 4
.B /etc/netrc
Fallback location for credentials when \fI~/.netrc\fR is not found.
The use of this file is deprecated.
.TP 4
.B ~/.config/ddupdate.conf
Default config file location. If defined, the XDG_CONFIG_HOME variable
relocates this to \fI$XDG_CONFIG_HOME/ddupdate.conf\fR.
.TP 4
.B  /etc/ddupdate.conf
Fallback configuration file location.
.TP 4
.B /usr/share/ddupdate/plugins
Default directory for upstream plugins, see PLUGIN LOADING.
.TP 4
.B /usr/local/share/ddupdate/plugins
Default directory for site plugins, see PLUGIN LOADING.
.TP 4
.B ~/.local/share/ddupdate/plugins
Default directory for user plugins, see PLUGIN LOADING.
.TP 4
.B  ~/.cache/ddupdate/*
Cached address from last update with an actual change, one for each
update service.
Setting the XDG_CACHE_HOME environment variable relocates these files to
$XDG_CACHE_HOME/ddupdate/*.

.SH "SEE ALSO"
.TP 4
.B ddupdate.conf(5)
Configuration file
.TP 4
.B ddupdate-config(8)
Configuration tool
.TP 4
.B netrc(5)
Authentication tokens file, originally used by ftp(1), used by the
netrc authentication backend.
.TP 4
.B https://pypi.org/project/keyring/
Interface for the keyring authentication backend
.TP 4
.B  https://github.com/leamas/ddupdate
Project homesite and README