The Aspera Sync Database

Each async session creates a database (snap.db) that is stored on both the local (client) computer and the remote (server) computer. The database records the state of the file system at the end of the last async session, and the next time the session is run, the file system is compared to the database to identify changes.

Aspera Sync Database Location and Structure

Aspera Sync creates private directories (.private-asp) to store the database and in-progress transfers (a transfer cache for pending files).

The Aspera Sync database directory is stored on the local computer in the directory specified by the -b option in the command line, and on the remote computer in the directory set for <async_db_dir> in the server's aspera.conf (or set by the client with -B if no value is set on the server).

Note: The Aspera Sync database does not work on CIFS, NFS, or other mounted shared file systems; therefore, -B and -b must specify a directory on a file system physically local to the endpoint host.

Multiple async sessions can synchronize the same directory or specify the same database directory (-b or -B), so for each session async creates a subdirectory in .private-asp that is named with the session name specified by -N. To allow the session name to be used as a directory name, names can only use standard alphanumeric characters and "_" and "-" characters.

Each async session must have a unique name. If multiple sessions synchronize the same directory or specify the same database directory (-b/-B), then the session names must be unique. For example, you run an async session named job1 that synchronizes the local directory /data and the remote directory /data1, and that stores the database in /sync/db on both endpoints. You cannot run another async session named job1 that synchronizes /data with /data2 and that stores the database in /sync/db; you must either run the session with a unique name or store the database in a different location.

Example 1: Bi-directional async  

# -N ex1 -b /var/db -B /opt/aspera/var -d /data/users -r root@server:/storage/users -K bidi

The above command creates the following:

On the local computer (client):

  • /var/db/.private-asp/ex1/snap.db
  • /data/users/.private-asp/ex1 (for transfer cache)

On the remote computer (server):

  • /opt/aspera/var/.private-asp/ex1/snap.db
  • /storage/users/ex1 (for transfer cache)

Example 2: Uni-directional async

# -N ex2 -b /var/db -B /opt/aspera/var -d /data/users -r root@server:/storage/users -K push

The above command creates the following:

On the local computer (client):

/var/db/.private-asp/ex2/snap.db

On the remote computer (server):

/opt/aspera/var/.private-asp/ex2/snap.db

/storage/users/ex2 (for transfer cache)

Changing Synchronization Direction Between Runs of the Same Session

Changing direction between runs of the same session is not supported. async fails with an error message and you must run it with -x (or --reset) or provide a new database directory.

Note: The -x or --reset options delete the existing database, and Aspera Sync must create a new one, which can take a long time if the file system contains many files and directories.

Starting a Aspera Sync Session When a Sync Database is Missing

If the database is missing or corrupted on either endpoint, repeating an async session fails with error messages similar to the following (in these examples, /sync/peer is the remote database directory and the session is named push): 

Failed. Peer error: Local snapshot DB exists but remote snapshot DB /sync/peer/.private-asp/push/snap.db does not exist
Failed. Peer error: file is encrypted or is not a database
Failed. Peer error: Corrupt database /sync/peer/.private-asp/push/snap.db

If this is the case, you can run async with -x or --reset. This option rebuilds the database, which can take some time for very large directories. A Aspera Sync session run with --reset has the following behavior:

  1. If the private directory (.private-asp) is missing, Aspera Sync creates it.
  2. If the database directory (.private-asp/session_name) is missing (and, therefore, the database file snap.db doesn’t exist), Aspera Sync creates snap.db and its directory.
  3. If the database directory does not contain the snap.db file, Aspera Sync creates it.

Deleting a Snapshot Database During Synchronization

Deleting either of the snapshot databases (client or server) that are in use by an active synchronization session results in undefined behavior. To recover, stop async, delete the database on the other side as well, and restart the session.