Adding and editing connections

To transfer with HSTS, HSTE, IBM Aspera Shares, IBM Aspera on Cloud transfer service (AoC), add it as a connection in the Connection Manager. The following instructions describe how to create and configure a connection and edit or delete connections.

To connect with cloud storage, you must meet the following prerequisites:

  • You have permissions to access the cloud storage and the necessary authentication information.
  • To transfer files with an S3 storage device that uses a S3 direct connection, the user must have a restriction rather than a docroot set on the server.

Once you create connections, you can export and import connection lists. For instructions, see Exporting and importing connections.

To create a new connection:

  1. Start the application.
    Go to Finder > Applications > IBM Aspera High-Speed Transfer Endpoint.
  2. To open the Connection Manager, click Connections.
    Bring up the Connection Manager.
  3. Click Add connections to create a new connection.
    Connection manager

    Click Duplicate connections to duplicate a selected connection (to copy all information into a new profile) and Remove connections to delete a connection profile.

  4. Configure the connection name.
    By default, connections are named username@host.

    To name or rename a connection, click the connection name and enter the new name in the window. Click OK to save your changes.

    Configure connection name
  5. Configure the required settings for the connection.
    On the Connection tab, enter the following information. In most cases, only Host, User, and Authentication are required.
    Connection Option Description
    Host The server's address, such as 192.168.1.10 or companyname.com. For Shares, Node API, or AoC connections, enter the URL and port for asperanoded, such as https://ats-aws-us-west-2.aspera.io:9092.
    User The transfer user's username, the Shares user, Node API credentials, or an access key ID.
    Authentication The authentication method. Select Password to authenticate with the transfer user's password, the Shares user's password, the Node API user password, or an access key secret (such as for AoCts or ATC Manager).

    Select Public Key to authenticate with the transfer user's public SSH key. For more information, see Creating SSH Keys in the GUI.

    Storage The default option is local storage. Use this option to connect to:
    • On-premises servers.
    • AoC.
    • Cloud-based servers when the transfer user has the storage credentials that are configured in their docroot on the server.

    When the server is in the cloud but the storage credentials are not configured in the transfer user's docroot, use the drop-down menu to select the object storage type and enter the credentials.

    Supported object storage includes the following types:

    • Akamai NetStorage
    • Amazon S3: Requires your Access ID, Secret Access Key, and bucket path. The local machine must be reasonably time synchronized to communicate with the Amazon servers. You can also click Advanced to modify the following settings:
      • Host: Amazon S3 hostname. The default is s3.amazonaws.com.
      • Port: Default is port 443.
      • HTTPS connection for file browsing: Enable for secure browsing.
      • Server-side file encryption: Enable for AES256 encryption.
      • Reduced redundancy storage class: Assign objects to the reduced redundancy storage class (durability of 99.99%).
    • Google Storage: Requires your project number and bucket path.
    • Limelight: Requires your account, username, and password.
    • Windows Azure: Requires your storage account and access key.

      Azure storage is set to use the Azure block blob REST API by default. To specify the REST API for page blobs, enter your account credentials then click Advanced. Select PAGE from the drop-down menu next to Api and click OK.

    • Windows Azure SAS: Requires your shared URL.
    • Azure Files: Requires your file service endpoint and password.
  6. Configure other connection settings, if needed.
    On the Connection tab, configure nondefault connection settings by editing any of the following settings:
    Connection Option Description
    Target Directory (or Bucket Path for most object storage) The default directory when connecting to this computer. When left blank, browsing the remote host brings up either the user's docroot or the last visited folder. When a path is set, the connection opens to the exact directory.
    Advanced Connection Settings > SSH Port (TCP) The TCP port for SSH connections. Default: 33001. If the application cannot connect on 33001, it automatically attempts a connection on port 22. If the connection on 22 succeeds, the setting is updated to 22.
    Advanced Connection Settings > FASP Port (UDP) The UDP port for FASP transfers. Default: 33001.
    Advanced Connection Settings > Connection Timeout Time out the connection attempt after the specified time.
    Test Connection Click to test the connection to the remote server with the settings you configured.
  7. Configure the connection's transfer settings, if needed.
    On the Transfer tab, configure nondefault transfer settings by editing any of the following settings:
    Transfer option Description
    Transfer Name Select from the following options:
    • Automatically generate: Allows the user interface to generate the transfer name.
    • Automatically generate and add prefix: Uses auto-generated name with a customizable prefix.
    • Specify: Uses the user-specified name.
    Policy Select the FASP transfer policy.
    • high - Adjust the transfer rate to fully use the available bandwidth up to the maximum rate. When congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy requires maximum (target) and minimum transfer rates.
    • fair - Adjust the transfer rate to fully use the available bandwidth up to the maximum rate. When congestion occurs, bandwidth is shared fairly by transferring at an even rate. The fair policy requires maximum (target) and minimum transfer rates.
    • low - Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to fair mode, but less aggressive when the bandwidth is shared with other network traffic. When congestion occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
    • fixed - Attempt to transfer at the specified target rate, regardless of network or storage capacity. This can decrease transfer performance and cause problems on the target storage. Use the fixed policy only for specific contexts, such as bandwidth testing, otherwise, avoid the use of this policy. The fixed policy requires a maximum target rate.
    • aggressiveness - The aggressiveness of transfers that are authorized by this access key in claiming available bandwidth. Value can be 0.00-1.00. For example, these values correspond to the policy option where a policy of high approximates to aggressiveness of 0.75, fair to 0.50 and low to 0.25. Aggressiveness can be used if you need to fine-tune the transfer policy.
    Speed Select Override default transfer rate settings to specify the transfer rate. The target rate is constrained by the global bandwidth settings. For more information, see Global bandwidth settings.
    Retry Select to automatically retry the transfer after a recoverable failure for a set amount of time, in seconds, minutes, or hours. You might set the initial and maximum retry intervals by clicking More Options.
    • Initial interval: The first retry waits for the initial interval. Input in seconds, minutes, or hours.
    • Maximum interval: After the initial interval, the next interval doubles until the maximum interval is met, and then stops retrying after the retry time is reached. Input in seconds, minutes, or hours.

    For example, if the retry is set for 180 seconds, the initial interval is 10 seconds, and the maximum interval is 60 seconds, then the transfer will retry at 10, 30, 70, 130, and 180 seconds after the first try, such that the interval progression is 10, 20, 40, 60, 60, and 50 seconds. The last interval is not the maximum because the retry period ends with a final retry.

    As another example, if the retry is set for 600 seconds, the initial interval is 30 seconds, and the maximum interval is 120 seconds, then the transfer will retry at 30, 90, 210, 330, 450, 570, and 600 seconds after the first try, such that the interval progression is 30, 60, 120, 120, 120, 120, and 30 seconds. Again, the last interval is not the maximum because the retry period ends with a final retry.

    Show Advanced Settings Click Show Advanced Settings to edit the following options:
    • Specify FASP datagram size (MTU): By default, the detected path MTU is used. Select to specify a value 296 - 10000 bytes.
    • Disable calculation of source files size before transferring: Select to turn off job size calculation on the client side, if allowed by the server.
  8. Configure tracking and email notifications.
    On the Tracking Tab, configure nondefault transfer settings by editing any of the following settings:
    Tracking option Description
    Generate delivery confirmation receipt Select to create a delivery receipt file in the specified location.
    Send email notifications Send email notifications based on specified events (start, complete, and error). See Using transfer notifications for more information.
  9. Configure filters to automatically exclude certain files from transfers with this connection, if needed.
    On the Filters tab, click Add and enter the pattern to exclude files or directories with the specified pattern in the transfer. The exclude pattern is compared with the whole path, not just the file name or directory name. Two special symbols can be used in the setting of patterns:
    Filter Symbol Name Description
    * Asterisk Represents zero to many characters in a string, for example *.tmp matches .tmp and abcde.tmp.
    ? Question mark Represents one character, for example t?p matches tmp but not temp.

    For more information on filter rule syntax, see Using filters to include and exclude files.

  10. Configure security settings, if needed.
    On the Security tab, configure nondefault transfer settings by editing any of the following settings:
    Security option Description
    Encryption
    Select the encryption cipher. Aspera supports three sizes of AES cipher keys (128, 192, and 256 bits) and supports two encryption modes, Cipher Feedback mode (CFB) and Galois Counter Mode (GCM). The GCM mode encrypts data faster and increases transfer speeds compared to the CFB mode, but the server must support and permit it.

    Cipher rules

    The encryption cipher that you are allowed to use depends on the server configuration and the version of the client and server:

    • When you request a cipher key that is shorter than the cipher key that is configured on the server, the transfer is automatically upgraded to the server configuration. For example, when the server setting is AES-192 and you request AES-128, the server enforces AES-192.
    • When the server requires GCM, you must use GCM or the transfer fails.
    • When you request GCM and the server is older than 3.8.1 or explicitly requires CFB, the transfer fails.
    • When the server setting is any, you can use any encryption cipher. The only exception is when the server is 3.8.1 or older and does not support GCM mode; in this case, you cannot request GCM mode encryption.
    • When the server setting is none, you must use none. Transfer requests that specify an encryption cipher are refused by the server.

    Cipher Values

    Value Description Support
    AES-128
    AES-192
    AES-256
    Use the GCM or CFB encryption mode, depending on the server configuration and version (see cipher negotiation matrix). All client and server versions.
    AES-128-CFB
    AES-192-CFB
    AES-256-CFB
    Use the CFB encryption mode. Client, all server versions.
    AES-128-GCM
    AES-192-GCM
    AES-256-GCM
    Use the GCM encryption mode. Client, all server versions.
    NONE Do not encrypt data in transit. Using this setting, might affect the security and the file integrity. All client and server versions.

    Client/Server Cipher negotiation

    The following table shows which encryption mode is used depending on the server and client versions and settings:

      Server

    AES-XXX-GCM

    Server

    AES-XXX-CFB

    Server

    AES-XXX

    Server

    AES-XXX

    Client

    AES-XXX-GCM

    GCM Server refuses transfer GCM Server refuses transfer
    Client

    AES-XXX-CFB

    Server refuses transfer CFB CFB CFB
    Client

    AES-XXX

    GCM CFB CFB CFB
    Client

    AES-XXX

    Server refuses transfer CFB CFB CFB
    Content Protection Select Encrypt uploaded files with a password to encrypt the uploaded files with the specified password (client-side encryption at rest). The protected file has the extension .aspera-env appended to the file name. Anyone downloading the file must have the password to decrypt it.

    Select Decrypt password-protected files downloaded to prompt for the decryption password when downloading encrypted files.

    For more information about client-side encryption at rest, see Client-Side Encryption-at-Rest (EAR).

  11. Configure file handling, if needed.
    On the File Handling tab, configure non-default transfer settings by editing any of the following settings:
    File Handling Option Description
    Resume Select Resume incomplete files to enable the resume feature. Select the file comparison method from the When checking files for differences drop-down menu:
    • Compare file attributes - Compares the sizes of the existing and original file. If they are the same, then the transfer resumes, otherwise the original file is transferred again.
    • Compare sparse file checksums - Performs a sparse checksum on the existing file and resumes the transfer if the file matches the original, otherwise the original file is transferred again. (Default)
    • Compare full file checksums - Performs a full checksum on the existing file and resumes the transfer if the file matches the original, otherwise the original file is transferred again.

    Under When a complete file already exists at the destination, select an overwrite rule when the same file exists at the destination. By default, files on the destination are overwritten if different from the source.

    File Attributes
    • Select Preserve Access Time to set the access time of the destination file to the same value as that of the source file.
    • Select Preserve Modification Timeto set the modification time of the destination file to the same value as that of the source file.
    • Select Preserve Source Access Time to keep the access time of the source file the same as its value before the transfer.
    • Select the preserve access mode from the Preserve Access Control List(ACL) drop-down menu:
      • native - Preserve attributes using the native capabilities of the file system. If the destination and source do not support the same native ACL format, ascp reports and error and exits.
      • metafile - Preserve file attributes in a separate file, named filename.aspera-meta. For example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-meta. These metafiles are platform independent and can be copied between hosts without the loss of information. This mode is supported on all file systems.

        Use metafile in combination with native to keep the extended attributes with the file being transferred. For example, on a source file system that supports ACLs, select Preserve Access Control List with the native mode and on the destination that does not support ACLs, select metafile.

        When selecting metafile for the source and native for the target, any transfers that resulted in a metafile applies the ACLs from the metafile to the native file system.

      • none - Do not preserve attributes. This mode is supported on all file systems.
    • Select the remote access control mode from the Preserve Remote Access Control List (ACL) drop-down menu. The options (native, metafile and none) apply in the same way as for Preserve Access Control List. This option is used when ACLs are stored in a different format on the remote computer.
    • Select the preserve extended file mode from the Preserve Extended Attributes (xattr) drop-down menu:
      • native - Preserve attributes using the native capabilities of the file system. If the destination and source do not support the same native xattr format, ascp reports and error and exits.
      • metafile - Preserve file attributes in a separate file, named filename.aspera-meta. For example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-meta. These metafiles are platform independent and can be copied between hosts without loss of information. This mode is supported on all file systems.
      • none - Do not preserve attributes. This mode is supported on all file systems.
    • Select the preserve remote attributes mode from the Preserve Remote Extended Attributes (xattr) drop-down menu. The options (native, metafile and none) apply in the same way as for Preserve Extended Attributes. This option is used when attributes are stored in a different format on the remote computer.
    Note: Access, modification, and source access times cannot be preserved for node and Shares connections that are using cloud storage.
    Source Handling Select Automatically delete source files after transfer to delete the files that transferred successfully from the source.

    Select Automatically move uploaded source files to a directory after transfer and specify the location on the source machine to which they should be moved. Only a path to an existing location on the client can be specified.

    Select Delete empty source subdirectories to remove empty subdirectories from the source once the files that they contain transfer successfully. This option is usually used to clean up the Hot Folder when source files are moved or deleted after transfer.

  12. Click OK to save your changes.
    Changes are not saved until you click OK. Selecting Cancel will discard any unsaved changes made in the Connection Manager, including the addition and removal of connections.
  13. Connect to the remote host.
    Double-click the connection name, or select it and click Connect.
    Select a connection.

Editing and Deleting Connections

Click Connections and select the connection you want to edit or delete. Edit the settings or click Remove connections to delete the connection. Deleting connections cannot be undone. When in doubt, export the connections as a backup before deleting a connection.