Internet Engineering Task Force B. Foster Internet Draft D. Auerbach Document: <draft-foster-mgcp-bulkaudits-00.txt> F. Andreasen Category: Informational Cisco Systems Expires: January 2002 July 2001 MGCP Bulk Audits, Redirect and Reset Status of this Document This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document includes two new MGCP packages. The first package defines a bulk audit mechanism to determine connection and endpoint state for a group of endpoints. The second package provides a mechanism for redirecting a group of endpoints to another Call Agent without affecting the state of the endpoints, as well as a mechanism to reset a group of endpoints. Conventions used in this document 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 RFC-2119. Foster et al. Informational [Page 1]
MGCP Bulk Audits and Redirect July 2001 1. Introduction This document contains two packages to help manage gateways with large numbers of endpoints: * The bulk audit package allows a Call Agent to obtain an overview of endpoint and connection state for a list of endpoints. * The redirect and restart package allows a Call Agent to: * provide a new NotifiedEntity for an "all of" wild-card grouping of endpoints (i.e. re-direct a number of endpoints to a new Call Agent) * reset and re-initialize a number of endpoints 2.0. Bulk Audit Package 2.1. Package Definition Package Name: BA Package Version: 0 Package Description: This package provides the Call Agent the ability to audit and obtain high-level overview of endpoint and connection state for a group of endpoints in a gateway. 2.1.1. Package Parameters A new BulkRequestedInfo parameter is defined for use in the AuditEndpoint command. The parameter can be used to request a compact list of EndpointIds or to request a high level view of endpoint or connection state for a group of endpoints as illustrated below: ReturnCode, [EndPointNameList,] [EndpointStateList,] [ConnectionCountList,] [NextEndpointName] <-- AuditEndPoint(EndpointId, [BulkRequestedInfo,] [StartEndpointName,] [MaxNumEndpoints]) Unlike the normal RequestedInfo parameter in the base MGCP specification, the BulkRequestedInfo parameter can be used with "all- of" wildcards for auditing a collection of endpoints. It is not an error to specify an EndpointId without wildcards, however. Because wild-carding may not be sufficient in terms of qualifying the endpoints of interest, further qualification can be provided by including a StartEndpointName (the first endpoint of interest) and Foster et al. Informational [Page 2]
MGCP Bulk Audits and Redirect July 2001 MaxNumEndPoints (the maximum number of endpoints of interest) parameters with the following ABNF syntax: "BA/SE" ":" 0*WSP LocalEndpointName "BA/NU" ":" 0*WSP MaxNumEndpoints where MaxNumEndpoints is the decimal number of endpoints with a value in the range 1 to 65535. Note that only the LocalEndpointName is provided in request and response parameter lines for this package rather than the full EndpointId. This is done for the sake of compactness, i.e. the domain name portion is left out since it is already available in the command line portion of a given request. The list of endpoints defined by the StartEndpointName and MaxNumEndPoints must be within the range designated by the wild- carding. If there is an inconsistency, error code 805 ("Incorrectly specified endpoint range") should be returned. The BulkRequestedInfo parameter line has the following ABNF format: BulkRequestedInfo = "BA/F:" 0*WSP ("BA/Z" / "BA/X" / "BA/C" / EndpointStateParam) EndpointStateParam = "BA/S" "(" StateType 0*("," 0*(WSP) StateType)")" StateType = "I" / "D" / "N" / "S" / "H" where the BulkRequestedInfo parameters have the following meaning: * "BA/Z" is a request to return EndPointNameList * "BA/X" is a request to return InstantiatedEndpointList * "BA/C" is a request to return the ConnectionCountList * "BA/S" is a request to return the EndpointStateList The "BA/S" parameter is itself parameterized with one or more StateType parameters that define the conditions to be evaluated for the endpoint: * "I" - the endpoint is in service * "D" - the endpoint is disconnected, * "N" - the endpoint is in the notification state, * "S" - there is an active signal on the endpoint, * "H" - the hook-state is off-hook or the endpoint is in some state other than "idle". The meaning of this last parameter depends on the type of endpoint: * The parameter has no meaning for stateless endpoints with no hook-state associated with them such as ISUP trunks. In this case, the endpoint is by definition in the "idle" state for this parameter. * For endpoints that have a state machine associated with them Foster et al. Informational [Page 3]
MGCP Bulk Audits and Redirect July 2001 (such as a CAS endpoint), the endpoint must be in some state other than the "idle" state. * In the case where the endpoint has hook-state associated with it, the hook-state must be off-hook. In the case of digital channel associated signaling (CAS) connections, hook-state may be provided in either direction. If the hook-state in either direction is off-hook, the endpoint is considered non- idle, i.e. the condition is satisfied. The list of StateTypes may be extended in the future. If an unknown StateType is encountered, the command MUST be rejected with error code 803 (i.e. "unsupported StateType"). The report provided as a result of this request, yields an indication of either "True", "False", or "Out of Service" for the endpoint. If the endpoint is in-service and any one of the criteria holds true, then the report for the endpoint will evaluate to "True". A "False" indication will only be reported if the endpoint is in-service and all criteria evaluate to false. The report thus provides the logical "OR" function over the conditions audited for endpoints in-service. Irrespective of the state being audited, an "Out of Service" indication will always be reported if the endpoint is considered out- of-service. Note that the criteria "D", "N", "S" and "H" can only be true if the endpoint is in-service, so that requesting "I" at the same time (although allowed) would be unnecessary (i.e. redundant). Example: If the request for EndpointStateList for one or more endpoints includes the parameter line: BA/F: BA/S(D,N) indicating a request for a report on whether endpoints are disconnected or in the notification state. If a given endpoint is in either a "disconnected" or "notification" state, then the report will indicate "True" for that endpoint. If the endpoint is neither in a disconnected state nor in a notification state, but is in-service, then the report for that endpoint will indicate "False". If the endpoint is out-of-service, then the report for that endpoint will indicate "Out of Service" In order to only determine whether an endpoint is in-service or out- of service, the Call Agent should make a request with only the "I" StateType parameter. The EndPointNameList is a list of the endpoint names (i.e. the endpoint naming convention) supported by the gateway as qualified by the wild-carded EndPointId, and possibly StartEndPointName and MaxNumEndpoints parameters. This list can include one or more lines in the following format: "BA/Z:" 0*WSP RangedLocalName 0*("," 0*WSP RangedLocalName) Foster et al. Informational [Page 4]
MGCP Bulk Audits and Redirect July 2001 where RangedLocalName is a LocalEndpointName that may include a decimal range notation "[N-M]" to indicate matching any value from decimal number "N" to "M". Example: ba/z: ds/ds1-1/[1-24], ds/ds1-2/[1-24], ds/ds1-3/[1-24] or simply: ba/z: ds/ds1-[1-3]/[1-24] Any EndpointId that has a local name that matches any of the values in the range notation is a valid endpoint. Since "[" is not a reserved character for endpoint names, an endpoint name that contains the character "[" shall escape each occurrence of the "[" character in the endpoint name by using an extra "[" character. For example, the endpoint name ds/ds1-1/foo[bar] is thus reported as ds/ds1-1/foo[[bar] Use of the "[" character in endpoint names for endpoints that support this package is discouraged. For virtual endpoints that are automatically created and deleted on the fly by the gateway, there is a difference between reporting the endpoint names (i.e. the "naming convention") used in describing the endpoints and reporting the actual endpoints that are instantiated at the time the request is made. For this case: * EndPointNameList indicates the naming convention and * "BA/X" is a request to return InstantiatedEndpointList which is the "real" (or instantiated) endpoints. In the case of hard-wired/real endpoints (such as DSO's) or other persistent endpoints, the InstantiatedEndpointList would normally not be requested. However, if it is requested, the InstantiatedEndpointList and the EndPointNameList will be the same. For non-persistent virtual endpoints, an "all of" wild card ("*") is returned for the leftmost term of the name, that is dynamically assigned in the EndPointNameList, to indicate that arbitrary names apply, and that the endpoints are virtual and non-persistent. The "all of" wild card notation MUST NOT be used when returning the EndPointNameList for persistent endpoints however. The following example illustrates this: ba/z: announcement/* ba/z: foo/bar/* ba/z: foo/foo/* Foster et al. Informational [Page 5]
MGCP Bulk Audits and Redirect July 2001 The "all of" wildcard tells us, that "announcement" is simply the leftmost term for a dynamic set of non-persistent virtual endpoints. To instantiate one of these endpoints, we would include the "any of" wildcard (e.g. "announcement/$") as the LocalEndpointName in the EndpointId of a request (e.g. NotificationRequest or CreateConnection). The response would then include the SpecificEndpointId indicating the instantiated endpoint. Also note in the above example, that "foo" defines two different levels of dynamic virtual endpoints. The ConnectionCountList indicates the number of connections on a series of endpoints. It consists of a number of lines with the following ABNF syntax: "BA/C:" 0*WSP NumConnections 0*(NumConnections) where NumConnections is either: * a hexa-decimal digit indicating the number of connections on the endpoint corresponding to the position on the list, or * the letter "Z" indicating that there are more than 15 connections on this endpoint. The EndpointStateList gives an overview of the endpoint state for a series of endpoints. It consists of a number of lines with the following ABNF syntax: "BA/S:" 0*WSP EndPointState 0*(EndPointState) EndPointState = "T" / "F" / "O" where: * "T" indicates "True" * "F" indicates "False" * "O" indicates "Out of Service" The "True" or "False" determination is based on the criteria supplied in StateType parameters when the request is made. Note that the EndPointState indicator does not say anything about the connection state of the endpoint. The NextEndpointName parameter will be included in the return, if there are additional endpoints in this gateway, that were not reported, but for which information is available to be reported. Note that the NextEndpointName is the LocalEndpointName (as opposed to EndpointName) of the next endpoint after the last endpoint reported. The syntax is as follows: "BA/NE" ":" 0*WSP LocalEndpointName Foster et al. Informational [Page 6]
MGCP Bulk Audits and Redirect July 2001 A gateway may supply a report that is shorter than the request if the resulting report would have resulted in a message that would be too large. 2.1.2. Bulk Auditing of Dynamic Virtual Endpoints Gateways that have dynamic virtual endpoints may precede groups of ConnectionCountList or EndpointStateList lines with an InstantiatedEndpointList to indicate which endpoints the ConnectionCountList or EndpointStateList are referring to. This may be required because the instantiated endpoints may be disjoint with respect to the name space. Example: A Call Agent requests to know about the EndPointNameList for the endpoints on a conference bridge: AUEP 1200 *@gw1.x.net MGCP 1.0 BA/F: BA/Z Response: 200 1200 OK ba/z: cnf/*@gw1.x.net This indicates the naming convention but in fact not all of these endpoints are instantiated. A request for the list of instantiated endpoints, i.e.: AUEP 1201 cnf/*@gw1.x.net MGCP 1.0 BA/F: BA/X might yield: 200 1201 OK ba/x: cnf/[1-3]@gw1.x.net ba/x: cnf/[6-12]@gw1.x.net indicating that only these particular endpoints are instantiated. Suppose the Call Agent now asks for the ConnectionCountList i.e.: AUEP 1202 cnf/*@gw1.x.net MGCP 1.0 BA/F: BA/C Because, the instantiated virtual endpoints are disjoint, the gateway may include an InstantiatedEndpointList in front of each ConnectionCountList e.g.: 200 1202 OK ba/x: cnf/[1-3]@gw1.x.net ba/c: 035 Foster et al. Informational [Page 7]
MGCP Bulk Audits and Redirect July 2001 ba/x: cnf/[6-12]@gw1.x.net ba/c: 3450333 2.1.3. Package Specific Return Codes The following return codes are specific to this package: 800 Invalid NextEndpointName 801 Invalid Ranged Local Name 802 Invalid or unsupported BulkRequestInfo Parameter 803 Invalid or unsupported StateType 804 Bulk Audit Type not supported 805 Incorrectly specified endpoint range Note that package specific error codes includes the package name following the error code. For example, if error code 801 occurs in response to a request with a transaction ID of 1001 it would be sent as: 801 1001 /BA 2.2. Examples of Package Use 2.2.1. Endpoint List This section contains examples of obtaining the list of endpoints. Example 1: This is an example of a gateway that contains a single OC3 that contains a single level of hierarchy at the T1 level. The request is made: AUEP 1200 *@gw1.x.net MGCP 1.0 BA/F: BA/Z This may result in a single "BA/Z" term with ranges specifying all of the endpoints. 200 1200 OK ba/z: ds/ds1-[1-84]/[1-24]@gw1.x.net Example 2: In this example the gateway has 10 analog lines and a single T1. The same request is made as in example 1, but now the response is: 200 1200 OK ba/z: aaln/[1-10]@gw1.x.net ba/z: ds/ds1-1/[1-24]@gw1.x.net 2.2.2. Connection Count List Example1: Audit the number of connections on endpoints of a single E1 Foster et al. Informational [Page 8]
MGCP Bulk Audits and Redirect July 2001 AUEP 2111 ds/e1-3/*@gw1.net BA/F: BA/C Response 200 2111 OK BA/C: 01211121000100000100000100001001 Example 2: Audit the number of connections on endpoints of a DS3: AUEP 1144 ds/ds3-1/*@gateway.net BA/F: BA/C Response: 200 1144 OK BA/C:01100001000100000100000100001000 BA/C:01100001000100000100000100001000 : . BA/C:01100001000100000100000100001000 BA/C:01100001000100000100000100001000 BA/C:01100001000100000100000100001000 BA/NE: ds/ds3-1/193 In this case, the response provided by the gateway contained information about the first 192 endpoints. If the ds-3 contained a T1 hierarchy, the BA/NE" value would indicate that hierarchy e.g. instead of " BA/NE: ds/ds3-1/193" as above, it might be: BA/NE: ds/ds3-1/ds1-9/1 The Call Agent could continue to request endpoints by indicating the starting endpoint where it left off, i.e. simply using the returned "BE/NE" value as the "BA/SE" value for the next request: AUEP 1145 ds/ds3-3/*@gw1.net BA/F: BA/C BA/SE: ds/ds3-1/193 or "BA/SE: ds/ds3-1/ds1-9/1" in the case where there was a T1 hierarchy. Example 3: In this case, the Call Agent wants to know about the connection state of 12 DS0's starting with the endpoint with the LocalEndpointName "ds/ds3-1/ds1-6/4": AUEP 1146 ds/ds3-1/*@gw1.net BA/F: BA/C Foster et al. Informational [Page 9]
MGCP Bulk Audits and Redirect July 2001 BA/SE: ds/ds3-1/ds1-6/4 BA/NU: 12 Response: 200 1144 OK BA/C:011000010001 BA/NE: ds/ds3-1/ds1-6/17 Note that NextEndpointName was returned even though the response included information for the max 12 endpoints requested. The reason is, that the wildcarded EndpointId in the request covers more than 12 endpoints. 2.2.3. Endpoint State Endpoint state requests and responses are similar. An example of requesting endpoint state similar to example 3 in the previous section: AUEP 1150 ds/ds3-1/*@gw1.net BA/F: BA/S(I) BA/SE: ds/ds3-1/ds1-6/4 BA/NU: 12 Response: 200 1150 OK BA/S:TOOTTOOTTOOT BA/NE: ds/ds3-1/ds1-6/17 The request for in-service endpoints returns "True" for all endpoints in-service, and "O" for all endpoints "Out of Service". A similar request but with parameters might be: AUEP 1151 ds/ds3-1/*@gw1.net BA/F: BA/S(H,N) BA/SE: ds/ds3-1/ds1-6/4 BA/NU: 12 Response: 200 1151 OK BA/S:FFFTFFFFFFFOT BA/NE: ds/ds3-1/ds1-6/17 This indicates that at least one of the StateType parameters "H" (off-hook) and "N" (notification state) evaluated to true for the endpoints that have a "T" associated with then (i.e. ds/ds3-1/ds1-6/7 and ds/ds3-1/ds1-6/16 since the request started from ds/ds3-1/ds1- Foster et al. Informational [Page 10]
MGCP Bulk Audits and Redirect July 2001 6/4). All other endpoints are neither off-hook nor in the "notification state". Note that endpoint ds/ds3-1/ds1-6/15 is marked as being out-of-service. 3.0. Redirect and Reset Package Package Name: RED Version: 0 Package Description: The purpose of this package is to: * allow a Call Agent to pass a new "notified entity" to a collection of endpoints specified by an "all of" wild card. This is useful in the case where a new Call Agent takes over from a previous one and wants to re-direct endpoint(s) to send "Notifies" etc. to it from now on, * allow a Call Agent to request a number of endpoints to do a reset. Both of these capabilities make use of the EndpointConfiguration command. A new NotifiedEntity parameter can be included with a "RED/N" parameter as follows: EPCF 1200 *@gw1.whatever.net MGCP 1.0 RED/N: ca1@ca1234.whatever.net This changes the "notified entity" for the endpoint(s) to the value specified. If the "all of" wildcard convention is used, the NotifiedEntity value replaces all of the existing "notified entities" for those endpoints. If NotifiedEntity is omitted in a subsequent EndpointConfiguration command, the "notified entity" remains unchanged. Another EndpointConfiguration parameter ("RED/R"), allows the Call Agent to reset one or more endpoints ("all-of" wild-card allowed). The ABNF syntax for the parameter line is as follows: "RES/R:" 0*WSP "reset" This has the effect of re-setting and re-initializing the specified endpoints (i.e. any connections on the endpoint will be deleted, and the endpoint will be returned to the idle state). The resulting "reset" has no affect on service state. Note that in contrast to the normal MGCP behavior, if the request is made on an out-of-service endpoints, the command will be acknowledged (i.e. it will not be rejected), but the request will not have any affect on that endpoint. 4.0. References [1} Arango et al, Media Gateway Control Protocol (MGCP)Version 1.0bis, draft-andreasen-mgcp-rfc2705bis-01.txt 5.0. Authors' Addresses Foster et al. Informational [Page 11]
MGCP Bulk Audits and Redirect July 2001 Flemming Andreasen Cisco Systems 499 Thornall Street, 8th Floor Edison, NJ 08837 EMail: fandreas@cisco.com David Auerbach Cisco Systems Europe 11, rue Camille Desmoulins 92782 Issy Les Moulineaux CEDEX 9 รป France EMail: dea@cisco.com Bill Foster Cisco Systems EMail: bfoster@cisco.com 6.0. Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Foster et al. Informational [Page 12]