# 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
    {
      location LAN;
      login "John";
      alias "John";
    }

    user Anyone 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
    {
      proxy level none;
      registration validity 70;
    }

    user User1
    {
      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. All where variables applicable, string type parameter can be presented by variable.

### regexp

String, which optionally can contain regular expressions. All 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:

- Mon 1/12/1999 12:00:00
- Mon 1/12/1999 12:00
- 1/12/1999 12:00:00
- 1/12/1999 12:00
- 12:00:00
- 12:00
- Mon

### 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.

## 5. Main (first level) expressions

### system { ... }

Complex expression which contains main system options.

### 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> { ... }

Complex expression used to declare group and it's behavior. This expression can contain any expressions from 'user' and 'gatekeeper' complex expressions. Refer to "User options" and "Gatekeeper options" sections. You can define group under 'everyone' reserved name, all users defined later will be automatically become members of that group.

### user <identifier> { ... }

This expression has almost the same meaning as 'group' with only difference. It declares concrete user who can log into system. Refer to "User options" section for details.

### gatekeeper <identifier> { ... }

Serves to declare user with some special (gatekeeper) abilities. It can contain group and user with own additional options. Main difference between user and gatekeeper is what on alias match, gatekeeper will not make call immediately.

Call will be preceded with Location Request (LRQ) message to remote gatekeeper (or gatekeepers if more than one matched) to discover concrete endpoint to be called. As endpoint, gatekeeper should register to indicate it's "active" state. Use 'static' expression, in case remote gatekeeper does not support registration. Refer to "Gatekeeper options" section for detailed information on gatekeeper specific options.

## 6. System options

### identifier <string>

Gatekeeper identifier. Used as gatekeeper's main identification. Also, 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.

### address <ip address>

Interface gatekeeper must work thru. It is important to set this feature to a proper value on machines with multiple network interfaces, so, gatekeeper could use right interface to H.323 network. Not actual on machines with single network interface. First random will be taken if this expression omitted.

### 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.

## 7. Monitor options

### port <uint>
default value: 2040

Port number, used for monitor communication with gatekeeper.

### password <string>

Password, user should present to gain monitor access. Note: 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.

### [direction] ras messages <bool>

Controls RAS messages printing. According to direction used, incoming or outgoing messages will be printed to a log. Option will take control on all RAS messages in case direction statement omitted.

### [direction] q931 messages <bool>

Controls Q.931 messages printing.

### [direction] h245 messages <bool>

Controls H.245 messages printing.

### [direction] radius messages <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.

### 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. User options

### proxy level <level>
default value: signalling

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

- none - Endpoint can call and be called directly by other endpoint (using "direct" call type). But, in this mode, endpoint still able to ask for "routed" call type (with 'proxy level choice' enabled) which corresponds 'signalling' proxy level. Not recommended because call presence can be monitored only by IRR. So, call timing information can be inadequate.
- signalling - Gatekeeper will proxy and control both "call signal" and "control" signalling channels. All calls with "direct" call type will be rerouted thru gatekeeper and call type will be changed to "routed".
- full - With addition to 'signalling' proxy level, gatekeeper will proxy all RTP channels which carry transmitted media.

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.

### 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'.

### hunt level <level>
default value: neutral

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

- none - No hunting will be performed in this mode. If conversation can not take it's place for some reason (remote endpoint is busy or remote equipment malfunction, e.t.c.), calling endpoint will not be switched to other alternative and calling person will hear error signal.
- neutral - Calling endpoint will be switched to an alternative path in event of error during call progress. However, if media channels are set already, no swithing will occur. Gatekeeper will not try to delay media channels initiation, that's because that mode called "neutral".
- soft - In this mode gatekeeper will try to delay media channels initiation by moving FastStart and H245Address information to Alerting message.
- hard - In this mode gatekeeper will try to delay media channels initiation by moving FastStart and H245Address information to Connect message.

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.

### 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'.

### 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.

### 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';

### 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. Also, 'static' statement automatically produces 'address' directive with given address and access flag set to 'true'.

### static [ip address]
static [bool]

Automatically register endpoint at startup with given call signal address. Provided for terminals which unable to communicate thru gatekeeper. All RAS registrations on given user account will be denied. Also, automatically produces 'address' directive with given address and access flag set to 'true'. With "ip address" parameter ommited calls to/from given user are impossible. But to enable incoming calls from that user you can insert 'address' directive.

Example

    address 19.38.12.7;
    static;

In this example static endpoint will be able to make calls but unable to receive them.

Example

    address 19.38.12.7 false;
    static 19.38.12.7;

In this example endpoint will be able to receive calls, but unable to place them.

### 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.

### 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.

- none - None authentication procedures will take place.
- login - Gatekeeper will ask RADIUS server for permission to log user in.
- caller - Gatekeeper will ask RADIUS server for permission to user make a call.
- callee - Gatekeeper will ask RADIUS server for permission to user answer the call
- call - Equal to 'caller | callee'.
- full - Equal to 'login | call'.

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.

- none - None accounting procedures will take place.
- login - Gatekeeper will register login and logout on RADIUS server.
- caller - Gatekeeper will register call duration on RADIUS server while user is call originator.
- callee - Gatekeeper will register call duration on RADIUS server while user is call terminator.
- call - Equal to 'caller | callee'.
- full - Equal to 'login | call'.

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.

### 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.

### 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".

### 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.

### 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.

## 12. Gatekeeper options

### ras address <ip address>

Indicates gatekeeper RAS layer address. Used in conjunction with 'static' option when our gatekeeper cannot discover this address from any other source.

### identifier <string>

Remote gatekeeper identifier. Our gatekeeper will use it in all requests where it's possible. Also, if 'ras address' clause omitted, gatekeeper will try to discover it by Gatekeeper Request (GRQ) message. Note: GRQ is a broadcast message and it will not go thru the router without special action taken first on that router.

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

Makes our gatekeeper register (with RRQ message) on remote gatekeeper with given aliases to indicate our "active" state. Registration method is just the same as for ordinary endpoint registration. And remote gatekeeper has the right to interpret us as ordinary endpoint if it was not told before by other way.

### link h235 name <string>
default value: UserName

Sets H.235 name for gatekeeper link.

### link h235 password <string>

Sets H.235 password for gatekeeper link.

### link h235 authentication <bool>
default value: false

Turns H.235 authentication over gatekeeper link on and off.

### registration period <uint seconds>

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

### link alternate gatekeeper <bool>
default value: false

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

## 13. 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';