ddupdate(8)

1DDUPDATE(8)             System Administration Utilities            DDUPDATE(8)
2
3
4

NAME

6       ddupdate - Update DNS data for dynamic IP addresses
7

SYNOPSIS

9       ddupdate [options]
10

DESCRIPTION

12       A  tool  to  update  dynamic IP addresses typically obtained using DHCP
13       with dynamic DNS service providers such as changeip.com, duckdns.org or
14       no-ip.com.   It makes it possible to access a machine with a fixed name
15       like myhost.duckdns.org even if the ip address changes.
16
17       The tool has a plugin structure with plugins for obtaining  the  actual
18       address (typically hardware-dependent) and to update it (service depen‐
19       dent).
20
21       The normal usecase is to specify all commandline options in the  config
22       file.   However, all options in this file could be overridden by actual
23       command line options e. g., while testing.
24
25       Using service providers and possibly also  firewalls  requires  use  of
26       username/password  credentials.   For these, either the netrc(5) or the
27       system keyring is used.
28
29       ddupdate is distributed with systemd support to run at  regular  inter‐
30       vals,  and with NetworkManager templates to run when interfaces goes up
31       or down. It fully supports ipv6 addresses and also using  proxies  (see
32       ENVIRONMENT).
33

OPTIONS

35       Options for normal operation, typically defined in config file:
36
37
38       -H, --hostname <hostname>
39           Hostname to update,  typically fully qualified. Defaults to the not
40           really usable host.nowhere.net
41
42
43       -s, --service-plugin <plugin>
44           Plugin used to update the dns data for the  address  obtained  from
45           the  address-plugin. Defaults to dry-run, which just prints the ad‐
46           dress. Use --list-services to list available plugins.
47
48
49       -a, --address-plugin <plugin>
50           Plugin used to obtain the actual ip address. Defaults  to  default-
51           if,  which  localizes  the default interface using /usr/sbin/ip and
52           uses it's primary address. Use --list-addressers to list  available
53           plugins.
54
55
56       -C, --auth-plugin <plugin>
57           Plugin   providing  authentication  credentials,  either  netrc  or
58           keyring
59
60
61       -v, --ip-version <v4|v6|all>
62           The kind of ip addresses to register. The addresses obtained by the
63           address-plugin  could be either v6, v4 or both. However, the actual
64           addresses sent to the service plugin is filtered using this  option
65           so  for  example an unused ipv6 address not becomes an official ad‐
66           dress to the host.  Defaults to v4.
67
68
69       -L, --loglevel [level]
70           Determine the amount of logging information. level  is  a  symbolic
71           syslog  level: error,warning, info, or debug.  It defaults to warn‐
72           ing.
73
74
75       -o, --service-option <plugin option>
76           Option  interpreted  by  service  plugin,  documented   in   --help
77           <plugin>.   May be given multiple times as required.  Any option on
78           the command line will clear the list of options as  of  the  config
79           file.  See PLUGIN OPTIONS.
80
81
82       -O, --address-option <plugin option>
83           Option  interpreted  by  address-plugin.   See --service-option and
84           PLUGIN OPTIONS.
85
86
87       Other options:
88
89
90       -c, --config-file <path>
91           File containing default values for all command line  options.   The
92           path  must  be  absolute.   An example file is distributed with the
93           sources.  See [FILES] below.
94
95
96       -f, --force
97           Force ddupdate to run even if the cached value is still valid.
98
99
100       -e, --execute-section <section>
101           Only run the given section in configuration file.  Use  --list-sec‐
102           tions to list available sections.
103
104
105       -h, --help [plugin]
106           Print  help.  If  given  a  plugin  argument,  prints help for this
107           plugin.
108
109
110       -S, --list-services
111           List service provider plugins.
112
113
114       -A, --list-addressers
115           List plugins providing one or more ip addresses
116
117
118       -P, --list-auth-plugins
119           List plugins for storing credentials like netrc and keyring.
120
121
122       -E, --list-sections
123           List available sections in configuration file.
124
125
126       -V, --version
127           Print ddupdate version.
128
129

PLUGIN OPTIONS

131       The plugin options are generally just handed to the plugins without any
132       further  interpretation.   An  option  is  either a single keyword or a
133       key=value string.  No whitespace is allowed in key or value.
134
135

PLUGIN LOADING

137       ddupdate looks for a directory named plugins and tries to load  plugins
138       from  all  files  in this directory. The search for plugins is done, in
139       descending priority:
140
141       •   The directory plugins in the same directory as the main.py  module.
142           This is the development case, and the highest priority.
143
144       •   User plugins are searched in ~/.local/share/ddupdate/plugins.  Set‐
145           ting   the   XDG_DATA_HOME   environment    relocates    this    to
146           $XDG_DATA_HOME/ddupdate/plugins
147
148       •   The  directories  listed in the XDG_DATA_DIRS environment variable,
149           by default  /usr/local/share:/usr/share,  are  searched  for  ddup‐
150           date/plugins.
151
152

EXAMPLES

154       Please  note  that  the  command  line  options  are normally stored in
155       ~/.config/ddupdate.conf, allowing an invocation  without  command  line
156       options.
157
158       Update on dyndns.com using the external address as seen from the inter‐
159       net, displaying the address used:
160
161            ddupdate -a default-web-ip -s dtdns.com -H myhost.dyndns.org -l info
162
163       Make a debug run without actually updating, displaying the  address  on
164       the local, default interface:
165
166            ddupdate -a default-if -s dry-run --loglevel info -H host.dyndns.org
167
168

ENVIRONMENT

170       ddupdate respects the data paths defined by freedesktop.org.
171
172
173       XDG_CACHE_HOME
174           Locates the cached addresses files. See FILES.
175
176
177       XDG_DATA_HOME
178           Locates user plugins. See PLUGIN LOADING.
179
180
181       XDG_DATA_DIRS
182           Involved in system plugins, see PLUGIN LOADING.
183
184
185       XDG_CONFIG_HOME
186           User  configuration  file  parent  directory  location, defaults to
187           ~/.config.
188
189       ddupdate also accepts the standard proxy environment:
190
191
192       http_proxy, https_proxy
193           URL to used proxies for http and  https  connections.  The  systemd
194           service  files  distributed  has  provisions to define these as re‐
195           quired.
196
197
198

FILES

200       ~/.netrc
201           When configured with the netrc authentication backend, this file is
202           used  to  store  username  and  password  for logging in to service
203           providers.  See netrc(5) for the format used.  The file  must  have
204           restricted permissions like 600 to be accepted.
205
206       /etc/netrc
207           Fallback  location for credentials when ~/.netrc is not found.  The
208           use of this file is deprecated.
209
210       ~/.config/ddupdate.conf
211           Default config file location. If defined, the XDG_CONFIG_HOME vari‐
212           able relocates this to $XDG_CONFIG_HOME/ddupdate.conf.
213
214       /etc/ddupdate.conf
215           Fallback configuration file location.
216
217       /usr/share/ddupdate/plugins
218           Default directory for upstream plugins, see PLUGIN LOADING.
219
220       /usr/local/share/ddupdate/plugins
221           Default directory for site plugins, see PLUGIN LOADING.
222
223       ~/.local/share/ddupdate/plugins
224           Default directory for user plugins, see PLUGIN LOADING.
225
226       ~/.cache/ddupdate/*
227           Cached address from last update with an actual change, one for each
228           update service.  Setting the  XDG_CACHE_HOME  environment  variable
229           relocates these files to $XDG_CACHE_HOME/ddupdate/*.
230
231