-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathsnaps.conf.5.html
More file actions
228 lines (226 loc) · 10.7 KB
/
Copy pathsnaps.conf.5.html
File metadata and controls
228 lines (226 loc) · 10.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<style>
table.head, table.foot { width: 100%; }
td.head-rtitle, td.foot-os { text-align: right; }
td.head-vol { text-align: center; }
div.Pp { margin: 1ex 0ex; }
</style>
<link rel="stylesheet" href="man.css" type="text/css" media="all"/>
<title>SNAPS.CONF(5)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">SNAPS.CONF(5)</td>
<td class="head-vol">File Formats Manual</td>
<td class="head-rtitle">SNAPS.CONF(5)</td>
</tr>
</table>
<div class="manual-text">
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
<b class="Nm" title="Nm">snaps.conf</b> —
<span class="Nd" title="Nd">snaps configuration file</span>
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
The config file format for <a class="Xr" title="Xr">snaps(8)</a> is optimized
for human read- and writability.
<div class="Pp"></div>
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 '\'.
<div class="Pp"></div>
The statement <var class="Ar" title="Ar">backup</var> 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.
<div class="Pp"></div>
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.
<div class="Pp"></div>
<a class="Xr" title="Xr">ssh(1)</a> is used to login to each remote and so the
locally configured user must have it's own public/private key pair. See the
<var class="Ar" title="Ar">user</var> option for more information.
<div class="Pp"></div>
The following options are supported:
<dl class="Bl-tag">
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">backup <var class="Ar" title="Ar">location</var>
[<span class="Op">{...}</span>]</dt>
<dd class="It-tag">Configure a <var class="Ar" title="Ar">location</var> to
take snapshots of. <var class="Ar" title="Ar">location</var> has the form
of [user@]host[:path]. Where [<span class="Op">user@</span>] and
[<span class="Op">:path</span>] override the global settings
<var class="Ar" title="Ar">ruser</var> and
<var class="Ar" title="Ar">rpath</var>, 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 <var class="Ar" title="Ar">backup</var> statement itself.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">createroot <var class="Ar" title="Ar">bool</var></dt>
<dd class="It-tag">Whether or not snaps should create the root directory if it
does not exist. <var class="Ar" title="Ar">bool</var> must be either
“yes” or “no”. Defaults to yes.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">exec <var class="Ar" title="Ar">path</var></dt>
<dd class="It-tag">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.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">group <var class="Ar" title="Ar">groupname</var> |
<var class="Ar" title="Ar">gid</var></dt>
<dd class="It-tag">The unprivileged group to run as. Defaults to the primary
group of the configured <var class="Ar" title="Ar">user</var>.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><var class="Ar" title="Ar">interval</var>
<var class="Ar" title="Ar">number</var></dt>
<dd class="It-tag">An interval with a number of snapshots to retain.
<var class="Ar" title="Ar">interval</var> must be one of
“hourly”, “daily”, “weekly” or
“monthly”. <var class="Ar" title="Ar">number</var> must be
an integer. The <var class="Ar" title="Ar">interval</var> setting is
mandatory and may appear multiple times to configure different
intervals.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">root <var class="Ar" title="Ar">path</var>
[<span class="Op"><var class="Ar" title="Ar">group</var></span>]</dt>
<dd class="It-tag">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
<var class="Ar" title="Ar">root</var> setting is mandatory.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">rpath <var class="Ar" title="Ar">path</var></dt>
<dd class="It-tag">The remote path to use for a location. Can also be set
implicitly via the <var class="Ar" title="Ar">location</var> value to
backup.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">rsyncargs <var class="Ar" title="Ar">arg ...</var></dt>
<dd class="It-tag">One or more extra arguments to pass to hrsync.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">rsyncexit <var class="Ar" title="Ar">code ...</var></dt>
<dd class="It-tag">One or more extra exit status codes from
<a class="Xr" title="Xr">hrsync(1)</a> to treat as success besides the
normal exit status of 0.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">ruser <var class="Ar" title="Ar">username</var></dt>
<dd class="It-tag">The remote user to login to a location. Can also be set
implicitly via the <var class="Ar" title="Ar">location</var> value to
backup. Defaults to "root".</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag">user <var class="Ar" title="Ar">username</var> |
<var class="Ar" title="Ar">uid</var></dt>
<dd class="It-tag">A local unprivileged username or id used to execute
<a class="Xr" title="Xr">hrsync(1)</a>. This user must have access to a
public/private key pair. The public key should be installed on every
remote location. See <a class="Xr" title="Xr">useradd(8)</a>,
AUTHORIZED_KEYS FILE FORMAT in <a class="Xr" title="Xr">sshd(8)</a>, and
<a class="Xr" title="Xr">ssh-keygen(1)</a> for further information. This
setting is mandatory and must not be set to the superuser.</dd>
</dl>
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
A minimal config file that contains only the mandatory settings and one backup
location could look like the following:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
root /srv/snaps
user _snaps
daily 6
backup john@foo.example.com:/srv
</pre>
</div>
<div class="Pp"></div>
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
<var class="Ar" title="Ar">user</var> for requirements on the local user.
<div class="Pp"></div>
The following example shows how to overrule global settings on a per location
basis:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
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
}
</pre>
</div>
<div class="Pp"></div>
Here two locations are being backed up. With some global settings and some
settings specific to a backup location.
<div class="Pp"></div>
For foo.example.com the following rules apply:
<ul class="Bl-dash">
<li class="It-dash">login as user john</li>
<li class="It-dash">take a snapshot of /srv</li>
<li class="It-dash">retain 3 monthly snapshots</li>
<li class="It-dash">retain 0 daily snapshots</li>
<li class="It-dash">include the snapshot even when hrsync exits with code 23
or 24</li>
</ul>
<div class="Pp"></div>
For bar.example.com the following rules apply:
<ul class="Bl-dash">
<li class="It-dash">login as user root (the default
<var class="Ar" title="Ar">ruser</var>)</li>
<li class="It-dash">take a snapshot of /home</li>
<li class="It-dash">retain 6 daily snapshots (globally set and not
overruled)</li>
<li class="It-dash">retain 12 hourly snapshots.</li>
<li class="It-dash">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.</li>
</ul>
<div class="Pp"></div>
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.
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<a class="Xr" title="Xr">hrsync(1)</a>, <a class="Xr" title="Xr">ssh(1)</a>,
<a class="Xr" title="Xr">ssh-keygen(1)</a>,
<a class="Xr" title="Xr">snaps(8)</a>, <a class="Xr" title="Xr">sshd(8)</a>,
<a class="Xr" title="Xr">useradd(8)</a>
<h1 class="Sh" title="Sh" id="AUTHORS"><a class="selflink" href="#AUTHORS">AUTHORS</a></h1>
<span class="An" title="An">Tim Kuijsten</span>
<<a class="Mt" title="Mt" href="mailto:tim@netsend.nl">tim@netsend.nl</a>></div>
<table class="foot">
<tr>
<td class="foot-date">May 22, 2018</td>
<td class="foot-os">OpenBSD 6.3</td>
</tr>
</table>
</body>
</html>