Radar
Reference Manual

4.1 Single Host

In the simplest architecture, you might have a single computer (with its own display) running both Radiator and Radar. The host could be any Unix or Windows computer. In this case, you would configure Radar to monitor the single Radiator at localhost:9048, and Radar would display on the host computer's display.

FIGURE 1. Example single host deployment architecture

4.2 Multi Host

In a larger and more complicated installation, you might have multiple independent Radiators running on several different hosts throughout your network. You could then run Radar on your personal workstation. Radar would connect by TCP to each Radiator and display itself on your workstation, allowing you to monitor all the Radiators from one location.

FIGURE 2. Example multi host deployment architecture

4.3 Remote display

You might want to use Radar from a remote or home workstation, but security and firewalling issues may mean that you can't make a Radar connection on TCP port 9048 from home to your Radiators. In that case, you could run Radar on an internal host, and use an SSH forwarded X windows connection to display Radar's window on your home computer.

FIGURE 3. Example remote display deployment architecture

5.1 Requirements

• Any Unix or Windows computer with a graphical display (X windows on Unix)
• Radiator 3.0 or later
• Perl 5.6.0 or later
• Perl TK 800.023 or later
• Net::SMTP (if using email announcements)
• Approximately 4 MB of disk space

5.2 Unix

1. Ensure that Perl 5.6.0 or later is installed
2. Ensure that Perl TK 800.023 or later is installed
3. Unpack the distribution in a work area with
   zcat Radar-1.0.tgz|tar xvf -
4. cd Radar-1.0
5. perl Makefile.PL
6. make
7. make test
8. Log in as, or su to root:
   make install
9. Any user can now run Radar by typing:
   radar

5.3 RPMs

The Radar RPM package is suitable for use with RedHat 7, SuSE and other linux ditributions.

1. Log in as root
2. Ensure that Perl 5.6.0 or later is installed
3. Ensure that Perl TK 800.023 or later is installed
4. rpm -Uvh Radar-1.0-1.noarch.rpm
5. Any user can now run Radar by typing:
   radar

5.4 Windows

The Radar Makefile.PL includes support for Windows systems without nmake.

1. Download and install ActivePerl from http://www.ActiveState.com/ActivePerl. During installation, accept all the defaults. Allow setup to reboot your computer if it needs to.
2. Connect your computer to the Internet so you can download any required Perl modules from ActiveState using PPM.
3. Double click on c:\perl\bin\ppm (the Perl package manager). You will get a command line screen running ppm with a PPM> prompt.
4. Type the command:
   install Tk
The perl Tk module wil be installed for you.
5. Close the PPM window. Perl and Perl Tk is now installed.
6. Unpack your Radar distribution to a suitable location. Recent versions of WinZip can be used to decompress and unpack the distribution file.
7. Start an MSDOS command window, change directories to the place where you unpacked Radar.
8. Type perl Makefile.PL . This will check that your distribution is complete.
9. Run the regression tests with perl test.pl . You should see some lines like "ok xx", and none saying "not ok xx".
10. Install Radar by typing:
    perl Makefile.PL install
11. You can now run Radar by typing
    radar

7.1 Command line arguments

Radar understands a number of command line arguments:

 
radar [-h] [-v] [-d] [-i inifile] [tk options]

• -h
  Print usage text and exit.
• -v
  Print Radar version number and exit.
• -d
  Debug, print out details of commands sent to and from each Radiator, plus other Radar debugging detail. Useful only for Radar maintainers and customisers.
• -i inifile
  Specifies an alternative configuration file location. The default location is .radar.ini in the users home directory on Unix, and radar.ini in the current directory on Windows.
• tk options
  Radar understands all the generic Tk options such as -background, -class, -display,
  -font, -foreground, -geometry, -iconic, -motif.

Examples :

Run radar on Unix with the default config file:

 
radar

Run radar on Microsoft Windows with a common configuration file location:

 
radar -i c:\radar.ini

Run radar on Unix, starting with a custom config file, the window at 800 pixels wide and 400 pixels high in the top left corner of the display on 10.1.1.2:

 
radar -i /share/radar.ini -geometry 800x400+0+0 -display 10.1.1.2:0.0

