Next Previous Contents

13. Monitoring the Gatekeeper

13.1 Status Port

The status port is the external interface for monitoring and controlling the gatekeeper. The gatekeeper will send out messages about ongoing calls to all connected clients and it can receive commands via this interface.

Access to the status port is restricted by the rules in GkStatus::Auth. For security reasons, the default is not to allow any access until you have configured GkStatus::Auth.

The messages sent by the gatekeeper to the status port are grouped into three output trace levels: (These trace levels only apply to what is shown on the status port. Don't confuse them with the trace level for GnuGk's trace file.)

The client connected to the status port can choose the output level it is interested in.

The interface is a simple TCP port (default: 7000) which you can connect to with telnet or another client. One example of a different client is the Java GUI, aka GkGUI. Another example is the Automatic Call Distribution application, aka GnuGk ACD.

Application Areas

What you do with the powers of the Status Interface is up to you, but here are a few ideas:

Examples

Suppose you are just interested in the CDRs (call detail records) and want to process them as a batch at regular intervals.

Here is a simple Perl script (gnugk_cdr.pl) that starts the gatekeeper and also forks a very simple client for the Status Interface and writes just the CDRs into a logfile. You'll have to modify it a little to fit your needs.

#!/usr/bin/perl
# sample program that demonstrates how to write the CDRs to a log file
use strict;
use IO::Socket;
use IO::Handle;

my $logfile = "/home/jan/cdr.log";      # CHANGE THIS
my $gk_host = "localhost";
my $gk_port = 7000;
my $gk_pid;

if ($gk_pid = fork()) {
        # parent will listen to gatekeeper status
        sleep(1);       # wait for gk to start
        my $sock = IO::Socket::INET->new(PeerAddr => $gk_host, PeerPort => $gk_port, Proto => 'tcp');
        if (!defined $sock) {
                die "Can't connect to gatekeeper at $gk_host:$gk_port";
        }
        $SIG{HUP} = sub { kill 1, $gk_pid; };   # pass HUP to gatekeeper
        $SIG{INT} = sub { close (CDRFILE); kill 2, $gk_pid; };  # close file when terminated

        open (CDRFILE, ">>$logfile");
        CDRFILE->autoflush(1);  # don't buffer output
        while (!$sock->eof()) {
                my $msg = $sock->getline();
                $msg = (split(/;/, $msg))[0];   # remove junk at end of line
                my $msgtype = (split(/\|/, $msg))[0];
                if ($msgtype eq "CDR") {
                        print CDRFILE "$msg\n";
                }
        }
        close (CDRFILE);
} else {
        # child starts gatekeeper
        exec("gnugk");
}

Keep in mind that this is just an example to show the usage of the status port. You can use the FileAcct module to log CDRs in a production system.

Java GUI for the Gatekeeper

Developed by Jan Willamowius.

You can monitor the registrations and calls that go through the gatekeeper. A right-click on a button gives you a pop up menu for that endpoint.

This GUI works with Java 1.0 built into most web browsers. For security reasons the GUI must be run as a standalone application or served by a web server on the same IP number as the gatekeeper (you cannot run it as an applet via a local file).

The program is available at GnuGk.org

13.2 Commands (Reference)

This section lists all commands that you can issue to the status port (manually or with an external application). Commands are not case-insensitive, but parameters may be.

Entering help or h will display a list of all available commands.

13.3 Messages (Reference)

The section describes the messages output to the status interface.

13.4 Status Port Filtering

Status port filtering facilitates control of the amount and type of output messages shown to the end user. Filtering is done using regular expressions which are used to decide whether to include (show) or exclude (ignore) an output message. Filtering control is performed using the following set of commands:

In order to enable usage of predefined filters, a new section named [GkStatus::Filtering] has been introduced. You may specify predefined filters to be loaded when the status port starts.

Example:

[GkStatus::Filtering]
IncludeFilter=.+
ExcludeFilter=.RQ
Enable=1

When filtering is enabled using the the filter 1 command, all messages will be shown other than lines with ARQ, LRQ etc. You may also type the following into the status port: 

addincludefilter .+
addexcludefilter .RQ
filter 1

Note that if you enable filtering when there are no include filters defined this will automatically exclude all message output!

Example to hide Tandberg's neighbor check and traversal zone keepalive messages:

[GkStatus::Filtering]
Enable=1
IncludeFilter=.+
ExcludeFilter=gatekeeper-monitoring-check
ExcludeFilter=SCR

Next Previous Contents