RelayPro

Note

RelayPro is available starting with AIR version 5.4 and represents the next generation of secure relay communications for Binalyze AIR.

Overview

The RelayPro relay server is a specialized, authenticated proxy server designed to provide secure connections between AIR Responders and the AIR console. It acts as an intermediary relay that validates every Responder connection and securely forwards traffic to the AIR console. RelayPro is purpose-built for AIR and is not intended for general proxy use cases.

Unlike the deprecated Relay Server, RelayPro does not require a Responder to be installed on the same machine. This separation reduces the overall attack surface and aligns with modern zero-trust and least-privilege design principles.

Caution

The legacy Relay Server will be deprecated in a future release (planned for early 2026). Both RelayPro and the legacy Relay Server will run in parallel during the transition period.

How it Works

All Responder connections use HTTPS for secure communication and must complete a two-step authentication flow:

1. Initial authentication — the Responder authenticates with RelayPro using JWT credentials.
2. Secure forwarding — RelayPro validates the token and forwards authorized requests to the AIR console only when the target address and port are allowed.

This flow ensures only authorized Responders can establish connections to the AIR console.

Security Features

• Unique authentication — each Responder receives its own time-limited JWT tokens
• Enhanced encryption — token encryption keys are derived uniquely per Responder
• Zero persistence — encryption keys are not shared between Responders or stored permanently
• Resilient design — if RelayPro restarts, existing valid tokens remain functional
• Modern JSON logging — logs are stored locally on the RelayPro server (not retrievable remotely)

Network Ports

RelayPro uses the same network ports as Responders connecting directly to the AIR console:

• 443 (HTTPS) — required
• 80 (HTTP) — optional, used only for HTTP reachability tests when HTTPS is unavailable
• 4222 (NATS) — optional, used when NATS is enabled in the AIR console

Key Differences from the Legacy Relay Server

• Independent deployment — no Responder required on the RelayPro host
• Enhanced security — HTTPS + JWT authentication instead of SOCKS5 without authentication
• Manual management — installation/upgrade/uninstallation are attended by admins
• Logging changes — local-only JSON logs; remote log fetch is not supported
• Configuration flexibility — more adjustable configuration options

Download and Install

Download the Package

1. In the AIR console, go to Organization Settings → Relay Server.
2. Select New Relay.
3. Choose New RelayPro.
4. Download the package for your platform/architecture.

RelayPro is available as .deb and .rpm packages.

RelayPro: Create a new RelayPro from Organization Settings

RelayPro: Download the RelayPro package and review prerequisites

Prerequisites

• Linux only (currently supported)
• Architecture: amd64 (x86_64) or arm64 (aarch64)
• Linux Kernel: 3.9 or later
• systemd: 231 or later
• Responder version: 2.79 or later

Standard, up-to-date Linux distributions typically meet these requirements.

Installation Commands

RelayPro uses environment variables during installation to register with the AIR console. Always set them first and use sudo -E to preserve the environment.

export AIR_CONSOLE_ADDRESS=your-console-address
export AIR_ORGANIZATION_ID=your-organization-id
export AIR_DEPLOYMENT_TOKEN=your-deployment-token

For .deb packages:

sudo -E dpkg -i ./binalyze-air-relaypro_<VERSION>_<ARCH>.deb

For .rpm packages:

sudo -E dnf install -y ./binalyze-air-relaypro_<VERSION>_<ARCH>.rpm

Example:

export AIR_CONSOLE_ADDRESS=192.168.1.100
export AIR_ORGANIZATION_ID=0
export AIR_DEPLOYMENT_TOKEN=1234567890abcdef

sudo -E dpkg -i ./binalyze-air-relaypro_1.0.0_amd64.deb

RelayPro: Example RelayPro installation on Linux

Package Details

• Package name: binalyze-air-relaypro
• Service name: binalyze-air-relaypro.service (systemd)
• Installation directory: /opt/binalyze/air/relaypro

The installation directory includes the RelayPro binary, logs, and a configuration file. Logging is enabled by default and is fully configurable.

Registration and Status

After installation and service start, RelayPro registers with the AIR console. On success, it updates /opt/binalyze/air/relaypro/config.yml with:

• relayId
• registeredTo
• securityToken

Caution

If the environment variables are incorrect, registration will fail. RelayPro will keep retrying registration and will not activate its proxy modules until registration succeeds.

You can verify status in:

• Config file: /opt/binalyze/air/relaypro/config.yml
• AIR console: Organization Settings → Relay Server

