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.
Sync database location and structure
Sync 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 that is 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).
-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 that is specified by -N
. To allow the session name to be used as a
directory name, names can use only 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 that
is 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 that is 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: Bidirectional async
# -N ex1 -b /var/db -B /opt/aspera/var -d /data/users -r root@server:/storage/users -K bidi
The command creates the following result:
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 command creates the following result:
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.
-x
or --reset
options delete the existing database, and
Sync must create a new one, which can take a long time if the file system contains many files and
directories.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 so, you can run async
with -x
or --reset
.
This option rebuilds the database, which can take some time for large directories. A Sync session
that is run with --reset
has the following behavior:
- If the private directory (.private-asp) is missing, Sync creates it.
- 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.
- 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.