GNU Radius NEWS -- history of user-visible changes. 2003-07-21
Copyright (C) 2002,2003 Free Software Foundation, Inc.
See the end for copying conditions.

Please send radius bug reports to <bug-gnu-radius@gnu.org>

Version 1.1:

* Bugfixes:

** Do not stop decoding	of the incoming request upon encountering of an
unknown or malformed attribute ('no Acct-Status-Record bug').
** Makefile.am's fixed to allow for `make DESTDIR=whatever install'.
** Close stdout when running Acct-Ext-Program, so that its eventual output
does not disturb the main process.
** Fixed extended request comparison.
** Fixed bug in hints processing that caused coredumps if the hints
entry attempted to replace the first attribute in the request.

* New features:

** Caching of the results of SQL queries during authentication and
accounting.
** Strings in raddb/config may contain escaped characters. This is
useful mainly for username-chars statement.
** Test shell significantly improved.


Version 1.0:

This version uses a different approach to simultaneous handling of the
requests. Instead of spawning a child each time a request arrives, the
main server keeps a pool of subprocesses and distributes the requests
among them. This allows to ensure the stability of the SQL
connections, and makes possible the retransmission of the replies should
the duplicate requests arrive.

* New features

** Support for Guile version 1.6 and newer.

** Multiple remote servers may be defined in a radius realm. 

** New IP allocation strategy.

Included is the plug-in module ipalloc.scm that implements a new
strategy of allocating framed IP addresses for the users. See file
doc/README.ipalloc for more info.

** Support for non-standard vendor-specific attributes.

** Radwho supports several predefined output formats.

** NLS support.

* Important differences in behaviour compared to the 0.96 series

** The default ports are now 1812 for authentication and 1813 for
accounting, as per RFC 2865. If you wish to continue using old
port values (1645/1646), invoke configure with --with-auth-port=old
option. Alternatively, you may use `listen' statement in your
raddb/config to change the compilation defaults.

** Additional information in logs.

Whenever possible, radius displays in its logs the additional
information about the request that triggered the log entry.
For example:

Jun 23 12:59:58 [10653]: Auth.warning: (AUTHREQ nas-6 224 user): 
Multiple logins: [user] max. 1, CLID unknown

Here "AUTHREQ" means that the request was of Authentication-Request type,
"nas-6" is the name of the NAS that sent the request, "224" is the
ID of the request, and "user" is the user name.

** The processing of raddb/hints is now done before raddb/realms for
all packets. The prior versions processed this file after raddb/realms
for accounting requests.

** The only accounting requests that are not processed are those which
do not have the NAS-Port-Id attribute and those whose processing is
explicitly disabled by Acct-Type attribute in raddb/hints. The 0.96
series did not account requests with NAS-Port-Type attribute set to
Sync and those with User-Name attribute "!root". If you wish to
emulate this behavior, see the file examples/hints-0.96.

** Specifying Auth-Type = Authenticate-Only in the LHS of a
users profile does not alter the authentication process as it did
in 0.96.

** Support for legacy ComOS accounting-on/accounting-off requests
was removed from the main server code and re-implemented in Rewrite
language. See examples/comos.rw for details.

** The syntax of radwho format specifications has been changed.

* Changes to configure

** --enable-snmp gets optional argument 'compat'.

The radius-specific MIBs use the MIB subtree allocated for GNU project:
.iso.org.dod.internet.private.enterprises.gnu.radius (.1.3.6.1.4.1.11591.1).
Previous versions have used the GNU radius private subtree for this purpose
(.iso.org.dod.internet.private.enterprises.gnu-radius = .1.3.6.1.4.1.9163)
Specifying --enable-snmp=compat enables support of this subtree along with
the official GNU subtree.

* Changes in raddb/config 

** New keywords (see example/config.syntax)

*** max-processes

This keyword controls the maximum number of handler processes the
dispatcher is allowed to start. It may be used in `option' block
(see raddb/config.status for an example). The default value is 16.
Please notice that each new process consumes 4 file descriptors, so
make sure you have enough descriptors available before increasing this
value.

*** process-idle-timeout

Each subprocess waits for the request for this amount of time.
If no request arrives, the subprocess exits.

*** print-milliseconds

