Skip to content

Backups ​

Backups is where per-account backup repositories live, along with everything that runs against them. It is one area with six tabs rather than six entries in the sidebar.

Overview ​

URL: /admin/backups

The Backups overview with the Hosting plans without backups section above the table

The Overview tab lists the backup repositories, one per hosting account, with the latest status of each. Since panel 1.9.3, while backups are not set up yet, the tab opens with the Set up backups guide, and an empty list reads No backups yet: "Backups start after you add a destination and a policy."

The tabs, each with its own address so it can be bookmarked:

TabURLWhat it holds
Overview/admin/backupsRepositories and their latest status.
Runs/admin/backups/runsEvery backup run, finished or in progress.
Restores/admin/backups/restoresRestore jobs and their outcome.
Destinations/admin/backups/destinationsWhere backups are written.
Policies/admin/backups/policiesWhat is backed up, how often, and how long it is kept.
Server Config/admin/backups/serverThe server's own configuration backup.

Each tab shows a count next to its name, so you can see at a glance whether anything is queued or failing without opening it.

Set up backups ​

Since panel 1.9.3, the Overview tab shows a Set up backups checklist while backups are not set up, with the steps done so far, for example "1 of 3 done":

  1. Add a backup destination - where backups are stored: S3 or S3-compatible storage, SFTP, WebDAV or Nextcloud, a restic REST server, a local path, or a custom rclone config. Add destination opens the destination form. Once done, the step shows how many destinations are active.
  2. Create a backup policy - what is backed up, for whom, on what schedule, and how long it is kept. Create policy opens the policy form with All accounts (server-wide default) already selected, which covers every account that has no more specific policy. When a server-wide policy exists but is turned off, the step says so and offers Edit policy instead, to turn it on.
  3. Wait for the first backup - the first backup of each covered account starts shortly after a policy is activated, and backups then run on the policy's schedule, by default daily at 01:30 server time. Once done, the step shows how many backup runs there have been.

Each done step links to its tab with Manage. Under the steps, the guide notes that a Local path destination keeps backups on this server, so it is not an off-site backup; see the warning on the destinations page.

The guide disappears after the first account backup has run, and comes back whenever no destination or no policy is active. A server configuration backup does not count as the first backup.

The Overview table ​

ColumnWhat it shows
AccountThe hosting account the repository belongs to.
DestinationWhere the repository is stored.
StateThe state of the repository.
Last backupThe outcome of the latest backup.
Last attemptWhen the latest backup ran, successful or not. Called When before panel 1.9.3.
Last successful backupSince panel 1.9.3. When a backup of the account last succeeded, or never.
Failures since last successSince panel 1.9.3. How many backup runs in a row have failed since then.
SizeThe size of the repository.
ErrorThe reason the latest backup failed.

A reseller's Backups page shows the same columns for the reseller's accounts.

Accounts on plans without backups ​

Since panel 1.9.6, a hosting plan can be sold without backups. The Overview says so instead of leaving such accounts unexplained:

  • A row of an account on such a plan reads Hosting plan without backups under the account's name, and offers no Backup now, unless the account has a backup policy of its own.
  • Accounts on such a plan that were never backed up have no row. A Hosting plans without backups section above the table names them with their plans, "These accounts are on a hosting plan set to no backups and have no policy of their own, so they are not backed up.", and counts the rest when there are many.
  • When these are the only accounts, the empty table reads "Accounts on hosting plans without backups are listed above." instead of asking for a destination and a policy.

A reseller's Backups page shows the same for the reseller's own accounts.

Backups that keep failing ​

