doc/manuals/chapters/configuration.adoc

== Configuring OsmoMGW

A basic configation of OsmoMGW mainly consists of specifying the IP address
and port on which to listen to MGCP commands, but changing the port range at
which the RTP streams terminate as well as limiting operation to a single call
agent can be done as well as changing the number of endpoints.

=== Configuring MGCP

By default OsmoMGW listens for MGCP on port 2427 on any IP address. If a call
agent address is configured then OsmoMGW will only answer MGCP commands from
that IP port 2727, otherwise all sources are handled. A domain can be
specified

.Example: MGCP configuration
----
OsmoMGW(config-mgcp)# bind ip 127.0.0.1
OsmoMGW(config-mgcp)# bind port 2427
OsmoMGW(config-mgcp)# call-agent ip 127.0.0.1
OsmoMGW(config-mgcp)# domain mgw-bsc
OsmoMGW(config-mgcp)# local ip 127.0.0.1
----

=== Configuring the trunk

The first trunk is considered a virtual trunk in OsmoMGW. All
endpoints of type "rtpbridge" are routed here. The virtual trunk is configured
in the config-mgcp context.

All other trunks are configured in the config-mgcp-trunk context, but the
commands used are identical. Right now trunks are considered only for "ds/e1"
type endpoints.

.Example: MGCP trunk configuration
----
OsmoMGW(config-mgcp)# number endpoints 63 <1>
OsmoMGW(config-mgcp)# rtp bind-ip 10.0.0.1 <2>
OsmoMGW(config-mgcp)# rtp port-range 12000-14000 <3>
----
<1> Maximum number of endpoints that can be allocated at once
<2> Use this IP when binding RTP endpoints
<3> Use ports in this range when binding RTP endpoints

There are some options to tweak how RTP forwarding behaves in OsmoMGW:

.Example: MGCP trunk rtp options
----
OsmoMGW(config-mgcp)# rtp keep-alive 30 <1>
OsmoMGW(config-mgcp)# rtp-patch ssrc <2>
OsmoMGW(config-mgcp)# rtp-patch timestamp <3>
----
<1> Send dummy UDP packets periodically to RTP destination
<2> Hide SSRC changes
<3> Ensure RTP timestamp is aligned with frame duration

NOTE: Changes to trunks that affect resource allocation, such as newly created
trunks or a change of the number of available endpoints, require a full restart
of osmo-mgw!

=== E1 trunk considerations

While the RTP bridge trunks are natively based on IP no special considerations
are required during setup. E1 trunks are mapped on a physical E1 line, which has
to be configured as shown below.

.Example: E1 line setup
----
OsmoMGW(config-e1_input)# e1_line 0 driver dahdi <1>
OsmoMGW(config-e1_input)# e1_line 0 port 2 <2>
----
<1> Name of the libosmo-abis driver implementation ("dahdi")
<2> Port number of the physical E1 port to use (2)

In osmo-mgw the e1_input node is used to configure the physical E1 line. The
line number will be used internally to identify the configured E1 line. The
port number is the physical E1 connector (sometimes called 'span') at the E1
hardware. Per trunk an individual E1 line will be needed. Beware that the E1
driver may also need configuration settings that are not discussed here.

.Example: E1 trunk setup
----
OsmoMGW(config-mgcp)# trunk 0 <1>
OsmoMGW(config-mgcp-trunk)# line 0 <2>
----
<1> Creation of a trunk (0)
<2> Reference to the E1 line to use (0)

The E1 trunk is created along with a number, typically starting at 0, but if
required any number from 0-64 is allowed. The E1 trunk configuration concerning
the IP related aspects is nearly identical to the configuration of the virtual
trunk. However, it is important that the user assigns one of the E1 line numbers
that were configured under the e1_input node.

NOTE: The endpoint name that is used on MGCP level will include the trunk number,
not the E1 line number. For simplicity (and compatibility with OsmoBSC) it is
recommended to use equal numbers for trunk and E1 line. However, if required any
E1 line can be mapped flexible on any trunk as long as the mapping is bijective.

.Example: A typical configuration with one E1 trunk
----
e1_input
 e1_line 0 driver dahdi
 e1_line 0 port 2
mgcp
 bind ip 127.0.0.1
 rtp net-range 6000 6011
 rtp net-bind-ip 192.168.100.130
 rtp ip-probing
 rtp ip-dscp 46
 no rtp keep-alive
 bind port 2428
 number endpoints 30
 loop 0
 force-realloc 1
 osmux off
 rtp-patch rfc5993hr
 trunk 0
  rtp keep-alive once
  no rtp keep-alive
  line 0
----

NOTE: One E1 trunk always covers a whole E1 line. All subslots (I.640) will be mapped
to individual MGCP endpoints. As long as the endpoints remain unused the
underlying E1 timeslot is not used.

NOTE: The E1 trunk implementation also works with T1 lines, however since T1 has
24 instead of 31 usable timeslots only the endpoints that fall into that 1-24 timeslot
range will be useable.