Configuring a Linux node for Faspex
A node is any server running IBM Aspera High-Speed Transfer Server (HSTS). Aspera web applications, such as Faspex, communicate with a node through the IBM Aspera Node API.
The instructions below assume you have already installed HSTS 4.3+ on your server. For instructions on installing HSTS see the IBM Aspera High-Speed Transfer Server Admin Guide: Installing HSTS section.
- You need root level access to configure HSTS. If you do not have root access use the
sudo
command to make changes to the operating system and theaspera.conf
fileChange ownership of the aspera.conf file to the current system user:chown system_user:root /opt/aspera/etc/aspera.conf
-
Verify that the node is running HSTS with a valid Connect Server license on your transfer
server: Run the following command:
ascp -A
In the resulting output, look for the following phrase:Connect Server License max rate
If you need to update your transfer server license, follow the instructions in IBM Aspera High-Speed Transfer Server Admin Guide: Updating Product License.
- Create the faspex system user account on the node.
Run the following commands to create the system user faspex.
groupadd -r faspex useradd -r faspex -g faspex
- Set up
aspshell
as the default shell for the transfer user.usermod -s /bin/aspshell faspex
-
Create and configure the faspex_packages directory.
Run the following commands to create the faspex_packages directories and configure the faspex user directories:
mkdir -p /home/faspex/faspex_packages chown faspex:faspex /home/faspex/ chown faspex:faspex /home/faspex/faspex_packages
The asconfigurator utility modifies the aspera.conf configuration file, located at: /opt/aspera/etc/aspera.conf.
-
Add the user to aspera.conf and set the docroot.
The directory you choose for the docroot is the absolute path for the transfer user. When this node is added to Faspex, users cannot access files or folders outside of the docroot.CAUTION:Do not use spaces in your docroot. If your docroot contains spaces, you may not receive all email notifications relating to transfer activity.Run the following asconfigurator command with the transfer username and the docroot path:
asconfigurator -x "set_user_data;user_name,username;absolute,/docroot/path"
For example:asconfigurator -x "set_user_data;user_name,faspex;absolute,/home/faspex/faspex_packages"
-
Set up token authorization for the user in aspera.conf.
- Run the following asconfigurator commands to set the encryption key for the
user:
# asconfigurator -x "set_user_data;user_name,username;authorization_transfer_in_value,token" # asconfigurator -x "set_user_data;user_name,username;authorization_transfer_out_value,token"
For example:
# asconfigurator -x "set_user_data;user_name,faspex;authorization_transfer_in_value,token" # asconfigurator -x "set_user_data;user_name,faspex;authorization_transfer_out_value,token"
- Configure dynamic key generation:
sudo asconfigurator -x "set_node_data;token_dynamic_key,true"
- Set a Redis primary key using askmscli. The master key must be a
unique random 256-bit key. The example below uses openssl to generate the key.
This Redis primary key will be used to encrypt the dynamic token encryption key.
echo -n "$(openssl rand -base64 32)" | sudo askmscli -s redis-primary-key
- Initialize the transfer user's keystore:
sudo askmscli -i -u username
- Set the store for the
asperadaemon
user that runs asperanoded:sudo askmscli -i -u asperadaemon
For more information, see the IBM Aspera High-Speed Transfer Server:Secrets Management with askmscli section. - Run the following asconfigurator commands to set the encryption key for the
user:
-
Set the IP address or hostname for the node in the aspera.conf file with
the following asconfigurator command:
asconfigurator -x "set_server_data;server_name,ip_or_hostname"
For example:asconfigurator -x "set_server_data;server_name,aspera.example.com"
-
Configure the node for HTTP and HTTPS fallback.
HTTP fallback serves as a backup transfer method when Aspera FASP transfers (UDP port 33001, by default) is unavailable. When HTTP fallback is enabled and UDP connectivity is lost or cannot be established, the transfer continues over HTTP or HTTPS. By default, Faspex requires you to enable HTTP and HTTPS and use the ports 8080 and 8443, respectively:
Restart the asperahttpd service.asconfigurator -x "set_http_server_data;enable_http,true" asconfigurator -x "set_http_server_data;http_port,8080" asconfigurator -x "set_http_server_data;enable_https,true" asconfigurator -x "set_http_server_data;https_port,8443"
Or on an OS running systemd:service asperahttpd restart
systemctl restart asperahttpd
- Enable activity logging on the
node:
If you do not enable activity logging, Faspex cannot retrieve package information and your users cannot download packages.asconfigurator -x "set_server_data;activity_logging,true"
- You must restart the asperanoded service for changes made using the
asconfigurator utility (which modifies the aspera.conf
configuration file) to take
effect:
Or on an OS running systemd:service asperanoded restart
systemctl restart asperanoded
-
Configure a HSTS transfer user account with a Node API username and password.
Faspex communicates to the HSTS transfer user account through the Node API to start transfers on the node.
For instructions on adding users to HSTS, see the IBM Aspera High-Speed Transfer Server Admin Guide: Setting Up Users.
-
Set up the Node API user:
/opt/aspera/bin/asnodeadmin -a -u node_api_username -p node_api_passwd -x system_username
Note: Use different names for the system user account and transfer user account in order to minimize confusion when tracing transactions and events.For example:/opt/aspera/bin/asnodeadmin -a -u node_user -p XF324cd28 -x faspex
-
Run the following command to check the system user was successfully added to
asnodeadmin:
/opt/aspera/bin/asnodeadmin -l
Given a node user named node_user and a system user named faspex, the output should be:user system/transfer user acls ==================== ======================= ==================== node_user faspex []
-
Set up the Node API user:
-
Copy the IBM Aspera Connect public key to authorized_keys to allow Connect
to connect to Faspex.
-
If the .ssh folder does not already exist in the faspex system
user's home directory, run the following command to create the folder:
mkdir -p /home/username/.ssh
For example:mkdir -p /home/faspex/.ssh
-
If the authorized_keys file does not already exist, add the
aspera_tokenauth_id_rsa.pub public key to the file by running:
For example:cat /opt/aspera/var/aspera_tokenauth_id_rsa.pub >> /home/username/.ssh/authorized_keys
cat /opt/aspera/var/aspera_tokenauth_id_rsa.pub >> /home/faspex/.ssh/authorized_keys
-
Transfer the .ssh folder and authorized_keys file
ownership to the system user by running the following commands:
chown -R username:username /home/username/.ssh chmod 600 /home/username/.ssh/authorized_keys chmod 700 /home/username chmod 700 /home/username/.ssh
For example:chown -R faspex:faspex /home/faspex/.ssh chmod 600 /home/faspex/.ssh/authorized_keys chmod 700 /home/faspex chmod 700 /home/faspex/.ssh
-
If the .ssh folder does not already exist in the faspex system
user's home directory, run the following command to create the folder: