DDUPDATE(8)

📦
version 0.7.2 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 DDUPDATE(8) 💖

okay bestie, sit DOWN, because today we're talking about ddupdate — it's a System Administration Utilities girlie from section 8 of the manual, and she is literally here to keep your dynamic IP looking cute under a fixed name. ✨

🌸 NAME 🌸

ddupdate — update DNS data for dynamic IP addresses. that's it, that's the whole job, and she does it flawlessly. 💅

🎀 SYNOPSIS 🎀

ddupdate [options]

🦋 DESCRIPTION 🦋

so picture this: your IP address is a little chaos gremlin that keeps changing on you, usually because DHCP handed you something new. ddupdate is the tool that takes that ever-shifting address and tells a dynamic DNS service provider about it — think changeip.com, duckdns.org, or no-ip.com. the whole point? you get to reach your machine at a fixed name like myhost.duckdns.org even when the IP underneath it changes. iconic behaviour, honestly. 🌈

she's built on a plugin structure, which is very main-character of her. there are plugins for getting the actual address (usually hardware-dependent) and separate plugins for updating it (service-dependent). two different jobs, two different plugin types, no cap.

the normal usecase is that you shove all your commandline options into the config file so you don't have to type them every time. BUT — and this is the fun part — every single option in that file can be overridden by an actual command line option, like when you're testing something. bestie said "config file for the everyday, flags for the experiments." 💅

using service providers (and possibly firewalls too) means you need username/password credentials. for those, ddupdate uses either netrc(5) or the system keyring. pick your fighter. 🫶

ddupdate ships with systemd support so it can run at regular intervals, plus NetworkManager templates that fire when an interface goes up or down. she fully supports ipv6 addresses AND proxies (peep the ENVIRONMENT section for that one, iykyk). ✨

✨ OPTIONS ✨

