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.

       aeoncasectl - AEoncase appliance management

       aeoncasectl COMMAND ...

           perform online backup

           display the PEM certificate used for the sync connection

           change ports the appliance listens at

           disable the configurator

           enable the configurator

           display configurator URL

           pause free space recovery (GC)

           unpause free space recovery (GC)

           display help about aeoncasectl and aeoncasectl commands

           list installed appliance versions

           create new users for testing purposes

           pause Sync Appliance

           stop Sync Appliance

           switch to another Sync Appliance version

           unpause Sync Appliance

           pause web service

           unpause web service

           disable WebDAV service

           enable WebDAV service

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

           Show version information.

6.2. Backup

The system state comprises the following elements:

  1. configuration in /etc/aeoncase
  2. databases under /var/lib/aeoncase
  3. 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:

       aeoncasectl-backup - perform online backup

       aeoncasectl backup [OPTION]... 

       Perform an online backup of the Sync Appliance state and

       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 


       and the configuration from 


       0 is returned on succesful backup completion, and the directory
       holding the backup will be printed to stdout.

       --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)

           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:

  1. /opt/aeoncase/aeoncasectl gc-pause
  2. /opt/aeoncase/aeoncasectl backup
  3. save the data under /var/lib/aeoncase/data and /var/lib/aeoncase/writeback
  4. /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:

  1. /opt/aeoncase/aeoncasectl stop
  2. 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
  3. restart the appliance with /opt/aeoncase/aeoncasectl switch

6.2.2. Storage needs 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. 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:

  1. install the Sync Appliance
  2. stop the appliance with /opt/aeoncase/aeoncasectl stop --force (since the fresh state is to be discarded, it is safe to use --force)
  3. discard the state corresponding to the new install in /etc/aeoncase and /var/lib/aeoncase
  4. 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

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
Stopping appliance
Launching appliance

# /opt/aeoncase/aeoncasectl list

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

       aeoncasectl-change-ports - change ports the appliance listens at

       aeoncasectl change-ports [OPTION]... VERSION HTTP_PORTS HTTPS_PORTS

       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

       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

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

           Show version information.