7.2 Configuration

You can change and adjust many Radar configuration parameters with:

• File->Edit Radar Configuration
• Select a server, use Tools->Properties
• On a logger, change the logging level menu
• On a plotter, use the Properties... button

When Radar starts up, it attempts to restore its previous configuration from a configuration file. The default location of the Radar configuration file is:

• .radar.ini in your home directory on Unix
• radar.ini in the current directory on Windows

The location of the configuration file can be changed with the -i flag (see Section 7.1, Command line arguments ).

Radar can save its configuration to the configuration file, so that each time you start Radar, it will start up with the same configuration as before, monitoring the same servers, and with the same loggers and plotters visible.

By default, Radar only saves its configuration when you select File->Save Radar Configuration. However, if you enable `Auto Save Configuration' in File->Edit Radar Configuration..., under the General tab, then Radar will save the new configuration every time the configuration is changed.

Caution : The configuration file may contain Radiator access passwords. If so, ensure the configuration file is suitably protected against access by unauthorized personnel.

Hint : In order for Radar to start next time with the same configuration, save the current configuration with File->Save Radar Configuration, or set Auto Save Configuration in File->Edit Radar Configuration, General tab.

The following configuration options are available under the File->Edit Radar Configuration menu:

7.3 Monitoring a new Radiator

When Radar starts for the first time, you will be presented with an empty screen similar to Figure 4 . No Radiators are being monitored, and no monitoring tools are visible.

FIGURE 4. Radar just after it is started for the first time

In order to monitor a Radiator, you must first configure it into Radar. Before you can monitor a new Radiator, you will need to know the DNS name or IP address where it is running, and its Monitor port number. You will also need to know a valid username and password that can be used with the Radiator Monitor. If you don't know this information, consult your Radiator server administrator.

To configure Radar to monitor a new Radiator, choose Tools->Monitor new Radiator server.... You will then see a dialog similar to Figure 5 .

FIGURE 5. Enter host name or address and port number

Enter the DNS name or IP address of the Radiator host. The default of `localhost' means `on the same computer where Radar is running'. Also enter the port number that the Radiator Monitor is listening on. The default port of 9048 is the same as the default port that the Monitor clause uses. See Section 6.0, Radiator configuration for more details. Press Return, or click on OK. You will then see a login dialog similar to Figure 6

FIGURE 6. Enter Username and Password

Enter a valid Username and Password to authenticate the Radar connection to the Radiator Monitor. If the Username and Password are accepted by the Radiator, you will see the entry in the server list window change to loggedin, similar to Figure 7 . If the Username and Password are not accepted, you will be prompted for them again.

FIGURE 7. Radar connected and logged in to Radiator

Hint : in order to automatically reconnect to the same servers next time you start Radar, save the current configuration with File->Save Radar Configuration.

Hint : There is a right mouse button menu available on the server list window, containing the same options as in the Tools menu.

7.3.2 Changing server details

After adding a new server, you may want to change some of the configurable parameters for that server. The default values that Radar uses for new connections are perfectly suitable for most uses, but for advanced or unusual situations, you may wish to customize them.

To change server details, click on the servers entry in the server list, then choose Tools->Properties. A dialog similar to Figure 6 will appear.

FIGURE 8. Changing host monitoring details

You can change any or all of the server configuration parameters:

• Title
  This is the name that will be used for the server in the server list. It defaults to the hostname and port number, but you might want to change it to something that is more meaningful for your organization, such as `Primary Radius' or `Secondary Radius'.
• User Name
  The username that will be used to authenticate connections to this server.
• Password
  The password that will be used to authenticate connections to this server.
• Ping interval
  The time interval (in seconds) between attempts to contact the server. If the server is not currently connected, Radar will attempt to reconnect after each interval. If the server is connected and logged in, Radar will send an ID request each interval, so it can confirm that the Radiator is running properly and is not stalled.
• Stalled time
  The time interval (in seconds) to determine that a Radiator is stalled. If no response is received from the server for more than this time, it will be marked as `stalled' and the `stalled' announcements (if any) will be made.
