view release on metacpan or  search on metacpan

lib/App/BackupPlan.pm  view on Meta::CPAN

=head2 CONFIGURATION

Here is a made-up sample configuration file for a backup plan that backups two directories with 
different frequencies: a B<pictures> and a B<videos> directories.

	<backup>
		<plan name="one">
			<default>
				<maxFiles>3</maxFiles>
				<frequency>1m</frequency>
				<targetDir><![CDATA[/backup]]></targetDir>
			</default>
			<task name="pics">
				<prefix>pics</prefix>
				<sourceDir><![CDATA[/data/pictures]]></sourceDir>
				<frequency>20d</frequency>	
			</task>	
			<task name="video">
				<prefix>vid</prefix>
				<maxFiles>2</maxFiles>
				<sourceDir><![CDATA[/data/Videos]]></sourceDir>
				<frequency>40d</frequency>	
			</task>			
		</plan>
	</backup>

=over

=item * The tag B<E<lt>backupE<gt>> is the container tag for the backup plan.

=item * The tag B<E<lt>planE<gt>> contains the actual plan, as a collection of B<tasks>,
with an identifying name that is not currently used. A B<plan> is made of a E<lt>defaultE<gt> B<task>
and many separate B<tasks>. The E<lt>defaultE<gt> B<task> contains the definition of the properties
of a general B<task>, when an override is not given. Strictly speaking the current version of 
B<App::BackupPlan> requires only a default task and some distinct task elements inside a well formed
XML document. The structure of this sample configuration is mostly given for clarity.

=item * The tag B<E<lt>defaultE<gt>> contains the specification of the common properties for all
other tasks. This element is used to specify the default behaviour and its properies are inherited
by all other B<tasks>. It allows the same XML sub-elements as E<lt>taskE<gt> does, so for its
specification please see below.

=item * The tag B<E<lt>taskE<gt>> defines a backup policy for a given directory structure. It
has an attribute I<name> mostly for debugging purpouse. Its properties, partially inherited
from the E<lt>defaultE<gt> B<task> and partially overridden, are:

=over

=item * B<E<lt>prefixE<gt>> The prefix used to identify the beginning of the compressed backup file.

=item * B<E<lt>maxFilesE<gt>> The maximum number of backup files preserved in the E<lt>targetDirE<gt>
directory. As soon as this number is breached, the oldest backup file is removed (rolling behaviour).

=item * B<E<lt>frequencyE<gt>> The period of time between two consecutive backups of the current
E<lt>sourceDirE<gt>. This is specified by a string of type C<n[dmy]>, where n is a number and the 
second letter is either C<d> for days, C<m> for months or C<y> for years. Internally, C<1m = 30d>
and C<1y = 360d>, wihtout considering months of 28 or 31 days. 

=item * B<E<lt>sourceDirE<gt>> The path for the directory structure to be backed up. It requires
a B<CDATA> xml tag to escape the slashes in the full path.

=item * B<E<lt>targetDirE<gt>> The path for the destination directory where backup files are stored. It requires
a B<CDATA> xml tag to escape the slashes in the full path. Typically this will be a single location on the disk,
and hence the same for all tasks and specified in the E<lt>defaultE<gt> section.

=back

=back

=head2 USAGE

This perl module was written with an automated backup functionality in mind. So, even if it can
be run manually and on demand, it is best suited to be integrated in a regular batch (overnight maybe)
or even better as a B<cron> task. To facilitate this task there is a script client in the bin
directory of this distribution, B<backup.pl>, which can be easily scheduled as cron task and, that can be run
as follow: C<backup.pl -c /pathto/plan.xml -l /pathto/log4perl.conf> when using I<system> B<tar>, or as
C<backup.pl -c /pathto/plan.xml -l /pathto/log4perl.conf -t perl> for I<perl> B<tar>.  

=head2 DEPENDENCIES

The list of module dependencies is as follows:

=over

=item * B<XML::DOM> for parsing the configuration file,

=item * B<Log::Log4perl> for logging,

=item * B<File::Find> to collect the entire content of a directory substructure when using Archive::Tar

=item * B<Archive::Tar> to perform perl based tar, instead of using system tar

=item * B<tar> executable used in Linux environment for storage and compression

=back

On a B<Linux> system it is recommended to use the I<system> B<tar> executable, which is the default
behaviour for this module.
There is also the option of using L<Archive::Tar> perl module isntead of the I<system> B<tar>. This is
recommended for Windows based systems, or if the B<tar> executable is not available. This behaviour is designated
as I<perl> B<tar> and is selected by setting C<$App::BackupPlan::TAR='perl'>.

On some distributions B<XML::DOM> does not build straight away, using cpan install or download & make.
This is caused by a dependency of this module, B<XML::Parser>, requiring a C library to be present
in your system: B<expat-devel>. On some distributions, Debian for example, this package is unavailble.
This problem can be overcome by first installing (apt-get) B<libxml-parser-perl>.

	
=head2 EXPORT

None by default.



=head1 SEE ALSO

L<XML::DOM>, L<Log::Log4perl>, L<File::Find>, L<Archive::Tar>

=head1 AUTHOR

Gualtiero Chiaia

=head1 COPYRIGHT AND LICENSE