sp_listener

Dynamically starts and stops SAP ASE listeners on any given port on a per-server basis.

Considerations for process mode

When executed in process mode, sp_listener dynamically starts and stops SAP ASE listeners on any given port on a per-engine basis.

Syntax

For threaded mode, the syntax is:

sp_listener “command”, “server_name | network”

Or:

sp_listener “command”, ‘[protocol:]machine:port:”CN=common_name”’

For process mode, the syntax is:

sp_listener “command”, “server_name | network”, engine | remaining

Or:

sp_listener “command”, ‘[protocol:]machine:port:”CN=common_name”’, engine

Parameters

command – can be any of:
- start – starts a listener on the specified ports on each of the specified servers.
- stop – terminates the specified listeners.
- suspend – prevents the listener from accepting any more connections.
- resume – instructs suspended listeners to resume listening.
- status – report on the state of the listeners specified by the parameters. The state is one of: active, stopped, or suspended.
  
  If your system is enabled for IPV6, the SAP ASE server encloses the listener name in brackets in the output.
- help – displays the sp_listener syntax.
server_name | network – is the name of the SAP ASE server, as specified in the interfaces file, or the name of the network.
engine – (Used only in process mode) specifies the number of the engine affected by this command. engine can be a single-engine number in quotes (“2”), a list (“3,5,6”), a range (“2 – 5”), or mix of all (“2,3 – 5,7”).
Note: Windows ignores the engine parameter.
remaining – specifies that the command is to take effect on all engines on which it can be meaningfully applied (that is, where the listener is in a state in which the command is can take effect).
protocol – the type of protocol; one of: afunix, tcp, tli, ssltcp, ssltli, winsock, sslnlwnsck, sslwinsock.
machine:port – the machine name and port number (as specified in the interfaces file) to which the listener connects.
CN=common_name – specifies a common name for the SSL certificate.
Use CN=common_name only if you specify ssltcp as the protocol. The SAP ASE server validates the common_name you specify against the common_name in the SSL certificate. If you do not include CN=common_name, the SAP ASE server uses server_name to validate against the common name in the SSL certificate. If you include a fully qualified domain name in the certificate, it must match CN=common_name.

Examples

Example 1 – Start listeners for each master entry in the interfaces file corresponding to server orion:
```
sp_listener "start", "orion"
```
Example 2 – Create TCP listeners for port number 4226:
```
sp_listener "start", "goldie:4226"
```
Example 3 – Create listeners for all master entries in the interfaces file for server orion:
```
sp_listener "start", "orion", "remaining"
```
Example 4 – Start TCP listeners on port 4226 on machine goldie for all engines not already listening to this port:
```
sp_listener "start", "goldie:4226", "remaining"
```

Example 5 – Specify the common name ase1.big server 1.com:

sp_listener 'start','ssltcp:blade1:17251:
"CN=ase1.big server 1.com"','0'

Example 6 – Stop the listener on port number 4226:
```
sp_listener "stop", "tcp:goldie:4226"
```
Example 7 – Stop all listeners on port number 4226. Because this command includes the remaining parameter, it does not fail if some engines are not listening to the port:
```
sp_listener "stop", "tcp:goldie:4226", "remaining"
```
Example 8 – Suspend Winsock listener on port 4226:
```
sp_listener "suspend", "winsock:clouds:4226"
```
Example 9 – Resume all active listeners on port number 4226:
```
sp_listener "resume", "tcp:goldie:4226", "remaining"
```
Example 10 – Start a named pipe listener using AF_UNIX communication.
```
sp_listener "start", "afunix:big_server:/tmp/big_pipe"
```

Usage

There are additional considerations when using sp_listener:

sp_listener uses either of two syntaxes, described in the syntax section, above. The first syntax affects all SAP ASE master ports listed in the interfaces file. The second allows you to manage listeners not listed in the interfaces file.
The attribute name “CN” is case-insensitive (it can be “CN”, “cn” or “Cn”), but the attribute value for the common name is case-sensitive.
sp_listener ignores the engine parameter if you include it while running in threaded mode.
The semantics for sp_listener is atomic; if a command cannot be completed successfully, it is aborted.
When the host component of a sp_listener command is an IPv6 address, it should be encloded in brackets. For example, tcp:[2001:ec8:4008:1::123]:80
You can issue the status parameter by itself. The status parameter displays the state of all the listeners in the interfaces file.
A listener can be in one of the following states: stopped, suspended, or active. sp_listener allows you to move listeners between these states. A request to move to a nonpermissible state results in failure (For example, requesting to stop a non existent listener). Use sp_listener “status” to determine the state of a listener.
The remaining parameter specifies that, for the command you are running (start, stop, resume, and so on), the command runs successfully for all listeners that are in a state that allow the change (for example, moving states from start to stop). For example, if you attempt to start listeners on engines one through six, but engines one, four, and five are unavailable, sp_listener... “remaining” starts listeners on engines two, three, and six, disregarding the offline engines. You cannot specify an engine number if you include the remaining parameter.
The maximum number of listeners is 32. If you create an SAP ASE server with two master ports in the interfaces file, you can start at most 30 more listeners on other ports.

For limitations related to IPV6 in sp_listener, see Specifying a Common Name in the Security Administration Guide.

Permissions

The permission checks for sp_listener differ based on your granular permissions settings.

Setting	Description
Enabled	With granular permissions enabled, you must be a user with`manage server` privilege.
Disabled	With granular permissions disabled, you must be a user with sa_role.

Auditing

Values in event and extrainfo columns from the sysaudits table are:

Information	Values
Event	38
Audit option	exec_procedure
Command or access audited	Execution of a procedure
Information in `extrainfo`	Roles – Current active roles Keywords or options – NULL Previous value – NULL Current value – NULL Other information – All input parameters Proxy information – Original login name, if set proxy in effect