TANDBERG Gatekeeper/Border Controller, User Manual

Page 1: ...TANDBERG Gatekeeper Border Controller API User Guide D14172 01 July 2008...

Page 2: ...1 6 Exercises 19 2 The XML based Advanced Command Line Interface 21 2 1 XACLI 21 2 2 The Status type root commands xstatus xhistory 24 2 3 The Configuration type root commands xconfiguration 26 2 4 Th...

Page 3: ...to change without prior notice and should not be construed as a commitment by TANDBERG The information in this document is believed to be accurate and reliable however TANDBERG assumes no responsibil...

Page 4: ...ain one or more sub elements while value elements contain a value This is analogous to files and folders on a computer Container elements are folders that can contain sub folders and files while value...

Page 5: ...ributes are used to provide valuable information in addition to establishing a dependency to the underlying sub structure of the element Example 1 4 In the above examples all elements have an attribut...

Page 6: ...item 1 Administrator SystemContact SystemLocation item 1 SystemLocation SNMP Configuration To specify the path to the SNMP element we simply start at the root level and separate the levels in the tre...

Page 7: ...without having to specify the complete path To show all the aliases registered on the system the complete path would be Status Registrations Registration Aliases Alias Using the double slash syntax th...

Page 8: ...rite information Command Information Information supplied by the user to initiate an action For example instructing the system to place a call disconnect an existing call remove a registration etc A c...

Page 9: ...cuments a configuration xml 3 Command documents w Documents defining the supported system commands used to initiate system processes This is write data i e the parameter values for a given command are...

Page 10: ...ne Zones Status Status Zones item 1 Zone item 1 status Active Name item 1 MyNeighbor Name Gatekeeper item 1 status Active Address 10 0 0 10 Address Port item 1 1719 Port Gatekeeper Calls item 1 Bandwi...

Page 11: ...Value 100half Value Value 100full Value EthernetSpeed ValueSpace To change configurations the part s of the document containing the configurations to be updated should be posted back to the system wi...

Page 12: ...lueSpace EncryptionTypesSpace item 1 EncryptionType Dial Command To issue a command the command structure is posted back to the system together with values for the various parameters Optional paramete...

Page 13: ...DialResult Command The response structure for the Dial command DialResult states that the command was accepted by the system In addition to stating that the command was accepted the Dial command retur...

Page 14: ...t or using the application x www form urlencoded content type method of POSTing form data getxml Request URI getxml Request parameter location XPath expression The getxml request returns an XML docume...

Page 15: ...iguration value can be confirmed using the getxml request curl k u admin password https 10 0 0 1 getxml location Configuration SNMP SystemContact xml version 1 0 Configuration SNMP item 1 SystemContac...

Page 16: ...vices wsdl e g http 10 0 0 1 webservices wsdl Most programming environments have built in support for developing web service clients or else third party libraries are available The following examples...

Page 17: ...ration The configuration parameter is passed as strongly typed SOAP parameters as defined in the WSDL document Example 1 20 The example below shows how to use GetXML to retrieve information about the...

Page 18: ...figurationXML to modify the SNMP system contact configuration php client new SoapClient http 10 0 0 1 webservices wsdl array login username password password config_xml Configuration xmlns http www ta...

Page 19: ...0 0 1 command xml http 10 0 0 1 valuespace xml Exercise 2 This exercise shows how to use getxml to read the supported XML documents from the system Enter the following expressions in the browser s ad...

Page 20: ...to the system by pressing the save button Below are examples of XML structures to be posted to the system Configuration SNMP SystemContact Administrator SystemContact SNMP Configuration Configuration...

Page 21: ...ing a serial cable to the serial interface connector referred to as the Dataport UP to 48 Telnet sessions can be active at the same time in addition to the RS 232 connection 2 1 2 Root commands For ea...

Page 22: ...xposure option after the address XPath or SimplePath expression the system can be instructed to return only parts of the information within an element structure root command address expression exposur...

Page 23: ...er API User Guide D14172 01 page 23 of 84 Request for Zone1 element with exposure option xstatus zones zone 1 s Zones Zone 1 status Active s end 2 1 5 Misc The XACLI interface is not case sensitive XA...

