18. Monitor command language

The Monitor clause client programs to make an (authenticated) TCP connection to Radiator, and use that connection to monitor, probe, modify and collect statistics from Radiator. For more information, see Section 3.132. <Monitor>.
Monitor implements a simple command language, which is described in this section.
All Monitor connections must be authenticated with the LOGIN command before any significant command can be executed. If a connection has not been authenticated, the only commands that can be executed are LOGIN, HELP and QUIT.
Monitor supports 2 basic connection types:
Monitor supports 2 types of authentication in the LOGIN command:

18.1. Object naming

Some Monitor commands accept Radiator object names as arguments. This allows you to identify specific internal Radiator objects to operate on or to monitor. A Radiator object is an internal Radiator structure which generally corresponds to a clause in the Radiator configuration file. There always exists a main object (ServerConfig) that represents the server as a whole, and which is the ultimate ‘parent’ of all the other objects. The Radiator objects form a tree structure with ServerConfig as the root.
You can identify specific Radiator objects with an object name. An object name consists of a number of dot (‘.’) separated words. A single dot is taken to mean the root, the main ServerConfig object. In object names, case is significant.
Consider this skeleton Radiator configuration file:
DbDir ....
Trace 4
<Realm xyz.com>
      <AuthBy FILE>
Then the following object names could be used:
  • .
    A single dot refers to the server as a whole, or ServerConfig. If you got STATS from . then you would receive the statistics for the whole server.
  • .Client.0
    This refers to the first (and only) Client clause.
  • .Realm.0
    This refers to the first (and only) Realm xyz.com clause.
  • .Realm.0.AuthBy.0
    This refers to the AuthBy FILE clause inside the Realm clause.

18.2. Commands

All command names are case insensitive, but arguments to commands may be case sensitive.

18.2.1. BINARY

Makes the connection run in BINARY mode. In BINARY mode, commands and their responses are separated by NULL characters. BINARY mode is only suitable for Monitor client programs. Do not use BINARY for interactive Telnet connections.


Requests a CHAP challenge from Monitor. The reply may be used to generate a CHAP response in a subsequent LOGIN command. This allows client programs to avoid sending plaintext passwords on the Monitor TCP connection.

18.2.3. DESCRIBE objectname

Describes the named object by returning a list of its attributes and their types.

18.2.4. GET objectname

Not implemented.

18.2.5. HELP

Prints a list of the supported commands.

18.2.6. ID

Prints the Radiator server identification string.

18.2.7. LIST objectname

If objectname names an object array parameter (such as a Client, Realm or Handler array), prints a list of the objects in the array and their indexes.

18.2.8. LOGIN username password

Authenticate the connection, so that privileged commands can be executed. Username and password must be authenticated by one of the Monitor's AuthBy clauses, or by the hardwired Username and Password (if present).
Password may be either a plaintext password or a CHAP response to a previously issued CHALLENGE command.
LOGIN mikem fred
CHALLENGE 5b0e00b1a379ae225634946268cc0144 
LOGIN mikem {chap}4bda435ca72249c0e9fe05d32775eb6e98 

18.2.9. RESTART

Causes Radiator to restart and reread its configuration file, with the same effect as a SIGHUP.

18.2.10. TRACE n

Causes Radiator to start printing log message at or below the given log level. The number n can be 0 to 5 inclusive. Each new Monitor connection starts out at level 0 (ERR level). Level 4 is DEBUG level. After setting a new Trace level, Radiator will send all log messages at or below that level on the Monitor connection.
If a TRACE_USERNAME is in force, only messages that result from requests from that specific User-Name will be printed.

18.2.11. TRACE_USERNAME user name

Causes TRACE to only print log messages that result from a RADIUS request from the given User-Name. This is handy for seeing only log messages for a given user when debugging connection problems.
The user name is compared to the User-Name in the incoming request after any RewriteUsername rules have been applied. Setting the TRACE_USERNAME to an empty string (the default) turns off this special behaviour, and all messages that are at or below the current TRACE level will be output.
In the following example, the TRACE level is set to 4, meaning all DEBUG and lower level log messages will be printed. Then the TRACE_USERNAME is set to mikem@open.com.au, which means that only DEBUG and lower log messages due to requests from mikem@open.com.au will be printed. Finally the TRACE_USERNAME is set to an empty string, which means that all DEBUG and lower level log messages will be printed again.
TRACE_USERNAME mikem@open.com.au
      <<< only messages that are at or below the current TRACE level
      for requests from mikem@open.com.au
      are output here.>>>
      <<< no more user-specific logging now. All trace level 4
      messages will be output >>>

18.2.12. SET objectname parameter value

Sets a new value for the named parameter in the named object. The new value will persist in the Radiator until it is restarted. This is useful for experimenting with new configuration values without having to restart the server. It is probably most useful for setting the PacketTrace parameter, permitting DEBUG level tracing of all packets that pass through a given object.
For example, this command will set PacketTrace on the first Client clause. Subsequently, all packets arriving from that Client will by logged to this Monitor connection (and any other logger) at DEBUG level:
SET .Client.0 PacketTrace 1

18.2.13. STATS objectname

Requests all the statistics available from the named object.

18.2.14. QUIT

Forces disconnection from Monitor.