Off-site backups & mybackup

Availability: hosted accounts and PRO-licensed servers. The extended backup subsystem on this page — scheduled, encrypted off-site backups plus the mybackup restore tool — is included with every hosted BOA account, and on self-hosted servers it unlocks with a BOA PRO licence. It's the one extra that isn't part of the free stack. If your account lives on a self-hosted server without PRO, this page's off-site half doesn't apply to you — but the local database backups at the end of this page run on every BOA server regardless.

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 it: for ordinary "undo" on a single site, reach for the control panel's Restore task first — it's quicker and takes a fresh backup before it rolls anything back (see Backing up and restoring in the UI). Reach for mybackup when you need the off-site copy: the box itself had a bad day, you deleted files you can't get back any other way, or you want something as it was a week or a month ago, pulled from cloud storage.

Basic use

Five things cover almost everything. If you stop reading after this section, you can already run your off-site backups and get your data back.

1. Know where your local database backups are. Every night, each of your active sites' databases is dumped into your account, under ~/static/files/dbackup/, and kept for 14 days by default. These dumps count towards your file-space quota; the retention knob is a one-line file (details below).

2. Check that off-site backups are enabled. On hosted accounts they typically are. If in doubt, one short support request confirms that the scheduled backups are running for your account.

3. Add your cloud-storage credentials. Pick a provider (Amazon S3, Backblaze B2, Wasabi, and more), open its ready-made template file in ~/static/control/remote_backups/credentials/ — aws.txt, b2.txt, wasabi.txt, and so on — and replace the your_... placeholders with the real keys from your provider's console. Then keep the file private:

chmod 600 ~/static/control/remote_backups/credentials/*.txt

That's the whole switch — from then on your backups are encrypted and shipped to your own storage on a schedule. A file still holding its your_ placeholders counts as not set up and is skipped.

4. Restore with one command. From your own shell:

mybackup restore <SERVICE>

(for example mybackup restore b2). This queues a restore of everything into a staging folder, ~/static/restores/ — it never overwrites your live files. BOA emails you when it's done, and you move back the pieces you want yourself. Restoring just one folder, or a point further back in time, is in Advanced use below.

5. Watch your quota. Everything stored locally in ~/static/files/dbackup/ counts towards your usage limit. Getting close? Shorten the retention period, remove old backups, or upgrade your plan.

That's it for the basics. Everything below — what exactly goes off-site, custom includes and excludes, bucket naming, precise restores — is optional depth for when you need more control.

Advanced use

How the system works

The off-site subsystem is built on Duplicity, a battle-tested backup tool that:

1. encrypts your data — the off-site copies are encrypted end to end: nobody can decrypt yours without your passphrase, and you can't decrypt anyone else's;
2. manages incremental backups — after each full copy, only changes are stored, which keeps the off-site footprint small;
3. supports versioning — you can restore files as they were at a specific point in time.

The encryption passphrase is generated and guarded on the server — nothing you do day to day needs it, because both the scheduled backups and mybackup read it server-side. It's still worth holding your own copy in a password manager: with it (plus your storage keys) you can read your backups on any machine, with no BOA server involved at all. Requesting it from your host and using it that way is covered on Disaster-proof access to your off-site backups. There is no reset, and a lost passphrase means the off-site copies can't be opened.

One deliberate design choice to know: no in-place restore. mybackup never writes restored files back into their original place. Everything lands in ~/static/restores/, and you move what you want back yourself — so a restore can never clobber good current data by surprise.

What goes off-site by default

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

Excluded — scratch space, duplicate views of folders already included, and the on-box task archives:

• 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/.

The FTP-home platforms/ and static/ entries are just shortcut views of folders the include list already covers directly, so nothing is lost by skipping them. The backups/ entry is the on-demand Backup task's archive store: those working archives deliberately stay on the box — your database half off-site is the nightly dbackup/ dump set riding inside static/, as the disaster-proof restore page shows. So the things worth keeping are in, and working copies stay out of your bucket.

Fine-tuning what goes off-site

If the defaults don't suit you, 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.

BOA checks every line against these rules before using it:

• Each line is exactly one directive, one space, one path or pattern, and nothing more — a path or pattern can't contain spaces or any other whitespace, and nothing may follow it on the line.
• Every path must be absolute and stay inside your account's /data/disk/<your-account>/static/ folder or your /home/<your-account>.ftp/ home — anything pointing outside those is refused, and after that base only / and further path text may follow.
• A plain --include or --exclude path is built from letters, digits and the characters _ . , + = @ ~ / - only.
• An --include-regexp or --exclude-regexp pattern may open with ^ before one of the allowed base paths (the dot in .ftp may be written escaped, as \.), and on top of the plain-path characters it may also use the regex characters . * + ? [ ] \ ^.
• The characters $ ( ) { } ; & | < > and the backtick aren't allowed in a path or pattern.
• Blank lines and # comment lines are simply skipped, and stray whitespace at either end of a line — including the line endings a Windows editor leaves behind — is trimmed rather than counted against the line.
• 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 — and only that line is dropped: the file's valid lines and the built-in defaults still take effect. 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 into a paths list it builds and owns itself, so a mistyped or even deliberately hostile line can do nothing but get left out.

Credentials in detail

The supported services, and the <SERVICE> names BOA understands, are:

  aws -------------- Amazon S3 (Standard)
  aws_one_zone ----- Amazon S3 (One Zone)
  aws_standard_ia -- Amazon S3 (Standard-IA)
  azure ------------ Azure Blob Storage
  b2 --------------- Backblaze B2
  cloudflare ------- Cloudflare R2 Object Storage
  do_spaces -------- DigitalOcean Spaces
  gcs -------------- Google Cloud Storage
  ibm -------------- IBM Cloud Object Storage
  linode ----------- Linode Object Storage by Akamai
  wasabi ----------- Wasabi Hot Cloud Storage

Each credential template names exactly what its provider needs (Backblaze wants B2_ACCOUNT_ID and B2_APPLICATION_KEY, Wasabi wants WASABI_ACCESS_KEY and WASABI_SECRET_KEY, and so on). Here's the AWS file (aws.txt) as BOA ships it:

export AWS_ACCESS_KEY_ID="your_aws_access_key"
export AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
export AWS_REGION="your_aws_region"  # E.g., "us-east-1"
export KEEP_WITHIN="3M"
export FULL_BACKUP_FREQUENCY="28D"

Every template ends with the same two retention knobs:

• KEEP_WITHIN — how long off-site backups are kept before the oldest are pruned. Months or years only: the default 3M keeps three months, 1Y keeps a year, and the minimum is 1M. A days-or-weeks value here is rejected and the default used instead.
• FULL_BACKUP_FREQUENCY — how often a complete fresh copy is taken; the backups in between store only what changed. Days only, from 7D to 60D: the default 28D takes a new full copy every four weeks. Out-of-range values fall back to the default.

The same safety rules as the config files apply: each line must be a simple NAME="value" assignment (comments after a # are fine), values may not contain $ ( ) { } ; & | < > or a backtick, and a line that breaks a rule is refused and logged for your host — nothing in the file is ever run as a command. If a key your provider generated happens to contain a forbidden character, generate a fresh key rather than trying to work around it.

Where your backups land: the bucket name

Off-site backups are stored in a bucket (some providers say container or space) in your storage account, and BOA derives its name automatically — you don't pick it:

back-to-USER-HOSTNAME-PROVIDER

• USER — your account name (the oN in /data/disk/oN/static).
• HOSTNAME — the server's hostname, with the dots turned into hyphens.
• PROVIDER — the service name, with underscores turned into hyphens (aws_one_zone becomes aws-one-zone; the credential file keeps the underscore).

The easy way to know the first two: together they're your Ægir control-panel address, which is exactly USER.HOSTNAME. If you sign in at o123.fr8.eu.aegir.cc, your USER is o123 and your HOSTNAME is fr8.eu.aegir.cc — so backups to Wasabi land in a bucket named back-to-o123-fr8-eu-aegir-cc-wasabi.

Why this matters: most providers let the bucket be created automatically on the first backup, so usually there's nothing for you to do. A few require you to create it by hand before the first run (Linode is one), and Amazon S3's automatic creation can be unreliable across regions. If you do create the bucket yourself in your provider's console, give it exactly the name above — and if you're not sure whether your provider needs the manual step, that's a quick question for your host.

Restoring with precision

The full form of the restore command is:

mybackup restore <SERVICE> [RESTORE_PATH] [RESTORE_TIME]

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

• <SERVICE> (required) — which provider to pull from, using the <SERVICE> names in the table above. It has to match the provider your account is set up with; if you're not sure which one that is, ask 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 — whole account, one folder, one folder a week ago:

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

What happens after you press enter

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

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.

Once it has finished:

1. look in ~/static/restores/,
2. check you got what you expected, and
3. 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.

(The restores/ folder is yours and writable by default — if you've tightened its permissions at some point, make sure it's writable again before you restore into it.)

Checking what the backups have been doing

The latest backup actions for your account are logged where you can read them yourself:

~/static/control/remote_backups/logs/

That's the first place to look if you're wondering whether the scheduled off-site backups have been running. Rejected lines from your config or credential files are logged separately, on the server side, where only your host can read them — that's the log to ask about if a customisation doesn't seem to take effect.

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:

~/static/files/dbackup/

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

You control how many days of these dumps are kept — by default the last 14 days. To change that, create (or edit) a small text file and put a single whole number in it — the number of days to keep — and nothing else:

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. The whole file has to be that one number — digits only, from 1 to 9999. A value that doesn't fit the shape, like 2 weeks or 0, is simply ignored: the cleanup still runs, on the 14-day default, and the ignored value is logged on the server side where your host can look it up. So a bad value never deletes more than the default would — but it also never extends your retention, which is worth knowing if you set a long window and the folder seems to shrink back to two weeks of history.)

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,
• a restore keeps failing for a reason that isn't your path or your provider name, or
• you want your own copy of the backup encryption passphrase for server-independent access — the exact request to send is on Disaster-proof access to your off-site backups.

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.

Related

• Disaster-proof access to your off-site backups — reading the same off-site backups from your own machine, with no server involved.
• 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.