Page 24: ...mmand Example 2 3 xstatus Status Calls NTP Ethernet Options ExternalManager Pipes Feedback 1 3 Registrations Gatekeeper ResourceUsage IP SubZones LDAP SystemUnit Links Zones OK xhistory History Calls...

Page 25: ...one instance of a given element exists A status top level element starts with s Example 2 5 shows XML formatting and XACLI formatting for the same status element NTP Example 2 5 XML Status NTP item 1...

Page 26: ...inks SSH ExternalManager Log SubZones Gatekeeper NTP SystemUnit HTTP Option 1 64 Telnet HTTPS Pipes TimeZone IP Services Traversal IPProtocol Session Zones OK 2 3 1 Configuration help To get help on c...

Page 27: ...ommand followed by an address expression configuration type root command address expr Example 2 8 User wants to read IP configurations ip c IPProtocol IPv4 c IP Address 10 0 0 1 c IP SubnetMask 255 25...

Page 28: ...TANDBERG Gatekeeper Border Controller API User Guide D14172 01 page 28 of 84 Example 2 9 User wants to set IP address ip address 10 0 0 1 or ip address 10 0 0 1...

Page 29: ...llTransfer FeedbackRegister SubZoneDelete CheckBandwidth FindRegistration TransformAdd CredentialAdd LinkAdd TransformDelete CredentialDelete LinkDelete TraversalZoneAdd DefaultLinksAdd Locate Travers...

Page 30: ...ng a command A command must start with a command type root command followed by a command name followed by a set of parameters Parameters values can either be specified by a mark up notation or by plac...

Page 31: ...system will assign the sequence entered parameters for the parameters not yet having been assigned a value Example 2 17 xcommand dial alice B 384 bob Command response When issuing a command the syste...

Page 32: ...through the root command xgetxml xgetxml takes an XPath expression as parameter and the elements or complete document matching the expression will be returned Example 2 19 xgetxml status ntp Status NT...

Page 33: ...nts addressed by a registered XPath expression the part of the element structure containing these changes will be returned The system supports a total of 20 registered expressions with a total of 15 e...

Page 34: ...nts to monitor for when a zone fails xfeedback register status zones zone status Failed OK When a problem with a zone occurs s Zones Zone 1 status Failed Cause No gatekeeper reachable Name MyNeighbor...

Page 35: ...application must supply the complete path to the configurations to be set no double slashes allowed This will improve the performance of the system when issuing many consecutive configurations NOTE I...

Page 36: ...12 00 00 LastUpdate LastCorrection item 1 1 LastCorrection NTP Status xpreferences xmlcommandresult on off If xmlcommandresult is set to on response for commands will be returned in XML format Example...

Page 37: ...information Ethernet Speed Auto 10half 10full 100half 100full Specifies the setting of the Ethernet link Use Auto to automatically configure the speed Note You must restart the system for any changes...

Page 38: ...making LDAP queries LDAP UserDN S 0 255 Sets the user distinguished name to be used when binding to the LDAP server LDAP Password S 0 25 Sets the password to be used when binding to the LDAP server LD...

Page 39: ...etween endpoints Note Applies only to non traversal calls the signaling of traversal calls will always be routed via the system regardless of this setting Gatekeeper LocalPrefix S 0 60 Sets the local...

Page 40: ...low List If one of an endpoint s aliases matches one of the patterns in the Allow List the registration will be permitted Gatekeeper Registration DenyList 1 2500 Pattern S 0 60 Specifies an entry to b...

Page 41: ...d in order of priority and the priority must be unique for each transform Gatekeeper Transform 1 200 Type Prefix Suffix Regex Determines the way in which the string must match the alias Prefix the str...

Page 42: ...t Traversal Media RTCP Port 1 65534 Applies only if the system is a Border Controller Specifies the UDP port to which media control information should be sent Traversal AssentEnabled On Off Applies on...

Page 43: ...ystem that is not configured as a neighbor zone or traversal zone Zones Zone 1 100 Name S 1 50 Assigns a name to this zone Zones Zone 1 100 Gatekeeper 1 6 Address S 0 128 Specifies the IP Address or F...