RelayPro: RelayPro registered and visible in the Relay Server list

Relay URL (Mandatory)

Caution

You must set the Relay URL to finalize RelayPro registration. Until the Relay URL is set, the RelayPro will not appear as an available connection route for Responders, and it will not be selectable during asset installer generation.

1. Go to Organization Settings → Relay Server.
2. Click the RelayPro Name to open its details.
3. Enter the Relay URL and save.

The Relay URL must include the port, for example:

https://relaypro.example.com:9443

If you use an intermediate proxy or load balancer, set the Relay URL to the first hop your Responders connect to:

https://intermediate-proxy.example.com:443

The Relay URL is the advertised URL of RelayPro and is what Responders will use to connect.

Assign Responders and Connection Route

When a RelayPro is registered and its Relay URL is set, it becomes available in Connection Route settings.

RelayPro: Edit Connection Route from the Assets list

RelayPro: Open the Connection Route selector from the Asset Info page

RelayPro: Select RelayPro as the connection route

If a Responder is switched to Direct Connection to the AIR console after previously using RelayPro:

• The Responder will attempt direct connection first.
• If direct connection fails, it will continue to use RelayPro while periodically re-checking direct availability.
• Once direct connection succeeds, the Responder stops using RelayPro.

Service Management

RelayPro runs as a systemd service and operates as a non-root user air-relaypro. The user and group are created automatically during installation.

sudo systemctl stop binalyze-air-relaypro
sudo systemctl start binalyze-air-relaypro
sudo systemctl restart binalyze-air-relaypro
sudo systemctl status binalyze-air-relaypro
sudo systemctl reload binalyze-air-relaypro

Caution

Restarting the service drops existing connections. Avoid frequent restarts to maintain stable Responder connectivity.

If you uninstall RelayPro, remove the air-relaypro user and group manually afterward.

Configuration

RelayPro configuration is stored in:

/opt/binalyze/air/relaypro/config.yml

Normally, you should not edit this file manually. Common reasons to update it include:

• Changing HTTPS proxy listener address/port
• Adjusting log file locations or rotation settings
• Changing CA certificate file or private file locations
• Manually configuring console addresses for migration

Core Configuration Fields

Field	Type	Required	Description
consoleAddress	string	Yes	Address of the AIR console
registeredTo	string	Yes	Console address this RelayPro is registered to
organizationId	integer	Yes	Organization ID provided during installation

Optional or Temporary Configuration Fields

Field	Type	Required	Description
relayProId	string	Yes	Unique RelayPro instance ID (generated if missing)
relayId	integer	Yes	Relay ID provided by the AIR console during registration
securityToken	string	Yes	Token used to authenticate RelayPro requests
consoleCACert	string	Yes	CA certificate in x509 PEM format
proxyEnabled	bool	Yes	Use system proxy to connect and forward traffic
debugLogging	bool	Yes	Enable debug logging
deploymentToken	string	No	Token used during registration (cleared after)
serverName	string	No	Server name for auto-generated TLS certificates
privateFolder	string	No	Path to private data folder
passwordFile	string	No	Password file for testing-only authentication
clientAuthToken	object	No	JWT token duration settings
httpsProxy	object	No	HTTPS proxy listener configuration
migration	object	No	Console migration information
logger	object	No	Logger configuration

Example Configuration

## Core connection settings
consoleAddress: "console.binalyze.com"
registeredTo: "console.binalyze.com"
organizationId: 1
relayProId: "e915b65b-ad83-4e81-991b-f236c1f90ad2"
relayId: 3
securityToken: "6a635b1d-398e-4a38-a908-4c53d75a641a"
consoleCACert: "-----BEGIN CERTIFICATE-----..."

## Optional proxy and debug logging settings
# proxyEnabled: true
# debugLogging: false

## Optional settings
# privateFolder: "/var/lib/relaypro/private"
# passwordFile: "/var/lib/relaypro/private/password.txt"

## Optional HTTPS proxy configuration
# httpsProxy:
#   listen: "0.0.0.0:8080"

## Optional migration settings
# migration:
#   consoleAddress: "new-console.binalyze.com"
#   validUntilAt: "2026-12-31T23:59:59Z"

## Optional logger configuration
# logger:
#   fileName: "relaypro.log.txt"
#   maxSize: "5GiB"
#   maxAge: "1week"
#   maxBackups: 10
#   noCompress: false

Logger Configuration (Environment Variable)

RelayPro merges logger configuration from the config file and the environment variable. The environment variable has higher priority.

