diff options
author | Nikolaus Rath <Nikolaus@rath.org> | 2016-03-09 10:08:21 -0800 |
---|---|---|
committer | Nikolaus Rath <Nikolaus@rath.org> | 2016-03-09 10:08:21 -0800 |
commit | 5b62499deb280253671a3c468644335be9e55f04 (patch) | |
tree | 96a12cd0c8833ca23e5993614b7d0405f2422a9f /rst/man/expire_backups.rst |
Import s3ql_1.0.1.orig.tar.bz2
Diffstat (limited to 'rst/man/expire_backups.rst')
-rw-r--r-- | rst/man/expire_backups.rst | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/rst/man/expire_backups.rst b/rst/man/expire_backups.rst new file mode 100644 index 0000000..6b2f538 --- /dev/null +++ b/rst/man/expire_backups.rst @@ -0,0 +1,106 @@ +.. -*- mode: rst -*- + + +======================================= + The :program:`expire_backups` command +======================================= + +Synopsis +======== + +:: + + expire_backups [options] <age> [<age> ...] + + +Description +=========== + +The |command| command intelligently remove old backups that are no +longer needed. + +.. begin_main_content + +To define what backups you want to keep for how long, you define a +number of *age ranges*. :program:`expire_backups` 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. + +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. + +Example: when :program:`expire_backups` is called with the age range +definition ``1 3 7 14 31``, it will guarantee that you always have the +following backups available: + +#. A backup that is 0 to 1 cycles old (i.e, the most recent backup) +#. A backup that is 1 to 3 cycles old +#. A backup that is 3 to 7 cycles old +#. A backup that is 7 to 14 cycles old +#. A backup that is 14 to 31 cycles old + +.. NOTE:: + + 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. + +:program:`expire_backups` usage is simple. It requires backups to have +names of the forms ``year-month-day_hour:minute:seconds`` +(``YYYY-MM-DD_HH:mm:ss``) and works on all backups in the current +directory. So for the above backup strategy, the correct invocation +would be:: + + expire_backups.py 1 3 7 14 31 + +When storing your backups on an S3QL file system, you probably want to +specify the ``--use-s3qlrm`` option as well. This tells +:program:`expire_backups` to use the :ref:`s3qlrm <s3qlrm>` command to +delete directories. + +:program:`expire_backups` 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 :file:`.expire_backups.dat`. If this file gets +damaged or deleted, :program:`expire_backups` no longer knows the ages +of the backups and refuses to work. In this case you can use the +:cmdopt:`--reconstruct-state` 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's generally a good idea not to +tamper with the state file. + +.. end_main_content + + +Options +======= + +The |command| command accepts the following options: + +.. pipeinclude:: ../../contrib/expire_backups.py --help + :start-after: show this help message and exit + +Exit Status +=========== + +|command| returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +See Also +======== + +|command| is shipped as part of S3QL, http://code.google.com/p/s3ql/. + +.. |command| replace:: :command:`expire_backups` + |