IBM Aspera Proxy with HSTS: end-to-end load balancing, Node API and Shares integration

IBM Aspera Proxy can provide a single entry point in front of multiple High-Speed Transfer Server (HSTS) nodes. The design becomes especially useful when the same endpoint must support FASP transfers, Node API access and Aspera Shares.

The important architectural point is that FASP and Node API are different traffic flows. FASP transfer sessions are distributed by the Aspera reverse proxy on 33001, while Node API requests are published over HTTPS and forwarded to the HSTS Node API service on 9092.

Target architecture

The goal is to give clients and Aspera Shares one Proxy FQDN or VIP instead of exposing individual HSTS nodes.

Think of the design as two services behind one Proxy address: FASP on 33001 and Node API on 443.

Prerequisites

Before configuring the Proxy, make sure the basic HSTS services work directly.

• HSTS nodes. Two or more HSTS servers are installed and reachable from the Proxy.
• FASP. TCP/UDP 33001 is allowed between clients, Proxy and HSTS nodes as required by the network design.
• Node API. The Proxy can reach each HSTS Node API on HTTPS 9092.
• Proxy endpoint. A stable Proxy VIP or FQDN is available for applications and users.
• TLS. A trusted certificate and private key are available for the Proxy HTTPS endpoint.
• Users. The required transfer and Node API identities are available consistently across the HSTS backends selected by the Proxy.
• SSH trust. The Proxy transfer user can authenticate to each HSTS destination.

Step 1 — Prepare each HSTS node

Each HSTS backend must be independently functional before it is placed behind the Proxy.

In the reference HSTS configuration, the transfer user had a defined docroot, read/write/directory permissions and token-based transfer authorization. The HSTS Node API service was listening on secure port 9092.

<user>
  <name>transfer_user</name>
  <file_system>
    <access>
      <paths>
        <path>
          <absolute>/data/aspera</absolute>
          <read_allowed>true</read_allowed>
          <write_allowed>true</write_allowed>
          <dir_allowed>true</dir_allowed>
        </path>
      </paths>
    </access>
  </file_system>
</user>

<server>
  <server_name>HSTS1</server_name>
  <listen>9092s,127.0.0.1:9091</listen>
</server>

Repeat the required user and Node API configuration on every HSTS node that can receive requests from the Proxy.

Step 2 — Verify Node API directly on every HSTS

Before introducing the Proxy, test the Node API directly against each HSTS server. A successful browse request should return an HTTP 200 response and the contents of the configured docroot.

curl -ik -u NODE_API_USER \
  -X POST \
  -d '{"path":"/"}' \
  https://HSTS1:9092/files/browse

Repeat the same test against HSTS2:9092. Do not proceed until both backend Node API endpoints behave consistently.

Step 3 — Configure FASP reverse proxy load balancing

Configure the Proxy-side /opt/aspera/proxy/etc/aspera.conf with all HSTS destinations that should receive FASP transfers.

<server>
  <proxy>
    <enabled>true</enabled>
    <authentication>false</authentication>
    <port_range_low>5000</port_range_low>
    <port_range_high>6000</port_range_high>
  </proxy>

  <rproxy>
    <enabled>true</enabled>
    <rules>
      <rule>
        <hosts>
          <host>HSTS1:33001</host>
          <host>HSTS2:33001</host>
        </hosts>
        <balancing>round_robin</balancing>
        <keyfile>/home/$(user)/.ssh/id_rsa</keyfile>
      </rule>
    </rules>
    <log_level>2</log_level>
  </rproxy>
</server>

With multiple destinations in the same rule, the Proxy can distribute transfer sessions across the configured HSTS servers using round_robin.

Step 4 — Configure transfer-user authentication

The Proxy must be able to authenticate the transfer identity against whichever HSTS node is selected.

Use the same transfer-user mapping required by your design on the Proxy and HSTS systems, then establish public-key trust from the Proxy to each HSTS destination. IBM's working configuration used the Proxy-side user's public key on the HSTS nodes.

An SSH-key workflow such as ssh-copy-id can be used to place the Proxy transfer user's public key on each backend, subject to your organization's SSH policy.

After configuration, verify the Proxy transfer user can authenticate to both HSTS nodes before testing FASP load balancing.

Step 5 — Grant the reverse-proxy sudo permission

The reverse-proxy transfer user needs controlled permission to run /sbin/iptables-restore as root without requiring an interactive terminal.

Create a dedicated file under /etc/sudoers.d/ for the transfer user:

Defaults:transfer_user !requiretty
Defaults:transfer_user secure_path = /sbin:/bin:/usr/sbin:/usr/bin
transfer_user ALL = NOPASSWD: /sbin/iptables-restore

Replace transfer_user with the actual account. Keep this permission narrowly scoped instead of granting general passwordless sudo.

Step 6 — Test FASP through the Proxy

Configure the Aspera client to use the Proxy VIP/FQDN instead of an individual HSTS address and start a transfer over port 33001.

Run multiple transfer sessions and confirm they are being distributed across the configured HSTS backends.

Step 7 — Configure Node API reverse proxy on HTTPS 443

FASP load balancing does not by itself publish the HSTS Node API. Configure the Aspera nginx service on the Proxy so that clients connect to HTTPS 443 and nginx forwards the request to the HSTS Node API services on 9092.

The reference configuration used both HSTS nodes in an nginx upstream group:

events {
  worker_connections 1024;
}

http {
  upstream https_hsts_backend {
    ip_hash;
    server HSTS1:9092;
    server HSTS2:9092;
  }

  server {
    listen PROXY_IP:443 ssl;

    ssl_certificate     /path/to/proxy-cert.pem;
    ssl_certificate_key /path/to/proxy-key.pem;

    client_max_body_size 0;
    max_ranges 1;

    location / {
      proxy_buffering off;
      proxy_pass https://https_hsts_backend;
      proxy_set_header Host $host;
    }
  }

  server {
    listen 80 default_server;
    server_name _;
    return 301 https://$host$request_uri;
  }
}