RELAYPRO_LOGGER_CONF=fileName=relaypro.log.txt,maxSize=5GiB,maxAge=1week,maxBackups=10,noCompress=false

Reload vs Restart

Changes requiring service restart:

• privateFolder
• serverName
• httpsProxy
• logger

Changes applied on reload:

• consoleAddress
• registeredTo
• relayProId
• securityToken
• relayId
• debugLogging
• proxyEnabled
• consoleCACert
• clientAuthToken
• migration

HTTPS Proxy Listener

RelayPro includes a built-in HTTPS proxy server. It is enabled by default and listens on 0.0.0.0:9443.

Example configuration:

httpsProxy:
  listen: "0.0.0.0:8443"

Set the Relay URL in the AIR console to match the advertised address and port:

https://relaypro.example.com:9443

If you use an intermediate proxy or load balancer, set the Relay URL to that external endpoint:

https://intermediate-proxy.example.com:443

HTTPS and HTTP Listener Environment Variables

• RELAYPRO_HTTPS_LISTEN — configure the HTTPS listener
• RELAYPRO_HTTP_LISTEN — enable an HTTP listener (disabled by default)

Caution

If you enable the HTTP listener, you are responsible for ensuring it is not exposed to the public internet and is protected by your internal network controls.

Password File (Testing Only)

Password-based authentication is intended for testing. After testing, remove the password file from config/env and reload.

Example password file:

username1:password1
username2:password2

Example test request:

https_proxy=https://127.0.0.1:9443 \
curl --proxy-user username1:password1 \
  --proxy-insecure -k https://your-air-console.binalyze.com/api/app/check

You can set a password file via RELAYPRO_PASSWORD_FILE without editing the config file.

CA Bundle File

RelayPro generates a CA bundle at startup if one does not exist. This bundle is used to:

• Generate TLS certificates for clients
• Derive encryption keys for JWT token protection

If the CA bundle changes, Responders will re-authenticate and update their certificates, which invalidates existing JWT token encryption. Back up the CA bundle and keep it safe.

Multiple RelayPro instances can share the same CA bundle for clustering scenarios.

You can specify the CA bundle path via:

RELAYPRO_CA_BUNDLE_FILE

RelayPro supports PEM-encoded certificates with RSA private keys (PKCS#1 only).

Environment Variables

Recommended location for environment variables:

/etc/environment.d/binalyze-air-relaypro.conf

RelayPro supports standard proxy variables for RelayPro → AIR console connections:

• HTTPS_PROXY
• HTTP_PROXY
• NO_PROXY

Lowercase variants are also supported. RelayPro uses the CONNECT method when communicating via a proxy.

Upgrade

RelayPro has an independent release cycle (separate from Responder versioning). Upgrade only when notified by AIR release notes.

To upgrade:

1. Download the latest RelayPro package for your platform.
2. Install it using the same package manager.

During an upgrade:

• A temporary RelayPro process starts
• The old process drains existing connections
• The new process takes over
• The temporary process stops after connections close

If anything goes wrong during the update, interrupt it and restart the update process. If the issue persists, stop the RelayPro service and retry the update.

Check status and logs during the upgrade:

sudo systemctl status binalyze-air-relaypro

Enable debug logging during upgrade and disable it afterward. No system reboot is required.

Uninstall

Before uninstalling, remove the RelayPro from the AIR console:

Organization Settings → Relay Server → Remove RelayPro

Then uninstall:

# For deb packages
sudo apt-get remove binalyze-air-relaypro

# For rpm packages
sudo dnf erase binalyze-air-relaypro

Cleanup remaining files and users:

sudo rm -rf /opt/binalyze/air/relaypro
sudo rm -rf /etc/environment.d/binalyze-air-relaypro.conf
sudo userdel -r air-relaypro
sudo groupdel air-relaypro

Migration from Legacy Relay Server

When migrating, plan a staged rollout:

1. Identify target Responders.
2. Verify compatibility — Responders should run v2.74.1 or later for RelayPro compatibility.
3. Install RelayPro.
4. Configure RelayPro.
5. In the AIR console, go to Organization Settings → Relay Server, and set the Relay URL.
6. Assign one or more Responders to RelayPro.
7. Verify connectivity (may take several minutes).
8. Optional: install a new Responder via New Asset → Choose a Connection Route to validate.
9. Migrate remaining Responders.
10. Keep the legacy Relay Server available for rollback if needed.
11. If issues occur, contact Support and revert if required.

RelayPro is a distinct product and can be installed on the same machine as the legacy Relay Server.