ClearBox Server™ v1.2 User's Guide


ClearBox Server is capable of logging. It can dump content of all packets it receive and send, all errors and warnings that may occur during server operation to files, Server Manager utility and to NT Event Log. It is vital information which can tell about processes occurring in the server.

These logs cannot be used for accounting and is intended for debugging purposes only.

All messages (errors, warnings, packets) are always logged into Server Manager utility. Also server may be configured to log messages into NT Event Log, but it is not recommended to dump packets there, as Event Log will become full soon.

Error Logging

All errors are logged to a specific file, and its name and path are specified in Server Manager. Default name is "errlog.txt", and it is located in the same directory with ClearBox Server (<installation directory>/Bin/errlog.txt).

Three types of events are logged into error file:

  • Errors. Every entry reporting about an error has its number, by which it can be identified (see numeric list of errors). An error has a description and may have additional information, which may describe error reason.
  • Warnings. They report about events that are not so severe as errors but may affect server operation.
  • Informational messages ("Info"). They carry information about changes in server state.

Error log file is the first place to look in when server does not operate properly. But if an error occurred before server configuration is read (so it doesn't know where error log file should be created), no errors are written in error log file. In that case all errors are written to NT Event Log as it always exists in the system.

See Troubleshooting for more details how to find errors and fix them.

Packets logging

ClearBox Server can be configured to log content of all packets. This feature should be used for debugging. If accounting logs are needed, they must be produced by server extension in its own format.

RADIUS and TACACS+ packets are logged into two different files, so necessary information can be found more easily. Packets are logged in transactions boundaries, which means that every request packet has matching response, and these packets are logged as one transaction. An empty line separates packets within a transaction.

RADIUS Packets

There are three types of transactions:

  • RADIUS Authentication transaction (Authentication request-response).
  • RADIUS Accounting transaction (Accounting request-response).
  • RADIUS Proxy transaction (RADIUS packet forwarded to another host and a response).

For every packet in a transaction the following fields are logged:

  • Client address. It is IP address of client (i.e. the sender of the request packet).
  • NAS address. It is the value extracted from NAS-IP-Address attribute if it was present in the packet.
  • UniqueID. It is the unique number assigned by server to the packet. It is incremented by one with every new packet.
  • Realm. It is the name of realm assigned to a user by server extension. If no realm is specified for a user, (null) is used.
  • User. It is user name for which the packet was created. It may not correspond to User-Name attribute from the request packet as server extension may transform it to another name.
  • PAP password. [Introduced in ClearBox v1.2] It is user password in cleartext form, decrypted from User-Password attribute in the Access-Request packet. The password is logged only if Log PAP cleartext passwords option is turned on in server configuration.
  • Code. It is standard RADIUS packet code describing type of the packet (e.g. Access-Request, Accounting-Response).
  • ID. It is ID of the RADIUS packet and is used for matching request-response packets.
  • Length. It is number of bytes in the packet. This field is valid for request packets only, and length of response packets is calculated after transaction is logged.
  • Authenticator. It is Authenticator field from the packet. Authenticator is calculated after transaction is logged, and is valid for request packets only.
  • Forwarded to/received from. It is specified for 'RADIUS Proxy transactions' and describes a host to which a packet was forwarded.

Then list of RADIUS attributes follows. The format in which they are logged depends on server configuration.

TACACS+ Packets

There are three types of transactions:

  • TACACS+ Authentication transaction
  • TACACS+ Authorization transaction
  • TACACS+ Accounting transact

For every packet the following fields are logged:

  • Packet type. (E.g."Authentication request", "Accounting response").
  • Client address. IP address of the packet sender. Specified by "Received from" for request packets and "Sent to" for response packets.
  • UniqueID. It is the unique number assigned by server to the packet. This value increments by one with every new packet.
  • Realm. It is the name of realm assigned to a user by server extension. If no realm is specified for a user, (null) is used.

Other fields are packet-type specific and represent fields of TACACS+ packets as they are described in protocol specification.

If the option "Dump TACACS+ packets headers" is checked in server configuration, TACACS+ packet header is logged, too. Its content may be used for easier debugging.

Raw Packets Logging

Since v1.15 ClearBox Server introduces a new feature - dumping all incoming and outcoming TACACS+/RADIUS packets to files in binary form. This feature can be useful in debugging when problems can be caused by invalid packet structure. The binary log (in hexadecimal form) of raw (unparsed) data allows to view and analyze the packets.

By default dumping raw data is turned off and can be configured with Server Manager on Server settings tab (Server Settings -> Logging settings -> Raw packet data dumping). Data bytes are grouped by four and are written for every received and sent packet with current date, time, IP address and port of a packet sender/receiver.

Note that this featured should normally be turned off as it affects server performance.

© 2001-2003 XPerience Technologies.

Created by chm2web html help conversion utility.