Configuration file syntax

Configuration file consists of separate expressions. There are no any positional or space symbols usage limitation. Text marked as comment does not interpreted as any useful information.

1. Comments

There are two types of comments - block and line. Block comment starts with '/*' symbol pair and ends with '*/'. Line comment starts with '//' and ends with current line.

Example

/* This is comment */
// This is comment too

2. Expressions

Each expression begins with reserved word(s), which indicates expression type. Expressions separated by semicolon or comma depending context of use. There are two expression types simple and complex. Simple expression controls single feature.

Example

login 'copah'

Complex expressions are similar to simple but they include one or more simple expressions enclosed in braces and separated by semicolon. Complex expressions can be written in simpler form where simple expressions separated by commas and follows directly after complex expression declaration.

Example

user John is ras
{
  location LAN;
  login "John";
  alias "John";
}

user Anyone is ras
  group member Basic,
  login '(.+)' set UN to '\1',alias UN;

Order in which expressions appear has significance. If there is more than one expression of the same type and all of them controls same feature, first active will be taken. Some expressions can be limited by their validity in time. These expressions have optional 'at' keyword (Refer to 'at' subexpression for details).

Example

group Group1 is ras
{
  proxy level none;
  registration validity 70;
}
user User1 is ras
{
  registration validity unlimited;
  group member Group1;
  proxy level signalling;
  connections 4 at 9:00-18:00;
  connections 2 at 13:00-14:00;
  connections 1;
}

In this example user registration validity will not be limited because, first expression of this type declares this state. Registration validity declared in group has no effect. And vice-versa user's 'proxy level' has no effect because, group's expression overrides this statement.

From 9:00 to 18:00 user will be able to make four connections. And only one connection all other the time. Second 'connections' rule has no effect because it's validity time covered by first expression with higher priority.

3. Reserved words

Reserved words are case insensitive. Which case to use in particular reserved word transcription is up to network manager. F.e. 'file' and 'File' is the same reserved word. Most of reserved words are used for expression type and expression options indication. This topic is about to discuss later. Other reserved words are used to indicate feature state.

Example

Boolean: true, false
Numeric: unlimited

4. Types

string

Text enclosed in quotes or double quotes. Anywhere, where variables applicable, string type parameter can be presented by variable.

regexp

String, which optionally can contain regular expressions. Anywhere, where variables applicable, regexp type parameter can be presented by variable.

uint

Unsigned integer value or 'unlimited' keyword to indicate infinite character.

bool

Boolean value. 'true' or 'false' reserved word.

identifier

Text starting from letter without spaces. Identifier is used inside configuration file as reference to varety type of objects, such as: zones, links, users, variables, e.t.c.

ip address

Numeric IP address or internet name enclosed in quotes or double quotes.

Example

123.48.132.56:12345
'canopus.aqua.comptek.ru:12345'

address range

Single ip address or two ip addresses forming the address range.

Example

Notation Description
19.38.12.45 single IP address.
19.38.12.45-19.38.12.49 range.
19.38.12.45-49 simplified range.

direction

'incoming' or 'outgoing' reserved word or nothing (if allowed) for both.

side

'caller' or 'callee' reserved word or nothing (if allowed) for both.

bandwidth

Bandwidth in bits per second. Must be divisible by 100. You can use 'K', 'M', 'G' modifiers to express bandwidth in kilobits, megabits and gigabits accordingly. Possible notations are: 128K, 6.4K, 10M, 0.5M

time

Date and time written in the form: Mon 31/12/2000 23:59:59 Any individual value can be changed for '.' symbol to make "wild" expression. Some parts can be omitted to shorten notation. So, all possible notations are:

period

Two times written beside '-' symbol forming the time period.

Example

Notation Description
Mon-Wed from Monday to Wednesday every week.
12:00-17:59 from 12:00:00 to 17:59:59 every day.
1/./. 00:00-10/./. 23:59 from 1st day 00:00:00 to 10th day 23:59:59 every month.
./1/. 00:00-./2/. 23:59 from 1 Jan to 31 Feb every year.

capability

Used to indicate media stream type. There are three general capability types: 'audio', 'video' and 'data'. The capability declaration begins with corresponding reserved word and followed by capability name of a given capabiltiy class.

Example

audio g722
video h261
data t38-fax

