Listeners

A Listener defines the port on which the USP Server accepts inbound connections and determines how those connections are forwarded to an internal target.

Depending on the Listener type, forwarding behavior is configured either through the session-break routing architecture (Routes, Inbound Nodes, and Outbound Nodes) or through direct TCP passthrough settings.

By default, the USP Server listens only for USP Manager connections on its predefined management port. Once a configuration that includes one or more Listener definitions is deployed, the USP Server instance begins accepting inbound connections according to the configuration of each Listener.

info

To create a protocol-specific (session-break) Listener, you must first add a Route with at least one Outbound Node.

TCP Listeners (Direct Mode) do not require a Route.

Before You Begin

Listener Types

USP supports two Listener types. Although both accept inbound connections on a port, their forwarding models differ.

Session-Break Listeners

Session-break Listeners handle specific application-layer protocols (FTP(S), HTTP(S), and SFTP). They rely on the standard routing architecture, where a Listener is associated with a Route, and the Route determines how connections are handled through Inbound Nodes and Outbound Nodes, including authentication and protocol-specific behavior.

Use a session-break Listener when you need application-layer proxying and the flexibility of route-based forwarding.

Direct Mode Listeners

Direct Mode Listeners (TCP Listeners) operate at the transport layer and do not perform session break or protocol inspection. They do not use Routes, Inbound Nodes, or Outbound Nodes. Instead, a TCP Listener forwards raw TCP traffic to a single outbound target (hostname and port) and applies the selected IP Filter at the Listener level before proxying the connection.

Each inbound connection creates a new outbound connection. If configured in the Deployment, outbound dialing can be performed through a Tunnel using a USP Client.

TCP Listeners are the right choice for simple port forwarding, proprietary protocols, or scenarios where session break is not required.

Network Interfaces

When a Listener is deployed, the USP Server binds the Listener Port to all network interfaces on the host (equivalent to binding to 0.0.0.0 for IPv4). As a result, the port is reachable through any local interface/IP address on the host.

Before deploying a Listener, make sure the selected Port is only exposed on the interfaces and networks you intend.

Complementary to network-level controls, you can use IP Filters to restrict which source IP addresses are allowed to establish connections.

Port

The Port specifies the network port on which the Listener accepts incoming connections. It must be an available port on the USP Server host.

Ensure that the selected port is open, not blocked by a firewall, and not already in use by another service.

Health Check

Listeners depend on multiple downstream components to successfully proxy inbound connections. If any of these dependencies is unavailable, inbound connections cannot be forwarded to their intended targets.

Health Check allows a Listener to automatically monitor the availability of its downstream dependencies and adjust its runtime state accordingly. This feature is particularly useful when USP Server instances are placed behind an upstream load balancer.

When enabled, the Listener performs periodic TCP-level connectivity checks to its downstream dependencies. If one or more required dependencies become unavailable, the Listener transitions to an Unhealthy state and stops accepting new inbound connections. Once all dependencies become reachable again, the Listener automatically returns to the Running state and resumes accepting connections.

info

If you migrated from USP 1.3.x, Health Check remains disabled for pre-existing Listeners.

Checked Dependencies

For Session-break Listeners (FTP(S), HTTP(S), SFTP):

• Outbound Node targets defined in the associated Route
• Tunnel and USP Client (if configured through a Deployment)
• LDAP servers (if configured in the Rule)

For TCP Listeners (Direct Mode):

• The outbound target defined by the Outbound Hostname and Outbound Port fields
• Tunnel and USP Client (if configured through a Deployment)

If a Tunnel and USP Client are configured through a Deployment, the Listener attempts TCP connectivity to the downstream targets through the tunnel. Otherwise, the Listener attempts connectivity directly from the USP Server host.

All checks are performed at the TCP level (connection attempt only). Health Check does not validate authentication, credentials, or application-level protocol behavior.

Configuration Parameters

When enabling Health Check, you must configure the following parameters:

• Interval: The time between health check cycles measured in seconds (must be greater than or equal to 5).
• Threshold: The number of consecutive failed or successful health check cycles per target required for it to transition between Healthy and Unhealthy states. A target transitions to Unhealthy only after the configured number of consecutive failures, and transitions back to Healthy only after the configured number of consecutive successes. The Listener is marked as Unhealthy as long as at least one required target is Unhealthy, and returns to Running only when no required targets are Unhealthy (must be greater than or equal to 1).
• Timeout: The maximum time in seconds allowed for each TCP connection attempt before it is considered failed (must be greater than 1 second and less than the configured Interval).

