Back up and restore

MOS creates manual, whole-suite backups on storage that is mounted on the server running MOS. The practical destination depends on where that server lives.

If you are deciding how many copies to keep and where, read Keeping copies first. This page is the mechanics.

A backup holds every secret your server has

Any backup contains your data, credentials, and secrets. It is encrypted with your recovery key before it is written anywhere, so a stolen drive or a breached bucket cannot be read. The server keeps a copy of that key so backups can run without you, which it holds inside its own encrypted vault: on own hardware, a stolen server with password-protected startup on gives up neither the server nor the backups, and with it off a thief who gets past the machine has the key to both. You keep a copy too, because it is the only thing that can open these backups on a replacement machine. Bundles you downloaded from an earlier MOS are not encrypted at all: move them out of Downloads and off casual cloud storage.

Your recovery key

MOS shows you the key once, before your first backup, and will not take that backup until you say you have kept it. It looks like MOS-7K2F-9XQ4-…: eight groups of four characters, in an alphabet with no letters that can be mistaken for digits, so it survives being written on paper.

• Save it somewhere that is not this server. A password manager, or paper somewhere that is not the building the server is in. Without it, a replacement server cannot read a single backup, and nobody can recover it for you.
• Download the recovery kit. A text file with the key, the drives and buckets you have connected, and the steps to recover onto another machine. It never contains your storage provider’s access key — that lives in your provider’s console, and a new key for the same bucket works just as well.
• You can see it again. Show key on the Backup & Restore screen asks for your owner password and then shows the key and offers the kit again, so a kit that has gone stale since you connected new storage can be re-downloaded. It also lists, by name, every place this key opens and every place that still needs another server’s key.
• What the copy on the server does and does not protect. A key held on the server protects against a stolen drive or a breached bucket, not against a compromised server: something running on your server with the key can read and delete your backups, which is why one copy you unplug matters. It is there so unattended scheduled backups can run.
• You can change it. Show key → Change recovery key makes a new one and moves this server’s disk and every backup it can reach over to it; a drive that was not plugged in catches up the next time you connect it. Changing the key does not make old snapshots unreadable to someone who already had the old key and a copy of your storage, and the screen says so — if you think that happened, start a fresh archive.

What a backup contains

A MOS backup captures:

• every installed app and its declared data volumes,
• the exact installed app-package snapshots and settings,
• the owner account, app secrets, and app connections,
• the Home dashboard layout,
• domain and HTTPS configuration.

Restore requires a working MOS installation. A backup is not a bare-metal installer by itself. The version does not have to match: MOS restores a backup written by its own release or any earlier one, so a current install reads a backup taken months ago.

Choose a destination for your installation

Own hardware

Connect a writable USB disk or other external drive directly to the MOS machine. An encrypted drive is strongly recommended. MOS can detect supported local devices and offer to mount them from Suite Manager.

Do not save the only backup on the server’s internal system disk: a disk failure could take out both the suite and its backup.

Cloud server

A rented server cannot use a USB disk attached to your computer. You have two options: attach a persistent block-storage volume through your provider, format and mount it on the server, and select that mounted volume in Suite Manager; or connect an S3-compatible bucket, which needs nothing mounted and can live at a different company from the server. Both are billed separately. A mounted volume stays inside your server provider’s trust boundary, so use provider-supported encryption where available; a bucket receives only data MOS has already encrypted.

Provider snapshots are outside MOS either way: they may be useful as an additional recovery layer, but MOS cannot verify their consistency, contents, retention, or restore behavior. They do not replace a tested MOS backup.

Taking a backup

1. Attach and mount the destination described above.

2. Open Suite Manager → Backup & Restore. The destination appears under Where backups go; if MOS has not opened it yet, choose Open this drive. Select it — that is what makes it the place your backups go.

3. Click Back up now. The first time, MOS shows your recovery key and asks you to confirm you have saved it before it will start. Apps pause while their data is captured and start again when the job finishes.

4. Keep the drive itself on access-controlled storage. There is no separate file to download—the encrypted store on the drive is the copy you keep, and moving a backup to another machine means taking the drive there.

