From SIPfoundry sipx, The Open Source SIP PBX for Linux - Calivia
===========
1. Overview
===========
A back to back user agent (B2BUA) is defined as a user agent that terminates
inbound calls and established a new call with another party:
+------------+ +-------+ +------------+
| Endpoint A | <----> | B2BUA | <----> | Endpoint B |
+------------+ +-------+ +------------+
This implementation serves as an example of how to implement a B2BUA using
sipXtapi. There are a number of design considerations when building a
B2BUA. Here is a quick look at that major B2BUA limitations/design
points:
1.1 1-1 Mapping
This B2BUA assumes a 1-1 mapping of calls/line identities. This is the
configuration that one would expect for a home-based solution where you have
one or two lines on some calling service (e.g. Vonage). Effectively, this
simulates having a single phone number for each user (both inbound and
outbound). In enterprise solutions, you may have a DID/phone number for
inbound calls, however, the PBX/solution could pick any free line for
outbound calls -- This is not handled as part of this implementation.
1.2 PBX/Call routing requirement
This B2BUA assumes that a PBX (such as sipX) is available to route
calls on one side of the B2BUA and that the PBX side does not have
any NAT hurdles. Only one side of the B2BUA (the service provider
side) can be configured to register. The other side will be mapped
to a provisioned address.
1.3 Early answer of inbound calls
This B2BUA will answer incoming calls as soon as they are received and
will simulate ringback and/or busy tones as appropriate. This isn't ideal
if calls on either side are metered. However, sipXtapi doesn't support
sending of early media which may result in odd user experiences if calling
a party such as Airlines (which plays the first part of it's IVR prompts
using early media).
1.4 Limited transfer support
Transfer is not supported when the B2BUA is acting as the transferee.
Additional work is required to support this.
1.5 Limited Call/Line support
This B2BUA will support a maximum of 32 line definitions and/or calls.
Additional work is required to determine actual resource limits /
scalability.
====================
2. General use cases
====================
These use cases assume that one side of the call is a service provider and
the other side is some sort of PBX. The implementation does not force this
usage, however, this is likely the most obvious use and used as an example.
2.1 Inbound call from the service provider side:
+------------------+ +-------+ +------------------+
| Service Provider | <----> | B2BUA | <----> | PBX |
+------------------+ +-------+ +------------------+
| | |
1 : |<----- REGISTER ------| |
2 : |------- 200 OK ------>| |
3 : | | |
4 : |------- INVITE ------>| |
5 : |<---- 100 TRYING -----| |
6 : |<---- 180 RINGING ----| |
7 : |<------ 200 OK -------| |
8 : |-------- ACK -------->| |
9 : | |------- INVITE ------>|
10: | |<---- 100 TRYING -----|
11: | |<---- 180 RINGING ----|
12: | |<------ 200 OK -------|
13: | |-------- ACK -------->|
In lines 1 and 2, the B2BUA will keep a registration alive with the service
provider (and/or PBX, etc).
In Lines 4-8, the B2BUA will answer the inbound call and play a ring tone
back to the caller.
In Lines 6-10, the B2BUA will setup a call to the mapped party and attempt
to setup the 2nd leg of the call. If the call fails, a busy tone will be
played to the caller, otherwise, the B2BUA will bridge the call and allow
audio to flow between both parties.
2.2 Outbound call from the PBX side:
+------------------+ +-------+ +------------------+
| PBX | <----> | B2BUA | <----> | Service Provider |
+------------------+ +-------+ +------------------+
| | |
1 : | |------ REGISTER ----->|
2 : | |<------ 200 OK -------|
3 : | | |
4 : |------- INVITE ------>| |
5 : |<---- 100 TRYING -----| |
6 : |<---- 180 RINGING ----| |
7 : |<------ 200 OK -------| |
8 : |-------- ACK -------->| |
9 : | |------- INVITE ------>|
10: | |<---- 100 TRYING -----|
11: | |<---- 180 RINGING ----|
12: | |<------ 200 OK -------|
13: | |-------- ACK -------->|
The sequences are virtually identical to case 1.
================
3. Configuration
================
3.1 General settings
3.1.1 OUTBOUND_PROXY : <proxy>
Defines the outbound proxy for SIP messages.
Optional, no default.
3.1.2 LOG_FILE : <log file>
Defines the log file target. If present, sipXtapi will log at the debug
log level. TODO: The ability to configure the log level is needed.
Optional, no default.
3.1.3 SIP_UDP_PORT : <UDP port number>
Defines the SIP UDP port.
Optional, default is 5060.
3.1.4 SIP_TCP_PORT : <TCP port number>
Defines the SIP TCP port. Specify -1 to disable TCP operation.
Optional, default is 5060.
3.1.5 RTP_START_PORT : <starting RTP port>
Defines the starting RTP port. Generally, you should not need to change
this default. Some system administrators may only open up specific port
ranges for UDP traffic. In that is case, you may need to modify this
value.
Optional, default is 16384.
3.1.6 STUN_SERVER : <STUN server hostname or IP>
Defines a stun server to use with the registering side of the B2BUA. The
non-registering side will use local IP addresses for contacts. Leave this
value blank to disable STUN.
Optional, default is stun.sip411.com
3.1.7 STUN_PORT : <STUN server port>
Defines the stun port. See STUN_SERVER for details on this setting.
Optional, default is 3478.
3.1.8 REGISTER_PERIOD_SECS : <default register period in secs>
Defines the default registration period. By default, sipXtapi will
register at a fraction of this period (~50%). The default value of 50
seconds helps keep firewall opens.
Required, default is 50.
3.2 Line Mappings
Up to 32 lines can be defined in the current implementation. The
configuration parameters below are expected to be number from 1 to 32,
where the [N] is replaced with actual number.
3.2.1 NUM_LINES : N
Defines the number of configured lines. This value should be between
1 and 32, inclusively.
Required, no default.
3.2.2 LINE_URL.[N] :
Defines the identity that will be used for registration purposes
(service provider side given the example in this document). This should
be in the form: "Caller ID" <sip:username@address>.
If an inbound call matches this line (e.g. sip:5551212@serviceprovider),
then a new call will be placed to LINE_MAP_URL.[N] setting.
Required for each instance of N, no default.
3.2.3 LINE_ALIAS.[N]:
Defines an aliases of the LINE_URL above that is used to match a line
definition. Cases exist where calls may not match the exact line URL,
however, they should be treated identically. For example, some
component of your network might use the IP address instead of the
hostname or you have have some URL transformations that results in
Optional, no default.
3.2.4 LINE_REALM.[N] :
Defines the authentication realm for the line/identity. If left blank,
the B2BUA will not attempt to register.
Optional, no default.
3.2.5 LINE_USERNAME.[N]:
Defines the authentication username for the line/identity. If left
blank, the B2BUA will not attempt to register.
Optional, no default.
3.2.6 LINE_PASSWORD.[N]:
Defines the authentication password for the line/identity in clear text.
If left blank, the B2BUA will not attempt to register.
TODO: Should not store password in clear text.
Optional, no default.
3.2.7 LINE_MAP_URL.[N]:
Defines the mapping for this line.
If an inbound call matches this URL (e.g. sip:122@company.com),
then a new call will be placed to the LINE_URL.[N] setting.
Required for each instance of N, no default.
3.2.8 LINE_MAP_URL_ALIAS.[N]:
Identical to LINE_ALIAS.[N], however, acts as an alias for the
LINE_MAP_URL.[N] setting.
Optional, no default.
3.3 Configuration Example
<<TODO>> -- Fill in example
