trAvis - MANAGER

Edit File: Radius.html

<html>
<head>
<title>ProFTPD mini-HOWTO - ProFTPD and RADIUS</title>
</head>

<hr>
<center><h2>ProFTPD and RADIUS</h2></center>
<hr>
Some sites use the <a href="http://en.wikipedia.org/wiki/RADIUS">RADIUS</a>
protocol for authenticating users. For these sites, there is the
<a href="../contrib/mod_radius.html"><code>mod_radius</code></a> ProFTPD module.

Common Configurations
First, let's start with the most basic <code>mod_radius</code> configuration,
where we want to use the RADIUS server only for validating the user's
password:
<pre>
 &lt;IfModule mod_radius.c&gt;
 AuthOrder mod_radius.c mod_auth_unix.c mod_auth_file.c

RadiusEngine on
 RadiusAuthServer localhost:1812 testing123 5
 RadiusLog /etc/proftpd/radius.log
 &lt;/IfModule&gt;
</pre>
Here, we have told <code>mod_radius</code> the IP address of the RADIUS
server via the <a href="../contrib/mod_radius.html#RadiusAuthServer"><code>RadiusAuthServer</code></a> directive, which includes the port, shared secret,
and default timeout value (in seconds).

Since this configuration only uses the RADIUS server for validating the
password, we still need to get the user's UID, GID, home directory, group
membership, etc from somewhere. Thus we need the <code>AuthOrder</code>
directive to tell <code>proftpd</code> to use the
<a href="../modules/mod_auth_unix.html"><code>mod_auth_unix</code></a> and
<a href="../modules/mod_auth_file.html"><code>mod_auth_file</code></a> modules
as well.

Using the above configuration, when a client connects and sends the
<code>USER</code> and <code>PASS</code> FTP commands, the
<code>mod_radius</code> module will send an <code>Access-Request</code> RADIUS
packet to the RADIUS server, which will include the following attributes:
<pre>
 Service-Type 8 (i.e. Authenticate-Only)
 User-Name username
 User-Password password
 NAS-Identifier "ftp"
 NAS-IP-Address (or NAS-IPv6-Address) server-ip-address
 NAS-Port server-port
 NAS-Port-Type 5 (i.e. Virtual)
 Calling-Station-Id client-ip-address
</pre>
If the RADIUS server responds with an <code>Access-Accept</code> packet, then
the login succeeds, and the FTP session is establish. If, on the other hand,
the RADIUS server responds with <code>Access-Reject</code>, the login fails.
(The <code>mod_radius</code> module does not currently support the
<code>Access-Challenge</code> packet type.)

Now, let's examine a slightly more complex configuration, which enables the
use of RADIUS accounting:
<pre>
 &lt;IfModule mod_radius.c&gt;
 AuthOrder mod_radius.c mod_auth_unix.c mod_auth_file.c

RadiusEngine on
 RadiusAuthServer localhost:1812 testing123 5
 RadiusAcctServer localhost:1813 testing123 5
 RadiusLog /etc/proftpd/radius.log
 &lt;/IfModule&gt;
</pre>
The additional directive here is the <a href="../contrib/mod_radius.html#RadiusAcctServer"><code>RadiusAcctSerer</code></a> directive, which is quite similar
to the <code>RadiusAuthServer</code> directive. The use of the
<code>RadiusAcctServer</code> directive instructs <code>mod_radius</code> to
use RADIUS accounting.

With this configuration, <code>mod_radius</code> will do the same as before.
In addition, once the login has succeeded, <code>mod_radius</code> will send
an <code>Accounting-Request</code> packet to the RADIUS accounting server
which includes:
<pre>
 User-Name username
 Acct-Status-Type 1 (i.e. Start)
 Acct-Session-Id session-pid
 Acct-Authentic 1 (i.e. Local)
</pre>
Then, when the client disconnects, <code>mod_radius</code> sends another
<code>Accounting-Request</code> packet, this time with a lot of information
about the just-ended session:
<pre>
 User-Name username
 Acct-Status-Type 2 (i.e. Stop)
 Acct-Session-Id session-pid
 Acct-Authentic 1 (i.e. Local)
 Acct-Session-Time session-duration
 Acct-Input-Octets bytes-in
 Acct-Output-Octets bytes-out
</pre>

The above configurations are the most common, as RADIUS is normally used
only as way of checking whether a client should be allowed to connect, based
on username/password.

