10 Managing Listeners

Connections between the clients and Oracle Traffic Director instances are created through HTTP and TCP listeners. Each listener is a unique combination of an IP address (or host name) and a port number.

This chapter describes how to create, view, modify, and delete listeners. It contains the following topics:

Creating a Listener

You can create listeners by using either the administration console or the CLI.

Note:

When you create a listener, you are, in effect, modifying a configuration. So for the new listener settings to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.
The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Before You Begin

Before you begin creating an listener, decide the following:

A unique name for the listener. Choose the name carefully; after creating a listener, you cannot change its name.
A unique IP address (or host name) and port number combinations for the listener.

You can define multiple listeners with the same IP address combined with different port numbers, or with a single port number combined with different IP addresses. So each of the following IP address and port number combinations would be considered a unique listener:
```
10.10.10.1:80
10.10.10.1:81
10.10.10.2:80
10.10.10.2:81
```
For HTTP listeners: The default virtual server for the listener.

Oracle Traffic Director routes requests to the default virtual server if it cannot match the Host value in the request header with the host patterns specified for any of the virtual servers bound to the listener.

For information about specifying the host patterns for virtual servers, see Creating a Virtual Server.
For HTTP listeners: The server name to be included in any URLs that are generated automatically by the server and sent to the client. This server name should be the virtual host name, or the alias name if your server uses an alias. If a colon and port number are appended to the server name then that port number is used in the autogenerated URLs.
For TCP listeners: TCP proxy for the listener.

A TCP proxy handles TCP requests through TCP listeners for traffic tunnelling. A TCP proxy can have several TCP listeners associated with it. You can associate TCP listeners and configure TCP proxy settings from this page.

For more information about creating TCP proxies, see Creating a TCP Proxy.

Creating an HTTP Listener Using the Administration Console

To create an HTTP listener by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to create an HTTP listener.
In the Common Tasks pane, click New HTTP Listener.

The New HTTP Listener wizard starts.

Figure 10-1 New HTTP Listener Wizard

Description of "Figure 10-1 New HTTP Listener Wizard"
Follow the on-screen prompts to complete creation of the HTTP listener by using the details—listener name, IP address, port, and so on—that you decided earlier.

Note:

If certificates are available in the configuration, in the second screen of the wizard, an SSL/TLS check box will be available. If you want the new listener to receive HTTPS requests, click the check box to enable SSL/TLS and then select the appropriate certificate from the drop-down list.

After the HTTP listener is created, the Results screen of the New HTTP Listener wizard displays a message confirming successful creation of the listener.
Click Close on the Results screen.
- The details of the listener that you just created are displayed on the Listeners page.
- In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Deploying a Configuration.

Creating a TCP Listener Using the Administration Console

To create a TCP listener by using the administration console, do the following:

Perform steps 1, 2, and 3 of Creating an HTTP Listener Using the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to create a TCP listener.
In the Common Tasks pane, click New TCP Listener.

The New TCP Listener wizard starts.

Figure 10-2 New TCP Listener Wizard

Description of "Figure 10-2 New TCP Listener Wizard"
Follow the on-screen prompts to complete creation of the TCP listener by using the details—listener name, IP address, port, and so on—that you decided earlier.

Note:

If certificates are available in the configuration, in the second screen of the wizard, an SSL/TLS check box will be available. If you want the new listener to receive T3S requests, click the check box to enable SSL/TLS and then select the appropriate certificate from the drop-down list.

After the TCP listener is created, the Results screen of the New TCP Listener wizard displays a message confirming successful creation of the listener.
Click Close on the Results screen.
- The details of the listener that you just created are displayed on the Listeners page.
- In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Deploying a Configuration.

Creating a Listener Using the CLI

To create an HTTP listener, run the create-http-listener command.

For example, the following command creates an HTTP listener named listener_soa for the configuration soa.example.com with the port as 1910 and the default virtual server as soa.
```
tadm> create-http-listener --config=soa.example.com --listener-port=1910 --server-name=soa.example.com --default-virtual-server-name=soa listener_soa
OTD-70201 Command 'create-http-listener' ran successfully.
```
To create a TCP listener, run the create-tcp-listener command.

For example, the following command creates a TCP listener named tcp_listener_soa for the configuration soa.example.com with the port as 1920 and the TCP Proxy as tcp_proxy1.
```
tadm> create-tcp-listener --config=soa.example.com --listener-port=1920 --server-name=soa.example.com --tcp-proxy=tcp_proxy1 listener_soa
OTD-70201 Command 'create-tcp-listener' ran successfully.
```

For more information about create-http-listener and create-tcp-listener, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

Viewing a List of Listeners

You can view a list of HTTP or TCP listeners by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Viewing a List of Listeners Using the Administration Console

To view a list of HTTP or TCP listeners by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to view HTTP or TCP listeners.
In the navigation pane, expand Listeners, and select a listener.

The Listeners page is displayed. It shows a list of the listeners defined for the configuration.

Note:

HTTP and TCP listeners can also be identified by their icons.

You can view the properties of a listener in detail by clicking on its name.

Viewing a List of Listeners Using the CLI

