Configuring Aspera Sync Endpoints

Aspera Sync reads configuration settings from aspera.conf, which can be edited using asconfigurator commands or manually. The following sections provide instructions for setting Aspera-recommended security configuration, instructions for how to edit other configurations, a reference for many of the available configuration options, and a sample aspera.conf.

Aspera-Recommended Configuration

Aspera recommends setting the following configuration options for greatest security. Additional settings are described in the following table.

Note: To synchronize with AWS S3 storage, you must configure specific locations for the log and database directories. For more information, see Synchronizing with AWS S3 Storage.

Set the location for the Aspera Sync log for each transfer user.
By default, Aspera Sync events are logged to the system log (see Logging). Aspera recommends setting the log to a directory within the transfer user's home folder.

Log location, size, and log level can be configured for both ascp and async by setting default or user-specific configurations in aspera.conf. For instructions, see Server Logging Configuration for Ascp and Ascp 4.

To set a logging directory for async that is separate from ascp, you can set async_log_dir. For example:
```
# /opt/aspera/bin/asconfigurator -x "set_user_data;user_name,username;async_log_dir,log_dir"
```
Note: If async_log_dir is not set, then the logging configuration for ascp is applied. The client can override the server logging settings with the -R option.
Set the location for the Aspera Sync database for each transfer user.
Aspera Sync uses a database to track file system changes between runs of the same session (see The Aspera Sync Database). The Aspera Sync database should not be located on CIFS, NFS, or other shared file systems mounted on Linux, unless you are synchronizing through IBM Aspera Proxy. If server data are stored on a mount, specify a local location for the Aspera Sync database. Aspera recommends setting the database location to a directory within the user's home folder by using the same approach as setting the local Aspera Sync log:
```
# /opt/aspera/bin/asconfigurator -x "set_user_data;user_name,username;async_db_dir,db_dir"
```
This setting overrides the remote database directory specified by the client with the -B option.

Note: If the transfer user's docroot is a URL (such as file:////*), then async_db_dir must be set in aspera.conf. For an example, see Synchronizing with AWS S3 Storage.
If the Aspera Sync source files are on a NFS or CIFS mount, create a mount signature file.
Aspera Sync can use a mount signature file to recognize that the source is on a mount. If you do not use the mount signature file and the NFS or CIFS mount is unreachable, Aspera Sync considers those files as deleted and delete them from the other endpoint.

To create a mount signature file, create the file in the parent directory of the source directory on the mount. For example, if the Aspera Sync directory is /mnt/sync/data, create the mount signature file /mnt/sync/mount_signature.txt by running the following command:
```
# echo mount >> /mnt/sync/mount_signature.txt
```
When you run a Aspera Sync session, use --local-mount-signature=mount_signature.txt if the local source is on a mount and --remote-mount-signature=mount_signature.txt if the remote source is on a mount. For bidirectional Aspera Sync sessions between mounts, use both.

Configuring Other Settings

To configure Aspera Sync settings in aspera.conf by using asconfigurator commands, use the following general syntax for setting default values (first line) or user-specific values (second line):

# /opt/aspera/bin/asconfigurator -x "set_node_data;option,value"
# /opt/aspera/bin/asconfigurator -x "set_user_data;user_name,username;option,value"

To manually edit aspera.conf, open it in a text editor with administrative privileges from the following location:

/opt/aspera/etc/aspera.conf

See an example aspera.conf following the settings reference table. For an example of the asperawatchd configuration, see Watch Service Configuration.

After manually editing aspera.conf, validate that its XML syntax is correct by running the following command:

# /opt/aspera/bin/asuserdata -v

This command does not check if the settings are valid.

Sync Configuration Options

