Chapter 9. Cleanup backups

You can remove old backups to limit the space your backups consume on your local hard drive. It's important to note, that only local backups will be cleaned up. So whatever kind of Sync you are using. Cleanup won't touch your remote files.

If you want to remove your synced backups as well, and you are not using the Rsync sync with its delete option. Have a look at the remote cleanup section.

Table 9.1. Supported types of cleanup:

Capacity Define the size your backups should occupy. If your backups start to exceed this value PHPBU will start to delete backups, starting with the oldest ones.
Outdated Remove backups older than a configured time-value. For example "2W" to delete all backups older than two weeks.
QuantityKeep only a configured amount of backups.
Stepwise Keep different amount of backups for different periods of time. For example keep all backups you made for the last 3 days, keep one for each week for the last 4 weeks, keep one for each month for the last 6 months and one for each year for at least 3 years.

Cleanup by capacity

Remove oldest backups if all created backups exceed the configured limit.

Table 9.2. Capacity-Options

sizestringyes-Space your backups are allowed to occupy. e.g. 500M for 500 Megabytes or 1G for one Gigabyte.
deleteTargetbooleannofalse If you don't want to keep any backups locally, just specify a size of "0B", set this to "true" and even the current backup will be deleted.

Example 9.1: capacity XML example

<!-- cleanup capacity: keep 250 Megabytes of backups -->
<cleanup type="capacity">
  <option name="size" value="250M"/>
  <option name="deleteTarget" value="false"/>

Example 9.2: capacity JSON example

  "type": "capacity",
  "options": {
    "size": "250M",
    "deleteTarget": "false"

Cleanup by date

Remove backups that are older than a configured value.

Table 9.3. Outdated-Options

olderstringyes-Time to keep backups. e.g. 1m for one month or 20d for twenty days.

Example 9.3: outdated XML example

<!-- cleanup outdated: keep backups for 2 weeks -->
<cleanup type="outdated">
  <option name="older" value="2W"/>

Example 9.4: outdated JSON example

  "type": "Outdated",
  "options": {
    "older": "2W"

Cleanup by quantity

Keep only a configured amount of backups.

Table 9.4. Quantity-Options

amountstringyes-The amount of backups to keep.

Example 9.5: quantity XML example

<!-- cleanup quantity: keep the last 20 backups -->
<cleanup type="quantity">
  <option name="amount" value="20"/>

Example 9.6: quantity JSON example

  "type": "quantity",
  "options": {
    "amount": 20

Cleanup stepwise

Keep more backups in the recent past and keep less backups for the distant past. The following table illustrates how this works.

        | for x days  | for x days        | for x weeks           | for x month keep   |
        | keep all    | keep one per day  | keep one per week     | keep one per month |
backups | ............| . . . . . . . . . | .       .       .     | .                . | 

So if you start to backup now your amount of backups will grow for the configured years to keep at least one backup. But by then the amount of your backups will be constantly the same.

Table 9.5. Stepwise-Options

daysToKeepAllintegeryes0Days to keep all backups you made.
daysToKeepDailyintegeryes0Days to keep at least one backup you made a day.
weeksToKeepWeeklyintegeryes0Amount of weeks to keep at least one backup for each week.
monthToKeepMonthlyintegeryes0Amount of month to keep at least one backup for each month.
yearsToKeepYearlyintegeryes0Amount of years to keep at least one backup for each year.

Example 9.7: stepwise XML example

<!-- cleanup stepwise -->
<cleanup type="stepwise">
  <option name="daysToKeepAll" value="2" />
  <option name="daysToKeepDaily" value="5" />
  <option name="weeksToKeepWeekly" value="3" />
  <option name="monthToKeepMonthly" value="4" />
  <option name="yearsToKeepYearly" value="10" />

Example 9.8: stepwise JSON example

  "type": "stepwise",
  "options": {
    "daysToKeepAll": 2,
    "daysToKeepDaily": 5,
    "weeksToKeepWeekly": 3,
    "monthToKeepMonthly": 4,
    "yearsToKeepYearly": 10

Remote cleanup

Some sync implementations support to cleanup remote files as well. To check if the sync of your choice supports remote cleanup have a look at the sync list.

Remote cleanups are configured within your Sync configuration similar to local cleanups. The only difference is that all options get prefixed by cleanup.. To better understand this have a look at the following examples.

Example 9.9: Remote cleanup XML example

<!-- cleanup stepwise -->
<sync type="dropbox">
  <!-- some sync relevant options -->
  <option name="token" value="mysecrettoken" />
  <option name="path" value="/backups" />
  <!-- remote cleanup options -->
  <option name="cleanup.type" value="quantity" />
  <option name="cleanup.amount" value="10" />

Example 9.10: Remote cleanup JSON example

  "type": "dropbox",
  "options": {
    "token": "mysecrettoken",
    "path": "/backups",
    "cleanup.type": "quantity",
    "cleanup.amount": 10

Please open a ticket on GitHub to suggest improvements to this page. Thanks!