157 lines
4.7 KiB
Groff
157 lines
4.7 KiB
Groff
.\" Automatically generated by Pandoc 2.19.2
|
|
.\"
|
|
.\" Define V font for inline verbatim, using C font in formats
|
|
.\" that render this, and otherwise B font.
|
|
.ie "\f[CB]x\f[]"x" \{\
|
|
. ftr V B
|
|
. ftr VI BI
|
|
. ftr VB B
|
|
. ftr VBI BI
|
|
.\}
|
|
.el \{\
|
|
. ftr V CR
|
|
. ftr VI CI
|
|
. ftr VB CB
|
|
. ftr VBI CBI
|
|
.\}
|
|
.ad l
|
|
.TH "PETRIFIED" "1" "2022-09-18" "petrified 2.0.3" "Petrified Manual"
|
|
.nh
|
|
.SH NAME
|
|
.PP
|
|
petrified - bash client to update dynamic DNS at freedns.afraid.org
|
|
.SH SYNOPSIS
|
|
.PP
|
|
Usage: \f[B]petrified\f[R] [ \f[B]-c\f[R] \f[I]config\f[R] ]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Petrified is a bash client to update dynamic DNS hosted at
|
|
https://freedns.afraid.org; the software goals are for simplicity,
|
|
flexibility and configurability while using the minimal system tools
|
|
installed with most distributions.
|
|
.PP
|
|
If upgrading from API v1 to v2, a manual action is required on the
|
|
FreeDNS website to generate a new API key for each domain name.
|
|
See https://freedns.afraid.org/dynamic/v2/ for more information.
|
|
.PP
|
|
By default, petrified will use the length of the API key to
|
|
automatically choose the APIv1 or APIv2 URL; this can be overridden in
|
|
the configuration file to force a specific version, as the v1 key length
|
|
is variable but the v2 key length is fixed at 24 chars.
|
|
.SH OPTIONS
|
|
.TP
|
|
\f[B]-c\f[R] \f[I]config\f[R]
|
|
Specify an exact config file to use, ignoring global and per-user
|
|
configs.
|
|
.SH CONFIGURATION
|
|
.PP
|
|
See \f[I]petrified.conf\f[R] for all available options and their usage.
|
|
.PP
|
|
Copy the default configuration file to \f[I]/etc/petrified.conf\f[R] for
|
|
global use, \f[I]\[ti]/.petrifiedrc\f[R] for user-level use, or another
|
|
location as desired.
|
|
At a minimum the \[dq]DDNS_KEY\[dq] variable must be configured for
|
|
basic usage; all other variables are preconfigured for system level
|
|
(root) usage.
|
|
.PP
|
|
If implementing at the user level, be sure and set the various file
|
|
options to locations that are writable by the user; the default config
|
|
is fully documented and should make sense.
|
|
.PP
|
|
To use a custom configuration file, the \[dq]-c config\[dq] parameter is
|
|
supported; note that using this option will not read the global or local
|
|
configuration files and only use the variables from this custom file.
|
|
.SH SYSTEMD
|
|
.PP
|
|
The provided systemd unit files are designed to use the native systemd
|
|
timer functionality in place of a cron daemon.
|
|
The timer can be activated as the system user which will use
|
|
specifically the global \f[I]/etc/petrified.conf\f[R] configuration, or
|
|
as any given user which will use the \f[I]\[ti]/.petrifiedrc\f[R]
|
|
configuration.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
system: systemctl --now enable petrified.timer
|
|
systemctl list-timers petrified.timer
|
|
|
|
user: systemctl --user --now enable petrified.timer
|
|
systemctl --user list-timers petrified.timer
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Multiple interfaces can be configured using the standard systemd
|
|
semantics of unit overrides, which might look like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/etc/systemd/system/petrified-iface1.service
|
|
--------------------------------------------
|
|
\&.include /usr/lib/systemd/system/petrified.service
|
|
[Service]
|
|
ExecStart=
|
|
ExecStart=/usr/bin/petrified -c /etc/petrified-iface1.conf
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
The first \[dq]ExecStart\[dq] is intentional, needed to negate the
|
|
existing value first before defining a new value (systemd design for
|
|
ExecStart override).
|
|
.PP
|
|
A corresponding new timer is then created to call this unit as it may be
|
|
desireable to run different interfaces on different time schedules,
|
|
which might then look like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/etc/systemd/system/petrified-iface1.timer
|
|
--------------------------------------------
|
|
\&.include /usr/lib/systemd/system/petrified.timer
|
|
[Timer]
|
|
Unit=petrified-iface1.service
|
|
OnCalendar=0/8:00:00
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
This timer will now operate the new custom unit when it\[aq]s enabled.
|
|
.PP
|
|
\f[B]See also:\f[R]
|
|
.IP \[bu] 2
|
|
http://www.freedesktop.org/software/systemd/man/systemd.unit.html
|
|
.IP \[bu] 2
|
|
http://www.freedesktop.org/software/systemd/man/systemd.timer.html
|
|
.SH DEPENDENCIES
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Utilities | Package
|
|
-----------------------------------|------------
|
|
logger, kill | util-linux
|
|
printf, touch, date, stat, cat, rm | coreutils
|
|
bash | bash
|
|
ip | iproute2
|
|
curl | curl
|
|
\f[R]
|
|
.fi
|
|
.SH FILES
|
|
.TP
|
|
\f[B]/etc/petrified.conf\f[R]
|
|
Global configuration file
|
|
.TP
|
|
\f[B]\[ti]/.petrifiedrc\f[R]
|
|
Per-user configuration file
|
|
.TP
|
|
\f[B]/var/cache/petrified/lastip.dat\f[R]
|
|
IP cache (if feature enabled - default: yes)
|
|
.TP
|
|
\f[B]/run/petrified.pid\f[R]
|
|
PID file (if feature enabled - default: no)
|
|
.TP
|
|
\f[B]/var/log/petrified.log\f[R]
|
|
LOG file (if feature enabled - default: no)
|
|
.SH AUTHOR
|
|
.PP
|
|
Copyright (c) 2014 Troy Engel
|
|
.PP
|
|
Licensed under the GNU General Public License version 3 or later, see
|
|
https://gnu.org/licenses/gpl.html
|