12. Utility Programs

Controlling who and when was logged in

12.1 radwho		Show who is logged in by radius now.
12.2 radlast		Show the history of logins by radius.

Maintenance commands

12.3 radzap		Modify the login records.
12.4 radgrep		Quickly find the login record.
12.5 radping		Ping the remote machine by the username.
12.6 radauth		Check if a user can be authenticated.
12.7 radctl		Radctl monitor.
12.8 builddbm		Create DBM version of the `raddb/users' file.

Guile interface

12.9 radscm: A Guile Interface to Radius Functions

A Guile interface to radius functions.

12.1 radwho

Radwho displays the list of users currently logged in by the Radius server.

Default output information is made compatible with that of the standard UNIX finger(1) utility. For each user the following information is displayed: login name, name, connection protocol, NAS port, login date, NAS name, assigned IP or corresponding network name.

When used with `-l' option, the long output format is used. In this format the following information is output:

`Login'

Login name of the user

`SessionID'

Unique session ID assigned by the terminal server.

`Proto'

Connection prototype.

`Port'

Port number

`When'

Login date and time

`From'

Name of the NAS that accepted the connection.

`Location'

Framed IP or the corresponding network name.

`Caller'

Caller station ID ad reported by the NAS.

`Duration'

Duration of the session.

12.1.1 radwho Command Line Options		Command line options.
12.1.2 radwho Format Strings
12.1.3 radwho Predefined Formats

12.1.1 radwho Command Line Options

The following command line options can be used to modify the behavior of the program:

`-A'

`--all'

Display the information about logged-out users as well. The logged-out users are shown with `Proto' field set to HUP.

`-c'

`--calling-id'

Display the calling station ID in the second column. Equivalent to `--format clid'.

`-d NAME'

`--directory NAME'

Set the Radius configuration directory name.

`-D fmt'

`--date-format fmt'

Set the date representation. Th fmt is usual strftime(3) format string. It defaults to %a %H:%M, i.e. the abbreviated weekday name according to the current locale, and the hour and the minutes as two-digit decimal numbers.

`-e STRING'

`--empty STRING'

Display any empty field as STRING. This is useful when the output of radwho is fed to some analyzing program, as it helps to keep the same number of columns on each line of output.

`-F'

`--finger'

Start in fingerd mode. In this mode radwho emulates the behavior of the fingerd(8) utility. Use this option if starting radwho from the `/etc/inetd.conf' line like this (5):

finger stream tcp nowait nobody /usr/sbin/radwho radwho -fL

This mode is also enabled by default if radwho notices that its name (argv[0]) is `fingerd' or `in.fingerd'.

`-H'

`--no-header'

Don't display header line.

`-i'

`--session-id'

Display session ID instead of GECOS in the second column. Equivalent to `--format sid'.

`-I'

`--ip-strip-domain'

Display hostnames without domain part.

`-u'

`--local-also'

Display information about local users from the system `utmp' file. May prove useful when running radwho as a finger daemon.

`-n'

`--no-resolve'

Do not resolve IP.

`-o format'

`--format format'

Select customized output format. This can also be changed by setting the value of environment variable RADWHO_FORMAT. The format is either a symbolic name of one of the predefined formats or a format specification (see next subsection).

`-s'

`--secure'

Run in secure mode. Queries without a user name are rejected.

12.1.2 radwho Format Strings

A format string controls the output of every record from `radutmp'. It contains two types of objects: ordinary characters, which are simply copied to the output, and format specifications, each of which causes output of a particular piece of information from the `radutmp' record.

Each format specification starts with an opening brace and ends with a closing brace. The first word after the brace is the name of the format specification. The rest of words are positional arguments followed by keyword arguments. Both are optional. The keyword arguments begin with a colon and must follow the positional arguments.

The full list of format specifications follows.

Format Spec: newline [count]

Causes the newline character to be output. If the optional count is supplied, that many newlines will be printed

Format Spec: tab [num]

Advance to the next tabstop in the output stream. If optional num is present, then skip num tabstops. Each tabstop is eight characters long.

The following specifications output particular fields of a `radutmp' record. They all take two positional arguments: width and title.

The first argument, width sets the maximum output length for this specification. If the number of characters actually output is less than the width, they will be padded with whitespace either to the left or to the right, depending on the presence of the :right keyword argument. If the number of characters is greater than width, they will be truncated to fit. If width is not given, the exact data are output as is.

The second argument, title, gives the title of this column for the heading line. By default no title is output.

Every field specification accepts at least two keyword arguments. The keyword :right may be used to request alignment to the right for the data. This keyword is ignored if width is not given.

The keyword :empty followed by a string causes radwho to output that string if the resulting value for this specification would otherwise be empty.

Format Spec: login width title [:empty repl][:right]

Print the user login name.

Format Spec: orig-login width title [:empty repl][:right]

Print original login name as supplied with the request.

Format Spec: gecos width title [:empty repl][:right]

The GECOS field from the local `/etc/passwd' corresponding to the login name. If the user does not have a local account, his login name is output.