Listener State Behavior

When Health Check is enabled:

• The Listener starts in the Unhealthy state until all dependencies are confirmed reachable.
• If a dependency becomes unreachable, the Listener transitions from Running to Unhealthy and stops listening on its configured port.
• When all dependencies recover, the Listener automatically transitions back to Running and resumes accepting inbound connections.

Protocol-Specific Configuration

FTP(S), HTTP(S), and SFTP Listeners (Session Break Mode)

Route Association

For session-break Listeners, the Route associates the Listener with a specific Route configuration. A Route defines how inbound connections are forwarded to internal targets. It determines the target address, authentication mechanisms, and forwarding behavior.

Default Outbound Node

The Default Outbound Node specifies the internal target to which all authorized incoming connections are forwarded.

TCP Listeners (Direct Mode)

IP Address Filter List

For TCP Listeners (Direct Mode), the IP Address Filter List defines which source IP addresses are allowed to establish inbound connections. Each incoming connection is evaluated against the selected IP Filter, and connections that do not match the filter rules are immediately rejected.

Outbound Hostname

The Outbound Hostname specifies the internal target host to which accepted TCP connections are forwarded. It can be a valid hostname or IP address and represents the destination system that ultimately receives the proxied traffic.

Outbound Port

The Outbound Port defines the network port on the outbound target to which the connection is forwarded. Together with the Outbound Hostname, it determines the exact destination endpoint for the proxied TCP connection.

Listener Administration

Adding a Listener

To add a Listener, follow these steps:

1. From the Sidebar, click Configuration > Listeners.
2. Click the protocol card you want.
3. Click Add Listener.
4. Complete the details for the new Listener using the Field Descriptions table as a guide.
5. Click Save.

Field Descriptions

FTP(S)

Name	Description	Specifications	Required
Name	The name of the Listener.	Must be unique.	Yes
Description	The description of the Listener.		No
Port	The port of the Listener.	Must be within 1 and 65535.	Yes
Route	The Route associated with the Listener.	Must reference an already-created Route.	Yes
Default Outbound Node	The Outbound Node to which the Listener forwards incoming connections.		Yes
Use Health Check	Enables dependency health monitoring for the Listener. For more information, see Health Check.		Yes
Interval (Seconds)	Defines the time between health-check cycles.	Must be greater than or equal to 5.	Yes
Threshold (times)	Defines the number of consecutive failed or successful health check cycles required for a downstream target to transition between Healthy and Unhealthy. The Listener is marked as Unhealthy as long as at least one required target is Unhealthy, and returns to Running only when no required targets are Unhealthy.	Must be greater than or equal to 1.	Yes
Timeout (Seconds)	Defines the maximum time allowed for each TCP connection attempt before it is considered failed.	Must be greater than 1 second and less than the configured Interval.	Yes

HTTP(S)

Name	Description	Specifications	Required
Name	The name of the Listener.	Must be unique.	Yes
Description	The description of the Listener.		No
Port	The port of the Listener.	Must be within 1 and 65535.	Yes
Route	The Route associated with the Listener.	Must reference an already-created Route.	Yes
Default Outbound Node	The Outbound Node to which the Listener forwards incoming connections.		Yes
Use Health Check	Enables dependency health monitoring for the Listener. For more information, see Health Check.		Yes
Interval (Seconds)	Defines the time between health-check cycles.	Must be greater than or equal to 5.	Yes
Threshold (times)	Defines the number of consecutive failed or successful health check cycles required for a downstream target to transition between Healthy and Unhealthy. The Listener is marked as Unhealthy as long as at least one required target is Unhealthy, and returns to Running only when no required targets are Unhealthy.	Must be greater than or equal to 1.	Yes
Timeout (Seconds)	Defines the maximum time allowed for each TCP connection attempt before it is considered failed.	Must be greater than 1 second and less than the configured Interval.	Yes

SFTP

Name	Description	Specifications	Required
Name	The name of the Listener.	Must be unique.	Yes
Description	The description of the Listener.		No
Port	The port of the Listener.	Must be within 1 and 65535.	Yes
Route	The Route associated with the Listener.	Must reference an already-created Route.	Yes
Default Outbound Node	The Outbound Node to which the Listener forwards incoming connections.		Yes
Use Health Check	Enables dependency health monitoring for the Listener. For more information, see Health Check.		Yes
Interval (Seconds)	Defines the time between health-check cycles.	Must be greater than or equal to 5.	Yes
Threshold (times)	Defines the number of consecutive failed or successful health check cycles required for a downstream target to transition between Healthy and Unhealthy. The Listener is marked as Unhealthy as long as at least one required target is Unhealthy, and returns to Running only when no required targets are Unhealthy.	Must be greater than or equal to 1.	Yes
Timeout (Seconds)	Defines the maximum time allowed for each TCP connection attempt before it is considered failed.	Must be greater than 1 second and less than the configured Interval.	Yes

