/[radius]/radius/doc/texinfo/operation.texi
ViewVC logotype

Diff of /radius/doc/texinfo/operation.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.17 by gray, Thu Feb 6 09:50:27 2003 UTC revision 1.18 by dbarowy, Mon Feb 24 03:56:19 2003 UTC
# Line 14  be used for any kind of network connecti Line 14  be used for any kind of network connecti
14    
15  @menu  @menu
16  * Attributes::                  Attributes.  * Attributes::                  Attributes.
17  * Requests::                    Radius requests.  * Requests::                    @RADIUS{} requests.
18  * Matching Rule::               Rules for request processing.  * Matching Rule::               Rules for request processing.
19  * Request processing::          How Radius processes incoming requests.  * Request processing::          How GNU Radius processes incoming requests.
20  @end menu  @end menu
21    
22  @comment *L2****************************************************************  @comment *L2****************************************************************
# Line 29  be used for any kind of network connecti Line 29  be used for any kind of network connecti
29  @cindex Propagation of an attribute  @cindex Propagation of an attribute
30  @cindex Properties of an attribute  @cindex Properties of an attribute
31    
32  Information carried by @RADIUS{} requests is stored as a list of  Information carried by @RADIUS{} requests are stored as a list of
33  @dfn{Attribute-Value pairs}. Each pair consists of @dfn{Attribute  @dfn{Attribute-Value pairs}. Each pair consists of an @dfn{Attribute
34  number} and @dfn{Attribute value}. The @dfn{Attribute number} identifies  number} and an @dfn{Attribute value}. The @dfn{Attribute number} identifies
35  the type of information the pair carries and the @dfn{Attribute Value}  the type of information the pair carries and the @dfn{Attribute Value}
36  keeps the actual data.  keeps the actual data.
37    
# Line 55  Attribute numbers range from 1 to 255. A Line 55  Attribute numbers range from 1 to 255. A
55  greater than 255 are used internally by the sever and cannot be sent to  greater than 255 are used internally by the sever and cannot be sent to
56  the @NAS{}.  the @NAS{}.
57    
58  The special attribute 26, @dfn{Vendor-Specific}, is available to allow  The @dfn{Vendor-Specific} attribute number 26 is special, allowing
59  vendors of the @NAS{} hardware or software to support their own extended  vendors of the @NAS{} hardware or software to support their own extended
60  attributes. @ref{Vendor-Specific,, Vendor-Specific attribute}.  attributes. @ref{Vendor-Specific,, Vendor-Specific attribute}.
61    
# Line 64  properties are: Line 64  properties are:
64    
65  @table @dfn  @table @dfn
66  @item usage flags  @item usage flags
67  These flags determine usage of the attribute in configuration  These flags determine the usage of the attribute in the configuration
68  files @file{huntgroups}, @file{hints} and @file{users}.  files @file{huntgroups}, @file{hints} and @file{users}.
69  @item propagation  @item propagation
70  When a @RADIUS{} server functions in proxy mode, it uses the @dfn{propagation  When a @RADIUS{} server functions in proxy mode, it uses the @dfn{propagation
# Line 75  Some configuration rules may cause the a Line 75  Some configuration rules may cause the a
75  incoming request. Before the addition of a new pair, @radiusd{}  incoming request. Before the addition of a new pair, @radiusd{}
76  scans the request to see if it already contains a pair with the same  scans the request to see if it already contains a pair with the same
77  attribute. If it does, the value of @dfn{additivity} determines the  attribute. If it does, the value of @dfn{additivity} determines the
78  further actions:  following additional actions:
79  @table @asis  @table @asis
80  @item None  @item None
81  The old pair is retained in the request, the new pair is not added to  The old pair is retained in the request, the new pair is not added to
# Line 88  The new pair is appended to the end of t Line 88  The new pair is appended to the end of t
88  @end table  @end table
89  @end table  @end table
90    
91  The attributes are declared in the @file{raddb/dictionary} file. For a  Attributes are declared in the @file{raddb/dictionary} file. For a
92  detailed description, @xref{ATTRIBUTE}.  detailed description, @xref{ATTRIBUTE}.
93  For information about particular attributes, @xref{Attribute List}.  For information about particular attributes, @xref{Attribute List}.
94    
# Line 98  For information about particular attribu Line 98  For information about particular attribu
98  @cindex Request  @cindex Request
99    
100  The term @dfn{request} refers to both the authentication/accounting  The term @dfn{request} refers to both the authentication/accounting
101  request packet  from a @NAS{} to a Radius server and the response  request packet from a @NAS{} to a @RADIUS{} server and the response
102  packet that the server sends back to the @NAS{}.  packet that the server sends back to the @NAS{}.
103    
104  Each request contains the following fields  Each request contains the following fields
# Line 136  request. Line 136  request.
136  @cindex Requests, authentication  @cindex Requests, authentication
137    
138  A @NAS{} sends authentication requests (packets with code field set to  A @NAS{} sends authentication requests (packets with code field set to
139  Access-Request) to a @RADIUS{} server when a user is trying to connect to that @NAS{}. Such  Access-Request) to a @RADIUS{} server when a user is trying to connect
140  requests convey information used to determine whether a user  to that @NAS{}. Such requests convey information used to determine
141  is allowed access to the @NAS{}, and whether any special services  whether a user is allowed access to the @NAS{}, and whether any
142  are requested for that user.  special services are requested for that user.
143    
144  An Access-Request must contain a @attr{User-Name} attribute  An Access-Request must contain a @attr{User-Name} attribute
145  @ref{User-Name}. It should contain either a @attr{NAS-IP-Address}  @ref{User-Name}. This packet should contain a @attr{NAS-IP-Address}
146  attribute or @attr{NAS-Identifier} attribute, or both of them.  attribute, a @attr{NAS-Identifier} attribute, or both attributes.  It
147  It also must contain either a @attr{User-Password} attribute or @attr{CHAP-Password}  also must contain either a @attr{User-Password} attribute or
148  attribute. These attributes are passed encoded using a method based  @attr{CHAP-Password} attribute. These attributes are passed encoded
149  on the RSA Message Digest Algorithm MD5.  using a method based on the RSA Message Digest Algorithm MD5.
150    
151  The Access-Request should contain a @attr{NAS-Port} or @attr{NAS-Port-Type}  The Access-Request should contain a @attr{NAS-Port} or @attr{NAS-Port-Type}
152  attribute or both unless the type of access being requested does  attribute or both unless the type of access being requested does
153  not involve a port or the @NAS{} does not distinguish among its  not involve a port or the @NAS{} does not distinguish among its
154  ports.  ports.
155    
156  Upon receiving Access-Request packet for a particular user and  Upon receiving an Access-Request packet for a particular user and
157  authenticating that user, Radius server replies to the @NAS{} that  authenticating that user, the @RADIUS{} server replies to the @NAS{} that
158  has sent the packet with either of the following packets:  has sent the packet with either of the following packets:
159    
160  @itemize @bullet  @itemize @bullet
# Line 163  has sent the packet with either of the f Line 163  has sent the packet with either of the f
163  @item Access-Challenge  @item Access-Challenge
164  @end itemize  @end itemize
165    
166  Radius replies with Access-Accept packet when it has successfully  GNU Radius replies with an Access-Accept packet when it has successfully
167  authenticated the user. Such reply packet provides specific  authenticated the user. Such a reply packet provides the
168  configuration information necessary to begin delivery of service to  configuration information necessary to begin delivery of service to
169  the user.  the user.
170    
171  Radius replies with Access-Reject packet when it was unable to  GNU Radius replies with an Access-Reject packet when it is unable to
172  authenticate the user. Such packet may contain a descriptive  authenticate the user. Such a packet may contain a descriptive text
173  text encapsulated in one or more @attr{Reply-Message} attributes.  encapsulated in one or more @attr{Reply-Message} attributes.  The
174  The @NAS{} may display this text along with its response to the  @NAS{} may display this text along with its response to the user.
175    
176    GNU Radius replies with an Access-Challenge packet when it needs to
177    obtain more information from the user in order to determine the user's
178    authenticity or to determine the kind of service to be provided to the
179  user.  user.
180    
181  Radius replies with Access-Challenge packet when it desires to  An Access-Challenge packet may include one or more
182  obtain more information from the user in order to determine its  @attr{Reply-Message} attributes, and it may or may not include a
183  authenticity or to determine the kind of service to be provided  single @attr{State} attribute. No other attributes are permitted in an
184  to the user.  Access-Challenge packet.
185    
186  An Access-Challenge packet may include one or more @attr{Reply-Message}  Upon receipt of an Access-Challenge, the Identifier field is matched
187  attributes, and may also include a single @attr{State} attribute, or  with a pending Access-Request. Additionally, the Response
188  none. No other Attributes are permitted in an Access-Challenge.  Authenticator field must contain the correct response for the pending
189    Access-Request.  In the event of an invalid packet, GNU Radius
190  On receipt of an Access-Challenge, the Identifier field is matched  discards the offending packet and issues the appropriate log message.
 with a pending Access-Request.  Additionally, the Response Authenticator  
 field must contain the correct response for the  pending Access-Request.  
 Radius discards invalid packets and issues appropriate log message.  
191    
192  If the @NAS{} does not support challenge/response, it treats an  If the @NAS{} does not support challenge/response, it treats an
193  Access-Challenge as though it had received an Access-Reject instead.  Access-Challenge as though it had received an Access-Reject instead.
194  Otherwise, upon receipt of a valid Access-Challenge the @NAS{} prompts the  Otherwise, upon receipt of a valid Access-Challenge the @NAS{} prompts
195  user for a response, possibly displaying the text message provided in  the user for a response, possibly displaying the text message provided
196  @attr{Reply-Message} attributes of the request. It then sends its  in @attr{Reply-Message} attributes of the request. It then sends its
197  original Access-Request with a new request @sc{id} and Request Authenticator,  original Access-Request with a new request @sc{id} and Request
198  with the @attr{User-Password} attribute replaced by the encrypted user's  Authenticator, along with the @attr{User-Password} attribute replaced
199  response, and including the @attr{State} attribute from the  by the encrypted user's response, and including the @attr{State}
200  Access-Challenge, if any.  attribute from the Access-Challenge, if any.
201    
202  @comment **L3***************************************************************  @comment **L3***************************************************************
203  @node Accounting Requests  @node Accounting Requests
# Line 204  Access-Challenge, if any. Line 205  Access-Challenge, if any.
205  @cindex Accounting requests  @cindex Accounting requests
206  @cindex Requests, accounting  @cindex Requests, accounting
207    
208  Accounting-Request packets are sent from a @NAS{} to a Radius server  Accounting-Request packets are sent from a @NAS{} to a @RADIUS{}
209  to allow for accounting of a service provided to a user.  server to allow for accounting of a service provided to a user.
210    
211  Upon receipt of an Accounting-Request, the server attempts to record  Upon receipt of an Accounting-Request, the server attempts to record
212  the accounting packet @ref{Accounting}, and if it succeeds in doing  the accounting packet @ref{Accounting}, and if it succeeds in doing
213  so it replies with an Accounting-Response packet. Otherwise it sends  so, it replies with an Accounting-Response packet. Otherwise, it sends
214  no reply, which then causes the @NAS{} to retransmit its request within  no reply, which then causes the @NAS{} to retransmit its request
215  a preconfigured interval of time. Such retransmits will continue until  within a preconfigured interval of time. Such retransmits will
216  either the server responds with an Accounting-Response packet or a  continue until either the server responds with an Accounting-Response
217  preconfigured number of retransmits is reached, whichever occurs first.  packet or a preconfigured number of retransmits is reached, whichever
218    occurs first.
219  Any attribute valid in an Access-Request or Access-Accept packet  
220  is also valid in an Accounting-Request packet, except the following  Any attribute valid in an Access-Request or Access-Accept packet is
221  attributes, which are never present in an Accounting-Request packet:  also valid in an Accounting-Request packet, except the following
222    attributes which are never present in any Accounting-Request packet:
223    
224  @itemize @bullet  @itemize @bullet
225  @item User-Password  @item User-Password
# Line 226  attributes, which are never present in a Line 228  attributes, which are never present in a
228  @item State  @item State
229  @end itemize  @end itemize
230    
231  Either @attr{NAS-IP-Address} or @attr{NAS-Identifier} must be present in an  Either a @attr{NAS-IP-Address} or a @attr{NAS-Identifier} must be
232  Accounting-Request.  It should contain a @attr{NAS-Port} or  present in an Accounting-Request.  It should contain either a
233  @attr{NAS-Port-Type} attribute or both unless the service does not involve a  @attr{NAS-Port} or @attr{NAS-Port-Type} attribute (or both
234  port or the @NAS{} does not distinguish among its ports.  attributes), unless the service does not involve a port or the @NAS{}
235    does not distinguish among its ports.
236    
237  If the Accounting-Request packet includes a Framed-IP-Address,  If the Accounting-Request packet includes a @attr{Framed-IP-Address},
238  that attribute @emph{must} contain the actual @IP{} of the user.  that attribute @emph{must} contain the actual @IP{} of the user.
239    
240  There are five types of accounting packets, which differ by the value of  There are five types of accounting packets, differentiated by the
241  @attr{Acct-Status-Type} attribute. These are:  value of @attr{Acct-Status-Type} attribute. These are:
242    
243  @table @dfn  @table @dfn
244  @item Session Start Packet.  @item Session Start Packet
245  The session start packet is sent after the user has successfully passed  The session start packet is sent after the user has successfully
246  the authentication and has started to receive the requested service. It  passed the authentication and has started to receive the requested
247  must contain at least following attributes:  service. It must contain at least following attributes:
248    
249  @itemize @bullet  @itemize @bullet
250  @item Acct-Status-Type = Start  @item Acct-Status-Type = Start
# Line 251  must contain at least following attribut Line 254  must contain at least following attribut
254  @item NAS-Port-Id  @item NAS-Port-Id
255  @end itemize  @end itemize
256    
257  @item Session Stop Packet.  @item Session Stop Packet
258  The Session Stop Packet is sent after the user has disconnected. It  The Session Stop Packet is sent after the user has disconnected. It
259  conveys the information about the duration of the session, number  conveys the information about the duration of the session, number of
260  of octets transferred, etc. It must contain at least the following  octets transferred, etc. It must contain at least the following
261  attributes:  attributes:
262    
263  @itemize @bullet  @itemize @bullet
# Line 264  attributes: Line 267  attributes:
267  @item Acct-Session-Id  @item Acct-Session-Id
268  @end itemize  @end itemize
269    
270  The last three of them are used to find the corresponding  The last three of them are used to find the corresponding @dfn{Session
271  @dfn{Session Start Packet}.  Start Packet}.
272    
273  @item Keepalive Packet  @item Keepalive Packet
274  The keepalive packet is sent by the @NAS{} when it obtains some  The keepalive packet is sent by the @NAS{} when it obtains some new
275  new information about the user's session, e.g. it has determined  information about the user's session, e.g. it has determined its @IP{}
276  its @IP{} or has changed the connection speed, etc. The packet must  or has changed the connection speed, etc. The packet must contain at
277  contain at least following attributes:  least following attributes:
278    
279  @itemize @bullet  @itemize @bullet
280  @item Acct-Status-Type = Alive  @item Acct-Status-Type = Alive
# Line 281  contain at least following attributes: Line 284  contain at least following attributes:
284  @end itemize  @end itemize
285    
286  @item Accounting Off Packet  @item Accounting Off Packet
287  By sending this packet @NAS{} requests that radius mark all sessions  By sending this packet, the @NAS{} requests that @radiusd{} mark all
288  registered from this @NAS{} as finished. Receiving this packet usually  sessions registered from this particular @NAS{} as finished. Receiving
289  means that the @NAS{} is to be shut down, or is about to change its  this packet usually means that the @NAS{} is to be shut down, or is
290  configuration in a way that requires all currently opened sessions to  about to change its configuration in a way that requires all currently
291  be shut down. The packet must contain at least the following attributes:  opened sessions to be closed. The packet must contain at least the
292    following attributes:
293    
294  @itemize @bullet  @itemize @bullet
295  @item Acct-Status-Type = Accounting-Off  @item Acct-Status-Type = Accounting-Off
# Line 293  be shut down. The packet must contain at Line 297  be shut down. The packet must contain at
297  @end itemize  @end itemize
298    
299  @item Accounting On Packet  @item Accounting On Packet
300  By sending this packet, the @NAS{} informs radius that it is ready  By sending this packet, the @NAS{} informs @radiusd{} that it is ready
301  to accept the incoming connections. Usually this packet is sent  to accept the incoming connections. Usually this packet is sent after
302  after startup, or after a major reconfiguration of the @NAS{}. It  startup, or after a major reconfiguration of the @NAS{}. It must
303  must contain at least the following attributes:  contain at least the following attributes:
304    
305  @itemize @bullet  @itemize @bullet
306  @item Acct-Status-Type = Accounting-Off  @item Acct-Status-Type = Accounting-Off
# Line 312  must contain at least the following attr Line 316  must contain at least the following attr
316  @cindex LHS, Matching Rule  @cindex LHS, Matching Rule
317  @cindex RHS, Matching Rule  @cindex RHS, Matching Rule
318    
319  A record in the radius database describing a particular rule for  A record in the GNU Radius database describing a particular rule for
320  matching an incoming request is called a @dfn{Matching Rule}. Each  matching an incoming request is called a @dfn{Matching Rule}. Each
321  such rule defines an action to be taken when the match occurs.  such rule defines an action to be taken when the match occurs.
322    
# Line 320  The @dfn{Matching Rule} consists of thre Line 324  The @dfn{Matching Rule} consists of thre
324    
325  @table @dfn  @table @dfn
326  @item Label  @item Label
327  This is used to identify the rule. The special usernames @code{DEFAULT}  This is used to identify the rule. The special usernames
328  and @code{BEGIN} are reserved. These will be described in detail below.  @code{DEFAULT} and @code{BEGIN} are reserved. These will be described
329    in detail below.
330    
331  @item Left-Hand Side (LHS)  @item Left-Hand Side (LHS)
332  The list of attribute-value pairs used for matching the profile against  The list of attribute-value pairs used for matching the profile
333  an incoming request.  against an incoming request.
334    
335  @item Right-Hand Side (RHS)  @item Right-Hand Side (RHS)
336  The list of attribute-value pairs that define the action to be taken  The list of attribute-value pairs that define the action to be taken
337  if the request matches @LHS{}.  if the request matches @LHS{}.
338  @end table  @end table
339    
340  The following radius configuration files keep data in a @dfn{Matching Rule}  The following GNU Radius configuration files keep data in a
341  format: @file{hints}, @file{huntgroups} and @file{users}. Although  @dfn{Matching Rule} format: @file{hints}, @file{huntgroups} and
342  they keep data in similar format, the rules that are used to match  @file{users}. Although they keep data in a similar format, the rules
343  incoming requests against contents of these files differ from file  that are used to match incoming requests against the contents of these
344  to file. The following section describes these rules in detail.  files differ from file to file. The following section describes these
345    rules in detail.
346    
347  @comment *L2****************************************************************  @comment *L2****************************************************************
348  @node Request processing  @node Request processing
349  @section Processing Requests  @section Processing Requests
350  @cindex Processing requests  @cindex Processing requests
351    
352  Upon receiving a request Radius applies to it a number of checks to  Upon receiving a request @radiusd{} applies to it a number of checks
353  determine whether the request comes from an authorized source. If these  to determine whether the request comes from an authorized source. If
354  checks succeed, the request is processed and answered. Otherwise, the  these checks succeed, the request is processed and
355  request is dropped and corresponding error message is issued (@pxref{Logging}).  answered. Otherwise, the request is dropped and corresponding error
356    message is issued (@pxref{Logging}).
357    
358  The following checks are performed:  The following checks are performed:
359    
360  @table @asis  @table @asis
361  @item Check if the username is supplied  @item Check if the username is supplied
362  If the packet lacks @attr{User-Name} attribute it is not processed  If the packet lacks the @attr{User-Name} attribute it is not processed
363  @item Check if the @NAS{} is allowed to speak  @item Check if the @NAS{} is allowed to speak
364  The source @IP{} of the machine that sent the packet is looked  The source @IP{} of the machine that sent the packet is looked up in
365  up in the @file{clients} file (@pxref{clients file}). If no match is found,  the @file{clients} file (@pxref{clients file}). If no match is found,
366  the request is rejected.  the request is rejected.
367  @item Compute the encryption key  @item Compute the encryption key
368  Using the data from the packet and the shared key value from the @file{clients}  Using the data from the packet and the shared key value from the
369  file, Radius computes the MD5 encryption key that will be used to decrypt  @file{clients} file, Radius computes the MD5 encryption key that will
370  the value of the @attr{User-Password} attribute.  be used to decrypt the value of the @attr{User-Password} attribute.
371  @item Process user-name hints.  @item Process user-name hints.
372  @dfn{User-name hints} are special rules that modify the request  @dfn{User-name hints} are special rules that modify the request
373  depending on user name and his credentials. These rules allow to divide  depending on user name and his credentials. These rules allow an
374  users into distinct groups, each group having its own authentication  administrator to divide users into distinct groups, each group having
375  and/or accounting methods. The user-name hints are stored in  its own authentication and/or accounting methods. The user-name hints
376  @file{raddb/hints} (@pxref{hints file}).  are stored in @file{raddb/hints} (@pxref{hints file}).
377  @item Process huntgroup rules.  @item Process huntgroup rules
378  @dfn{Huntgroup rules} allow to segregate incoming requests depending  @dfn{Huntgroup rules} allow an administrator to segregate incoming
379  on the @NAS{} and/or port number they came from. These rules are stored in  requests depending on the @NAS{} and/or port number they came
380  @file{raddb/huntgroups} (@pxref{huntgroups file}).  from. These rules are stored in @file{raddb/huntgroups}
381  @item Determine whether the request must be proxied to another radius  (@pxref{huntgroups file}).
382  server  @item Determine whether the request must be proxied to another @RADIUS{}
383  The requests pertaining to another realm are immediately forwarded  server The requests pertaining to another realm are immediately
384  to the remote radius server for further processing. @xref{Proxying},  forwarded to the remote @RADIUS{} server for further
385  for the description of this process.  processing. @xref{Proxying}, for the description of this process.
386  @item Process individual user profiles.  @item Process individual user profiles
387  This step applies only to authentication requests.  This step applies only to authentication requests.
388  @end table  @end table
389    
390  @menu  @menu
391  * Checking Duplicates::  * Checking Duplicates::
392  * Proxying::        * Proxying::
393  * Hints::  * Hints::
394  * Huntgroups::  * Huntgroups::
395  * User Profiles::  * User Profiles::
# Line 393  This step applies only to authentication Line 400  This step applies only to authentication
400  @subsection Checking for Duplicate Requests  @subsection Checking for Duplicate Requests
401  @cindex duplicate requests, checking  @cindex duplicate requests, checking
402    
403  As described above (@pxref{Operation}), a @NAS{} may decide  As described above (@pxref{Operation}), a @NAS{} may decide to
404  to retransmit the request under a certain circumstances. Whereas this  retransmit the request under certain circumstances. This behaviour
405  behaviour makes sure no requests are lost, it has its upshots. For  ensures that no requests are lost. For example, consider the following
406  example, consider the following scenario:  scenario:
407    
408  @enumerate  @enumerate
409  @item @NAS{} sends a request to the server.  @item The @NAS{} sends a request to the server.
410  @item The server processes it and sends back the reply.  @item The server processes it and sends back the reply.
411  @item The reply is lost due to network outage or the load average of the  @item The reply is lost due to a network outage or the load average of the
412  @NAS{} was too high and it dropped the response.  @NAS{} was too high and it dropped the response.
413  @item The @NAS{} retransmits the request.  @item The @NAS{} retransmits the request.
414  @end enumerate  @end enumerate
415    
416  Thus the server will receive and process the same request twice. It  Thus the @RADIUS{} server will receive and process the same request
417  possibly won't do any harm if the request in question is an  twice. It probably won't do any harm if the request in question is an
418  authentication one, but for accounting requests this will lead to  authentication one, but for accounting requests this will lead to
419  duplicate accounting. To avoid such undesirable effects, @command{radiusd}  duplicate accounting. To avoid such an undesirable effect, @radiusd{}
420  keeps a queue of received requests. When an incoming request arrives,  keeps a queue of received requests. When an incoming request arrives,
421  @command{radiusd} first scans the request queue to see if the request  @radiusd{} first scans the request queue to see if the request is a
422  is a duplicate of an already received one. If so, it drops the request.  duplicate. If so, it drops the request, otherwise it inserts the
423  Otherwise it inserts the request into the queue and starts processing  request into the queue for processing. After the request is completed
424  it. After the request is completed it will still reside in the queue for a  it will still reside in the queue for a preconfigured interval of time
425  preconfigured interval of time (@xref{auth}, parameter  (@xref{auth}, parameter @code{request-cleanup-delay}).
 @code{request-cleanup-delay}).  
426    
427  By default, @command{radiusd} considers two requests to be equal  By default, @radiusd{} considers two requests to be equal if the
428  if the following conditions are met:  following conditions are met:
429    
430  @enumerate  @enumerate
431  @item Both requests come from the same @NAS{}.  @item Both requests come from the same @NAS{}.
# Line 428  if the following conditions are met: Line 434  if the following conditions are met:
434  @item The request authenticator is the same for both requests.  @item The request authenticator is the same for both requests.
435  @end enumerate  @end enumerate
436    
437  Additionally, @command{radiusd} may be configured to take into account  Additionally, @radiusd{} may be configured to take into account the
438  the contents of both requests. This may be necessary since some @NAS{}es  contents of both requests. This may be necessary since some @NAS{}es
439  modify the request authenticator or even request identifier before  modify the request authenticator or request identifier before
440  retransmitting the request, so the method described above fails to  retransmitting the request, so the method described above fails to
441  recognize the request as a duplicate. This @dfn{extended comparison} is  recognize the request as a duplicate. This @dfn{extended comparison}
442  described in detail in @ref{Extended Comparison}.  is described in detail in @ref{Extended Comparison}.
443    
444  @comment **L3***************************************************************  @comment **L3***************************************************************
445  @node Proxying  @node Proxying
446  @subsection Proxying  @subsection Proxying
447  @cindex Proxying  @cindex Proxying
448    
449  @dfn{Proxying} is a mode of operation when a radius server forwards  @dfn{Proxying} is a mode of operation when a @RADIUS{} server forwards
450  an incoming requests from a @NAS{} to another radius server, waits  incoming requests from a @NAS{} to another @RADIUS{} server, waits for
451  for the latter to reply, and forwards the reply back to the requesting  the latter to reply, and then forwards the reply back to the
452  @NAS{}. A common use for such operation mode is to provide @dfn{roaming}  requesting @NAS{}. A common use for such operation mode is to provide
453  between several Internet Service Providers (@acronym{ISP}s). Roaming  @dfn{roaming} between several Internet Service Providers
454  permits the @acronym{ISP}s to share their resources, allowing  (@acronym{ISP}s). Roaming permits @acronym{ISP}s to share their
455  each other's users to connect to other party's equipment. Thus, users  resources, allowing  each other's users to connect to other party's
456  traveling outside the area of one @acronym{ISP}'s coverage are still  equipment. Thus, users traveling outside the area of one
457  able to access their services through another @acronym{ISP}.  @acronym{ISP}'s coverage are still able to access their services
458    through another @acronym{ISP}.
459    
460  @menu  @menu
461  * Proxy Service::          * Proxy Service::
462  * Realms::  * Realms::
463  @end menu  @end menu
464    
# Line 460  able to access their services through an Line 467  able to access their services through an
467  @subsubsection Proxy Service  @subsubsection Proxy Service
468  @cindex Proxy Service  @cindex Proxy Service
469    
470  Suppose the @acronym{ISP} @samp{Local} has a roaming arrangement with the  Suppose the @acronym{ISP} @samp{Local} has a roaming arrangement with
471  @acronym{ISP} @samp{Remote}. When the user of @samp{Remote} dials in  the @acronym{ISP} @samp{Remote}. When the user of @samp{Remote} dials
472  to the @NAS{} of @samp{Local}, the @NAS{} sends the authentication  in to the @NAS{} of @samp{Local}, the @NAS{} sends the authentication
473  request to @samp{Local} radius server. The server then determines that this  request to the @samp{Local} @RADIUS{} server. The server then
474  is a roaming user, stores a copy of the request in its  determines that this is a roaming user, stores a copy of the request
475  internal queue, and forwards the request to @samp{Remote} radius  in its internal queue, and forwards the request to the @samp{Remote}
476  server for processing. Thus, @samp{Local} radius acts as a client for  @RADIUS{} server for processing. Thus, the @samp{Local} @RADIUS{}
477  @samp{Remote} radius. When @samp{Remote} radius responds, the  server acts as a client for the @samp{Remote} @RADIUS{} server.
478  @samp{Local} receives the response, and passes it back to the @NAS{}.  
479  The copy of the request from the server's queue serves to determine  When the @samp{Remote} @RADIUS{} server responds, the @samp{Local}
480  which @NAS{} originated the request. Before passing the request  @RADIUS{} server receives the response, and passes it back to the
481  back to the @NAS{}, radius removes from it the information,  @NAS{}.  The copy of the request from the server's queue determines
482  specific for @samp{Remote} site, such as @attr{Framed-IP-Address},  which @NAS{} originated the request. Before passing the request back
483    to the @NAS{}, the server removes information specific to the
484    @samp{Remote} site, such as @attr{Framed-IP-Address},
485  @attr{Framed-Netmask}, etc. Only the attributes marked with  @attr{Framed-Netmask}, etc. Only the attributes marked with
486  @samp{propagate} flag (@pxref{Attributes}) are passed back to  @samp{propagate} flag (@pxref{Attributes}) are passed back to the
487  the @NAS{}. After removing site-specific attributes, @samp{Local} radius  @NAS{}. After removing site-specific attributes, the @samp{Local}
488  passes the request through its user profiles (@pxref{User Profiles}) to  @RADIUS{} server passes the request through its user profiles
489  insert any local site-specific information that might be  (@pxref{User Profiles}) to insert any local, site-specific information
490  needed. Finally, it passes the reply back to the @NAS{}.  that might be needed. Finally, it passes the reply back to the @NAS{}.
491    
492  The accounting requests are processed in the similar manner, except that  Proxied accounting requests are processed in a similar manner, except
493  no attribute filtering takes place, as the accounting responses do  that no attribute filtering takes place as accounting responses do not
494  not carry any @AVP{}s.  carry any @AVP{}s.
495    
496  This example illustrates the simplest @dfn{proxy chain}, consisting of  This example illustrates only the simplest @dfn{proxy chain},
497  only two servers. The proxy chains may consist of several servers. In  consisting of two servers; real-life proxy chains may consist of
498  our example, the @samp{Remote} radius server may also act as a proxy  several servers. For example, our @samp{Remote} @RADIUS{} server might
499  and forward the request to still another radius server, etc.  also act as a proxy, forwarding the request to yet another @RADIUS{}
500    server, and so on.
501  @emph{Note}, that when the accounting request passes through a chain of  
502  forwarding servers, the accounting records are stored on all servers in  NOTE: When the accounting request passes through a chain of forwarding
503  the chain.  servers, the accounting records are @emph{stored on all servers in the
504    chain}.
505    
506  @comment ***L4**************************************************************  @comment ***L4**************************************************************
507  @node Realms  @node Realms
508  @subsubsection Realms  @subsubsection Realms
509  @cindex Realms  @cindex Realms
510    
511  Radius server determines which server a request must be forwarded to  GNU Radius determines which server a request must be forwarded to by
512  by request's @dfn{authentication realm}. There are three kinds of  the request's @dfn{authentication realm}. There are three kinds of
513  realms:  realms:
514    
515  @enumerate 1  @enumerate 1
# Line 508  realms: Line 518  realms:
518  @samp{jsmith@@this.net}, then @samp{this.net} is the realm.  @samp{jsmith@@this.net}, then @samp{this.net} is the realm.
519    
520  The named realms can be cascaded, e.g. a request with user name  The named realms can be cascaded, e.g. a request with user name
521  @samp{jsmith@@this.net@@remote.net} will first be forwarded to  @samp{jsmith@@this.net@@remote.net} will first be forwarded to the
522  the radius server of realm @samp{remote.net}, which in turn  @RADIUS{} server of realm @samp{remote.net}, which in turn will
523  will forward it to @samp{this.net}.  forward it to @samp{this.net}.
524  @item A @dfn{Default Realm} defines the server to which the requests  @item A @dfn{Default Realm} defines the server to which the requests
525  for realms, not mentioned explicitly in the configuration,  for realms not mentioned explicitly in the configuration are forwarded.
 are forwarded.  
526  @item An @dfn{Empty Realm} defines the server to which the requests  @item An @dfn{Empty Realm} defines the server to which the requests
527  @emph{without} explicit named realm are forwarded. If the configuration  @emph{without} explicitly named realms are forwarded. If the
528  does not define the empty realm, such requests are processed by the  configuration does not define an empty realm, such requests are
529  server itself.  processed by the server itself.
530  @end enumerate  @end enumerate
531    
532  GNU Radius keeps the information about the realms it serves in  GNU Radius keeps the information about the realms it serves in the
533  configuration file @file{raddb/realms} (@pxref{realms file}).  @file{raddb/realms} configuration file (@pxref{realms file}).
534    
535  @comment **L3***************************************************************  @comment **L3***************************************************************
536  @node Hints  @node Hints
537  @subsection Hints  @subsection Hints
538  @cindex Hints  @cindex Hints
539    
540  @dfn{User-name hints} are special rules that modify the incoming request  @dfn{User-name hints} are special rules that modify the incoming
541  depending on user name and his credentials. Hints are stored as a list  request depending on the username and its credentials. Hints are
542  of @dfn{Matching Rules} (@pxref{Matching Rule}). Upon receiving a request,  stored as a list of @dfn{Matching Rules} (@pxref{Matching Rule}). Upon
543  @command{radiusd} scans the hints entries sequentially, comparing each  receiving a request, @radiusd{} scans the hints entries sequentially,
544  rule's @dfn{Label} with the value of @attr{User-Name} attribute from  comparing each rule's @dfn{Label} with the value of the
545  the request. If they coincide, then @command{radiusd} appends the contents  @attr{User-Name} attribute from the request. If they coincide, then
546  of the rule's @RHS{} to the request pair-list.  @radiusd{} appends the contents of the rule's @RHS{} to the request's
547    pair-list.
548    
549  Both user names must match exactly in order for a hint to  Both user names must match exactly in order for a hint to take effect,
550  take effect, unless the hint's checklist contains either @attr{Prefix} or  unless the hint's checklist contains either the @attr{Prefix} or the
551  @attr{Suffix} attribute. The special name @samp{DEFAULT} or  @attr{Suffix} attribute. The special name @samp{DEFAULT} or
552  @samp{DEFAULT%d} (where %d denotes any decimal number), used as hint's  @samp{DEFAULT%d} (where %d denotes any decimal number), used as hint's
553  @dfn{Label} match any username.  @dfn{Label}, match any username.
554    
555  The two special attributes, @attr{Prefix} and @attr{Suffix}, may be used  Two special attributes, @attr{Prefix} and @attr{Suffix}, may be used
556  in @LHS{} to restrict the match to a specified part of a user-name. Both  in @LHS{} to restrict the match to a specified part of a
557  are string attributes. The @attr{Prefix} instructs radius to accept the  username. Both are string attributes. The @attr{Prefix} instructs
558  hint only if the username begins with the given prefix. Similarly,  @radiusd{} to accept the hint only if the username begins with the
559  @attr{Suffix} instructs radius to accept the hint only if the username  given prefix. Similarly, @attr{Suffix} instructs @radiusd{} to accept
560  ends with the given suffix. A hint may contain both @attr{Prefix} and  the hint only if the username ends with the given suffix. A hint may
561  @attr{Suffix} attributes.  contain both @attr{Prefix} and @attr{Suffix} attributes.
562    
563  In addition to these two attributes, a hint's @LHS{}  may  In addition to these two attributes, a hint's @LHS{} may contain
564  contain @attr{User-ID} and @attr{Group} attributes.  @attr{User-ID} and @attr{Group} attributes.
565    
566  The following attributes, when used in a hint's @RHS{} have  The following attributes, when used in a hint's @RHS{} have special
567  special meaning. They are not appended to the request pair-list.  meaning. They are not appended to the request pair-list.  Instead,
568  Instead, they are removed after completing their function:  they are removed after completing their function:
569  @table @attr  @table @attr
570  @item Fall-Through  @item Fall-Through
571  If this attribute is present, and is set to @code{Yes}, @command{radiusd}  If this attribute is present, and is set to @code{Yes}, @radiusd{}
572  continues scanning the hints, after processing current entry. This  continues scanning the hints after processing current entry. This
573  allows for applying several hints to a single packet.  allows @radiusd{} to apply several hints to a single packet.
574  @item Rewrite-Function  @item Rewrite-Function
575  If this attribute is present, the specified rewrite function is invoked.  If this attribute is present, the specified rewrite function is
576    invoked.
577  @item Replace-User-Name  @item Replace-User-Name
578  The value of this attribute is expanded (@pxref{Macro Substitution}),  The value of this attribute is expanded (@pxref{Macro Substitution}),
579  and replaces the value of @attr{User-Name} attribute from the request.  and replaces the value of the @attr{User-Name} attribute from the
580    request.
581  @end table  @end table
582    
583  The hints rules are defined in @file{raddb/hints} file  Hints rules are defined in @file{raddb/hints} file (@pxref{hints
584  (@pxref{hints file}).  file}).
585    
586  @comment **L3***************************************************************  @comment **L3***************************************************************
587  @node Huntgroups  @node Huntgroups
588  @subsection Huntgroups  @subsection Huntgroups
589  @cindex Huntgroups  @cindex Huntgroups
590    
591  Huntgroups are special rules, that allow to alter processing of incoming  Huntgroups are special rules that allow an administrator to provide
592  requests, depending on @NAS{} @IP{} and port number they come  alternate processing of certain incoming requests depending on the
593  from. The rules are stored as a list of @dfn{Matching Rules}  @NAS{} @IP{} and port number they come from. These rules are stored as
594  (@pxref{Matching Rule}). Upon receiving a request, @command{radiusd}  a list of @dfn{Matching Rules} (@pxref{Matching Rule}).
595  scans this list sequentially until it finds an entry, such that  
596  the conditions set forth in its @LHS{} are matched by the  Upon receiving a request, @radiusd{} scans this list sequentially
597  request. If such an entry is found, @command{radiusd} verifies that  until it finds an entry, such that the conditions set forth in its
598  the request meet the conditions described by @RHS{}. If it  @LHS{} are matched by the request. If such an entry is found,
599  does not, the request is rejected. In short, a huntgroup requires  @radiusd{} verifies that the request meets the conditions described by
600  that any request matching its @LHS{} must match also its  @RHS{}. If it does not, the request is rejected. In short, a huntgroup
601  @RHS{}. The @dfn{Label} part of the rule is not used in  requires that any request matching its @LHS{} must match also its
602  comparisons, instead it is used to label huntgroups. All entries  @RHS{}.
603  with the same label form a single huntgroup. The special attribute  
604  @attr{Huntgroup-Name} can be used to request a match against a  The @dfn{Label} part of the rule is not used in comparisons, instead
605  particular huntgroup (@pxref{Huntgroup-Name}).  it is used to label huntgroups. All entries with the same label form a
606    single huntgroup. The special attribute @attr{Huntgroup-Name} can be
607    used to request a match against a particular huntgroup
608    (@pxref{Huntgroup-Name}).
609    
610  The huntgroups rules are defined in @file{raddb/huntgroups} file  Huntgroup rules are defined in the @file{raddb/huntgroups} file
611  (@pxref{huntgroups file}).  (@pxref{huntgroups file}).
612    
613  @comment **L3***************************************************************  @comment **L3***************************************************************
# Line 601  The huntgroups rules are defined in @fil Line 616  The huntgroups rules are defined in @fil
616  @cindex User Profiles  @cindex User Profiles
617  @cindex Authentication  @cindex Authentication
618    
619  @dfn{User Profiles} are the per-user matching rules  @dfn{User Profiles} are @emph{per-user} matching rules
620  (@pxref{Matching Rule}). Any incoming authentication request is compared  (@pxref{Matching Rule}). All incoming authentication requests are
621  with the @dfn{User Profiles} after it has passed both @dfn{Hints} and  compared with the @dfn{User Profiles} after they have passed both
622  @dfn{Huntgroups}. @command{Radiusd} selects from the @dfn{User Profiles}  @dfn{Hints} and @dfn{Huntgroups}. @radiusd{} selects the @dfn{User
623  those rules, whose @dfn{Label} matches the value of @attr{User-Name}  Profiles} whose @dfn{Label} matches the value of @attr{User-Name}
624  attribute from the incoming request.  attribute from the incoming request.
625    
626  The selected profiles form the list of authentication rules for  The selected profiles form the list of authentication rules for the
627  the request. In order for a profile to be selected, its label must  request. In order for a profile to be selected, its label must either
628  either coincide literally with the @attr{User-Name} value, or  coincide literally with the @attr{User-Name} value, or it must be one
629  it must be one of special labels @code{DEFAULT} and @code{BEGIN}.  of special labels, @code{DEFAULT} or @code{BEGIN}.
630  The rules in the authentication list are ordered as follows: first  
631  go all the profiles with @code{BEGIN} label, they are followed  Rules in an authentication list are ordered as follows: first go all
632  by the profiles, whose labels match the @attr{User-Name} literally,  the profiles with @code{BEGIN} label, followed by the profiles whose
633  and, finally, these are followed by rules labeled with @code{DEFAULT}.  labels match the @attr{User-Name} literally, finally followed by rules
634  @footnote{For compatibility with other implementations of radius, GNU  labeled with @code{DEFAULT}. @footnote{For compatibility with other
635  Radius treats profile labels in the form @code{DEFAULT%d}, where @code{%d}  implementations of radius, GNU Radius treats profile labels in the
636  represents a decimal number, in the same way it treats @code{DEFAULT}  form @code{DEFAULT%d}, where @code{%d} represents a decimal number, in
637  labels. The same applies to @code{BEGIN} labels.} Within each of the  the same way it treats @code{DEFAULT} labels. The same applies to
638  three sub-lists the rules preserve the order in which they appear in  @code{BEGIN} labels.}
639  @file{raddb/users} file. Once the list is constructed, it is scanned  
640  sequentially until the rule is found, whose @LHS{} matches the incoming  Within each of the three sub-lists, the rules preserve the order in
641  request. If no such rule is found, then the authentication  which they appear in the @file{raddb/users} file. Once the list is
642  fails. Otherwise, the contents of its @RHS{} is appended to @dfn{Reply  constructed, it is scanned sequentially until the rule is found whose
643  List} being constructed. If the @RHS{} of the matched rule contains attribute  @LHS{} matches the incoming request. If no such rule is found, the
644  @attr{Fall-Through} with the value @code{Yes}, the matching continues.  authentication fails. Otherwise, the contents of its @RHS{} is
645  When the list is exhausted, the authentication result is sent back  appended to the @dfn{Reply List} being constructed. If the @RHS{} of
646  to the @NAS{} along with the @AVP{}s collected in the @dfn{Reply  the matched rule contains the attribute @attr{Fall-Through} with the
647  List}.  value @code{Yes}, the matching continues.  When the list is exhausted,
648    the authentication result is sent back to the @NAS{} along with the
649    @AVP{}s collected in the @dfn{Reply List}.
650    
651  The user profiles are defined in @file{raddb/users} file  User profiles are defined in the @file{raddb/users} file
652  (@pxref{users file}).  (@pxref{users file}).
653    
654    

Legend:
Removed from v.1.17  
changed lines
  Added in v.1.18

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26