Command- Line Interface Guide 3.9.2 Windows Revision:118 Generated:08/28/2019 12:49 | Contents | ii Contents Introduction............................................................................................................... 4 Installation................................................................................................................. 4 Installing the Aspera CLI.....................................................................................................................................4 Setting Environment Variables for the Aspera CLI.............................................................................................5 Configuring for Aspera on Cloud........................................................................................................................ 6 Configuring for Faspex.........................................................................................................................................7 Sample Configuration File....................................................................................................................................8 Uninstalling........................................................................................................................................................... 9 aspera: The Command-Line Transfer Client........................................................ 9 About the Command-Line Client.........................................................................................................................9 Prerequisites.......................................................................................................................................................... 9 aspera Command Reference................................................................................................................................. 9 aoc Command Reference....................................................................................................................................12 ats Command Reference.....................................................................................................................................22 faspex Command Reference...............................................................................................................................30 node Command Reference..................................................................................................................................38 shares Command Reference............................................................................................................................... 46 ascp: Transferring from the Command Line with Ascp.....................................54 Ascp Command Reference................................................................................................................................. 54 Ascp General Examples......................................................................................................................................69 Ascp File Manipulation Examples..................................................................................................................... 71 Ascp Transfers with Object Storage and HDFS................................................................................................ 73 Transfers with IBM Aspera On Demand and Cloud-Based HST Servers............................................. 73 Writing Custom Metadata for Objects in Object Storage......................................................................76 Using Standard I/O as the Source or Destination..............................................................................................77 Using Filters to Include and Exclude Files........................................................................................................80 Symbolic Link Handling.................................................................................................................................... 86 Creating SSH Keys (Command Line)................................................................................................................87 Reporting Checksums......................................................................................................................................... 89 Client-Side Encryption-at-Rest (EAR)...............................................................................................................92 Comparison of Ascp and Ascp 4 Options......................................................................................................... 93 Ascp FAQs..........................................................................................................................................................96 Technical Support................................................................................................... 98 Legal Notice.............................................................................................................98 ascp4: Transferring from the Command Line with Ascp 4................................99 Introduction to Ascp 4........................................................................................................................................99 Ascp 4 Command Reference..............................................................................................................................99 | Contents | iii Ascp 4 Transfers with Object Storage............................................................................................................. 107 Ascp 4 Examples.............................................................................................................................................. 107 Technical Support................................................................................................. 108 Legal Notice...........................................................................................................108 | Introduction | 4 Introduction The IBM Aspera Command-Line Interface (the Aspera CLI) is a collection of Aspera tools for performing high- speed, secure data transfers from the command line. The Aspera CLI is for users and organizations who want to automate their transfer workflows. The Aspera CLI is comprised of three command-line programs: aspera The aspera executable is a command-line client for performing transfers with Aspera on Cloud, Aspera Faspex, and Aspera Shares transfer servers. For further information on the aspera program, see aspera: The Command-Line Transfer Client on page 9 ascp The ascp executable is a command-line FASP transfer program. For information on the ascp program, see ascp: Transferring from the Command Line with ascp Note: Ascp is not for use with Aspera on Cloud. ascp4 ascp4, or A4, is a FASP transfer program similar to ascp that has been optimized for sending large sets of individual files and can support UDP multicast through Aspera FASPStream. For information on A4, see ascp4: Transferring from the Command Line with Ascp4. Note: Ascp4 is not for use with Aspera on Cloud. Installation To use the Aspera CLI, you must 1. Install the product. See Installing the Aspera CLI on page 4. 2. Configure it. See Configuring for Aspera on Cloud and Configuring for Faspex on page 7. Installing the Aspera CLI 1. Download the Aspera CLI package from the Aspera website. 2. Unzip the installation file: aspera-cli-x.x.x.xxx.xxxxxxx-win-xxxx-32-release.zip 3. Add the Aspera CLI to your Path system variable: a) Select Start > Control Panel > System and Security > System > Advanced System Settings and enter the admin password for this computer. The System Properties dialog appears. b) On the Advanced tab, click Environment Variables. c) In the System variables area, select the Path variable in the list and click Edit. d) In the Variable value field, add the path to the bin directory of your new Aspera CLI installation. For example: C:\other\paths\already\configured;C:\aspera\cli\bin\ | Installation | 5 e) Click OK in the dialogs to save your changes. About Your Installation Your Aspera CLI installation is a per-user, local installation. The CLI can be run by the computer where it is installed. It is not a system-wide installation. Setting Environment Variables for the Aspera CLI You can use environment variables to make your interaction with the Aspera CLI smoother. The CLI provides for environment variables around program password, content encryption, Aspera on Cloud client ID and secret, private key, HTTP proxy credentials, and FASP proxy credentials. Password for the Aspera CLI To set an environment variable with the value of your password, to be used with all aspera commands, run the following command: > set ASPERA_PASS=my_password Note: If your system uses PowerShell, the syntax to set the environment variable is slightly different: > $env:ASPERA_PASS = "my_password" Encryption/Decryption Passphrase If you plan to use encryption on the content you are transferring, you can set an environment variable for your encryption/decryption passphrase. Run the following command: > set ASPERA_SCP_FILEPASS=my_decryption_passphrase Client ID, Client Secret, and Private Key for Aspera on Cloud When you use the Aspera CLI with the Aspera on Cloud (AoC) SaaS, the CLI is a client application to AoC, and must have a client ID, client secret, and the private key portion of a public/private keypair. • For the client ID and secret, you can use the default, "global" values that are provided with the CLI