EXPIRE_BACKUPS(1)

💾 expire_backups(1) — the S3QL girlie's guide to letting old backups go 💅

okay bestie, sit down, we're doing backup hygiene today ✨ this page is literally expire_backups(1) from the S3QL fam, and it's about to become your new hyperfixation 🫶

---

✨ NAME ✨

expire_backups — intelligently expire old backups 👑 (yes, intelligently, we're not just yeeting things into the void)

---

🌸 SYNOPSIS 🌸

expire_backups [options] <age> [<age> ...]

---

🦋 DESCRIPTION 🦋

okay so the whole vibe of the expire_backups command is that it intelligently removes old backups that are no longer needed 💖

to define which backups you wanna keep and for how long, you define a bunch of age ranges. expire_backups makes sure you will have at least one backup in each age range at all times ⭐. it keeps exactly as many backups as are required for that, and it deletes any backups that become redundant. slay, no hoarding.

age ranges get 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. the way that works is honestly iconic.

example: when 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:

1. A backup that is 0 to 1 cycles old (i.e, the most recent backup)
2. A backup that is 1 to 3 cycles old
3. A backup that is 3 to 7 cycles old
4. A backup that is 7 to 14 cycles old
5. 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.

not me crying over how thoughtful that design is 😭 it's giving main character energy fr fr.

expire_backups usage is simple, periodt. it requires backups to be stored in directories of the form year-month-day_hour:minute:seconds (YYYY-MM-DD_HH:mm:ss) and it 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 expire_backups to use the s3qlrm command to delete directories.

expire_backups uses a "state file" to keep track of 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 .expire_backups.dat 🎀. if this file gets damaged or deleted, expire_backups no longer knows the ages of the backups and refuses to work 💀. in this case you can use the --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 🙈. hands off, bestie.

---

🎀 OPTIONS 🎀

the expire_backups command accepts the following options:

• --quiet — be really quiet 🤫
• --log <target> — destination for log messages. specify none for standard output or syslog for the system logging daemon. anything else will be interpreted as a file name. log files will be rotated when they reach 1 MiB, and at most 5 old log files will be kept. Default: None
• --debug-modules <modules> — activate debugging output from specified modules (use commas to separate multiple modules, 'all' for everything). debug messages will be written to the target specified by the --log option 🐛
• --debug — activate debugging output from all S3QL modules. debug messages will be written to the target specified by the --log option 🐛✨
• --version — just print program version and exit
• --state <file> — file to save state information in (default: ".expire_backups.dat")
• -n — dry run. just show which backups would be deleted 👀 (no cap, nothing actually gets deleted)
• -p <N>, --proportion-delete <N> — maximum proportion of backups to delete (between 0 and 1, default: 0.5)
• --reconstruct-state — try to reconstruct a missing state file from backup dates 🧚
• --use-s3qlrm — use s3qlrm command to delete backups

---

🌈 EXIT CODES 🌈

expire_backups may terminate with the following exit codes:

• 0 — everything went well. we ate. 💖
• 1 — an unexpected error occurred. this may indicate a bug in the program 🐛💀
• 2 — invalid command line argument or configuration file key 🚫

---

💜 SEE ALSO 💜

expire_backups is shipped as part of S3QL, https://github.com/s3ql/s3ql/. go check it out, iykyk 🦋

---

👑 COPYRIGHT 👑

© 2008 Nikolaus Rath <Nikolaus@rath.org>

---

and that's the whole page bestie, version 5.2.3, dated Nov 02, 2024 — S3QL stays iconic, and so do you 🫶✨ bye now, go expire some backups responsibly 💅