=pod
=head1 What is Yabsm?
Yabsm (yet another btrfs snapshot manager) is a btrfs snapshot and backup
management system that provides the following features:
=over 4
=item *
Takes read only snapshots and performs both remote and local incremental backups.
=item *
Separates snapshots and backups into 5minute, hourly, daily, weekly, and monthly
timeframe categories.
=item *
Provides a simple query language for locating snapshots and backups.
=back
=head1 Dependencies
=over 4
=item *
L
=item *
L
=item *
L
=item *
L
=back
=head1 Snapshots vs Backups
Before we go on, let's clear up the difference between a snapshot and a backup.
A L
is a read-only subvolume created with the C command.
A L is a
snapshot that has been transferred to another btrfs filesystem via a combination
of C and C.
=head1 Installation
In the near future Yabsm should be available in all major Linux distribution
repositories.
Until then Yabsm can be installed with L.
# apt install cpanminus
# cpanm App::Yabsm
=head1 Usage
usage: yabsm [--help] [--version] []
commands:
[--help] [check ?file] [ssh-check ] [ssh-key]
[yabsm-user-home] [yabsm_dir] [subvols] [snaps] [ssh_backups]
[local_backups] [backups]
[--help] []
[--help] [start] [stop] [restart] [status] [init]
Yabsm provides 3 commands: L,
L, and L
=head1 The Yabsm Daemon
usage: yabsm [--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 (and a group named I) that the
daemon will run as. You can initialize the daemon's runtime environment without
actually starting the daemon by running C.
When the daemon starts, it reads the C file that specifies its
L 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 to apply the
changes.
=head3 Initialize Daemon Runtime Environment
You can use the command C to initialize the daemon's runtime
environment without actually starting the daemon. Running this command creates
the I user and group, gives the I user sudo access to btrfs-progs,
creates I SSH keys, and creates the directories needed for performing all
the I, I, and I defined in C.
=head3 Daemon Logging
The Yabsm daemon logs all of its errors to C. If, for example,
you have an I 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 file.
You can run the command C 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 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. Yabsm
will take this directory literally so you almost certainly want the path to end
in C. If this directory does not exist, the Yabsm daemon will create it
automatically when it starts.
There are 4 different configuration objects: I, I,
I, and I. 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
on your system. A subvol definition accepts one field named C which
takes a value that is a path to a subvolume.
subvol home_subvol {
mountpoint=/home
}
=head4 Timeframes
We need to understand timeframes before we can understand I,
I, and I. There are 5 timeframes: 5minute, hourly,
daily, weekly, and monthly.
I, I, and I are performed in one or more
timeframes. For example, a I may be configured to take backups in the
I and I categories, which means that we want to backup every hour
and once a week.
The following table describes in plain English what each timeframe means:
5minute -> Every 5 minutes.
hourly -> At the beginning of every hour.
daily -> Every day at one or more times of the day.
weekly -> Once a week on a specific weekday at a specific time.
monthly -> Once a month on a specific day at a specific time.
To specify the timeframes you want, you set the value of C to a comma
separated list of timeframe values. For example, this is how you specify that you
want every timeframe:
timeframes=5minute,hourly,daily,weekly,monthly
Each timeframe you specify adds new required settings for the configuration
object. Here is a table that shows the timeframe settings:
5minute -> 5minute_keep
hourly -> hourly_keep
daily -> daily_keep, daily_times
weekly -> weekly_keep, weekly_time, weekly_day
monthly -> monthly_keep, monthly_time, monthly_day
Any C<*_keep> setting defines how many snapshots/backups you want to keep at one
time for the configuration object. A common configuration is to keep 48 hourly
snapshots so you can go back 2 days in one-hour increments.
The C setting for daily snapshots takes a comma separated list of
I times. Yabsm will perform the snapshot/backup every day at all the given
times.
The weekly timeframe requires a C setting that takes a day of week
string such as I, I, or I and a I
setting that takes a I time. The weekly snapshot/backup will be performed
on the given day of the week at the given time.
The monthly timeframe requires a C setting that takes an integer
between 1-31 and a C setting that takes a I time. The
monthly snapshot/backup will be performed on the given day of the month at the
given time.
=head4 Snaps
A I represents a snapshot configuration for some I. Here is an
example of a I that snapshots I twice a day.
snap home_subvol_snap {
subvol=home_subvol
timeframes=daily
daily_keep=62 # two months
daily_times=13:40,23:59
}
=head4 SSH Backups
A I represents a backup configuration that sends snapshots over a
network via SSH. See this example of a I that backs up I
to C every night at midnight:
ssh_backup home_subvol_larry_server {
subvol=home_subvol
ssh_dest=larry@192.168.1.73
dir=/backups/yabsm/laptop_home
timeframes=daily
daily_keep=31
daily_times=23:59
}
The difficult part of configuring a I is making sure the SSH server
is properly configured. You can test that a I is able to be performed
by running CSSH_BACKUPE>. For a I to
be able to be performed the following conditions must be satisfied:
=over 4
=item *
The host's I user can sign into the SSH destination (I) using
key based authentication. To achieve this you must add the I users SSH key
(available via C<# yabsm ssh print-key>) to the server user's
C<$HOME/.ssh/authorized_keys> file.
=item *
The remote backup directory (I) is an existing directory residing on a btrfs
filesystem that the remote user has read and write permissions to.
=item *
The SSH user has root access to btrfs-progs via sudo. To do this you can add a
file containing a string like C to
a file in C.
=back
=head4 Local Backups
A I represents a backup configuration that sends snapshots to a
partition mounted on the host OS. This is useful for sending snapshots to an
external hard drive plugged into your computer.
Here is an example I that backs up C every hour, and
once a week.
local_backup home_subvol_easystore {
subvol=home_subvol
dir=/mnt/easystore/backups/yabsm/home_subvol
timeframes=hourly,weekly
hourly_keep=48
weekly_keep=56
weekly_day=sunday
weekly_time=23:59
}
The backup directory (C) must be an existing directory residing on a btrfs
filesystem that the I user has read permission on.
=head1 Configuration Querying
Yabsm comes with a C command that allows you to check and query your
configuration.
usage: yabsm [--help] [check ?file] [ssh-check ]
[ssh-key] [yabsm-user-home] [yabsm_dir] [subvols]
[snaps] [ssh_backups] [local_backups] [backups]
The C subcommand checks that C is a valid yabsm configuration
file and if not prints useful error messages. If the C argument is omitted
it defaults to C.
The CSSH_BACKUPE> subcommand checks that CSSH_BACKUPE> can be
performed and if not prints useful error messages. See the section
L for an explanation on the configuration required
for performing an I.
The C subcommand prints the I user's public SSH key.
All of the other subcommands query for information derived from your
C:
subvols -> The names of all subvols.
snaps -> The names of all snaps.
ssh_backups -> The names of all ssh_backups.
local_backups -> The names of all local_backups.
backups -> The names of all ssh_backups and local_backups.
yabsm_dir -> The directory used as the yabsm_dir.
yabsm_user_home -> The 'yabsm' users home directory.
=head1 Finding Snapshots
Now that we know how to configure Yabsm to take snapshots, we are going to want
to locate those snapshots. Yabsm comes with a command C that allows you to
locate snapshots and backups using a simple query language. Here is the usage
string for the C command.
usage: yabsm [--help] []
Here are a few examples:
$ yabsm find home_snap back-2-mins
$ yabsm f root_ssh_backup 'after b-2-m'
$ yabsm f home_local_backup 10:45
The first argument is the name of any I, I, or I.
Because these configuration entities share the same namespace there is no risk of
ambiguity.
The second argument is a snapshot location query. There are 7 types of queries:
all -> Every snapshot sorted newest to oldest
newest -> The most recent snapshot/backup.
oldest -> The oldest snapshot/backup.
after TIME -> All the snapshot/backups that are newer than TIME.
before TIME -> All the snapshot/backups that are older than TIME.
between TIME1 TIME2 -> All the snapshot/backups that were taken between TIME1 and TIME2.
TIME -> The snapshot/backup that was taken closest to TIME.
=head2 Time Abbreviations
In the list above the C