This boolean keyword that can be used in `channel' statement of
the `logging' block. It makes radiusd print log timestamps with
milliseconds. See raddb/config.syntax for examples.

*** master-read-timeout

This keyword controls the amount of time the server waits when
reading data from the child process. If no data arrives within this
time, the child is considered `stuck' and is terminated. By default
the value of this parameter is zero (no timeout at all).

*** master-write-timeout

Sets the number of seconds to wait for the child input channel to be
able to receive data from the dispatcher process. If it does not
become ready within this time , the child is considered `stuck' and
is terminated. By default the value of this parameter is zero (no
timeout at all).

*** storage

This new block statement in the `snmp' section allows you to configure
the storage file for the SNMP service. You will have to use this
statement if you see in your log file one of the following notices:

reached SNMP storage limit for the number of monitored ports:
increase max-port-count

or

reached SNMP storage limit for the number of monitored NASes:
increase max-nas-count

See the file examples/config.syntax for an example and the
accompanying documentation for more information on this statement.

** Deprecated keywords

*** usr2delay (option)

*** spawn (auth,acct,snmp)

The keyword is useless in the new multiprocess model

*** proxy (block statement)

Proxied requests are handled on the common basis with their
corresponding requests (auth or acct).

** Use of listen statement is allowed in snmp block.

** New block statement `filters' declares user external filters.
Filters are another way of adding radius extensions.
See accompanying documentations for more detail (node `Filters').

* sqlserver: auth_max_connections and acct_max_connections are
deprecated

The maximum number of connections to the authentication database equals
the maximum number of processes set by `max-processes' statement. The
same holds for the number of connections to the accounting database.

* Testsuite completely rewritten.


=============================================================================
Changes in Radius 0.96.4

* The syntax of the "rewrite" language is extended. It 
  supports addressing multiple attributes in a request and
  deleting arbitrary attributes.

* Fixed bug in "rewrite" optimizer, which caused boolean
  short-cuts (|| and &&) to malfunction.

* Added support for sybase and SecurID (thanks to Steve Bleazard)

* Introduced new Auth-Type value Ignore. It causes the incoming request
  to be dropped.

* Configurable comparison of the requests allows to detect duplicate
  requests even if the NAS changes request ID or authenticator between
  retransmissions.

* Fixed bug in formatting A/V pairs for detailed logging which
  caused radiusd to dump core upon receiving certain vendor-specific
  attributes.

* If the incoming request does not contain NAS-IP-Address attribute,
  it is generated and added to it.

* Fixed bug in handling Expiration attribute


=============================================================================
Changes in Radius 0.96.3

* Radiusd now automatically determines whether CHAP authentication
  type should be used.

* Proxy-State attributes are preserved in accounting replies.

* Ascend-specific filters (attributes Ascend-Call-Filter and
  Ascend-Data-Filter are now supported. Note, that you will
  have to update your raddb/dict/ascend dictionary to use
  this feature.


=============================================================================
Changes in Radius 0.96.2

This release fixes some bugs found in 0.96. These are:

* Malfunction of the daemon if the total number of reported ports
  grows beyond STAT_MAX_PORT_COUNT (default 1024).

* Inconsistencies in Postgres part of db/ scripts.

* Typo in raddb/Makefile.am which prevented menus subdirectory
  from being installed.

* Typos in raddb/config.y (acct_def production) which caused
  spawn, ttl, max-requests and request-cleanup-delay statements
  to affect authentication settings, instead of accounting ones.

* Client sub-package has been extended to send accounting
  packets as well.

* Fixed bug that caused install to attempt installing *.el? files
  into / in the absence of emacs.

Beside this, the handling of output from processes spawned by
Exec-Program-Wait attribute was improved to allow for equal sign without
surrounding whitespace (as in Session-Timeout=10).

The detection of Guile version in configure script was improved to
work with non-gnu versions of sed.

The install procedure no longer overwrites the existing dictionaries.


=============================================================================
Changes in Radius 0.96

* The format of raddb/config has changed a little.

To convert old raddb/config to new format, run scripts/config-conv.
It uses /usr/local as default prefix. If you have installed the
previous version of radius under a different prefix, run

	scripts/config-conv --prefix=PATH

The script will create a backup copy of the old config file in your
raddb directory (It will name it config~). Please, take a look at
converted file, and edit it to your liking.

For more information about the new format look in the texinfo
documentation (chapter Configuration files/config file).

* Slight changes to the format of raddb/dictionary.

Your old raddb/dictionary will be replaced automagically by
`make install'. The copy of your dictionary will be preserved
in file raddb/dictionary~.

* Radiusd is able to listen on multiple interfaces/ports.

By default, it listens for auth and account ports on all available
interfaces. To specify addresses/ports to listen on, use `listen'
statement in raddb/config file, e.g.:

auth {
	listen 10.10.10.1, 10.10.10.2:1812, localhost;
}

This statement is currently allowed only in `auth' and `acct' blocks

* Shared secrets of arbitrary length are allowed

* Passwords of arbitrary length are allowed

NOTE for MAX Ascend users: the ascend termserver IOS incorrectly
encodes passwords longer than 16 bytes. The workaround for this
bug is enabled by setting boolean variable broken_pass in the
flags column of the naslist file, e.g.:

# NAS Name		Short Name	Type		  Flags
#----------------	----------	----		---------------
my_ascend		my_ascend	max		broken_pass


* raddb/(naslist,nastypes): `arg' variable for method finger 

The variable allows for specifying the finger query string. It
defaults to %u, i.e. user name.

* raddb/naslist:

The word DEFAULT may be used in the first column to match any
NAS, not explicitely defined in the file. E.g.:

# NAS Name		Short Name	Type		  Flags
#----------------	----------	----		---------------
DEFAULT			other		

Logins from the DEFAULT NASes are not reported by raduse, neither
are they reflected in SNMP variables.

* raddb/realms: Special realm NOREALM is supported.

The realm is matched when the user did not specify any explicit realm
with his username.

* raddb/realms: Both authentication and accouting ports can be
specified.

The syntax is: servername[:auth-port[:acct-port]] (brackets mark
optional fields), e.g.:

#Realm name	Radius server
#----------	-------------
remote.net	radius.remote.net:1923:2023


* raddb/config: cntl statement is obsoleted.

* raddb/config: exec-program-group is obsoleted.

The group to be used when executing external programs is determined
from the /etc/passwd entry for exec-program-user.

* %C{Password} substitution returns plaintext password, instead of
  crypted one. Please, use with care.

* The default values may be provided for % substitutions.

The default values are used when the referenced attribute does not
exist. The syntax is similar to that of shell environment variables:

  %{Acct-Session-Time:-0}   -- return the value of Acct-Session-Time
                               attribute or 0 if it doesn't exist
  %{Acct-Session-Time:=0}   -- return the value of Acct-Session-Time.
                               If it doesn't exist, create it and assign
			       0 to it.
  %{User-Name:?not defined} -- return the value of User-Name. If it is
                               not present, issue diagnostic message
                               saying "User-Name: not defined" and
			       return string "not defined".

* The value of a reply pair can be computed at authentication time.

For example:

DEFAULT	Auth-Type = SQL
	Service-Type = Framed-User,
		Framed-IP-Address = "=get_ip_addr(10.10.10.1)"

In this case, the function get_ip_addr will be called with the argument
(IP) 10.10.10.1 and its return value will be assigned to Framed-IP-Address
pair. The function itself must be declared in raddb/rewrite.

In short, the syntax for evaluated pairs is:

	ATTR-NAME = "=FUNC-NAME(ARGS)"

where ATTR-NAME is the attribute name,
      FUNC-NAME is the name of the function, declared in raddb/rewrite 
      ARGS is a comma-separated list of arguments. Usual %C substitutions
      may be used as arguments. ARGS can be empty.

* Plaintext passwords are allowed in SQL database.

This allows to authenticate users via CHAP. To do so, user's profile
should contain the following check-pairs:

	Auth-Type = Local, Password-Location = SQL

* Compiling Guile support into the server.

The radiusd server can be compiled with Guile support, which allows
to further extend its functionality. The `guile' statement in raddb/config
controls the use of Guile functions. Please, take a look in
raddb/config.syntax for an example of how to use it. Complete description
is in texinfo documentation (Configuration files/config file/guile).

The Guile functions can be called on authentication or accounting
using the following special reply-pairs:

1. Scheme-Procedure. 
This attribute can be used in reply-pairs of raddb/users entry.
Its value is the name of Guile function to be called on
authentication. The function defininition should look like:

(define (auth-function-name request-list check-list reply-list)
  ...

The arguments are:

request-list -- The list of A/V pairs received in the request.
check-list   -- The check list from the user's profile entry (raddb/users).
reply-list   -- The reply list collected this far.

The authentication function (i.e., the one specified in Scheme-Procedure
pair) should return cons in the form:

	( BOOL . reply-pair-list )

where BOOL is #t if authentication succeeds, and #f otherwise.
      reply-pair-list is the list of A/V pairs to be added to the
      reply packet.

2. Scheme-Acct-Procedure.
This attribute can be used in reply-pairs of raddb/hints entry.
Its value is the name of Guile function to be called on
accounting. The function definition should look like:

(define (acct-function-name request-list)
  ...

The function should return #t on success and #f on failure.

An A/V list is represented as a scheme list of conses in the form

        ( ATTR-NAME-OR-NUMBER . ATTR-VALUE )

** Changes to SQL subsystem

*** Default MySQL and PostgreSQL database structures are provided.

To create the default radius database:
 1. Change to the subdirectory db/
 2. Edit file config.m4. Most of its contents is commented out, so
    uncomment anything that may be needed. Variables are:

    server   - SQL server name or IP address
    port     - port to connect to

	User credentials for creator of the database:
    CREATOR  - SQL username. This user must have create privileges.
    CREATOR_PASSWORD - SQL password.

	User credentials for the owner of the database:
    DB_USER  - SQL username.
    DB_PWD   - SQL password.
    (These must coincide with the values in raddb/sqlserver file)
 3. Depending on type of SQL server you are using, run either

	make mysql
    or
	make pgsql

 Alternately, you can create text files, describing the database structure
 by running `make mysql.struct' or `make pgsql.struct'

*** Check and reply pairs for user's profile can be retrieved from the 
    SQL database.

To do so, use `check_attr_query' and `reply_attr_query' statements in
the raddb/sqlserver file. `reply_attr_query' must return pairs
Attrname - Value, where Attrname is the name of attribute, as listed in
raddb/dictionary, Value is the value to be assigned to it.
Similarly, `check_attr_query' must return a list of triplets
Attrname - Value - Op, where Op means one of comparison operators,
allowed in check pairs: "=", "!=", "<", ">", "<=", ">=".

For example, given the following table:

CREATE TABLE attrib (
  user_name varchar(32) default '' not null,
  attr      char(32) default '' not null,
  value     char(128),
  op enum("=", "!=", "<", ">", "<=", ">=") default null
);

the queries will look like:

reply_attr_query  select attr,value \
                  from attrib \
                  where user_name='%u' \
                  and op is null

check_attr_query  select attr,value,op \
                  from attrib \
                  where user_name='%u' \
                  and op is not null

*** raddb/sqlserver: query_buffer_size clause is obsolete.

* radiusd can be compiled with support for both MySQL and PostgreSQL.

In this case, the actual database to be used is controlled by `interface'
statement in raddb/sqlserver file, e.g.:

interface mysql
or
interface postgres

* Client sub-package

Two client programs are provided: nas.scm and pam_radius.so. Specify the
switch --with-client to enable the client packages.

i. nas.scm is a guile program that allows to use a GNU/Linux box as a NAS.
It requires Guile and ppp-2.3.7 or higher. To use it, you will basically
need to do the following:

 1. Create links:
      ln -s $libexec/nas.scm /etc/ppp/ip-up
      ln -s $libexec/nas.scm /etc/ppp/ip-down
 2. Edit file $sysconfdir/raddb/nas.rc
 3. Configure your inittab and getty.

ii. pam_radius.so is an authentication module to be used in PAM.
The module understands following command line options:

  audit             -  Enable audit information
  debug[=LEVEL]     -  Enable debugging information
  use_authtok       -  Use authentication token passed from the previous module
                       in stack.
  confdir=PATH      -  Use PATH as a configuration directory
                       (defaults to $sysconfdir/etc/raddb).
  service_type=STR  -  Add Service-Type=STR to the auth packet. STR should
                       be a valid value, described in dictionary file.

The default configuration file, $sysconfdir/raddb/client.conf, is installed
by make install.

* Support for computable session timeout 

This is a framework for computing the session timeout in real time.
To use it, Radius must be compiled with Guile support. raddb/config
must contain:

guile {
	load "ttl.scm";
};

See the source file radscm/ttl.scm for the description of the module.


=============================================================================
NEWS for version 0.95

I. Changes to radiusd
----------------------
I.1. SNMP

Statistics MIBs have been moved to .iso.org.dod.internet.enterprises
subtree. MIB conceptual tables are supplied with bidirectional indexes.
E.g.: suppose user `jones' has logged in to NAS 10.100.0.1 on port 10.

  To get the login name and login date of the last login to port
10 on NAS 10.100.0.1 one would do:

	GetPDU <>.NASIndex.10.100.0.1 = 2
	GetPDU <>.StatPortIndex.2.10 = 18
	GetPDU <>.StatPortLastLoginName.18 = jones
	GetPDU <>.StatPortLastLoginTimestamp.18 = 986898520


  To get the NAS IP and NAS Port number for the entry 18 one would do

	GetPDU <>.StatPortNASIndex.18 = 2
	GetPDU <>.StatNASAddress.2 = 10.100.0.1
	GetPDU <>.StatPortID.18 = 10

In the examples above <> means
.iso.org.dod.internet.private.enterprises.gnu-radius.radiusStatistics
(.1.3.6.1.4.1.9163.3)


II. Changes to configuration files
-----------------------------------

A new attribute Log-Mode-Mask has been added. The attribute modifies
logging	mode for a given username/hint-group. Works like UNIX umask,
i.e. effective-log-mode = log_mode & ~Log-Mode-Mask.

III. Emacs modes for editing configuration files
-------------------------------------------------

The major modes for editing configuration files users, hints,
huntgroups and config are provided. The installation instructions
are in file elisp/README.


=============================================================================
NEWS for version 0.93

* Changes to radiusd

Added realm quota support. This feature allows to limit number of
users coming from a certain realm.

-i runtime option sets IP address radiusd binds to. It is useful in
case there are several network interfaces on the machine running radiusd.

The checkrad program is now gone. Its functionality is integrated in
the daemon itself. 

* Changes to configuration files

A special username, BEGIN or BEGIN%d, where %d is any decimal number,
may be used in raddb/users. It matches any username, just like DEFAULT
does, but BEGIN profiles are tried *before* any other profiles. Thus
they can be used to provide defaults for all other profiles. For example:

	BEGIN	NULL	Framed-IP-Address = "10.10.10.1+", Fall-Through = Yes

The effect of this statement is that Framed-IP-Address = "10.10.10.1+"
is added to reply pairs of a matching profile. Please note the use of
Fall-Through attribute. If it were not present, the matching
would stop at this entry.

Several internal attributes have been added. They are:

1. Match-Profile

The Match-Profile attribute can be used in check and reply lists of a
user profile. Its value is the name of another user's profile (target
profile). When Match-Profile is used in the check list, the incoming
packet will match this profile only if it matches the target profile.
In this case the reply pairs will be formed concatenating the reply
lists from both profiles.
When used in the reply list, this attribute causes the reply pairs
from the target profile to be appended to the reply from the current
profile if the target profile matches the incoming request.

2. Auth-Data

Auth-Data attribute can be used to provide additional authentication
data for SQL and PAM authentication methods. When used with PAM
authentication method it provides the same functionality as PAM-Auth
attribute.

* Querying terminal servers

GNU Radius version 0.94 is able to query a NAS about whether a given
user's session is active at the moment. Such querying takes place when
a user is trying to log in when the maximum number of open sessions
for his login has been reached. NASes can be queried using either
SNMP or finger protocols. Methods for querying any particular type
of NAS as well as functions to parse NAS output are defined in
configuration files raddb/nastype and raddb/rewrite. Thus if the files
shipped with the distribution do not provide support for some particular
type of NAS, such support can easily be added without having to recompile
radiusd. If you supply such additional support, the author would appreciate
sending him the patches so that they can be included in the subsequent
distributions.

The following describes briefly the basic idea.

Some definitions:
 1. *method* is the method to use for querying NAS. Currently it can be
    either SNMP or finger.
 2. *method arguments* are the arguments needed by the method. These are
    basic arguments, specific for a method, such as community and OID
    for SNMP and optional arguments, such as timeout, number of retries,
    etc.
 3. *type* is a symbolic name denoting the method along with the set of
    its arguments.
 4. *NAS-specific arguments* are those method arguments which are
    specific for a given NAS.
 5. *session specific data* are data uniquely identifying the user's
    session on a given NAS. This is a triplet (username,NAS-Port-id,
    Session-Id).

When it is necessary to check whether a session is actually active on
a NAS, radiusd first picks up the NAS type and NAS specific arguments
from the third and fourth columns of raddb/naslist file. Two special
NAS types are predefined. These are `true' and `false' types. Each of
them means that no querying should be done. Type `true' means that the
session is always deemed active, `false' means the session is always
deemed inactive. For any other type its method and arguments are looked 
up in raddb/nastypes database. Each record in the database consists of
three fields: type, method and argument list. When the matching record
is found, radiusd appends NAS specific arguments to the method argument
list. If an argument occurs in both lists, the value supplied by the NAS
specific list takes precedence over the one supplied by the method argument
list. After all these data is gathered radiusd finally queries the NAS.
For example, suppose the naslist contains the following:

# NAS Name		Short Name	Type		Checkrad flags
#----------------	----------	----		---------------
remote.dom.ain		REMOTE		unix		timeout=20,retries=2

and raddb/nastypes contains:

# Type     Method          Args
# ----     ------          ----
unix	   finger          function=check_unix,port=79,timeout=3

Then to check the activity of a session on the NAS `REMOTE', radiusd
will connect to it on port 79 using finger protocol. It will retry 2
times and will timeout in 20 seconds (not 3, because the value from the
naslist overrides this from nastypes). The function check_unix will
be used to parse the output from NAS.

Some words about the `function=' argument. It *must* be present in any
type definition. This argument specifies the function to be used for
parsing the NAS reply. If this function returns 1, it means the user
session is really active. The parsing of the NAS output continues while
the function returns 0. The function should be declared as:

	integer fun(string str, string name, integer pid, string sid)

The meaning of its arguments is:
	str          --  a line of NAS output
	name,pid,sid --  session specific data.

In the above example, assuming usual UNIX finger output format, the
function check_unix can be defined as:

	integer
	check_unix(string str, string name, integer pid, string sid)
	{
		return field(str, 1) == name &&
		       (integer) field(str, 3) == pid &&
	               field(str, 7) == sid;
	}


* SQL support

User's group can now be obtained from the SQL database. The group_query
statement in raddb/sqlserver file specifies the query to be used to
retrieve the group. The query may return multiple rows. The Group
attribute is matched when used in the check pair list of a hints
profile.

The acct_keepalive_query keyword specifies the query to be used
on the arrival of a keepalive packet.


=============================================================================
NEWS for version 0.93

* The Guile interface to Radius functions has been added. The program
  radscm (radius scheme) is actually a Guile Scheme interpreter with
  some special functions added.

* The radctl monitor is completely rewritten in scheme.

* The PostgreSQL support has been added. To configure radius with
  SQL accounting to a Postrgres server run

	./configure --enable-mysql=postgres


=============================================================================
NEWS for version 0.92.1

The major differences between this implementation of radius and
another existing ones are:

1.	Configurable MySQL support

You don't have to recompile anything if you change your database structure.
All queries are completely configurable.

2.	PostgreSQL support

3.	Fast lookup in the users database.

4.	Support for NASes that don't honor RFC.

Some NASes have peculiarities in sending Radius packets. These can
be overridden by using special rewriting language which allows to 
modify the contents of a packet on the fly. 

5. 	Configurable support for VSA pairs.

Vendor specific attributes can be added to dictionaries and Radius can
be told the ways of handling them without recompiling.


=========================================================================
Copyright information:

Copyright (C) 2002 Free Software Foundation, Inc.

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

Local variables:
mode: outline
paragraph-separate: "[	]*$"
end:
