Network Working Group                                          B. Foster
Request for Comments: 3660                                  F. Andreasen
Updates: 2705                                              Cisco Systems
Category: Informational                                    December 2003


         Basic Media Gateway Control Protocol (MGCP) Packages

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

IESG Note

   This document is being published for the information of the
   community.  It describes a non-IETF protocol that is currently being
   deployed in a number of products.  Implementers should be aware of
   RFC 3525 [37], which was developed in the IETF Megaco Working Group
   and the ITU-T SG16, and is considered by the IETF and ITU-T to be the
   standards-based (including reviewed security considerations) way to
   meet the needs that MGCP was designed to address.  The IETF Megaco
   Working Group and the ITU-T Study Group 16 are developing extensions
   to RFC 3525 [37] that for functions of the type in addressed in this
   document.

Abstract

   This document provides a basic set of Media Gateway Control Protocol
   (MGCP) packages.  The generic, line, trunk, handset, RTP, DTMF (Dual
   Tone Multifrequency), announcement server and script packages are
   updates of packages from RFC 2705 with additional explanation and in
   some cases new versions of these packages.  In addition to these,
   five new packages are defined here.  These are the signal list,
   resource reservation, media format, supplementary services and digit
   map extension packages.










Foster & Andreasen           Informational                      [Page 1]

RFC 3660                  Basic MGCP Packages              December 2003


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  2
       1.1.  List of Packages . . . . . . . . . . . . . . . . . . . .  3
       1.2.  Changes to Existing RFC 2705 Packages. . . . . . . . . .  3
             1.2.1.  Change in Signal Types . . . . . . . . . . . . .  3
             1.2.2.  Operation Complete and Operation Failure . . . .  3
             1.2.3.  Package Versions . . . . . . . . . . . . . . . .  4
             1.2.4.  Event Definitions, Aliases and Interoperability
                     Issues . . . . . . . . . . . . . . . . . . . . .  4
             1.2.5.  New Events . . . . . . . . . . . . . . . . . . .  5
       1.3.  New Packages and Excluded Packages . . . . . . . . . . .  5
   2.  Packages . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
       2.1.  Generic Media Package. . . . . . . . . . . . . . . . . .  7
       2.2.  DTMF Package . . . . . . . . . . . . . . . . . . . . . . 11
       2.3.  Trunk Package. . . . . . . . . . . . . . . . . . . . . . 16
       2.4.  Line Package . . . . . . . . . . . . . . . . . . . . . . 24
       2.5.  Handset Emulation Package. . . . . . . . . . . . . . . . 33
       2.6.  Supplementary Services Tone Package. . . . . . . . . . . 36
       2.7.  Digit Map Extension. . . . . . . . . . . . . . . . . . . 37
       2.8.  Signal List Package. . . . . . . . . . . . . . . . . . . 38
       2.9.  Media Format Parameter Package . . . . . . . . . . . . . 39
       2.10. RTP Package. . . . . . . . . . . . . . . . . . . . . . . 43
       2.11. Resource Reservation Package . . . . . . . . . . . . . . 48
             2.11.1. Description. . . . . . . . . . . . . . . . . . . 48
             2.11.2. Parameter Encoding . . . . . . . . . . . . . . . 52
             2.11.3. Events . . . . . . . . . . . . . . . . . . . . . 53
       2.12. Announcement Server Package. . . . . . . . . . . . . . . 55
       2.13. Script Package . . . . . . . . . . . . . . . . . . . . . 56
   3.  IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 59
   4.  Security Considerations. . . . . . . . . . . . . . . . . . . . 59
   5.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59
   6.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 60
       6.1.  Normative References . . . . . . . . . . . . . . . . . . 60
       6.2.  Informative References . . . . . . . . . . . . . . . . . 62
   7.  Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 63
   8.  Full Copyright Statement . . . . . . . . . . . . . . . . . . . 64

1.  Introduction

   This document provides a basic set of Media Gateway Control Protocol
   (MGCP) packages.  The generic, line, trunk, handset, RTP, DTMF,
   announcement server and script packages are updates of packages from
   RFC 2705 [38] with additional explanation and in some cases new
   versions of these packages.  In addition to these, five new packages
   are defined here.  These are the signal list, resource reservation,
   media format, supplementary services and digit map extension
   packages.



Foster & Andreasen           Informational                      [Page 2]

