<!-- $Id: mod_radius.html,v 1.2 2002/12/18 18:27:57 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/contrib/mod_radius.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_radius</title>
</head>
<body bgcolor=white>
<hr><br>
<center>
<h2><b>ProFTPD module <code>mod_radius</code></b></h2>
</center>
<hr><br>
This module is contained in the <code>mod_radius.c</code> file for
ProFTPD 1.2, found <a href="http://www.castagalia.org/proftpd/">here</a>,
and is not compiled by default. Installation instructions are discussed
<a href="#Installation">here</a>.
<p>
This module is used to authenticate users using the <code>RADIUS</code>
protocol. It can also be used to do logging via <code>RADIUS</code> accounting
packets. A more in-depth discussion of the <a href="#Usage">usage</a> of this
module follows the configuration directive documentation.
<p>
The most current version of <code>mod_radius.c</code> can be found at:
<pre>
<a href="http://www.castaglia.org/proftpd/">http://www.castaglia.org/proftpd/</a>
</pre>
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Thanks</h2>
<p>
<i>2002-06-26</i>: Thanks to Josh Wilsdon <josh <i>at</i> wizard.ca>
for correcting a bad assumption in the code that caused data corruption under
some circumstances.
<p>
<i>2002-12-18</i>: Many thanks to Steffen Clausjuergens <stcl <i>at</i> clausjuergens.de> for helping to track down several bugs with accounting packets.
<h2>Directives</h2>
<ul>
<li><a href="#RadiusAcctServer">RadiusAcctServer</a>
<li><a href="#RadiusAuthServer">RadiusAuthServer</a>
<li><a href="#RadiusEngine">RadiusEngine</a>
<li><a href="#RadiusLog">RadiusLog</a>
<li><a href="#RadiusRealm">RadiusRealm</a>
<li><a href="#RadiusUserInfo">RadiusUserInfo</a>
</ul>
<hr>
<h2><a name="RadiusAcctServer">RadiusAcctServer</a></h2>
<strong>Syntax:</strong> RadiusAcctServer <em>server[:port] shared-secret [timeout]</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusAcctServer</code> is used to specify a RADIUS server to be
used for accounting. The <em>server</em> 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 <em>timeout</em> parameter is used
to tell <code>mod_radius</code> how long to wait for a response from the
server; it defaults to 30 seconds.
<p>
Multiple <code>RadiusAcctServer</code>s may be configured; each will be
tried, in order of appearance in the configuration file, until
that server times out or <code>mod_radius</code> receives a response.
<p>
If no <code>RadiusAcctServer</code>s are configured, <code>mod_radius</code>
will not use RADIUS for accounting.
<p>
See also: <a href="#RadiusAuthServer">RadiusAuthServer</a>
<p>
<hr>
<h2><a name="RadiusAuthServer">RadiusAuthServer</a></h2>
<strong>Syntax:</strong> RadiusAuthServer <em>server[:port] shared-secret [timeout]</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusAuthServer</code> is used to specify a RADIUS server to be
used for authentication. The <em>server</em> 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 <em>timeout</em> parameter is used
to tell <code>mod_radius</code> how long to wait for a response from the
server; it defaults to 30 seconds.
<p>
Multiple <code>RadiusAuthServer</code>s may be configured; each will be
tried, in order of appearance in the configuration file, until
that server times out or <code>mod_radius</code> receives a response.
<p>
If no <code>RadiusAuthServer</code>s are configured, <code>mod_radius</code>
will not use RADIUS for authentication.
<p>
See also: <a href="#RadiusAcctServer">RadiusAcctServer</a>
<p>
<hr>
<h2><a name="RadiusEngine">RadiusEngine</a></h2>
<strong>Syntax:</strong> RadiusEngine <em>on|off</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusEngine</code> directive enables or disables the module's
runtime RADIUS engine. If it is set to <em>off</em> this module does no
RADIUS authentication or accounting at all. Use this directive to disable the
module instead of commenting out all <code>mod_radius</code> directives.
<p>
<hr>
<h2><a name="RadiusLog">RadiusLog</a></h2>
<strong>Syntax:</strong> RadiusLog <em>file|"none"</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusLog</code> directive is used to a specify a log file for
<code>mod_radius</code> reporting and debugging, and can be done a per-server
basis. The <em>file</em> parameter must be the full path to the file to use for
logging. Note that this path must <b>not</b> be to a world-writeable
directory and, unless <code>AllowLogSymlinks</code> is explicitly set to
<em>on</em> (generally a bad idea), the path must <b>not</b> be a symbolic
link.
<p>
If <em>file</em> is "none", no logging will be done at all; this
setting can be used to override a <code>RadiusLog</code> setting inherited from
a <code><Global></code> context.
<p>
<hr>
<h2><a name="RadiusRealm">RadiusRealm</a></h2>
<strong>Syntax:</strong> RadiusRealm <em>realm</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusRealm</code> directive configures a <em>realm</em> string
that will be added to the username in the constructed RADIUS packets.
<p>
Example:
<pre>
RadiusRealm .castaglia.org
</pre>
<p>
<hr>
<h2><a name="RadiusUserInfo">RadiusUserInfo</a></h2>
<strong>Syntax:</strong> RadiusUserInfo <em>uid gid home shell [suppl-group-names suppl-group-ids]</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_radius<br>
<strong>Compatibility:</strong> 1.2.5rc2 and later
<p>
The <code>RadiusUserInfo</code> directive is used to configure login
information used for every user authenticated via RADIUS. The optional
<em>suppl-group-names</em> and <em>suppl-group-ids</em> parameters are used
to specify supplemental group membership for each user; the number of names
and IDs must match if these parameters are used.
<p>
In order to support RADIUS servers that may use custom attributes in their
<code>Access-Accept</code> response packets to supply user information back
to the RADIUS client (<code>mod_radius</code> in this case), this directive
allows the following syntax for some of its parameters:
<pre>
$(<i>attribute-id</i>:<i>default-value</i>)
</pre>
where the enclosing <code>$()</code> signals that the parameter is to
be supplied by the RADIUS server, <code><i>attribute-id</i></code> is the
custom attribute ID for which to search in the response packet, and
<code><i>default-value</i></code> is the value to use in case the requested
attribute is not present in the response packet. This syntax is not
supported for the <em>suppl-group-names</em> or <em>suppl-group-ids</em>
parameters.
<p>
If <code>RadiusUserInfo</code> is not used, <code>mod_radius</code> 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 (<i>e.g.</i> <code>/etc/passwd</code>,
<code>AuthUserFile</code>s, MySQL tables, etc).
<p>
<hr><br>
<h2><a name="Usage">Usage</a></h2>
Strong authentication is in demand for Internet services. For many, this
means using the <b>RADIUS</b> (<b>R</b>emote <b>A</b>uthentication
<b>D</b>ial-<b>I</b>n <b>U</b>ser <b>S</b>ervice) protocol.
<p>
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, <b><i>do not</i></b> have your authenticating RADIUS servers exposed
to the Internet; keep them protected within your LAN. Second, it is
<i>highly recommended</i> to use separate RADIUS servers for each of your
services.
<p>
<b>RADIUS Authentication</b><br>
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 <code>proftpd</code> 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 <code>RadiusUserInfo</code> directive is meant to be
used to address this issue, to provide the missing information.
<p>
In those cases where the RADIUS servers <i>can</i> provide that additional
login information, via custom attributes, the <code>RadiusUserInfo</code>
directive can also be used obtain that information as well.
<p>
<b>RADIUS Accounting</b><br>
While RADIUS is primarily used for authentication, the protocol also allows
for accounting of user activities. The <code>mod_radius</code> module
makes use of this ability, using RADIUS accounting packets to transmit the
following data:
<ul>
<li><b>Acct-Authentic</b>: How the user was authenticated (<i>e.g.</i>
locally, or via RADIUS)<br>
</li>
<br>
<li><b>Acct-Session-Id</b>: The process ID of the FTP session<br>
</li>
<br>
<li><b>Acct-Session-Time</b>: The duration of the FTP session, in seconds<br>
</li>
<br>
<li><b>Acct-Input-Octets</b>: The number of bytes uploaded (includes
appending to files)<br>
</li>
<br>
<li><b>Acct-Output-Octets</b>: The number of bytes downloaded<br>
</li>
<br>
</ul>
Merely configuring a <code>RadiusAcctServer</code> enables the module's
accounting capabilities.
<p>
<b>Common Attributes</b><br>
The following RADIUS attributes are sent with every RADIUS packet generated
by <code>mod_radius</code>:
<ul>
<li><b>User-Name</b>: The name of the logging-in user<br>
</li>
<br>
<li><b>NAS-Identifier</b>: Always "ftp"<br>
</li>
<br>
<li><b>NAS-IP-Address</b>: IP address of FTP server<br>
</li>
<br>
<li><b>NAS-Port</b>: Port of FTP server<br>
</li>
<br>
<li><b>NAS-Port-Type</b>: Always <code>Virtual</code>.<br>
</li>
<br>
<li><b>Calling-Station-Id</b>: IP address of connecting FTP client<br>
</li>
<br>
</ul>
<p>
<hr><br>
<h2><a name="Installation">Installation</a></h2>
To install <code>mod_radius</code>, copy the <code>mod_radius.c</code> file into
<pre>
<i>proftpd-dir</i>/contrib/
</pre>
after unpacking the latest proftpd-1.2 source code. Then follow the usual
steps for using third-party modules in proftpd:
<pre>
./configure --with-modules=mod_radius
make
make install
</pre>
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2002/12/18 18:27:57 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2000-2002 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
