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
|
.\" Man page generated from reStructuredText.
.
.TH "EXPIRE_BACKUPS" "1" "October 28, 2016" "2.21" "S3QL"
.SH NAME
expire_backups \- Intelligently expire old backups
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
expire_backups [options] <age> [<age> ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBexpire_backups\fP command intelligently remove old backups that are no
longer needed.
.sp
To define what backups you want to keep for how long, you define a
number of \fIage ranges\fP\&. \fBexpire_backups\fP ensures that you
will have at least one backup in each age range at all times. It will
keep exactly as many backups as are required for that and delete any
backups that become redundant.
.sp
Age ranges are specified by giving a list of range boundaries in terms
of backup cycles. Every time you create a new backup, the existing
backups age by one cycle.
.sp
Example: when \fBexpire_backups\fP is called with the age range
definition \fB1 3 7 14 31\fP, it will guarantee that you always have the
following backups available:
.INDENT 0.0
.IP 1. 3
A backup that is 0 to 1 cycles old (i.e, the most recent backup)
.IP 2. 3
A backup that is 1 to 3 cycles old
.IP 3. 3
A backup that is 3 to 7 cycles old
.IP 4. 3
A backup that is 7 to 14 cycles old
.IP 5. 3
A backup that is 14 to 31 cycles old
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you do backups in fixed intervals, then one cycle will be
equivalent to the backup interval. The advantage of specifying the
age ranges in terms of backup cycles rather than days or weeks is
that it allows you to gracefully handle irregular backup intervals.
Imagine that for some reason you do not turn on your computer for
one month. Now all your backups are at least a month old, and if you
had specified the above backup strategy in terms of absolute ages,
they would all be deleted! Specifying age ranges in terms of backup
cycles avoids these sort of problems.
.UNINDENT
.UNINDENT
.sp
\fBexpire_backups\fP usage is simple. It requires backups to be
stored in directories of the form \fByear\-month\-day_hour:minute:seconds\fP
(\fBYYYY\-MM\-DD_HH:mm:ss\fP) and works on all backups in the current
directory. So for the above backup strategy, the correct invocation
would be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
expire_backups.py 1 3 7 14 31
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When storing your backups on an S3QL file system, you probably want to
specify the \fB\-\-use\-s3qlrm\fP option as well. This tells
\fBexpire_backups\fP to use the \fIs3qlrm\fP command to
delete directories.
.sp
\fBexpire_backups\fP uses a "state file" to keep track which
backups are how many cycles old (since this cannot be inferred from
the dates contained in the directory names). The standard name for
this state file is \fB\&.expire_backups.dat\fP\&. If this file gets
damaged or deleted, \fBexpire_backups\fP no longer knows the ages
of the backups and refuses to work. In this case you can use the
\fB\-\-reconstruct\-state\fP option to try to reconstruct the state
from the backup dates. However, the accuracy of this reconstruction
depends strongly on how rigorous you have been with making backups (it
is only completely correct if the time between subsequent backups has
always been exactly the same), so it\(aqs generally a good idea not to
tamper with the state file.
.SH OPTIONS
.sp
The \fBexpire_backups\fP command accepts the following options:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-\-quiet
be really quiet
.TP
.BI \-\-debug\-modules \ <modules>
Activate debugging output from specified modules (use
commas to separate multiple modules). Debug messages
will be written to the target specified by the
\fB\-\-log\fP option.
.TP
.B \-\-debug
Activate debugging output from all S3QL modules. Debug
messages will be written to the target specified by
the \fB\-\-log\fP option.
.TP
.B \-\-version
just print program version and exit
.TP
.BI \-\-state \ <file>
File to save state information in (default:
".expire_backups.dat")
.TP
.B \-n
Dry run. Just show which backups would be deleted.
.TP
.B \-\-reconstruct\-state
Try to reconstruct a missing state file from backup
dates.
.TP
.B \-\-use\-s3qlrm
Use \fBs3qlrm\fP command to delete backups.
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXIT CODES
.sp
\fBexpire_backups\fP may terminate with the following exit codes:
.INDENT 0.0
.TP
.B 0
Everything went well.
.TP
.B 1
An unexpected error occured. This may indicate a bug in the
program.
.TP
.B 2
Invalid command line argument.
.UNINDENT
.SH SEE ALSO
.sp
\fBexpire_backups\fP is shipped as part of S3QL, \fI\%https://bitbucket.org/nikratio/s3ql/\fP\&.
.SH COPYRIGHT
© 2008 Nikolaus Rath <Nikolaus@rath.org>
.\" Generated by docutils manpage writer.
.
|