Backups are written under MOS-backups/ on the selected destination, into a single encrypted store that every backup on that drive shares. That store is a restic repository. MOS has no backup format of its own: restic — an open-source backup program in wide use since 2014 — does the encryption, the chunking, the deduplication and the integrity checking, and MOS drives it rather than replacing it. Because the store is content-addressed, a second backup only writes what actually changed, and one drive holds many restore points for far less space than one full copy each. Each restore point records which stored data it needs; MOS checks the store’s integrity and re-verifies every app package before a restore changes running services.

One drive holds one store. Bundles from MOS 0.19 or earlier, in the older unencrypted format, are still listed if they are on the same drive, but this version cannot restore them—restoring one needs MOS 0.19 or earlier. You can delete them here to free the space they take.

Backing up somewhere else

A drive in the same room as the server survives a failed disk. It does not survive a fire, a flood, or someone walking off with both. Under Where backups go, Add destination points MOS at a bucket at a storage provider — anything S3-compatible, such as Backblaze B2, Wasabi, Cloudflare R2, Tigris, or a MinIO server of your own.

You need four things from your provider: the endpoint address, a bucket that already exists, and an access key with its secret. A folder is optional and lets one bucket hold the backups of more than one server. Check it works tells you whether MOS can reach it before you save, and says which of a wrong key, a missing bucket or an unreachable address it ran into.

• Your backups are encrypted before they leave the server. The provider stores what it cannot read. restic encrypts every chunk and its metadata with your recovery key, so nothing MOS uploads is readable without it.
• A bucket behaves like a drive from there on. Back up to it by hand or on a schedule, check it, note it, restore from it, delete from it.
• Nothing is deleted when you disconnect. MOS forgets how to reach the bucket; the backups in it stay, and reconnecting with the same details lists them again.

A bucket is only as recoverable as your recovery key

The provider holds data it cannot read. Your recovery key is what opens it, and the copy that matters is the one you keep — see Recover onto a new machine.

Backing up automatically

The most recent backup you have should not be the one you last remembered to take. Select the place your backups should go under Where backups go, then under Automatic backups on the same screen choose Change, turn the schedule on, and pick daily or weekly and a time. The selected place is also where the backup before a MOS update goes; a backup you take yourself goes there too unless you pick another one for that backup, so a drive you keep in a fire safe is still one click.

• Times are yours, not the server’s. The time you pick is read in the time zone of the browser you set the schedule from, so 3am means 3am where you are even when the server runs in UTC. The screen names the zone it is using.
• A destination that is not there is not a failure. If the drive is unplugged, or the connection to your storage provider is down when the time comes, MOS says it is waiting and backs up as soon as it can reach it again, up until the next scheduled time.
• A server that was switched off catches up. It takes one backup shortly after starting again, not one for every window it missed.
• Retention prunes automatic backups only. Keeping the last 7 means the eighth automatic backup removes the oldest, once the new one has succeeded. Backups you took yourself are never removed by retention, whatever it is set to—so a copy you took before a risky change stays until you delete it. The backup MOS takes before it updates itself counts towards the same number, like a scheduled one.

Apps pause for a few minutes while a backup runs, which is worth remembering when picking the time.

A workable routine

Leave a daily schedule on. MOS backs up on its own before it updates itself, so the moment left to cover by hand is a change you are about to make—uninstalling an app, or updating one that migrates data. Periodically check that the destination is still readable with Check on a restore point.

Restoring

Restore replaces the current suite with a backup on a machine that already has a compatible MOS installation.

1. Attach or mount the storage containing the backup, open Suite Manager → Backup, and select it.
2. Type RESTORE to confirm.
3. MOS verifies the stored data and each saved app-package snapshot before stopping services. It creates a small rescue copy of current state, restores settings, package definitions, and data, then rebuilds the app runtimes.

Important boundaries:

• Restore goes forward, never backward. Each backup records the MOS version that wrote it, and restores onto that version or any later one. Install the current release; MOS does not need, and cannot install, an older version of itself. The one direction that fails is restoring a newer backup onto an older MOS, which MOS reports and refuses rather than half-applying.
• Backups from MOS 0.19 or earlier cannot be restored here. Those were unencrypted bundles, a format this version no longer reads. Restore one with MOS 0.19 or earlier, or take a fresh backup on the machine you are running now.
• Restore is whole-suite. Per-app restore is not supported.
• The machine must already run MOS. Install MOS first, then attach the backup destination and restore. Bare-metal recovery has not yet been validated as a single end-to-end workflow.
• A replacement machine needs the recovery key as well as the storage. See below; restoring onto the server that made the backup never asks for it, because that server already holds it.
• Package snapshots are preserved, registry artifacts are not. If an upstream registry removes a required digest-pinned image, MOS restores state and reports the affected app as failed rather than substituting another version.

Recover onto a new machine

This is what the recovery key is for: the server is gone — fire, theft, a dead disk — and a drive or a bucket is all that is left. A cold standby kept powered off elsewhere, or any freshly installed machine, becomes the server you lost.

1. Install MOS on the replacement machine — the current release, whatever the backup was written by — and create an owner account on it so you can sign in. It can be a throwaway account; the restore replaces it with the one from the backup.

2. Open Suite Manager → Backup & Restore and connect the same storage: attach the drive and open it under Where backups go, or Add destination with the same endpoint, bucket and folder. Your provider’s console holds your access key, and a new key for the same bucket works too.

3. The place appears under Brought in from other servers, saying its backups were written by another server. Choose Enter recovery key and type the key from your kit. Capitals, spaces and dashes do not matter, and a slip is reported as a typo rather than as a wrong key.

4. The restore points appear, each showing which server wrote it. Pick one and restore it as usual.

5. When the restore finishes you are signed out. Sign in with the owner password of the server the backup came from — accounts and passwords now match the backup.

If the old server used a domain

Your suite comes back on this machine’s own address — the one you were using while you restored. A restore never changes that, whichever address it is: the Easy Door, the name your own network holds, or a domain you set this machine up with before restoring. If you had already given this server a domain, that is what your suite comes back on, and nothing about it changes.

The old server’s domain is set aside rather than moved, because a name points at one machine at a time. Settings names it and offers to serve it from this machine in one step: MOS kept the domain’s credential from the backup, so you enter no token, and MOS reports success only once the certificate has been issued and the name answers here.

Until that name points at this machine, anything set up against the old address keeps failing — phone apps, desktop sync clients, browser extensions. Three things fix that:

• Point the name here. Change the record at your DNS provider, and any override your own network holds for it, to this machine’s address. MOS reads that name and tells you what it currently answers, but it never changes DNS for you.
• Give this machine the old server’s network address, if the old server is off and both are on the same network. That is a change on your router — a DHCP reservation for the new machine — and nothing at your DNS provider has to change. It happens outside MOS, so MOS neither does it for you nor sees that you have.
• Point your devices at the new address instead, one app at a time.

Turn the old server off before you point the name here. Two machines answering for one suite means two copies of your data drifting apart, and no way to merge them afterwards.

What just happened to the backups themselves: nothing. Connecting to an archive another server wrote never changes it — not its contents and not the list of keys that open it. MOS keeps the key you entered on this machine and uses it to read that place, and Forget this key on the row takes it back off again.

The key becomes this machine’s own when you restore another server’s backup onto it: the machine now holds that suite’s data, so it uses that suite’s key, and from then on one key opens both the disk and the backups. If the original server comes back on, both machines can write to the same destination; each restore point names the machine that wrote it.

Current limitations

Whole-suite restore only · a restore needs an owner account to sign in with first, so recovery is install, create an account, restore · no automatic backup before an app update, only before a MOS update · one destination per schedule, so a drive copy and a bucket copy are two separate backups · the recovery key cannot be rotated.

If you work with backup, storage, encryption, or recovery systems and want to shape how they land, join us on Discord or open a GitHub issue.