asconfigurator option aspera.conf setting	Description and Value Options
async_connection_timeout <async_connection_timeout>	The number of seconds `async` waits for a connection to be established before it terminates. Value is a positive integer. (Default: 20) If synchronization fails and returns connection timeout errors, which could be due to issues such as under-resourced computers, slow storage, or network problems, set the value higher, from 120 (2 minutes) to even 600 (10 minutes).
async_db_dir <async_db_dir>	Specify an alternative location for the async server's snap database files. If unspecified, log files are saved in the default location or the location that is specified by the client with the -B option.
async_db_spec <async_db_spec>	Value has the syntax `sqlite:lock_style:storage_style`. (Default: undefined) `lock_style`: Specify how async interfaces with the operating system. Values depend on operating system. Unix-based systems have the following options: empty or `unix`: The default method that is used by most applications. `unix-flock`: For file systems that do not support POSIX locking style. `unix-dotfile`: For file systems that do not support POSIX nor flock-locking styles. `unix-none`: No database-locking mechanism is used. Allowing a single database to be accessed by multiple clients is not safe with this option. `storage_style`: Specify where Aspera Sync stores a local database that traces each directory and file. Three values can be used: undefined or `disk`: The default option. Read and write the database to disk. This provides maximum reliability and no limitations on the number of files that can be synchronized. `lms`: The database is loaded from disk into memory at startup, changes during the session are saved to memory, and the database is saved to disk on exit. This option increases speed but all changes are lost if async stops abruptly, and the number of synchronized files is limited by available memory. `memory`: The database is stored completely in memory. This method provides maximum speed but is not reliable because the database is not backed up to disk.
async_enabled <async_enabled>	Enable (set to `true`, default) or disable (set to `false`) Sync. When set to `false`, the client `async` session fails with the error `"Operation 'sync' not enabled or not permitted by license"`.
async_log_dir <async_log_dir>	Specify an alternative location for the async server's log files. If unspecified, log files are saved in the default location or the location that is specified by the client with the -R option. For information on the default log file location, see Logging.
async_log_level <async_log_level>	Set the amount of detail in the async server activity log. Valid values are `log` (default), `dbg1`, or `dbg2`.
async_session_timeout <async_session_timeout>	The number of seconds `async` waits for a non-responsive session to resume before it terminates. Value is a positive integer. (Default: 20)
directory_create_mode <directory_create_mode>	Specify the directory creation mode (permissions). If specified, create directories with these permissions irrespective of `<directory_create_grant_mask>` and permissions of the directory on the source computer. This option is applied only when the server is a Unix-based receiver. Value is a positive integer (octal). (Default: undefined)
directory_create_grant_mask <directory_create_grant_mask>	Specify the mode for newly created directories if `directory_create_mode` is not specified. If specified, directory modes are set to their original modes plus the grant mask values. This option is applied only when the server is a Unix-based receiver and when `directory_create_mode` is not specified. Value is a positive integer (octal). (Default: 755)
preserve_acls preserve_xattrs <preserve_acls> <preserve_xattrs>	Specify if the ACL access data (`acls`) or extended attributes (`xattrs`) from Windows or macOS files are preserved. Three modes are supported. (Default: `none`) `native`: `acls` or `xattrs` are preserved by using the native capabilities of the file system. If the destination does not support `acls` or `xattrs`, async generates an error and exits. `metafile`: `acls` or `xattrs` are preserved in a separate file. The file is in the same location and has same name, but has the added extension .aspera-meta. The .aspera-meta files are platform-independent, and files can be reverted to native form if they are synchronized with a compatible system. `none`: No `acls` or `xattrs` data is preserved. This mode is supported on all file systems. ACL preservation is only meaningful if both hosts are in the same domain. If a SID (security ID) in a source file does not exist at a destination, the sync proceeds but no ACL data is saved and the log records that the ACL was not applied. The aspera.conf settings for `acls` or `xattrs` can be overwritten by using the `--preserve-acls` or `--preserve-xattrs` options, respectively, in a command-line async session.

Example Sync Configuration in aspera.conf

<file_system>
   ...	
   <directory_create_mode> </directory_create_mode> 
   <directory_create_grant_mask>755</directory_create_grant_mask>
   <preserve_acls>none</preserve_acls> 
   <preserve_xattrs>none</preserve_xattrs> 
   ...  
</file_system>
   ...
<default>
   ...
   <async_db_dir>  </async_db_dir>
   <async_db_spec>  </async_db_spec>
   <async_enabled>true</async_enabled>
   <async_connection_timeout>20</async_connection_timeout> 
   <async_session_timeout>20</async_session_timeout> 
   <async_log_dir>AS_NULL</async_log_dir> 
   <async_log_level>log</async_log_level>
   ...
</default>