TANDBERG Gatekeeper User Guide Software version N5.1 D13381.07 January 2007 This document is not to be reproduced in whole or in part without permission in writing from:...
Portions of this software are licensed under 3rd party licenses. See the CD accompanying this product for details. 3rd party license information may also be obtained from the Gatekeeper itself -- see the license command in section 16.6.4 for details.
Digital User Guides TANDBERG is pleased to announce that we have replaced the printed versions of our User Guides with a digital CD version. Instead of a range of different user manuals, there is now one CD -- which can be used with all TANDBERG products -- in a variety of languages.
Do not operate the apparatus in areas with high concentration of dust. 1.4.6. Vibration Do not operate the apparatus in areas with vibration or place it on an unstable surface. TANDBERG Gatekeeper User Guide Page 10 of 105...
Do not use communication equipment to report a gas leak in the vicinity of the leak. To reduce the risk of fire, use only No. 26 AWG or larger telecommunication line cord (ISDN cables). TANDBERG Gatekeeper User Guide Page 11 of 105...
Up to 100 traversal calls in conjunction with a TANDBERG Border Controller. Can be used to control the amount of bandwidth used both within the Gatekeeper zone and to neighboring Border Controllers and Gatekeepers. Can limit total bandwidth usage and set maximum per call bandwidth usage with automatic downspeeding if call exceeds per-call maximum.
Page 13
Figure 1: Front panel of Gatekeeper On the back of the Gatekeeper (see Figure 2) there are: a power connector a power switch a serial port (Data 2) for connecting to a PC. Figure 2: Rear panel of Gatekeeper...
Make sure that the Gatekeeper is accessible and that all cables can be easily connected. For ventilation: Leave a space of at least 10cm (4 inches) behind the Gatekeeper's rear and 5cm (2 inches) on the sides. ...
3.4. Mounting The Gatekeeper comes with brackets for mounting in standard 19" racks. Before starting the rack mounting, please make sure the TANDBERG Gatekeeper is placed securely on a hard, flat surface. Disconnect the AC power cable. Make sure that the mounting space is according to the Installation site preparations in section 3.2.
PC connected to the serial port (Data 1) or by connecting to the system's default IP address: 192.168.0.100. The IP address, subnet mask and gateway must be configured before use. The Gatekeeper has to be configured with a static IP address. Consult your network administrator for information on which addresses to use.
HTTPS and SSH protocols instead. For increased security, disable HTTPS and SSH as well, using the serial port to manage the system. Note: If you do not have an IP gateway, configure the Gatekeeper with an unused IP address that is valid in your subnet.
A miscellaneous group of commands for setting information or obtaining it. xhistory Provides historical information about calls and registrations. xfeedback An event interface, providing information about calls and registrations. See the Command Reference (section 16) for a full list of commands. TANDBERG Gatekeeper User Guide Page 18 of 105...
Note: The pwrec account is only active for one minute following a restart. Beyond that time you will have to restart the system again to change the password. Because access to the serial port allows the password to be reset, it is recommended that you install the Gatekeeper in a physically secure environment.
4.4. IP Configuration The Gatekeeper may be configured to use IPv4, IPv6 or both protocols. If using both protocols, the Gatekeeper will act as a gateway if necessary, allowing calls to be made between an IPv4-only endpoint and an IPv6-only endpoint. This behavior will use a traversal license for each call gatewayed between IPv4 and IPv6.
In some deployments an endpoint may frequently receive a new IP address, causing unwanted registration rejections. When it tries to register, it may be rejected because the Gatekeeper still has a registration from its old IP address. The Gatekeeper may be configured to allow an endpoint to overwrite the old IP address.
When an incoming call request is received a Gatekeeper will first search all of its registered endpoints. If no match is found, all strongly matching neighbor and traversal zones will be queried concurrently. If the target is not found in any of the strongly matching zones, all weakly matching neighbor zones will be queried, then all weakly matching traversal zones.
Gatekeeper, it is presented with the IP addresses of all the Alternates. If the endpoint loses contact with its initial Gatekeeper, it will seek to register with one of the Alternates. This may result in your endpoint community's registrations being spread over all the Alternates.
4.8. Call Processing Overview Figure 6 illustrates the process the Gatekeeper performs when receiving call requests. Receive Request from Endpoint (ARQ) or other gatekeeper (LRQ) Apply Transforms Locally registered endpoint? Locally registered service? IP address literal? On local network? ...
Page 25
The destination address can take several forms: IP address, H.323 ID, E.164 alias or a full H.323 URI. When an H.323 ID or E.164 alias is used, the Gatekeeper looks for a match between the dialed address and the aliases registered by its endpoints. If no match is found, it may query other Gatekeepers and Border Controllers.
The Alias Transforms function takes any aliases present in ARQ and LRQ messages and runs a set of transformations on them. The resulting aliases will then be used in the normal Gatekeeper logic, exactly as if those aliases were unchanged. Alias transforms will be applied prior to possible CPL modification and Zone transforms.
Zone transforms support the use of Regular Expressions. See Appendix C for more information. Example Endpoints might be registered to a Gatekeeper with aliases of the form user@example.com. If someone were to dial user@exampleusa.com we might want to try and find that user as user@example.com, hence we need a rule that replaces the suffix exampleusa.com with example.com before searching off...
Not all endpoints allow you to enter an alias and an IP address to which the call should be placed. In that case you can simply place the call to the IP address of the Gatekeeper, with no alias information. The Gatekeeper may be configured to associate all such anonymous calls with a single destination alias.
Page 29
TANDBERG Gatekeeper User Guide When the Gatekeeper is used with a Border Controller for firewall traversal, you will typically set CallsToUnknownIPAddresses to Indirect on the Gatekeeper and Direct on the Border Controller. This will allow calls originating inside the firewall to use the Gatekeeper and Border Controller to successfully traverse the firewall.
7.2. Subzones All endpoints registered with your Gatekeeper are part of its local zone. As shown in Figure 9, the local zone can contain two or more different networks with different bandwidth limitations. In order to model this, the local zone is made up of one or more subzones. When an endpoint registers with the Gatekeeper it is assigned to a subzone, based on its IP address.
If multiple routes are possible, your Gatekeeper will select the one with the fewest links. Links may be configured using the web interface via command line using the following commands: xConfiguration Links Link [1..100] Name...
If bandwidth control is in use, there may be situations when there is insufficient bandwidth available to place a call at the requested rate. By default (and assuming that there is some bandwidth still available) the Gatekeeper will still attempt to connect the call, but at a reduced bandwidth - known as downspeeding .
Figure 12: Configuring downspeeding options 7.4. Bandwidth Control and Firewall Traversal When a Border Controller and Gatekeeper are being used to traverse a firewall, an additional zone and subzone come into use, as follows: The traversal zone is used to represent the zone containing the Gatekeeper with which this Gatekeeper is paired.
TANDBERG Gatekeeper and Border Controller to maintain connectivity. Figure 14: Network deployment with firewalls In Figure 14, the endpoints in the enterprise register with the Gatekeeper, whilst those in the branch and home office register with the Border Controller.
Page 35
Traversal Zone for all calls placed to endpoints managed by the Enterprise Gatekeeper. In this example we have assumed that there is no bottleneck on the link between the Border Controller and the Enterprise network, so have not placed a pipe on this link. If you want to limit the amount of traffic flowing through your firewall, you could provision a pipe on this link.
Setting Registration Restriction Policy When an endpoint registers with your Gatekeeper it presents a list of aliases. You can control which endpoints are allowed to register by including any one of its aliases on the Allow List or the Deny list.
To edit or delete an existing pattern, highlight the pattern in the list and select either Edit or Delete. TANDBERG Gatekeeper User Guide and select Add New Pattern from underneath the Page 37 of 105...
Gatekeeper communicates. In order to verify the identity of a device, the Gatekeeper needs access to the password information. This credential information may be stored in a local database on the Gatekeeper or obtained from an LDAP Directory Server.
Configuring LDAP base DN The Gatekeeper needs to be configured with the area of the directory which will be searched for the communication device information. This should be specified as the Distinguished Name (DN) in the directory under which the H.350 objects reside. To do this, either issue the following command: xConfiguration Authentication LDAP BaseDN: "Your base DN"...
The traffic between the Gatekeeper and the LDAP server can be encrypted using Transport Layer Security (TLS). To use TLS, the LDAP server must have a valid certificate installed so that the Gatekeeper can verify the server's identity. For more information on setting up certificates using common LDAP servers, see Appendix B.
Using URI dialing, you call using an H.323 URI which looks like an email address. The destination Gatekeeper is found from the domain name -- the part after the @ -- in the same way that an email server is found.
Each of these should be able to discover an endpoint registered as either user or user@a.record.domain.name. On receipt of the URI the Gatekeeper will modify the URI by removing the @ and host if the host matches either: ...
First the Gatekeeper will query for a Location SRV record, to discover the authoritative Gatekeeper for the destination DNS zone. If is not located, the Gatekeeper will query for a Call SRV record and try to place the call to that address.
The DNS zone used for ENUM contains NAPTR records as defined by RFC 2915 [7]. These provide the mapping between E.164 numbers and H.323 URIs. The Gatekeeper may be configured with up to 5 DNS zones to search for a NAPTR record. It will iterate through them in order, stopping when the first record is found.
Page 45
TANDBERG Gatekeeper User Guide Figure 19: Setting the ENUM Zone Page 45 of 105...
ENUM relies on the presence of NAPTR records, as defined by RFC 2915 [7]. This is used to obtain an H.323 URI from the E.164 number. The record format that the Gatekeeper supports is: ;; order flag preference service regex replacement IN NAPTR 10 100 "u"...
Disable URI dialing on the Gatekeeper. This is because you wish calls to be routed from the private network to the Border Controller in order to traverse the firewall. This can be done via the same commands/paths as above.
In order to be able to receive calls placed to example.com using URI dialing, configure the following: Set example.com as the domain name you are using on both the Gatekeeper and Border Controller. This can be done via either: xConfiguration Gatekeeper LocalDomain DomainName: <name>...
Figure 22 shows a private endpoint (1001) calling an endpoint on a public IP address. In this case the public endpoint is not registered to a Gatekeeper and can only be reached using its IP address. In order to successfully traverse the firewall it is necessary for the call to be relayed through the Border Controller;...
Allow DNS Resolution Controller to resolve any H.323 URI received Configure the same local domain name on both the Gatekeeper and the Border Controller. Configure the Border Controller with the address of a public DNS server. When an endpoint in our enterprise dials the full H.323 URI of an endpoint in another enterprise (for example, Ben@EnterpriseB.com), the call will be routed to our Border Controller.
12.1. About Third Party Call Control The Gatekeeper provides a third party call control API which enables you to place calls, disconnect calls, or initiate a blind transfer of an existing call. The API is provided through the command line interface; it is not available via the web interface.
Allow call transfer box (see Figure 23). Figure 23: Enabling call transfer 12.4. Disconnecting a Call An existing call may be disconnected using the Gatekeeper by issuing the command: xCommand DisconnectCall: <index> where: the call index as reported by xStatus Calls index...
13.1. About Call Policy Your TANDBERG Gatekeeper allows you to set up policy to control which calls are allowed and even redirect selected calls to different destinations. You specify this policy by uploading a script written in the Call Processing Language (CPL). Each time a call is made the Gatekeeper executes the script to decide, based on the source and destination of the call, whether to ...
If the selected field contains multiple aliases then the Gatekeeper will attempt to match each address node with all of the aliases before proceeding to the next address node i.e. an address node matches if it matches any alias.
This form is most useful when authentication is being used. With authentication enabled the Gatekeeper will only use authenticated aliases when running policy so the not-present action can be used to take appropriate action when a call is received from an unauthenticated user (see CPL Examples, section13.5).
13.3.2. proxy On executing a proxy node the Gatekeeper will attempt to forward the call to the locations specified in the current location set. If multiple entries are in the location set then they are treated as different aliases for the same destination and are all placed in the destination alias field. If the current location set is empty the call will be forwarded to its original destination.
In this example, user ceo will only accept calls from users vpsales, vpmarketing or vpengineering. <cpl> <incoming> <address-switch field="destination"> <address is="ceo"> <address-switch field="origin"> <address regex="vpsales|vpmarketing|vpengineering"> <proxy/> </address> <otherwise> <reject/> </otherwise> <not-present> <reject/> </not-present> </address-switch> </address> </address-switch> </incoming> </cpl> TANDBERG Gatekeeper User Guide Page 57 of 105...
Setting the log level You can control which events are logged by the Gatekeeper by specifying the log level. All events with a level numerically equal to and lower than the specified logging level are recorded in the event log.
For all messages logged from the tandberg process the field is structured to allow easy parsing. It consists of a number of human-readable name=value pairs, separated by a space. The first field is always: Field Example...
The Reason event parameter contains the H225 cause code. Optionally, the Detail event parameter may contain a textual representation of the H.225 additional cause code. A registration has been removed by the Gatekeeper/Border Controller. The Reason event parameter specifies the reason why the registration was removed.
Page 61
The Gatekeeper has started. Application Start Further detail may be provided in the event data Detail field. The Gatekeeper application is out of service due to an unexpected Application Failed failure. Licensing limits for a given feature have been reached.
Page 62
H.245 LDAP Neighbor Gatekeeper Specifies the type of the message. Message Type TANDBERG Gatekeeper User Guide Applicable Events Call Attempted Call Bandwidth Changed Call Connected Call Disconnected Call Rejected External Server Communication Failure Message Sent...
Page 63
If present, the first H.323 Alias associated with Dst-Alias the recipient of the message If present, the first E.164 Alias associated with the recipient of the message TANDBERG Gatekeeper User Guide Applicable Events Call Attempted Call Bandwidth Changed Call Connected...
14.6. Remote Logging The event log is stored locally on the Gatekeeper. However, it is often convenient to collect copies of all event logs from various systems in a single location. A computer running a BSD-style syslog server, as defined in RFC 3164 [4] , may be used as the central log server.
Using secure copy (SCP). Note: To upgrade the Gatekeeper, a valid Release key and software file is required. Contact your TANDBERG representative for more information. Note: Configuration is restored after performing an upgrade but we recommend that you make a backup of the existing configuration using the TANDBERG Management Suite before performing the upgrade.
Select Restart. You will see a confirmation window: The system will then perform a second reboot to restore system parameters. After 3-4 minutes, the Gatekeeper is ready for use. 15.3. Upgrading Using SCP/PSCP To upgrade using SCP or PSCP (part of the PuTTY free Telnet/SSH package) you need to transfer two files to the Gatekeeper: ...
Page 67
Upload the release key file using SCP/PSCP to the /tmp folder on the system e.g. scp release-key root@10.0.0.1:/tmp/release-key or pscp release-key root@10.0.0.1:/tmp/release-key Enter password when prompted. Copy the software image using SCP/PSCP. The target name must be /tmp/tandberg- image.tar.gz, e.g. scp s42000n51.tar.gz root@10.0.0.1:/tmp/tandberg-image.tar.gz or pscp s42100n51.tar.gz root@10.0.0.1:/tmp/tandbergimage.tar.gz Enter password when prompted.
This chapter lists the basic usage of each command. The commands also support more advanced usage, which is outside the scope of this document. 16.1. Status The status root command, xstatus, returns status information from the Gatekeeper. 16.1.1. Listing all status information To list all status information, type: xstatus Status is reported hierarchically beneath the status root.
ExternalManager xstatus ExternalManager Returns information about the external manager. The External Manager is the remote system, such as the TANDBERG Management Suite (TMS) used to manage the endpoints and network infrastructure. Returns the IP address of the external manager. Address Returns the Protocol used to communicate with the external manager.
Reports call and bandwidth information for the specified pipe. 16.1.12. Registrations xstatus Registrations Returns a list of all registered endpoints on the system and their information. xstatus Registrations Registration <index> Returns information about the specified registration. TANDBERG Gatekeeper User Guide Page 70 of 105...
Software version Software Build Software name Software release date Number of calls supported Number of registered endpoints and services supported Hardware serial number Hardware version TANDBERG Gatekeeper User Guide Page 71 of 105...
Zones xstatus Zones Returns call and bandwidth information for all zones on the system. Also shows status of the zone as a whole and the status of each gatekeeper in the zone. 16.2. Configuration The configuration root command, xconfiguration, is used to configuration the system's settings.
Gatekeeper Alternates Alternate [1..5] Address: <IPAddress> Sets the IP address of an alternate Gatekeeper. Up to 5 alternates may be configured. When the Gatekeeper receives a Location Request, all alternates will also be queried. xconfiguration Gatekeeper Alternates Alternate [1..5] Port: <Port>...
Page 74
Gatekeeper CallsToUnknownIPAddresses: <Off/Direct/Indirect> Specifies whether or not the Gatekeeper will attempt to call systems which are not registered with it or one of its neighbor gatekeepers. Options are: Allows an endpoint to make a call to an unknown IP address without the Direct Gatekeeper querying any neighbors.
Page 75
Specifies whether calls may be made by an unregistered endpoint. Defaults to Off. xconfiguration Gatekeeper Unregistered Caller Fallback: <alias> Specifies the alias to which calls are placed if the Gatekeeper receives a call setup containing no alias information. Page 75 of 105...
Note: If web access is required, we recommend that you enable HTTPS and disable HTTP for improved security. 16.2.6. Commands under the IP node allow you to configure IP-related parameters. The TANDBERG Gatekeeper may be configured to use either IPv4 or IPv6 or both. When entering IPv4 addresses, dotted quad notation is used: 127.0.0.1.
Note: This parameter is only used when attempting to resolve server addresses such as LDAP servers, NTP servers etc. It plays no part in URI dialing: (see xconfiguration gatekeeper localdomain).
Pipes Pipe [1..100] Name: <pipename> Name for a pipe. 16.2.13. Services xConfiguration Services CallTransfer Mode: <On/Off> Controls whether or not third party call transfer is enabled. The Gatekeeper must also be operating in call routed mode. TANDBERG Gatekeeper User Guide Page 78 of 105...
SNMP CommunityName: <name> SNMP Community names are used to authenticate SNMP requests. SNMP requests must have this 'password' in order to receive a response from the SNMP agent in the Gatekeeper. You must restart the system for changes to take effect.
Page 80
TANDBERG Gatekeeper User Guide xconfiguration SubZones TraversalSubZone Bandwidth PerCall Limit: <1..100000000> Per-call bandwidth available on the traversal subzone. xconfiguration SubZones TraversalSubZone Bandwidth PerCall Mode: <None/Limited/Unlimited> Whether or not the traversal subzone is enforcing per-call bandwidth restrictions. None corresponds to no bandwidth available.
Traversal xconfiguration Traversal Registration RetryInterval: <1..65534> Sets the interval in seconds at which the Gatekeeper will attempt to register with the Border Controller if its initial registration fails for some reason. The default is 120 seconds. xconfiguration Traversal AllowMediaDirect: <On/Off>...
Page 82
Specifies the hop count to be used when originating an LRQ. xconfiguration Zones Zone [1..100] Monitor: <On/Off> If zone monitoring is enabled, an LRQ will be periodically sent to the zone gatekeeper. If it fails to respond, that gatekeeper will be marked as inactive.
Page 83
TANDBERG Gatekeeper User Guide xconfiguration Zones Zone [1..100] Match [1..5] Pattern String: <pattern> The pattern to be used when deciding whether or not to query a zone. This is only used if the zone's match mode is set to AlwaysMatch.
16.3. Command The command root command, xcommand, is used to execute commands on the Gatekeeper. To list all xcommands type: xcommand ? To get usage information for a specific command, type: xcommand <command_name> ? 16.3.1. AllowListAdd xCommand AllowListAdd <allowed_alias> Adds an entry to the allow list, used by the registration restriction policy.
16.3.11. DenyListDelete xCommand DenyListDelete <index> Removes the pattern with the specified index from the deny list. Deny list entries can be viewed using the command xconfiguration Gatekeeper Registration DenyList. TANDBERG Gatekeeper User Guide Page 85 of 105...
History/Registrations For example: (backslashes are used to indicate continuation lines) xCommand FeedbackRegister ID:1 \ URL:http://10.1.1.1/SystemManagementService.asmx \ Expression:Event/Connected,Status/Calls would notify all call connections and their subsequent changes in status to the specified URL. TANDBERG Gatekeeper User Guide Page 86 of 105...
Locate xCommand Locate <alias> <HopCount> Runs the Gatekeeper'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". Results are reported back through the xFeedback mechanism, which must therefore be set up before issuing this command.
The type of matching to apply - options are Prefix, Suffix or Regex type The action to take for the transform - options are Strip or Replace behavior The text to be substituted replace TANDBERG Gatekeeper User Guide Page 88 of 105...
Adds a new zone with the specified name and IP address. The zone is pre-configured with a link to the default subzone and a pattern match mode of AlwaysMatch. 16.3.30. ZoneDelete xCommand ZoneDelete <index> Removes the zone with the specified index. TANDBERG Gatekeeper User Guide Page 89 of 105...
16.4.1. calls xhistory calls Displays history data for up to the last 255 calls handled by the Gatekeeper. Call entries are added to the Call History on call completion. Call histories are listed in reverse chronological order of completion time.
Registers for feedback on changes in the status of either calls or registrations only. 16.5.2. Register History xfeedback Register History Registers for feedback on all history. xfeedback Register History/<Calls/Registrations> Registers for feedback on history of either calls or registrations only. TANDBERG Gatekeeper User Guide Page 91 of 105...
Note: Registering for the ResourceUsage event will return the entire ResourceUsage structure every time one of the ResourceUsage fields changes. ResourceUsage fields consist of: Registrations MaxRegistrations TraversalCalls MaxTraversalCalls TotalTraversalCalls NonTraversalCalls MaxNonTraversalCalls TotalNonTraversalCalls TANDBERG Gatekeeper User Guide Page 92 of 105...
IPAddress Optional parameters which specify up to 10 IP addresses to log information for. If no addresses are specified, activity to all IP addresses will be logged. Setting syslog 0 will turn off tracing. TANDBERG Gatekeeper User Guide Page 93 of 105...
Note: It is good practice to keep the H.350 directory in its own organizational unit to separate out H.350 objects from other types of objects. This allows access controls to be setup which only allow the Gatekeeper read access to the BaseDN and therefore limit access to other sections of the directory.
H.350.2 Directory services architecture for H.235 - An LDAP schema to represent H.235 elements. The schemas can be downloaded in ldif format from the web interface on the Gatekeeper. To do this, navigate to Gatekeeper Configuration Copy the downloaded schemas to the OpenLDAP schema directory: /etc/openldap/schemas/commobject.ldif...
Add the ldif file to the server using the command: slapadd -l <ldif_file> This organizational unit will form the BaseDN to which the Gatekeeper will issue searches. In this example the BaseDN will be ou=h350,dc=my-domain,dc=com. Note: It is good practice to keep the H.350 directory in its own organizational unit to separate out H.350 objects from other types of objects.
For more details on configuring OpenLDAP to use TLS consult the OpenLDAP Administrator's Guide. To configure the Gatekeeper to use TLS on the connection to the LDAP server you must upload the CA's certificate as a trusted CA certificate. To do this, navigate to upload the certificate.
19. Appendix C: Regular Expression Reference Regular expressions can be used in conjunction with a number of Gatekeeper features such as alias transformations, zone transformations, CPL policy and ENUM. The Gatekeeper uses POSIX format regular expression syntax. For an example of regex usage, see Call screening based on alias (section 13.5.4).
Nemko. According to their Follow-Up Inspection Scheme, these agencies also perform production inspections at a regular basis, for all production of TANDBERG's equipment. The test reports and certificates issued for the product show that the TANDBERG Gatekeeper, Type number TTC2-02, complies with the following standards.
Page 102
RFC 2915:The Naming Authority Pointer (NAPTR) DNS Resource Record http://www.ietf.org/rfc/rfc2915.txt RFC 3761: The E.164 to Uniform Resource Identifiers (URI) Dynamic Delegation Discovery System (DDDS) Application (ENUM) http://www.ietf.org/rfc/rfc3761.txt Mastering Regular Expressions, Jeffrey E.F. Friedl, O'Reilly and Associates, ISBN: 1-56592-257- TANDBERG Gatekeeper User Guide Page 102 of 105...
Page 103
TANDBERG Gatekeeper User Guide 22. Glossary Alias The name an endpoint uses when registering with the Gatekeeper. Other endpoints can then use this name to call it. ARQ, Admission Request An endpoint RAS request to make or answer a call.