TCP

Name	Description	Specifications	Required
Name	The name of the Listener.	Must be unique.	Yes
Description	The description of the Listener.		No
Port	The port of the Listener.	Must be within 1 and 65535.	Yes
IP Address Filter List	The IP Filter that determines whether an incoming connection is allowed.	Must reference an already-created IP Filter.	Yes
Outbound Hostname	Hostname or IP address of the outbound target.		Yes
Outbound Port	The port number of the internal target.	Must be within 1 and 65535.	Yes
Use Health Check	Enables dependency health monitoring for the Listener. For more information, see Health Check.		Yes
Interval (Seconds)	Defines the time between health-check cycles.	Must be greater than or equal to 5.	Yes
Threshold (times)	Defines the number of consecutive failed or successful health check cycles required for a downstream target to transition between Healthy and Unhealthy. The Listener is marked as Unhealthy as long as at least one required target is Unhealthy, and returns to Running only when no required targets are Unhealthy.	Must be greater than or equal to 1.	Yes
Timeout (Seconds)	Defines the maximum time allowed for each TCP connection attempt before it is considered failed.	Must be greater than 1 second and less than the configured Interval.	Yes

Editing a Listener

To edit a Listener, follow these steps:

1. From the Sidebar, click Configuration > Listeners.
2. Click the protocol card of the Listener you want.
3. Click the row of the Listener you want to edit.
4. Click Edit.
5. Edit the Listener details using the Field Descriptions table as a guide.
6. Click Save.

warning

If you modify a Listener that is associated with a USP Server instance, the updated configuration must be manually pushed to the instance.

To push the configuration:

1. Navigate to Monitoring > Status.
2. Click the row of the associated server.
3. Go to the Configuration tab.
4. Review the pending changes in the Candidate Configuration - Preview section.
5. If the changes are correct, click Push Configuration.

If you edit the Listener Port, Use Health Check, Interval (Seconds), Threshold (times), or Timeout (Seconds) fields, you must also restart the Listener for the changes to take effect.

To restart the Listener:

1. Go to the Live Listeners tab.
2. Click the [ ··· ] button.
3. Click Stop Listener.
4. Click the [ ··· ] button again.
5. Click Start Listener.

The changes do not take effect on the server until these steps are completed.

Listener Metadata

Listener details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

FTP(S)

Name	Description
ID	Universally Unique Identifier of this Listener.
Routing Method	The routing method that the Listener uses. The only possible value is standard.
Created	Date and time this Listener was created.
Updated	Date and time this Listener was last updated.

HTTP(S)

Name	Description
ID	Universally Unique Identifier of this Listener.
Routing Method	The routing method that the Listener uses. The only possible value is standard.
Created	Date and time this Listener was created.
Updated	Date and time this Listener was last updated.

SFTP

Name	Description
ID	Universally Unique Identifier of this Listener.
Routing Method	The routing method that the Listener uses. The only possible value is standard.
Created	Date and time this Listener was created.
Updated	Date and time this Listener was last updated.

TCP

Name	Description
ID	Universally Unique Identifier of this Listener.
Version	Version number of the configuration. Every change increases the number.
Updated	Date and time this Listener was last updated.
Created	Date and time this Listener was created.

Deleting a Listener

To delete a Listener, follow these steps:

1. From the Sidebar, click Configuration > Listeners.
2. Click the protocol card of the Listener you want to delete.
3. Click the row of the Listener you want to delete.
4. Click the Delete button above the Listener details.
5. You will be asked to confirm the deletion. Click Delete.

warning

To delete a Listener, you must first delete its associated Deployment. Additionally, the USP Server instance configuration must be manually updated. To do this, follow these steps:

1. Navigate to Monitoring > Status.
2. Click on the associated server.
3. Go to the Configuration tab.
4. Click Push Configuration.

The changes do not take effect on the server until these steps are completed.

Managing Listeners

After deploying a Listener to a USP Server instance (by creating a Deployment and pushing the configuration), you can monitor, start, and stop the Listener from the Status dashboard. See Live Listeners Tab for more information.