• Max clock skew
  The maximum permissible time difference (in seconds) between the Radar host clock and the Radiator host clock. If this difference is exceeded, the `clock_skew' announcements (if any) will be made.

Hint : in order to reconnect with the same parameters next time you start Radar, save the current configuration with File->Save Radar Configuration.

Hint: use a time synchronisation system like NTP to synchronise the clocks on your Radar and Radiator hosts.

7.4 Viewing the Trace message log

You can optionally display a Trace message logger for each monitored Radiator. This allows you to easily see error and warning messages sent by Radiator, and optionally to enable debug messages, allowing you to analyze how and why Radiator is handling certain requests.

Radar Trace logging is in addition to and completely independent of any other logging configured into Radiator. If you have your Radiator configured to log ERR messages to a FILE, it will continue to do so irrespective of the settings of the Radar Trace logger.

To view a Trace logger for a Radiator, click on the server in the server list, then choose Tools->Trace log. You will see a logger window in the tools area, similar to Figure 9 .

Radar can only show one logger per server. If you try to view a new one, nothing will happen.

As Trace log messages arrive, they are scrolled upwards in the logger window, so the most recent messages are always visible. The standard Tk text menu is available with the right mouse button, allowing you to cut and search for text. All the messages received by the logger are kept in the text buffer (and therefore within Radar) until the logger window is closed.

Caution : this can mean that Radar memory usage can grow very large if you turn it on to debug logging on a busy server.

FIGURE 9. Viewing a Radiator Trace message log

The logger window can be resized vertically at any time by dragging the adjuster in the lower left corner of the window.

You can change the Trace level for the Radar logger at any time with the level option menu in the logger window. Radiator then only sends log messages that are at or above the trace level set by the trace level menu in Radar.

You can specify a logger Filter, so that the logger will only show messages resulting from Radius requests that satisfy the filter and which are at or above the current Trace level. To create or alter a filter, click on the Filter... button. A dialog will appear,allowing you to specify one or more Radius attributes, values and matching rules. Only Radius packets that satisfy all the rules will be logged to the Radar logging window. To accept the new filter, click on OK. The filter rules wil be printed in the logger window, and the new filter will take effect immediately.

FIGURE 10. Editing the logger packet filter

7.5 Viewing statistics

You can optionally display and plot statistics gathered by each monitored Radiator. Radiator gathers over 20 statistical measures for the server as a whole, and for each Radiator object (i.e. for each Client, Realm, Handler, AuthBy and Host in the Radiator configuration). Radar allows you plot any or all of the available statistics from any or all objects within a Radiator.

Plotting statistics allows you to see, for example, when Total throughput is unusually low, or if Average response time is usually high, indicating a problem in the authentication system. Many other interesting and useful statistics are also available, allowing you to keep close tabs on the health of your authentication system.

To view a plotter for a Radiator, click on the server in the server list, then choose Tools->Plot statistics. You will see a plotter window in the tools area, similar to Figure 11 . This plotter will show statistics gathered for the server as a whole.

To view a plotter for an object with Radiator, expand the server in the server list by clicking on the +. The server will expand to show all the configurable parameters and objects at that level within the server. You can drill down to see objects embedded within other objects. For example, to plot statistics for a single Client, click on + next to the server name to expand it, then click on the + next to Client. It will expand to list the name of each Client in the Radiator configuration. Click on the Client name, then choose Tools->Plot statistics. You will see a new plotter window in the tools area, similar to Figure 10 on page 15. This plotter will show statistics gathered for just that Client

FIGURE 11. Viewing a Radiator statistics plot

You can have any number of plotters for any number of Radiator internal objects. For example, you could have a `Total requests' plotter for the server as a whole, a separate `Average Response Time' plotter for the server as a whole, a `Bad authenticators in accounting requests' for a certain Client that is currently causing trouble, and a `Total requests' plotter for a Host in an AuthBy RADIUS, showing how many requests are being proxied. Furthermore, each plotter can plot any number of the available statistics for that object at the same time. However, it is not possible to have statistics from two different objects plotted in the same plotter. See Figure 12 , showing an example of Radar plotting statistics for two different servers.

Note that if a Radar becomes disconnected or unavailable while being plotted, the plot line for that Radiator will not be drawn while it is disconnected. This means there may be gaps in the plot line reflecting times when there was no statistical data available from that server. This is normal behaviour for Radar, but the cause of the diconnection should be investigated.

