Configuring the Sync Server

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

If Sync is installed on an Aspera transfer server, Aspera recommends setting the following configuration options for each user 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 Sync with AWS S3.
  1. Set the location for the Sync log.

    By default, Sync events are logged to the Aspera log (see Logging). Aspera recommends setting the log to a directory within the transfer user's home folder. For example:

    > asconfigurator -x "set_user_data;user_name,username;async_log_dir,log_dir"

    This setting overrides the remote logging directory specified by the client with the -R option.

  2. Set the location for the Sync database.

    Sync uses a database to track file system changes between runs of the same session (see The Sync Database). The Sync database should not be located on CIFS, NFS, or other shared file systems mounted on Linux, unless you are synchronizing through IBM Aspera FASP Proxy. If server data are stored on a mount, specify a local location for the Sync database. Aspera recommends setting the log to a directory within the user's home folder by using the same approach as setting the local Sync log:

    > asconfigurator -x "set_user_data;user_name,username;async_db_dir,log_dir"

    This setting overrides the remote database directory specified by the client with the -B option.

Configuring Other Settings

To configure 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):

> asconfigurator -x "set_node_data;option,value"
> 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:

C:\Program Files (x86)\Aspera\Point-to-Point\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:

> 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. On Windows, the options are undefined or win32.

storage_style: Specify where 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 synced.
  • 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 synced 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 disable, 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 Mac OS X 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 synced 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>