Documentation

Using as-backup.sh

Everything an administrator needs to back up and restore OpenVPN Access Server with as-backup.sh: installation, daily use, scheduled backups with retention, the full option reference, and what to do when something goes wrong.

Describes the script published on 2026-11-10 (as-backup.sh SHA-256 8300d528…). Run as-backup.sh --help on your host for the options of the copy you have.

On this page
  1. Overview
  2. Install & upgrade
  3. Quick start
  4. Creating backups
  5. Listing backups
  6. Restoring
  7. Scheduled backups
  8. Reference
  9. Requirements
  10. Troubleshooting
Overview

What as-backup.sh does#

as-backup.sh is a single POSIX shell script that takes consistent backups of an OpenVPN Access Server configuration, lists them, and restores any of them by ID. It runs on the Access Server host itself, as root, and needs no daemon or agent: an optional systemd timer or cron job runs it on a schedule.

What a backup contains

  • The seven Access Server databases: config, certs, userprop, log, config_local, cluster and notification. That covers settings, users and their properties, groups, certificates and keys, and the connection log.
  • Each database is exported with the tool its backend needs. The script reads the *_db lines in as.conf: local SQLite databases are dumped with sqlite3, MySQL databases with mysqldump.
  • The configuration file /usr/local/openvpn_as/etc/as.conf.

What it does not contain

Anything outside those databases and as.conf. That includes the files in etc/web-ssl, licence files, and the Access Server package itself. These can be restored or reinstalled separately. To move to another Access Server version, install that package first, then restore.

Where backups are kept

Each backup is one .tar.gz archive in /usr/local/openvpn_as/etc/backup/<year>/. Every backup has an ID: the Unix time, in seconds, at which it was taken. You use that ID to restore it. Archives stay on the server's own disk, so copy them elsewhere if you need off-host copies.

Install & upgrade

Installing as-backup.sh#

Run the installer as root on the Access Server host:

$bash <(curl -fsS https://as-backup.devopenvpn.net/install.sh)

The installer puts the script at /usr/local/bin/as-backup.sh and then asks three questions:

Do you want to schedule regular backups? [Y/n] y
How often? h=hourly d=daily w=weekly (or 1/2/3) [d]: h
Keep how many scheduled backups? (0 = keep all) [14]: 48
systemd timer configured.
Scheduled backups: hourly, keeping the newest 48 (manual backups are never deleted).
Installation complete.

It uses a systemd timer when systemd is available and a file in /etc/cron.d otherwise. If the script, the timer or the cron file already exists, it asks before overwriting it. See Scheduled backups for what the schedule runs.

Verifying the download

The main page publishes the SHA-256 checksums of install.sh and as-backup.sh. To check them before running anything:

$ curl -fsSO https://as-backup.devopenvpn.net/install.sh
$ sha256sum install.sh          # compare with the main page
$ bash install.sh
$ sha256sum /usr/local/bin/as-backup.sh

Installing without questions

For automation (config management, cloud-init, ssh without a terminal), pass the answers as options:

$ bash <(curl -fsS https://as-backup.devopenvpn.net/install.sh) --yes --keep 14
  • --yes answers every question with its default and overwrites existing files without asking.
  • --keep N sets how many scheduled backups to keep; 0 keeps all. Without it, --yes keeps 14.
Note --yes always installs a daily schedule. If the host already had an hourly or weekly schedule, --yes replaces it with daily. To keep another frequency, run the installer interactively.

Checking the schedule

$ systemctl list-timers as-backup.timer
$ cat /etc/systemd/system/as-backup.service    # ExecStart=/usr/local/bin/as-backup.sh --auto --keep 14
$ journalctl -u as-backup.service -n 20         # output of the last scheduled runs
$ cat /etc/cron.d/as-backup                     # on hosts without systemd

systemd: daily runs at midnight and weekly on Monday at midnight. If the host was off at that time, the run happens at the next boot. cron: hourly at minute 0, daily at 02:00, weekly on Sunday at 02:00.

Upgrading

Run the installer again and answer y when it asks to overwrite the script and the timer. Existing backups stay where they are and keep working with the new version.

Upgrading from the first release Scheduled backups taken by the first release have no "scheduled" marker, so the new version treats them as manual backups and never deletes them. Remove the ones you no longer need by hand. On internal Access Server builds (version 3.3.0_internal), the first release also hid its own backups from --list. The new version lists them.

Uninstalling

$ systemctl disable --now as-backup.timer
$ rm -f /etc/systemd/system/as-backup.service /etc/systemd/system/as-backup.timer /etc/cron.d/as-backup
$ systemctl daemon-reload
$ rm -f /usr/local/bin/as-backup.sh

The archives in /usr/local/openvpn_as/etc/backup/ are not removed.

Quick start

Five commands#

  1. Take a backup with a comment before you change anything.
    $ as-backup.sh -c "pre-upgrade"
    Backup created: /usr/local/openvpn_as/etc/backup/2026/v1-1794304800-v3-3-0-cHJlLXVwZ3JhZGU.tar.gz
    Backup ID: 1794304800
  2. List backups to find an ID.
    $ as-backup.sh --list
    ID          DATE (UTC)            AS VERSION  COMMENT
    1794268800  2026-11-10 00:00:00   3.3.0       auto
    1794301200  2026-11-10 09:00:00   3.3.0       baseline
    1794304800  2026-11-10 10:00:00   3.3.0       pre-upgrade
  3. Preview a restore. Nothing changes.
    $ as-backup.sh --restore 1794301200 --dry-run
  4. Restore. Access Server is stopped and started again.
    $ as-backup.sh --restore 1794301200
    Restore backup 1794301200 (AS 3.3.0, "baseline") over the current configuration? [y/N] y
    Pre-restore backup ID: 1794306000
    Restore complete from backup ID: 1794301200 (undo: as-backup.sh -r 1794306000)
  5. Undo it if needed. The restore backed up the state it replaced.
    $ as-backup.sh -r 1794306000
Creating backups

Taking a backup#

Run the script without options for a plain backup, or add a comment that tells you later why it was taken:

$ as-backup.sh
$ as-backup.sh -c "before LDAP change, ticket 1234"
  • Comments can be up to 80 characters. Longer comments are refused, and no backup is taken.
  • The comment auto is reserved for scheduled backups and is refused for manual ones.
  • Access Server keeps running during a backup. A typical backup takes a few seconds; a large log database takes longer.
  • Backups never overwrite each other. If two backups start in the same second, the second one waits for the next second, so every ID is unique.

Using the ID in scripts

With -q the script prints only the new ID:

$ id=$(as-backup.sh -q -c "before maintenance")
$ echo "rollback: as-backup.sh -r $id"
rollback: as-backup.sh -r 1794308400

The command exits with a non-zero status, and prints the reason on stderr, when the backup fails.

Listing backups

Finding a backup#

$ as-backup.sh --list
ID          DATE (UTC)            AS VERSION  COMMENT
1794268800  2026-11-10 00:00:00   3.3.0       auto
1794301200  2026-11-10 09:00:00   3.3.0       baseline
1794304800  2026-11-10 10:00:00   3.3.0       pre-upgrade
1794306000  2026-11-10 10:20:00   3.3.0       pre-restore of 1794301200
  • ID: what you pass to --restore.
  • DATE (UTC): when the backup was taken.
  • AS VERSION: the Access Server version the backup was taken on.
  • COMMENT: your comment, auto for scheduled backups, pre-restore of <ID> for the automatic backup taken before a restore, or - for none.

Narrow the list down:

$ as-backup.sh --list --as-version 3.2.1    # only backups taken on 3.2.1
$ as-backup.sh --list --no-header              # no header row

Output for scripts: --tsv

--list --tsv prints one tab-separated line per backup, without a header. The columns stay the same in future versions:

#ColumnExample
1Backup ID1794304800
2Date, UTC2026-11-10 10:00:00
3AS version3.3.0
4Archive path/usr/local/openvpn_as/etc/backup/2026/v1-1794304800-v3-3-0-cHJlLXVwZ3JhZGU.tar.gz
5Comment (empty when none)pre-upgrade
$ as-backup.sh --list --tsv | awk -F'\t' '$5 == "pre-upgrade" { print $1 }'
1794304800

When there are no backups, --tsv prints nothing and exits with status 0.

Restoring

Restoring a backup#

Restore by ID. Access Server is unavailable for the time it takes to stop, import and start, usually under a minute.

$ as-backup.sh --restore 1794301200

What happens during a restore

  1. The backup is located and unpacked to a temporary directory. If it was taken on a different Access Server version, a warning is printed (see below).
  2. On a terminal, you are asked to confirm (see Confirmation).
  3. A backup of the current state is taken first, with the comment pre-restore of <ID>. If this backup fails, the restore stops and nothing is changed.
  4. The openvpnas service is stopped.
  5. SQLite databases are rebuilt next to the live files and then moved into place. MySQL dumps are imported into their databases.
  6. as.conf is restored, and the database files and as.conf get mode 0600.
  7. openvpnas is started again, and the script prints the command that undoes the restore.

Previewing a restore: --dry-run

Shows what a restore would change, without stopping anything or creating a backup:

$ as-backup.sh -r 1794301200 --dry-run
Dry run: restore of backup 1794301200 (AS 3.3.0, comment: baseline)
  archive: /usr/local/openvpn_as/etc/backup/2026/v1-1794301200-v3-3-0-YmFzZWxpbmU.tar.gz
  current AS version: 3.3.0
  pre-restore backup: would be created ("pre-restore of 1794301200")
  service: openvpnas would be stopped and started
  config: replace (sqlite)
  certs: replace (sqlite)
  userprop: replace (sqlite)
  log: replace (sqlite)
  config_local: replace (sqlite)
  cluster: replace (sqlite)
  notification: replace (sqlite)
  as.conf: replace
No changes made.

For MySQL databases the line shows the target, for example userprop: import (mysql db.example.com:3306/as_userprop). Passwords are never printed.

Confirmation

  • When you run a restore on a terminal, it asks … over the current configuration? [y/N]. Only y or yes continues; anything else prints Restore cancelled and changes nothing.
  • -y / --yes skips the question.
  • When there is no terminal (scripts, cron, ssh host command), nothing is asked and the restore runs, so existing automation keeps working.

Undoing a restore

Every restore ends with the command that brings back the state it replaced:

Pre-restore backup ID: 1794306000
Restore complete from backup ID: 1794301200 (undo: as-backup.sh -r 1794306000)

Pre-restore backups are ordinary manual backups. They show up in --list and are never deleted by as-backup.sh.

Keeping the current connection log: --skip-log

A restore normally also replaces the log database, which holds the connection and event log written since the backup. To keep the current log, for example while investigating an incident:

$ as-backup.sh -r 1794301200 --skip-log
Pre-restore backup ID: 1794306092
log database kept (--skip-log)
Restore complete from backup ID: 1794301200 (undo: as-backup.sh -r 1794306092)

The log database is left untouched, whether it is SQLite or MySQL. The restored as.conf keeps the current log_db line.

MySQL databases

MySQL dumps are imported with the mysql client, using the connection details stored in the backup's own copy of as.conf. The database server must be reachable with those credentials. The password is passed through the environment, never on the command line. On a cluster, the restored databases are shared by every node.

Restoring onto another Access Server version

A backup taken on a different version can be restored. The script warns but does not stop:

Warning: backup version (3.2.1) differs from current AS version (3.3.0)

If the release notes of the versions in between mention database changes, install the version the backup was taken on before you restore it, or check the release notes for the supported path.

If a restore fails half-way If something fails after the databases have been replaced, the script leaves Access Server stopped on purpose and prints restore failed after database promotion -- service NOT restarted. Check the message above it, fix the cause, then either run the same restore again or restore the pre-restore backup it printed. Start the service when the configuration is consistent: systemctl start openvpnas.
Scheduled backups

Schedules and retention#

The schedule set up by the installer runs:

/usr/local/bin/as-backup.sh --auto --keep 14
  • --auto marks the backup as scheduled. It is listed with the comment auto.
  • --keep N runs after a successful scheduled backup and deletes the oldest scheduled backups, so that at most N remain. When the backup fails, nothing is deleted.
  • If another as-backup.sh operation is running, for example a restore, the scheduled run prints …; scheduled backup skipped and exits successfully. Nothing is queued: the next run happens at the next scheduled time.

Manual and scheduled backups

BackupListed commentDeleted by as-backup.sh?
Scheduled (--auto)autoYes, beyond the newest N of --keep N
Manualyour comment, or -Never
Before a restorepre-restore of <ID>Never
Taken by the first release-Never (treated as manual)

To change N or the frequency, run the installer again.

Deleting manual backups

Delete manual backups you no longer need by removing their archive. --tsv gives the path:

$ as-backup.sh --list --tsv | awk -F'\t' '$1 == 1794301200 { print $4 }'
/usr/local/openvpn_as/etc/backup/2026/v1-1794301200-v3-3-0-YmFzZWxpbmU.tar.gz
$ rm /usr/local/openvpn_as/etc/backup/2026/v1-1794301200-v3-3-0-YmFzZWxpbmU.tar.gz
Disk space Access Server also writes its own backups to /usr/local/openvpn_as/etc/backup/, as dated directories, on every package upgrade. as-backup.sh neither lists nor deletes those. Check the total with du -sh /usr/local/openvpn_as/etc/backup.
Reference

Options, variables, exit codes#

Options

OptionUse withWhat it does
(none)–Create a backup.
-c, --comment VALbackupCreate a backup with a comment, up to 80 characters. auto is reserved.
-q, --quietbackupPrint only the new backup ID.
--autobackupScheduled backup: comment auto; skipped (exit 0) if another operation is running.
--keep N--autoAfter the backup, keep only the newest N scheduled backups (N ≥ 1).
-l, --list–List all backups.
--no-header--listLeave out the header row.
--as-version VER--listOnly backups taken on version VER (X.Y.Z).
--tsv--listTab-separated output for scripts (columns).
-r, --restore ID–Restore the backup with this ID.
--dry-run--restoreShow what the restore would change; change nothing.
-y, --yes--restoreDo not ask for confirmation.
--skip-log--restoreKeep the current log database.
-h, --help–Show the built-in help.

Options used without the one they belong to are refused with an error, for example --dry-run requires --restore.

Installer options

OptionWhat it does
--yesNo questions: overwrite existing files, schedule daily backups.
--keep NNumber of scheduled backups to keep; 0 keeps all. Default 14.

Environment variables

For non-standard installations. Set them in the shell, the systemd unit or the cron line.

VariableDefaultPurpose
BACKUP_ROOT/usr/local/openvpn_as/etc/backupWhere archives are stored.
AS_CONF/usr/local/openvpn_as/etc/as.confAccess Server configuration file.
DB_DIR/usr/local/openvpn_as/etc/dbDirectory of the local SQLite databases.
LOCK_FILE/run/as-backup.lockLock that lets only one backup or restore run at a time.

Exit codes

CodeMeaning
0Success. Also returned by a scheduled run that was skipped because another operation was running.
1Error; the reason is printed on stderr. Also returned by a cancelled restore.
4Another backup or restore is running.
130 / 143Interrupted (Ctrl-C / SIGTERM). Temporary files, partial archives and the lock are cleaned up.

Archive name

v1-1794304800-v3-3-0-cHJlLXVwZ3JhZGU.tar.gz
format backup ID AS version comment (base64url, optional)
  • Scheduled backups end in -YXV0bw.tar.gz, the encoded auto.
  • Archives from the first release taken on internal builds have names like …-v3-3-0_internal.tar.gz. They are listed and restored like any other backup.
  • Do not rename archives: the ID, version and comment are read from the name.

Archive contents

FileContent
<db>.db.bakSQL dump of a local SQLite database.
<db>.mysql.sqlmysqldump output of a MySQL database.
as.conf.bakCopy of as.conf.

The archives are ordinary gzip tarballs: tar tzf <archive> lists them, and the dumps are plain SQL.

Requirements

What the host needs#

A Linux Access Server host with systemd or cron. Everything except the MySQL client tools is present on a standard installation.

root
For backup and restore
sacli
On PATH; reports the AS version
tar · gzip · base64
Archives and comments
sqlite3
Local database dumps
mysqldump
Only if a database is on MySQL
mysql
Only to restore MySQL dumps

Not supported: running as-backup.sh on the BACKUP node of a failover pair. Access Server does not run there, so back up the active node instead.

Troubleshooting

Messages and what to do#

Errors are printed on stderr. Click a message for its cause and fix.

Another as-backup operation is running (pid N)

Another backup or restore holds the lock (exit code 4). Wait for it to finish and run your command again. ps -p N shows what it is.

A lock left behind by a process that no longer exists, for example after a crash or kill -9, is cleared automatically by the next run.

Comment exceeds 80 characters

Shorten the comment; no backup was taken.

Comment 'auto' is reserved for scheduled backups

Choose any other comment. auto marks the backups that --keep may delete.

mysqldump not found / mysql not found

A database in as.conf (backup), or in the archive (restore), is on MySQL, and the client tool is missing. Install the MySQL or MariaDB client package and run again.

A restore also needs mysqldump when the current configuration uses MySQL, because it backs up the current state first.

Backup ID not found: ID

No archive in /usr/local/openvpn_as/etc/backup/<year>/ has this ID. Check the ID with --list. IDs are numbers only.

A backup taken while Access Server was not running can have no version in its name; such a backup does not show up in --list. Find it with ls /usr/local/openvpn_as/etc/backup/*/; it still restores by ID.

Warning: backup version (X) differs from current AS version (Y)

The backup was taken on another Access Server version. The restore continues. See Restoring onto another version.

Pre-restore backup failed: restore aborted, nothing changed

The backup of the current state could not be taken, so the restore did not start. The line above it gives the reason, for example a full disk or a missing mysqldump. Access Server was not stopped.

restore failed after database promotion -- service NOT restarted

See If a restore fails half-way. The service is stopped on purpose; fix the cause, then run the restore again or restore the pre-restore backup, and start openvpnas.

Restore complete. openvpnas failed to start

The data was restored, but the service did not come up. Check systemctl status openvpnas and /var/log/openvpnas.log. If the restored configuration is the problem, restore the pre-restore backup.

Restore cancelled

You answered something other than y at the question. Nothing was changed. Use --yes to skip the question.

This operation requires root privileges

Run backup and restore as root, for example with sudo. --list does not need root, as long as the user can read the backup directory.

--dry-run requires --restore (and similar)

The option only works together with the one named in the message. See the options table.

My scheduled backups do not appear

Check that the timer is enabled (systemctl list-timers as-backup.timer) and read the output of the last runs (journalctl -u as-backup.service). A run that printed scheduled backup skipped found another operation running.

Back to top ↑