RFC 3660                  Basic MGCP Packages              December 2003


   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14, RFC 2119 [31].

1.1.  List of Packages

   The basic set of packages specified in this document is for use with
   MGCP 1.0 as defined in [1].  Included are the following packages:

              -------------------------------------------
             | Package                        |   Name   |
             |-------------------------------------------|
             | Generic Media Package          |   G      |
             | DTMF package                   |   D      |
             | Trunk Package                  |   T      |
             | Line Package                   |   L      |
             | Handset Package                |   H      |
             | Supplementary Services Package |   SST    |
             | Digit Map Extension            |   DM1    |
             | Signal List Package            |   SL     |
             | Media Format Package           |   FM     |
             | RTP Package                    |   R      |
             | Resource Reservation Package   |   RES    |
             | Announcement Server Package    |   A      |
             | Script Package                 |   Script |
              -------------------------------------------

1.2.  Changes to Existing RFC 2705 Packages

1.2.1.  Change in signal types

   MGCP 1.0, as defined in RFC 2705 [38] (and now updated in [1]),
   provided some additional clarification on the meaning of On-Off (OO)
   signals compared to earlier versions of MGCP.  This lead to some
   inconsistency in some of the signal definitions in the accompanying
   packages in RFC 2705 [38].  This has been corrected in the packages
   that are included here by changing some of the signals from type On-
   Off to type Time-Out (TO).

1.2.2.  Operation Complete and Operation Failure

   Another change made to improve consistency and interoperability was
   to add the "operation complete" and "operation failure" events in
   packages where there are TO signals defined, but where the "operation
   complete" and "operation failure" events were not previously included
   as part of the package.  By definition, all packages that contain





Foster & Andreasen           Informational                      [Page 3]

RFC 3660                  Basic MGCP Packages              December 2003


   Time-Out type signals now contain the "operation failure" ("of") and
   "operation complete" ("oc") events as defined in [1], irrespective of
   whether they are provided as part of the package description or not.

   If a package without Time-Out signals contains definitions for the
   "oc" and "of" events, the event definitions provided in the package
   may over-ride those indicated here.  Such practice is however
   discouraged and is purely allowed to avoid potential backwards
   compatibility problems.

   It is considered good practice to explicitly mention that the "oc"
   and "of" events are supported in accordance with their default
   definitions.  If no definition is included in the package, the
   default syntax and semantics are assumed.

   Please refer to [1] for additional details on these events.

1.2.3.  Package Versions

   The generic, line, trunk, handset, RTP, DTMF, announcement server and
   script packages included in this document are new versions of
   packages that were previously contained in RFC 2705 [38].  The
   updated base MGCP 1.0 specification [1] provides an optional
   capability of auditing package versions.  Any gateway that implements
   versioned packages SHOULD also implement this option.

1.2.4.  Event Definitions, Aliases and Interoperability Issues

   Some event definitions or clarifications of previous event
   definitions have also been added in order to improve
   interoperability.

   In some cases, events have aliases either in the same or in other
   packages and a recommendation has been made for the use of alternates
   by Call Agents for future implementations.  For maximum
   interoperability, gateways MUST still implement these events (in fact
   they MUST always implement all of the events, signals, etc. in a
   package).

   Some events that were previously defined require specific
   provisioning in both the gateway and the Call Agent in order to allow
   for interoperability.  In those cases, a warning to that affect has
   been included.








Foster & Andreasen           Informational                      [Page 4]

RFC 3660                  Basic MGCP Packages              December 2003


1.2.5.  New Events

   In some cases, new events have been added to existing packages.  Any
   changes to existing packages of course have resulted in the package
   version number being updated from unversioned (version 0) to version
   1.

1.3.  New Packages and Excluded Packages

   Two packages from RFC 2705 [38] have not been included.  These are
   the "MF" and the "NAS" packages.  These packages are still valid as
   are all unversioned (version 0) packages defined in RFC 2705 [38].
   The reason these packages were not included are:

      *  The original MF package had no defined way to outpulse MF
         digits so that MF CAS is now provided by other packages (i.e.,
         the "MS", "MO" and "MD" packages) in a separate document.

      *  The "N" package, as defined in RFC 2705 [38], was incomplete.
         A new MGCP "NAS" package has been developed and provided in a
         separate document.

   New packages have also been included beyond what was included in RFC
   2705 [38].  These are the signal list, resource reservation, media
   format, supplementary services and digit map extension packages.  The
   Resource Reservation ("RES") and Media Format ("FM") packages in
   particular are different from other packages in this document in that
   they contain new LocalConnectionOptions.  This is allowed by the new
   extension rules in [1].  Future packages of this type MUST use a
   packages prefix in front of local connection options ("/") so as to avoid name-space problems.
   However because of the timing of the arrival of these packages
   relative to updating MGCP 1.0, this was not done for the "RES" and
   "FM" packages.  The resulting new local connection options have been
   registered with IANA.  For future cases where a package prefix is
   included, only the package name needs to be registered.

2.  Packages

   For those packages that involve MGCP events, the terms "signal" and
   "event" are used to differentiate a request from a Call Agent to a
   Media Gateway to apply an event ("signal"), from the request for the
   detection of an "event" that occurs on the Media Gateway and is
   "Notified" to the Call Agent.







Foster & Andreasen           Informational                      [Page 5]

RFC 3660                  Basic MGCP Packages              December 2003


   For packages that involve events and signals, the tables contain five
   columns:

      Symbol:  the (package) unique symbol used to identify the event.

      Definition:   a short description of the event.

      R:  an x appears in this column if the event can be requested by
      the Call Agent.  Alternatively, one or more of the following
      symbols may appear.  An "S" is included if the event-state may be
      audited.  A "C" indicates that the event can be detected on a
      connection, and a "P" indicates the event is persistent.

      S: if nothing appears in this column for an event, then the event
      cannot be signaled by the Call Agent.  Otherwise, the following
      symbols identify the type of event:

         * OO     On/Off signal

         * TO     Time-Out signal.

         * BR     Brief signal.

      In addition, a "C" will be included if the signal can be generated
      on a connection.

      Duration: specifies the default duration of TO signals.  If a
      duration is left unspecified, then the default timeout will be
      assumed to be infinite, unless explicitly noted in the description
      of the signal.  A duration may also be declared as being variable
      in a case where signals involve complex sequencing (e.g., scripts
      or digit out-pulsing) where the amount of time may vary with
      either processing time or the signaling environment.

   Default time-out values may be over-ridden by the Call Agent for any
   Time-Out event defined in this document (with the exception of those
   that have a default value of "variable") by a "to" signal parameter
   which specifies the timeout value in milliseconds (see [1]).  The
   following example indicates a timeout value of 20 seconds:

         S: sst/cw(to=20000)

   As indicated in [1]: by default, a supplied time-out value MAY be
   rounded to the nearest non-zero value divisible by 1000, i.e., whole
   second.  However, individual signal definitions within a package may
   define other rounding rules.





Foster & Andreasen           Informational                      [Page 6]

RFC 3660                  Basic MGCP Packages              December 2003


   Note that Time-Out signals that involve other parameters still allow
   the use of the "to" signal parameter e.g.:

         S: T/sit(1,to=3000)

   The order of the "to" parameter relative to the other parameters is
   not important.

   Note: as per [1], On-Off (OO) signals are parameterized with "+"
   (meaning turn on) or "-" (meaning turn off).  If the parameter is
   missing, the default is to turn on the signal.  Unlike Time-Out
   signals, On-Off signals do not stop when an event occurs.

   Other than the "to" parameter for Time-out (TO) signals and the "+"
   and "-" for On-Off (OO) signals, signals and events in the packages
   in this document do not have parameters unless explicitly indicated
   in the description of the event for that package.

   In some of the signal definitions below, specific tone definitions
   are provided even though actual frequencies may vary from country to
   country.

