Configuring Session Agents

To configure session agents:

In Superuser mode, type configure terminal and press Enter.
```
ORACLE# configure terminal
```
Type session-router and press Enter to access the system-level configuration elements.
```
ORACLE(configure)# session-router
```
Type session-agent and press Enter. The system prompt changes to let you know that you can begin configuring individual parameters.
```
ORACLE(session-router)# session-agent
ORACLE(session-agent)#
```
host-name—Enter the name of the host associated with the session agent in either hostname or FQDN format, or as an IP address.

If you enter the host name as an IP address, you do not have to enter an IP address in the optional IP address parameter. If you enter the host name in FQDN format, and you want to specify an IP address, enter it in the optional IP address parameter. Otherwise you can leave the IP address parameter blank to allow a DNS query to resolve the host name.

If the initial DNS query for the session agent fails to get back any addresses, the session agent is put out-of-service. When session agent is pinged, the DNS query is repeated. The ping message is not sent until the DNS query gets back one or more IP addresses. After the query receives some addresses, the ping message is sent. The session agent remains out of service until one of the addresses responds.

Note:
The value you enter here must be unique to this session agent. No two session agents can have the same hostname.

The hostnames established in the session agent populate the corresponding fields in other elements.
ip-address—Optional. Enter the IP address for the hostname you entered in FQDN format if you want to specify the IP address. Otherwise, you can leave this parameter blank to allow a DNS query to resolve the host name.
port—Enter the number of the port associated with this session agent. Available values include:
- zero (0)—If you enter zero (0), the Oracle® Enterprise Session Border Controller will not initiate communication with this session agent (although it will accept calls).
- 1025 through 65535
  
  The default value is 5060.
  
  Note:
  If the transport method value is TCP, the Oracle® Enterprise Session Border Controller will initiate communication on that port of the session agent.
state—Enable or disable the session agent by configuring the state. By default, the session agent is enabled.
- enabled | disabled
app-protocol—Enter the protocol on which you want to send the message. The default value is SIP. Available values are:
- SIP | H.323
app-type—If configuring H.323, indicate whether the application type is a gateway or a gatekeeper. Available values include:
- H.323-GW—gateway
- H.323-GK—gatekeeper
transport-method—Indicate the IP protocol to use (transport method) to communicate with the session agent. UDP is the default value. The following protocols are supported:
- UDP—Each UDP header carries both a source port identifier and destination port identifier, allowing high-level protocols to target specific applications and services among hosts.
- UDP+TCP—Allows an initial transport method of UDP, followed by a subsequent transport method of TCP if and when a failure or timeout occurs in response to a UDP INVITE. If this transport method is selected, INVITEs are always sent through UDP as long as a response is received.
- DynamicTCP—dTCP indicates that dynamic TCP connections are the transport method for this session agent. A new connection must be established for each session originating from the session agent. This connection is torn down at the end of a session.
- StaticTCP—sTCP indicates that static TCP connections are the transport method for this session agent. Once a connection is established, it remains and is not torn down.
- DynamicTLS—dTLS indicates that Dynamic TLS connections are the transport method for this session agent. A new connection must be established for each session originating from the session agent. This connection is torn down at the end of a session.
- StaticTLS—sTLS indicates that Static TLS connections are the transport method for this session agent. Once a connection is established, it will remain and not be torn down.
realm-id—Optional. Indicate the ID of the realm in which the session agent resides.

The realm ID identifies the realm for sessions coming from or going to this session agent. For requests coming from this session agent, the realm ID identifies the ingress realm. For requests being sent to this session agent, the realm ID identifies the egress realm. In a Oracle® Enterprise Session Border Controller, when the ingress and egress realms are different, the media flows must be steered between the realms.
- no value: the egress realm is used unless the local policy dictates otherwise
- asterisk (*): keep the egress realm based on the Request URI
  
  Note:
  The realm ID you enter here must match the valid identifier value entered when you configured the realm.
description—Optional. Enter a descriptive name for this session agent.
carriers—Optional. Add the carriers list to restrict the set of carriers used for sessions originating from this session agent.

Carrier names are arbitrary names that can represent specific service providers or traditional PSTN telephone service providers (for sessions delivered to gateways). They are global in scope, especially if they are exchanged in TRIP. Therefore, the definition of these carriers is beyond the scope of this documentation.

You could create a list using carrier codes already defined in the North American Numbering Plan (NANP); or those defined by the local telephone number or carrier naming authority in another country.

Note:
If this list is empty, any carrier is allowed. If it is not empty, only local policies that reference one or more of the carriers in this list will be applied to requests coming from this session agent.
allow-next-hop-lp—Indicate whether this session agent can be used as a next hop in the local policy.

If you retain the default value of enabled, the session agent can be used as the next hop for the local policy. Valid values are:
- enabled | disabled
constraints—Enable this parameter to indicate that the individual constraints you configure in the next step are applied to the sessions sent to the session agent. Retain the default value of disabled if you do not want to apply the individual constraints. Valid values are:
- enabled | disabled
  
  Note:
  In general, session control constraints are used for SAGs or SIP proxies outside or at the edge of a network.

Enter values for the individual constraints you want applied to the sessions sent to this session agent. The following table lists the available constraints along with a brief description and available values.

Constraint	Description
maximum sessions	Maximum number of sessions (inbound and outbound) allowed by the session agent. The range of values is: minimum: zero (0) is the default value and means there is no limit maximum: 4294967295
maximum outbound sessions	Maximum number of simultaneous outbound sessions (outbound from the Oracle® Enterprise Session Border Controller) that are allowed from the session agent. The range of values is: minimum: zero (0) is the default value and means there is no limit maximum: 4294967295 The value you enter here cannot be larger than the maximum sessions value.
maximum burst rate	Number of session invitations allowed to be sent to or received from the session agent within the configured burst rate window value. SIP session invitations arrive at and leave from the session agent in intermittent bursts. By entering a value in this field, you can limit the amount of session invitations that are allowed to arrive at and leave from the session-agent. For example, if you enter a value of 50 here and a value of 60 (seconds) for the burst rate window constraint, no more than 50 session invitations can arrive at or leave from the session agent in that 60 second time frame (window). Within that 60-second window, any sessions over the limit of 50 are rejected. The range of values is: minimum: zero (0) session invitations per second maximum: 4294967295 session invitations per second Zero is the is the default value.
maximum sustain rate	Maximum rate of session invitations (per second) allowed to be sent to or received from the session agent within the current window. The current rate is determined by counting the number of session invitations processed within a configured time period and dividing that number by the time period. By entering a value in this field, you can limit the amount of session invitations that are allowed to arrive at and leave from the session agent over a sustained period of time. For the sustained rate, the Oracle® Enterprise Session Border Controller maintains a current and previous window size. The period of time over which the rate is calculated is always between one and two window sizes. For example, if you enter a value of 5000 here and a value of 3600 (seconds) for the sustain rate window constraint, no more than 5000 session invitations can arrive at or leave from the session agent in any given 3600 second time frame (window). Within that 3600-second window, sessions over the 5000 limit are rejected. The range of values is: minimum: zero (0) invitations per second maximum: 4294967295 invitations per second Zero is the is the default value. The value you set here must be larger than the value you set for the maximum burst rate constraint.
time to resume	Time in seconds after which the SIP proxy resumes sending session invitations to this session agent. This value only takes effect when the SIP proxy stops sending invitations because a constraint is exceeded. The range of values is: minimum: zero (0) seconds maximum: 4294967295 seconds Default is zero.
time to resume (ttr) no response	Delay in seconds that the SIP proxy must wait from the time that it sends an invitation to the session agent and gets no response before it tries again. The range of values is: minimum: zero (0) seconds maximum: 4294967295 seconds Default is zero. The value you enter here must be larger than the value you enter for the time to resume constraint.
in service period	Amount of time in seconds the session agent must be operational (once communication is re-established) before the session agent is declared as being in-service (ready to accept session invitations). This value gives the session agent adequate time to initialize. The range of values is: minimum: zero (0) seconds maximum: 4294967295 seconds Default is zero.
burst rate window	Burst window period (in seconds) that is used to measure the burst rate. The term window refers to the period of time over which the burst rate is computed. Refer to the maximum burst rate information. The range of values is: minimum: zero (0) seconds maximum: 4294967295seconds Zero is the is the default value. The value you set here must be smaller than the value you set for the maximum burst rate constraint.
sustain rate window	Sustained window period (in seconds) that is used to measure the sustained rate. Refer to the maximum sustain rate information. The range of values is: minimum: zero (0) seconds maximum: 4294967295seconds Zero is the is the default value. The value you set here must be larger than the value you set for the maximum sustain rate constraint.

req-uri-carrier-mode—SIP only. Set whether you want the selected carrier (determined by a value in the local policy) added to the outgoing message by configuring the request uri carrier mode parameter.

You can set this parameter to let the system perform simple digit translation on calls sent to gateways. A 3-digit prefix is inserted in front of the telephone number (the Request-URI) that the gateway will use to select a trunk group. Most often, the Oracle® Enterprise Session Border Controller needs to insert the carrier code into the signaling message that it sends on.

The default value is none. The following lists the available modes.
- none—Carrier information will not be added to the outgoing message.
- uri-param—Adds a parameter to the Request-URI. For example, cic-XXX.
- prefix—Adds the carrier code as a prefix to the telephone number in the Request-URI (in the same manner as PSTN).
proxy-mode—SIP only. Indicate the proxy mode to use when a SIP request arrives from this session agent.

If this field is empty (upon initial runtime or upgrade), it’s value is set to the value of the SIP configuration’s proxy mode by default. If no proxy mode value was entered for the SIP configuration, the default for this field is proxy.

The following are valid proxy modes:
- proxy—If the Oracle® Enterprise Session Border Controller is a Session Router, the system will proxy the request coming from the session agent and maintain the session and dialog state. If the Oracle® Enterprise Session Border Controller is a Session Director, the system behaves as a B2BUA when forwarding the request.
- redirect—The system sends a SIP 3xx reDIRECT response with contacts (found in the local policy) to the previous hop.
redirect-action—SIP only. Indicate the action you want the SIP proxy to take when it receives a Redirect (3XX) response from the session agent.

If the response comes from a session agent and this field is empty (upon initial runtime or upgrade), the redirect action will be recurse. If no session agent is found (for example, if a message comes from an anonymous user agent), the redirect action is set to proxy. If the Redirect (3xx) response does not have any Contact header, the response will be sent back to the previous hop.

The following table lists the available proxy actions along with a brief description
- proxy—The SIP proxy passes the response back to the previous hop; based on the pfoxy mode of the original request.
- recurse—The SIP proxy serially sends the original request to the list of contacts in the Contact header of the response (in the order in which the contacts are listed in the response). For example, if the first one fails, the request will be send to the second, and so on until the request succeeds or the last contact in the Contact header has been tried.
loose-routing—SIP only. Enable this parameter if you want to use loose routing (as opposed to strict routing). The default is enabled. Valid values are:
- enabled | disabled
  
  When the SIP NAT route home proxy parameter is enabled, the Oracle® Enterprise Session Border Controller looks for a session agent that matches the home proxy address and checks the loose routing value. If loose routing is enabled, a Route header is included in the outgoing request in accordance with RFC 3261. If loose routing is disabled, the Route header is not included in the outgoing request (in accordance with strict routing procedures defined in RFC 2543).
  
  The loose routing value is also checked when the local policy’s next hop value matches a session agent. If loose routing is set to enabled, the outgoing request retains the original Request-URI and Route header with the next hop address.
send-media-session—SIP only. Enable this parameter if you want to include a media session description (for example, SDP) in the INVITE or REINVITE message sent by the Oracle® Enterprise Session Border Controller. Setting this field to disabled prevents the Oracle® Enterprise Session Border Controller from establishing flows for that INVITE message.

The default is enabled. Valid values are:
- enabled | disabled
  
  Note:
  Only set send media session to disabled for a session agent that always redirects requests. It returns an error or 3xx response instead of forwarding an INVITE message. In addition, do not disable send media session on session agents that support SIP-to-H.323 IWF call flows. This can cause call failure.
response-map—Optional and for SIP only. Enter the name of the response map to use for this session agent. The mappings in each SIP response map is associated with a corresponding session agent. You can also configure this value for individual SIP interfaces.
ping-method—SIP only. Indicate the SIP message/method to use to ping a session agent. The ping confirms whether the session agent is in service. If this field is left empty, no session agent will be pinged.

Setting this field value to the OPTIONS method might produce a lengthy response from certain session agents and could potentially cause performance degradation on your Oracle® Enterprise Session Border Controller.
ping-interval—SIP only. Indicate how often you want to ping a session agent by configuring the ping interval parameter. Enter the number of seconds you want the Oracle® Enterprise Session Border Controller to wait between pings to this session agent. The default value is 0. The valid range is:
- Minimum: 0
- Maximum: 999999999
  
  The Oracle® Enterprise Session Border Controller only sends the ping if no SIP transactions (have occurred to/from the session agent within the time period you enter here.
trunk-group—Enter up to 500 trunk groups to use with this single session agent. Because of the high number of trunk groups you can enter, the ACLI provides enhanced editing mechanisms for this parameter:
- You use a plus sign (+) to add single or multiple trunk groups to the session agent’s list.
  
  When you add a single trunk group, simply use the plus sign (+) in front of the trunk group name and context. Do not use a Space between the plus sign and the trunk group name and context.
  
  For example, you might have already configured a list of trunk groups with the following entries: tgrpA:contextA, tgrpB:contextB, and tgrpC:contextC. To add tgrp1:context1, you would make the following entry:
```
ORACLE(session-agent)# trunk-group +tgrp1:context1
```
  Your list would then contain all four trunk groups.
  
  When you add multiple trunk groups, simply enclose your entry in quotation marks () or in parentheses (()). While you put spaces between the trunk group name and context entries, you do not use spaces with the plus sign, parentheses or quotation marks.
```
ORACLE(session-agent)# trunk-group +tgrp1:context1 tgrp2:context2 tgrp3:context3
```
- You use a minus sign (-) to delete single or multiple trunk groups from the session agent’s list.
  
  When you remove a single trunk group, simply use the minus sign (-) in front of the trunk group name and context. Do not use a Space between the minus sign and the trunk group name and context.
  
  For example, you might have already configured a list of trunk groups with the following entries: tgrpA:contextA, tgrpB:contextB, tgrpC:contextC, and tgrp1:context1. To delete tgrp1:context1 from the list, you would make the following entry:
```
ORACLE(session-agent)# trunk-group -tgrp1:context1
```
  Your list would then contain: tgrpA:contextA, tgrpB:contextB, and tgrpC:contextC.
  
  When you add multiple trunk groups, simple enclose your entry in quotation marks () or in parentheses (()). While you put spaces between the trunk group name and context entries, you do not use spaces with the plus sign, parentheses or quotation marks.
```
ORACLE(session-agent)# trunk-group -tgrp1:context1 tgrp2:context2
```
- You overwrite (replace) the entire list of a session agent’s trunk groups by entering a list that does not use either the plus (+) or the minus (-) sign syntax.
ping-in-service-response-codes—SIP only. Enter the list of response codes that keep a session agent in service when they appear in its response to the Oracle® Enterprise Session Border Controller’s ping request. The Oracle® Enterprise Session Border Controller takes the session agent out of service should a response code be used that does not appear on this list. Default is none.
out-service-response-codes—SIP only. Enter the list defines the response codes that take a session agent out of service when they appear in its response to the Oracle® Enterprise Session Border Controller’s ping request or any in-dialog creating request (such as an INVITE, SUBSCRIBE, etc.). The Oracle® Enterprise Session Border Controller ignores this list if an in-service list exists.
options—Optional. You can add your own features and/or parameters by using the options parameter. You enter a comma-separated list of either or both of the following:
- feature=<value feature>
For example:

You can include the original address in the SIP message from the Oracle® Enterprise Session Border Controller to the proxy in the Via header parameter by entering the following option:

via-origin=<parameter-name>

The original parameter is included in the Via of the requests sent to the session agent. The via origin feature can take a value that is the parameter name to include in the Via. If the value is not specified for via origin, the parameter name is origin.

Note:
If the feature value itself is a comma-separated list, enclose it within quotation marks.
media-profiles—Optional and for H.323 only. You can enter a list of media profiles to open logical channels when starting an outgoing call as a Fast Start H.323 call.

Values you enter here must start with either an alphabetical character from A through Z (A-Za-z) or with an underscore (_). After the first character, each list entry can contain any combination of alphabetical or numerical characters (0-9A-Za-z), as well as the period (.), the dash (-), and the underscore (_). For example, netnet_mediaprofile1.

You can enter 1 to 24 characters.

Note:
The values you enter here must correspond to a valid name you entered when you configure the media profile.
in-translationid—Optional. Enter the In Translation ID for a configured session translation (group of address translation rules with a single ID) if you want to apply session translation to incoming traffic.
out-translationid—Optional. Enter the Out Translation ID for a configured session translation (group of address translation rules with a single ID) if you want to apply session translation to outgoing traffic.

Address translations attached to session agents take precedence over address translations attached to realms. If no address translation is applied to a session agent, then the Oracle® Enterprise Session Border Controller will use the address translation applied to a realm. If an address translation is applied to both a realm and session agent, the translation attached to the session agent will apply. If the applicable session agent and realm have no associated translations, then the addresses will remain in their original forms and no address translations will be performed.

trust-me—Indicate whether this session agent is a trusted source, which the Oracle® Enterprise Session Border Controller checks when it receives a message to determine if the source is trusted. The default value is disabled. The valid values are:

enabled | disabled

The following example shows a session agent with an IP address used for the hostname.

session-agent
        hostname                       192.168.1.10
        ip-address                     192.168.1.10
        port                           5060
        state                          enabled
        app-protocol                   SIP
        app-type
        transport-method               UDP
        realm-id                       realm-1
        description                    englab
        carriers
                                       carrier1
        allow-next-hop-lp              enabled
        constraints                    disabled
        max-sessions                   355
max-inbound-sessions           4
        max-outbound-sessions          355
        max-burst-rate                 0
        max-inbound-burst-rate         10
        max-outbound-burst-rate        1
        max-sustain-rate               3000
        max-inbound-sustain-rate       0
        max-outbound-sustain-rate      0
        min-seizures                   5
        min-asr                        0 time-to-resume                 60
        ttr-no-response                0
        in-service-period              30
        burst-rate-window              60
        sustain-rate-window            3600
        req-uri-carrier-mode           None
        proxy-mode                     Proxy
        redirect-action                Recurse
        loose-routing                  enabled
        send-media-session             enabled
        response-map
        ping-method
        ping-interval                  0
        media-profiles
        in-translationid
        out-translationid
        trust-me                       disabled
        request-uri-headers
        stop-recurse
        local-response-map
        ping-to-user-part
        ping-from-user-part
        li-trust-me                    disabled
        in-manipulationid
        out-manipulationid
        p-asserted-id
        trunk-group
        max-register-sustain-rate      0