man/man8/radiusd.8

   1 .TH RADIUSD 8 "08 Mar 2009" "" "FreeRADIUS Daemon"
   2 .SH NAME
   3 radiusd - Authentication, Authorization and Accounting server
   4 .SH SYNOPSIS
   5 .B radiusd
   6 .RB [ \-C ]
   7 .RB [ \-d
   8 .IR config_directory ]
   9 .RB [ \-f ]
  10 .RB [ \-i
  11 .IR ip-address ]
  12 .RB [ \-n
  13 .IR name ]
  14 .RB [ \-p
  15 .IR port ]
  16 .RB [ \-s ]
  17 .RB [ \-v ]
  18 .RB [ \-x ]
  19 .RB [ \-X ]
  20 .SH DESCRIPTION
  21 FreeRADIUS is a high-performance and highly configurable RADIUS
  22 server.  It supports many database back-ends such as flat-text files,
  23 SQL, LDAP, Perl, Python, etc.  It also supports many authentication
  24 protocols such as PAP, CHAP, MS-CHAP(v2), HTTP Digest, and EAP
  25 (EAP-MD5, EAP-TLS, PEAP, EAP-TTLS, EAP-SIM, etc.).
  26
  27 It also has experimental support for Cisco's VLAN Query Protocol
  28 (VMPS) and DHCP.
  29
  30 Please read the DEBUGGING section below.  It contains instructions
  31 for quickly configuring the server for your local system.
  32 .SH OPTIONS
  33 The following command-line options are accepted by the server.
  34 .IP \-C
  35 Check the configuration and exit immediately.  If there is a problem
  36 reading the configuration, then the server will exit with a non-zero
  37 status code.  If the configuration appears to be acceptable, then the
  38 server will exit with a zero status code.
  39
  40 Note that there are many limitations to this check.  Due to the
  41 complexities involved in \fIalmost\fP starting a RADIUS server, these
  42 checks are necessarily incomplete.  The server can return a zero
  43 status code when run with -C, but may still exit with an error when
  44 run normally.
  45
  46 See the output of
  47 .B "radiusd -XC"
  48 for an informative list of which modules are checked for correct
  49 configuration, and which modules are skipped, and therefore not checked.
  50 .IP "\-d \fIconfig directory\fP"
  51 Defaults to \fI/etc/raddb\fP. \fBRadiusd\fP looks here for its configuration
  52 files such as the \fIdictionary\fP and the \fIusers\fP files.
  53 .IP "\-i \fIip-address\fP"
  54 Defines which IP address that the server uses for sending and
  55 receiving packets.
  56
  57 If this command-line option is given, then the "bind_address" and all
  58 "listen{}" entries in \fIradiusd.conf\fP are ignored.
  59
  60 This option MUST be used in conjunction with "-p".
  61 .IP \-f
  62 Do not fork, stay running as a foreground process.
  63 .IP "\-n \fIname\fP"
  64 Read \fIraddb/name.conf\fP instead of \fIraddb/radiusd.conf\fP.
  65 .IP "\-p \fIport\fP"
  66 Normally radiusd listens on the ports specified in \fI/etc/services\fP
  67 (radius and radacct). When this option is given, radiusd listens on
  68 the specified port for authentication requests and on the specified
  69 port +1 for accounting requests.
  70
  71 If this command-line option is given, then the "port" directive in
  72 \fIradiusd.conf\fP is ignored.
  73
  74 This option MUST be used in conjunction with "-i".
  75 .IP \-s
  76 Run in "single server" mode.  The server normally runs with multiple
  77 threads and/or processes, which can lower its response time to
  78 requests.  Some systems have issues with threading, however, so
  79 running in "single server" mode may help to address those issues.  In
  80 single server mode, the server will also not "daemonize"
  81 (auto-background) itself.
  82 .IP \-v
  83 Print server version information and exit.
  84 .IP \-X
  85 Debugging mode.  Equivalent to "-sfxx -l stdout".  When trying to
  86 understand how the server works, ALWAYS run it with "radiusd -X".
  87 .IP \-x
  88 Finer-grained debug mode. In this mode the server will print details
  89 of every request on it's \fBstdout\fP output. You can specify this
  90 option multiple times (-x -x or -xx) to get more detailed output.
  91 .SH DEBUGGING
  92 The server can be difficult to configure correctly in systems with
  93 complex requirements.  We STRONGLY RECOMMEND proceeding via the
  94 following steps:
  95 .PP
  96 1) Always run the server in debugging mode (
  97 .B radiusd -X
  98 ).  We cannot emphasize this enough.  If you are not running the
  99 server in debugging mode, you \fIwill not\fP be able to see what is
 100 doing, and you \fIwill not\fP be able to correct any problems.
 101 .PP
 102 2) Change as little as possible in the default configuration files.
 103 The server contains a decade of experience with protocols, databases,
 104 and different systems.  Its default configuration is designed to work
 105 almost everywhere, and to do almost everything.
 106 .PP
 107 3) Make small changes to the configuration files, while testing each
 108 change as you make it.  If the change works, save a copy of the
 109 configuration, and make another change.  If the change doesn't work,
 110 debug it, and try to understand why it doesn't work.
 111 .PP
 112 If you begin by making large changes to the server configuration, it
 113 will never work, and you will never be able to debug it.
 114 .PP
 115 4) If you need to add a connection to a database FOO (e.g. LDAP or
 116 SQL), then:
 117 .PP
 118 .in +0.3i
 119 a) Edit raddb/modules/foo
 120 .br
 121 This file contains the default configuration for the module.  It
 122 contains comments describing what can be configured, and what those
 123 configuration entries mean.
 124 .br
 125 .br
 126 b) Edit raddb/sites-available/default
 127 .br
 128 This file contains the default policy for the server.  e.g. "enable
 129 CHAP, MS-CHAP, and EAP authentication".  Look in this file for all
 130 references to your module "foo".  Read the comments, and remove the
 131 leading hash '#' from the lines referencing the module.  This enables
 132 the module.
 133 .br
 134 .br
 135 c) Edit raddb/sites-available/inner-tunnel
 136 .br
 137 This file contains the default policy for the "tunneled" portion of
 138 certain EAP methods.  Perform the same kind of edits as above, for the
 139 "default" file..  If you are not using EAP (802.1X), then this step
 140 can be skipped.
 141 .br
 142 .br
 143 d) Start the server in debugging mode (
 144 .B radiusd -X
 145 ), and start testing.
 146 .in -0.3i
 147 .PP
 148 5) Ask questions on the mailing list
 149 (freeradius-users@lists.freeradius.org).  When asking questions,
 150 include the output from debugging mode (
 151 .B radiusd -X
 152 ).  This information will allow people to help you.  If you do not
 153 include it, the first response to your message will be "post the
 154 output of debug mode".
 155 .PP
 156 Ask questions earlier, rather than later.  If you cannot solve a
 157 problem in a day, ask a question on the mailing list.  Most questions
 158 have been seen before, and can be answered quickly.
 159 .SH BACKGROUND
 160 \fBRADIUS\fP is a protocol spoken between an access server, typically
 161 a device connected to several modems or ISDN lines, and a \fBradius\fP
 162 server. When a user connects to the access server, (s)he is asked for
 163 a loginname and a password. This information is then sent to the \fBradius\fP
 164 server. The server replies with "access denied", or "access OK". In the
 165 latter case login information is sent along, such as the IP address in
 166 the case of a PPP connection.
 167 .PP
 168 The access server also sends login and logout records to the \fBradius\fP
 169 server so accounting can be done. These records are kept for each terminal
 170 server seperately in a file called \fBdetail\fP, and in the \fIwtmp\fP
 171 compatible logfile \fB/var/log/radwtmp\fP.
 172 .SH CONFIGURATION
 173 \fBRadiusd\fP uses a number of configuration files. Each file has it's
 174 own manpage describing the format of the file. These files are:
 175 .IP radiusd.conf
 176 The main configuration file, which sets the administrator-controlled
 177 items.
 178 .IP dictionary
 179 This file is usually static. It defines all the possible RADIUS attributes
 180 used in the other configuration files.  You don't have to modify it.
 181 It includes other dictionary files in the same directory.
 182 .IP hints
 183 Defines certain hints to the radius server based on the users's loginname
 184 or other attributes sent by the access server. It also provides for
 185 mapping user names (such as Pusername -> username). This provides the
 186 functionality that the \fILivingston 2.0\fP server has as "Prefix" and
 187 "Suffix" support in the \fIusers\fP file, but is more general. Ofcourse
 188 the Livingston way of doing things is also supported, and you can even use
 189 both at the same time (within certain limits).
 190 .IP huntgroups
 191 Defines the huntgroups that you have, and makes it possible to restrict
 192 access to certain huntgroups to certain (groups of) users.
 193 .IP users
 194 Here the users are defined. On a typical setup, this file mainly contains
 195 DEFAULT entries to process the different types of logins, based on hints
 196 from the hints file. Authentication is then based on the contents of
 197 the UNIX \fI/etc/passwd\fP file. However it is also possible to define all
 198 users, and their passwords, in this file.
 199 .SH SEE ALSO
 200 radiusd.conf(5), users(5), huntgroups(5), hints(5),
 201 dictionary(5).
 202 .SH AUTHOR
 203 The FreeRADIUS Server Project (http://www.freeradius.org)
 204