Restoring with mybackup

Your account is backed up off-site for you, on a schedule, without you having to do anything. The tool on this page, mybackup, is the other half of that: it's how you pull those off-site backups back down when you need them. You run it from your own shell — the same login you use for your files — and you never touch the server or need any special access.

There is one thing to know up front, and it saves a lot of confusion later: mybackup only ever restores. It does not make backups. The scheduled off-site backups run on their own behind the scenes; mybackup is purely the "get my data back" button.

When to use mybackup, and when to use the UI instead

You actually have two ways to roll back, and they suit different jobs:

The Ægir control-panel Restore task — the fast, everyday one. Open a site, run Backup before a risky change, and later click Restore to roll that site back to any backup it has. It happens in the web UI, it's quick, and a fresh backup is taken automatically before the restore runs. This is the right tool for "I'm about to do something risky to this one site" and for "put this site back the way it was." It has its own page — see Backing up and restoring in the UI.
mybackup — the off-site safety net. Use it when the UI backups aren't enough on their own: the box itself had a bad day, you deleted files you can't get back any other way, or you want a copy of something as it was a week or a month ago, pulled from cloud storage. It reaches the encrypted off-site copies, not just the on-box ones.

Rule of thumb: reach for the UI Restore first for ordinary "undo" on a single site. Reach for mybackup when you need the off-site copy — a point further back in time, or files that are gone locally.

What mybackup can restore

mybackup restores from your account's off-site backups, which by default cover your whole account:

your Drupal codebases and platforms,
your uploaded files, and
the per-site database dumps that BOA keeps for you.

You can restore the lot, or just one folder inside it.

Two things it deliberately does not do:

No in-place restore. It does not restore files back into their original place. Everything it pulls down lands in a separate staging folder (below), and you move what you want back yourself. That way a restore can never clobber good current data by surprise.
Only you can decrypt yours. It can't decrypt another account's backups, and nobody can decrypt yours without your passphrase — the off-site copies are encrypted end to end. Keep that passphrase somewhere safe (a password manager); there is no reset, and a lost passphrase means the backups can't be opened.

What your off-site backup includes

The off-site copy covers your whole account by default, but it's worth knowing exactly what it takes and what it skips — that's precisely what a restore can bring back.

Included by default: everything under ~/static/ and ~/platforms/, any platforms without codebase access in ~/distro/, and your whole FTP home at /home/<your-account>.ftp/.

Left out by default — scratch space and copies already kept elsewhere, so your off-site storage isn't filled with throwaway data:

in your account: .tmp/, clients/, u/, undo/, and inside static/ the restores/, tmp/ and trash/ folders;
in your FTP home: .tmp/, backups/, clients/, platforms/ and static/.

So the things worth keeping are in, and scratch space and already-duplicated copies stay out.

Fine-tuning what goes off-site

If those defaults don't suit you, you can add your own rules with four small text files in ~/static/control/remote_backups/config/:

include.txt and exclude.txt each hold one --include or --exclude line per path;
include_regexp.txt and exclude_regexp.txt do the same with --include-regexp / --exclude-regexp patterns.

A few rules keep this safe, and BOA checks every line against them before using it:

Every path must be absolute and stay inside static/ or your /home/<your-account>.ftp/ home — anything pointing outside those is refused.
Regex patterns begin with ^ followed by one of those allowed base paths.
The characters $ ( ) { } ; & | < > and the backtick aren't allowed in a path or pattern.
Where an include and an exclude overlap, the exclude always wins.

A line that breaks one of these rules is refused and logged for your host to review rather than quietly applied, so if a customisation doesn't seem to take effect, that log is where your host looks. Nothing in these files is ever run as a command — BOA reads them a line at a time and merges only the directives that pass the checks above into a paths list it builds and owns itself, so a mistyped or even deliberately hostile line can do nothing but get left out. Editing these files needs no special access — they're plain text in your own account.

Running a restore

You run mybackup from your account's shell (the same SSH/SFTP login you use for your files — see Connecting to your account). The command has exactly one form:

TXT

mybackup restore <SERVICE> [RESTORE_PATH] [RESTORE_TIME]