Capability name can be substituted by 'any' reserved word to indicate every capability in given class.

Example

audio any
data any

Entire capability declaration can be expressed by 'any' keyword to indicate every capability in every class.

Example

any

audio capability name index

alaw, alaw-56, ulaw, ulaw-56, g722, g722-56, g722-48, g7231, g728, g729, g729a, is11172, is13818, g729b, g729ab, g7231c, gsm, gsm-hr, gsm-er, g729ext

video capability name index

h261, h262, h263, is11172

data capability name index

t120, dsm-cc, user-data, t84, t434, h224, nlpid, dsvd-control, h222-partitioning, t30-fax, t140, t38-fax

capability list

One or more capability declarations separated by space.

Example

supported capability
  audio alaw
  audio g7231
  audio g729
  data t38-fax;

5. Main (first level) expressions

interface <identifier> <ip address> { ... }

Define local interface for later use. Interface associated directly with single system address. It is possible to define number of interfaces. Currently this directive does not have any sub-expressions. First defined interface will be default interface.

facility <identifier> { ... }

Define gatekeeper facility to serve RAS and static users. RAS and call signal sockets created by this expression. It is possible to define number of facilities. See facility options for details.

monitor { ... }

Monitor options control expression. See monitor options section for details.

log { ... }

Complex expression which can contain log output control options.

aaa { ... }

Contains RADUS server information and options.

zone <identifier> { ... }

Declare informational zone. Network segment, which can carry data stream and it is independent from other network zones by its bandwidth. Used to limit phone traffic over particular subnet and other QoS. Gatekeeper will not allow making connections over zone with exhausted bandwidth. Refer to "Zone and link options" section for expressions it can include.

link [identifier] between <identifier zone> and <identifier zone> { ... }

Bears zone functionality with additional ability to connect two zones to follow up network topology. Refer to "Zone and link options" section for expressions it can include.

group <identifier> [is <user type>] [implied] { ... }

Complex expression used to declare group and it's behavior. This expression can contain any expressions from 'user' complex expression of a given type. "User type" parameter used to indicate group type and can be one of the following values: 'ras', 'static', 'ras link', 'static link'. In case "user type" omitted, group can contain only base user expressions. Refer to "User options" section. 'Implied' flag means that group is implied to every user of given type. I.e. every user of given type, defined later will automatically become member of that group.

user <identifier> is <user type> { ... }

This expression declares concrete user. There are number of user types, which vary in connection protocols and abilities as well as general behavior. User expression of every type can contain common user expressions, see "Common user options" section for details.

user <identifier> is ras { ... }

Declares RAS user who can logon into system using RAS protocol. Refer to "RAS user options" section for details.

user <identifier> is static [ip address] { ... }

Static user. Automatically registered at startup with given call signal address. Provided for terminals which unable to communicate with gatekeeper using RAS protocol. All RAS opreations on given user account will be denied. However, LRQ requests will be served for that user type. Static user produces 'address' directive to itself with given address and access flag set to 'true'. With "ip address" parameter ommited calls to/from given user are impossible. But to enable calls from that user you can insert 'address' directive. Refer to "Static user options" section for details.

user <identifier> is ras link <ip address> { ... }

Declares user contrary, by it's functionality, to RAS type user. This user acts as normal RAS endpoint. F.e. it registers on other gatekeeper like any other RAS endpoint. Mainly used for gatekeepers interconnection. Call to that user will be preceded with LRQ message to discover call termination possibility. Later, our gatekeeper will send all usual endpoint messages (ARQ, BRQ, DRQ, ...) to the remote gatekeeper to lay connection to. "ip address" used to secify remote gatekeeper RAS address. Refer to "RAS link user options" section for details.

user <identifier> is static link <ip address> { ... }

Functionally contrary version of static type user. Mainly used for gatekeepers interconnection. Call to that user will be preceded with LRQ message to discover call termination possibility. "ip address" used to secify remote gatekeeper RAS address. Refer to "Static link user options" section for details.

user <identifier> is slave of <identifier> { ... }

Declares slave user. Slave user does not have any signalling functionality by itsef, it uses master user signalling facilities to make connection. Used to discriminate endpoints that hidden behind gateway. Slave user inherits all master user settings that can be overriden by slave user expressions. Refer to "Slave user options" section for details.

