Configuring Cargo for Faspex 5

CAUTION:
For Faspex 5.0.6 and later, you can't leave the client_id and client_secret values empty in the faspex5_jwt.sample.conf file.
Cargo uses a configuration file to store the account information for your transfer servers and settings for the way that packages will be downloaded. Before Cargo can function correctly, you must specify these elements in the .conf file.
Important: After upgrading your Faspex 4 server to Faspex 5, you may encounter compatibility issues with Cargo due to changes in authentication methods in Faspex. Review the Compatibility notice: Faspex 5 server section for more information.
  1. If Cargo is running, stop the daemon.
  2. Find the sample configuration file in the following path.

    /Library/Aspera/Cargo/etc/faspex5_jwt.sample.conf

    Note: Make sure that your configuration file is valid JSON. For example, if your path uses backslashes, use /.
  3. In a text editor, modify the sample configuration file. See the following table for required fields.
    Note: If your environment includes different types of servers, you can create a single configuration file that lists the information for all of them.
  4. Save your edited configuration file.

    You can change the file name of the sample file. Your new file name must end in .conf.

  5. Import the file into Cargo.
    $ sudo /Library/Aspera/Cargo/sbin/cargo -f path-to-config-file
  6. For security, if you have set the <passphrase_cleartext> field, delete the configuration file after you have imported it, to avoid leaving the password in unencrypted form.
  7. Now, start the Cargo daemon. See Starting and Stopping Cargo.

Sample configuration file

A sample configuration file is shown (and is included in the installation package). Your settings might differ from these examples. At a minimum, change the required entries to your system, and import the file. For instructions, see the previous steps.

The text of the faspex5_jwt.sample.conf file:

{
    "conf": {
        "accounts": [
            {
                "authentication_type": "JWT",
                "client_id": "",
                "client_secret" : "",
                "sso_host_type": 7
                "host": "https://sample.faspex5.com",
                "name": "Sample Faspex 5",
                "private_key": "/absolute/path/to/private_key",
                "user": "sample@domain.com",
                "packages": {
                    "auto_start": true,
                    "check_interval_seconds": 900,
                    "download_dir": "/path/to/automatically/download/packages/to/",
                    "name": "Sample Faspex 5 Inbox",
                    "passphrase_cleartext": "",
                    "passphrase_enabled": false,
                    "separate_package_folders": true,
                    "skip_owner_packages": false,
                    "version": 2,
                },
            }
        ],
        "version": 1,
    }
}

Conf file fields and values

Field Required/Optional Description Values
authentication_type Required. Cargo's authentication type that is used with this transfer server. Do not modify the value in this field. JWT
client_id Required for Faspex 5.0.6 and later. Optional for Faspex 5.0 and earlier.

Set this field only if you want to use a custom client ID that you have generated in Faspex 5 Admin app.

 The client ID for the Faspex 5 organization. To use the generic, default value, omit this field or leave it empty.
Attention: If you're using Faspex 5.0.6 or later this field cannot be left empty.
client_secret Required for Faspex 5.0.6 and later. Optional for Faspex 5.0 and earlier.

Set this field only if you want to use a custom client secret that you have generated in Faspex 5 Admin app.

 The client secret for the Faspex 5 organization. To use the generic, default value, omit this field or leave it empty.
Attention: If you're using Faspex 5.0.6 or later this field cannot be left empty.
host Required. The Faspex 5 server hostname or IP address.  
name Required. A human-readable name for your Faspex 5 server, for differentiation of multiple accounts.  
private_key Required. The full path to your SSH private key file.  
user Required.

Your Faspex 5 email address. The email address must be the same as your Faspex 5 username. For more information refer to the Cargo 4.2.11 Release notes.

  
packages fields:      
auto_start Optional. Sets whether Cargo should automatically start checking for packages when it is started. Cargo sets this value to true.
check_interval_seconds Optional. The time, in seconds, to elapse between checking for new packages. Valid values are 60, 300, 900, 1800, and 3600.

The default value is 900.
download_dir Required. The absolute path to the directory that is used to store downloaded packages.  
passphrase_cleartext Optional; required for automatic package decryption. The passphrase that Cargo must use for automatic decryption of packages upon download.

If there is a passphrase mismatch, the file is left encrypted, but is downloaded successfully.

For security, the value you enter in the <passphrase_cleartext> field is stored in an encrypted form when you import the configuration file.
Important: If you use the <passphrase_cleartext> field, be sure to delete the configuration file after you have imported it, to avoid leaving the password in unencrypted form.
  
passphrase_enabled Optional. Set to true if you want Cargo to use a passphrase to decrypt packages.

Set the passphrase itself in the <passphrase_cleartext> field.

 The default value is false.
separate_package_folders Optional. Set to true if you want packages with the same title to be downloaded to unique folders. The default value is true.
skip_owner_packages Optional. Set to true if Cargo must skip packages that you sent to yourself. The default value is false.
version Required. Cargo-internal data. Do not modify the value in this field.  
sso_host_type Required. Attribute to differentiate the types of host/server. Do not modify the value in this field.  

Compatibility notice: Faspex 5 server

Faspex 5 no longer uses a user-password pair for its authentication method, instead it now relies on JWT (JSON Web Tokens) for that purpose. As a result, after upgrading your Faspex 4 server to Faspex 5, Cargo will not work properly. To restore Cargo to a functional state after upgrading your Faspex server to version 5, follow these steps:

  1. If Cargo is running, stop the daemon.
  2. Delete the database files located under the var directory. Alternatively, you can uninstall Cargo and perform a clean install. You will need to delete both the application and app-data directories.
  3. Prepare a new configuration file for Faspex 5. See the Sample configuration file section for more information.
    Note: To enable JWT authentication for Faspex 5 the server admin must provide a pair of client ID and secret associated with the Faspex 5 (login-user) account.
  4. Follow the steps in the Configuring Cargo for Faspex 5 section to load the configuration file into the database and starting the Cargo service.