FIGURE 12. Viewing multiple statistics plots

For each plotter, you can extensively customize what statistics are displayed and how they are displayed. You can add and remove data items from the plotter, change colors and titles, and change the scale factors and plotting frequency.

To change the configuration of a plotter, click on the Properties button in the plotter. A configuration dialog similar to Figure 14 will appear.

The plotter configuration dialog contains two tabs. General ( Figure 13 ) allows you to configure parameters for the whole plotter. Data Sets ( Figure 14 ) allows you to configure each individually plotted statistic.

FIGURE 13. Changing plotter configuration General

The general tab allows you to configure the behaviour of the plotter as a whole.

• Title
  This field specifies the title to be used to label the plotter window. It appears in the bottom left corner of the plotter window, to the left of the Properties button. It defaults to the ID of the server and the name of the object it is plotting.
• Plot every
  Specifies how frequently statistical data is to be retrieved from Radiator for this plot. Options range from 1 Second to 1 Day
• Y Scale
  Specifies the range of the Y (vertical) scale. Options include `auto', `0-1', 0-10', `0-100' etc. Auto means vertical scale will be automatically chosen according to the maximum historical value of the displayed data, so that the data fits within the vertical scale.

FIGURE 14. Changing plotter configuration Data Sets

The Data Sets tab allows you to configure the look of each individual statistic displayed. On the left side, there is a list of available statistics from that object. Clicking on one will show how it is configured on the right. The following options are available

• Show
  Set this to make the statistic visible in the plotter. If not set, the statistic will not be plotted.
• Show name as
  Specifies an alternative name to use for this statistic in the plotter. Defaults to the standard Radiator name for the statistic.
• Style
  Specifies the way to display data points for this statistic. `Lines' means join samples with lines. `Dots' means plot each data point with a single 1 pixel dot. `Solid' mean plot the data as a filled solid vertical bar.
• Color
  Specifies the color to use to plot this data item.
• Normalise
  Specifies how to normalise the data for each statistic. Radiator provides the raw measurement of each data item. The most common choice is `per sec' which shows the average rate per second. Other choices include rescaling up or down by factors of 10, allowing differently scaled statistics to be usefully plotted on the same scale.

The plotter window can be resized vertically at any time by dragging the adjuster in the lower left corner of the window.

Hint : There is a right mouse button menu available on the plotting area of the plotter window. It includes a Properties button. If you click the right mouse button close enough to a data sample, it will show the name of the data item, and the time of the sample.

7.6 Viewing Radiator parameters

Radar allows you to drill down into the monitored Radiators to view and possibly change the Radiator configuration parameters. Click on the + next to a server in the server list window causes the list to expand and show all the top level server configuration parameters and clauses, similar to Figure 15 . Clicking on the + next to an object or object list causes it to expand in turn. Using this technique, you can explore the entire Radiator configuration.

FIGURE 15. Radiator with expanded parameter details

Many parameters display their current value next to them. You can resize and scroll the server list window to see more of the parameter list. Some parameters are not able to usefully display all their data values. They will show up as ARRAY or HASH or similar.

7.7 Changing Radiator parameters

Radar allows you to change selected Radiator configuration parameters. The changes are not permanent: they only last until the next time the Radiator is restarted (i.e the changes only effect the Radiator internal state). This feature allows you to quickly experiment with changes to the configuration without constantly restarting the server. For example, you can change the text of hooks, and set various flags, strings and integers in the configuration.

To change a configuration parameter, expand the server details in the server list window until you find the parameter you which to change.

Click on the parameter you are interested in, then choose Tools->Change Parameter Value... You will see an editing dialog similar to one of the ones shown in Figure 16 , Figure 17 , Figure 18 or Figure 19 .

FIGURE 16. Changing a flag parameter

FIGURE 17. Changing a hook parameter

FIGURE 18. Changing a string parameter

FIGURE 19. Changing an integer parameter

Edit or change the parameter, then press Ok. The dialog will disappear, and the new value for the parameter will appear next to the parameter in the server list window.