6. Facility options

interface <identifier>

Define local interface (system address) used by facility. In case not defined, default interface will be used.

ras port <uint>
default value: 1719

Port number, which will be used for RAS communication with gatekeeper. Will be standard (1719) if not specified.

call signal port <uint>
default value: 1720

Port number, which will be used as call signal. Call signal port used by gatekeeper to be called by other devices, which does not support gatekeeper registration. Will be standard (1720) if not specified.

identifier <string>

Gatekeeper identifier for given facility. This name will be used in discovery and registration processes when endpoint wants to register at gatekeeper with particular name. So, all discovery and registration requests with non-matching gatekeeper ID will be denied. Requests containing no gatekeeper ID still be processed.

7. Monitor options

interface <identifier>

Define local interface used by monitor. In case not defined, default interface will be used.

port <uint>
default value: 2040

Port number, used for monitor communication with gatekeeper.

identifier <string>

Monitor facility identification. User will see that value as controlled service identifier in monitoring application.

password <string>

Password, user should present to gain monitor access. Note: Also, this password used for configuration data encription while it being sent over network using monitor protocol. In case there is no password set — no data encription will take the place.

address <address range> [bool]
address <bool>

Define right to log on to monitor service from specific address or address range. Omitting "bool" parameter means 'true'. Omitting "address range" parameter means all possible addresses.

8. Log options

file <string>

Path to log file, which will contain console output copy. Identical to 'consolefile' command line option.

ras messages [where list] <bool>

Controls RAS messages printing.

q931 messages [where list] <bool>

Controls Q.931 messages printing.

h245 messages [where list] <bool>

Controls H.245 messages printing.

h450 messages [where list] <bool>

Controls H.450x messages printing.

radius messages [where list] <bool>

Controls RADIUS messages printing.

messages dump <bool>

In enabled state will print all incoming messages dump.

registrations <bool>

Print registrations/unregistrations.

connection status <bool>

Print connection progress.

chosen route <bool>

Print chosen route on alias resolve.

available bandwidth <bool>

Print available bandwidth for call.

bandwidth changes <bool>

Print all bandwidth changes.

9. AAA options

file <string>

Path to a file containing information about conversations and their time (CDR file). Will be placed to configuration file folder if path omitted. There will be no CDR log file if entire option omitted.

interface <identifier>

Define local interface used by RADIUS facility. In case not defined, default interface will be used.

identifier <string>

NAS identifier used for RADIUS operations.

address <ip address>

Address of RADIUS server.

authentication port <uint>
default value: 1812

Authentication port. Will be standard (1812) if option omitted.

accounting port <uint>
default value: 1813

Accounting port. Will be standard (1813) if option omitted.

password <string>

RADIUS server shared secret.

log failed calls <bool>
default value: false

Log failed calls to both, CDR file and RADIUS.

time zone name <string>
default value: "UTC"

Defines time zone name used in RADIUS packets.

time zone offset <offset>
default value: GMT

Time zone offset for AAA records. Available values: GMT, local.

10. Zone and link options

bandwidth <bandwidth>
default value: unlimited

Total bandwidth zone can handle. Gatekeeper will not allow to make connections through zones with exhausted bandwidth.

connections <uint>
default value: unlimited

Connections count zone can handle. Gatekeeper will not allow to make connections over that setting in given zone.

11. Common user options

set <identifier variable> to <string>

Set given variable to some string value. As with any other expressions, only first 'set' expression on particular variable will work out.

alias <regexp> [bool] [cost <uint>] [translate to <regexp>] [set list] [at]
alias <bool> [cost <uint>] [set list] [at]

Defines actual aliases set, endpoint can be called by. The "bool" parameter points on belonging of a given alias to endpoint. In case "bool" parameter set to 'false', a given alias excluded from actual aliases set.

Example

alias '81234' false;
alias '8\d{5}' true;

In this example endpoint will be available by any five-digit number starting from digit 8 excluding number 81234. Omitting "bool" parameter means 'true'. Omitting "regexp" parameter means all possible aliases.

The 'translate to' subexpression used to represent received alias to endpoint in different form, likewise it can be done by 'translate alias' directive.

The 'cost' subexpression allows to set cost on individual alias. The default user cost will be used in case this subexpression omitted.

make [direction] [side] alias <regexp> <set list> [at]

Make in call alias create or modify some variables. Omitted direction and/or side parameter means all aliases of every type in omitted class.

translate [direction] [side] alias <regexp> to <regexp> [at]

Translate alias for further presentation and processing purposes. The "direction" and "side" parameters control "incoming/outgoing" and "caller/callee" aliases translation accordingly. "Incoming" alias will be translated after dialed alias was matched with concrete endpoint alias only. Only first matched translation will affect alias. You may omit "direction" and "side" parameters to translate all alias types in omitted class. For example, if you have caller and callee aliases from same dialing plan, you can write down translation for some gateway to accomodate outer dialing plan like this:

translate incoming alias '(\d{3})' to '+73432451\1';
translate outgoing alias '+73432451(\d{3})' to '\1';

Also, it is very useful to set concrete source alias for single user:

translate outgoing caller alias '.*' to '212';

while endpoint alias configured like

alias '212';

proxy level <level>
default value: signalling

Sets given proxy level. Available values: 'none', 'signalling' and 'full'.

In case endpoints participated in connection have different proxy level, the stronger of two will be taken. Using this feature you can keep users on LAN to use 'signalling' proxy level while some outer gateway use 'full' proxy level to get thru firewall.

hunt level <level>
default value: neutral

Sets given hunt level, in case endpoint is calling side. Available values: 'none', 'neutral', 'soft', 'hard'.

Note, that in any hunt mode endpoints still able to open media channels using H.245 tunneling, thus making further hunting impossible.

fast start <bool>
default value: true

Enable fast connect procedure for given endpoint. Some endpoints (f.e. Cisco ATA186) can be crashed by received fast start sequence, you can avoid this by disabling fast connect procedures for such endpoints.

h245 tunneling <bool>
default value: true

Enable H.245 tunneling for endpoint.

cost <uint> [at]
default value: unlimited

Route cost. If there is more than one endpoint with same alias available, less costing one will be selected for a call. Can contain 'at' sub expression.

connections <uint> [at]
default value: unlimited

Represents maximum simultaneous connections user can handle. This value goes into account for node load calculation in load balancing procedure. So, if there is more than one endpoint with same alias and cost available, less loaded will be selected for a call. Anyway gatekeeper will not allow making connections over this setting.

location <identifier zone>

Zone endpoint belongs to. Used for QoS and bandwidth limitation. No these services if omitted.

bandwidth <bandwidth>
default value: 128k

The bidirectional, divisible by 100, bandwidth used for static endpoints. F.e. if your endpoint uses 64 kbit aLaw codec for both directions, then such bandwidth shall be expressed as 128k.

dial [identifier] <bool> [at]

Define user right to dial for user or group. Omitting identifier, defaults to all users in a system. By default user has right to dial for any other user in the system. If user or its group contain one or more 'dial' statements, all other user dials will be denied. You can use 'self' reserved word instead of some real user name. This is very useful for rules defined in groups.

address <address range> [bool]
address <bool>

Define user right to log on from specific address or address range. Omitted address range value means all possible addresses. Omitted bool value means 'true'. By default user has right to log on from any address which equivalent to single 'address true' expression. If user or its group contain one or more 'address' statements, logging in from all other addresses will be denied. In case given endpoint is static, 'address' statements define acceptable addresses for direct (call signal) gatekeeper call.

max [direction] ringback duration <uint seconds>
default value: unlimited

Time limit in seconds for user can wait the other side to pick up the call. Smallest from two (incoming and outgoing) will be taken.

max [direction] connection duration <uint seconds>
default value: unlimited

Time limit in seconds for maximum connection duration. Smallest from two (incoming and outgoing) will be taken.

radius authentication <mode>
default value: none

Sets given authentication mode on RADIUS server. Available values: 'none', 'login', 'caller', 'callee', 'call' and 'full'. Options can be combined by pipe (|) character.

Login authentication request has "Service-Type" field set to "Login". Call authentication request has "Service-Type" field set to "Call Check".

radius accounting <mode>
default value: none

Sets given accounting mode on RADIUS server. Available values: 'none', 'login', 'caller', 'callee', 'call' and 'full'. Options can be combined by pipe (|) character.

Login accounting request has "Service-Type" field set to "Login". Call accounting request has no "Service-Type" field.

