1. ACLI Reference Guide
  2. ACLI Configuration Elements N-Z
  3. session-agent

session-agent

The session-agent element defines a signaling endpoint that can be configured to apply traffic shaping attributes and information regarding next hops or previous hops.

Parameters

hostname
Enter the hostname of this session agent. This is a required entry that must follow the Hostname (or FQDN) Format or the IP Address Format. Hostname values must be unique.
An IPV6 address is valid for this parameter.
ip-address
Enter the IP address of session agent if hostname value is an FQDN
An IPV6 address is valid for this parameter.
port
Enter the port number for this session agent.
  • Default: 5060
  • Values: Min: 0; 1025 | Max: 65535
state
Enable or disable the session agent
  • Default: enabled
  • Values: enabled | disabled
app-protocol
Select the signaling protocol used to signal with the session agent
  • Default: SIP
  • Values: H323 | SIP
app-type
Set the H.323 session agent type as a gateway or a gatekeeper. This field is mandatory if the app-protocol parameter is set to H323. If the app-protocol parameter is set to SIP, then this field must be left blank.
  • Values: H323-GW | H323-GK
transport-method
Select the IP protocol used for communicating with this session agent
  • Default: UDP
  • Values:
    • UDP—UDP used as the transport method
    • UDP+TCP—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, then INVITEs are always sent via UDP as long as a response is received.
    • DynamicTCP—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— Static TCP connections are the transport method for this session agent. Once a connection is established, it will remain and not be torn down.
    • StaticSCTP—SCTP is used as the transport method.
    • DynamicTLS—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— Static TLS connections are the transport method for this session agent. Once a connection is established, it will remain and not be torn down.
    • ANY—support all transport methods
realm-id
Enter the realm for sessions coming from or going to this session agent. Entries in this field must follow the Name Format. This field must correspond to a valid identifier field entry in a realm-config.
egress-realm-id
Enter the name of the realm you want defined as the default egress realm used for ping messages. The Oracle Communications Session Border Controller will also use this realm when it cannot determine the egress realm for normal routing.
description
Describe the session-agent element. Entries in this field must follow the Text Format.
carriers
Enter the carrier names associated with this session agent. 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. This list can contain as many entries within it as necessary. Entries in this field must follow the Carrier Format.
allow-next-hop-lp
Enable or disable the session agent as the next hop in a local policy
  • Default: enabled
  • Values: enabled | disabled
match-identifier
Match-identifier is a sub-element of session-agent. Configure the match-identifier parameters to identify the session-agent.
associated-agents
Enter the list of session-agents configured on the Oracle Communications Session Border Controller
constraints
Enable or disable the constraints established in this element in the fields that follow (maximum numbers of sessions allowed, maximum session rates, and timeout values) that are applied to the sessions sent to the session agent
  • Default: disabled
  • Values: enabled | disabled
max-sessions
Enter the maximum number of sessions allowed by the session agent; 0 means there is no constraint
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
max-inbound-sessions
Enter the maximum number of inbound sessions allowed from this session agent
  • Default: 0
  • Values: Min: 0 / Max: 999999999
max-outbound-sessions
Enter the maximum number of simultaneous outbound sessions that are allowed to the session agent; 0 means there is no constraint
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
max-burst-rate
Enter the number of session invitations per second allowed to be sent to or received from the session agent. A session is rejected if the calculated per-second rate exceeds this value.
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
max-inbound-burst-rate
Enter the maximum inbound burst rate in INVITEs per second from this session agent
  • Default: 0
  • Values: Min: 0 / Max: 999999999
max-outbound-burst-rate
Enter the maximum outbound burst rate in INVITEs per second
  • Default: 0
  • Values: Min: 0 / Max: 999999999
max-sustain-rate
Enter the maximum rate of session invitations per second allowed to or from the session agent within the current window. The period of time over which the rate is calculated is always between one and two window sizes. A session is rejected only if the calculated per-second rate exceeds the max-sustain-rate value. The value set for the max-sustain-rate field must be larger than the value set for the max-burst-rate field.
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
max-inbound-sustain-rate
Enter the maximum inbound sustain rate in INVITEs per second
  • Default: 0
  • Values: Min: 0 / Max: 999999999
max-outbound-sustain-rate
Enter the maximum outbound sustain rate in INVITEs per second
  • Default: 0
  • Values: Min: 0 / Max: 999999999
