Manage Listen Ports

A listen port is a TCP port that "listens" for incoming messages that are then passed to the gateway message processor. The Manage Listen Ports task lets you define passive listeners, including HTTP(S) and FTP(S). (JMS message polling is handled by the JMS queuing capabilities of the Gateway, while email listeners are configured using the Manage Email Listeners task.)
9-5
Gateway 10.x Users: Modify Your Listen Port to Fix Returned 404 Errors When Querying an API with Special Characters in URI Query String
Per Apache Tomcat specifications, "the HTTP/1.1 specification requires that certain characters are %nn encoded when used in URI query strings". This means that the following unencoded characters (including values wrapped in those characters) will return an error or be ignored if used to query an API through the Gateway:
" < > [ \ ] ^ ` { | }
.
To remedy this, you must use percent encoding. For example instead of using brackets [ ] in your query, use %5B and %5D instead. Or, to bypass this encoding requirement altogether, you may modify your listen port properties in the Gateway via the Policy Manager:
  1. Ensure that you're not logged into the same port as the listen port you wish to modify. For example, to modify port 8443, log out of that port and connect to a different port such as 9443.
  2. Run the Manage Listen Ports task in the Policy Manager. Select a port and then select [Properties].
  3. Select the [Advanced] tab.
  4. In the 'Advanced Properties' section, create a new property with the name 'relaxedQueryChars'.
  5. Enter the unencoded special characters as the values for this property. In our example, we wish to continue to using unencoded brackets for our query strings so we would enter '[ ]' as the property value.
  6. Click [OK] to save your changes and restart the Gateway so the new listen port properties
  7. Restart the Gateway so the new listen port properties will go into effect.
A listen port is a TCP port that "listens" for incoming messages that are then passed to the
Layer7 API Gateway
message processor. The Manage Listen Ports task lets you define passive listeners, including HTTP(S) and FTP(S). (JMS message polling is handled by the JMS queuing capabilities of the Gateway, while email listeners are configured using the Manage Email Listeners task.)
At least one administrative listen port is configured when the Gateway is first set up (see Gateway System Settings (Appliance). After this, you use the Manage Listen Ports task to add, modify, or delete ports.
Changes to the listen ports propagate through a Gateway cluster within 30 seconds—new ports are effective within 30 seconds, while deleted ports should be unavailable after 30 seconds or when the last "keep-alive" connection closes, whichever is later. A Gateway restart is not required after listen port changes.
You can only modify listen ports that the Policy Manager is not currently connected to.
Policy Manager Port Requirements
A listen port for the Policy Manager was defined when the Gateway was configured. If you need to create a new listen port, it must conform to the following characteristics:
  • must be above port 1024
  • must be SSL
  • must not require a client certificate
  • must have one of the following options enabled: [
    Policy Manager access
    ] for the standard client, or [
    Browser-based administration
    ] for the browser client; these are set in the [
    Basic Settings
    ] tab of the listen port properties
Configuring listen ports is intended for advanced technical users. The default values delivered with the Gateway should be adequate in most cases.
To manage listen ports
:
  1. In the Policy Manager, select
    [Tasks] > Transports > Manage Listen Port
    from the Main Menu (on the browser client, from the Manage menu).
    The Manage Listen Ports dialog appears.
    (1) Listen ports shown in red text indicate a possible conflict with another port. (2) Though the Manage Listen Ports dialog allows you to delete the predefined listen ports, you must ensure that the features are enabled in some other listener to ensure correct Gateway functionality.
  2. The following table describes each column (these are set in the listening port's properties):
    Column
    Description
    Enabled
    Indicates whether the port is enabled for listening. If disabled, the Gateway treat the port as if it was removed from the system.
    The listen port is enabled or disabled in the [Basic Settings] tab of the Listen Port Properties.
    Name
    The "friendly" name given to the port. This name is used only for logging and display purposes. The name is defined in the [
    Basic Settings
    ] tab of the Listen Port Properties.
    Protocol
    Indicates the transport protocol used by the listener. The following protocols are available:
    • HTTP
      : This is the standard HTTP interface to the Gateway. All available IP addresses are used, over port 8080.
    • HTTP2:
      This endpoint provides unsecured transport via HTTP/2 protocol.
    • HTTP2 (Secure):
      This endpoint provides secured transport via HTTP/2 protocol.
    • HTTPS
      : This is the SSL interface to the Gateway, used during mutual authentication. All available IP addresses are used, over port 8443.
    • HTTPS (no client authentication)
      : This endpoint is the same as the SSL Endpoint without client certificate challenges. All available IP addresses are used, over port 9443.
    • FTP
      : This endpoint provides unsecured transport, similar to HTTP.
    • FTPS
      : This endpoint provides secured transport, similar to HTTPS.
    • SSH2
      : This endpoint provides secured transport via the SSH2 protocol.
    Note:
    For HTTPS and FTPS, we recommend that you disable
    TLS 1.0
    and
    TLS 1.1
    .
    The protocols are defined in the [
    Basic Settings
    ] tab of the Listen Port Properties.
    Interface
    Lists the interfaces used by the listen port. This is configured in the [
    Basic Settings
    ] tab of the Listen Port Properties.
    Port
    The port number being monitored. Ports 1 to 1024 are reserved by the Gateway. The port number is specified in the [
    Basic Settings
    ] tab of the Listen Port Properties.
    If the Policy Manager is connected to a software form factor of the Gateway , you must ensure that the firewall protecting the Gateway y host machine permits traffic through the ports specified here.
    For a list of the ports required, consult the  file <Gateway_home>/var/firewall_rules on the Gateway machine. This file is a standard Linux firewall configuration file that can be used to automatically adjust the firewall if you are using the Linux RHEL version of the Gateway.
    If the Policy Manager will be connecting to the Gateway using a port other than the default 8443, the port number must be appended to the Gateway name. For more information, see Start the Policy Manager.
  3. Select a task to perform:
    To...
    Do this...
    Add a new listen port
    1. Click [
      Create
      ].
    Clone an existing listen port
    1. Select the port to clone.
    2. Click [
      Clone
      ].
    3. Edit the Listen Port Properties as required.
    Remove a listen port
    1. Select the port to remove.
    2. Click [
      Remove
      ].
    View or edit the properties of a listen port
    1. Select the port to view.
    2. Click [
      Properties
      ]. See Listen Port Properties for details.
    Manage interfaces
    Click [
    Interfaces
    ]. See Manage Interfaces for details.
    Manage Firewall Rules
    Click [
    Manage Firewall Rules
    ]. See Manage Interfaces for details.
    Configure how services are resolved
    Click [
    Service Resolution
    ]. See Manage Service Resolution for details.
    You cannot remove or modify the port currently used to administer the Gateway. To move the admin listener to another port:
    1) Create a new admin listener on the new port.
    2) Reconnect the Gateway on the new port.
    3) Remove the old admin listener.
  4. Click [
    Close
    ] when done.