Node API Setup

Select or create a system user to associate with the Node API credentials.

Aspera uses a specially configured system user for SSH authentication when starting transfers.

Note: If this user will be associated with Node API credentials that will be used to create access keys or bearer tokens, either do not set a password for the user or create a very large password.

Create a user account—for example, aspera_user_1—by running the following command:

# useradd aspera_user_1

Restrict the system user's access to the server's file system.

If the Node API user will use access key or bearer token authentication to authenticate to the Node API, configure a restriction for the system user. If the Node API user will use Node API credentials to authenticate to the Node API, configure a docroot for the system user.

To configure a restriction:

Run the following command:

# asconfigurator -x "set_user_data;user_name,username;file_restriction,|restriction"

Where username is the system user's username, | is a delimiter, and restriction is specific to the storage type and path:

Storage Type	Format Example
local storage	For Unix-like OS: specific folder: file:////`folder`/* drive root: file:////* For Windows OS: specific folder: file:///c%3A/`folder`/* drive root: file:///c*
Amazon S3 and IBM Cloud Object Storage - S3	s3://*
Azure	azu://*
Azure Files	azure-files://*
Azure Data Lake Storage	adl://*
Alibaba Cloud	oss://*
Google Cloud	gs://*
HDFS	hdfs://*

To configure a docroot:
Run the following command:
```
# asconfigurator -x "set_user_data;user_name,username;absolute,docroot"
```
Where username is the system user's username and docroot is the absolute path to which the system user has access.

Restrict user permissions with aspshell.

By default, all system users can establish a FASP connection and are only restricted by file permissions. Restrict the user's file operations by assigning them to use aspshell, which permits only the following operations:

Running Aspera uploads and downloads to or from this computer.
Establishing connections in the application.
Browsing, listing, creating, renaming, or deleting contents.

These instructions explain one way to change a user account or active directory user account so that it uses the aspshell; there may be other ways to do so on your system.

Run the following command to change the user login shell to aspshell:

# sudo usermod -s /bin/aspshell username

Confirm that the user's shell updated by running the following command and looking for /bin/aspshell at the end of the output:

# grep username /etc/passwd
username:x:501:501:...:/home/username:/bin/aspshell

Note: If you use OpenSSH, sssd, and Active Directory for authentication: To make aspshell the default shell for all domain users, first set up a local account for server administration because this change affects all domain users. Then open /etc/sssd/sssd.conf and change default_shell from /bin/bash to /bin/aspshell.

Set the IBM Aspera Connect public SSH key as an authorized key for the transfer user and ensure that they own the file.

Create the .ssh directory in the user's home folder.
```
# mkdir /home/aspera_user_1/.ssh/
```
Copy the Connect public SSH key into .ssh and rename it authorized_keys (or append the public key to authorized_keys if the file already exists).
```
# cp /opt/aspera/var/aspera_tokenauth_id_rsa.pub /home/aspera_user_1/.ssh/authorized_keys
```

Ensure that .ssh and .ssh/authorized_keys are owned by the user.

# chown -R aspera_user_1:aspera_user_1 /home/aspera_user_1/.ssh
# chmod 600 /home/aspera_user_1/.ssh/authorized_keys
# chmod 700 /home/aspera_user_1

# chmod 700 /home/aspera_user_1/.ssh

Associate the Aspera transfer user with a Node API username and password.

For example, to assign Node API credentials to user aspera_user_1, run the following command:

# /opt/aspera/bin/asnodeadmin -a -u node_api_username -p node_api_passwd -x aspera_user_1

(Optional) Change HTTPS port and/or SSL certificate.

The Aspera Node API provides an HTTPS interface for encrypted communication between node machines (on port 9092, by default). To modify the HTTPS port, see Configuring the IBM Aspera NodeD Service. For information on maintaining and generating a new SSL certificate, see Setting up SSL for your Nodes.

Configure other Node API settings.

If you want to query transfers by using GET /ops/transfers or to retrieve usage data by using GET /usage, enable activity logging on the node by running the following command:
```
# asconfigurator -x "set_server_data;activity_logging,true"
```
If you want to query events by using GET /events, enable activity event logging on the node by running the following command:
```
# asconfigurator -x "set_server_data;activity_event_logging,true"
```
As of version 3.8.0, activity_event_logging can be configured in individual access keys and overrides the setting on the node. If activity_event_logging is enabled for the access key, any Node API events associated with that access key are logged even if the node setting is false. If it is disabled for the access key, events are not logged for the access key even if activity_event_logging is enabled on the node.
For a description of other settings, see Configuring the IBM Aspera NodeD Service.

Restart asperanoded to activate your changes.

Run the following commands to restart asperanoded:

# /etc/init.d/asperanoded restart