min-seizures
Enter the minimum number of seizures that, when exceeded, cause the session agent to be marked as having exceeded its constraints. Calls will not be routed to the session agent until the time-to-resume has elapsed.
  • Default: 5
  • Values: Min: 1 | Max: 999999999
min-asr
Enter the minimum percentage, that if the session agent’s ASR for the current window falls below this percentage, the session agent is marked as having exceeded its constraints and calls will not be routed to it until the time-to-resume has elapsed
  • Default: 0%
  • Values: Min: 0% /|Max: 100%
cac-trap-threshold
The CAC (session or burst-rate) utilization threshold expressed as a percent that when exceeded generates a trap
  • Default: 0
  • Values: Min: 0 / Max: 100
time-to-resume
Enter the number of seconds after which the SA (Session Agent) is put back in service (after the SA is taken out-of-service because it exceeded some constraint).
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
ttr-no-response
Enter the time delay in seconds to wait before the SA (Session Agent) is put back in service (after the SA is taken out-of-service because it did not respond to the Oracle Communications Session Border Controller).
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
in-service-period
Enter the time in seconds the session-agent must be operational (once communication is re-established) before the session agent is declared to be in-service. This value gives the session agent adequate time to initialize.
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
burst-rate-window
Enter the burst window period in seconds used to measure the burst rate. The term “window” refers to the period of time over which the burst rate is computed.
  • Default: 0
  • Values: Min: 0 | Max: 4294967295
sustain-rate-window
Enter the sustained window period in seconds used to measure the sustained rate. The term “window” refers to the period of time over which the sustained rate is computed.
  • Default: 0
  • Values: Min: 10 | Max: 4294967295
    The value you set here must be higher than or equal to the value you set for the burst rate window.

    Note:

    If you are going to use this parameter, you must set it to a minimum value of 10.
req-uri-carrier-mode
Select how a carrier determined by the local policy element should be added to the outgoing message
  • Default: None
  • Values:
    • None—Carrier information will not be added to the outgoing message
    • uri-param—Adds a parameter to the Request-URI (e.g., cic-XXX)
    • prefix—Adds the carrier code as a prefix to the telephone number in the Request-URI (in the same manner as is done in the PSTN)
proxy-mode
Select how SIP proxy forwards requests coming from the session agent. If this parameter is empty, its value is set to the value of the proxy-mode parameter in the sip-interface element by default. If the proxy-mode field in the element is also empty, the default is proxy.
  • Values
    • proxy—If the Oracle Communications Session Border Controller is an SR, the system will proxy the request coming from the session agent and maintain the session and dialog state. If the Oracle Communications Session Border Controller is a Oracle Communications Session Border Controller, system will behave as a B2BUA when forwarding the request.
    • redirect—System will send a SIP 3xx reDIRECT response with contacts (found in the local-policy) to the previous hop
    • record-route—The Oracle Communications Session Border Controller forwards requests with a record-route
redirect-action
Select the action the SIP proxy takes when it receives a Redirect (3xx) response from the session agent. If the response comes from a session agent and this field is empty, the system uses the redirect action value defined in the sip-interface.
  • Values:
    • proxy—SIP proxy passes the response back to the previous hop. The response will be sent based on the proxy-mode of the original request.
    • recurse—SIP proxy sends the original request to the list of contacts in the Contact header of the response, serially (in the order in which the contacts are listed in the response)
    • Recurse-305-only—recurse on the contacts in the 305 response
loose-routing
Enable or disable loose routing
  • Default: enabled
  • Values: enabled | disabled
send-media-session
Enable or disable the inclusion of a media session description in the INVITE sent by the Oracle Communications Session Border Controller. The only instance in which this field should be set to disabled is for a session agent that always redirects requests, meaning that it returns an error or 3xx response instead of forwarding an INVITE message. Setting this field to disabled prevents the Oracle Communications Session Border Controller from establishing flows for that INVITE message until it recurses the 3xx response.
  • Default: enabled
  • Values: enabled | disabled
response-map
Enter the name of the sip-response-map element set in the session router element to use for translating inbound final response values
ping-method
Enter the SIP message/method to use to “ping” a session agent
ping-interval
Set how often to ping a session agent in seconds
  • Default: 0
  • Values: Min: 0 | Max: 999999999
