6. Operations¶

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.

6.2. Backup¶

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¶

6.2.2.1. 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.

6.2.2.2. 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.

6.3. Recovery¶

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:

Warning

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.