1. DL manuals
  2. TANDBERG
  3. Software
  4. Gatekeeper/Border Controller
  5. User Manual

TANDBERG Gatekeeper/Border Controller User Manual

Manual is about: TANDBERG Gatekeeper/Border Controller API User Guide

Summary of Gatekeeper/Border Controller

  • Page 1

    Tandberg gatekeeper/border controller api user guide d14172.01 july 2008.

  • Page 2: Table of Contents

    Tandberg gatekeeper/border controller api user guide d14172.01 page 2 of 84 table of contents 1 the tandberg api ................................................................................................................. 3 1.1 introduction to xml...................................................

  • Page 3: 1 The

    Tandberg gatekeeper/border controller api user guide d14172.01 page 3 of 84 1 the tandberg api this document is a guide to the api interface of the tandberg gatekeeper and border controller products. All rights reserved. This document contains information that is proprietary to tandberg. No part of ...

  • Page 4: 1.1 Introduction

    Tandberg gatekeeper/border controller api user guide d14172.01 page 4 of 84 1.1 introduction to xml xml is a markup language for documents containing structured information. All information elements in an xml document are marked by a tag and a corresponding end-tag. The end-tag has the same name as ...

  • Page 5

    Tandberg gatekeeper/border controller api user guide d14172.01 page 5 of 84 example 1.3 if we now look at the ntp element once ntp has been correctly configured we see that it now contains more sub-structure: 123 2008-01-01 12:00:00 1 in this example, the attributes are used to provide valuable info...

  • Page 6: 1.2

    Tandberg gatekeeper/border controller api user guide d14172.01 page 6 of 84 1.2 introduction to xml path language (xpath) xpath is a comprehensive language to address data in xml documents. It is, however, very simple to understand the basics. If you are able to specify the path to a file on your co...

  • Page 7

    Tandberg gatekeeper/border controller api user guide d14172.01 page 7 of 84 example 1.7 when using xpath it is possible to omit specifying intermediate levels in the address expression. By using the powerful “double slash" you can address elements without having to specify the complete path. To show...

  • Page 8: 1.3

    Tandberg gatekeeper/border controller api user guide d14172.01 page 8 of 84 1.3 the tandberg xml engine the tandberg xml engine is optimized for advanced machine-machine interaction between a tandberg system and an external control application. The main features can be summarized as: • structuring o...

  • Page 9: 1.4

    Tandberg gatekeeper/border controller api user guide d14172.01 page 9 of 84 monitor by using xpath. The user/control application can therefore limit the amount of information it receives from the target system to only those parts being of interest for the given application. 1.4 the xml documents 1.4...

  • Page 10

    Tandberg gatekeeper/border controller api user guide d14172.01 page 10 of 84 example 1.9 the element zone will contain different sub elements depending on the zone status: no gatekeeper reachable myneighbor dns resolution failed 1719 unlimited unlimited 0 myneighbor 1719 unlimited unlimited 0 in the...

  • Page 11

    Tandberg gatekeeper/border controller api user guide d14172.01 page 11 of 84 example 1.10 from the xml structure below we see that the speed element of ethernet[1] is configured to auto. The speed element references the ethernetspeed element in the valuespace document, showing the value domain for t...

  • Page 12

    Tandberg gatekeeper/border controller api user guide d14172.01 page 12 of 84 example 1.11 the command dial is defined to take five parameters. Only the callsrc and calldst parameters are required; this is specified by the attribute required. The value domain for the parameters is referenced by the a...

  • Page 13

    Tandberg gatekeeper/border controller api user guide d14172.01 page 13 of 84 example 1.13 the dial command in the above example may return the following response structure: alice@example.Com bob@example.Com 384 1 auto auto the response structure for the dial command, dialresult, states that the comm...

  • Page 14: 1.5

    Tandberg gatekeeper/border controller api user guide d14172.01 page 14 of 84 1.5 introduction to tandberg xml api service (txas) txas is a service provided by tandberg units for transmitting and receiving information encoded in xml format. The api uses http(s) as the transport mechanism and connects...

  • Page 15

    Tandberg gatekeeper/border controller api user guide d14172.01 page 15 of 84 like getxml, it has the data url form-data encoded with one single parameter. The content-type of the document must be of type “application/x-www-form-urlencoded" and the body must be encoded accordingly (e.G. First line wi...

  • Page 16

    Tandberg gatekeeper/border controller api user guide d14172.01 page 16 of 84 putxml request uri: /putxml request parameter: http body as argument putxml is like formputxml, but uses the complete body as the argument (i.E. The content of the xmldoc parameter). The content-type should be set to either...

  • Page 17

    Tandberg gatekeeper/border controller api user guide d14172.01 page 17 of 84 the soap interface has a number of operations for dealing with status and configuration: getxml returns status or configuration information for a specified xpath expression. The returned value is an xml document. Getconfigu...

  • Page 18

    Tandberg gatekeeper/border controller api user guide d14172.01 page 18 of 84 example 1.22 the example below performs the same task as example 1.21 but uses getconfiguration: $client = new soapclient('http://10.0.0.1/webservices.Wsdl', array('login' => 'username>', 'password' => 'password>')); $resul...

  • Page 19: 1.6 Exercises

    Tandberg gatekeeper/border controller api user guide d14172.01 page 19 of 84 1.6 exercises the exercises in this section are based on using a tandberg gatekeeper and microsoft internet explorer. Some of the examples may however also apply to other systems and other browsers. Note! Replace the ip add...

  • Page 20

    Tandberg gatekeeper/border controller api user guide d14172.01 page 20 of 84 exercise 4 the address: http://10.0.0.1/xmlput.Ssi contains an editor where xml data can be edited and then posted to the system by pressing the save button. Below are examples of xml structures to be posted to the system: ...

  • Page 21: 2 The

    Tandberg gatekeeper/border controller api user guide d14172.01 page 21 of 84 2 the xml-based advanced command line interface the xml-based advanced command line interface, xacli, is a very flexible interface optimized for both machine-machine interaction and man-machine interaction. It is based on t...

  • Page 22

    Tandberg gatekeeper/border controller api user guide d14172.01 page 22 of 84 if the instance number of a given element is omitted, the expression addresses all instances of this element example 2.1 to address the address sub-element of dns server 2: xpath: ip/dns/server[2]/address simplepath: ip dns...

  • Page 23

    Tandberg gatekeeper/border controller 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. • xacli allows using only partial names..

  • Page 24: 2.2

    Tandberg gatekeeper/border controller api user guide d14172.01 page 24 of 84 2.2 the status-type root commands – xstatus / xhistory the information accessible through these commands is the exact same information that is available in the corresponding xml documents. To get an overview of accessible t...

  • Page 25

    Tandberg gatekeeper/border controller api user guide d14172.01 page 25 of 84 2.2.1 format status information is presented by a mark-up notation, similar to xml. The main differences are: • all braces are removed in the xacli format • xacli does not use end-tags, except for a tag to mark end of the t...

  • Page 26: 2.3

    Tandberg gatekeeper/border controller api user guide d14172.01 page 26 of 84 2.3 the configuration-type root commands - xconfiguration the information accessible through these commands is exactly the same information that is available in the corresponding xml documents. To get an overview of accessi...

  • Page 27

    Tandberg gatekeeper/border controller api user guide d14172.01 page 27 of 84 note! Only typing ? Actually addresses all configuration elements within the root command. One would therefore expect that help on all configurations would be returned. But as described above, this is a special case and onl...

  • 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: 2.4

    Tandberg gatekeeper/border controller api user guide d14172.01 page 29 of 84 2.4 the command-type root commands - xcommand to get an overview of the supported commands within a command-typeroot command, type ? Or help after the command-type root command. ? Example 2.10 xcommand ? - user commands - a...

  • Page 30

    Tandberg gatekeeper/border controller api user guide d14172.01 page 30 of 84 2.4.1 command help to get help on a specific command, type the command-type root command, followed by a command name, followed by ? Or help: ? Example 2.12 xcommand dial ? Xcomm dial ? *h xcommand dial callsrc(r): calldst(r...

  • Page 31

    Tandberg gatekeeper/border controller api user guide d14172.01 page 31 of 84 sequence notation ... When using this notation, the parameter values must be entered in the sequence as stated in the help text: example 2.16 xcommand dial alice bob 384 combination a combination of mark-up notation and seq...

  • Page 32: 2.5

    Tandberg gatekeeper/border controller api user guide d14172.01 page 32 of 84 2.5 xml output - xgetxml as an alternative to the standard xacli output format, xml format is supported through the root command xgetxml. Xgetxml takes an xpath expression as parameter and the elements (or complete document...

  • Page 33: 2.6 Special

    Tandberg gatekeeper/border controller api user guide d14172.01 page 33 of 84 2.6 special commands in addition to the root commands described above, xacli support a set of root commands that only applies to the telnet session or rs232 session from where they are issued. This lets the user/control app...

  • Page 34

    Tandberg gatekeeper/border controller api user guide d14172.01 page 34 of 84 alias 2 (type=e164, origin=endpoint): "441184960001" *s/end example 2.21 user wants to monitor for when a zone fails: xfeedback register status/zones/zone[@status="failed"] ok when a problem with a zone occurs: *s zones: zo...

  • Page 35

    Tandberg gatekeeper/border controller api user guide d14172.01 page 35 of 84 2.6.2 xpreferences the special command xpreferences lets the user/control application individually configure the telnet/rs-232 session in use. Xpreferences ? Usage: xpreferences xpathwrite or: xpreferences detaillevel or: x...

  • Page 36

    Tandberg gatekeeper/border controller api user guide d14172.01 page 36 of 84 xpreferences xmlstatusfeedback if xmlstatusfeedback is set to on, all status feedback will be returned in xml-format instead of the standard xacli status format. Example 2.26 xacli-format: *s ntp (status=active): address: "...

  • Page 37: 3 Api

    Tandberg gatekeeper/border controller api user guide d14172.01 page 37 of 84 3 api - configurations this section gives an overview of the configuration information available in the configuration xml document (configuration.Xml). All examples are presented using the standard xacli format. 3.1 configu...

  • Page 38

    Tandberg gatekeeper/border controller api user guide d14172.01 page 38 of 84 ip dns server [1..5] address: sets the ip address of up to 5 dns servers to be queried when resolving domain names. Ip dns domain name: specifies the name to be appended to the host name before a query to the dns server is ...

  • Page 39

    Tandberg gatekeeper/border controller api user guide d14172.01 page 39 of 84 ssh mode: determines whether the system can be accessed via ssh and scp. Note: you must restart the system for any changes to take effect. Http mode: determines whether the system can be accessed via the web server over htt...

  • Page 40

    Tandberg gatekeeper/border controller api user guide d14172.01 page 40 of 84 gatekeeper forwardlocationrequests: determines the behavior of the system when it receives from another gatekeeper a location request (lrq) that it cannot resolve locally. On: the request will be forwarded to neighbor gatek...

  • Page 41

    Tandberg gatekeeper/border controller api user guide d14172.01 page 41 of 84 gatekeeper downspeed percall mode: determines whether or not the system will attempt to downspeed a call if there is insufficient per-call bandwidth available to fulfill the request. On: the system will attempt to place the...

  • Page 42

    Tandberg gatekeeper/border controller api user guide d14172.01 page 42 of 84 traversal udpprobe retrycount: (applies only if the system is a border controller.) specifies the number of attempts at re- establishing a failed udp channel. Traversal udpprobe keepaliveinterval: (applies only if the syste...

  • Page 43

    Tandberg gatekeeper/border controller api user guide d14172.01 page 43 of 84 authentication database: selects between a local database and a remote ldap repository for the storage of password information for authentication. Authentication ldap basedn: specifies the distinguished name to use when con...

  • Page 44

    Tandberg gatekeeper/border controller api user guide d14172.01 page 44 of 84 zones zone [1..100] match [1..5] pattern type: (applies only if the match mode is pattern match.) determines the way in which the string must match the alias. Prefix: the string must appear at the beginning of the alias. Su...

  • Page 45

    Tandberg gatekeeper/border controller api user guide d14172.01 page 45 of 84 zones traversalzone [1..50] match [1..5] pattern type: (applies only if the match mode is pattern match.) determines the way in which the string must match the alias. Prefix: the string must appear at the beginning of the a...

  • Page 46

    Tandberg gatekeeper/border controller api user guide d14172.01 page 46 of 84 subzones traversalsubzone bandwidth percall mode: determines whether there is a limit on the bandwidth of any one traversal call being handled by the system. Subzones traversalsubzone bandwidth percall limit: specifies the ...

  • Page 47

    Tandberg gatekeeper/border controller api user guide d14172.01 page 47 of 84 pipes pipe [1..100] bandwidth total limit: if this pipe has limited bandwidth, sets the maximum bandwidth (in kbps) available at any one time on the pipe. Pipes pipe [1..100] bandwidth percall mode: determines whether or no...

  • Page 48: 4 Api

    Tandberg gatekeeper/border controller api user guide d14172.01 page 48 of 84 4 api - commands this section gives an overview of the supported system commands. All examples are presented using the standard xacli format. 4.1 command.Xml – xcommand adhocconference transfers all calls for the specified ...

  • Page 49

    Tandberg gatekeeper/border controller api user guide d14172.01 page 49 of 84 bandwidth(r): the requested bandwidth of the call (in kbps). Calltype(r): whether the call type is traversal, routed or direct. Credentialadd adds an entry to the local authentication database. Credentialname(r): defines th...

  • Page 50

    Tandberg gatekeeper/border controller api user guide d14172.01 page 50 of 84 encryptiontype: the type of encryption that will be used for the call. Disconnectcall disconnects a call. Call: the index of the call to be disconnected.. Callserialnumber: the serial number of the call to be disconnected. ...

  • Page 51

    Tandberg gatekeeper/border controller api user guide d14172.01 page 51 of 84 locate runs the system's location algorithm to locate the endpoint identified by the given alias, searching locally, on neighbors, and on systems discovered through the dns system, within the specified number of 'hops'. Res...

  • Page 52

    Tandberg gatekeeper/border controller api user guide d14172.01 page 52 of 84 registrationserialnumber: the serial number of the registration to be removed. Subzoneadd adds and configures a new subzone. Subzonename(r): assigns a name to this subzone. Address1: specifies an ip address used (in conjunc...

  • Page 53

    Tandberg gatekeeper/border controller api user guide d14172.01 page 53 of 84 percallintramode: determines whether there is a limit on the bandwidth for any one call between two endpoints within this subzone. Percallintra: specifies the bandwidth limit (in kbps) for any one call between two endpoints...

  • Page 54

    Tandberg gatekeeper/border controller api user guide d14172.01 page 54 of 84 gatekeeper2address: specifies the ip address or fqdn of the traversal server. Up to five alternate traversal servers can also be specified. Gatekeeper2port: (applies only if the system is a gatekeeper.) specifies the port o...

  • Page 55

    Tandberg gatekeeper/border controller api user guide d14172.01 page 55 of 84 match1patternreplace: (applies only if the pattern behavior is replace.) specifies the string to be used as a substitution for the part of the alias that matched the pattern. Match2mode: determines if and when a query will ...

  • Page 56

    Tandberg gatekeeper/border controller api user guide d14172.01 page 56 of 84 match4patterntype: (applies only if the match mode is pattern match.) determines the way in which the string must match the alias. Prefix: the string must appear at the beginning of the alias. Suffix: the string must appear...

  • Page 57

    Tandberg gatekeeper/border controller api user guide d14172.01 page 57 of 84 gatekeeper2port: specifies the port on the neighbor to be used. Gatekeeper3address: specifies the ip address or fqdn of this neighbor. Gatekeeper3port: specifies the port on the neighbor to be used. Gatekeeper4address: spec...

  • Page 58

    Tandberg gatekeeper/border controller api user guide d14172.01 page 58 of 84 match2patternstring: (applies only if the match mode is pattern match.) specifies the pattern against which the alias is compared. Match2patterntype: (applies only if the match mode is pattern match.) determines the way in ...

  • Page 59

    Tandberg gatekeeper/border controller api user guide d14172.01 page 59 of 84 match4patternbehavior: (applies only if the match mode is pattern match.) determines whether the matched part of the alias should be modified before an lrq is sent to this zone. Leave: the alias will be unmodified. Strip: t...

  • Page 60: 5 Api

    Tandberg gatekeeper/border controller api user guide d14172.01 page 60 of 84 5 api - status this section gives an overview of the status information available in the status xml documents (status.Xml / history.Xml / event.Xml) and the status root commands (xstatus / xhistory) of the xacli interface. ...

  • Page 61

    Tandberg gatekeeper/border controller api user guide d14172.01 page 61 of 84 systemunit software configuration traversalcalls: shows the systems traversal call capacity. Systemunit software configuration registrations: shows the systems registration capacity. Systemunit software configuration encryp...

  • Page 62

    Tandberg gatekeeper/border controller api user guide d14172.01 page 62 of 84 ip ipv6 gateway: shows the ipv6 address of the default gateway. Only present if the protocol is ipv6 or both. Ip dns server [1..5] address: shows the ip address of a configured dns server. Ip dns domain name: shows the dns ...

  • Page 63

    Tandberg gatekeeper/border controller api user guide d14172.01 page 63 of 84 externalmanager externalmanager [status = ] shows the status of the connection to the external manager. Externalmanager cause: shows an error reason for a failure to connect to the external manager. Only present if the exte...

  • Page 64

    Tandberg gatekeeper/border controller api user guide d14172.01 page 64 of 84 resourceusage totalnontraversalcalls: shows the total number of non traversal calls that have been placed on the system. Only present if the system is a gatekeeper. Resourceusage traversalcalls: shows the current number of ...

  • Page 65

    Tandberg gatekeeper/border controller api user guide d14172.01 page 65 of 84 calls call [1..900] leg [1..2] registrationid: shows the registration id of the call party if it is locally registered. Calls call [1..900] leg [1..2] serialnumber: shows the serial number of the call party registration. On...

  • Page 66

    Tandberg gatekeeper/border controller api user guide d14172.01 page 66 of 84 registrations registrations registration [1..3750] callsignaladdresses address [1..10]: shows the ip address and port to use for call signaling. Registrations registration [1..3750] rasaddresses address [1..10]: shows the i...

  • Page 67

    Tandberg gatekeeper/border controller api user guide d14172.01 page 67 of 84 zones zones defaultzone calls call [1..900]: shows the index of a call in the default zone. Zones defaultzone bandwidth total: shows the total bandwidth in kbps allowed in the default zone. Zones defaultzone bandwidth perca...

  • Page 68

    Tandberg gatekeeper/border controller api user guide d14172.01 page 68 of 84 zones traversalzone [1..50] bandwidth percall: shows the bandwidth in kbps allowed per call in the traversal zone. Zones traversalzone [1..50] bandwidth used: shows the bandwidth in kbps being used in the traversal zone. Zo...

  • Page 69

    Tandberg gatekeeper/border controller api user guide d14172.01 page 69 of 84 subzones subzones defaultsubzone registrations registration [1..3750]: shows the index of a registration in the default subzone. Subzones defaultsubzone calls call [1..900]: shows the index of a call in the default subzone....

  • Page 70

    Tandberg gatekeeper/border controller api user guide d14172.01 page 70 of 84 links links link [1..100] name: shows the name of the link. Links link [1..100] calls call [1..900]: shows the index of a call using the link. Links link [1..100] bandwidth total: shows the total bandwidth in kbps allowed o...

  • Page 71: 5.2

    Tandberg gatekeeper/border controller api user guide d14172.01 page 71 of 84 5.2 history.Xml – xhistory calls calls call [1..255] serialnumber: shows the unique serial number of the call. Calls call [1..255] state: shows the state of the call. Calls call [1..255] calltype: shows the type of the call...

  • Page 72

    Tandberg gatekeeper/border controller api user guide d14172.01 page 72 of 84 registrations registrations registration [1..255] callsignaladdresses address [1..10]: shows the ip address and port used for call signaling. Registrations registration [1..255] rasaddresses address [1..10]: shows the ip ad...

  • Page 73

    Tandberg gatekeeper/border controller api user guide d14172.01 page 73 of 84 registrations registration [1..255] registrationrejectioncause: shows the cause for the registration being rejected. Only present if the reason is registrationrejected. Registrations registration [1..255] registrationreject...

  • Page 74: 5.3

    Tandberg gatekeeper/border controller api user guide d14172.01 page 74 of 84 5.3 event.Xml – xevent callattempt callattempt call [1..900] serialnumber: shows the unique serial number of the call. Callattempt call [1..900] state: shows the state of the call. Callattempt call [1..900] calltype: shows ...

  • Page 75

    Tandberg gatekeeper/border controller api user guide d14172.01 page 75 of 84 callattempt call [1..900] duration: shows the duration of the call in seconds. Callattempt call [1..900] sourcealias: shows the alias of the source call party. Callattempt call [1..900] sourceaddress: shows the ip address a...

  • Page 76

    Tandberg gatekeeper/border controller api user guide d14172.01 page 76 of 84 connected call [1..900] leg [1..2] address: shows the ip address and port of the call party. Connected call [1..900] leg [1..2] encryption [status = ] shows the status of encryption on the call leg. Connected call [1..900] ...

  • Page 77

    Tandberg gatekeeper/border controller api user guide d14172.01 page 77 of 84 disconnected call [1..900] starttime: shows the time at which the call was initiated. Disconnected call [1..900] duration: shows the duration of the call in seconds. Disconnected call [1..900] disconnectcausevalue: shows th...

  • Page 78

    Tandberg gatekeeper/border controller api user guide d14172.01 page 78 of 84 connectionfailure call [1..900] starttime: shows the time at which the call was initiated. Connectionfailure call [1..900] duration: shows the duration of the call in seconds. Connectionfailure call [1..900] disconnectcause...

  • Page 79

    Tandberg gatekeeper/border controller api user guide d14172.01 page 79 of 84 registration registration [1..3750] mcu prefix [1..200]: shows the prefix of a registered mcu service. Only present if the registration is an mcu. Registration registration [1..3750] outofresources: shows the resource usage...

  • Page 80

    Tandberg gatekeeper/border controller api user guide d14172.01 page 80 of 84 unregistration registration [1..3750] mcu: shows that the registration was an mcu. Only present if the registration was an mcu. Unregistration registration [1..3750] mcu prefix [1..200]: shows the prefix of a registered mcu...

  • Page 81

    Tandberg gatekeeper/border controller api user guide d14172.01 page 81 of 84 registrationfailure registration [1..3750] gateway prefix [1..200]: shows the prefix of a registered gateway service. Only present if the registration was a gateway. Registrationfailure registration [1..3750] mcu: shows tha...

  • Page 82

    Tandberg gatekeeper/border controller api user guide d14172.01 page 82 of 84 bandwidth bandwidth call [1..900] serialnumber: shows the unique serial number of the call. Bandwidth call [1..900] state: /connectionfailed/parked/parking/unparking/parkfailed> shows the state of the call. Bandwidth call [...

  • Page 83

    Tandberg gatekeeper/border controller api user guide d14172.01 page 83 of 84 bandwidth call [1..900] duration: shows the duration of the call in seconds. Bandwidth call [1..900] sourcealias: shows the alias of the source call party. Bandwidth call [1..900] sourceaddress: shows the ip address and por...

  • Page 84

    Tandberg gatekeeper/border controller api user guide d14172.01 page 84 of 84 resourceusage resourceusage registrations: shows the current number of registrations on the system. Resourceusage maxregistrations: shows the maximum number of concurrent registrations on the system. Resourceusage nontraver...