ping-send-mode
Set the mode with which you want to send ping messages to session agents
  • Default: keep-alive
  • Values: keep-alive | continuous
ping-all-addresses
Enable pinging each IP address dynamically resolved via DNS. If disabled (default), the Oracle Communications Session Border Controller only pings the first available resolved IP address.
  • Default: disabled
  • Values: enabled | disabled
options
Establish customer-specific features and/or parameters. This value can be a comma separated list of “feature=<value>" or "feature" parameters.
spl-options
Establish customer-specific features and/or parameters. This value can be a comma separated list of “feature=<value>" or "feature" parameters.
media-profiles
Start up an outgoing call as a Fast Start call with the information in the media profile used for the logical channels when the incoming call is slow start for an H.323 operation. This list is used to determine if a source and/or destination of a call is a session agent on that list. If a media profiles list is configured in the matching session-agent element, then the frame and codec information in the corresponding media profile will be used for the outgoing call. If the media-profiles list in the session-agent element is empty, the h323-stack > media-profiles list will be consulted. This field should reference the codec that you expect the gatekeeper/gateway to use. This media-profiles entry must correspond to at least one valid name field entry in a media profile element that has already been configured.
in-translationid
Enter the identifier/name of the configured session translation to apply. The Oracle Communications Session Border ControllerC applies this group of rules to the incoming leg of the call for this session agent. There can be only one entry in this field.
out-translationid
Enter the identifier/name of the configured session translation to apply. The Oracle Communications Session Border Controller applies this group of rules to the outgoing leg of the call for this session agent. There can be only one entry in this field.
trust-me
Enable or disable the trust of this session agent; used for privacy features
  • Default: disabled
  • Values: enabled | disabled
request-uri-headers
Enter a list of embedded headers extracted from the Contact header that will be inserted in the re INVITE message
stop-recurse
Enter a list of returned response codes that this session agent will watch for in order to stop recursion on the target’s or contact’s messages
local-response-map
Enter the name of local response map to use for this session agent. This value should be the name of a sip-response-map configuration element.
ping-to-user-part
The user portions of the Request-URI and To: headers that define the destination of a session agent ping message.
ping-from-user-part
The user portion of the From: header that defines the source of a session agent ping message.
ping-response
Enable the SBC to consider OPTIONS received as pings and respond locally for Teams deployments.
  • Default: disabled
  • Values: enabled | disabled
li-trust-me
Set this parameter to enabled to designate this session agent as trusted for P-DCS-LAES use
  • Default: disabled
  • Values: enabled | disabled
in-manipulationid
Enter the name of the SIP header manipulations configuration to apply to the traffic entering the Oracle Communications Session Border Controller via this session agent
out-manipulationid
Enter the name of the SIP header manipulations configuration to apply to the traffic exiting the Oracle Communications Session Border Controller via this session agent
p-asserted-id
Set the configurable P-Asserted-Identity header for this session agent. This value should be a valid SIP URI.
trunk-group
Enter trunk group names and trunk group contexts to match in either IPTEL or custom format; one session agent can accommodate 500 trunk groups. If left blank, the Oracle Communications Session Border Controller uses the trunk group in the realm for this session agent. Multiple entries are surrounded in parentheses and separated from each other with spaces. You can add and delete single entries from the list using plus (+) and minus (-) signs without having to overwrite the whole list.
Entries for this list must one of the following formats: tgrp:context or tgrp.context.
max-register-sustain-rate
Specify the registrations per second for this session agent. The constraints parameter must be enabled for this parameter to function.
  • Default: 0 (disabled)
  • Values: Min: 0 | Max: 4294967295
early-media-allow
Select the early media suppression for the session agent
  • Values:
    • none—No early media allowed
    • reverse—Allow early media in the direction of calling endpoint
    • both—Allow early media in both directions
invalidate-registrations
Enable or disable the invalidation of all the registrations going to this SA when its state transitions to “out of service”
  • Default: disabled
  • Values enabled | disabled