Page 44: ...Zones TraversalZone 1 50 Mode Assent H46018 Determines which H 323 traversal protocol to use either Assent or H 460 18 Zones TraversalZone 1 50 AccountName S 0 50 Specifies the account name to be used...

Page 45: ...ndpoints at any one time None corresponds to no bandwidth available SubZones DefaultSubZone Bandwidth Total Limit 1 100000000 Sets the total bandwidth limit in kbps of the Default Subzone applies only...

Page 46: ...call to or from an endpoint in this subzone SubZones SubZone 1 100 Bandwidth PerCall Inter Limit 1 100000000 Specifies the bandwidth limit in kbps on any one call to or from an endpoint in this subzo...

Page 47: ...0 Node2 Name S 0 50 Specifies the second zone or subzone to which this link will be applied Links Link 1 100 Pipe1 Name S 0 50 Specifies the first pipe to be associated with this link Links Link 1 100...

Page 48: ...rmitted AllowListDelete Deletes an entry from the Allow List AllowListId r 1 2500 The index of the entry to be deleted Boot Reboots the system This command has no parameters CallTransfer Transfers the...

Page 49: ...lues Level 1 will reset most parameters There are currently no level 2 parameters so setting that level has the same effect as setting level 1 Level 3 resets all level 1 and 2 parameters as well as ad...

Page 50: ...change to be notified See the Administrator Guide for a full list of valid Expressions FeedbackDeregister Deactivates a particular feedback request ID 1 3 The ID of the feedback request to be deactiv...

Page 51: ...ANDBERG representative for further information OptionKeyDelete Deletes a software option key from the system OptionKeyId r 1 64 Specifies the ID of the software option to be deleted PipeAdd Adds and c...

Page 52: ...e Subnet IP Address which must match for an IP Address to belong in this subzone Address4 S 0 39 Specifies an IP Address used in conjunction with the IP Prefix Length to identify a subnet to be assign...

Page 53: ...p the matching prefix or suffix will removed from the alias Replace the matching part of the alias will be substituted with the text in the Replace string Replace S 1 60 Applies only if pattern behavi...

Page 54: ...specified Gatekeeper6Port 1 65534 Applies only if the system is a Gatekeeper Specifies the port on the traversal server to connect to HopCount 1 255 Specifies the hop count to be used when sending an...

Page 55: ...t matched the pattern Match3Mode AlwaysMatch PatternMatch Disabled Determines if and when a query will be sent to this zone Always the zone will always be queried Pattern the zone will only be queried...

Page 56: ...eried Match5PatternString S 0 60 Applies only if the Match mode is Pattern Match Specifies the pattern against which the alias is compared Match5PatternType Prefix Suffix Regex Applies only if the Mat...

Page 57: ...will always be queried Pattern the zone will only be queried if the alias queried for matches the corresponding pattern Disabled the zone will never be queried Match1PatternString S 0 60 Applies only...

Page 58: ...he pattern against which the alias is compared Match3PatternType Prefix Suffix Regex Applies only if the Match mode is Pattern Match Determines the way in which the string must match the alias Prefix...

Page 59: ...er be queried Match5PatternString S 0 60 Applies only if the Match mode is Pattern Match Specifies the pattern against which the alias is compared Match5PatternType Prefix Suffix Regex Applies only if...

Page 60: ...teger Shows the uptime in seconds SystemUnit SystemTime String Shows the system time SystemUnit TimeZone String Shows the time zone SystemUnit TimeZone String Shows the time zone SystemUnit LocalTime...

Page 61: ...ptions Options Option 1 64 Key String Shows an installed option key Options Option 1 64 Description String Shows a description of the option key Ethernet Ethernet MacAddress String Shows the MAC addre...

Page 62: ...server Only present if the NTP status is Active or Failed NTP LastUpdate String Shows the time at which the last NTP update occurred Only present if the NTP status is Active NTP LastCorrection String...

Page 63: ...o Only present if the external manager status is Active or Failed Feedback Feedback 1 3 status On Off Shows whether feedback is configured Feedback 1 3 URL String Shows the URL of a system which has r...

Page 64: ...on for a failure to connect to the alternate system Only present if the alternate status if Failed Gatekeeper Alternates Alternate 1 5 Address String Shows the address of the alternate system Gatekeep...