Only restore works. Anything else (mybackup backup, mybackup list, and so on) just prints the usage message — remember, this tool restores and nothing else.

The three parts:

<SERVICE> (required) — which cloud-storage provider to pull from. It has to match the provider your account is set up with. The names BOA understands are: aws, aws_one_zone, aws_standard_ia, azure, b2, cloudflare, do_spaces, gcs, ibm, linode, and wasabi. If you're not sure which one your account uses, that's a quick question for your host.
[RESTORE_PATH] (optional) — the one folder or file you want back, instead of everything. Write it as a full path without the leading slash — for example data/disk/<your-account>/static/projects, not /data/disk/.... Leave it out to restore your whole account. The path can't contain spaces or shell punctuation; anything odd is rejected on purpose, so if a restore is refused, check the path first.
[RESTORE_TIME] (optional) — how far back to go, written as a duration: 1D (one day ago), 7D (a week), 2W, 1M, 1Y, and so on — a number followed by D, W, M, or Y. Leave it out and you get the most recent backup.

Examples

Restore your whole account from the latest off-site backup (here the provider is b2):

mybackup restore b2

Restore just one folder, latest version:

mybackup restore b2 data/disk/<your-account>/static/projects

Restore that same folder as it was 7 days ago:

mybackup restore b2 data/disk/<your-account>/static/projects 7D

What happens after you press enter

When you run mybackup from your shell, it doesn't restore right there and then. It checks your request and queues it, then prints something like:

TXT

Command queued for user <your-account>...
It will be executed by the system shortly...

That's normal and it's a good sign — the restore runs a moment later, on its own, out of the way of your shell session. So if the command returns straight away without pouring out a wall of restore progress, nothing is wrong; it simply hasn't started yet. BOA emails you a confirmation when the restore finishes, if there's an email address on your account.

Where the restored files land

Everything mybackup pulls down goes into a staging folder inside your own space:

TXT

~/static/restores/

It is not copied back over your live files. Once the restore has finished:

look in static/restores/,
check you got what you expected, and
move or copy the pieces you actually want back into place yourself (an ordinary mv, cp, or rsync in your shell).

Your current site is never overwritten behind your back — you're always the one who decides what goes live.

Your local database backups and the space they use

Separately from the off-site backups, BOA also keeps recent database dumps for your Ægir-managed sites right inside your account, so a recent copy is always close to hand:

TXT

~/static/files/dbackup/

These are handy, but they live in your account, which means they count toward your file-space quota. If you're getting close to your limit, this folder is one of the first places worth trimming.

Controlling how many days are kept

You control how many days of these dumps are kept. By default BOA keeps the last 14 days. To change that, create (or edit) a small text file:

TXT

~/static/control/dBackupCycle.info

Put a single whole number in it — the number of days to keep — and nothing else. For example, 7 keeps a week, 30 keeps a month:

echo 7 > ~/static/control/dBackupCycle.info

BOA reads that number the next time it tidies up your dumps and removes anything older. A shorter number frees space sooner; a longer one gives you more history to restore from, at the cost of quota.

(If the file is empty or you delete it, BOA falls back to the 14-day default. If you accidentally put something that isn't a plain number in it, BOA plays it safe and simply skips the cleanup rather than guessing — so it never deletes dumps on a bad value.)

Disabled sites. If a site is disabled, its database is still safe at the system level, but its dumps won't show up in your dbackup/ folder. That's expected — re-enable the site and its dumps come back.

If something needs the operator

Almost everything about restoring is in your hands from your own shell. But a few situations genuinely sit on the server side — for example:

if you're told your account has no off-site backups configured at all, or
a restore keeps failing for a reason that isn't your path or your provider name.

Those aren't things you can fix yourself, and there's nothing to reconfigure on the server from your side. In that case, just open a support request with your host and describe what you saw — that's the right and fastest path.

Backing up and restoring in the UI — the in-UI Backup and Restore tasks, the everyday way to roll a single site back.
Connecting to your account — the shell login you run mybackup from.
Tuning your site & platform — other small text files in your account that change how BOA behaves for you.