2.1.  Generic Media Package

   Package Name: G
   Version: 1

   The generic media package groups the events and signals that can be
   observed on several types of endpoints, such as trunk gateway
   endpoints, access gateway endpoints or residential gateway endpoints.

    ---------------------------------------------------------------
   | Symbol   |   Definition               |   R | S     Duration  |
   |---------------------------------------------------------------|
   | cf       |   Confirm Tone             |     | BR              |
   | cg       |   Congestion Tone          |     | TO    infinite  |
   | ft       |   Fax Tone                 |   x |                 |
   | it       |   Intercept Tone           |     | TO    infinite  |
   | ld       |   Long Duration Connection |   C |                 |
   | mt       |   Modem Tone               |   x |                 |
   | oc       |   Operation Complete       |   x |                 |
   | of       |   Operation Failure        |   x |                 |
   | pat(###) |   Pattern Detected         |   x | OO              |
   | pt       |   Preemption Tone          |     | TO    infinite  |
   | rbk(...) |   Ringback                 |     | TO,C 180 seconds|
   | rt       |   Ringback Tone            |     | TO,C 180 seconds|
    ---------------------------------------------------------------




Foster & Andreasen           Informational                      [Page 7]

RFC 3660                  Basic MGCP Packages              December 2003


   New events added to this package from the previously unversioned
   package: "oc"

   Changes: "it" and "pt" signals changed from OO to TO.

   Note that default time-out values may be over-ridden by the Call
   Agent for any Time-Out signal defined in this package by a "to"
   signal parameter.  Refer to section 2 of this document, as well as
   [1] for details.

   The events and signals are defined as follows:

   Confirmation Tone (cf):
      This is also referred to as "positive indication tone" in ITU-T
      E.182.  In North America, Confirmation Tone uses the same
      frequencies and levels as dial tone (350 and 440 Hertz) but with a
      cadence of 0.1 second on, 0.1 second off, repeated three times.
      See GR-506-CORE [7] Section 17.2.4.  It is considered an error to
      try and play confirmation tone on a phone that is on-hook and an
      error MUST consequently be returned when such attempts are made
      (error code 402 - phone on-hook).

   Congestion Tone (cg):
      Refer to ITU-T E.180 [8] and E.182 [10].  This maps to re-order
      tone in North America (refer to GR-506-CORE [7] Section 17.2.7).

   Fax Tone (ft):
      The fax tone event is generated whenever a fax call is detected by
      the presence of V.21 fax preamble.  The fax tone event SHOULD also
      be generated when the T.30 CNG tone is detected.  See ITU-T
      Recommendations T.30 [21] and V.21 [22].

   Intercept Tone(it):
      This is a country specific tone as defined in ITU-T E.180
      Supplement 2 [9].

   Long Duration Connection (ld):
      The "long duration connection" is detected when a connection has
      been established for more than a provisioned amount of time.  The
      default value is 1 hour.

      This event is detected on a connection.  When no connection is
      specified as part of the request, the event applies to all
      connections for the endpoint, regardless of when the connections
      are created.  The "all connections" wildcard (see [1]) may also be
      used for this case, and is in fact preferred for consistency.  In





Foster & Andreasen           Informational                      [Page 8]

RFC 3660                  Basic MGCP Packages              December 2003


      either case, the name of the connection on which the event was
      detected will be included when the event is observed, e.g.:

         G/ld@0A3F58

   Modem Tone (mt):
      Indicates V.25 Answer tone (ANS) with or without phase reversals
      or V.8 Modified Answer Tone (ANSam) tone with or without phase
      reversals.  Note that this implies the presence of a data call.
      Also note that despite the name of the event, devices other than
      modems may generate such tones, e.g., a fax machine.

   Operation Complete (oc):
      The standard definition of operation complete [1].

   Operation Failure (of):
      The standard definition of operation failure [1].

   Pattern Detected (pat(###)):
      This event requires special provisioning that needs to be agreed
      on between the Call Agent and media gateway in order to ensure
      interoperability.  It is retained in order to maintain backwards
      compatibility with version 0 of the "G" package.  This event MUST
      be parameterized with a decimal numeric value from 0 to 999
      specifying the pattern to detect.  When reported, the pattern is
      also included as a parameter.

   Preemption Tone (pt):
      This is a country specific tone and is defined in ITU-T E.180
      Supplement 2 [9].

   Ringback (rbk(connectionID)):
      This is an alias for "rt@connectionID" and is included here for
      backwards compatibility only.  It is recommended that Call Agents
      use "rt@connectionID" instead of "rbk(connectionID)" for ring-back
      over a connection for new implementations.  Although the ringback
      signal is applied on a connection, the "rbk" signal does not
      support the "@connection" syntax.  When the signal is requested,
      it MUST be parameterized with a connection-ID or a connection-ID
      wildcard as specified in [1].

   Ringback Tone (rt):
      Refer to ITU-T E.180 [8] and ITU-T E.182 [10].  Also referred to
      as ringing tone - a tone advising the caller that a connection has
      been made and that a calling signal is being applied to the called
      party or service point.  In North America, this tone is a
      combination of two AC tones with frequencies of 440 and 480 Hertz
      and levels of -19 dBm each, to give a combined level of -16 dBm.



Foster & Andreasen           Informational                      [Page 9]

RFC 3660                  Basic MGCP Packages              December 2003


      The cadence for Audible Ring Tone is 2 seconds on, followed by 4
      seconds off.  See GR-506-CORE [7] - LSSGR: SIGNALING, Section
      17.2.5.

      This signal can be applied directly to an endpoint or
      alternatively on a connection using the syntax "rt@connectionID".
      When the ringback signal is applied to an endpoint, it is
      considered an error to try and play ringback tone if the endpoint
      is considered on-hook, and an error MUST consequently be returned
      when such attempts are made (error code 402 - phone on-hook).
      When the ringback signal is applied to a connection, no such check
      is to be made.

      Note that as specified in [1], signals requested on a connection
      MUST be played regardless of the connection mode.  For example, in
      a call-waiting situation, ringback tone may be played on a
      connection in "inactive" mode.


































Foster & Andreasen           Informational                     [Page 10]

RFC 3660                  Basic MGCP Packages              December 2003


2.2.  DTMF package

   Package name: D
   Version: 1

    --------------------------------------------------------------
   | Symbol  |   Definition              |   R |   S     Duration |
   |--------------------------------------------------------------|
   | 0       |   DTMF 0                  |   x |   BR             |
   | 1       |   DTMF 1                  |   x |   BR             |
   | 2       |   DTMF 2                  |   x |   BR             |
   | 3       |   DTMF 3                  |   x |   BR             |
   | 4       |   DTMF 4                  |   x |   BR             |
   | 5       |   DTMF 5                  |   x |   BR             |
   | 6       |   DTMF 6                  |   x |   BR             |
   | 7       |   DTMF 7                  |   x |   BR             |
   | 8       |   DTMF 8                  |   x |   BR             |
   | 9       |   DTMF 9                  |   x |   BR             |
   | #       |   DTMF #                  |   x |   BR             |
   | *       |   DTMF *                  |   x |   BR             |
   | A       |   DTMF A                  |   x |   BR             |
   | B       |   DTMF B                  |   x |   BR             |
   | C       |   DTMF C                  |   x |   BR             |
   | D       |   DTMF D                  |   x |   BR             |
   | DD(..)  |   DTMF Tone Duration      |   x |   TO  3 seconds  |
   | DO(..)  |   DTMF OO Signal          |     |   OO             |
   | L       |   Long Duration Indicator |   x |                  |
   | oc      |   Operation Complete      |   x |                  |
   | of      |   Operation Failure       |   x |                  |
   | T       |   Interdigit Timer        |   x |   TO 16 seconds  |
   | X       |   DTMF Tones Wildcard,    |   x |                  |
   |         |    match any digit 0-9    |     |                  |
    --------------------------------------------------------------

   Changes from the previous version of the package: events "dd", "do",
   "oc" were added.

   Note that DTMF tones including the DTMF tones wildcard can use the
   eventRange notation defined in [1] when requesting events, e.g.,
   "D/[0-9](N)".

   Note that default time-out values may be over-ridden by the Call
   Agent for any Time-Out signal defined in this package by a "to"
   signal parameter.  Refer to section 2 of this document, as well as
   [1] for details.






Foster & Andreasen           Informational                     [Page 11]

RFC 3660                  Basic MGCP Packages              December 2003


   The events are defined as follows:

   DTMF tones (0-9,#,*,A,B,C,D):
      Detection and generation of DTMF tones is described in GR-506-CORE
      [7] - LSSGR: SIGNALING, Section 15.  Note that it is considered an
      error to try and play DTMF tones on a phone that is on-hook and an
      error MUST consequently be returned when such attempts are made
      (error code 402 - phone on-hook).  The event codes can be
      specified in a digit map.  When requested as a signal, as per
      GR-506-CORE [7], section 15, a minimum tone duration of 50 ms will
      be followed by a minimum interdigit silence period of 45 ms, i.e.,
      if requested in a signal list such as "S: sl/s(d/5,d/6,d/7)", then
      interdigit timing requirements will be satisfied.

      Note that some types of endpoints, such as announcement endpoints,
      MAY allow detection and/or generation of a DTMF tone over a
      connection.  However, this requires consistent provisioning
      between the Call Agent and announcement server (it is not required
      in order to be compliant with the DTMF package).

   DTMF Tone Duration (dd(dg=,to=