App-BorgRestore
view release on metacpan or search on metacpan
- Add --json option
- Add --detail option
- Log cache update status message per archive to INFO
- Add --quiet option
- Remove sqlite cache size warning
3.0.0 2018-03-23T14:57:52Z
- No longer automatically enable --adhoc when cache is empty
2.3.0 2018-02-06T15:58:36Z
- Add --list option to search for paths occuring in backups
- Warn if sqlite's memory cache is is filled during cache updates
- Improve documentation of @backup_prefixes setting
2.2.0 2017-11-25T23:16:04Z
- Add borg 1.1 support
- Mention required positive return code of config in documentation
- Enable adhoc mode automatically when cache is empty
2.1.1 2017-10-05T07:58:12Z
- Fix incorrect/missing dependencies
- Use autodie everywhere to catch errors early
- Add basic documentation to internal packages
{
"abstract" : "Restore paths from borg backups",
"author" : [
"Florian Pritz <bluewind@xinu.at>"
],
"dynamic_config" : 0,
"generated_by" : "Minilla/v3.1.22",
"license" : [
"gpl_3"
],
"meta-spec" : {
"url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
---
abstract: 'Restore paths from borg backups'
author:
- 'Florian Pritz <bluewind@xinu.at>'
build_requires:
Log::Any::Adapter::TAP: '0'
Software::License::GPL_3: '0'
Test::Differences: '0'
Test::Exception: '0'
Test::MockObject: '0'
Test::More: '0.98'
Test::Pod: '0'
# NAME
borg-restore.pl - Restore paths from borg backups
# SYNOPSIS
borg-restore.pl \[options\] <path>
Options:
--help, -h short help message
--debug show debug messages
--quiet show only warnings and errors
--detail Output additional detail for some operations
(currently only --list)
--json Output JSON instead of human readable text
(currently only --list)
--update-cache, -u update cache files
--list [pattern] List paths contained in the backups, optionally
matching an SQLite LIKE pattern
--destination, -d <path> Restore backup to directory <path>
--time, -t <timespec> Automatically find newest backup that is at least
<time spec> old
--adhoc Do not use the cache, instead provide an
unfiltered list of archive to choose from
--version display the version of the program
Time spec:
Select the newest backup that is at least <time spec> old.
Format: <number><unit>
Units: s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year)
# EXAMPLE USAGE
> borg-restore.pl bin/backup.sh
0: Sat. 2016-04-16 17:47:48 +0200 backup-20160430-232909
1: Mon. 2016-08-15 16:11:29 +0200 backup-20160830-225145
2: Mon. 2017-02-20 16:01:04 +0100 backup-20170226-145909
3: Sat. 2017-03-25 14:45:29 +0100 backup-20170325-232957
Enter ID to restore (Enter to skip): 3
INFO Restoring home/flo/bin/backup.sh to /home/flo/bin from archive backup-20170325-232957
# DESCRIPTION
borg-restore.pl helps to restore files from borg backups.
It takes one path, looks for its backups, shows a list of distinct versions and
allows to select one to be restored. Versions are based on the modification
time of the file.
It is also possible to specify a time for automatic selection of the backup
that has to be restored. If a time is specified, the script will automatically
select the newest backup that is at least as old as the time value that is
passed and restore it without further user interaction.
**borg-restore.pl --update-cache** has to be executed regularly, ideally after
creating or removing backups.
[App::BorgRestore](https://metacpan.org/pod/App%3A%3ABorgRestore) provides the base features used to implement this script.
It can be used to build your own restoration script.
# OPTIONS
- **--help**, **-h**
Show help message.
Output additional detail information with some operations. Refer to the
specific options for more information. Currently only works with **--list**
- **--json**
Output JSON instead of human readable text with some operations. Refer to the
specific options for more information. Currently only works with **--list**
- **--update-cache**, **-u**
Update the lookup database. You should run this after creating or removing a backup.
- **--list** **\[pattern\]**
List paths contained in the backups, optionally matching an SQLite LIKE
pattern. If no % occurs in the pattern, the patterns is automatically wrapped
between two % so it may match anywhere in the path.
If **--detail** is used, also outputs which archives contain a version of the
file. If the same version is part of multiple archives, only one archive is
shown.
If **--json** is used, the output is JSON. Can also be combined with **--detail**.
- **--destination=**_path_, **-d **_path_
Restore the backup to 'path' instead of its original location. The destination
either has to be a directory or missing in which case it will be created. The
backup will then be restored into the directory with its original file or
directory name.
- **--time=**_timespec_, **-t **_timespec_
Automatically find the newest backup that is at least as old as _timespec_
specifies. _timespec_ is a string of the form "<_number_><_unit_>" with _unit_ being one of the following:
s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year). Example: 5.5d
- **--adhoc**
Disable usage of the database. In this mode, the list of archives is fetched
directly from borg at run time. Use this when the cache has not been created
yet and you want to restore a file without having to manually call borg
extract. Using this option will show all archives that borg knows about, even
if they do not contain the file that shall be restored.
lib/App/BorgRestore.pm view on Meta::CPAN
use List::Util qw(any all);
use Log::Any qw($log);
use Pod::Usage;
use POSIX ();
use Time::HiRes;
=encoding utf-8
=head1 NAME
App::BorgRestore - Restore paths from borg backups
=head1 SYNOPSIS
use App::BorgRestore;
my $app = App::BorgRestore->new();
# Update the cache (call after creating/removing backups)
$app->update_cache();
# Restore a path from a backup that is at least 5 days old. Optionally
# restore it to a different directory than the original.
# Look at the implementation of this method if you want to know how the
# other parts of this module work together.
$app->restore_simple($path, "5days", $optional_destination_directory);
=head1 DESCRIPTION
App::BorgRestore is a restoration helper for borg.
It maintains a cache of borg backup contents (path and latest modification
time) and allows to quickly look up backups that contain a path. It further
supports restoring a path from an archive. The archive to be used can also be
automatically determined based on the age of the path.
The cache has to be updated regularly, ideally after creating or removing
backups.
L<borg-restore.pl> is a wrapper around this class that allows for simple CLI
usage.
This package uses L<Log::Any> for logging.
=head1 METHODS
=head2 Constructors
lib/App/BorgRestore.pm view on Meta::CPAN
=back
=cut
method new($class: $deps = {}) {
$deps->{settings} //= App::BorgRestore::Settings->new();
my $config = $deps->{settings}->get_config();
$deps->{borg} //= App::BorgRestore::Borg->new(@{$config->{borg}}{qw(repo backup_prefix)});
$deps->{db} //= App::BorgRestore::DB->new($config->{cache}->{database_path}, $config->{cache}->{sqlite_memory_cache_size});
return $class->new_no_defaults($deps, $config);
}
=head3 new_no_defaults
Same as C<new> except that this does not initialize unset dependencies with
their default values. This is probably only useful for tests.
lib/App/BorgRestore.pm view on Meta::CPAN
if (!defined($abs_path)) {
$log->errorf("Failed to resolve path to absolute path: %s: %s", $canon_path, $!);
$log->error("Make sure that all parts of the path, except the last one, exist.");
die "Path resolving failed\n";
}
return $abs_path;
}
=head3 map_path_to_backup_path
my $path_in_backup = $app->map_path_to_backup_path($abs_path);
Maps an absolute path from the system to the path that needs to be looked up in
/ extracted from the backup using C<@backup_prefixes> from
L<App::BorgRestore::Settings>.
Returns the mapped path (string).
=cut
method map_path_to_backup_path($abs_path) {
my $backup_path = $abs_path;
for my $backup_prefix (@{$self->{config}->{borg}->{path_prefixes}}) {
if ($backup_path =~ m/$backup_prefix->{regex}/) {
$backup_path =~ s/$backup_prefix->{regex}/$backup_prefix->{replacement}/;
last;
}
}
return $backup_path;
}
=head3 find_archives
my $archives = $app->find_archives($path);
Returns an arrayref of archives (hash with "modification_time" and "archive")
from the database that contain a path. Duplicates are filtered based on the
modification time of the path in the
archives.
lib/App/BorgRestore.pm view on Meta::CPAN
if (exists($factors{$unit})) {
return $value * $factors{$unit};
}
}
return;
}
=head3 restore
$app->restore($backup_path, $archive, $destination);
Restore a backup path (returned by C<map_path_to_backup_path>) from an archive
(returned by C<find_archives> or C<get_all_archives>) to a destination
directory.
If the destination path (C<$destination/$last_elem_of_backup_path>) exists, it
is removed before beginning extraction from the backup.
Warning: This method temporarily modifies the current working directory of the
process during method execution since this is required by C<`borg extract`>.
=cut
method restore($path, $archive, $destination) {
$destination = untaint($destination, qr(.*));
$path = untaint($path, qr(.*));
lib/App/BorgRestore.pm view on Meta::CPAN
C<$destination> is not specified, it is set to the parent directory of C<$path>
so that C<$path> is restored to its original place.
Refer to L</"select_archive_timespec"> for an explanation of the C<$timespec>
variable.
=cut
method restore_simple($path, $timespec, $destination) {
my $abs_path = $self->resolve_relative_path($path);
my $backup_path = $self->map_path_to_backup_path($abs_path);
$destination //= dirname($abs_path);
my $archives = $self->find_archives($backup_path);
my $selected_archive = $self->select_archive_timespec($archives, $timespec);
$self->restore($backup_path, $selected_archive, $destination);
}
=head3 search_path
my $paths = $app->search_path($pattern)
Returns a arrayref of paths that match the pattern. The pattern is matched as
an sqlite LIKE pattern. If no % occurs in the pattern, the patterns is
automatically wrapped between two % so it may match anywhere in the path.
lib/App/BorgRestore/Borg.pm view on Meta::CPAN
=head1 NAME
App::BorgRestore::Borg - Borg abstraction
=head1 DESCRIPTION
App::BorgRestore::Borg abstracts borg commands used by L<App::BorgRestore>.
=cut
method new($class: $borg_repo, $backup_prefix) {
my $self = {};
bless $self, $class;
$self->{borg_repo} = $borg_repo;
$self->{backup_prefix} = $backup_prefix;
$self->{borg_version} = $self->borg_version();
return $self;
}
=head3 borg_version
Return the version of borg.
lib/App/BorgRestore/Borg.pm view on Meta::CPAN
run [qw(borg --version)], ">", \my $output or die $log->error("Failed to determined borg version")."\n";
if ($output =~ m/^.* ([0-9.a-z]+)$/) {
return $1;
}
die $log->error("Unable to extract borg version from borg --version output")."\n";
}
method borg_list() {
my @archives;
my $backup_prefix = $self->{backup_prefix};
if (Version::Compare::version_compare($self->{borg_version}, "1.2") >= 0) {
$log->debug("Getting archive list via json");
run [qw(borg list --glob-archives), "$backup_prefix*", qw(--json), $self->{borg_repo}], '>', \my $output or die $log->error("borg list returned $?")."\n";
my $json = decode_json($output);
for my $archive (@{$json->{archives}}) {
push @archives, $archive->{archive};
}
} elsif (Version::Compare::version_compare($self->{borg_version}, "1.1") >= 0) {
$log->debug("Getting archive list via json");
run [qw(borg list --prefix), $backup_prefix, qw(--json), $self->{borg_repo}], '>', \my $output or die $log->error("borg list returned $?")."\n";
my $json = decode_json($output);
for my $archive (@{$json->{archives}}) {
push @archives, $archive->{archive};
}
} else {
$log->debug("Getting archive list");
run [qw(borg list --prefix), $backup_prefix, $self->{borg_repo}], '>', \my $output or die $log->error("borg list returned $?")."\n";
for (split/^/, $output) {
if (m/^([^\s]+)\s/) {
push @archives, $1;
}
}
}
$log->warning("No archives detected in borg output. Either you have no backups or this is a bug") if @archives == 0;
return \@archives;
}
method borg_list_time() {
my @archives;
if (Version::Compare::version_compare($self->{borg_version}, "1.1") >= 0) {
$log->debug("Getting archive list via json");
run [qw(borg list --json), $self->{borg_repo}], '>', \my $output or die $log->error("borg list returned $?")."\n";
lib/App/BorgRestore/Borg.pm view on Meta::CPAN
if ($time) {
push @archives, {
"archive" => $1,
"modification_time" => $time,
};
}
}
}
}
$log->warning("No archives detected in borg output. Either you have no backups or this is a bug") if @archives == 0;
return \@archives;
}
method restore($components_to_strip, $archive_name, $path) {
$log->debugf("Restoring '%s' from archive %s, stripping %d components of the path", $path, $archive_name, $components_to_strip);
$archive_name = untaint($archive_name, qr(.*));
system(qw(borg extract -v --strip-components), $components_to_strip, $self->{borg_repo}."::".$archive_name, $path);
}
lib/App/BorgRestore/Settings.pm view on Meta::CPAN
Also note that it is important that the last statement of the file is positive
because it is used to check that running the config went well. You can simply
use "1;" on the last line as shown in the example config.
=over
=item C<$borg_repo>
This specifies the URL to the borg repo as used in other borg commands. If you
use the $BORG_REPO environment variable set this to an empty string. Default:
"backup:borg-".hostname;
=item C<$backup_prefix>
This specifies that only archives with the prefix should be considered. For
example, if you back up multiple things (file system and database) into
differntly named archives (fs-* and db-*), this can be used to only consider
file system archives to keep the database size small. In the example you'd set
the setting to "fs-". An empty string considers all archives. Default: ""
=item C<$cache_path_base>
This defaults to "C<$XDG_CACHE_HOME>/borg-restore.pl". It contains the lookup database.
=item C<@backup_prefixes>
This is an array of prefixes that need to be added or removed when looking up a
file in the backup archives. If you use filesystem snapshots and the snapshot
for /home is located at /mnt/snapshots/home, you have to add the following:
# In the backup archives, /home has the path /mnt/snapshots/home
{regex => "^/home/", replacement => "mnt/snapshots/home/"},
The regex must always include the leading slash and it is suggested to include
a tailing slash as well to prevent clashes with directories that start with the
same string. The first regex that matches for a given file is used. This
setting only affects lookups, it does not affect the creation of the database
with --update-database.
If you create a backup of /home/user only, you will need to use the following:
# In the backup archives, /home/user/foo has the path foo
{regex => "^/home/user", replacement => ""},
=item C<$sqlite_cache_size>
Default: 102400
The size of the in-memory cache of sqlite in kibibytes. Increasing this may
reduce disk IO and improve performance on certain systems when updating the
cache.
lib/App/BorgRestore/Settings.pm view on Meta::CPAN
multiple time, thus writing directly to the database is slower, but preparing
the data in memory may require a substaintial amount of memory.
New in version 3.2.0. Deprecated in v3.2.0 for future removal possibly in v4.0.0.
=back
=head2 Example Configuration
$borg_repo = "/path/to/repo";
$backup_prefix = "";
$cache_path_base = "/mnt/somewhere/borg-restore.pl-cache";
@backup_prefixes = (
{regex => "^/home/", replacement => "mnt/snapshots/home/"},
# /boot is not snapshotted
{regex => "^/boot/", replacement => "boot"},
{regex => "^/", replacement => "mnt/snapshots/root/"},
);
$sqlite_cache_size = 2097152;
$prepare_data_in_memory = 0;
1; #ensure positive return value
lib/App/BorgRestore/Settings.pm view on Meta::CPAN
Licensed under the GNU General Public License version 3 or later.
See LICENSE for the full license text.
=cut
method new($class: $deps = {}) {
return $class->new_no_defaults($deps);
}
our $borg_repo = "backup:borg-".hostname;
our $cache_path_base;
our @backup_prefixes = (
{regex => "^/", replacement => ""},
);
our $sqlite_cache_size = 102400;
our $prepare_data_in_memory = 0;
our $backup_prefix = "";
method new_no_defaults($class: $deps = {}) {
my $self = {};
bless $self, $class;
$self->{deps} = $deps;
if (defined $ENV{XDG_CACHE_HOME} or defined $ENV{HOME}) {
$cache_path_base = sprintf("%s/borg-restore.pl", $ENV{XDG_CACHE_HOME} // $ENV{HOME} ."/.cache");
}
lib/App/BorgRestore/Settings.pm view on Meta::CPAN
$cache_path_base = untaint($cache_path_base, qr/.*/);
return $self;
}
method get_config() {
return {
borg => {
repo => $borg_repo,
backup_prefix => $backup_prefix,
path_prefixes => [@backup_prefixes],
},
cache => {
base_path => $cache_path_base,
database_path => "$cache_path_base/v3/archives.db",
prepare_data_in_memory => $prepare_data_in_memory,
sqlite_memory_cache_size => $sqlite_cache_size,
}
};
}
script/borg-restore.pl view on Meta::CPAN
#!/usr/bin/perl -T
use strictures 2;
=head1 NAME
borg-restore.pl - Restore paths from borg backups
=head1 SYNOPSIS
borg-restore.pl [options] <path>
Options:
--help, -h short help message
--debug show debug messages
--quiet show only warnings and errors
--detail Output additional detail for some operations
(currently only --list)
--json Output JSON instead of human readable text
(currently only --list)
--update-cache, -u update cache files
--list [pattern] List paths contained in the backups, optionally
matching an SQLite LIKE pattern
--destination, -d <path> Restore backup to directory <path>
--time, -t <timespec> Automatically find newest backup that is at least
<time spec> old
--adhoc Do not use the cache, instead provide an
unfiltered list of archive to choose from
--version display the version of the program
Time spec:
Select the newest backup that is at least <time spec> old.
Format: <number><unit>
Units: s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year)
=head1 EXAMPLE USAGE
> borg-restore.pl bin/backup.sh
0: Sat. 2016-04-16 17:47:48 +0200 backup-20160430-232909
1: Mon. 2016-08-15 16:11:29 +0200 backup-20160830-225145
2: Mon. 2017-02-20 16:01:04 +0100 backup-20170226-145909
3: Sat. 2017-03-25 14:45:29 +0100 backup-20170325-232957
Enter ID to restore (Enter to skip): 3
INFO Restoring home/flo/bin/backup.sh to /home/flo/bin from archive backup-20170325-232957
=head1 DESCRIPTION
borg-restore.pl helps to restore files from borg backups.
It takes one path, looks for its backups, shows a list of distinct versions and
allows to select one to be restored. Versions are based on the modification
time of the file.
It is also possible to specify a time for automatic selection of the backup
that has to be restored. If a time is specified, the script will automatically
select the newest backup that is at least as old as the time value that is
passed and restore it without further user interaction.
B<borg-restore.pl --update-cache> has to be executed regularly, ideally after
creating or removing backups.
L<App::BorgRestore> provides the base features used to implement this script.
It can be used to build your own restoration script.
=cut
=head1 OPTIONS
=over 4
script/borg-restore.pl view on Meta::CPAN
Output additional detail information with some operations. Refer to the
specific options for more information. Currently only works with B<--list>
=item B<--json>
Output JSON instead of human readable text with some operations. Refer to the
specific options for more information. Currently only works with B<--list>
=item B<--update-cache>, B<-u>
Update the lookup database. You should run this after creating or removing a backup.
=item B<--list> B<[pattern]>
List paths contained in the backups, optionally matching an SQLite LIKE
pattern. If no % occurs in the pattern, the patterns is automatically wrapped
between two % so it may match anywhere in the path.
If B<--detail> is used, also outputs which archives contain a version of the
file. If the same version is part of multiple archives, only one archive is
shown.
If B<--json> is used, the output is JSON. Can also be combined with B<--detail>.
=item B<--destination=>I<path>, B<-d >I<path>
Restore the backup to 'path' instead of its original location. The destination
either has to be a directory or missing in which case it will be created. The
backup will then be restored into the directory with its original file or
directory name.
=item B<--time=>I<timespec>, B<-t >I<timespec>
Automatically find the newest backup that is at least as old as I<timespec>
specifies. I<timespec> is a string of the form "<I<number>><I<unit>>" with I<unit> being one of the following:
s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year). Example: 5.5d
=item B<--adhoc>
Disable usage of the database. In this mode, the list of archives is fetched
directly from borg at run time. Use this when the cache has not been created
yet and you want to restore a file without having to manually call borg
extract. Using this option will show all archives that borg knows about, even
if they do not contain the file that shall be restored.
script/borg-restore.pl view on Meta::CPAN
if ($opts{json}) {
print encode_json($json_data);
}
return 0;
}
if (!$app->cache_contains_data() && !$opts{adhoc}) {
$log->error("Cache is empty. Either the cache path is incorrect or you did not run --update yet.");
$log->error("If you did not create a cache yet, you may want to rerun with --adhoc to simply list all backups.");
return 1;
}
my @paths = @ARGV;
my $path;
my $timespec;
my $destination;
my $archives;
script/borg-restore.pl view on Meta::CPAN
$timespec = $opts{time};
}
if (@ARGV > 1) {
die "Too many arguments";
}
my $abs_path = $app->resolve_relative_path($path);
$destination = dirname($abs_path) unless defined($destination);
my $backup_path = $app->map_path_to_backup_path($abs_path);
$log->debug("Asked to restore $backup_path to $destination");
if ($opts{adhoc}) {
$archives = $app->get_all_archives();
} else {
$archives = $app->find_archives($backup_path);
}
my $selected_archive;
if (defined($timespec)) {
$selected_archive = $app->select_archive_timespec($archives, $timespec);
} else {
$selected_archive = user_select_archive($archives);
}
if (!defined($selected_archive)) {
die "No archive selected or selection invalid";
}
$app->restore($backup_path, $selected_archive, $destination);
return 0;
}
exit main();
( run in 0.290 second using v1.01-cache-2.11-cpan-cba739cd03b )