rfc2833-mode
Select whether 2833/UII negotiation will be transparent to the Oracle Communications Session Border Controller (pre-4.1 behavior), or use 2833 for DTMF
  • Default: none
  • Values:
    • none—The 2833-UII interworking will be decided based on the h323-stack configuration.
    • transparent—The session-agent will behave exactly the same way as before and the 2833 or UII negotiation will be transparent to the Oracle Communications Session Border Controller. This overrides any configuration in the h323-stack even if the stack is configured for “preferred” mode.
    • preferred—The session-agent prefers to use 2833 for DTMF transfer and would signal that in its TCS. However, the final decision depends on the remote H323EP.
rfc2833-payload
Enter the payload type used by the SA in preferred rfc2833-mode
  • Default: 0
  • Values: Valid Range: 0, 96-127

    Note:

    When this value is zero, the global “rfc2833-payload” configured in the H323 configuration element will be used instead. For SIP SA, the payload defined in the SIP Interface will be used, if the SIP-I is configured with rfc2833-mode as “preferred”.
  • Values: Min: 0 / Max: 999999999
codec-policy
Enter the codec policy you want to apply to this session agent
enforcement-profile
Enter the enforcement policy set of allowed SIP methods you want to use for this session agent
  • Default: None
  • Values: Name of a valid enforcement-profile element
refer-call-transfer
Enable or disable the refer call transfer feature for this session agent
  • Default: disabled
  • Values: enabled | disabled
refer-notify-provisional
Sends NOTIFY message after provisional messages are received in a REFER scenario.
  • Default: none
  • Values:
    • none—The system does not send any NOTIFY messages after receiving provisional messages.
    • initial—The system sends a NOTIFY, including 100 Trying, immediately after accepting the REFER.
    • all— The system sends an immediate 100 Trying NOTIFY and a NOTIFY for each non-100 provisional received.
reuse-connections
Enter the SIP TCP connection reuse mode. The presence of “reuse-connections” in the options field of the sip-interface will cause the Oracle Communications Session Border Controller to reuse all inbound TCP connections for sending rquests to the connected UA.
  • Default: tcp
  • Values: tcp | sctp | tls | none
tcp-keepalive
Enable or disable standard keepalive probes to determine whether or not connectivity with a remote peer is lost.
  • Default: none
  • Values: none | enabled | disabled
tcp-reconn-interval
Set the amount of time in seconds before retrying a TCP connection.
  • Default: 0
  • Values: 0, 2-300
max-register-burst-rate
Enter the maximum number of new registrations you want this session agent to accept within the registration burst rate window. When this threshold is exceeded, the Oracle Communications Session Border Controller responds to new registration requests with 503 Service Unavailable messages.
  • Default: 0
  • Values: Min: 0 / Max: 999999999
register-burst-window
Enter the window size in seconds for the maximum number of allowable SIP registrations.
  • Default: 0
  • Values: Min: 0 / Max: 999999999
rate-constraints
Access the rate-constraints subelement
ping-in-service-response-codes
Enter the response codes that keep a session agent in service when they appear in its response to the Oracle Communications Session Border Controller’s ping
  • Default: None
  • Values: SIP Response codes
out-service-response-codes
Enter the response codes that take a session agent out of service when they appear in its response to the Oracle Communications Session Border Controller’s ping request or any dialog-creating request.
  • Default: None
  • Values: SIP Response codes
manipulation-string
Enter a string you want used in the header manipulation rules for this session-agent. Enter a value to references the $HMR_STRING variable used to populate SIP headers and elements using HMR
manipulation-pattern
Enter the regular expression to be used in header manipulation rules for this session-agent.
sip-profile
Enter the name of the sip-profile you want to add to the session-agent
sip-isup-profile
Enter the name of the sip-isup-profile you want to add to the session-agent.
load-balance-dns-query
Sets the method the Oracle Communications Session Border Controller uses to send messages to when it queries a DNS server and receives multiple A-Records. The strategy configured here is used to select which of the multiple addresses the Oracle Communications Session Border Controller forwards the message to first.
  • Default: hunt
  • Values: hunt | round-robin
kpml-interworking
Enable or disable KPML interworking.
  • Default: inherit
  • Values: inherit | enabled | disabled
kpml2833-iwf-on-hairpin
When enabled, specifies that the system supports KPML to RFC2833 interworking for hairpinned calls. This requires that kpml-interworking to also be enabled.
  • Default: inherit
  • Values: inherit | enabled | disabled —When enabled, allows the Oracle Communications Session Border Controller to present the correct digit encapsulation (KPML or RFC2833) when hairpinned back to the original interface.
