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.   ddupdate
16       caches  the  address, and only attempts the update if the address actu‐
17       ally is changed.
18
19       The tool has a plugin structure with plugins for obtaining  the  actual
20       address (typically hardware-dependent) and to update it (service depen‐
21       dent).
22
23       The normal usecase is to specify all commandline options in the  config
24       file.   However, all options in this file could be overridden by actual
25       command line options e. g., while testing.
26
27       Using service providers and possibly also  firewalls  requires  use  of
28       username/password credentials.  For these, the netrc(5) file is used.
29
30       ddupdate  is  distributed with systemd support to run at regular inter‐
31       vals, and with NetworkManager templates to run when interfaces goes  up
32       or  down.  It fully supports ipv6 addresses and also using proxies (see
33       ENVIRONMENT).
34

OPTIONS

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

PLUGIN OPTIONS

114       The plugin options are generally just handed to the plugins without any
115       further interpretation.  An option is either  a  single  keyword  or  a
116       key=value string.  No whitespace is allowed in key or value.
117
118

PLUGIN LOADING

120       ddupdate  looks for a directory named plugins and tries to load plugins
121       from all files in this directory. The search for plugins  is  done,  in
122       descending priority:
123
124       ·   The  directory plugins in the same directory as the main.py module.
125           This is the development case, and the highest priority.
126
127       ·   User plugins are searched in ~/.local/share/ddupdate/plugins.  Set‐
128           ting    the    XDG_DATA_HOME    environment   relocates   this   to
129           $XDG_DATA_HOME/ddupdate/plugins
130
131       ·   The directories listed in the XDG_DATA_DIRS  environment  variable,
132           by  default  /usr/local/share:/usr/share,  are  searched  for ddup‐
133           date/plugins.
134
135

EXAMPLES

137       Please note that the  command  line  options  are  normally  stored  in
138       /etc/ddupdate.conf,   allowing   an  invocation  without  command  line
139       options.
140
141       Update on dyndns.com using the external address as seen from the inter‐
142       net, displaying the address used:
143
144            ddupdate -a default-web-ip -s dtdns.com -H myhost.dyndns.org -l info
145
146       Make  a  debug run without actually updating, displaying the address on
147       the local, default interface:
148
149            ddupdate -a default-if -s dry-run --loglevel info -H host.dyndns.org
150
151

ENVIRONMENT

153       ddupdate respects the data paths defined by freedesktop.org.
154
155
156       XDG_CACHE_HOME
157           Locates the cached addresses files. See FILES.
158
159
160       XDG_DATA_HOME
161           Locates user plugins. See PLUGIN LOADING.
162
163
164       XDG_DATA_DIRS
165           Involved in system plugins, see PLUGIN LOADING.
166
167
168       XDG_CONFIG_HOME
169           User configuration file  parent  directory  location,  defaults  to
170           ~/.config.
171
172       ddupdate also accepts the standard proxy environment:
173
174
175       http_proxy, https_proxy
176           URL  to  used  proxies  for http and https connections. The systemd
177           service  files  distributed  has  provisions  to  define  these  as
178           required.
179
180
181

FILES

183       ~/.netrc
184           Used  to  store  username  and  password  for logging in to service
185           providers to update, firewalls to  get  the  IP  address  etc.  See
186           netrc(5) for the format used. The file must have restricted permis‐
187           sions like 600 to be accepted.
188
189       /etc/netrc
190           Fallback location for credentials when ~/.netrc is not found.
191
192       ~/.config/ddupdate.conf
193           Default config file location. If defined, the XDG_CONFIG_HOME vari‐
194           able relocates this to $XDG_CONFIG_HOME/ddupdate.conf.
195
196       /etc/ddupdate.conf
197           Fallback configuration file location.
198
199       /usr/share/ddupdate/plugins
200           Default directory for upstream plugins, see PLUGIN LOADING.
201
202       /usr/local/share/ddupdate/plugins
203           Default directory for site plugins, see PLUGIN LOADING.
204
205       ~/.local/share/ddupdate/plugins
206           Default directory for user plugins, see PLUGIN LOADING.
207
208       ~/.cache/ddupdate/*
209           Cached address from last update with an actual change, one for each
210           update service.  Setting the  XDG_CACHE_HOME  environment  variable
211           relocates these files to $XDG_CACHE_HOME/ddupdate/*.
212
213