.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "App::BorgRestore 3pm" .TH App::BorgRestore 3pm 2023-09-03 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME App::BorgRestore \- Restore paths from borg backups .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& 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); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" App::BorgRestore is a restoration helper for borg. .PP 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. .PP The cache has to be updated regularly, ideally after creating or removing backups. .PP borg\-restore.pl is a wrapper around this class that allows for simple CLI usage. .PP This package uses Log::Any for logging. .SH METHODS .IX Header "METHODS" .SS Constructors .IX Subsection "Constructors" \fInew\fR .IX Subsection "new" .PP .Vb 1 \& App::BorgRestore\->new(\e%deps); .Ve .PP Returns a new instance. The following dependencies can be injected: .IP \(bu 4 borg (optional) .Sp This object is used to interact with the borg repository of the system. Defaults to App::BorgRestore::Borg .IP \(bu 4 db (optional) .Sp This object is used to store the extracted data (the cache). Defaults to App::BorgRestore::DB .PP \fInew_no_defaults\fR .IX Subsection "new_no_defaults" .PP Same as \f(CW\*(C`new\*(C'\fR except that this does not initialize unset dependencies with their default values. This is probably only useful for tests. .SS "Public Methods" .IX Subsection "Public Methods" \fIresolve_relative_path\fR .IX Subsection "resolve_relative_path" .PP .Vb 1 \& my $abs_path = $app\->resolve_relative_path($path); .Ve .PP Returns an absolute path for a given path. .PP \fImap_path_to_backup_path\fR .IX Subsection "map_path_to_backup_path" .PP .Vb 1 \& my $path_in_backup = $app\->map_path_to_backup_path($abs_path); .Ve .PP Maps an absolute path from the system to the path that needs to be looked up in / extracted from the backup using \f(CW@backup_prefixes\fR from App::BorgRestore::Settings. .PP Returns the mapped path (string). .PP \fIfind_archives\fR .IX Subsection "find_archives" .PP .Vb 1 \& my $archives = $app\->find_archives($path); .Ve .PP 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. .PP \fIget_all_archives\fR .IX Subsection "get_all_archives" .PP .Vb 1 \& my $archives = $app\->get_all_archives(); .Ve .PP Returns an arrayref of archives (hash with "modification_time" and "archive") from borg directly. This does not require the database to be populated. Instead it just fetches a list of archives from borg at runtime and returns it. .PP The returned data structure is the same as that returned by \f(CW\*(C`find_archives\*(C'\fR. .PP \fIcache_contains_data\fR .IX Subsection "cache_contains_data" .PP .Vb 1 \& if ($app\->cache_contains_data()) { ... } .Ve .PP Returns 1 if the cache contains any archive data, 0 otherwise. .PP \fIselect_archive_timespec\fR .IX Subsection "select_archive_timespec" .PP .Vb 1 \& my $archive = $app\->select_archive_timespec($archives, $timespec); .Ve .PP Returns one archive from \f(CW$archives\fR that is older than the value of \&\f(CW$timespec\fR. .PP \&\fItimespec\fR is a string of the form "<\fInumber\fR><\fIunit\fR>" with \fIunit\fR being one of the following: s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year). Example: "5.5d" .PP \fIrestore\fR .IX Subsection "restore" .PP .Vb 1 \& $app\->restore($backup_path, $archive, $destination); .Ve .PP Restore a backup path (returned by \f(CW\*(C`map_path_to_backup_path\*(C'\fR) from an archive (returned by \f(CW\*(C`find_archives\*(C'\fR or \f(CW\*(C`get_all_archives\*(C'\fR) to a destination directory. .PP If the destination path (\f(CW\*(C`$destination/$last_elem_of_backup_path\*(C'\fR) exists, it is removed before beginning extraction from the backup. .PP Warning: This method temporarily modifies the current working directory of the process during method execution since this is required by \f(CW\`borg extract\`\fR. .PP \fIrestore_simple\fR .IX Subsection "restore_simple" .PP .Vb 1 \& $app\->restore_simple($path, $timespec, $destination); .Ve .PP Restores a \f(CW$path\fR based on a \f(CW$timespec\fR to an optional \f(CW$destination\fR. If \&\f(CW$destination\fR is not specified, it is set to the parent directory of \f(CW$path\fR so that \f(CW$path\fR is restored to its original place. .PP Refer to "select_archive_timespec" for an explanation of the \f(CW$timespec\fR variable. .PP \fIsearch_path\fR .IX Subsection "search_path" .PP .Vb 1 \& my $paths = $app\->search_path($pattern) .Ve .PP 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. .PP \fIget_missing_items\fR .IX Subsection "get_missing_items" .PP .Vb 1 \& my $items = $app\->get_missing_items($have, $want); .Ve .PP Returns an arrayref of items that are part of \f(CW$want\fR, but not of \f(CW$have\fR. .PP \fIupdate_cache\fR .IX Subsection "update_cache" .PP .Vb 1 \& $app\->update_cache(); .Ve .PP Updates the database used by e.g. \f(CW\*(C`find_archives\*(C'\fR. .SH LICENSE .IX Header "LICENSE" Copyright (C) 2016\-2018 Florian Pritz .PP This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. .PP You should have received a copy of the GNU General Public License along with this program. If not, see . .PP See LICENSE for the full license text. .SH AUTHOR .IX Header "AUTHOR" Florian Pritz