6.1. aeoncasectl tool¶
Common administration tasks can be performed by using the self-documenting /opt/aeoncase/aeoncasectl tool installed by the appliance.
NAME aeoncasectl - AEoncase appliance management SYNOPSIS aeoncasectl COMMAND ... COMMANDS backup perform online backup cert display the PEM certificate used for the sync connection change-ports change ports the appliance listens at config-disable disable the configurator config-enable enable the configurator config-url display configurator URL gc-pause pause free space recovery (GC) gc-unpause unpause free space recovery (GC) help display help about aeoncasectl and aeoncasectl commands list list installed appliance versions make-test-users create new users for testing purposes pause pause Sync Appliance stop stop Sync Appliance switch switch to another Sync Appliance version unpause unpause Sync Appliance web-pause pause web service web-unpause unpause web service webdav-disable disable WebDAV service webdav-enable enable WebDAV service OPTIONS --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of `auto', `pager', `groff' or `plain'. With `auto', the format is `pager` or `plain' whenever the TERM env var is `dumb' or undefined. --version Show version information.
The system state comprises the following elements:
- configuration in /etc/aeoncase
- databases under /var/lib/aeoncase
- file data under /var/lib/aeoncase/data and /var/lib/aeoncase/writeback
The Sync Appliance can perform online backup of the two first with a minimal (sub-second) pause in the services. Backups are space-efficient: the space required for a system snapshot is typically around a few MBs regardless of the size of the main database. This is made possible by the main DB’s copy-on-write (CoW) mechanism, see Main database.
Online backup is performed by the backup command from the aeoncasectl tool:
NAME aeoncasectl-backup - perform online backup SYNOPSIS aeoncasectl backup [OPTION]... DESCRIPTION Perform an online backup of the Sync Appliance state and configuration. The appliance will experience a short (sub-second) pause as the backup is performed. If the appliance is paused, it will be unpaused while the online backup takes place, and paused again on completion. If the appliance is stopped, no action will be performed; in that case, state can be safely copied manually from /var/lib/aeoncase/ and the configuration from /etc/aeoncase RETURN CODE 0 is returned on succesful backup completion, and the directory holding the backup will be printed to stdout. OPTIONS --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of `auto', `pager', `groff' or `plain'. With `auto', the format is `pager` or `plain' whenever the TERM env var is `dumb' or undefined. -q, --quiet Quiet operation (for use in scripts) --version Show version information.
6.2.1. Backup procedure¶
The data backend is append-only by nature except for the occasional space recovery (garbage collection, GC) performed by an internal service. If file data referenced by a system snapshot is GCed afterwards and the system is restored at a later point, the data will be found missing and system operation will be affected.
Therefore, the proper procedure for a full system backup including file data is the following:
- /opt/aeoncase/aeoncasectl gc-pause
- /opt/aeoncase/aeoncasectl backup
- save the data under /var/lib/aeoncase/data and /var/lib/aeoncase/writeback
- /opt/aeoncase/aeoncasectl gc-unpause
Since the data backend is append-only when GC is paused, step (3) need not be atomic and can be performed trivially using rsync or any similar tool to transfer the data off-site.
Alternatively, a cold (offline) system backup can be performed by shutting down the appliance and copying the data manually as follows:
- /opt/aeoncase/aeoncasectl stop
- back up the data under:
- /etc/aeoncase: configuration
- /var/lib/aeoncase/data: file data (main storage backend)
- /var/lib/aeoncase/writeback: file data (fallback storage backend)
- /var/lib/aeoncase/*.db and /var/lib/aeoncase/db/: databases
- restart the appliance with /opt/aeoncase/aeoncasectl switch
6.2.2. Storage needs¶
184.108.40.206. Auxiliary databases¶
Within the backup directory, the smaller databases (*.db) hold metadata relative to the users, their projects, access permissions, etc., and are comparatively very small. In a deployment with thousands of users and tens of thousands of projects, they will take but a few MBs.
220.127.116.11. Main database¶
The main database with the bulk of the data (the file/revision information, along with most sync info and project snapshots) is contained in db under the backup directory. This data is stored using a Log-Structured Merge-tree which allows efficient transferral to off-site backup:
- the main database is represented using several files numbered as 000001 and so on
- the files are only written to once and never modified
- two backups share most of the files and will differ by a number of files proportional to the amount of change that has happened in between and the logarithm of the total size
Online backups use hardlinks, making snapshots nearly “free” compared to the whole DB size.
Moreover, these properties allow to transfer backups very efficiently using standard tools like rsync, by essentially sending only the changes as opposed to the whole database. Proper use of hardlinks in the destination allows to keep several backups using less space than the sum of each separate backup.
In order to recover from a system snapshot:
- install the Sync Appliance
- stop the appliance with /opt/aeoncase/aeoncasectl stop --force (since the fresh state is to be discarded, it is safe to use --force)
- discard the state corresponding to the new install in /etc/aeoncase and /var/lib/aeoncase
- copy the snapshot data to the appropriate locations:
- the dir structure under config in the backup directory should be placed under /etc/aeoncase/
- the remaining files and directories from the backup directory should be placed under /var/lib/aeoncase
- the storage backend holding all the data should be mounted or the data copied under /var/lib/aeoncase/data
- similarly, the fallback storage backend should be restored under /var/lib/aeoncase/writeback
In step (4), care must be taken to preserve the original permissions, and the owner should be set to the local aeoncase user as follows:
# chown -R aeoncase:aeoncase /etc/aeoncase /var/lib/aeoncase
6.4. Manual appliance version switching¶
The Sync Appliance is updated automatically by the launcher/updater. A few versions are kept to allow manual up/downgrade in case of need using aeoncasectl switch.
The versions available locally can be listed with aeoncasectl list:
# /opt/aeoncase/aeoncasectl list 0.11.0.5228.4190 [R] 0.11.0.5232.4190
The currently chosen appliance version is prepended with [R] when running, or [P] when paused.
Switching to a different version is done as follows:
# /opt/aeoncase/aeoncasectl switch 0.11.0.5228.4190 Stopping appliance 0.11.0.5232.4190 Launching appliance 0.11.0.5228.4190 # /opt/aeoncase/aeoncasectl list [R] 0.11.0.5228.4190 0.11.0.5232.4190
Sync clients will reconnect automatically to the appliance.
6.5. Changing service ports¶
By default, the appliance uses the standard HTTP (80) and HTTPS (443) ports; this can be changed during the initial setup, or at a later point using with aeoncasectl change-ports:
The sync clients connect to the lowest port used for the HTTPS/sync service. If modified, clients that are already linked to the server will not be able to connect to the sync service (future client versions will allow to re-link to the server in such scenarios).
NAME aeoncasectl-change-ports - change ports the appliance listens at SYNOPSIS aeoncasectl change-ports [OPTION]... VERSION HTTP_PORTS HTTPS_PORTS DESCRIPTION Changes the ports the appliance listens at, and sets the default ports used by the updater when upgrading the appliance. If the specified version is running, a safe shutdown will be performed, and the appliance will be restarted with the new configuration. ARGUMENTS HTTP_PORTS (required) ports for HTTP service (comma-separated list) HTTPS_PORTS (required) ports for HTTPS and sync services (comma-separated list) VERSION (required) appliance version OPTIONS --help[=FMT] (default=auto) Show this help in format FMT. The value FMT must be one of `auto', `pager', `groff' or `plain'. With `auto', the format is `pager` or `plain' whenever the TERM env var is `dumb' or undefined. --version Show version information.