The 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. async creates private directories (~private-asp) to store the database and in-progress transfers (a transfer cache for pending files).

The 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). The Sync database does not work on CIFS, NFS, or other shared file systems mounted on Linux; therefore, -B and -b must specify a directory on a file system physically local to the endpoint host.

The transfer cache is stored in a ~private-asp in the synchronized directory.

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 c:/db -B d:/aspera/var -d c:/data/users -r admin@server:d:/storage/users -K bidi 

The above command creates the following:

On the local computer (client):

On the remote computer (server):

Example 2: Uni-directional async

> -N ex2 -b c:/db -B d:/aspera/var -d c:/data/users -r admin@server:d:/storage/users -K push

The above command creates the following:

On the local computer (client):

c:/db/~private-asp/ex2/snap.db

On the remote computer (server):

d:/aspera/var/~private-asp/ex2/snap.db

d:/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.

Starting a 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 Sync session run with --reset has the following behavior:

  1. If the private directory (~private-asp) is missing, Sync creates it.
  2. If the database directory (~private-asp\session_name) is missing (and, therefore, the database file snap.db doesn’t exist), Sync creates snap.db and its directory.
  3. If the database directory does not contain the snap.db file, 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.