About Listeners

Learn how to add and modify listeners for an API Gateway or API Gateway Cluster.

Overview
Supported Listener Types
Adding a Listener
Listener configuration: HTTP
Listener configuration: HTTPS
"Bind to all interfaces" setting on HTTP/HTTPS listeners
Listener configuration: JMS
Listener configuration: AMQP
Listener configuration: AMQPS

Overview

In general, a listener is an object that executes some code when triggered by an event. A listener monitors events happening in the program and acts based on how it's programmed to act in certain events.

In the context of the API platform, a listener is the server process that listens for and accepts incoming connection requests from client applications. Listeners are added to an API Gateway or an API Gateway cluster; they are then mapped based on matching listener names.

Supported Listener Types

Policy Manager supports the following listener types:

HTTP
HTTPS
JMS
AMQP
AMQPS

Adding a Listener

Follow the procedure below to add a listener. Refer to the applicable section for details about how to configure a specific listener type, or use the help to the left of the page.

To add a listener

Log in to Policy Manager.
Navigate to the Containers folder: Workbench > Browse > Organization > Containers. The Containers summary page is displayed, as shown below.
Click to select the container you want to add a listener for. The Container Overview page is displayed, with a summary of information about the current container. The Inbound Listeners Portlet displays the current listener configuration, as shown below.
Click Add Container Listener. The Select Container Listener Type page is displayed.
Choose a listener type from the drop-down list and click Next. The Configure page for the specified listener type is displayed.
In the top section, configure the general listener properties (these are the same for all listener types):
- Listener Name—A unique instance name for the listener.
- Description—A short description for the listener.
In the second section, configure the listener properties based on your specific requirements. This section is different for each listener type. For information about specific configuration fields, refer to the applicable section:
- HTTP
- HTTPS
- JMS
- AMQP
- AMQPS
HTTP, HTTPS, and JMS only: Configure thread pool values. For information about the thread pool, and valid values, see Thread Pool below.
HTTP and HTTPS only: In the Service Hosting section, choose to clone services, if needed. For more information, see Service Hosting below.
Note: Once you've saved the listener configuration, you cannot change the Service Hosting setting.
Click Finish.

Listener configuration: HTTP

Many of the listener configuration fields, such as name/description and thread pool fields, are the same for multiple listener types. These are briefly defined in the procedure above (see Adding a listener step 8).

HTTP listener

The center section of each listener page includes values specific to the individual listener. For HTTP listeners, those fields are defined below. You can also use the help to the left of the page.

Bind to all interfaces: Based on your network infrastructure and security requirements, it might be better to configure the listener to bind the specified port to all network interfaces, or only the configured one IP address/hostname:port and not others.; Checked: The container listener is configured to listen to all network interfaces through one port.; Cleared: The container listener listens through one port only.; Note: Not choosing the Bind to all interfaces option can potentially cause hostname lookup issues. For more information, see "Bind to all interfaces" setting on HTTP/HTTPS listeners below.
Host Name: The Host Name portion of the Listener URL.
Port Number: The Port Number portion of the Listener URL.
Context Path: The Context Path portion of the Listener URL. Entering a Context Path is optional. This field only displays for Network Director containers and legacy containers.; Note: The Context Path only applies to services hosted in the container. It does not refer to or change the path of the Akana Policy Manager Console or the Akana Administration Console associated with a container.; The Host Name, Port Number, and Context Path combined represent the full URL. The URL represents the name or address of the machine on which the container is running. Be sure to use a name or IP address that will be recognizable to all computers that will be accessing this container. For example, if computers outside your network will be using the container, use a fully-qualified domain name or an IP address that is visible and accessible outside the network.
Thread Pool: The thread pool is used to manage the thread configuration for the estimated volume of transactions that will be processed through your production site. Each request requires one thread. If the thread pool configuration is configured with a maximum thread pool size of 256, the container will support 256 concurrent requests. If more concurrent requests are required in a container, the thread pool configuration for the specific listener can be updated within the container. The initial display shows default values. Thread pool settings:; Minimum: The minimum number of threads that are reserved for requests from applications. Default: 5.; Maximum: The maximum number of threads that are reserved for requests from applications. Default: 500.; Idle Thread Timeout (mls): The number of milliseconds after which idle threads are removed from the thread pool. Default: 180,000 (3 minutes).; Note: The thread pool is dynamically adjusted between the minimum and maximum values. The minimum thread pool setting signals the server to allocate at least that many threads in reserve for application requests. That number is increased up to the maximum specified thread pool size.
Service Hosting: HTTP and HTTPS only: If you want to clone services hosted on other listeners to match the services hosted on the current listener, check the Clone services hosted on other listener(s) checkbox, and then select a listener type out of available options. Possible choices: All Listeners, the default HTTP listener, or selected listeners that you have defined.; If you're adding a new PM/CM listener, unless you specifically do not want all the services to be available on the new listener, it's best to check this box. For example, if you will be running the Community Manager developer portal, the services are required.