Format Spec: nas-port width title [:empty repl][:right]

NAS port number

Format Spec: session-id width title [:empty repl][:right]

The session ID.

Format Spec: nas-address width title [:empty repl][:right][:nodomain]

The NAS name or IP.

The :nodomain keyword suppresses the output of the domain part of the name, i.e., the hostname is displayed only up to the first dot.

Format Spec: framed-address width title [:empty repl][:right][:nodomain]

Framed IP assigned to the user, if any.

The :nodomain keyword suppresses the output of the domain part of the name, i.e. the hostname is displayed only up to the first dot.

Format Spec: protocol width title [:empty repl][:right]

Connection protocol as reported by Framed-Protocol attribute. If the symbolic value is found in the dictionary file, it will be displayed. Otherwise, the numeric value will be displayed as is.

Format Spec: time width title [:empty repl][:right][:format date-format]

Date and time when the session started.

The :format keyword introduces the strftime format string to be used when converting the date for printing. The default value is %a %H:%M.

Format Spec: duration width title [:empty repl][:right]

Total time of the session duration.

Format Spec: delay width title [:empty repl][:right]

Delay time (see section 14.2.2 Acct-Delay-Time).

Format Spec: port-type width title [:empty repl][:right]

Port type as reported by the value of the NAS-Port-Type attribute. If the symbolic value is found in the dictionary file, it will be displayed. Otherwise, the numeric value will be displayed as is.

Format Spec: clid width title [:empty repl][:right]

The calling station ID.

Format Spec: realm width title [:empty repl][:right][:nodomain]

If the request was forwarded to a realm server, print the symbolic name of the realm from the `raddb/realms' file. If no symbolic name is found, print the remote server IP or hostname. In the latter case, the :nodomain keyword may be used to suppress the output of the domain part of the name, i.e. to display the hostname only up to the first dot.

12.1.3 radwho Predefined Formats

The predefined formats are:

`default'

