Server logging configuration for ascp and ascp4

Server transfer logs are stored in the default location, rotated once they are 10 MB, and log at log level. For ascp transfers, you can configure a different default log directory, log size, number of logs, and logging intensity on the server, and apply these settings globally or to specific users. For Ascp4 transfers, you can configure a default log size (Ascp4 does not support user-specific logging settings). These settings do not affect IBM Aspera Sync logging, which is configured in a different section.

For more information about the logs location, see: Log files. And for more information on how to configure Sync logs see: Configuring Sync endpoints.

If the client specifies a log directory on the server (using -R remote_log_dir) or the location and size of the local log directory (using -L local_log_dir[:size]), then these take precedence over the server settings.

Default versus user-specific settings

You can set the default logging configuration or assign users to different logging classes, which are sets of logging configurations.

Note: Default settings override user-specific settings. To enable user-specific settings, do not set default settings. User settings do not apply to Ascp4 transfers.

Configuration methods

Logging settings are configured by running asconfigurator commands, or by manually editing aspera.conf. To edit aspera.conf, open it with admin privileges from the following location:

C:\Program Files\Aspera\Enterprise Server\etc\aspera.conf

  1. To set default logging values, run the following commands, as required:
    > asconfigurator -x "set_logging_data;directory,logging_directory"
    > asconfigurator -x "set_logging_data;log_size,size_mb"
    > asconfigurator -x "set_logging_data;log_count,count"
    > asconfigurator -x "set_logging_data;level,log_level"
    Object Description
    directory The full path to the logging directory. Applies only to ascp transfers.
    log_size The size of the log file, in MB, at which it is rotated (the oldest information is overwritten by the newest information). Default: 10 MB. Applies to ascp and ascp4 transfers.
    log_count The number of log files to be retained. The default is 10, and the maximum is 250. If a value of zero or a negative number is provided, it is ignored and the default of 10 is used.
    level The logging level. Valid values are log (default value), dbg1, or dbg2. Applies only to ascp transfers.

    These commands modify the <logging> subsection of the <default> section of aspera.conf. You can manually edit the file as well:

    ...
    <default>
        <file_system>...</file_system>
        <logging>
            <directory>logging_directory</directory>
            <log_size>size_mb</log_size>
            <log_count>count</log_count>
            <level>log_level</level>
        </logging>
    </default>
    ...
  2. To set user logging values, create logging classes (each with a specific logging configuration) and then assign users to classes.
    1. Create a logging class:
      > asconfigurator -x "set_log_setting_data;classes,class_name;directory,logging_directory;log_size,size_mb;level,log_level"
      Object Description
      classes The name of the class. This is the value that you use to assign users to this class of logging settings.
      directory The full path to the logging directory. Applies only to ascp transfers.
      log_size The size of the log file, in MB, at which it is rotated (the oldest information is overwritten by the newest information). Default: 10 MB. Applies to ascp and ascp4 transfers.
      level The logging level. Valid values are log (default value), dbg1, or dbg2. Applies only to ascp transfers.
    2. Assign a user to the logging class:
      > asconfigurator -x "set_user_data;user_name,username;logging_class,class_name"

    For example, the following commands create two logging classes, admin and home. The home logging class uses the substitution string $(home) to log to the user's home directory, ensuring that the transfer users have access to the log files for their transfers. They assign user root to the admin logging configuration, and users user1 and user2 to the home logging configuration.

    > asconfigurator -x "set_log_setting_data;classes,admin;directory,/root/logs;log_size,3;level,dbg"
    > asconfigurator -x "set_log_setting_data;classes,home;directory,$(home)/logs;log_size,20;level,dbg1"
    > asconfigurator -x "set_user_data;user_name,root;logging_class,admin"
    > asconfigurator -x "set_user_data;user_name,user1;logging_class,home"
    Tip: You can adjust the level of detail for the log. Selecting dbg1 provides a less detailed log, while choosing dbg2 generates a log with more in-depth information.

    This creates the following result in aspera.conf:

    ...
    <logging>
        <log_setting>
            <classes>admin</classes>
            <directory>/root/logs</directory>
            <log_size>3</log_size>
            <level>dbg1</level>
        </log_setting>
        <log_setting>
            <classes>home</classes>
            <directory>$(home)/logs</directory>
            <log_size>20</log_size>
            <level>log</level>
        </log_setting>
    </logging>
    <aaa><realms><realm>
        <users>
            <user>
               <name>root</name>
               <logging_class>admin</logging_class>
               <file_system>...</file_system>
            </user>
            <user>
               <name>user1</name>
               <logging_class>home</logging_class>
               <file_system>...</file_system>
            </user>
            <user>
               <name>user2</name>
               <logging_class>home</logging_class>
               <file_system>...</file_system>
            </user>
        </users></realm></realms>
    </aaa>
    ...
  3. If you manually edited aspera.conf, save your changes.
  4. If you manually edited aspera.conf, validate the XML form of aspera.conf:
    > asuserdata -v