An Enterprise Server Workspace can hold a broad range of valuable data, including defined users, groups, LDAP Sync tasks, design data (including projects, components, models, templates), and configurations for PLS and NIS services (and typically a range of acquired products and extensions, and defined deployment packages for the latter). A key requirement of ensuring the long-term integrity of this data, is backing it up. The standard Enterprise Server installation includes a backup and restore tool, accessed via a command prompt.
The default location of the backup tool is in the folder \Program Files (x86)\Altium\Altium365\Tools\BackupTool.
The name of the backup tool is avbackup.exe.
-
If the avbackup.exe tool is not located in the default path – \Program Files (x86)\Altium\Altium365\Tools\BackupTool – errors/exceptions may be encountered during a restoration.
-
The standalone Health Monitor tool (avhealth.exe) must be closed when using the Backup Tool (in either backup or restore mode), since both tools require access to the Enterprise Server's database file.
-
It is highly recommended that users are not connected to and using the Workspace during the backup and restore processes, which require access to the Workspace’s database. As a Workspace administrator, you can forcibly log out users if necessary by dropping their current Workspace session through the Sessions page of the browser interface (Admin – Sessions). See the Sessions page for more information.
-
Restoring a backup is only possible to the same version of Enterprise Server from which that backup was made. In this respect, it can be a good idea to keep the installer for that Enterprise Server, and corresponding license files, with the backup Zip archive.
The backup tool uses the Volume Shadow Copy Service (VSS) to make a shadow copy of the volume where the server data is located (a configuration when revisions are stored on a separate volume is also supported). With the VSS, the backup tool stops services, creates a shadow copy, starts services, and then performs data backup using the created shadow copy. This approach minimizes the server downtime period (a period between stopping and starting the services) and is used by default. In case of an error during creating a shadow copy, the backup tool will use an approach without creating a shadow copy (which can also be enabled explicitly using the --skip-shadow-copy switch).
Accessing the Backup Tool
To use the tool:
-
Launch a Windows Command Prompt.
You must run the Command Prompt in administrator mode to be able to use the Backup and Restore tool. If you are not running a CMD prompt as a Windows Administrator, attempting to execute a command in respect of backing up, or restoring your Enterprise Server, will result in the clear message: Access Denied. Administrator permissions are needed to use the selected options. Use an administrator command prompt to complete these tasks.
-
Navigate to the correct folder. For a default installation on the C drive of the host computer, this will be: cd C:\Program Files (x86)\Altium\Altium365\Tools\BackupTool\
-
To run the tool and list the available options, at the prompt type: avbackup ?
On some versions of Windows, it is not possible to paste into a Command Prompt using Ctrl+V, but you can paste via the right-click menu. Copy the required strings first, then paste using this technique to save time and avoid mistakes.
Accessing the backup tool through a Command Prompt (run as administrator).
Note the ?, including this displays help on the functions available in the backup tool:
-
backup – backup data to ZIP archive.
-
restore – restore data from ZIP archive. The Restore Point will be automatically created.
-
help – display the help screen (? can be used instead of the string help).
Contents of the Zip Archive
The tool backs up the entire Enterprise Server and user data, including:
-
Full database backup, including: all data Items (models, components, managed sheets, templates, released designs, etc.), users, groups, installations acquired via the Network Installation Service, and LDAP Sync settings.
-
All revisions of above.
-
Repositories and included Workspace designs.
-
Search index.
-
User-defined (custom) settings.
Backup Syntax and Switches
The following switches are available when using the backup function of the tool:
avbackup backup -z [-t] [-h] [-i] [-m] [-d] [-c] [--split] [--skip-shadow-copy]
-
-z – path and filename of the target zip file that is to be created. Enclose in quotes if there are spaces in the string. This switch is required.
-
-t, --test – if this switch is specified, the zip file will be tested after backup.
-
-h, --hash – if this switch is specified, an MD5 hash file (*.md5) will be created.
-
-i – full path to the Enterprise Server's LocalVault.ini file, which provides data location information for the Enterprise Server to be backed up. The default path of this file is C:\Program Files (x86)\Altium\Altium365\LocalVault.ini. If this switch is not specified, the tool will attempt to find the file automatically based on this default installation location. Enclose in quotes if there are spaces in the string.
-
-m – allows you to determine whether the backup operation should run silently (-m silent, which is the default mode), or if a dialog should pop up asking to retry in the event of failure (-m dialog). If this switch is not specified, silent mode will be used.
-
-d, --debug – if this switch is specified, debug mode will be used, which will enable more logs to be created for diagnostic purposes and for sharing with Altium Engineers.
-
-c – allows you to specify the compression level of the target zip file. Use a number from 0 to 9. You can also use the following values:
-
Default – equals to the compression level 6 (used if this switch is not specified)
-
None – equals to the compression level 0
-
BestSpeed – equals to the compression level 1
-
BestCompression – equals to the compression level 9.
-
--split – if this switch is specified, separate zip files will be created for repositories and revisions (without compression), in addition to the zip file for the other data.
-
--skip-shadow-copy – if this switch is specified, a shadow copy will not be created. Note that the server downtime (a period between stopping and starting the services) increases when this switch is used.
By typing just avbackup backup, these switches will be listed as a helpful aid.
Switches available when using the tool in backup mode.
Backup Example
The following entry will silently back up the Enterprise Server into the file named 02102024_Backup.zip, writing the file to the folder C:\Backups\Altium Enterprise Server\:
avbackup backup -z "C:\Backups\Altium Enterprise Server\02102024_Backup.zip" -i "C:\Program Files (x86)\Altium\Altium365\LocalVault.ini"
Any folders specified must already exist. Also, existing files are overwritten if the new file has the same name as an existing file.
The result of running the example backup command.
Restore Syntax and Switches
The following switches are available when using the restore function of the tool:
avbackup restore -z [--skip-backup] [-i] [-m] [-d] [-c] [--split] [--skip-shadow-copy]
-
-z – path and filename of the backup zip file from which to restore. Enclose in quotes if there are spaces in the string. This switch is required.
-
--skip-backup – allows you to skip creating a restore point before commencing to restore the Enterprise Server. Use it carefully since if data restore fails, it will not be possible to roll back.
-
-i – full path to the Enterprise Server's LocalVault.ini file, which provides information on the locations in which to restore the Enterprise Server data. The default path of this file is C:\Program Files (x86)\Altium\Altium365\LocalVault.ini. If this switch is not specified, the tool will attempt to find the file automatically based on this default installation location. Enclose in quotes if there are spaces in the string.
-
-m – allows you to determine whether the restore operation should run silently (-m silent, which is the default mode), or if a dialog should pop up asking to retry in the event of failure (-m dialog). If this switch is not specified, silent mode will be used.
-
-d, --debug – if this switch is specified, debug mode will be used, which will enable more logs to be created for diagnostic purposes and for sharing with Altium Engineers.
-
-c – allows you to specify the compression level of the target zip file for the restore point (a backup of the current Enterprise Server installation). Use a number from 0 to 9. You can also use the following values:
-
Default – equals to the compression level 6 (used if this switch is not specified)
-
None – equals to the compression level 0
-
BestSpeed – equals to the compression level 1
-
BestCompression – equals to the compression level 9.
-
--split – if this switch is specified, separate zip files will be created for repositories and revisions (without compression), in addition to the zip file for the other data, for the restore point (a backup of the current Enterprise Server installation).
-
--skip-shadow-copy – if this switch is specified, a shadow copy will not be created for the restore point (a backup of the current Enterprise Server installation). Note that the server downtime (a period between stopping and starting the services) increases when this switch is used.
By typing just avbackup restore, these switches will be listed as a helpful aid.
Switches available when using the tool in restore mode.
If an *.md5 hash file exists for the backup zip file from which to restore (the *.md5 file is in the same folder as the zip file and is named after the zip file, i.e. <ZipFileName>.zip.md5), its hash will be checked before the restore.
Restore Example
The following entry will silently restore the Enterprise Server using the backup zip file named 30082022_Backup.zip, which is stored in the folder C:\Backups\Altium Enterprise Server\:
avbackup restore -z "C:\Backups\Altium Enterprise Server\30082022_Backup.zip" -i "C:\Program Files (x86)\Altium\Altium365\LocalVault.ini"
The result of running the example restore command. Notice that the tool creates a restore point first (a backup of the current Enterprise Server installation), before performing the restore.
Restore Point
The backup tool automatically creates a restore point before commencing to restore the Enterprise Server (if --skip-backup has not been used for restore). To do this, the backup tool performs a backup on the existing Enterprise Server, and copies the restore ZIP into the following location:
C:\Program Files (x86)\Altium\Altium365\Tools\BackupTool\Backups\
The ZIP is named in the format: Backup_<Date>_<Time>.zip.
Errors During Backup or Restore
Errors that occur during a backup or restore are presented directly within the CMD window, along with full path information to the error log:
C:\Program Files (x86)\Altium\Altium365\Tools\BackupTool\errors.log
When backing up or restoring your Enterprise Server, details of any errors, as well as full path to the errors.log file, are presented directly in the CMD window.
