Backup and restore
What a backup contains
An instance backup covers the instance as a whole: its databases, its filestore, its addons, the configuration needed to rebuild it and the certificate it serves. A database backup covers one database.
The certificate travels so that a restore, or a move to another server, serves the same certificate at once instead of requesting a new one: the served certificate with its chain, an uploaded certificate when the instance holds one it is not serving, and its names and expiry. Let's Encrypt's own account and renewal files stay behind; the server that restores it makes its own when renewal is due. Its private key is in the archive readably only when every copy of the archive is encrypted, or when it is written with portable credentials. Otherwise it is enciphered for the server that wrote the archive: a restore there puts the certificate back, and a restore anywhere else requests a new one. The backup job's log says which. See Restoring.
Which you want depends on what you are protecting against. A database backup answers "someone deleted the wrong records". An instance backup answers "the server is gone".
Taking one
pelmo$ ohm instance backup --instance fanespelmo$ ohm instance database backup --instance fanesBoth run as background jobs, and both take an exclusive lock on the instance.
Taking a backup, by hand or on a schedule, needs an edition: an unregistered server takes none. Listing and downloading the backups and dumps already on the server is never restricted, so an unregistered server can always reach its own data.
A new instance is not backed up until you set it up: see Schedule nightly backups.
Where an Operator's backup lands
A database backup, a database dump and an instance backup's manual copy started by an Operator,
or by an API key limited to some instances, write
only into that instance's own backup folder on the server. A destination such as
--backup-destination is then a file name, or a path inside that folder; anything outside it is
refused with the folder named. An Administrator, and a key that covers every instance, still write
wherever they name.
A script that uses an instance-limited key to write a backup or a dump to a folder of its own must name only a file from 0.24.0 on, and finds it in the instance's folder of the server's backup directory.
A filestore or data folder that is a link
A backup, a duplicate and a restore never follow a link inside an instance's files: when a database's filestore, or the instance's data folder, has been replaced by a link to somewhere else, the job is refused with the reason, so that nothing outside the instance is copied. If you linked one of those folders to another disk on purpose, move the folder instead of linking it, or link the instance's whole directory, which is still followed.
When the license carries less
This is the part worth reading before it matters. When the license stops carrying a kind of target, that target is switched off on every instance, with its settings and credentials kept, and switched on again by itself when a license carries it again:
The scheduler is handled the same way: a license without scheduled backups disables every backup and restore schedule, keeping their times, while running a backup yourself still works.
A subscription that ends runs unregistered, and an unregistered server takes no backups at all: every instance's backups are set to Disabled until a license is installed again. Renew before the end date. While the license server merely cannot be reached, nothing changes: every schedule and every off-site copy keeps running. See When the license changes.
Where backups go
Every configured target receives a copy. See Targets.
| Target | Edition |
|---|---|
| Local filesystem | Community, Developer, Professional and Provider, but not unregistered |
| FTP | Community, Professional and Provider, but not Developer |
| Amazon S3 and S3-compatible | Professional and Provider |
| Azure Blob Storage | Professional and Provider |
Community takes complete instance backups and writes them to the server and to FTP, and it restores a database into an existing instance. Restoring a whole instance - as a new instance, over an existing one, or by duplicating or moving one - needs the Developer, Professional or Provider edition. A Community server can still list and download every archive, and the archive restores on a server whose license carries restoring.
Configuring a cloud provider is allowed at any edition. A target the license does not carry is switched off by the license, its settings kept, and switched on by itself once a license that carries it is installed, so you can still set an installation up completely before its license arrives.
Being told how it went
An instance's Backup tab can e-mail a report when a backup of that instance finishes, whether you started it or a schedule did. The switch says exactly that, and Minimum outcome is its filter: report everything, or only the runs that came out at or below the outcome you name.
Each recipient box names the addresses the server's SMTP profile appends to whatever you type, so you can see the real recipient list rather than half of it. A check button validates a list without saving it.
Sending needs a working SMTP profile. A backup report is also an alert event, so it can go to a channel instead of, or as well as, mail.
A failed backup is shown without any mail too, so a server that cannot send any still tells you:
- under the bell, as a Backup failed alert;
- on the instance's Backup tab, in red at the top, with the reason and a link to the job, until a backup of the instance succeeds;
- on the Dashboard's Backup card, which names every instance whose last backup failed;
- in the instance's health check: Backups is an error once an instance backed up on a schedule has had no successful backup for longer than its schedule plus a day.
When a backup fails
A backup does not stop at the first target that fails: it tries every one and records a result per target. Work through it in this order:
-
Open the job. The red notice on the instance's Backup tab and the Backup failed alert both link to it. Its result names each target and what it answered.
-
Test the target. Test connection on the target, on the Backup tab, says whether the server can reach it with the credential it holds. A target that reads not configured has no key stored; a credential written on another server has to be entered again here (the instance's Health tab names it).
-
Check the license. A target the license no longer carries is switched off rather than left to fail; the Backup tab says so. See When the license changes.
-
Check the space. A local target needs room on the server's disk; Resources > Storage shows where it went. A managed container whose retention still holds the copy a backup would replace refuses it, and the job says so: give the policy more Copies kept (see Backup storage).
-
Check encryption. An instance that encrypts its backups needs the server's backup key; its Backup encryption health check says when the key is missing.
-
Run it again with Backup now on the Backup tab, or:
Remote or localagainstpelmo$ ohm instance backup --instance fanesThe red notice stays until a backup of the instance succeeds. Until then, the instance's last good archive is the one listed on its Backup tab: take one by hand to a target that works if the cause will take time to fix.
Copies kept
Each target's backup policies say how many copies they keep (Copies kept), so a fast local disk can keep a week while off-site storage keeps a year. The oldest copies beyond that number are removed by the backup job itself, after a successful upload rather than before one. This is separate from a storage provider's retention lock, which stops copies being deleted at all until a date (see Backup storage).