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

 Version 1.x = FreeDNS API v1
 Version 2.x = FreeDNS API v2

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.

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