radius name <string>
default value: UserName

Set user name for RADIUS operations. There is useful internal variables named UserName and H235Name which holds configuration user name and user name passed in H.235 security info accordingly.

radius password <string>

Set user password for RADIUS operations. Null password means that no password needed. This is default value. In case 'radius password H235Password' expression used, gatekeeper will extract password from endpoint supplied H.235 information layer. That mode supports Cisco Access Token (CAT) only.

h235 authentication <bool>

Turn on/off H.235 authentication of RAS and Q.931 messages. Methods supported: CAT, Password with hashing (MD5).

h235 name <string>
default value: UserName

Set name user should present for message authentication.

h235 password <string>

Set password user should present for message authentication.

display <string>
default value: UserDisplay

Set user Q.931 display field to given value. Original display value is placed to UserDisplay variable automatically. So, to restore original behaviour you can always give a 'display UserDisplay' command.

connection dupe <bool>
default value: false

Allow or disable user to make connections with duplicate call identifier value. Normally you should keep this feature disabled. But, some endpoints such as call rerouting automatic answering machines can make connection back to gatekeeper with changed destination address but same call identifier value. In normal case call will be banned by loop detector, so you have to enable 'connection dupe' feature for given endpoint. Use this feature with extreme caution, endpoint should not be from the same side (f.e. a caller side) twice on different connections with same call identifier, because gatekeeper will be unable to discriminate between these connections.

supported capability <capability list>
default value: any

List of supported capabilities. Gatekeeper will not connect two endpoints that does not have capability lists intersection.

unsupported capability <bool>
default falue: true

In case set to 'false', forces gatekeeper to strip unsupported capabilities from transferred terminal capability sets and fast start elements.

capability sort order <capability list>
default value: any

Forces gatekeeper to sort transferred capabilities up in a given order. Both connection participants will have same sort list. Which list will be taken to perform sort operation is determined by 'capability sort preference' expression.

capability sort preference <uint>
default value: unlimited

This value used to determine which capability sort list (caller or callee) will be taken for capability sort operation during connection. Less value means most preference. In case both values are equal, caller's sort list will be taken. But, if caller's sort list has 'any' value only, callee list will be chosen.

secure rtp <bool>
default value: true

In case set to 'true', connects all RTP sockets to appropriate destination addresses, making it impossible to forward UDP packet from unknown address. In this mode gatekeeper has better proxy perfomance. Some terminals send RTP packets from address other than stated in OpenLogicalChannel message. So, with 'secure rtp' feature turned on, they can't establish outgoing media stream. I.e. other connection participant will not hear that teminal. In that case you need to turn 'secure rtp' feature for such endpoint off.

12. RAS user options

login <regexp> [bool] [set list]
login <bool> [set list]

Alias, endpoint will be registering with. Omitted "regexp" parameter means every possible login alias. Omitted "bool" parameter means 'true'. Using 'set' subexpressions you can extract some parts of login alias.

Example

login 'user(.+)goinin' set UserAlias to '\1';
alias UserAlias;

User trying to log in with 'userJohngoinin' will be logged under current user conditions and it will be reachable by alias 'John'.

make login <regexp> <set list>

Make login alias create or modify some variables. Note, that this expression does not affect login process, it work thru login aliases that already passed 'login' expression.

Example

group everyone make login '.*' set UserAlias to '\0',alias UserAlias;
user User1 login '201';
user User2 login '202';

In this example User1 will be allowed with alias "201" only. And it will have actual alias "201".

proxy level choice <bool>
default value: false

Controls endpoint ability to change stated proxy level during call admission procedure. By H.323 standard endpoint can choose between "direct" and "gatekeeper routed" modes. So, with enabled 'proxy level choice' feature endpoint can switch from stated proxy level 'signalling' or 'full' to 'none', or keep original mode. In case endpoint configured to proxy level 'none', it can switch to 'signalling' or stay at 'none'.

registration validity <uint seconds>
default value: unlimited

Limit registration validity to "uint" seconds. Endpoint should support reregister feature to indicate it's alive state. If endpoint fails to reregister in given period of time, it will be unregistered by force. Use 'unlimited' keyword to disable previously declared (f.e. in user's group) value.

connection validity <uint seconds>
default value: 60