Since panel 1.9.3, an account backup that keeps failing is raised until a backup of it succeeds again. AdminBolt follows each account on each destination on its own. Scheduled backups and Backup now both count; server configuration backups do not.

  • The first failure after the last successful backup sends the critical Account backups keep failing notification to the notification email address, to the webhooks, and to the notification bell of every administrator. The bell reads "Backups of account to destination are failing", with the number of failed runs in a row, since when, the last successful backup, and the last error, and links to this page.
  • A reminder reads "Backups of account to destination are still failing". It is sent once the failures reach a number of runs in a row, or a number of hours since the first of them, whichever comes first, and then every 7 days while the failures last. Both limits are set on System Notifications, 3 runs and 48 hours unless you change them.
  • Health lists the account backup as a critical issue: "Backups of account to destination have been failing since date (n failed runs in a row).", with the next step "Open Backups, check the destination and the last error, then run Backup now." See Health.
  • The Overview table shows the last successful backup and the failures since.

A successful backup ends it: the count returns to 0, and the Health issue goes away.

No notification is sent for a suspended account, or while the Account backups keep failing event is switched off on System Notifications; Health still shows the issue. When no active policy uses the destination any more, for example because the account's policy now writes to another destination, nothing is sent and Health shows nothing for it. Since panel 1.9.3, the per-run Account backup failed notification is not sent for a suspended account either.

When a server is updated to 1.9.3, the failures recorded before the update are counted without sending a notification for them, and Health lists them at once. The first reminder for them is sent when a backup fails again after the update and a limit is reached.

Backup slots ​

A server runs a limited number of account backups at once. Each running backup takes a backup slot, whether its policy's schedule started it or someone pressed Backup now.

Since panel 1.9.1, the number of slots is half of the server's CPUs, rounded down, and at least one. To set a fixed number instead, run this from the server's command line, with the number of slots you want:

bash
bolt-cli set-ini-settings BOLT_BACKUP_CONCURRENCY 4

The value must be a whole number of 1 or more. Anything else is refused, and nothing is stored.

A due backup starts when a slot is free. When every slot is in use, it waits for a free one.

When scheduled backups fall behind ​

Since panel 1.9.1, the Overview tab warns Scheduled backups are falling behind when an account's next scheduled time has passed and the backup it was due still has not started. The warning says:

  • how many accounts are behind their schedule, how many are waiting for a backup, and since when the oldest has been due,
  • how many backup slots are in use, out of how many, and where that number comes from: half of the server's CPUs, or BOLT_BACKUP_CONCURRENCY when you set it.

It then names one of two causes:

  • All backup slots are in use, so due accounts wait for a free slot. Raise the limit with bolt-cli set-ini-settings BOLT_BACKUP_CONCURRENCY <n>, spread the policy schedules over the day, or use a faster destination.
  • Backup slots are free but due backups are not being started. Check that the panel scheduler is running.

The warning covers the whole server, so it appears on the administrator's Backups page only, not on a reseller's.

Starting a backup by hand ​

Backup now on a repository's row starts a backup of that account at once. Since panel 1.9.1, when the backup does not start, the notification says why:

MessageMeaning and next step
Please wait for the current backup to finish.The account already has a backup running. Wait for it to finish.
All backup slots on this server are in use by other backups.Try again in a few minutes, once one of them has finished. See Backup slots.
Another backup was being started at the same moment.Try again in a moment.
The server did not accept the backup, so no backup is running for this account.Check that the backup destination is reachable, then try again.
The stored settings of backup destination name cannot be decrypted. Edit the destination, enter all of its settings again and save it.Since panel 1.9.2. The destination's settings cannot be read, so no backup can use it. Enter them again; see Unreadable destination settings.
This folder already holds a backup repository created by another server or an earlier install. Create a new destination with its own path for this server and back up to it. Do not change this destination's path: the backups already on it would stop working.Since panel 1.9.3. The destination's folder already holds a repository this server cannot open. See Sharing a destination between servers.
Backups are disabled for this account, it has no active backup policy, or the server could not be reached.Check which of the three applies. Which accounts a policy covers is on the Policies tab.

