=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

Multiple interfaces can be configured using the standard systemd semantics
of unit overrides, which might look like this:

 /etc/systemd/system/petrified-iface1.service
 --------------------------------------------
 .include /usr/lib/systemd/system/petrified.service
 [Service]
 ExecStart=
 ExecStart=/usr/bin/petrified -c /etc/petrified-iface1.conf

The first C<ExecStart=> is intentional, needed to negate the existing value
first before defining a new value (systemd design for ExecStart override).

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:

 /etc/systemd/system/petrified-iface1.timer
 --------------------------------------------
 .include /usr/lib/systemd/system/petrified.timer
 [Timer]
 Unit=petrified-iface1.service
 OnCalendar=0/8:00:00

This timer will now operate the new custom unit when it's enabled.

=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>

=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) 2014 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>