Using Radar you can only change some of the Radiator configuration parameters. You can change any string, integer, flag or hook parameter.

Hint : Not all parameter changes have an effect. For example, you can use Radar to change the Radiator AuthPort, but this will not actually change the port Radiator is listening on.

Hint : One of the more useful flag parameters for testing and debugging is the PacketTrace flag, available in each object. If a request passes `through' an object or clause with the PacketTrace flag set, Radiator will log at DEBUG level all the messages for that request, regardless of the current Trace level. This is useful, for example, for getting detailed traces for requests coming only from a certain Client.

Hint : When changing a hook, details of any compile errors for the new hook can be seen by opening a logger window to that server at Error level.

7.8 Restarting a Radiator

You can manually restart any Radiator connected to Radar. To restart a Radiator, click on its name in the server list window, then choose Tools->Restart Server. This has the same effect as sending a HUP signal: Radiator restarts by completely rereading its configuration file.

9.1 Support contract holders

Radar support may be purchased at the time you purchase Radar. See http://www.open.com.au/ordering.html for details. Support contracts last for a limited period (typically one year) and may include a limited amount of pre-paid email support.

Open System Consultants will respond promptly to support email during business hours, Australian Eastern Standard time. Telephone support is not provided. We will keep track of the effort required to answer your support email, and inform you when your prepaid support time has expired.

If you have a Radar or Radius support contract, you may send email to

 
radius-support@open.com.au

Include your support contract identifier in the Subject line. If you don't have a support contract, we will not respond to your query on this address.

If you need an urgent response outside of the standard email support hours, you may want to post to the Radar mailing list instead. Someone will be sure to be awake somewhere in the world.

9.2 No support contract

The standard Radar license does not include support, but it does include the full source code and free access to the Radar mailing list. This means you can help yourself, and you can work with other Radar users in the user community. In order to participate with others in this effort, you can join the Radar mailing list by sending email with the single word subscribe in the body ( not in the subject line) to

 
radar-request@open.com.au

After subscribing you can post to the mailing list by mailing to

 
radar@open.com.au

The staff of OSC monitor the Radar mailing list and frequently answer questions. It's very active so don't hesitate to use it. There is an archive of the mailing list available at http://www.open.com.au/archives/radar/

Please , don't post HTML to the Radar mailing list. Not everyone is using HTML compatible mailers.

9.3 What to do if you need help

Before you post to the support address or mailing list asking for assistance, we suggest you go through the following check list:

1. Consult this reference manual.
2. Consult the FAQ at http://www.open.com.au/radar/faq.html for extra hints and up-to-date information.
3. Consult the mailing list archive at http://www.open.com.au/archives/radar/ for more hints. You can search this archive for items related to your problem.
4. Check that you are using the latest version of Radar. See
   http://www.open.com.au/radar/downloads, use the username and password we have issued to you. Upgrade if you need to.
5. Check whether there are any patches that address your problem. See the README file in the patches directory for your release at
   http://www.open.com.au/radar/downloads/patches-*/README. Apply the patch if you think you might need it.
6. If you still have the problem, post to the mailing list by mailing to:
   radar@open.com.au. I f you have a support contract, send email to radar-support@open.com.au.
Be sure to include at least the following information:
7. A detailed description of the problem.
8. Your Radar and Radiator configuration files (remove any secrets and passwords first).
9. An extract from your Radiator log file (with Trace level of 4) illustrating the problem, or at least what is happening at the time of the problem.
10. Details of the computer type, operating system etc.

This information helps people to better understand your problem and help find a solution more quickly.

9.4 Announcements

There is a separate Radar mailing list that just carries product announcements and upgrades. If you want to know about upgrades available, but do not want all the technical volume from the normal mailing list, this may be the one for you. Radar product announcements will be posted to both lists.

You can join the Radar Announcements mailing list by sending email with the single word subscribe in the body ( not in the subject line) to

 
radar-announce-request@open.com.au

9.5 Bug reports

We are interested in your feedback, both positive and negative, and bug reports. Please send them to info@open.com.au. Licensees are entitled to free upgrades, and we do fix bugs that are reported to us, so if you report a bug, you can expect to get an upgrade with a fix one day. If you don't report it, it might never get fixed.