snaps.conf —
snaps configuration file
The config file format for
snaps(8) is optimized
for human read- and writability.
Each config file consists of several statements. Statements are separated from
each other by a semicolon or a newline. A statement consists of a keyword
followed by one or more values. Special characters can be escaped by
surrounding the value with double quotes or by prepending the special
character with '\'. Whenever a '#' is encountered the rest of the line will be
ignored. The following characters are special: tab, space, newline, semicolon
';', hash '#', opening brace '{', double and single quote and backslash '\'.
The statement
backup is the only statement that
can be followed by a block. This is a convenient way to overrule global
settings for one specific location. Blocks are denoted by braces.
Since snaps is not a daemon, it should be run periodically, at least as often as
the shortest configured interval. Note that unless -f is given, a new snapshot
will only be taken if the last one has expired according to the configured
intervals for a location.
ssh(1) is used to login to each remote and so the
locally configured user must have it's own public/private key pair. See the
user option for more information.
The following options are supported:
-
-
- backup location
[{...}]
- Configure a location to
take snapshots of. location has the form
of [user@]host[:path]. Where [user@] and
[:path] override the global settings
ruser and
rpath, respectively. A backup statement
can optionally be followed by a block to override global settings for this
specific location. Within the block any statement can be used except for
the backup statement itself.
-
-
- createroot bool
- Whether or not snaps should create the root directory if it
does not exist. bool must be either
“yes” or “no”. Defaults to yes.
-
-
- exec path
- A path to a script to execute after hrsync is done. The
script receives the exit status of hrsync through the first argument. The
script itself should exit with status 0 if the new snapshot should be
included, or >0 if it should be discarded. The current working
directory of the process is set to that of the new snapshot and it is
running with the same privileges as the hrsync process.
-
-
- group groupname |
gid
- The unprivileged group to run as. Defaults to the primary
group of the configured user.
-
-
- interval
number
- An interval with a number of snapshots to retain.
interval must be one of
“hourly”, “daily”, “weekly” or
“monthly”. number must be
an integer. The interval setting is
mandatory and may appear multiple times to configure different
intervals.
-
-
- root path
[group]
- The root directory that contains the snapshots of one or
more backup locations. Optionally the name of a group can be set to share
all snapshots within this root with a specific group. By default snapshots
are only readable by the superuser. The
root setting is mandatory.
-
-
- rpath path
- The remote path to use for a location. Can also be set
implicitly via the location value to
backup.
-
-
- rsyncargs arg ...
- One or more extra arguments to pass to hrsync.
-
-
- rsyncexit code ...
- One or more extra exit status codes from
hrsync(1) to treat as success besides the
normal exit status of 0.
-
-
- ruser username
- The remote user to login to a location. Can also be set
implicitly via the location value to
backup. Defaults to "root".
-
-
- user username |
uid
- A local unprivileged username or id used to execute
hrsync(1). This user must have access to a
public/private key pair. The public key should be installed on every
remote location. See useradd(8),
AUTHORIZED_KEYS FILE FORMAT in sshd(8), and
ssh-keygen(1) for further information. This
setting is mandatory and must not be set to the superuser.
A minimal config file that contains only the mandatory settings and one backup
location could look like the following:
root /srv/snaps
user _snaps
daily 6
backup john@foo.example.com:/srv
The above configures a backup directory, an unprivileged user to run as and a
daily interval with at most six snapshots retained. Only one location is
backed up, which is foo.example.com:/srv. The local user "_snaps"
logs in on foo.example.com as the user "john". See
user for requirements on the local user.
The following example shows how to overrule global settings on a per location
basis:
root /srv/snaps
createroot no
user _snaps
daily 6
backup john@foo.example.com:/srv {
daily 0
monthly 3
rsyncexit 23 24
}
backup bar.example.com:/home {
hourly 12
exec /usr/local/bin/postsync.sh
}
Here two locations are being backed up. With some global settings and some
settings specific to a backup location.
For foo.example.com the following rules apply:
- login as user john
- take a snapshot of /srv
- retain 3 monthly snapshots
- retain 0 daily snapshots
- include the snapshot even when hrsync exits with code 23
or 24
For bar.example.com the following rules apply:
- login as user root (the default
ruser)
- take a snapshot of /home
- retain 6 daily snapshots (globally set and not
overruled)
- retain 12 hourly snapshots.
- after hrsync finishes, run the custom script
“/usr/local/bin/postsync.sh” which can inspect the new
snapshot and can signal whether or not to include the new snapshot.
Always make sure to run snaps at least as often as the shortest configured
interval. With the last example that is at least twelve times a day because of
the configured twelve hourly snapshots.
hrsync(1),
ssh(1),
ssh-keygen(1),
snaps(8),
sshd(8),
useradd(8)
Tim Kuijsten
<
tim@netsend.nl>