157 lines
4.7 KiB
Text
157 lines
4.7 KiB
Text
=head1 NAME
|
|
|
|
petrified - bash client to update dynamic DNS at freedns.afraid.org
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
Usage: B<petrified> [ B<-c> I<config> ]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<petrified> is a bash client to update dynamic DNS hosted at
|
|
L<https://freedns.afraid.org>; the software goals are for simplicity,
|
|
flexibility and configurability while using the minimal system tools
|
|
installed with most distributions.
|
|
|
|
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
|
|
L<https://freedns.afraid.org/dynamic/v2/> for more information.
|
|
|
|
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.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-c> I<config>
|
|
|
|
Specify an exact config file to use, ignoring global and per-user configs.
|
|
|
|
=back
|
|
|
|
=head1 CONFIGURATION
|
|
|
|
See F<petrified.conf> for all available options and their usage.
|
|
|
|
Copy the default configuration file to F</etc/petrified.conf> for global
|
|
use, F<~/.petrifiedrc> for user-level use, or another location as desired.
|
|
At a minimum the C<DDNS_KEY> variable must be configured for basic usage;
|
|
all other variables are preconfigured for system level (root) usage.
|
|
|
|
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.
|
|
|
|
To use a custom configuration file, the C<-c config> 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.
|
|
|
|
=head1 SYSTEMD
|
|
|
|
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</etc/petrified.conf>
|
|
configuration, or as any given user which will use the F<~/.petrifiedrc>
|
|
configuration.
|
|
|
|
system: systemctl --now enable petrified.timer
|
|
systemctl list-timers petrified.timer
|
|
|
|
user: systemctl --user --now enable petrified.timer
|
|
systemctl --user list-timers petrified.timer
|
|
|
|
A target of C<petrified.target> is pre-configured if multuple interfaces are
|
|
to be configured; per standard systemd methodology the existing service unit
|
|
is first customized either at the system or user level, then all custom units
|
|
and the timer are started/enabled.
|
|
|
|
For example at the system level if two interfaces are to be used, it might
|
|
look like:
|
|
|
|
/etc/systemd/system/petrified-iface1.service
|
|
--------------------------------------------
|
|
.include /usr/lib/systemd/system/petrified.service
|
|
[Service]
|
|
ExecStart=/usr/bin/petrified -c /etc/petrified-iface1.conf
|
|
|
|
/etc/systemd/system/petrified-iface2.service
|
|
--------------------------------------------
|
|
.include /usr/lib/systemd/system/petrified.service
|
|
[Service]
|
|
ExecStart=/usr/bin/petrified -c /etc/petrified-iface2.conf
|
|
|
|
Then both customized service units are enabled, as well as the timer unit:
|
|
|
|
systemctl --now enable petrified-iface1.service
|
|
systemctl --now enable petrified-iface2.service
|
|
systemctl --now enable petrified.timer
|
|
|
|
The per user configuration looks the same and is usually configured in the
|
|
F<~/.config/systemd/user/> space in the home directory. The provided units
|
|
for the service contain the connection to the target pre-configured.
|
|
|
|
=over 4
|
|
|
|
=item B<See also:>
|
|
|
|
L<http://www.freedesktop.org/software/systemd/man/systemd.unit.html>
|
|
|
|
L<http://www.freedesktop.org/software/systemd/man/systemd.timer.html>
|
|
|
|
L<http://www.freedesktop.org/software/systemd/man/systemd.target.html>
|
|
|
|
=back
|
|
|
|
=head1 DEPENDENCIES
|
|
|
|
Utilities | Package
|
|
-----------------------------------|------------
|
|
logger, kill | util-linux
|
|
printf, touch, date, stat, cat, rm | coreutils
|
|
bash | bash
|
|
ip | iproute2
|
|
curl | curl
|
|
|
|
=head1 FILES
|
|
|
|
=over 4
|
|
|
|
=item F</etc/petrified.conf>
|
|
|
|
Global configuration file
|
|
|
|
=item F<~/.petrifiedrc>
|
|
|
|
Per-user configuration file
|
|
|
|
=item F</var/cache/petrified/lastip.dat>
|
|
|
|
IP cache (if feature enabled - default: yes)
|
|
|
|
=item F</run/petrified.pid>
|
|
|
|
PID file (if feature enabled - default: no)
|
|
|
|
=item F</var/log/petrified.log>
|
|
|
|
LOG file (if feature enabled - default: no)
|
|
|
|
=back
|
|
|
|
=head1 AUTHOR
|
|
|
|
Copyright (c) 2015 Troy Engel
|
|
|
|
GPLv3 - see LICENSE for details
|
|
|
|
=head1 SUPPORT
|
|
|
|
If you like this software, please consider upgrading to a Premium account
|
|
to help support the L<Free DNS|http://freedns.afraid.org> project. All
|
|
questions and issues should be asked/reported via the Github project:
|
|
|
|
L<https://github.com/troyengel/petrified>
|
|
|