Limit inactive connection validity to "uint" seconds. Endpoint should send IRR message periodically to indicate connection "alive". IRR period set by gatekeeper and it's three times less then 'connection validity' parameter to let IRR tree retries to reach gatekeeper. With 'connection validity' set to 'unlimited' gatekeeper will not ask endpoint for IRRs. This feature can help to connect flaw endpoints which do not send IRR messages thru the call despite this feature still mandatory by H.323 standard. It is highly recommended to not use 'connection validity unlimited;' with 'proxy level none;' because, in this case there is no reliable way for gatekeeper to know that connection has been terminated. It may cause "hung" connections and wild bill data.

alternate gatekeeper <ip address> [string] [gatekeeper ...]
alternate gatekeeper none

Declares list of alternate gatekeepers for the user. This list will be supplied to endpoint in case it supports alternate gatekeeper procedures indicating this by include SupportsAltGK field in RRQ message. 'alternate gatekeeper none' expression turns this feature off. This is default behaviour.

use location <bool>
dafault value: false

In case this feature enabled, gatekeeper will not place call to given endpoint immediately. Call will be preceded by LRQ message to discover termination possibility. Mostly, terminals do not support this (LRQ to endpoint) feature. But some gateways or gatekeepers with sufficiently large amount of directions served, can support this useful feature. This gatekeeper version does support it over 'ras link' and 'static link' user types.

13. Static user options

facility <identifier>

Facility used to make connections to and serve LRQs for given endpoint.

14. RAS link user options

interface <identifier>

Local interface gatekeeper should use for given user.

ras port <uint>
default value: 1719

Local port number, which will be used for RAS communication. Will be standard (1719) if not specified.

call signal port <uint>
default value: 1720

Local port number, which will be used as call signal.

identifier <string>

Remote gatekeeper identifier. Our gatekeeper will use it in all requests where it's possible.

register alias <string> [alias ...]
register alias none

Declares alias list to be registered at remote gatekeeper.

registration period <uint seconds>
default value: unlimited

Forces our gatekeeper to repeat registration procedure in given period of time. This feature used to indicate our alive state.

alternate gatekeeper <bool>
default value: false

Allows alternate gatekeeper procedures for given user. With this option enabled our gatekeeper will set SupportsAltGK flag, analyse alternate gatekeeper list presented by remote gatekeeper and ativate alternate gatekeeper switching procedure.

15. Static link user options

interface <identifier>

Local interface gatekeeper should use for given user.

ras port <uint>
default value: 1719

Local port number, which will be used for RAS communication. Will be standard (1719) if not specified.

call signal port <uint>
default value: 1720

Local port number, which will be used as call signal.

identifier <string>

Remote gatekeeper identifier. Our gatekeeper will use it in all requests where it's possible.

16. Slave user options

serve alias <regexp> [bool]
serve alias <bool>

In case call is made by master endpoint, slave user can be set as caller for the call using this expression. Search will be done through caller aliases presented by master endpoint and if 'serve alias' expression condition will met, given endpoint will be set as caller. Omitted "regexp" parameter means all possible aliases.

17. Sub-expressions

at <period>

Sets period of validity for expression.

set <identifier variable> to <string>

Set given variable to some string value.

Example

set UserLogin to 'user(.+)';
login UserLogin set UserAlias to '\1';
alias UserAlias;

set <identifier variable> add <string>

Adds string to given variable. String will be preceded with pipe (|) character if variable already contained not null string. This feature designed especialy for handling multiple aliases during endpoint login process. If there brackets in the string, contained by variable, substring will be inserted before first closing bracket.

Example

set UserAlias to 'common|(2())';
login 'gw5(\d{3})' set UserAlias add '\1';
alias UserAlias;

In this case user presented by two aliases, f.e. "gw5100" and "gw5101" will have "common|(2(100|101))" resulting regexp alias string.

set list

List of 'set ... to' and 'set ... add' sub-expressions.

Example

alias '(\d{3})(\d{3}).*' set Account to '\1' set PIN to '\2';

where direction <direction>

Sets expression validity over direction.

where address <address range>

Sets expression validity over given address.

where [side] alias <regexp>

Sets expression validity over given alias.

where list

List of 'where direction ...', 'where address ...' and 'where alias ...' sub-expressions.

Example

log q931 messages
  where address 212.11.15.6
  where caller alias '124366';