To view a list of HTTP listeners, run the list-http-listeners command, as shown in the following example:
```
tadm> list-http-listeners --config=soa --verbose --all
name          ip       port    ssl-enabled     default-virtual-server
-----------------------------------------------------------------------
listener-1    *        1904       false           vs1
listener-2    *        80         false           vs1
```
You can view the properties of an HTTP listener in detail by running the get-http-listener-prop command.

For more information about the list-http-listeners and get-http-listener-prop commands, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

To view a list of TCP listeners, run the list-tcp-listeners command, as shown in the following example:
```
tadm> list-tcp-listeners --config=soa --verbose --all
name          ip         port            ssl-enabled             tcp-proxy-name
------------------------------------------------------------------------
listener-1    *          9090         false                    tcp_proxy1
listener-2    *          9092         false               tcp_proxy1
```
You can view the properties of an TCP listener in detail by running the get-tcp-listener-prop command.

For more information about the list-tcp-listeners and get-tcp-listener-prop commands, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Modifying a Listener

You can modify listeners by using either the administration console or the CLI.

Note:

When you modify a listener, you are, in effect, modifying a configuration. So for the new settings of a listener to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.
The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Modifying a Listener Using the Administration Console

To modify an HTTP or TCP listener by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to modify listeners.
In the navigation pane, click Listeners.

The Listeners page is displayed. It shows a list of the HTTP/TCP listeners defined for the configuration.
Click the name of the listener that you want to modify.
The Listener Settings page is displayed. On this page, you can do the following:
- Enable and disable the listener.
- Change the listener port number and IP address.
- For HTTP listeners: Change the server name and the default virtual server.
- For TCP listeners: Change the TCP proxy.
- If server certificates have been created for the configuration, you can enable SSL/TLS and configure SSL/TLS settings for the listener. For more information, see Configuring SSL/TLS for a Listener.
- Change the protocol family—IPv4, IPv6, or SDP—for which the listener should accept requests.
- For HTTP listeners: Configure parameters to tune the performance of the virtual server—the number of acceptor threads, the listen queue size, receive buffer size, and so on. For more information, see Tuning HTTP Listener Settings.
Specify the parameters that you want to change.

On-screen help and prompts are provided for all of the parameters.

When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

At any time, you can discard the changes by clicking the Reset button.
After making the required changes, click Save.
- A message, confirming that the updated listener was saved, is displayed in the Console Messages pane.
- In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Modifying a Listener Using the CLI

To change the properties of an HTTP listener, run the set-http-listener-prop command. For example, the following command changes the port number of the listener ls1 in the configuration soa to 1911.
```
tadm> set-http-listener-prop --config=soa --http-listener=ls1 port=1911
OTD-70201 Command 'set-http-listener-prop' ran successfully.
```
To change the SSL/TLS settings of an HTTP listener, run the set-ssl-prop command. For example, the following command enables SSL 3.0 support for the listener ls1 in the configuration soa.
```
tadm> set-ssl-prop --config=soa --http-listener=ls1 ssl3=true
OTD-70201 Command 'set-ssl-prop' ran successfully.
```
To change the properties of a TCP listener, run the set-tcp-listener-prop command. For example, the following command changes the port number of the listener tcp_ls1 in the configuration soa to 1911.

```
tadm> set-tcp-listener-prop --config=soa --tcp-listener=tcp_ls1 listen-queue-size=238
OTD-70201 Command 'set-tcp-listener-prop' ran successfully.
```
To change the SSL/TLS settings of an TCP listener, run the set-ssl-prop command. For example, the following command enables SSL 3.0 support for the listener tcp_ls1 in the configuration soa.

tadm> set-ssl-prop --config=soa --tcp-listener=ls1 ssl3=true
OTD-70201 Command 'set-ssl-prop' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For a list of the properties that you can set or change by using the set-tcp-listener-prop and set-ssl-prop commands, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Deleting a Listener

You can delete HTTP or TCP listeners by using either the administration console or the CLI.

Note:

When you delete a listener, you are, in effect, modifying a configuration. So for the updated configuration to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.
The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Deleting a Listener Using the Administration Console

To delete an HTTP or TCP listener by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to delete listeners.
In the navigation pane, select Listeners.

The Listeners page is displayed. It shows a list of the listeners defined for the configuration.
Click the Delete icon for the listener that you want to delete.

A prompt to confirm deletion of the listener is displayed.

Note:

For HTTP listeners: If the HTTP listener is associated with any virtual servers, the prompt shows the names of those virtual servers.
To proceed with the deletion, click OK.

A message is displayed in the Console Message pane confirming that the HTTP/TCP listener was deleted.

In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Deploying a Configuration.

Deleting a Listener Using the CLI

To delete an HTTP listener, run the delete-http-listener command, as shown in the following example:

tadm> delete-http-listener --config=soa http-listener-1
OTD-70201 Command 'delete-http-listener' ran successfully.

To delete an TCP listener, run the delete-tcp-listener command, as shown in the following example:

tadm> delete-tcp-listener --config=soa tcp-listener-1
OTD-70201 Command 'delete-tcp-listener' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about delete-http-listener and delete-tcp-listener, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.