Use your current approved TLS protocol and cipher baseline rather than copying legacy TLS settings from an old example.

Step 8 — Validate and restart nginx

Validate the nginx configuration before restarting the Aspera nginx service. Then confirm the Proxy is listening on HTTPS 443 and can reach both HSTS Node API endpoints on 9092.

systemctl restart asperanginx
systemctl status asperanginx

The external Node API path is now:

Step 9 — Test Node API through the Proxy

Use the Proxy endpoint instead of an individual HSTS address:

curl -ik -u NODE_API_USER \
  -X POST \
  -d '{"path":"/"}' \
  https://proxy.example.com/files/browse

The response should be equivalent to the direct HSTS Node API test. At this point the application no longer needs to know which HSTS node served the request.

Step 10 — Add the Proxy node in Aspera Shares

In Aspera Shares, add the Proxy endpoint as the node. The reference implementation used HTTPS 443, not direct Node API port 9092.

Once the node is saved, verify that Shares can browse the HSTS-backed storage through the Proxy.

Step 11 — Validate an end-to-end Shares transfer

Do not stop after the folder browser works. A complete validation should prove both traffic paths.

1. Log in to Aspera Shares.
2. Open the node configured with the Proxy FQDN.
3. Browse the HSTS-backed storage.
4. Upload or download a test file.
5. Confirm the Node API request uses HTTPS 443.
6. Confirm the actual transfer uses the Proxy FASP path on 33001.

This proves that Node API and FASP are both working through the same logical Proxy endpoint.

Step 12 — Test HSTS failover

The final validation is to prove that an unavailable HSTS node does not stop new transfers.

IBM Support confirmed that when a reverse-proxy destination does not respond, the Proxy marks it as faulty, logs the condition, and attempts the next HSTS destination. While the node is marked faulty, new transfers are not forwarded to it. The node is later returned to the available list after the fault interval.

During an approved test window:

1. Confirm both HSTS nodes are available.
2. Start several successful transfers through the Proxy.
3. Make one backend HSTS unavailable using the approved test method.
4. Start a new transfer.
5. Confirm the Proxy sends the session to the remaining HSTS node.
6. Restore the first HSTS and verify that it eventually returns to service.

Final configuration map

Troubleshooting

The main deployment should follow the steps above. If something does not work, use the symptom to identify which traffic path is failing.

Node API through the Proxy returns 500 Invalid Argument

First verify the same Node API request works directly against each HSTS on 9092. If the HSTS response is successful but the Proxy request fails, verify that the Proxy is forwarding HTTPS traffic through nginx to the HSTS Node API backends. Do not treat the FASP reverse-proxy service on 33001 as a Node API endpoint.

nginx cannot bind to port 9092

If nginx reports that port 9092 is already in use, keep the public nginx listener on 443 and use 9092 only for the backend HSTS Node API services.

Client / Shares → Proxy:443 → nginx → HSTS:9092

Port 443 fails with Permission denied

If Aspera nginx runs as a non-root user and cannot bind to privileged port 443, IBM Support recommended applying the Linux bind-service capability to the nginx binary:

setcap 'cap_net_bind_service=+ep' /opt/aspera/nginx/nginx
getcap /opt/aspera/nginx/nginx

Expected output:

/opt/aspera/nginx/nginx = cap_net_bind_service+ep

Authentication works but the FASP session does not start

Verify the Proxy transfer user's SSH key, the corresponding HSTS account, backend connectivity and the sudoers permission for /sbin/iptables-restore.

Defaults:transfer_user !requiretty
Defaults:transfer_user secure_path = /sbin:/bin:/usr/sbin:/usr/bin
transfer_user ALL = NOPASSWD: /sbin/iptables-restore

pvcl_client or Invalid argument errors appear in NodeD logs

Check that asperanoded is running under the expected service account, that pvcl_client has the required executable permission, and that the service account has the required sudoers entry.

ps -edf | grep asperanoded
ls -l /opt/aspera/bin/pvcl_client

The reference troubleshooting also checked:

asperadaemon ALL=(ALL) NOPASSWD: /opt/aspera/bin/pvcl_client

Do not use copying binaries between HSTS and Proxy servers as a production fix unless IBM explicitly documents it for your product version.

Shares can reach HSTS directly but not through Proxy

Verify the node in Shares is configured with the Proxy VIP/FQDN on port 443, SSL is enabled, the Proxy certificate is trusted, and the supplied Node API credential is valid for whichever HSTS backend nginx selects.

Production recommendations

• Use a stable VIP/FQDN. Keep clients and Shares independent of physical server addresses.
• Design Proxy HA separately. Multiple HSTS nodes do not remove the Proxy itself as a potential dependency.
• Use trusted TLS. Publish port 443 with an enterprise-approved certificate and current TLS policy.
• Keep Node API private. HSTS port 9092 should normally be reachable from the Proxy and approved management/application networks, not broadly exposed.
• Use least privilege. Avoid 777 filesystem modes and unrestricted sudo.
• Protect credentials. Node API passwords, token keys and private keys should be managed through the approved secrets process.
• Test both planes. Always validate Node API browsing and an actual FASP transfer independently.

Final take

The clean design is simple once the traffic is separated correctly.

FASP: clients connect to the Proxy on 33001, and Aspera Proxy distributes transfer sessions across the HSTS nodes.

Node API: Shares and API clients connect to the same Proxy endpoint on HTTPS 443, and nginx forwards those requests to HSTS 9092.

This gives applications a single endpoint while allowing the transfer and API layers to be scaled and managed independently.