A scheduled backup to a destination whose settings cannot be read stops the same way: the run is recorded as failed on the Runs tab with that message, and the Account backup failed notification is sent. Since panel 1.9.2, a backup whose repository could not be set up on the destination is recorded as a failed run and notified too; the next scheduled run, or Backup now, tries to set the repository up again.

On a reseller's Backups page, an unreadable destination is reported as "The backup destination settings for this account cannot be read, so no backup is running. Contact your server administrator to fix the destination.", because only an administrator can edit destinations.

When a repository key cannot be read ​

Each repository is protected by a key the panel stores encrypted. Since panel 1.9.3, when the panel cannot decrypt that key, no backup can be written to the repository or restored from it, and the repository's row on the Overview tab offers Start a new repository. Health lists such repositories too.

Start a new repository asks for confirmation, then prepares a new repository with a new key, which the next backup of the account creates. The old repository is not deleted: it stays on the destination with its previous password and path, but the panel cannot open it. Contact support if you need data from it. The action is refused, with nothing changed, while a backup of the repository is running, and when the key turns out to be readable.

The server's own configuration backup has the same action on the Server Config tab; see Server Configuration Backup. Only administrators see the action.

Over the admin REST API, POST /api/admin/backup-repositories/{id}/start-new-repository does the same. It answers 200 with the old and the new path, 404 for an unknown repository, 409 while a backup of it is running, and 422 when its key can be read.

Backups of a deleted account ​

Deleting a hosting account does not delete its backups. The repository stays on the Overview tab under the account's old username, marked Account deleted with the date, and carries two actions of its own:

  • Restore to new account - recreate the account and restore the snapshot into it. When you keep the original username and the snapshot was taken after the server was updated to 1.9.0, the account's mailboxes, databases, database users, and grants come back as well (see Restoring a whole account). Otherwise only the home directory is restored, and you recreate the databases and import each dump afterwards.
  • Delete backups - remove the repository together with its history. This cannot be undone.

Since panel 1.9.6, an account created again under the same username starts a repository of its own. The deleted account's repository stays on the Overview as it is, and only Restore to new account hands its backups to a new account. Each hosting account sees and restores only its own snapshots; see Choosing a restore point.

Restoring a whole account ​

Since panel 1.9.0, Restore on a repository's row offers Whole account (files, mailboxes, databases and users). It restores the home directory and recreates every mailbox, database, database user, and grant the account is missing, with their original passwords, then imports the data of each database it recreated.

What still exists is left as it is:

  • an existing mailbox keeps its password, its quota, and its mail,
  • an existing database is never imported into, and an existing database user keeps its password.

It needs a snapshot taken after the server was updated to 1.9.0, because only those record what the account held. An older snapshot is refused before anything changes; restore its files and import its dumps as before. The restore is also refused up front when the snapshot belongs to a different username, or when something in it now belongs to another account on this server.

A few things are not recreated automatically. PostgreSQL databases and users are reported and left for you to recreate before restoring the dump. Remote MySQL hosts are not restored. A mailbox on a separate mail server is not recreated. The report names each of these with what to do.

Administrators and resellers can start a whole-account restore. Clients cannot.

The restore report ​

The restore runs in the background. When it has run, Restore report on the repository's row, and the job on the Restore Jobs page, list every object with its outcome:

OutcomeMeaning
RecreatedThe object was missing and is back, with its original password where it has one. A recreated database has its data imported.
Left as it wasThe object still existed and was not touched.
FailedThe object could not be recreated. The row says why.
Not restoredThe object could not be recreated automatically, for example because the snapshot does not hold its password. The row says what to do.

The job succeeds only when nothing failed and nothing was left unrestored. Running the restore again after a failure finishes what the first attempt could not, without creating anything twice.

A mailbox recreated this way has its original password, which the panel does not know. The account owner signs in to webmail with that password, or sets a new one to use the panel's one-click webmail sign-in again.

Warning: Downgrading the panel below 1.9.0 is not supported after a whole-account restore has run on the server.

The administrator API ​

Since panel 1.9.5, the administrator REST API backs up and restores accounts as the Overview tab does. The calls need an administrator API key; none of them needs an explicit grant. With an expired license, the reads keep working and the other calls answer 403. Lists take page and per_page (25 by default, at most 100) and answer with meta.

Method and pathWhat it does
GET /api/admin/backup-repositoriesThe repositories of the Overview table, with their state, last backup, size, destination, and last error. hosting_account_id, state (uninitialized, ok, error, or locked), and orphaned filter them; an orphaned repository belongs to a deleted account.
GET /api/admin/backup-repositories/{id}One repository.
GET /api/admin/backup-repositories/{id}/snapshotsThe snapshots of a repository, read from its destination, with the full id a restore takes. A destination that cannot be reached answers 502.
POST /api/admin/backup-repositories/{id}/backupStart a backup now, like Backup now.
POST /api/hosting-accounts/{id}/backupThe same by account id, also for an account that has no repository yet; its first backup creates it.
POST /api/admin/backup-repositories/{id}/restoreRestore the account from a snapshot, like Restore.
POST /api/admin/backup-repositories/{id}/restore-deletedRestore the backup of a deleted account into a new account, like Restore to new account.
POST /api/admin/backup-repositories/{id}/start-new-repositoryStart a new repository, described above.

A backup or a restore runs in the background and answers 202 with the run or the restore job. Follow it on GET /api/admin/backup-runs/{id} (Backup Runs) or GET /api/admin/restore-jobs/{id} (Restore Jobs). A backup that cannot start is refused with 409 and the same reason as the notification on the page, for example while the account already has a backup running, while all backup slots are in use, or when the account has no active backup policy. When the server did not accept the backup, the answer is 502 with the failed run.

A restore takes:

FieldMeaning
snapshot_idRequired. The full id of a snapshot of this repository, from its snapshot list. Another snapshot answers 422.
modein_place (the default) puts the files back, download copies them into ~/restored-files next to the live ones, and full_account is the whole account restore.
pathA file or folder inside the account's home, to restore only that. A whole account restore ignores it.
restore_databasesWith in_place: also import the database dumps the snapshot holds.

A restore is refused with 409 while another restore of the account runs, also one from Acronis, and while the server runs as many restores as it allows. A whole account restore from a snapshot that does not record the account is refused with 409 before anything changes. The restore report of a whole account restore is in the job's report.

Restore to new account over the API takes snapshot_id, username, domain, hosting_plan_id, and optionally password, which is generated when you leave it out and otherwise takes 16 to 128 letters, digits, underscores, and hyphens. It answers 202 with the new account's hosting_account_id and the restore job. When the account was created but the restore did not start, it answers 201 and says why. A username that is taken answers 422. As on the page, the whole account comes back only when you keep the original username and the snapshot records the account; otherwise the home directory is restored.

Destinations, policies, and the server configuration backup are on the API too; see Backup Destinations, Backup Policies, and Server Configuration Backup. Delete backups of a deleted account, the Limits settings, and the run logs stay on the page. Resellers back up and restore their own accounts over the reseller API, see reseller Backups, and account owners restore a mailbox or a mail folder over the client API, see client Backups.

How the pieces fit together ​

  • A destination is a place backups are stored.
  • A policy says what to back up, on what schedule, and how many copies to keep.
  • A run is one execution of a policy. It succeeds, fails, or is still going.
  • A restore job takes data back out of a repository.
  • A repository is the per-account store that all of the above act on.

Set up a destination first, then a policy, and the runs follow on their own.

Whole-server backups with Acronis ​

Since panel 1.9.3, a server can also be backed up as a whole into Acronis Cyber Protect Cloud, with the optional Acronis Backup module. Those backups are managed on their own page, Backups > Acronis, not on the tabs above: see Acronis Backup. A server can use both, but they read the same data and compete for disk I/O, so keep their schedules apart.