Default output format. Each record occupies one line. The fields output are: login name, GECOS name, connection protocol, port number, time when the connection was initiated, NAS IP, and assigned framed IP. This corresponds to the following format specification (split in several lines for readability:

(login 10 Login) (gecos 17 Name) \ (protocol 5 Proto) (nas-port 5 TTY) \ (time 9 When) (nas-address 9 From) \ (framed-address 16 Location)

`sid'

The same as `default', except that the session ID is output in the second column.

`clid'

The same as `default', except that the calling station ID is output in the second column.

`long'

Outputs all information from each `radutmp' record. It is equivalent to specifying the following format string:

(login 32 Login) (session-id 32 SID) \ (protocol 5 Proto) (nas-port 5 Port) \ (time 27 Date) (nas-address 32 NAS) \ (clid 17 CLID) (duration 7 Duration) \ (framed-address 16 Location) (realm 16 Realm)

`gnu'

Each `radutmp' record is represented as a table. It is equivalent to specifying the following format string:

User: (login)(newline)\ In real life: (gecos)(newline)\ Logged in: (time)(newline)\ NAS: (nas-address)(newline)\ Port: (nas-port)(newline)\ CLID: (clid)(newline)\ Protocol: (protocol)(newline)\ Session ID: (session-id)(newline)\ Uptime: (duration)(newline)\ Assigned IP: (framed-address)(newline)\ Realm: (realm)(newline)"

12.2 radlast

The radlast utility lists sessions of specified users, NASes, NAS ports, and hosts, in reverse time order. By default, each line of output contains the login name, the NAS short name and port number from where the session was conducted, the host IP or name, the start and stop times for the session, and the duration of the session. If the session is still continuing, radlast will so indicate.

When the `-l' option is specified, radlast produces long output. It includes following fields:

• Login name
• NAS short name
• Port number
• Connection protocol
• Port type
• Session ID
• Caller ID
• Framed IP address
• Session Start Time
• Session Stop Time
• Duration of the Session

12.2.1 radlast Command Line Options

Command line options.

12.2.1 radlast Command Line Options

Use following command line options to control the behavior of the radlast utility:

`-number'

`-c number'

`--count number'

When given this option, radlast will output at most this many lines of information.

`-f'

`--file name'

Read the specified file instead of the default `/var/log/radwtmp'.

`-h hostname'

`--host hostname'

Report the logins from given host. Host can be either a name or a dotted-quad Internet address.

`-n shortname'

`--nas shortname'

Report the logins from the given NAS.

`-l'

`--long-format'

Long output format. Report all the information stored in `radwtmp' file.

`-p number'

`--port number'

Report the logins on a given port. The port may be specified either fully or abbreviated, e.g. radlast -p S03 or radlast -p 3.

`-s'

`--show-seconds'

Report the duration of the login session in seconds instead of the default days, hours, and minutes.

`-t'

The same as `-p'. This flag is provided for compatibility with last(1).

`-w'

`--wide'

Widen the duration field to show seconds as well as the default days, hours and minutes.

If multiple arguments are given, the logical OR operation between them is assumed, i.e., the information selected by each argument is printed. This, however, does not apply to the `-c' option. That option is always combined with the rest of command line by logical AND.

The pseudo-user `~reboot' logs in on every reboot of the network access server.

If radlast is interrupted, it indicates to what date the search had progressed.

12.3 radzap

radzap searches the Radius accounting database for matching login records and closes them.

At least one of the options `-n', `-p', or the user name must be specified. If they are used in conjunction, they are taken as if joined by the logical AND operation.

radzap operates in two modes: silent and confirm. The silent mode is enabled by default. When run in this mode, radzap deletes every record that matches the search conditions given.

In confirm mode radzap will ask for a confirmation before zapping each matching record. Any line beginning with a `y' is taken as a positive response; any other line is taken as a negative response.

The confirm mode is toggled by the command line option `-c'.

Syntax

radzap [options] [username]

Options are:

`-c'

`--confirm'

Enable confirm mode.

`-d dir'

`--directory dir'

Specify alternate configuration directory. Default is `/usr/local/etc/raddb'.

`-f file'

`--file file'

Operate on file instead of the default `RADLOG/radutmp'.

`-l dir'

`--log-directory dir'

Search the file `radutmp' in the given directory.

This option is deprecated. It is currently retained for backward compatibility with previous versions.

`-q'

`--quiet'

Disable confirm mode.

`-h'

`--help'

Display a short help summary, and exit.

`-n name'

`--nas name'

Specify NAS name to zap user from.

`-p port'

`--port port'

Specify the port number of the session to be zapped. The port number can be specified either in its full form, e.g. radzap -p S02, or in its short form, e.g. radzap -p 2.

12.4 radgrep

This utility allows one to quickly look up the user in the Radius accounting database, using a regular expression match. radgrep scans the output of radwho utility and outputs only the lines that match given regular expressions.

Syntax

12.5 radping

This utility is a shell program that determines the user's framed IP and runs ping on that address.

Syntax

radping username
radping -c calling-station-id

The second way of invoking the program allows one to use the calling station ID to indicate the user.

12.6 radauth

The radauth utility sends the Radius server an Access-Request packet and displays the result it gets. If the server responds with Access-Accept radauth can also send an Accounting-Request thereby initiating user's session.

The utility is a radtest program. See section 13.2.12 Sample Radtest Program, for the detailed discussion of its internals.

Invocation

radauth [options] [command] user-name [password]

Options are:

`-v'

Print verbose descriptions of what is being done.

`-n nas-ip'

Set NAS IP address

`-s sid'

Set accounting session ID

`-P port'

Set NAS port number.

<FIXME> GNU long options are not yet supported </>

Valid commands are:

auth

Send only Access-Request. This is the default.

acct

Send Access-Request. If successfull, send Accounting-Request with Acct-Status-Type = Start.

start

Send Accounting-Request with Acct-Status-Type = Start.

stop

Accounting-Request with Acct-Status-Type = Stop.

The program determines which Radius server to use, the authentication port number, and the shared secret, following the procedure common to all client scripts (see section 13.1 Client Configuration).

12.7 radctl

Radctl is a control interface to the radiusd daemon. It allows the user running it to query radiusd about various aspects of its work and to issue administrative commands to it. The syntax is

radctl command [args]

where command is a command telling radctl which actions to take, and args are optional arguments to the command. Only one command can be specified per invocation.

The valid commands are as follows:

start [args]

If radiusd is not running already, it is started. When present, args are passed as the command line to the server.

stop

Stops running radiusd.

restart [args]

Stops the server and then starts it again. When present, args are passed as the command line to the server.

reload

Causes the running radiusd server to reread its configuration files.

dumpdb

Tells radiusd to dump its user hash table into the file `radlog/radius.parse'. This can be used for debugging configuration files.

which

Reports the running version of radiusd. This command shows the line of ps(1) describing the running copy of radiusd program. The exact look depends on the version of operating system you are running. Please refer to "man ps" for more detail on ps output.

Here is an example of what radctl which prints on GNU/Linux:

19692 ? 01:53:11 radiusd

Here, first field is the PID of the process, second field (`?') indicates that the running program has detached from the controlling terminal, the third field gives total amount of CPU time used by the program, and, finally, the last field shows the full name under which the command was invoked.

12.8 builddbm

Usage

Syntax

If used with one argument, that argument is taken as the name of the plaintext database file to operate upon.

Use the following command line options to modify the operation of buildbm:

`-d dir'

Specifies alternate directory for the Radius configuration files. This defaults to `/usr/local/etc/raddb'.

`-h'

Outputs short usage summary and exits with 0 exit code.

12.9 radscm: A Guile Interface to Radius Functions

radscm is a Scheme interpreter based on Guile with the addition of special functions and variables for communicating with radiusd. This chapter concentrates on the special features provided by radscm. Refer to Guile documentation for information about Scheme and Guile (see section `Overview' in The Guile Reference Manual).

Variables

Variable: %raddb-path

A path to the Radius configuration directory.

Function: rad-server-list

A list of radius servers. Each element of the list is:

(list id-str host-str secret-str auth-num acct-num cntl-num)

where the arguments are as follows:

id-str	Server ID
host-str	Server hostname or IP
secret-str	Shared secret key to use
auth-num	Authentication port number
acct-num	Accounting port number
cntl-num	Control channel port number

Thus, each entry can be used as an argument to rad-client-set-server or rad-client-add-server.

Functions

Function: rad-send-internal port-number code-number pair-list

Sends the request to currently selected server. Arguments are:

port-number

Port number to use. These values are allowed:

0	Authentication port
1	Accounting port
2	Control port

The actual port numbers are those configured for the given server.

code-number

Request code.

pair-list

List of attribute-value pairs. Each pair is either

(cons attr-name-str value)

or

(cons attr-number value)

Return: On success,

(list return-code-number pair-list)

On failure,

'()

Function: rad-send port-number code-number pair-list . verbose

Sends a radius request. Actually it does the same work as rad-send-internal, but if verbose is specified, the verbose report about interaction with the radius server is printed.

Function: rad-client-list-servers

List currently configured servers. Two columns for each server are displayed: server ID and IP.

Function: rad-get-server

Returns the ID of the currently selected server.

Function: rad-client-set-server list

Selects for use the server described by list. Here list takes the form

(list id-str host-str secret-str auth-num acct-num cntl-num)

where the elements are as follows:

id-str	Server ID
host-str	Server hostname or IP
secret-str	Shared secret key to use
auth-num	Authentication port number
acct-num	Accounting port number
cntl-num	Control channel port number

Function: rad-client-add-server list

Adds the server described by list to the list of active servers. Here list takes the form

(list id-str host-str secret-str auth-num acct-num cntl-num)

where the elements are as follows:

id-str	Server ID
host-str	Server hostname or IP
secret-str	Shared secret key to use
auth-num	Authentication port number
acct-num	Accounting port number
cntl-num	Control channel port number

Function: rad-read-no-echo prompt-str

Prints the given prompt-str, disables echoing, reads a string up to the next newline character, restores echoing, and returns the string entered. This is the interface to the C getpass(3) function.

Function: rad-client-source-ip ip-str

Sets the IP to be used as source. ip-str can be either an IP in dotted-quad form or a hostname.

Function: rad-client-timeout number

Sets the timeout in seconds for waiting for a server reply.

Function: rad-client-retry number

Sets the number of retries for sending requests to a Radius server.

Function: rad-format-code dest-bool code-number

Format a radius reply code into a human-readable form. dest-bool has the same meaning as in format (see section `Formatted Output' in The Guile Reference Manual.)

Function: rad-format-pair dest-bool pair

Format a radius attribute-value pair for output. dest-bool has the same meaning as in format. pair is either

(cons name-str value)

or

(cons attr-number value)

where value may be of any type appropriate for the given attribute.

Function: rad-print-pairs dest-bool pair-list

Output the radius attribute-value pairs from pair-list. dest-bool has the same meaning as in format. pair-list is a list of pairs in the form

(cons name-str value)

or

(cons attr-number value)

where value may be of any type appropriate for the given attribute.

All Reply-Message pairs from the list are concatenated and displayed as one.

Function: rad-format-reply-msg pair-list . text

Concatenate and print text from all Reply-Message pairs from pair-list. If text is specified, it is printed before the concatenated text.

Function: rad-list-servers

For each server from rad-server-list, print its ID and hostname or IP.

Function: rad-select-server ID-STR

Select the server identified by id-str as a current server. The server data are looked up in rad-server-list variable.

Function: rad-add-server id-str

Add the server identified by id-str to the list of current servers. The server data are looked up in rad-server-list variable.