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.
- ip-address
- Enter the IP address of session agent if hostname value is an FQDN
- 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
- Values
- 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
- Values:
- 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.
- 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
- Values:
- 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:
This is a multiple instance configuration element.