the everyday girlies — usually set in the config file 💖

  • -H, --hostname <hostname> — the hostname you wanna update, typically fully qualified. defaults to the truly unusable host.nowhere.net (she's a placeholder, not a personality, bestie 😭).
  • -s, --service-plugin <plugin> — the plugin that pushes your DNS data to the provider, using the address it got from the address-plugin. defaults to dry-run, which literally just prints the address. want the menu? run --list-services. 💅
  • -a, --address-plugin <plugin> — the plugin that goes and finds your actual IP address. defaults to default-if, which figures out your default interface using /usr/sbin/ip and takes its primary address. run --list-addressers to see all the options. 🦋
  • -C, --auth-plugin <plugin> — the plugin that supplies your authentication credentials. either netrc or keyring. 🔐
  • -v, --ip-version <v4|v6|all> — which kind of IP addresses to register. the address-plugin might hand back v6, v4, or both — but what actually gets sent to the service plugin is filtered through this option. so like, an unused ipv6 address doesn't accidentally become an official address for your host. defaults to v4. 🌈
  • -L, --loglevel [level] — how much logging you want. level is a symbolic syslog level: error, warning, info, or debug. defaults to warning. (yes there's a space in that list, that's just how the manpage wrote it, don't @ me 🫶)
  • -o, --service-option <plugin option> — an option that gets interpreted by the service plugin, documented in --help <plugin>. give it as many times as you need. ⚠️ heads up: any option on the command line will clear the list of options from the config file — so it's not additive, bestie. see PLUGIN OPTIONS. 💀
  • -O, --address-option <plugin option> — same deal but for the address-plugin. see --service-option and PLUGIN OPTIONS. 🎀

other options 🎀

  • -c, --config-file <path> — the file holding default values for all the command line options. the path must be absolute. an example file ships with the sources. see [FILES] below. 📁
  • -f, --force — force ddupdate to run even if the cached value is still valid. she said "I don't care if it's fresh, I'm running it anyway." 🔥
  • -e, --execute-section <section> — only run the given section in the configuration file. use --list-sections to see what's available. 📑
  • -h, --help [plugin] — print help. if you hand her a plugin argument, she prints help for that specific plugin. 🫶
  • -S, --list-services — list the service provider plugins. 🧚
  • -A, --list-addressers — list plugins that provide one or more IP addresses. 🌸
  • -P, --list-auth-plugins — list plugins for storing credentials, like netrc and keyring. 🔑
  • -E, --list-sections — list the available sections in the configuration file. 🗂️
  • -V, --version — print the ddupdate version. ⭐

💅 PLUGIN OPTIONS 💅

so these plugin options are, generally speaking, just yeeted straight to the plugins with zero further interpretation from ddupdate. no vibes check, no processing, just handed over. 🫶

an option is either a single keyword or a key=value string. and ⚠️ no whitespace is allowed in either the key or the value — not even a little, bestie. keep it tight. 💅

🧚 PLUGIN LOADING 🧚

ddupdate goes looking for a directory named plugins and tries to load plugins from all the files in that directory. the search happens in descending priority, so here's the ranking, bestie:

  • The directory plugins in the same directory as the main.py module. this is the development case, and it has the highest priority. 🌈
  • User plugins get searched in ~/.local/share/ddupdate/plugins. setting the XDG_DATA_HOME environment variable relocates this to $XDG_DATA_HOME/ddupdate/plugins. 💖
  • The directories listed in the XDG_DATA_DIRS environment variable — by default /usr/local/share:/usr/share — get searched for ddupdate/plugins. 🦋

🌈 EXAMPLES 🌈

okay quick note before we dive in: the command line options are normally stored in ~/.config/ddupdate.conf, which means you can just run her with no command line options at all. queen of convenience. 👑

Update on dyndns.com using the external address as seen from the internet, displaying the address used:

ddupdate -a default-web-ip -s dtdns.com -H myhost.dyndns.org -l info

Make a debug run without actually updating, displaying the address on the local, default interface:

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

🌸 ENVIRONMENT 🌸

ddupdate respects the data paths defined by freedesktop.org. very mindful, very demure. 🎀

  • XDG_CACHE_HOME — locates the cached addresses files. see FILES. 🗃️
  • XDG_DATA_HOME — locates user plugins. see PLUGIN LOADING. 🧚
  • XDG_DATA_DIRS — involved in system plugins, see PLUGIN LOADING. 🦋
  • XDG_CONFIG_HOME — the parent directory location for the user configuration file, defaults to ~/.config. 📁

ddupdate also accepts the standard proxy environment:

  • http_proxy, https_proxy — the URL to the proxies used for http and https connections. the distributed systemd service files have provisions to define these as required. 🌐

💖 FILES 💖

  • ~/.netrc — when you're configured with the netrc authentication backend, this file stores the 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 — she will NOT be letting that slide, bestie.
  • /etc/netrc — fallback location for credentials when ~/.netrc isn't found. 🚨 the use of this file is deprecated.
  • ~/.config/ddupdate.conf — default config file location. if it's defined, the XDG_CONFIG_HOME variable relocates this to $XDG_CONFIG_HOME/ddupdate.conf. 📝
  • /etc/ddupdate.conf — fallback configuration file location. 🗂️
  • /usr/share/ddupdate/plugins — default directory for upstream plugins, see PLUGIN LOADING. ⬆️
  • /usr/local/share/ddupdate/plugins — default directory for site plugins, see PLUGIN LOADING. 🏠
  • ~/.local/share/ddupdate/plugins — default directory for user plugins, see PLUGIN LOADING. 🫶
  • ~/.cache/ddupdate/* — the cached address from the last update that had an actual change, one for each update service. setting the XDG_CACHE_HOME environment variable relocates these files to $XDG_CACHE_HOME/ddupdate/*. 🗃️

⭐ SEE ALSO ⭐

and that's the whole page, bestie!! 💅 this one's a ddupdate special, last changed Apr 2022, and she's repping DDUPDATE(8) — go forth and keep those dynamic addresses looking immaculate. mwah 🫶💖✨

📦 where this page comes from