Plugin: faspex5: IBM Aspera Faspex v5🔗
Faspex 5 is IBM Aspera's newer self-managed application.
The following authentication methods are supported (option auth):
| Method | Description |
|---|---|
jwt |
General purpose, private-key based authentication |
web |
Requires authentication with web browser |
public_link |
Public link authentication (set when option url is a public link) |
boot |
Use authentication token copied from browser (experimental) |
Tip
If you have a Faspex 5 public link, provide it, as-is, through the option url.
Faspex 5 quick start with wizard🔗
For a quick start, one can use the wizard, which will help to create an Option Preset:
ascli config wizard
Then, answer questions interactively:
argument: url> faspex5.example.com
If multiple applications are detected, the wizard asks which one to use (this step is skipped if only Faspex is detected):
Multiple applications detected:
╭─────────┬───────────────────────────────────────────┬─────────────╮
│ product │ url │ version │
╞═════════╪═══════════════════════════════════════════╪═════════════╡
│ faspex5 │ https://faspex5.example.com/aspera/faspex │ F5.0.6 │
│ server │ ssh://faspex5.example.com:22 │ OpenSSH_8.3 │
╰─────────┴───────────────────────────────────────────┴─────────────╯
product> faspex5
When Faspex is detected, the wizard asks for a private key (a value like @file:<path>).
If you do not have a private key, leave that field blank, and one will be generated or a previously generated key will be used.
Using: Faspex at https://faspex5.example.com/aspera/faspex
Private RSA key, e.g. @file:<path> (leave empty to generate):
option: private_key>
Using existing key:
/Users/someuser/.aspera/ascli/my_key
Then, the email of the user shall be provided:
option: username> someuser@example.com
The administrator of Faspex shall provide you with a client_id, as specified below.
Ask the ascli client ID and secret to your Administrator.
Admin should login to: https://faspex5.example.com/aspera/faspex
Navigate to: :: → Admin → Configurations → API clients
Create an API client with:
- name: ascli
- JWT: enabled
Then, logged in as someuser@example.com go to your profile:
(User) → Account Settings → Preferences → Public Key in PEM:
-----BEGIN PUBLIC KEY-----
redacted
-----END PUBLIC KEY-----
Once set, fill in the parameters:
option: client_id> <CLIENT_ID>
option: client_secret> ****
Preparing preset: faspex5_example_com_user
Setting config preset as default for faspex5
Done.
You can test with:
ascli faspex5 user profile show
Saving configuration file.
Note
Paste the entire public key, including the BEGIN and END lines, into the user's profile.
For more information on the JWT method, refer to the section below.
If you have generated a private key with the wizard and lost the public key, you can retrieve the public key like this:
ascli faspex5 --show-config --out.secrets=yes --fields=private_key | ascli config pubkey @stdin: --out.secrets=yes
Faspex 5 JWT authentication🔗
This is the general purpose and recommended method to use.
Activation is in two steps:
- The administrator must create an API client in Faspex with JWT support
This operation is generally done only once:
- As Admin, Navigate to the web UI: Admin → Configurations → API Clients → Create
- Give a name, like
ascli - Activate JWT
- There is an option to set a global public key allowing the owner of the private key to impersonate any user. Unless you want to do this, leave this field empty.
- Click Create
-
Take note of Client ID (and Client Secret, but not used in current version)
-
The user will authenticate with a private key and set the public key in their Faspex 5 profile.
This operation is done by each user using the CLI.
- As a user, click the user logo located to the left of the app switcher in the top-right corner.
- Select
Account Settings. - At the bottom, in the
Public key in PEM formatfield, paste the public key that corresponds to the private key assigned to your account.
Tip
If you don't have a private key, see Private Key to generate one.
Then use these options:
--auth=jwt
--client-id=<CLIENT_ID>
--client-secret=<SECRET>
--username=<USERNAME>
--private-key=@file:.../path/to/key.pem
Note
Use the private_key option to provide the PEM content (not the file path).
To load from a file, prefix the path with @file:, for example, @file:/path/to/key.pem.
Typically, users create a preset so they don't have to enter these options each time.
Example:
ascli config preset update <F5_PRESET> --auth=jwt --client-id=<CLIENT_ID> --client-secret=<SECRET> --username=<USERNAME> --private-key=@file:.../path/to/key.pem
ascli config preset set default faspex5 <F5_PRESET>
ascli faspex5 user profile show
Faspex 5 web authentication🔗
For web-based authentication, the administrator must create an API client in Faspex to support an external web app:
- As Admin, Navigate to the web UI: Admin → Configurations → API Clients → Create
- Do not Activate JWT
- Set Redirect URI to
https://127.0.0.1:8888 - Click Create
- Take note of the Client Id (and Client Secret, but not used in current version)
The user will use the following options:
--auth=web
--client-id=<CLIENT_ID>
--client-secret=<SECRET>
--redirect-uri=https://127.0.0.1:8888
Faspex 5 public link authentication🔗
If all you have is a public link received by email or other, you can still do authorized actions with it.
For example, for a public link to post a package:
ascli faspex5 packages send --url='https://faspex5.example.com/?context=<CONTEXT>'
Faspex 5 bootstrap authentication🔗
For boot method: (will be removed in future)
- As user: Open a Web Browser
- Start developer mode
- Login to Faspex 5
- Find the first API call with
Authorizationheader, and copy the value of the token (series of base64 values with dots)
Use this token as password and use --auth=boot.
ascli config preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=<TOKEN>
Tested commands for faspex5🔗
Note
Add ascli faspex5 in front of the following commands:
admin accounts list
admin alternate_addresses list
admin clean_deleted
admin configuration modify @: mfa_required=false
admin configuration show
admin contacts list
admin distribution_lists create @json:'{"name":"test4","contacts":[{"name":"john@example.com"}]}'
admin distribution_lists delete %name:test4
admin distribution_lists list --query.type=global
admin email_notifications list
admin email_notifications show welcome_email
admin event application --query=@ruby:'{"event_type[]"=>["login_success"],"created_at_start"=>(Time.now.utc-60).strftime("%Y-%m-%dT%H:%M:%S.%LZ")}'
admin event webhook
admin jobs list --query=@json:'{"job_type":"email","status":"failed"}' --fields=id,error_desc
admin metadata_profiles list
admin node browse %name:Local
admin node list
admin node shared_folders %name:Local list
admin node shared_folders %name:Local show %name:Main
admin node shared_folders %name:Local user %name:Main list
admin node show %name:Local
admin oauth_clients list
admin registrations list
admin saml_configs list
admin shared_inboxes invite %name:my_shared_box_name @: email_address=johnny@example.com
admin shared_inboxes list
admin shared_inboxes list --query.all=true
admin shared_inboxes members %name:my_shared_box_name create %name:john@example.com submit_only
admin shared_inboxes members %name:my_shared_box_name delete %name:john@example.com
admin shared_inboxes members %name:my_shared_box_name delete %name:johnny@example.com
admin shared_inboxes members %name:my_shared_box_name list
admin smtp create @json:'{"auth_type":"open","server_address":"smtp.gmail.com","server_port":587,"domain":"gmail.com","tls_enabled":true,"packages_recipient_from":"sender"}'
admin smtp modify @: default_time_zone_offset=@val:0
admin smtp show
admin smtp test my_email_external
admin workgroups list
bearer_token
gateway @: url=https://localhost:12346/aspera/faspex
health --url=https://f5.example.com/path
invitation list
invitations create @: email_address=aspera.user1+u@gmail.com
packages browse --url=<PUBLIC_LINK_RECV_FR_USER> /
packages browse <ID> --query.recursive=true
packages delete <ID>
packages list --box=ALL
packages list --box=my_shared_box_name
packages list --box=my_workgroup --group-type=workgroups
packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
packages receive --box=my_shared_box_name <ID> --to-folder=.
packages receive --box=my_workgroup --group-type=workgroups <ID> --to-folder=.
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> --to-folder=.
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> ALL --to-folder=.
packages receive <ID> --to-folder=. --ts.content_protection_password=<PASSWORD>
packages receive <ID> <F5_PACK_FIRST_FILE> --to-folder=. --ts.content_protection_password=<PASSWORD>
packages receive ALL --once-only=yes --to-folder=. --query.max=5
packages receive INIT --once-only=yes
packages send --url=<PUBLIC_LINK_SEND_SHARED_BOX> @json:'{"title":"test title"}' test_file.bin
packages send --url=<PUBLIC_LINK_SEND_TO_USER> @json:'{"title":"test title"}' test_file.bin
packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=<PASSWORD>
packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
packages show --box=my_shared_box_name <ID>
packages show --box=my_workgroup --group-type=workgroups <ID>
packages show <ID>
packages status <F5_PACK_SEND_SHARED> @list:,failed,completed
packages status <ID>
postprocessing @: url=https://localhost:8553/asclihook script_folder=/path/to/scripts cert=.../localhost.p12 key=<PASSWORD>
shared browse %name:my_shared_folder_name
shared list
shared_folders browse %name:my_shared_folder_name
shared_folders list
user account
user account --query.expand=true
user profile modify @: preference.rows_per_page=10
user profile show
version
Most commands correspond directly to REST API calls.
Parameters to commands are carried through option query, as Extended Value, for list, or through Command Parameter for creation.
For a single parameter, the dot-path option form is the most direct (for example, --query.status=completed).
For multiple parameters or when copying directly from API documentation, @json: is more suitable.
Tip
The API is listed in Faspex 5 API Reference under IBM Aspera Faspex API.
Faspex 5: Inbox selection🔗
By default, package operations receive and list are performed on all the user's inboxes, not archived (inbox_all).
To select another inbox, use option box with one of the following values:
box |
Comment |
|---|---|
inbox_all |
All packages (not archived) Default. |
inbox_all_history |
All archived packages. |
inbox |
My packages. (not archived) |
inbox_history |
My archived packages. |
outbox |
Sent packages. |
outbox_history |
Archived sent packages. |
pending |
Pending packages. |
pending_history |
Archived pending packages. |
all |
All boxes accessible by current user. |
ALL |
All boxes of all users. admin only. |
<NAME> |
Name of shared inbox or workgroup. If option group_type is shared_inboxes: name of a shared inbox (default).If group_type is workgroups: name of workgroup. |
Note
In case the name of the box is an open value, use option group_type set to either shared_inboxes or workgroups.
A submit_only user cannot list packages in a shared inbox.
Faspex 5: Send a package🔗
Use the following command to send a package:
ascli faspex5 packages send <PACKAGE_DATA> <FILE_LIST> ...
The Hash passed as a command parameter corresponds to the Faspex 5 API endpoint POST /packages.
See the API reference for a full list of supported fields, or inspect such a request in the browser developer tools.
The following fields are required:
title- the package titlerecipients- the intended recipients
Note
The box option does not select a recipient shared inbox.
Use parameter recipients to send a package to a specific shared inbox.
Basic example (assuming a default preset has been configured for connection information):
ascli faspex5 packages send @json:'{"title":"some title","recipients":["user@example.com"]}' <FILE_PATH>
Specifying Recipients🔗
The Faspex 5 API expects recipients to be an Array of Hash, each containing a name field and an optional recipient_type field:
{"title":"some title","recipients":[{"recipient_type":"user","name":"user@example.com"}]}
Valid values for recipient_type are (API):
userworkgroupexternal_userdistribution_listshared_inbox
Other "recipient" fields are also defined in the API and can be used:
private_recipientsnotified_on_uploadnotified_on_downloadnotified_on_receipt
If the provided list is only an Array of String, then fields name and recipient_type are resolved automatically using the user's contacts.
Simplified recipient format🔗
As a convenience, ascli also accepts plain Strings in the recipients Array rather than Hashes:
{"title":"some title","recipients":["user@example.com"]}
When Strings are provided, ascli automatically looks up the contact across all recipient types.
If exactly one match is found, the name and recipient_type fields are resolved automatically.
If no match or multiple matches are found, an exception is raised.
Note
The lookup is case-insensitive and on partial matches.
Sending to a shared inbox🔗
To address a shared inbox, set recipient_type to shared_inbox:
{"title":"some title","recipients":[{"recipient_type":"shared_inbox","name":"box name"}]}
Restricting the lookup to specific recipient types🔗
To limit automatic contact lookup to one or more specific types, include the recipient_types field with either a single value or an Array of values:
{"title":"test title","recipient_types":"user","recipients":["user1@example.com","user2@example.com"]}
Content Protection (Encryption at Rest)🔗
To enable content protection (CSEAR), set parameter ear_enabled to true in the package creation payload.
See the Faspex package creation API for full details.
The following error is returned by Faspex if CSEAR was not specified in the package creation and if it is configured as mandatory on the server:
the provided encryption value (no) does not match the expected server side encryption value (yes)
Package with metadata🔗
To attach metadata to a package, include the metadata field in the package creation payload.
See the API documentation.
Each key corresponds to a metadata field name, and its value is the metadata value:
{"title":"test title","recipients":["<SH_INBOX_NAME>"],"metadata":{"Confidential":"Yes","Drop menu":"Option 1"}}
Faspex 5: List packages🔗
Option box can be used to list packages from a specific box (see Inbox Selection above).
Option query can be used to filter the list of packages, based on native API parameters, directly sent to Faspex 5 API GET /packages.
| Parameter | Type | Description |
|---|---|---|
offset |
Native | Managed by ascli: Offset of first package.Default: 0 |
limit |
Native | Managed by ascli: # of packages per API call.Default: 100 |
q |
Native | General search string, case-insensitive. Matches if value is contained in one of several fields. |
| ... | Native | Other native parameters are supported. See API documentation. |
max |
Special | Maximum number of items to retrieve Stop pages when the maximum is passed. |
pmax |
Special | Maximum number of pages to request. Stop pages when the maximum is passed. |
A Command Parameter in last position, of type Proc, can be used to filter the list of packages.
The advantage of this method is that the expression can be any test, even complex, as it is Ruby code.
But the disadvantage is that the filtering is done in ascli and not in Faspex 5, so it is less efficient.
Examples:
- List only available packages: (filtering is done in Faspex)
ascli faspex5 packages list --query=@json:'{"status":"completed"}'
- Similar, using filtering in
ascli:
ascli faspex5 packages list @ruby:'->(p){p["state"].eql?("released")}'
Faspex 5: Browsing folder content🔗
Several entities support folder browsing: Packages, Nodes, Shared Folders. All support two modes: paging and legacy API. By default, paging is used.
Option query is available with parameters supported by the API and ascli:
| Parameter | Evaluation | Default | Description |
|---|---|---|---|
paging |
ascli |
true |
Use paging API. |
recursive |
ascli |
false |
List inside folders. |
max |
ascli |
- | Maximum number of items. |
filter |
API | {"basenames":[]} |
See API doc. |
offset |
API (legacy) | 0 |
Index of first item. |
limit |
API (legacy) | 500 |
Number of items in one API call result. |
per_page |
API (paging) | 500 |
Number of items in one API call result. |
Faspex 5: Content of a received Package🔗
Note
Listing content also applies to sent packages using --box=outbox.
To list the content of a received package, use command faspex5 packages browse <PACKAGE_ID>.
Optionally, provide a folder path.
Faspex 5: Receive a package🔗
To receive one, or several packages at once, use command faspex5 packages receive.
Provide either a single package ID, or an Extended Value Array of package IDs, for example, @list:,1,2,3 as argument.
The same options as for faspex5 packages list can be used to select the box and filter the packages to download.
That is, options box and query, and the last Command Parameter Proc (filter).
Option --once-only=yes can be used, for "cargo-like" behavior.
Special package ID INIT initializes the persistency of already received packages when option --once-only=yes is used.
Special package ID ALL selects all packages (of the selected box).
In this case, typically, only completed packages should be downloaded, so use option --query.status=completed (or equivalently --query=@json:'{"status":"completed"}').
If a package is password protected, then the content protection password is asked interactively.
To keep the content encrypted, use option: --ts=@json:'{"content_protection":null}', or provide the password instead of null.
Tip
If you use option query and/or positional filter, you can use the list command for a dry run.
Faspex 5: List all shared inboxes and work groups🔗
Note
Shared inboxes (faspex5 admin shared_inboxes) are package recipients (dropboxes), accessible under the Packages app.
They are distinct from shared folders (faspex5 shared_folders), which are node-based storage access points accessible under the Files app.
If you are a regular user, to list work groups you belong to:
ascli faspex5 admin workgroups list
If you are admin or manager, add option --query=@json:'{"all":true}': this lists items you manage, even if you do not belong to them.
Example:
ascli faspex5 admin shared_inboxes list --query=@json:'{"all":true}' --fields=id,name
Shared inbox members can also be listed, added, removed, and external users can be invited to a shared inbox.
ascli faspex5 admin shared_inboxes invite_external_collaborator '%name:the shared inbox' @: email_address=john@example.com
It is equivalent to:
ascli faspex5 admin shared_inboxes invite_external_collaborator '%name:the shared inbox' @json:'{"email_address":"john@example.com"}'
Other payload parameters are possible for invite_external_collaborator in this last Hash Command Parameter:
{"description":"blah","prevent_http_upload":true,"custom_link_expiration_policy":false,"invitation_expires_after_upload":false,"set_invitation_link_expiration":false,"invitation_expiration_days":3}
Faspex 5: Create Metadata profile🔗
ascli faspex5 admin metadata_profiles create @json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
Faspex 5: Create a Shared inbox with specific metadata profile🔗
ascli faspex5 admin shared_inboxes create @json:'{"name":"the shared inbox","metadata_profile_id":1}'
Faspex 5: List content in Shared folder and send package from remote source🔗
Note
Shared folders (faspex5 shared_folders) provide node-based storage access, accessible under the Files app.
They are distinct from shared inboxes (faspex5 admin shared_inboxes), which are package recipients (dropboxes) accessible under the Packages app.
ascli faspex5 shared_folders list --fields=id,name
╭────┬──────────────╮
│ id │ name │
╞════╪══════════════╡
│ 2 │ Server Files │
╰────┴──────────────╯
ascli faspex5 shared_folders browse %name:'Server Files' /folder
ascli faspex5 packages send @json:'{"title":"hello","recipients":[{"name":"<RECIPIENT>"}]}' --shared-folder=%name:partages /folder/file
Tip
The shared folder can be identified by its numerical id or by name using the percent selector: %<FIELD>:<VALUE>. For example: --shared-folder=3 or --shared-folder=%name:partages.
Faspex 5: Receive all packages (cargo)🔗
To receive all packages, only once, through persistency of already received packages:
ascli faspex5 packages receive ALL --once-only=yes --query=@json:'{"status":"completed"}'
To initialize, that is, skip all current packages, so that next time ALL is used, only newer packages are downloaded:
ascli faspex5 packages receive INIT --once-only=yes
Faspex 5: Invitations🔗
There are two types of invitations for package submission: public or private.
Public invitations are for external users; provide only the email address.
ascli faspex5 invitations create @json:'{"email_address":"john@example.com"}' --fields=access_url
Private invitations are for internal users: provide the user or shared inbox identifier through field recipient_name.
Faspex 5: Cleanup packages🔗
Warning
Operation requires admin level.
The default automated cleanup period can be displayed with:
ascli faspex5 admin configuration show --fields=days_before_deleting_package_records
This parameter can be modified with:
ascli faspex5 admin configuration modify @json:'{"days_before_deleting_package_records":30}'
To start package purge, that is, permanently remove packages marked for deletion older than days_before_deleting_package_records, use command:
ascli faspex5 admin clean_deleted
Note
The expiration period taken by default is the one from admin configuration show.
To use a different period than the default, specify it on command line with: @json:'{"days_before_deleting_package_records":15}'
To delete all packages, one can use the following command:
ascli faspex5 packages list --box=ALL --format=yaml --fields=id | ascli faspex5 packages delete @yaml:@stdin:
Note
Above command will mark all packages for deletion, and will be permanently removed after the configured period (clean_deleted command).
It is possible to add a filter to the list command to only delete packages matching some criteria, for example, using --select=@ruby:'->(p){...}' on packages list.
Faspex 5: Admin: Unlock user🔗
To unlock a user, you can deactivate and then re-activate the user:
ascli faspex5 admin accounts modify %name:some.user@example.com @json:'{"account_activated":false}'
ascli faspex5 admin accounts modify %name:some.user@example.com @json:'{"account_activated":true}'
Tip
This example uses the percent selector, but the numerical ID can be used as well.
To send a password reset link to a user, use command faspex5 admin accounts reset_password <ACCOUNT_ID>.
Faspex 5: Faspex 4-style post-processing🔗
The command ascli faspex5 postprocessing emulates Faspex 4 post-processing script execution in Faspex 5.
It implements a web hook for Faspex 5 and calls a script with the same environment variables as set by Faspex 4.
Environment variables are set to the values provided by the web hook, which are the same as Faspex 4 post-processing.
Only values whose key starts with faspex_ are passed: other keys are ignored, as they could change the behavior of the script (e.g. PATH).
A structured value (object or array) is passed as JSON.
It allows migrating workflows from Faspex 4 to Faspex 5 while preserving scripts. Nevertheless, in the long term, a native approach shall be considered, such as using Aspera Orchestrator or other workflow engine, using Faspex 5 native web hooks or File Processing.
It is invoked like this:
ascli faspex5 postprocessing
An optional positional parameter can be provided as Extended Value Hash:
| Field | Type | Description |
|---|---|---|
allowed_ips |
String, Array[String] |
IP address or network (CIDR, e.g. 10.89.0.0/24), or list of them, allowed to call the listener. Requests from any other source IP are rejected with HTTP 403. When not set, no IP restriction is applied. This parameter or secret_token is required when url is not a local address. |
cert |
String |
Path to the TLS certificate file. Accepted formats: PEM (.pem) or PKCS12 (.p12 / .pfx).Example: /path/to/cert.pem. |
chain |
String |
Path to the PEM certificate chain file (appended as extra chain certificates). Example: /path/to/chain.pem. |
fail_on_error |
Bool |
When true, return HTTP 500 if the script exits with a non-zero status code. When false (default), the exit code is reported in the response body but HTTP 200 is returned.Default: false. |
key |
String |
Path to the PEM private key file, or the PKCS12 passphrase when cert is a .p12/.pfx file.Example: /path/to/key.pem. |
script_folder |
String |
Folder containing the post-processing scripts. The URL path (after the base path) is appended to this folder to locate the script to execute. Default: ..Example: /opt/faspex/scripts. |
secret_token |
String |
Shared secret for webhook authentication. When set, every incoming request must include ?token=<value> in the URL; requests without the correct token are rejected with HTTP 401. Configure the Faspex webhook URL as http://host:port/path/script.sh?token=<value>. This parameter or allowed_ips is required when url is not a local address. Generate it with openssl rand -hex 32: a weak token is refused (see secret_token_min_bits). |
secret_token_min_bits |
Integer |
Minimum estimated strength of secret_token, in bits (log2 of the number of guesses to find it). The strength is estimated with gem zxcvbn if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. 0 disables the check. A random token of 32 bytes (openssl rand -hex 32) is far above the default.Default: 80. |
timeout_seconds |
Integer |
Maximum time in seconds to wait for the script to complete before killing it. Default: 60. |
url |
String |
Address and port the server listens on. Use https:// with cert/key for TLS.Default: http://localhost:8080. |
For details on url and HTTPS (cert, key, chain), see Web service.
When a request on ascli is received the following happens:
- If
allowed_ipsis set,asclichecks the source IP address of the request (else HTTP 403). - If
secret_tokenis set,asclichecks thetokenparameter of the URL (else HTTP 401). ascligets the path of the URL called.- It removes the base path of base URL.
- It prepends it with the value of
script_folder. - It executes the script at that path, if it exists (else HTTP 404) and is inside
script_folder(else HTTP 403). - The script is killed if it does not finish within
timeout_seconds. - Upon success, a success code is returned.
For example:
ascli faspex5 postprocessing @json:'{"url":"http://0.0.0.0:8080/processing","script_folder":"/opt/scripts","secret_token":"<TOKEN>"}'
Generate the token with openssl rand -hex 32.
A weak token is refused at startup: its strength is estimated in bits, and shall be at least secret_token_min_bits.
The estimate uses the optional gem zxcvbn if installed, else a built-in estimate.
In Faspex 5, the URL of the webhook endpoint shall be reachable from within Faspex containers.
For example, if ascli is running on the host, the URL hostname shall not be localhost, as this refers to the local address inside the Faspex container.
Instead, one can specify the IP address of the host or host.containers.internal (Check podman manual).
So, ascli shall listen on an address reachable from the containers: the IP address of the host, or 0.0.0.0 for all interfaces.
Note
Security: by default the listener binds to loopback (localhost) and is not reachable from outside the host (see Web service).
When url is not a loopback address, at least one of the following protections is required:
secret_token: include the token in the Faspex webhook URL:http://host:8080/processing/script1.sh?token=<TOKEN>. Requests without the correct token are rejected with HTTP 401.allowed_ips: restrict the listener to the known Faspex container IPs or network, e.g.@json:'{"allowed_ips":["192.168.1.10","10.89.0.0/24"]}'. Requests from other IPs are rejected with HTTP 403.
Define the web hook as follows:
Webhook endpoint URI: http://host.containers.internal:8080/processing/script1.sh?token=<TOKEN>
Then the post-processing script executed will be /opt/scripts/script1.sh.
A Ruby script can also be evaluated in the process of ascli, instead of being executed in a new process.
For this, add lambda to the query of the URL, e.g. http://host.containers.internal:8080/processing/notify.rb?token=<TOKEN>&lambda.
The script shall have extension .rb, and return a lambda, which is called with all the webhook values (Hash).
For example:
->(params) { File.write('/tmp/last_package.txt', params['faspex_pkg_name']) }
The lambda runs with the privileges and configuration of ascli, and is stopped after timeout_seconds.
Faspex 5: Faspex 4 Gateway🔗
Note
This is not a feature for production. It's provided for testing only.
For legacy Faspex client applications that use the send API (only) of Faspex v4, the command gateway provides the capability to present an API compatible with Faspex 4, and it will call the Faspex 5 API.
It takes an optional Hash argument:
| Field | Type | Description |
|---|---|---|
cert |
String |
Path to the TLS certificate file. Accepted formats: PEM (.pem) or PKCS12 (.p12 / .pfx).Example: /path/to/cert.pem. |
chain |
String |
Path to the PEM certificate chain file (appended as extra chain certificates). Example: /path/to/chain.pem. |
key |
String |
Path to the PEM private key file, or the PKCS12 passphrase when cert is a .p12/.pfx file.Example: /path/to/key.pem. |
password |
String |
Password expected from clients in HTTP Basic authentication, for the above username. Generate it with openssl rand -hex 32: a weak password is refused (see password_min_bits).Example: <PASSWORD>. |
password_min_bits |
Integer |
Minimum estimated strength of password, in bits (log2 of the number of guesses to find it). The strength is estimated with gem zxcvbn if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. 0 disables the check. A random password of 32 bytes (openssl rand -hex 32) is far above the default.Default: 80. |
url |
String |
Address and port the server listens on. Use https:// with cert/key for TLS.Default: http://localhost:8080. |
username |
String |
Username expected from clients in HTTP Basic authentication. Set together with password. When not set, requests are accepted without authentication. Mandatory when url is not a loopback address (localhost, 127.0.0.0/8, ::1).Example: fx4_user. |
For details on url and HTTPS (cert, key, chain), see Web service.
Example:
ascli faspex5 gateway @json:'{"url":"https://localhost:12345/aspera/faspex","username":"fx4","password":"<PASSWORD>"}'
Clients authenticate with HTTP Basic, as on Faspex 4, with the username and password of the gateway.
Generate the password with openssl rand -hex 32.
A weak password is refused at startup: its strength is estimated in bits, and shall be at least password_min_bits.
username and password are mandatory when url is not a loopback address (see Web service): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
When they are not set, requests are accepted without authentication.
There are many limitations:
- It's only to emulate the Faspex 4
sendAPI (send package). - No support for remote sources, only for an actual file transfer by the client.
- The client must use the transfer spec returned by the API (not
faspe:URL). - Tags returned in transfer spec must be used in transfer.
- Only a single authentication is possible (per gateway) on Faspex 5: all packages are sent by the same Faspex 5 user.
Behavior: The API client calls the Faspex 4 API on the gateway, then the gateway transforms this into a Faspex 5 API call, which returns a transfer spec, which is returned to the calling client. The calling client uses this to start a transfer to HSTS, which is managed by Faspex 5.
Faspex 5: Get Bearer token to use API🔗
If a command is missing, then it is still possible to call the API directly on the command line using curl:
curl -H "Authorization: $(ascli faspex5 bearer_token --out.secrets=yes)" https://faspex5.example.com/aspera/faspex/api/v5/<API_ENDPOINT>