.\"  -*- nroff -*-
.\"
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.\" Copyright (C) 2004       Shaul Karl.
.\" Copyright (C) 2010-2021  Joachim Wiberg.
.\"
.\" You may modify and distribute this document for any purpose, as
.\" long as this copyright notice remains intact.
.\"
.Dd February 20, 2020
.Dt INADYN 8 SMM
.Os
.Sh NAME
.Nm inadyn
.Nd Internet Automated Dynamic DNS Client
.Sh SYNOPSIS
.Nm inadyn
.Op Fl 1, -once
.Op Fl -force
.Op Fl -cache-dir Ar PATH
.Op Fl c, -cmd Ar /path/to/cmd
.Op Fl C, -continue-on-error
.Op Fl e, -exec Ar /path/to/cmd
.Op Fl -exec-mode Ar MODE
.Op Fl f, -config Ar FILE
.Op Fl h, -help
.Op Fl i, -iface Ar IFNAME
.Op Fl I, -ident Ar NAME
.Op Fl l, -loglevel Ar LEVEL
.Op Fl L, -list-providers
.Op Fl n, -foreground
.Op Fl -no-pidfile
.Op Fl P, -pidfile Ar FILE
.Op Fl p, -drop-privs Ar USER Ns Op : Ns Ar GROUP
.Op Fl s, -syslog
.Op Fl S, -show-provider NAME
.Op Fl t, -startup-delay Ar SEC
.Op Fl v, -version
.Sh DESCRIPTION
.Nm ,
or In-a-Dyn, periodically checks your actual Internet accessible IP for
changes.  When it changes
.Nm
updates your name server record(s) automatically.
.Pp
Common DDNS service providers supported by
.Nm
are listed below.  Some of these services are free of charge for
non-commercial use, others take a small fee, but also provide more
domain names to choose from.
.Pp
.Nm
defaults to HTTPS for all providers, some may however not support this
so try disabling SSL for your provider in case of problems.  Providers
known to support SSL updates are listed below with
.Sy https .
The list is ordered by the plugin that support the service:
.Pp
.Bl -bullet -compact
.It
.Aq https://freedns.afraid.org
.It
.Aq https://nsupdate.info
.It
.Aq https://duckdns.org
.It
.Aq https://freemyip.com
.It
.Aq http://www.dyndns.org ,
.Aq http://dyn.com
.Bl -bullet -compact
.It
.Aq http://dns.he.net
.It
.Aq https://www.dnsomatic.com
.It
.Aq https://domains.google
.It
.Aq https://www.dynu.com
.It
.Aq https://www.loopia.com
.It
.Aq http://www.noip.com
.It
.Aq https://www.pubyun.com ,
formerly
.Aq http://www.3322.org
.It
.Aq https://www.selfhost.de
.It
.Aq https://spdyn.de
.El
.It
.Aq http://www.easydns.com
.It
.Aq http://www.tunnelbroker.net
.It
.Aq http://www.sitelutions.com
.It
.Aq http://www.dnsexit.com ,
parent of
.Aq https://zoneedit.com
.It
.Aq http://www.changeip.com
.Bl -bullet -compact
.It
.Aq https://www.ovh.com
.It
.Aq https://www.strato.com
.El
.It
.Aq http://www.dhis.org
.It
.Aq http://giradns.com ,
.Aq https://gira.de
.It
.Aq https://www.duiadns.net
.It
.Aq https://ddnss.de
.It
.Aq http://dynv6.com
.It
.Aq http://ipv4.dynv6.com
.It
.Aq https://www.cloudxns.net
.It
.Aq https://www.dnspod.cn
.It
.Aq https://connect.yandex.ru
.It
.Aq https://www.cloudflare.com
.It
.Aq https://www.goip.de
.El
.Pp
DDNS providers not listed here, e.g.
.Aq https://www.namecheap.com ,
can often be configured using the custom DDNS provider plugin.  See
.Xr inadyn.conf 5
for examples.
.Sh OPTIONS
Earlier versions of
.Nm
supported more command line options, from v2.0
.Nm
has been greatly simplified.  See
.Xr inadyn.conf 5
for details of the
.Pa /etc/inadyn.conf
configuration file format.
.Pp
.Bl -tag -width Ds
.It Fl 1, -once
Run only once and quit, updates only if too old or unknown.  Use
.Fl -force
to for an update before exiting.
.It Fl -force
Force one update.  Only works with
.Fl 1, -once
flag, ignored for all other use-cases.
.It Fl -cache-dir Ar PATH
Set directory for persistent cache files, defaults to
.Pa /var/cache/inadyn
.Pp
The cache files are used to keep track of which addresses have been
successfully sent to their respective DDNS provider and when.  The
latter 'when' is important to prevent
.Nm
from banning you for excessive updates.
.Pp
When restarting
.Nm
or rebooting your server, or embedded device,
.Nm
reads the cache files to seed its internal data structures with the last
sent IP address and when the update was performed.  It is therefore very
important to both have a cache file and for it to have the correct time
stamp.  The absence of a cache file will currently cause a forced
update.
.Pp
On an embedded device with no RTC, or no battery backed RTC, it is
strongly recommended to pair this setting with the
.Fl -startup-delay Ar SEC
command line option.
.It Fl c, -cmd Ar /path/to/cmd Op optional args
Full path to command, or script, to run to check for IP address change.
This is the same as the configuration file option
.Ar checkip-command
but will apply to
.Sy all
providers.  This command line option is only provided for convenience, it
is recommended to instead use the configuration file.  For more details,
see the
.Xr inadyn.conf 5
man page.  You will need to quote the complete command if any arguments,
or pipe, is given.
.It Fl -continue-on-error
Ignore errors from DDNS provider and try again later.  This command line
option tells
.Nm
to not exit on errors from a DDNS provider and instead try again later.
Please do not use this, it usually indicates that we are sending a
malformed request, e.g. wrong username, password or DNS alias for the
given account.  Continuing could possibly lock you out of your account!
.It Fl e, -exec=/path/to/cmd Op optional args
Full path to command, or script, to run.
The following environment variables are set: INADYN_IP, INADYN_HOSTNAME.
The first environment variable contains the new IP address, the second
the host name alias.  The
.Nm cmd
is called for each listed host name.  If
.Nm
is started with the
.Fl i Ar IFNAME
command line option, the INADYN_IFACE environment variable is also set.
You will need to quote the complete command if any arguments, or pipe,
is given.
.It Fl -exec-mode Ar MODE
Use
.Ar MODE
to set the exec script run mode: compat, event:
- compat: run exec handler on successful DDNS update only, default
- event: run exec handler on any update status
The following environment variables are set:
INADYN_EVENT, INADYN_ERROR, INADYN_ERROR_MESSAGE.
INADYN_EVENT contains the event, one of: nochg, update, error.
The event nochg indicates that no update had to be sent, the event
update indicates that an update was sent successully, the event error
indicates that the update was sent and an error occurred.
INADYN_ERROR contains the error code,
INADYN_ERROR_MESSAGE contains the error message for the error code.
.It Fl f, -config Ar FILE
Use
.Ar FILE
for configuration. By default
.Pa /etc/inadyn.conf ,
is used.  See
.Xr inadyn.conf 5
for examples.
.It Fl h, -help
Show summary of command line options and exit
.It Fl i, -iface Ar IFNAME
Check IP of IFNAME instead of querying an external server.  With this
command line option the external IP check is disabled and
.Nm
will report the IP address of
.Ar IFNAME
to all DDNS providers listed in the configuration file.  This can be
useful to register LAN IP addresses, or, when connected directly to a
public IP address, to speed up the IP check if the DDNS provider's
check-ip servers are slow to respond.
.Pp
This option can also be given as a configuration option in
.Xr inadyn.conf 5 ,
both serve a purpose, use whichever one works for you.
.It Fl I, Fl -ident Ar NAME
Specify program identity (name) to be used for PID file and syslog
messages.  Useful with multiple instances of
.Nm ,
or to simply replace the
.Nm
name with something more generic, e.g. "DDNS", without renaming the
binary.  Note, this option only changes the base name of the PID file,
not the location, which is system specific.  Usually
.Pa /var/run/inadyn.pid
or
.Pa /run/inadyn.pid .
.It Fl l, -loglevel Ar LEVEL
Set log level: none, err, info,
.Ar notice ,
debug.  The default is
.Ar notice ,
but you might want to set this to
.Fl l Ar warning .
.It Fl l, -list-providers
List available DDNS providers.
.It Fl n, -foreground
Run in foreground, default is to daemonize and continue in the
background.  This option is usually required when running under process
supervisors like systemd and Finit, but is also useful when running from
the terminal, when debugging a config or at initial set up.  Remember to
also give the
.Fl s
option if you still want to redirect log messages to the syslog.
.It Fl p, -drop-privs Ar USER Ns Op : Ns Ar GROUP
Drop root privileges after initial setup to the given user and group.
.It Fl -no-pidfile
When running as a daemon, even when running in the foreground with
.Fl n ,
.Nm
creates a PID file so users can easily find the PID of the process to
send signals to.  See
.Sx SIGNALS
for more information on this.  This option tells
.Nm
to
.Sy not
create a PID file.  Some users prefer this when running under systemd.
.It Fl P, -pidfile Ar FILE
Set PID file name and location, defaults to
.Pa /run/inadyn.pid ,
derived from
.Fl -ident Ar NAME ,
which is strongly recommended to change over this option.  However, some
users want to keep application runtime files in separate directories,
usually in combination with
.Fl -drop-privs ,
for such cases this is the option to use.
.It Fl s, -syslog
Use
.Xr syslog 3
for log messages, warnings and error conditions.  This is the default
when running in the background.  When running in the foreground, see
.Fl n ,
log messages are printed to stdout.
.It Fl S, -show-provider Ar NAME
Show information about DDNS provider
.Ar NAME ,
substring search supported.
.It Fl t, -startup-delay Ar SEC
Initial startup delay.  Default is 0 seconds.  Any signal can be used to
abort the startup delay early, but SIGUSR2 is the recommended to use.
See
.Sx SIGNALS
below for full details of how
.Nm
responds to signals.
.Pp
Intended to allow time for embedded devices without a battery backed
real time clock to set their clock via NTP at bootup.  This is so that
the time since the last update can be calculated correctly from the
.Nm
cache file and the
.Cm forced-update Ar SEC
setting honored across reboots, avoiding unnecessary IP address updates.
.It Fl v, -version
Show program version and exit.
.El
.Sh OUTPUT
.Nm
prints a message when the IP is updated.  If no update is needed then by
default it prints a single
.Dq .\&
character, unless
.Fl -loglevel
is set to
.Ar none .
Therefore, unless
.Fl -loglevel
is set to
.Ar none ,
the log will contain lots of dots.  When the connection goes down
.Nm
may print some harmless error messages which should be followed by
.Dq OK
messages after the Internet connection is restored.
.Sh SIGNALS
.Nm
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It HUP
Reload the
.Nm .conf 
file, standard UNIX behavior
.It TERM
Tell
.Nm
to exit gracefully
.It INT
Same as TERM
.It USR1
Force update now, even if the IP address has not changed
.It USR2
Check IP address change now. Useful when a new DHCP/PPPoE lease or new
gateway is received.  Please note that
.Nm
does not track such events by itself.  You need an external monitor for
that
.El
.Pp
For convenience in sending signals,
.Nm
writes its process ID to
.Pa /var/run/inadyn.pid ,
unless the
.Fl -ident Ar NAME
option is used.
.Sh FILES
.Bl -tag -width /var/cache/inadyn/freedns.afraid.org.cache -compact
.It Pa /etc/inadyn.conf
.It Pa /run/inadyn.pid
.It Pa /var/cache/inadyn/dyndns.org.cache
.It Pa /var/cache/inadyn/freedns.afraid.org.cache
.It Pa ... one .cache file per DDNS provider
.El
.Sh SEE ALSO
.Xr inadyn.conf 5
.Pp
The
.Nm
home page is at GitHub:
.Aq https://github.com/troglobit/inadyn
.Sh AUTHORS
.Nm
was originally written by Narcis Ilisei
.Aq mailto:inarcis2002@hotpop.com
and Steve Horbachuk.  Current patch monkey is Joachim Wiberg
.Aq mailto:troglobit@gmail.com
with a lot of help from Andrey Tikhomirov and Mike Fleetwood.
.Pp
This manual page was originally written for the
.Em Debian GNU/Linux
project by Shaul Karl
.Aq mailto:shaul@debian.org ,
and is currently maintained by Joachim Wiberg.