view release on metacpan or  search on metacpan

bin/yabsm  view on Meta::CPAN

Provides a simple query language for locating snapshots and backups.

=back

=head1 Usage

Yabsm provides 3 commands: L<config|/"Configuration Querying">,
L<find|/"Finding Snapshots">, and L<daemon|/"The Yabsm Daemon">

    usage: yabsm [--help] [--version] [<COMMAND> <ARGS>]

    commands:

    <config|c> [--help] [check ?file] [ssh-check <SSH_BACKUP>] [ssh-key]
               [yabsm-user-home] [yabsm_dir] [subvols] [snaps] [ssh_backups]
               [local_backups] [backups]

    <find|f>   [--help] [<SNAP|SSH_BACKUP|LOCAL_BACKUP> <QUERY>]

    <daemon|d> [--help] [start] [stop] [restart] [status] [init]

=head1 Dependencies

=over 4

=item *

L<Perl|https://perldoc.perl.org/>

=item *

L<OpenSSH|https://www.openssh.com/>

=item *

L<Sudo|https://www.sudo.ws/>

=item *

L<btrfs-progs|https://github.com/kdave/btrfs-progs>

=back

=head1 Installation

In the near future Yabsm should be available in all major Linux distribution
repositories.

Until then Yabsm can be installed with L<cpanminus|https://metacpan.org/pod/App::cpanminus>.

    # apt install cpanminus
    # cpanm App::Yabsm

=head1 The Yabsm Daemon

    usage: yabsm <daemon|d> [--help] [start] [stop] [restart] [status] [init]

Snapshots and backups are performed by the Yabsm daemon. The Yabsm daemon must be
started as root so it can initialize its runtime environment, which includes
creating a locked user named I<yabsm> (and a group named I<yabsm>) that the
daemon will run as. You can initialize the daemon's runtime environment without
actually starting the daemon by running C<yabsm daemon init>.

When the daemon starts, it reads the C</etc/yabsm.conf> file that specifies its
L<configuration|/"Configuration"> to determine when to schedule the snapshots and
backups and how to perform them. If the Yabsm daemon is already running and you
make a configuration change, you must run C<yabsm daemon restart> to apply the
changes.

=head3 Initialize Daemon Runtime Environment

You can use the command C<yabsm daemon init> to initialize the daemon's runtime
environment without actually starting the daemon. Running this command creates
the I<yabsm> user and group, gives the I<yabsm> user sudo access to btrfs-progs,
creates I<yabsms> SSH keys, and creates the directories needed for performing all
the I<snaps>, I<ssh_backups>, and I<local_backups> defined in C</etc/yabsm.conf>.

=head3 Daemon Logging

The Yabsm daemon logs all of its errors to C</var/log/yabsm>. If, for example,
you have an I<ssh_backup> that is not being performed, the first thing you should
do is check the logs.

=head1 Configuration

The Yabsm daemon is configured via the C</etc/yabsm.conf> file.

You can run the command C<yabsm config check> that will check your config and
output useful error messages if there are any problems.

=head3 Configuration Grammar

First things first: you must specify a C<yabsm_dir> that Yabsm will use for
storing snapshots and as a cache for holding data needed for performing snapshots
and backups. Most commonly this directory is set to C</.snapshots/yabsm>. Yabsm
will take this directory literally so you almost certainly want the path to end
in C</yabsm>. If this directory does not exist, the Yabsm daemon will create it
automatically when it starts.

There are 4 different configuration objects: I<subvols>, I<snaps>,
I<ssh_backups>, and I<local_backups>. The general form of each configuration
object is:

    type name {
        key=val
        ...
    }

All configuration objects share a namespace, so you must make sure they all have
unique names. You can define as many configuration objects as you want.

=head4 Subvols

A subvol is the simplest configuration object and is used to give a name to a
L<btrfs subvolume|https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes>
on your system. A subvol definition accepts one field named C<mountpoint> which
takes a value that is a path to a subvolume.

    subvol home_subvol {
        mountpoint=/home