The behavior of the gatekeeper is completely determined by the command line
options and configuration file. Some command line options may override
the setting of the configuration file.
For example, the option -l
overrides the setting TimeToLive
in the configuration file.
Almost every option has a short and a long format, e.g.,
-c
is the same as --config
.
-h --help
Show all available options and quit the program.
-c --config filename
Specify the configuration file to use.
-s --section section
Specify which main section to use in the configuration file. The default is [Gatekeeper::Main].
-i --interface IP
Specify the interface (IP number) that the gatekeeper listens to. You should leave out this option to let the gatekeeper automatically determine the IP it listens to, unless you want the gatekeeper only binds to a specified IP.
-l --timetolive n
Specify the time-to-live timer (in seconds) for endpoint registration.
It overrides the setting TimeToLive
in the configuration file.
See
there for detailed explanations.
-b --bandwidth n
Specify the total bandwidth available for the gatekeeper. Without specifying this option, the bandwidth management is disable by default.
--pid filename
Specify the pid file, only valid for Unix version.
-u --user name
Run the gatekeeper process as this user. Only valid for Unix versions.
--core n
(Unix only) Enable writing core dump files when the application crashes. A core dump file will not exceed n bytes in size. A special constant "unlimited" may be used to not enforce any particular limit.
The options in this subsection override the settings in the [RoutedMode] section of the configuration file.
-d --direct
Use direct endpoint call signaling.
-r --routed
Use gatekeeper routed call signaling.
-rr --h245routed
Use gatekeeper routed call signaling and H.245 control channel.
-o --output filename
Write trace log to the specified file.
-t --trace
Set trace verbosity. The more -t
you add, the more verbose to output.
For example, use -ttttt
to set the trace level to 5.
The configuration file is a standard text file. The basic format is:
[Section String]
Key Name=Value String
Comments are marked with a hash (#
) or a semicolon (;
)
at the beginning of a line.
The file
complete.ini
contains all available sections for the GnuGk.
In most cases it doesn't make sense to use them all at once.
The file is just meant as a collection of examples for many settings.
The configuration file can be changed at runtime.
Once you modify the configuration file, you may issue reload
command
via status port, or send a signal HUP
to the gatekeeper process on Unix.
For example,
kill -HUP `cat /var/run/gnugk.pid`
Fortytwo=42
N/A
This setting is used to test the presence of the config file. If it is not found, a warning is issued. Make sure it's in all your config files.
Name=OpenH323GK
OpenH323GK
Gatekeeper identifier of this gatekeeper. The gatekeeper will only respond to GRQs for this ID and will use it in a number of messages to its endpoints. This setting doesn't change when the config is reloaded!
Home=192.168.1.1
0.0.0.0
The gatekeeper will listen for requests on this IP number. By default, the gatekeeper listens on all interfaces of your host. You should leave out this option, unless you want the gatekeeper only to bind to a specified IP. Multiple Home addresses can be used and have to be separated with a semicolon (;) or comma (,).
NetworkInterfaces=192.168.1.1/24,10.0.0.1/0
N/A
Specify the network interfaces of the gatekeeper. By default the gatekeeper will detect the interfaces of your host automatically. There is situations that you may want to use this option. One is automatic detection fails. If you are using GnuGk behind a NAT box then you should use the ExternalIP setting which will automatically configure GnuGk to operate as if it was on the NAT box and superceded using this entry. This setting doesn't change when the config is reloaded!
Bind=192.168.1.1
0.0.0.0
Specify the IP address for default routing. If there is only one interface then this setting is ignored. Use this to specify which default IP address to use in a multihomed virtual environment where there are many virtual interfaces on one box.
EndpointIDSuffix=_gk1
_endp
The gatekeeper will assign a unique identifier to each registered endpoint. This option can be used to specify a suffix to append to the endpoint identifier. This is only useful when using more than one gatekeeper.
TimeToLive=300
-1
An endpoint's registration with a gatekeeper may have a limited life span. The gatekeeper specifies the registration duration of an endpoint by including a timeToLive field in the RCF message. After the specified time, the registration has expired. The endpoint shall periodically send an RRQ having the keepAlive bit set prior to the expiration time. Such a message may include a minimum amount of information as described in H.225.0. This is called a lightweight RRQ.
This configuration setting specifies the time-to-live timer in seconds until the registration expires. Note the endpoint may request a shorter timeToLive in the RRQ message to the gatekeeper. To avoid an overload of RRQ messages, the gatekeeper automatically adjusts this timer to 60 seconds if you give a lesser value!
After the expiration time, the gatekeeper will subsequently send two IRQ messages to query if the endpoint is still alive. If the endpoint responds with an IRR, the registration will be extended. Otherwise the gatekeeper will send a URQ with reason ttlExpired to the endpoint. The endpoint must then re-register with the gatekeeper using a full RRQ message.
To disable this feature, set it to -1
.
TraceLevel=2
0
Set trace level (same as -t on the command line).
This setting doesn't change when the config is reloaded!
TotalBandwidth=100000
-1
Total bandwidth available to be given to endpoints. By default this feature is off. Be careful when using it, because right now it only checks calls from registered endpoints and many endpoints supply give incorrect bandwidth values.
RedirectGK=Endpoints > 100 || Calls > 50
N/A
This option allow you to redirect endpoints to alternate gatekeepers when the gatekeeper overloaded. For example, with the above setting the gatekeeper will reject an RRQ if registered endpoints exceed 100, or reject an ARQ if concurrent calls exceed 50.
Furthermore, you may explicitly redirect all endpoints by
setting this option to temporary
or permanent
.
The gatekeeper will return an RAS rejection message with a list of
alternate gatekeepers defined in AlternateGKs
.
Note that a permanent
redirection means that the redirected endpoints
will not register with this gatekeeper again.
Please also note the function only takes effect to H.323 version 4
compliant endpoints.
AlternateGKs=1.2.3.4:1719:false:120:OpenH323GK
N/A
We allow for existence of another gatekeeper to provide redundancy. This is implemented in a active-active manner. Actually, you might get into a (valid !) situation where some endpoints are registered with the first and some are registered with the second gatekeeper. You should even be able use the two gatekeepers in a round_robin fashion for load-sharing (that's untested, though :-)). If you read on, "primary GK" refers to the gatekeeper you're currently configuring and "alternate GK" means the other one. The primary GK includes a field in the RCF to tell endpoints which alternate IP and gatekeeper identifier to use. But the alternate GK needs to know about every registration with the primary GK or else it would reject calls. Therefore our gatekeeper can forward every RRQ to an alternate IP address.
The AlternateGKs config option specifies the fields contained in the primary GK's RCF. The first and second fields of this string define where (IP, port) to forward to. The third tells endpoints whether they need to register with the alternate GK before placing calls. They usually don't because we forward their RRQs, so they get registered with the alternate GK, too. The fourth field specified the priority for this GK. Lower is better, usually the primary GK is considered to have priority 1. The last field specifies the alternate gatekeeper's identifier.
SendTo=1.2.3.4:1719
N/A
Although this information is contained in AlternateGKs, you must still specify which address to forward RRQs to. This might differ from AlternateGK's address, so it's a separate config option (think of multihomed machines).
SkipForwards=1.2.3.4,5.6.7.8
N/A
To avoid circular forwarding, you shouldn't forward RRQs you get from the other GK (this statement is true for both, primary and alternate GK). Two mechanisms are used to identify whether a request should be forwarded. The first one looks for a flag in RRQ. Since few endpoints implement this, we need a second, more reliable way. Specify the other gatekeeper's IP in this list.
StatusPort=7000
7000
Status port to monitor the gatekeeper. See this section for details.
StatusTraceLevel=2
2
Default output trace level for new status interface clients. See this section for details.
TimestampFormat=ISO8601
Cisco
Control default format of timestamp strings generated by the gatekeeper.
This option affects
[SqlAcct],
[RadAcct],
[FileAcct]
and other modules, except
[CallTable].
You can further customize timestamp formatting per-module by configuring
per-module TimestampFormat
setting.
There are four predefined formats:
RFC822
- a default format used by the gatekeeper (example: Wed, 10 Nov 2004 16:02:01 +0100)ISO8601
- standard ISO format (example: 2004-11-10 T 16:02:01 +0100)Cisco
- format used by Cisco equipment (example: 16:02:01.534 CET Wed Nov 10 2004)MySQL
- simple format that MySQL can understand (example: 2004-11-10 16:02:01)If you need another format, you can build your own format string, using
rules known from strftime
C function (see man strftime or search MSDN for strftime).
In general, the format string consists of regular character and format codes, preceded
by a percent sign. Example: "%Y-%m-%d and percent %%" will result in "2004-11-10 and percent %".
Some common format codes:
%a
- abbreviated weekday name%A
- full weekday name%b
- abbreviated month name%B
- full month name%d
- day of month as decimal number%H
- hour in 24-hour format%I
- hour in 12-hour format%m
- month as decimal number%M
- minute as decimal number%S
- second as decimal number%y
- year without century%Y
- year with century%u
- microseconds as decimal number (this is a GnuGk extension)%z
- time zone abbreviation (+0100)%Z
- time zone name%%
- percent signEncryptAllPasswords=1
0
Enable encryption of all passwords in the config (SQL passwords, RADIUS
passwords, [Password] passwords, [GkStatus::Auth] passwords). If enabled,
all passwords have to be encrypted using addpasswd
utility. Otherwise
only [Password] and [GkStatus::Auth] passwords are encrypted (old behavior).
KeyFilled=0
N/A
Define a global padding byte to be used during password encryption/decryption.
It can be overridden by setting KeyFilled
inside a particular config section.
Usually, you do not need to change this option.
Most users will never need to change any of the following values. They are mainly used for testing or very sophisticated applications.
UseBroadcastListener=0
1
Defines whether to listen to broadcast RAS requests. This requires binding to all interfaces on a machine so if you want to run multiple instances of gatekeepers on the same machine you should turn this off.
UnicastRasPort=1719
1719
The RAS channel TSAP identifier for unicast.
MulticastPort=1718
1718
The RAS channel TSAP identifier for multicast.
MulticastGroup=224.0.1.41
224.0.1.41
The multicast group for the RAS channel.
EndpointSignalPort=1720
1720
Default port for call signaling channel of endpoints.
ListenQueueLength=1024
1024
Queue length for incoming TCP connection.
SignalReadTimeout=1000
1000
Time in milliseconds for read timeout on call signaling channels (Q931).
StatusReadTimeout=3000
3000
Time in milliseconds for read timeout on status channel.
StatusWriteTimeout=5000
5000
Time in milliseconds for write timeout on status channel.
ExternalIP=myip.no-ip.com
N
A/When using GnuGk behind a NAT you can set the external IP address that you wish the GK to masquarade as. This will allow external EP's and other gatekeepers to contact the NATed GK. To work you must port forward the required ports to the GK IP or put the GK in the NAT box DMZ. This is different to the bind setting which sets a physical IP address on the GnuGk box to default to.
ExternalIsDynamic=1
0
Whether the external IP is dynamic and where queries are required to keep the external IP up to date. To work you must specify the External IP with a DNS address maintained by a DDNS service such as www.dyndns.com or www.no-ip.com.
DefaultDomain=gnugk.org
N
A/When receiving a request for an address in the format user@domain.com. This option will strip the domain from the address matching this value and process the request as the user component only. This is handy when dealing with interdomain calls placed via srv routing policy where the full URI is received. It can also be used in conjunction with the [RasSrv::RewriteAlias] section to convert the received URI into a E164 number for routing.
Authenticators=H.235.1,CAT
N
A/Selecting the specific authenticators to use when authenticating endpoints. The default options are: H.235.1 (HMAC SHA1 old H235AnnexD), MD5 (Digest Authentication) and CAT (Cisco Access Tokens ie RADIUS). If this setting is omitted, all authenticators are loaded by default. If you are using plugin authenticators, then you may want to disable the default authenticators to provide optimum security. Note: H.235.1 requires OpenSSL support compiled into GnuGk.
Define a number of rules who is allowed to connect to the status port. Whoever has access to the status port has full control over your gatekeeper. Make sure this is set correctly.
rule=allow
forbid
Possible values are
forbid
- disallow any connection.allow
- allow any connectionexplicit
- reads the parameter ip=value
where ip
is the IP address of the peering client,
value
is 1,0
or allow,forbid
or yes,no
.
If ip
is not listed the parameter default
is used.regex
- the IP of the client is matched against the given regular expression.
To allow client from 195.71.129.0/24 and 195.71.131.0/24:
regex=^195\.71\.(129|131)\.[0-9]+$
password
- the user has to input appropriate username and password to login. The format of username/password is the same as
[SimplePasswordAuth] section.
Moreover, these rules can be combined by "|" or "&". For example,
rule=explicit | regex
explicit
or regex
rule.
rule=regex & password
regex
rule, and the user has to login by username and password.default=allow
forbid
Only used when rule=explicit
.
Shutdown=forbid
allow
Whether to allow shutdown the gatekeeper via status port.
DelayReject=5
0
How long (in seconds) to wait before rejecting invalid username/password for the status line access.
This section defines log file related parameters. Currently it allows users to specify log file rotation options.
Filename=/var/log/gk_trace.log
N/A
Set the output filene for the log file (same as -o on the command line).
Rotate=Hourly | Daily | Weekly | Monthly
N/A
If set, the log file will be rotated based on this setting. Hourly rotation
enables rotation once per hour, daily - once per day, weekly - once per week
and monthly - once per month. An exact rotation moment is determined by a combination
of RotateDay
and RotateTime
variables. During rotation, an existing
file is renamed to CURRENT_FILENAME.YYYYMMDD-HHMMSS, where YYYYMMDD-HHMMSS
is replaced with the current timestamp, and new lines are logged to an empty
file. To disable the rotation, do not set Rotate
parameter or set it to 0.
[LogFile]
Rotate=Hourly
RotateTime=45
[LogFile]
Rotate=Daily
RotateTime=23:00
[LogFile]
Rotate=Weekly
RotateDay=Sun
RotateTime=00:59
[LogFile]
Rotate=Monthly
RotateDay=31
RotateTime=23:00