Listener configuration: HTTPS

HTTPS listener

The center section of each listener page includes values specific to the individual listener. For HTTPS listeners, those fields are defined below. The fields are essentially the same as for an HTTP listener, with the addition of the Client Certificates field.

You can also use the help to the left of the page.

Note: in order to set up a secure listener, you must have existing keys/certificates. See Managing Keys and Certificates.

Bind to all interfaces

Based on your network infrastructure and security requirements, it might be better to configure the listener to bind the specified port to all network interfaces, or only the configured one IP address/hostname:port and not others.

Checked: The container listener is configured to listen to all network interfaces through one port.

Cleared: The container listener is limited to listen through one port.

Note: Not choosing the Bind to all interfaces option can potentially cause hostname lookup issues. For more information, see "Bind to all interfaces" setting on HTTP/HTTPS listeners below.

Host Name

The Host Name portion of the Listener URL.

Port Number

The Port Number portion of the Listener URL.

Context Path

The Context Path portion of the Listener URL. Entering a Context Path is optional. This field only displays for Network Director containers and legacy containers.

Note: The Context Path only applies to services hosted in the container. It does not refer to or change the path of the Akana Policy Manager Console or the Akana Administration Console associated with a container.

The Host Name, Port Number, and Context Path combined represent the full URL. The URL represents the name or address of the machine on which the container is running. Be sure to use a name or IP address that will be recognizable to all computers that will be accessing this container. For example, if computers outside your network will be using the container, use a fully-qualified domain name or an IP address that is visible and accessible outside the network.

Client Certificates

Defines behavior with regard to client certificates. Choices:

ignore
accept
require

If you choose accept or require, you'll see additional fields for inbound and outbound certificates, where you can select and upload a certificate to include in your container configuration.

Thread Pool

Same as for an HTTP listener. See Thread Pool above.

Service Hosting

Same as for an HTTP listener. See Service Hosting above.

"Bind to all interfaces" setting on HTTP/HTTPS listeners

If you're configuring an HTTP or HTTPS listener, you have the option to bind the listener to all interfaces.

The listener always listens on a specific port. The server/container might have multiple interfaces; for example, multiple IP addresses or hostnames. If Bind to all interfaces is checked, the listener listens on all IP addresses/hostnames for the specific port. If it is not checked, the listener listens only on the IP address/hostname and port specified in the configuration.

Note: Not choosing the Bind to all interfaces option can potentially cause hostname lookup issues (HTTP 404 or 405 errors) when calling the services hosted on the container.

Listener configuration: JMS

Note: If you're using a JMS listener you'll need to deploy the correct JAR file provided by your JMS vendor, in the /deploy/ folder. See JMS Configuration.

JMS listener

The center section of each listener page includes values specific to the individual listener. For JMS listeners, those fields are defined below. You can also use the help to the left of the page.

JNDI URL: Enter the URL where the Java Naming and Directory Interface (JNDI) server can be accessed.
JNDI Initial Context: Enter the starting point for resolution of names for naming and directory operations.
JMS Destination Factory Name: Enter a topic name or queue with a physical resource for the Java Message Service (JMS) Destination Factory.
Connection Properties: Optional, user-defined additional properties that allow you to specify the messaging engine that an application will connect to. Only message properties of type String are supported. To configure a connection property, define a Name and Value. You can also remove an existing property and/or add a new one.

Listener configuration: AMQP

Many of the listener configuration fields, such as name/description, are the same for all listener types. These are briefly defined in the procedure above (see Adding a listener).

AMQP listener

The center section of each listener page includes values specific to the individual listener. For AMQP listeners, those fields are defined below. You can also use the help to the left of the page.

AMQP Version: Supported versions include 1.0, 0.9.1, and 0.9.
Virtual Host Name: The virtual host name of the AMQP broker.
Host: The host name. You can also remove an existing host and/or add a host.
Port: Displays the default port, 5672, used for AMQP connections.
Authentication Required: If the AMQP binding will be used to authenticate an AMQP registry where AMQP destinations or targets are located, or to authenticate the AMQP system itself, authentication might be required. To enable authentication, select the checkbox and specify the Identity Source, Username, and Password.
Connection Properties: Optional, user-defined additional properties that allow you to specify the messaging engine that an application will connect to. Only message properties of type String are supported. Connection Properties are configured by entering a "Property Name" and "Property Value. You can enter unlimited connection properties.

Listener configuration: AMQPS