Page 65: ...IP address and port of the call party Calls Call 1 900 Leg 1 2 Encryption status On Off Shows the status of encryption on the call leg Calls Call 1 900 Leg 1 2 Encryption CheckCode String Shows the ch...

Page 66: ...Registration 1 3750 MCU Shows that the registration is an MCU Only present if the registration is an MCU Registrations Registration 1 3750 MCU Prefix 1 200 String Shows the prefix of a registered MCU...

Page 67: ...ne 1 50 Name String Shows the name of the traversal zone Zones TraversalZone 1 50 Traversal Assent H46018 Shows the traversal type of the traversal zone Zones TraversalZone 1 50 AccountName String Sho...

Page 68: ...e 1 50 Gatekeeper 1 6 status Unknown Active Failed Shows the status of the connection to the gatekeeper Zones Zone 1 50 Gatekeeper 1 6 Cause String Shows an error reason for a failure to communicate w...

Page 69: ...SubZone SubZones TraversalSubZone Bandwidth Total String Shows the total bandwidth in kbps allowed in the Traversal SubZone SubZones TraversalSubZone Bandwidth PerCall String Shows the bandwidth in k...

Page 70: ...e bandwidth in kbps allowed per call on the link Links Link 1 100 Bandwidth Used String Shows the bandwidth in kbps being used on the link Pipes Pipes Pipe 1 100 Name Integer Shows the name of the pip...

Page 71: ...call party Calls Call 1 255 Leg 1 2 Address String Shows the IP address and port of the call party Calls Call 1 255 StartTime String Shows the time at which the call was initiated Calls Call 1 255 Du...

Page 72: ...way service Only present if the registration was a gateway Registrations Registration 1 255 MCU Shows that the registration was an MCU Only present if the registration was an MCU Registrations Registr...

Page 73: ...onRejectionCause String Shows the cause for the registration being rejected Only present if the reason is RegistrationRejected Registrations Registration 1 255 RegistrationRejectionDescription String...

Page 74: ...call takes CallAttempt Call 1 900 Leg 1 2 RegistrationID String Shows the registration ID of the call party if it is locally registered CallAttempt Call 1 900 Leg 1 2 SerialNumber String Shows the se...

Page 75: ...lType Traversal Direct Routed Shows the type of the call Connected Call 1 900 Transferable On Off Shows whether this call is capable of being transferred Connected Call 1 900 Bandwidth Integer Shows t...

Page 76: ...ring Shows the IP address and port of the source call party Connected Call 1 900 DestinationAlias String Shows the alias of the destination call party Connected Call 1 900 DestinationAddress String Sh...

Page 77: ...ws the alias of the destination call party Disconnected Call 1 900 DestinationAddress String Shows the IP address and port of the destination call party ConnectionFailure ConnectionFailure Call 1 900...

Page 78: ...of the destination call party Only present if the destination address could be determined Registration Registration Registration 1 3750 CallSignalAddresses Address 1 10 String Shows the IP address an...

Page 79: ...ration belongs Registration Registration 1 3750 SerialNumber String Shows the unique serial number of the registration Registration Registration 1 3750 StartTime String Shows the time at which this re...

Page 80: ...on Registration 1 3750 StartTime String Shows the time at which this registration was created Unregistration Registration 1 3750 EndTime String Shows the time at which this registration ended Unregist...

Page 81: ...e Registration 1 3750 Aliases Alias 1 200 String Shows the alias value RegistrationFailure Registration 1 3750 SubZone String Shows the subzone to which this registration belonged RegistrationFailure...

Page 82: ...link that is part of the route the call takes Bandwidth Call 1 900 Leg 1 2 RegistrationID String Shows the registration ID of the call party if it is locally registered Bandwidth Call 1 900 Leg 1 2 S...

Page 83: ...eing searched for LocateResult CallSerialNumber String Shows the unique serial number of the call LocateResult Location Type Local Database Neighbor Traversal Shows the type of location being searched...

Page 84: ...sourceUsage MaxNonTraversalCalls Integer Shows the maximum number of concurrent non traversal calls on the system Only present if the system is a Gatekeeper ResourceUsage TotalNonTraversalCalls Intege...