Sophisticated Configurations
It is possible to use RADIUS as the sole means of user authentication, rather
than just validating passwords. The <code>mod_radius</code> configuration
to do so would look like:
<pre>
 &lt;IfModule mod_radius.c&gt;
 AuthOrder mod_radius.c

RadiusEngine on
    RadiusAuthServer localhost:1812 testing123 5
    RadiusAcctServer localhost:1813 testing123 5
    RadiusLog /etc/proftpd/radius.log

# Use RADIUS Vendor-Specific Attributes (VSAs) for user details 
 RadiusVendor Unix 4
 RadiusUserInfo $(10:1000) $(11:1000) $(12:/tmp) $(13:/bin/bash)
 RadiusGroupInfo $(14:users,ftpd) $(15:500,501)
 &lt;/IfModule&gt;
</pre>
The key difference here is the use of the <a href="../contrib/mod_radius.html#RadiusUserInfo"><code>RadiusUserInfo</code></a> directive. Its appearance within
the configuration is what instructs <code>mod_radius</code> to do more than
just password validation. The <code>RadiusUserInfo</code> and <a href="../contrib/mod_radius.html#RadiusGroupInfo"><code>RadiusGroupInfo</code></a> directives
together tell <code>mod_radius</code> where to find the necessary information
about a user, such as the UID, GID, home directory, group membership,
etc in the response packets from the RADIUS server.

To let the RADIUS server know that we are expecting it do more than just
validate the password, the <code>Access-Request</code> packet will use a
different <code>Service-Type</code> attribute. Now the packet will look like:
<pre>
 Service-Type 1 (i.e. Login)
 User-Name username
 User-Password password
 NAS-Identifier "ftp"
 NAS-IP-Address (or NAS-IPv6-Address) server-ip-address
 NAS-Port server-port
 NAS-Port-Type 5 (i.e. Virtual)
 Calling-Station-Id client-ip-address
</pre>

Upon receiving the <code>Access-Accept</code> packet, <code>mod_radius</code>
will now look for specific <a href="http://en.wikipedia.org/wiki/RADIUS#Attribute_value_pairs">attributes</a>, bearing user details, within the packet.
What attributes does it look for? Answer: <a href="http://en.wikipedia.org/wiki/RADIUS#Vendor-specific_attributes">Vendor-Specific Attributes</a> (commonly
called "VSAs").

Every VSA is prefixed with a vendor ID, followed by an attribute ID/value which
are defined by that vendor. For example, Cisco has a vendor ID of 9,
Microsoft has a vendor ID of 311, and "Unix" has a vendor ID of 4. (For the
curious, these vendor IDs, per <a href="http://tools.ietf.org/search/rfc2865#section-5.26">RFC 2865, Section 5.26</a>, come from the <a href="http://www.iana.org/assignments/enterprise-numbers/enterprise-numbers">IANA Enterprise Numbers</a> registry.)

With this background, we can explain the <code>RadiusUserInfo</code> and
<code>RadiusGroupInfo</code> directives in detail. Notice that we tell
<code>mod_radius</code> the vendor ID to look for, using the
<a href="../contrib/mod_radius.html#RadiusVendor"><code>RadiusVendor</code></a>
directive:
</pre>
 RadiusVendor Unix 4
</pre>
The above is actually not necessary; <code>mod_radius</code> will look for
VSAs for vendor ID 4 (Unix) by default. It is useful, though, to make it
explicitly visible in the configuration.

Let's now see just what the <code>RadiusUserInfo</code> parameters are doing:
<pre>
 RadiusUserInfo $(10:1000) $(11:1000) $(12:/tmp) $(13:/bin/bash)
</pre>
In order for <code>proftpd</code> to log a user in, it needs to know that
user's UID, GID, home directory, and shell. And the <code>RadiusUserInfo</code>
parameters say where to find those values, in that order.

For UIDs, &quot;$(10:1000)&quot; says to look for a vendor-specific
attribute ID of 10. If we find such an attribute, use the attribute value as
the UID. Otherwise, use 1000 as the UID for the user logging in.

For GIDs, &quot;$(11:1000)&quot; says to look for a vendor-specific
attribute ID of 11. If we find such an attribute, use the attribute value as
the GID. Otherwise, use 1000 as the GID for the user logging in.

For home directories, &quot;$(12:/tmp)&quot; says to look for a
vendor-specific attribute ID of 12. If we find such an attribute, use the
attribute value as the home directory. Otherwise, use /tmp as the
home directory for the user logging in.

And for the shell, &quot;$(13:/bin/bash)&quot; says to look for a
vendor-specific attribute ID of 13. If we find such an attribute, use the
attribute value as the shell. Otherwise, use /bin/bash as the shell
for the user logging in.

The <code>RadiusGroupInfo</code> directive is very similar: it tells
<code>mod_radius</code> which VSAs will contain the group membership, both
in terms of group IDs and group names, for the logging in user:
<pre>
 RadiusGroupInfo $(14:users,ftpd) $(15:500,501)
</pre>

For group names, &quot;$(14:users,ftpd)&quot; says to look for a
vendor-specific attribute ID of 14. If we find such an attribute, use the
attribute value as the comma-separated list of supplemental group names.
Otherwise, use users,ftpd as the group names for the user logging in.

For group IDs, &quot;$(15:500,501)&quot; says to look for a
vendor-specific attribute ID of 15. If we find such an attribute, use the
attribute value as the comma-separated list of supplemental group IDs.
Otherwise, use 500,501 as the group IDs for the user logging in.

FreeRADIUS Configuration 
To help demonstrate how you would configure and use VSAs, I will show the
<a href="http://freeradius.org/">FreeRADIUS</a> configuration that I used for
development and testing.

Here is the FreeRADIUS <code>dictionary.unix</code> file I used (slightly
modified from the stock <code>dictionary.unix</code> file distributed with
FreeRADIUS); this file defines the attributes supported for the "Unix"
vendor:
<pre>
 VENDOR Unix 4

BEGIN-VENDOR Unix

ATTRIBUTE       Unix-User-UID            10      integer
  ATTRIBUTE       Unix-User-GID            11      integer
  ATTRIBUTE       Unix-User-Home           12      string
  ATTRIBUTE       Unix-User-Shell          13      string
  ATTRIBUTE       Unix-User-Group-Names    14      string
  ATTRIBUTE       Unix-User-Group-Ids      15      string

END-VENDOR Unix
</pre>
You can see how:
<pre>
 VENDOR Unix 4
</pre>
here corresponds to the <code>mod_radius</code> configuration line:
<pre>
 RadiusVendor Unix 4
</pre>

The following attribute IDs are what we use in our <code>mod_radius</code>
directives:
<pre>
 ATTRIBUTE Unix-User-UID 10 integer
 ATTRIBUTE Unix-User-GID 11 integer
 ATTRIBUTE Unix-User-Home 12 string
 ATTRIBUTE Unix-User-Shell 13 string
</pre>
which match up with our <code>RadiusUserInfo</code> parameters:
<pre>
 RadiusUserInfo $(10:1000) $(11:1000) $(12:/tmp) $(13:/bin/bash)
</pre>

Similarly for the group membership attributes, <code>dictionary.unix</code>
has:
<pre>
 ATTRIBUTE Unix-User-Group-Names 14 string
 ATTRIBUTE Unix-User-Group-Ids 15 string
</pre>
and our <code>RadiusGroupInfo</code> parameters are:
<pre>
 RadiusGroupInfo $(14:users,ftpd) $(15:500,501)
</pre>

Note that only the IDs (numbers) for attributes are used in the RADIUS packets
sent between clients/servers. The attribute names are to make the configuration
and logging more human-readable.

Now, in order to tell FreeRADIUS that we want it to include those
VSAs in its <code>Access-Accept</code> packet back to <code>mod_radius</code>,
we have to modify the FreeRADIUS <code>users</code> file, like so:
<pre>
 DEFAULT Auth-Type := System
 Unix-User-UID := 500,
 Unix-User-GID := 500,
 Unix-User-Home := "/home/tj",
 Unix-User-Shell := "/bin/bash",
 Unix-User-Group-Names := "radius,ftpd",
 Unix-User-Group-Ids := "200,501",
 Fall-Through = 1
</pre>
See the FreeRADIUS documentation for the <code>users</code> file format in
order to learn how to configure different UID/GID/home/group values for each
user in that file.

Obtaining Quota Information via RADIUS 
If you use the <a href="../contrib/mod_quotatab.html"><code>mod_quotatab</code></a> module for quota support in <code>proftpd</code>, and you use the
<code>mod_radius</code> module for authentication, then you might also be
interesting in getting your quota information from your RADIUS server, much
like you can get user details from the RADIUS server.

The mechanism is identical that used for user details, i.e.
vendor-specific attributes (VSAs). Assuming that you are using FreeRADIUS,
you would add the following to your FreeRADIUS <code>dictionary.unix</code>
file:
<pre>
 ATTRIBUTE Unix-FTP-Quota-Per-Session 106 string
 ATTRIBUTE Unix-FTP-Quota-Limit-Type 107 string
 ATTRIBUTE Unix-FTP-Quota-Bytes-Upload 108 string
 ATTRIBUTE Unix-FTP-Quota-Bytes-Download 109 string
 ATTRIBUTE Unix-FTP-Quota-Bytes-Transfer 110 string
 ATTRIBUTE Unix-FTP-Quota-Files-Upload 111 string
 ATTRIBUTE Unix-FTP-Quota-Files-Download 112 string
 ATTRIBUTE Unix-FTP-Quota-Files-Transfer 113 string
</pre>
and in the FreeRADIUS <code>users</code> file (assuming the above user-related
attributes as well):
<pre>
 DEFAULT Auth-Type := System
 Unix-User-UID := 500,
 Unix-User-GID := 500,
 Unix-User-Home := "/home/tj",
 Unix-User-Shell := "/bin/bash",
 Unix-User-Group-Names := "radius,ftpd",
 Unix-User-Group-Ids := "200,501",
 Unix-FTP-Quota-Per-Session := "false",
 Unix-FTP-Quota-Limit-Type := "soft",
 Unix-FTP-Quota-Bytes-Upload := "1.1",
 Unix-FTP-Quota-Bytes-Download := "2.2",
 Unix-FTP-Quota-Bytes-Transfer := "3.3",
 Unix-FTP-Quota-Files-Upload := "4",
 Unix-FTP-Quota-Files-Download := "5",
 Unix-FTP-Quota-Files-Transfer := "6",
 Fall-Through = 1
</pre>
and then, to tell <code>mod_radius</code> that it should look for quota-related
VSAs in the <code>Access-Accept</code> RADIUS packet, there is the aptly-named
<a href="../contrib/mod_radius.html#RadiusQuotaInfo"><code>RadiusQuotaInfo</code></a> directive:
<pre>
 RadiusQuotaInfo $(106:false) $(107:hard) $(108:40.0) $(109:0.0) $(110:0.0) $(111:0) $(112:0) $(113:0)
</pre>

<a name="FAQ">
Frequently Asked Questions 
Question: Do I have to configure my RADIUS server to
return VSAs in order to use <code>mod_radius</code>? 
Answer: No. As shown above, <code>mod_radius</code>
is usually used just for validating user credentials.

It is also possible to use only <code>mod_radius</code> for user authentication,
without needing VSAs. For example, using a configuration like this will
do what you need:
<pre>
 &lt;IfModule mod_radius.c&gt;
 AuthOrder mod_radius.c

RadiusEngine on
    RadiusAuthServer localhost:1812 testing123 5
    RadiusAcctServer localhost:1813 testing123 5
    RadiusLog /etc/proftpd/radius.log

RadiusUserInfo 1000 1000 /tmp /bin/bash
 RadiusGroupInfo ftpd 1000
 &lt;/IfModule&gt;
</pre>
Notice how the <code>RadiusUserInfo</code> and <code>RadiusGroupInfo</code>
directives do not use the "$(N:M)" syntax? That means that
we are not telling <code>mod_radius</code> what vendor ID and attribute IDs
to look for. Instead, we are telling <code>mod_radius</code> to always
use the configured UID, GID, home directory, shell, group membership values.

Note that this means that all of your logged-in users will have the
exact same UID, GID, and home directory. For some sites, this is ideal. Other
sites need to have different UID/GID/homes for each users, and thus they will
use the VSA support.

<a name="RadiusAndSSH">
Question: Can I use <code>mod_radius</code> for SFTP
connections? 
Answer: Yes. However, there are some caveats. The
main issue that clients which want to use SSH publickey authentication
cannot use RADIUS, since the RADIUS protocol does not define any means
of conveying the public key information from the connecting client to the
RADIUS server. So only password-based SSH authentication can be supported
using <code>mod_radius</code>.

<hr>
Last Updated: $Date: 2014-01-27 01:28:21 $ 
<hr>

</body>
</html>