Docs / Running the server

Backup and restore

A backup holds everything needed to bring the phone system back after a failure: the database with all tenants, extensions, numbers, routes, settings and call history, plus voicemail, prompts, hold music and, if you choose, call recordings. This chapter covers setting up backups on Server › Backup, what a backup holds, running one by hand, restoring, and moving to a new server.

The Backup page is for system administrators. The same settings are in the console menu on the server's screen, under Backup and restore (see Server tools).

Choosing where backups go

Backups belong somewhere other than the server itself: a NAS, a file server, or at least another disk.

1. Open Server › Backup. Until a destination is set, the page says No backups are being made. Choose where they go below.
2. In the Where backups go card, choose the Destination:
   • Windows / NAS share (SMB): fill in Share (for example //nas.example.com/backups), User name, Domain (optional), Password and optionally a Folder inside the share. The share must allow SMB version 3. The password is stored on the server, readable by root only; leave the field empty later to keep the saved one.
   • NFS: fill in Export (for example nas.example.com:/volume1/backups) and optionally a Folder inside it. The export must allow this server to write to it.
   • Local disk: fill in Folder, a folder on a separate disk mounted on this server, for example /mnt/backup. System folders and the phone system's own data folders are refused. A folder on the system disk does not protect you against losing that disk.
3. Select Save and test.

The server mounts the destination, writes and deletes a test file, and reports The destination works: with the free space and the number of backups already there. If it fails, the message shows the error, for example a share name that does not exist, a password the NAS refused, or no permission to write.

The share is mounted only while a backup, a test, a listing or a restore runs, and unmounted afterwards.

Schedule, how many to keep, and recordings

In the Schedule card:

• Back up every day: tick it for a daily backup.
• At: the time of day, in the server's time zone. The default is 02:30.
• Keep the newest: how many backups of this server to keep, 1 to 365. The default is 7. After each new backup, older ones beyond this number are removed.
• Include call recordings (they can be large): off by default. Tick it to put recordings in every backup.

Select Save. The card then shows when the next backup runs. Without a schedule, the card says Backups run only when you start them.

Think about recordings before you tick the box: with many recorded calls, every daily backup carries all of them again. If you keep recordings for legal reasons, make sure the destination has room for Keep the newest times their size.

How the schedule runs

The daily backup is the system timer onyx-backup.timer. It is switched on when a schedule and a destination are both set, and off otherwise. It starts at the chosen time, up to two minutes later. If the server was off at that time, the backup runs soon after the server starts again. To see when it runs next from a shell: systemctl list-timers onyx-backup.timer.

Running a backup now

Select Back up now at the top of the Backup page (it appears once a destination is set). The backup runs as a job: the page shows its output, and it keeps running if you leave the page. When it is done, the page shows Last backup with the name, the size and how long it took. If a backup fails, scheduled or not, the page shows The last backup failed with the reason until the next one succeeds.

The phone system keeps working during a backup. Calls are not affected.

From a shell, sudo onyx-os backup.run starts the same job.

What a backup holds

Each backup is a folder named after the server and the time, for example pbx-20261007-023000, inside a folder onyx-backup at the destination. It contains:

A backup that was interrupted has no manifest. It shows as incomplete (interrupted) in the list and cannot be restored; it is removed by a later backup.

Listing and deleting backups

In the Backups card, select List backups. The list shows every backup at the destination with its version, date and size, and the free space at the destination. Select Delete on a row to remove a backup.

Keep the newest only removes this server's own backups. If several servers back up to the same share, each keeps its own number of backups and leaves the others alone.

Restoring a backup

A restore replaces the phone system's current data with the backup's. Use it after a failure, a mistake you cannot undo by hand, or to move to a new server.

The phone system stops while it restores: calls in progress drop and phones cannot call until it is done. Voicemail left since the backup was made is set aside, not merged.

To restore:

1. Open Server › Backup and select List backups.
2. On the backup you want, select Restore....
3. Read the warning, then type the backup's name in Confirm, exactly as shown.
4. Select Restore.

What happens, in order:

1. A backup made by a newer version of Onyx Voice than the server runs is refused: update the server first (see Updates). A backup from an older version is fine: the database is brought up to date when Onyx Voice starts.
2. Every file of the backup is checked against its checksum. If one is damaged, the restore stops and nothing is changed.
3. Onyx Voice and the engine stop.
4. The current data folder, the voicemail folder and (if the backup has recordings) the recordings folder are renamed, not deleted, with .before-restore- and the time added to their names. The backup's copies are unpacked in their place.
5. The current database is renamed, not deleted, to onyx_before_restore_ and the time. The backup's database is restored as the new one.
6. The key that protects two-factor sign-in secrets is taken from the backup, so two-factor sign-in keeps working. The current key is kept next to it.
7. Onyx Voice and the engine start again, and phones register again.

If anything fails on the way, the restore puts the previous data and database back and starts the phone system again.

What a restore does not change: the server's network settings, host name, firewall, and its own configuration file. If the backup has no recordings, the recordings on the server stay as they are.

A restore is refused when the data, voicemail or recordings folder is a disk of its own (mounted directly at that folder). Moving voicemail and recordings to their own disk under Storage does not do this, so it does not get in the way.

Cleaning up after a restore

The previous data and database stay on the server so you can go back if the restore was the wrong one. Once everything works, remove them: open Server › Storage, and in the Clean up card tick the entries Copy kept by a restore and Database kept by a restore, then select Remove selected. They are not ticked at first, on purpose. The message at the end of the restore names them too.

Restoring onto a new server

To move to new hardware, or to rebuild a server that is lost:

1. Install a new Onyx Voice server (see Installing the server) with the same version as the backup, or newer.
2. Give it the old server's address and host name, if phones, carriers, DNS records and port forwards point at them. Otherwise update those afterwards.
3. On the new server, open Server › Backup and set Where backups go to the same share or disk the old server backed up to. Select Save and test.
4. Select List backups. The old server's backups are listed too.
5. Restore the newest one as described above.

The new server keeps its own network settings and configuration file; everything the phone system knows comes from the backup. The certificate comes back with the data. Phones register again once they reach the server at the address or name they were given.

If you want something from the old server's configuration, such as certificate files you placed in /etc/onyx-voice yourself, it is in the backup's config.tar.gz.

Backups in a cluster

A backup cannot be restored onto a server that is part of a cluster: the restore would replace the cluster's settings, and the page refuses with a message saying so. Restore onto a single server, then add the second server again. See High availability.