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