ProFTPD module mod_radius

## ProFTPD module `mod_radius`

This module is contained in the `mod_radius.c` file for ProFTPD 1.2, and is not compiled by default. Installation instructions are discussed here.

This module is used to authenticate users using the `RADIUS` protocol. It can also be used to do logging via `RADIUS` accounting packets. A more in-depth discussion of the usage of this module follows the configuration directive documentation.

The most current version of `mod_radius` is distributed with the ProFTPD source code.

## Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

## Thanks

2002-06-26: Thanks to Josh Wilsdon <josh at wizard.ca> for correcting a bad assumption in the code that caused data corruption under some circumstances.

2002-12-18: Many thanks to Steffen Clausjuergens <stcl at clausjuergens.de> for helping to track down several bugs with accounting packets.

## Directives

- RadiusAcctServer
- RadiusAuthServer
- RadiusEngine
- RadiusLog
- RadiusRealm
- RadiusUserInfo

## RadiusAcctServer

Syntax: RadiusAcctServer server[:port] shared-secret [timeout]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusAcctServer` is used to specify a RADIUS server to be used for accounting. The server parameter may be either an IP address or a DNS hostname. If not specified, the port used will be the IANA-registered 1813. The optional timeout parameter is used to tell `mod_radius` how long to wait for a response from the server; it defaults to 30 seconds.

Multiple `RadiusAcctServer`s may be configured; each will be tried, in order of appearance in the configuration file, until that server times out or `mod_radius` receives a response.

If no `RadiusAcctServer`s are configured, `mod_radius` will not use RADIUS for accounting.

See also: RadiusAuthServer

## RadiusAuthServer

Syntax: RadiusAuthServer server[:port] shared-secret [timeout]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusAuthServer` is used to specify a RADIUS server to be used for authentication. The server parameter may be either an IP address or a DNS hostname. If not specified, the port used will be the IANA-registered 1812. The optional timeout parameter is used to tell `mod_radius` how long to wait for a response from the server; it defaults to 30 seconds.

Multiple `RadiusAuthServer`s may be configured; each will be tried, in order of appearance in the configuration file, until that server times out or `mod_radius` receives a response, either "accept" or "reject".

If no `RadiusAuthServer`s are configured, `mod_radius` will not use RADIUS for authentication.

See also: RadiusAcctServer

## RadiusEngine

Syntax: RadiusEngine on|off
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusEngine` directive enables or disables the module's runtime RADIUS engine. If it is set to off this module does no RADIUS authentication or accounting at all. Use this directive to disable the module instead of commenting out all `mod_radius` directives.

## RadiusLog

Syntax: RadiusLog file|"none"
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusLog` directive is used to a specify a log file for `mod_radius` reporting and debugging, and can be done a per-server basis. The file parameter must be the full path to the file to use for logging. Note that this path must not be to a world-writeable directory and, unless `AllowLogSymlinks` is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

If file is "none", no logging will be done at all; this setting can be used to override a `RadiusLog` setting inherited from a `<Global>` context.

## RadiusRealm

Syntax: RadiusRealm realm
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusRealm` directive configures a realm string that will be added to the username in the constructed RADIUS packets.

Example:

      RadiusRealm .castaglia.org

## RadiusUserInfo

Syntax: RadiusUserInfo uid gid home shell [suppl-group-names suppl-group-ids]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_radius
Compatibility: 1.2.5rc2 and later

The `RadiusUserInfo` directive is used to configure login information used for every user authenticated via RADIUS. The optional suppl-group-names and suppl-group-ids parameters are used to specify supplemental group membership for each user; the number of names and IDs must match if these parameters are used.

In order to support RADIUS servers that may use custom attributes in their `Access-Accept` response packets to supply user information back to the RADIUS client (`mod_radius` in this case), this directive allows the following syntax for some of its parameters:

      $(attribute-id:default-value)

where the enclosing `$()` signals that the parameter is to be supplied by the RADIUS server, `attribute-id` is the custom attribute ID for which to search in the response packet, and `default-value` is the value to use in case the requested attribute is not present in the response packet. This syntax is not supported for the suppl-group-names or suppl-group-ids parameters.

Note that some RADIUS vendors may attempt to use attributes that violate RFC by attempting to use an attribute `type` that is larger than 255. Such vendor implementations are not, and should not be, supported.

If `RadiusUserInfo` is not used, `mod_radius` will perform pure "yes/no" authentication only, in the style of PAM. The information that would have been configured via this directive will be pulled from other sources (e.g. `/etc/passwd`, `AuthUserFile`s, MySQL tables, etc).

## Usage

Strong authentication is in demand for Internet services. For many, this means using the RADIUS (Remote Authentication Dial-In User Service) protocol.

However, there are caveats to using RADIUS for authentication. RADIUS packets are sent in the clear, which means that they can easily be sniffed. First, do not have your authenticating RADIUS servers exposed to the Internet; keep them protected within your LAN. Second, it is highly recommended to use separate RADIUS servers for each of your services.

RADIUS Authentication
The RADIUS protocol can be used for answering the question "Should this user be allowed to login?" However, the "yes/no" answer is not everything that `proftpd` needs to log a user in; the server also requires the UID and GID to use for the authenticated user, home directory, and shell. This information is usually not available from the RADIUS servers, which means that using RADIUS to provide all the necessary login information can be problematic. The `RadiusUserInfo` directive is meant to be used to address this issue, to provide the missing information.

In those cases where the RADIUS servers can provide that additional login information, via custom attributes, the `RadiusUserInfo` directive can also be used obtain that information as well.

RADIUS Accounting
While RADIUS is primarily used for authentication, the protocol also allows for accounting of user activities. The `mod_radius` module makes use of this ability, using RADIUS accounting packets to transmit the following data:

- Acct-Authentic: How the user was authenticated (e.g. locally, or via RADIUS)
- Acct-Session-Id: The process ID of the FTP session
- Acct-Session-Time: The duration of the FTP session, in seconds
- Acct-Input-Octets: The number of bytes uploaded (includes appending to files)
- Acct-Output-Octets: The number of bytes downloaded

Merely configuring a `RadiusAcctServer` enables the module's accounting capabilities.

Common Attributes
The following RADIUS attributes are sent with every RADIUS packet generated by `mod_radius`:

- User-Name: The name of the logging-in user
- NAS-Identifier: Always "ftp"
- NAS-IP-Address: IP address of FTP server
- NAS-Port: Port of FTP server
- NAS-Port-Type: Always `Virtual`.
- Calling-Station-Id: IP address of connecting FTP client

## Installation

The `mod_radius` module is distributed with ProFTPD. Simply follow the normal steps for using third-party modules in proftpd:

      ./configure --with-modules=mod_radius
      make
      make install

Author: $Author: castaglia $
Last Updated: $Date: 2004/04/16 00:19:34 $

© Copyright 2000-2002 TJ Saunders
All Rights Reserved