.RE
.sp
..
-.TH rlm_passwd 5 "14 April 2004" "" "FreeRADIUS Module"
+.TH rlm_passwd 5 "20 January 2015" "" "FreeRADIUS Module"
.SH NAME
rlm_passwd \- FreeRADIUS Module
.SH DESCRIPTION
The \fIrlm_passwd\fP module provides authorization via files similar
in format to /etc/passwd.
.PP
-The \frlm_passwd\fP module allows you to retrieve any account
-information from any files with passwd-like format (/etc/passwd,
-/etc/group, smbpasswd, .htpasswd, etc). Every field of the file may
-be mapped to a RADIUS attribute, with one of the fields used as a
-key.
+This module allows you to retrieve any account information from any
+files with passwd-like format (/etc/passwd, /etc/group,
+smbpasswd, .htpasswd, etc). Every field of the file may be mapped to
+a RADIUS attribute, with one of the fields used as a key.
.PP
-The module reads the file when it initializes, and caches the data
-in memory. As a result, it does not support dynamic updates of the
-files (the server has to be HUP'd), but it is very fast, even for
-files with thousands of lines.
+The module reads the file when it initializes, and caches the data in
+memory. This makes it very fast, even for files with thousands of
+lines. To re-read the file the module will need to be reloaded with
+\fIradmin(8)\fP, or the server will need to be sent a SIGHUP, as
+dynamic updates are not supported.
.PP
+.SH CONFIGURATION
The configuration item(s):
-.IP filename
-The path to the file.
-.IP delimiter\ =\ ":"
-The character to use as a delimiter between fields. The default is
-":"
-.IP hash_size
-The size of the hashtable. If 0, then the passwords are not cached
-and the passwd file is parsed for every request. We do not recommend
-such a configuration. A larger hash_size means less probability of
-collision and faster search in hashtable. Having a hash_size in the range
-of 30-100% of the number of passwd file records is reasonable.
.IP allow_multiple_keys
If set to 'yes', and more than one record in file matches the request,
then the attributes from all records will be used. If set to 'no' (the
default) the module will warn about duplicated records.
-.IP ignore_nislike
-If set to 'yes', then all records from the file beginning with the '+'
-sign will be ignored. The default is 'no'.
+.IP delimiter\ =\ ":"
+The character to use as a delimiter between fields. The default is
+":"
+.IP filename
+The path to the file.
.IP format
The format of the fields in the file, given as an example line from
the file, with the content of the fields as the RADIUS attributes
-which the fields map to. The fields are seperated by the ':' character.
+which the fields map to. The fields are seperated by the ':' character
+in the configuration (no matter what is configured for the 'delimiter'
+option).
+.IP hash_size
+The size of the hash table. A larger value means less probability of a
+collision so records will be found faster, at the expense of greater
+memory usage. Having a hash_size in the range of 30-100% of the number
+of passwd file records is reasonable.
+.IP ignore_empty
+When set to "yes", the default, empty fields in the input will be
+skipped and the RADIUS attribute will not be added. By setting this
+value to "no", all attributes in the format list will always be added,
+even if they have no value.
+.IP ignore_nislike
+If set to 'yes', then all records from the file beginning with the '+'
+sign will be ignored. The default is 'no'.
.PP
-The key field is signified by being preceded with a '*' character,
-which indicates that the field has only one key, like the /etc/passwd
-file. The key field may instead be preceded with '*,', which
-indicates that the field has multiple possible keys, like the
-/etc/group file.
+.SH FORMAT
+The \fIformat\fP option controls how lines are read from the file, and
+which fields are mapped to which RADIUS attributes.
.PP
-The other fields signify RADIUS attributes which, by default, are
-added to the configuration items for a request.
+The key field is the field being searched for within the file. It is
+normally signified by being preceded with a '*' character, which
+indicates that the field has only one key, like the /etc/passwd file.
+The key field may instead be preceded with '*,', which indicates that
+the field has multiple possible comma-separated keys, such as when
+searching the /etc/group file.
.PP
-To add an attribute to the request (as though it was sent by the NAS),
-prefix the attribute name in the "format" string with the '~' character.
+The other fields signify RADIUS attributes. By default they will be
+added as a control attribute list.
+.PP
+To add an attribute to the RADIUS request (as though it had been sent
+by the NAS), prefix the attribute name in the "format" string with the
+'~' character.
+.PP
+To add an attribute to the RADIUS reply (to be sent back to the NAS),
+prefix the attribute name in the "format" string with the '='
+character.
.PP
-To add an attribute to the reply (to be sent back to the NAS) prefix
-the attribute name in the "format" string with the '=' character.
-.IP ignore_empty
-This configuration item defaults to "yes". If there is no value for
-the attribute, then the attribute is not added. By setting this value
-to "no", you can force the attribute to be added, even if there is no
-value.
-
.SH EXAMPLES
.DS
+format = "*User-Name:Crypt-Password:"
+.DE
+.IP
+For a file the looks similar to /etc/passwd. The first field,
+User-Name, is the key to look up in the file. When the record is
+found, a control attribute, 'Crypt-Password', will be added with the
+contents of the second field. (Note this will not work with shadow
+passwords.)
+.PP
+.DS
format = "My-Group:::*,User-Name"
.DE
.IP
Parse a file similar to the /etc/group file. An entry matches a
request when the name in a User-Name attribute exists in the
comma-seperated list of a line in the file. When an entry matches,
-a "My-Group" attribute will be created and added to the configuration
+a "My-Group" attribute will be created and added to the control
items for the request. The value of that attribute will be taken from
the first field of the matching line in the file.
.IP
fields do not map to any RADIUS attribute, and are therefore ignored.
.IP
For this example to work in practice, you will have to add the
-My-Group attribute to the dictionary file. See the dictionary manual
-page for details on how this may be done.
+My-Group attribute to the dictionary file. See \fIdictionary(5)\fP
+for details on how this may be done.
.PP
.DS
format = "~My-Group:::*,User-Name"
.IP
Similar to the previous entry, except the My-Group attribute is added
to the request, as though it was sent by the NAS.
+.PP
.SH SECTIONS
.BR authorize
.PP
.SH FILES
-.I /etc/raddb/radiusd.conf
+.I /etc/raddb/mods-available/passwd
.PP
.SH "SEE ALSO"
.BR radiusd (8),
-.BR radiusd.conf (5)
+.BR radiusd.conf (5),
+.BR radmin (8),
.BR dictionary (5),
+.BR rlm_unix (5)
.SH AUTHOR
-Alan DeKok <aland@freeradius.org>
+Alan DeKok <aland@freeradius.org>, Matthew Newton
+<matthew@newtoncomputing.co.uk>.
projects / freeradius.git / commitdiff