SNAPS.CONF(5) File Formats Manual SNAPS.CONF(5)

NAME

snaps.confsnaps configuration file

DESCRIPTION

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.

EXAMPLES

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:
For bar.example.com the following rules apply:
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.

SEE ALSO

hrsync(1), ssh(1), ssh-keygen(1), snaps(8), sshd(8), useradd(8)

AUTHORS

Tim Kuijsten <tim@netsend.nl>
May 22, 2018 OpenBSD 6.3