precedence

Specifies the selection precedence of Session Agents with same IP address.

  • Default: 0 (disabled)
  • Values: Min: 0 / Max: 4294967295
monitoring-filters
Comma-separated list of monitoring filters used for SIP monitor and trace.
auth-attribute
Enter the auth-attribute configuration element.
session-recording-server
A maximum of four names of session-recording-servers, or session-recording-groups, or a combination of both exisiting in the realm associated with the session reporting client. Valid values are alpha-numeric characters. Session recording groups are indicated by prepending the groupname with SRG:
session-recording-required
Determines whether calls are accepted by the SBC if recording is not available.
  • Default: disabled
  • enabled—Restricts call sessions from being initiated when a recording server is not available.
  • disabled—Allows call sessions to initiate even if the recording server is not available.
sm-icsi-match-for-invite
The ICSI URN to match on to increment the session-based messaging counters.
  • Default: urn:rrn-7:3gpp-service.ims.icsi.oma.cpm.msg
sm-icsi-match-for-message
The ICSI URN to match on to increment the event-based messaging counters.
  • Default: urn:rrn-7:3gpp-service.ims.icsi.oma.cpm.largemsg
ringback-file
Specifies the name of the media file, stored previously in /code/media, that the system plays when triggered for this realm.
ringback-trigger
Specifies when the system triggers the local media playback function.
  • Default: none
  • none—The system does not perform local media playback procedures. Based on precedence, however, the system may issue playback based on other element configurations. Local media playback follows the precedence session-agent, realm, then sip-interface.
  • disabled—The system does not perform media playback procedures on this flow, regardless of ensuing configurations.
  • 180-no-sdp—Defines the trigger by which the system starts local media playback to caller. This parameter causes playback trigger whenever the called leg responds with a 180 message that does not include SDP.
  • 180-force—Defines the trigger by which the system starts local media playback to caller. This parameter causes playback trigger whenever the called leg responds with a 180 message.
  • 183—Starts playback to caller when 183 is sent to call originator. The system stops the playback on the final response (either 2xx success or 4xx error). Configure this 183 value on the original INVITE ingress realm/sip-interface/session-agent.
  • refer—Starts playback to the referee when it receives a REFER. This trigger operates only if the OCSBC actually terminates and performs the refer operation. If the REFER is via proxy, playback is not a triggered. Playback stops when the refer operation is complete with a final response (200-299 or 400-699). Configure this refer value on the ingress realm/sip-interface/session-agent of the transferred call.
  • 183-and-refer—Starts playback when both 183 and refer triggers are activated.
  • 183-no-sdp—Defines the trigger by which the system starts local media playback to caller. This parameter causes playback trigger whenever the called leg responds with a 183 message that does not include SDP.
  • playback-on-header—Starts or stops playback based on the presence of the P-Acme-Playback header and its definitions.
sti-as
Specifies the name of an sti-server-group name or a space-separated list of sti-server (up to four allowed) to which the SBC shall send AS requests. When configuring a group name, use the prefix stg: followed by your group name. For example, stg:myStiGroupName.
sti-vs
Specifies the name of an sti-server-group name or a space-separated list of sti-server (up to four allowed) to which the SBC shall send VS requests. When configuring a group name, use the prefix stg: followed by your group name. For example, stg:myStiGroupName.
sti-orig-id
Specifies the UUID v4 to be added to STI-AS requests, if not already present, during STIR/SHAKEN functions.
sti-attest
Specifies the attestation value that is sent in AS request, during STIR/SHAKEN functions. The default is empty
  • full-attestation
  • partial-attestation
  • gateway-attestation
sti-signaling-attest
Enable this parameter to instruct the SBC to use attestation level and origination ID headers from the ingress SIP INVITE in the REST query to the STI-AS, if preferred. When enabled, the Attestation-Info and Origination-ID headers override the configured values, if present. If one of the two requested headers is present, the other value is obtained from configured parameters.
  • Default: Disable—The system does not use the attestation value and origId from SIP headers.
  • Enable—The system uses the attestation value and origId from SIP headers, when present.

Path

session-agent is an element under the session-router path. The full path from the topmost ACLI prompt is: configure terminal , and then session-router , and then session-agent.

This is a multiple instance configuration element.