Handle case where Acct-Session-Time might not exist
[freeradius.git] / raddb / proxy.conf
1 # -*- text -*-
2 ##
3 ## proxy.conf -- proxy radius and realm configuration directives
4 ##
5 ##      $Id$
6
7 #######################################################################
8 #
9 #  Proxy server configuration
10 #
11 #  This entry controls the servers behaviour towards ALL other servers
12 #  to which it sends proxy requests.
13 #
14 proxy server {
15         #
16         #  Note that as of 2.0, the "synchronous", "retry_delay",
17         #  "retry_count", and "dead_time" have all been deprecated.
18         #  For backwards compatibility, they are are still accepted
19         #  by the server, but they ONLY apply to the old-style realm
20         #  configuration.  i.e. realms with "authhost" and/or "accthost"
21         #  entries.
22         #
23         #  i.e. "retry_delay" and "retry_count" have been replaced
24         #  with per-home-server configuration.  See the "home_server"
25         #  example below for details.
26         #
27         #  i.e. "dead_time" has been replaced with a per-home-server
28         #  "revive_interval".  We strongly recommend that this not
29         #  be used, however.  The new method is much better.
30
31         #
32         #  In 2.0, the server is always "synchronous", and setting
33         #  "synchronous = no" is impossible.  This simplifies the
34         #  server and increases the stability of the network.
35         #
36         #  If you need to set "synchronous = no", please send a
37         #  message to the list <freeradius-users@lists.freeradius.org>
38         #  explaining why this feature is vital for your network.
39
40         #
41         #  If a realm exists, but there are no live home servers for
42         #  it, we can fall back to using the "DEFAULT" realm.  This is
43         #  most useful for accounting, where the server can proxy
44         #  accounting requests to home servers, but if they're down,
45         #  use a DEFAULT realm that is LOCAL (i.e. accthost = LOCAL),
46         #  and then store the packets in the "detail" file.  That data
47         #  can be later proxied to the home servers by radrelay, when
48         #  those home servers come back up again.       
49
50         #  Setting this to "yes" may have issues for authentication.
51         #  i.e. If you are proxying for two different ISP's, and then
52         #  act as a general dial-up for Gric.  If one of the first two
53         #  ISP's has their RADIUS server go down, you do NOT want to
54         #  proxy those requests to GRIC.  Instead, you probably want
55         #  to just drop the requests on the floor.  In that case, set
56         #  this value to 'no'.
57         #
58         #  allowed values: {yes, no}
59         #
60         default_fallback = no
61
62 }
63
64 #######################################################################
65 #
66 #  Configuration for the proxy realms.
67 #
68 #  As of 2.0. the old-style "realms" file is deprecated, and is not
69 #  used by FreeRADIUS.
70 #
71 #  As of 2.0, the "realm" configuration has changed.  Instead of
72 #  specifying "authhost" and "accthost" in a realm section, the home
73 #  servers are specified seperately in a "home_server" section.  For
74 #  backwards compatibility, you can still use the "authhost" and
75 #  "accthost" directives.  If you only have one home server for a
76 #  realm, it is easier to use the old-style configuration.
77 #
78 #  However, if you have multiple servers for a realm, we STRONGLY
79 #  suggest moving to the new-style configuration.
80 #
81 #
82 #  Load-balancing and failover between home servers is handled via
83 #  a "home_server_pool" section.
84 #
85 #  Finally, The "realm" section defines the realm, some options, and
86 #  indicates which server pool should be used for the realm.
87 #
88 #  This change means that simple configurations now require multiple
89 #  ssections to define a realm.  However, complex configurations
90 #  are much simpler than before, as multiple realms can share the same
91 #  server pool.
92 #
93 #  That is, realms point to server pools, and server pools point to
94 #  home servers.  Multiple realms can point to one server pool.  One
95 #  server pool can point to multiple home servers.  Each home server
96 #  can appear in one or more pools.
97 #
98
99 ######################################################################
100 #
101 #  This section defines a "Home Server" which is another RADIUS
102 #  server that gets sent proxied requests.  In earlier versions
103 #  of FreeRADIUS, home servers were defined in "realm" sections,
104 #  which was awkward.  In 2.0, they have been made independent
105 #  from realms, which is better for a number of reasons.
106 #
107 home_server localhost {
108         #
109         #  Home servers can be sent Access-Request packets
110         #  or Accounting-Request packets.
111         #
112         #  Allowed values are:
113         #       auth      - Handles Access-Request packets
114         #       acct      - Handles Accounting-Request packets
115         #       auth+acct - Handles Access-Request packets at "port",
116         #                   and Accounting-Request packets at "port + 1"
117         #       coa       - Handles CoA-Request and Disconnect-Request packets.
118         #                   See also raddb/sites-available/originate-coa
119         type = auth
120
121         #
122         #  Configure ONE OF the following entries:
123         #
124         #       IPv4 address
125         #
126         ipaddr = 127.0.0.1
127
128         #       OR IPv6 address
129         # ipv6addr = ::1
130
131         #       OR virtual server       
132         # virtual_server = foo
133
134         #       Note that while both ipaddr and ipv6addr will accept
135         #       both addresses and host names, we do NOT recommend
136         #       using host names.  When you specify a host name, the
137         #       server has to do a DNS lookup to find the IP address
138         #       of the home server.  If the DNS server is slow or
139         #       unresponsive, it means that FreeRADIUS will NOT be
140         #       able to determine the address, and will therefore NOT
141         #       start.
142         #
143         #       Also, the mapping of host name to address is done ONCE
144         #       when the server starts.  If DNS is later updated to
145         #       change the address, FreeRADIUS will NOT discover that
146         #       until after a re-start, or a HUP.
147         #
148         #       If you specify a virtual_server here, then requests
149         #       will be proxied internally to that virtual server.
150         #       These requests CANNOT be proxied again, however.  The
151         #       intent is to have the local server handle packets
152         #       when all home servers are dead.
153         #
154         #       Requests proxied to a virtual server will be passed
155         #       through the pre-proxy and post-proxy sections, just
156         #       like any other request.  See also the sample "realm"
157         #       configuration, below.
158         #
159         #       None of the rest of the home_server configuration is used
160         #       for the "virtual_server" configuration.
161
162         #
163         #  The port to which packets are sent.
164         #
165         #  Usually 1812 for type "auth", and  1813 for type "acct".
166         #  Older servers may use 1645 and 1646.
167         #  Use 3799 for type "coa"
168         #
169         port = 1812
170
171         #
172         #  The transport protocol.
173         #
174         #  If unspecified, defaults to "udp", which is the traditional
175         #  RADIUS transport.  It may also be "tcp", in which case TCP
176         #  will be used to talk to this home server.
177         #
178         #  When home servers are put into pools, the pool can contain
179         #  home servers with both UDP and TCP transports.
180         #
181         #proto = udp
182
183         #
184         #  The shared secret use to "encrypt" and "sign" packets between
185         #  FreeRADIUS and the home server.
186         #
187         #  The secret can be any string, up to 8k characters in length.
188         #
189         #  Control codes can be entered vi octal encoding,
190         #       e.g. "\101\102" == "AB"
191         #  Quotation marks can be entered by escaping them,
192         #       e.g. "foo\"bar"
193         #  Spaces or other "special" characters can be entered
194         #  by putting quotes around the string.
195         #       e.g. "foo bar"
196         #            "foo;bar"
197         #
198         secret = testing123
199
200         ############################################################
201         #
202         #  The rest of the configuration items listed here are optional,
203         #  and do not have to appear in every home server definition.
204         #
205         ############################################################
206
207         #
208         #  You can optionally specify the source IP address used when
209         #  proxying requests to this home server.  When the src_ipaddr
210         #  it set, the server will automatically create a proxy
211         #  listener for that IP address.
212         #
213         #  If you specify this field for one home server, you will
214         #  likely need to specify it for ALL home servers.
215         #
216         #  If you don't care about the source IP address, leave this
217         #  entry commented.
218         #
219 #       src_ipaddr = 127.0.0.1
220
221         #  RFC 5080 suggests that all clients SHOULD include it in an
222         #  Access-Request.  The configuration item below tells the
223         #  proxying server (i.e. this one) whether or not the home
224         #  server requires a Message-Authenticator attribute.  If it
225         #  is required (value set to "yes"), then all Access-Request
226         #  packets sent to that home server will have a
227         #  Message-Authenticator attribute.
228         #
229         #  allowed values: yes, no
230         require_message_authenticator = no
231
232         #
233         #  If the home server does not respond to a request within
234         #  this time, this server will initiate "zombie_period".
235         #
236         #  The response window is large because responses MAY be slow,
237         #  especially when proxying across the Internet.
238         #
239         #  Useful range of values: 5 to 60
240         response_window = 20
241
242         #
243         #  If you want the old behavior of the server rejecting
244         #  proxied requests after "response_window" timeout, set
245         #  the following configuration item to "yes".
246         #
247         #  This configuration WILL be removed in a future release
248         #  If you believe you need it, email the freeradius-users
249         #  list, and explain why it should stay in the server.
250         #
251 #       no_response_fail = no
252
253         #
254         #  If the home server does not respond to ANY packets during
255         #  the "zombie period", it will be considered to be dead.
256         #
257         #  A home server that is marked "zombie" will be used for
258         #  proxying as a low priority.  If there are live servers,
259         #  they will always be preferred to a zombie.  Requests will
260         #  be proxied to a zombie server ONLY when there are no
261         #  live servers.
262         #
263         #  Any request that is proxied to a home server will continue
264         #  to be sent to that home server until the home server is
265         #  marked dead.  At that point, it will fail over to another
266         #  server, if a live server is available.  If none is available,
267         #  then the "post-proxy-type fail" handler will be called.
268         #
269         #  If "status_check" below is something other than "none", then
270         #  the server will start sending status checks at the start of
271         #  the zombie period.  It will continue sending status checks
272         #  until the home server is marked "alive".
273         #
274         #  Useful range of values: 20 to 120
275         zombie_period = 40
276
277         ############################################################
278         #
279         #  As of 2.0, FreeRADIUS supports RADIUS layer "status
280         #  checks".  These are used by a proxy server to see if a home
281         #  server is alive.
282         #
283         #  These status packets are sent ONLY if the proxying server
284         #  believes that the home server is dead.  They are NOT sent
285         #  if the proxying server believes that the home server is
286         #  alive.  They are NOT sent if the proxying server is not
287         #  proxying packets.
288         #
289         #  If the home server responds to the status check packet,
290         #  then it is marked alive again, and is returned to use.
291         #
292         ############################################################
293
294         #
295         #  Some home servers do not support status checks via the
296         #  Status-Server packet.  Others may not have a "test" user
297         #  configured that can be used to query the server, to see if
298         #  it is alive.  For those servers, we have NO WAY of knowing
299         #  when it becomes alive again.  Therefore, after the server
300         #  has been marked dead, we wait a period of time, and mark
301         #  it alive again, in the hope that it has come back to
302         #  life.
303         #
304         #  If it has NOT come back to life, then FreeRADIUS will wait
305         #  for "zombie_period" before marking it dead again.  During
306         #  the "zombie_period", ALL AUTHENTICATIONS WILL FAIL, because
307         #  the home server is still dead.  There is NOTHING that can
308         #  be done about this, other than to enable the status checks,
309         #  as documented below.
310         #
311         #  e.g. if "zombie_period" is 40 seconds, and "revive_interval"
312         #  is 300 seconds, the for 40 seconds out of every 340, or about
313         #  10% of the time, all authentications will fail.
314         #
315         #  If the "zombie_period" and "revive_interval" configurations
316         #  are set smaller, than it is possible for up to 50% of
317         #  authentications to fail.
318         #
319         #  As a result, we recommend enabling status checks, and
320         #  we do NOT recommend using "revive_interval".
321         #
322         #  The "revive_interval" is used ONLY if the "status_check"
323         #  entry below is "none".  Otherwise, it will not be used,
324         #  and should be deleted.
325         #
326         #  Useful range of values: 60 to 3600
327         revive_interval = 120
328
329         #
330         #  The proxying server (i.e. this one) can do periodic status
331         #  checks to see if a dead home server has come back alive.
332         #
333         #  If set to "none", then the other configuration items listed
334         #  below are not used, and the "revive_interval" time is used
335         #  instead.
336         #
337         #  If set to "status-server", the Status-Server packets are
338         #  sent.  Many RADIUS servers support Status-Server.  If a
339         #  server does not support it, please contact the server
340         #  vendor and request that they add it.
341         #
342         #  If set to "request", then Access-Request, or Accounting-Request
343         #  packets are sent, depending on the "type" entry above (auth/acct).
344         #  
345         #  Allowed values: none, status-server, request
346         status_check = status-server
347
348         #
349         #  If the home server does not support Status-Server packets,
350         #  then the server can still send Access-Request or
351         #  Accounting-Request packets, with a pre-defined user name.
352         #
353         #  This practice is NOT recommended, as it may potentially let
354         #  users gain network access by using these "test" accounts!
355         #
356         #  If it is used, we recommend that the home server ALWAYS
357         #  respond to these Access-Request status checks with
358         #  Access-Reject.  The status check just needs an answer, it
359         #  does not need an Access-Accept.
360         #
361         #  For Accounting-Request status checks, only the username
362         #  needs to be set.  The rest of the accounting attribute are
363         #  set to default values.  The home server that receives these
364         #  accounting packets SHOULD NOT treat them like normal user
365         #  accounting packets.  i.e It should probably NOT log them to
366         #  a database.
367         #
368         # username = "test_user_please_reject_me"
369         # password = "this is really secret"
370
371         #
372         #  Configure the interval between sending status check packets.
373         #
374         #  Setting it too low increases the probability of spurious
375         #  fail-over and fallback attempts.
376         #
377         #  Useful range of values: 6 to 120
378         check_interval = 30
379
380         #
381         #  Configure the number of status checks in a row that the
382         #  home server needs to respond to before it is marked alive.
383         #
384         #  If you want to mark a home server as alive after a short
385         #  time period of being responsive, it is best to use a small
386         #  "check_interval", and a large value for
387         #  "num_answers_to_alive".  Using a long "check_interval" and
388         #  a small number for "num_answers_to_alive" increases the
389         #  probability of spurious fail-over and fallback attempts.
390         #
391         #  Useful range of values: 3 to 10
392         num_answers_to_alive = 3
393
394         #
395         #  The configuration items in the next sub-section are used ONLY
396         #  when "type = coa".  It is ignored for all other type of home
397         #  servers.
398         #
399         #  See RFC 5080 for the definitions of the following terms.
400         #  RAND is a function (internal to FreeRADIUS) returning
401         #  random numbers between -0.1 and +0.1
402         #
403         #  First Re-transmit occurs after:
404         #
405         #        RT = IRT + RAND*IRT
406         #
407         #  Subsequent Re-transmits occur after:
408         #
409         #       RT = 2 * RTprev + RAND * RTprev
410         #
411         #  Re-trasnmits are capped at:
412         #
413         #       if (MRT && (RT > MRT)) RT = MRT + RAND * MRT
414         #
415         #  For a maximum number of attempts: MRC
416         #
417         #  For a maximum (total) period of time: MRD.
418         #
419         coa {
420                 # Initial retransmit interval: 1..5
421                 irt = 2
422
423                 # Maximum Retransmit Timeout: 1..30 (0 == no maximum)
424                 mrt = 16
425
426                 # Maximum Retransmit Count: 1..20 (0 == retransmit forever)
427                 mrc = 5
428
429                 # Maximum Retransmit Duration: 5..60
430                 mrd = 30
431         }
432
433         #
434         #  Connection limiting for home servers with "proto = tcp".
435         #
436         #  This section is ignored for other home servers.
437         #
438         limit {
439               #
440               #  Limit the number of TCP connections to the home server.
441               #
442               #  The default is 16.
443               #  Setting this to 0 means "no limit"
444               max_connections = 16
445
446               #
447               #  Limit the total number of requests sent over one
448               #  TCP connection.  After this number of requests, the
449               #  connection will be closed.  Any new packets that are
450               #  proxied to the home server will result in a new TCP
451               #  connection being made.
452               #
453               #  Setting this to 0 means "no limit"
454               max_requests = 0
455
456               #
457               #  The lifetime, in seconds, of a TCP connection.  After
458               #  this lifetime, the connection will be closed.
459               #
460               #  Setting this to 0 means "forever".
461               lifetime = 0
462
463               #
464               #  The idle timeout, in seconds, of a TCP connection.
465               #  If no packets have been sent over the connection for
466               #  this time, the connection will be closed.
467               #
468               #  Setting this to 0 means "no timeout".
469               idle_timeout = 0
470         }
471
472 }
473
474 # Sample virtual home server.
475 home_server virtual.example.com {
476             virtual_server = virtual.example.com
477 }
478
479 ######################################################################
480 #
481 #  This section defines a pool of home servers that is used
482 #  for fail-over and load-balancing.  In earlier versions of
483 #  FreeRADIUS, fail-over and load-balancing were defined per-realm.
484 #  As a result, if a server had 5 home servers, each of which served
485 #  the same 10 realms, you would need 50 "realm" entries.
486 #
487 #  In version 2.0, you would need 5 "home_server" sections,
488 #  10 'realm" sections, and one "home_server_pool" section to tie the
489 #  two together.
490 #
491 home_server_pool my_auth_failover {
492         #
493         #  The type of this pool controls how home servers are chosen.
494         #
495         #  fail-over - the request is sent to the first live
496         #       home server in the list.  i.e. If the first home server
497         #       is marked "dead", the second one is chosen, etc.
498         #
499         #  load-balance - the least busy home server is chosen,
500         #       where "least busy" is counted by taking the number of
501         #       requests sent to that home server, and subtracting the
502         #       number of responses received from that home server.
503         #
504         #       If there are two or more servers with the same low
505         #       load, then one of those servers is chosen at random.
506         #       This configuration is most similar to the old
507         #       "round-robin" method, though it is not exactly the same.
508         #
509         #       Note that load balancing does not work well with EAP,
510         #       as EAP requires packets for an EAP conversation to be
511         #       sent to the same home server.  The load balancing method
512         #       does not keep state in between packets, meaning that
513         #       EAP packets for the same conversation may be sent to
514         #       different home servers.  This will prevent EAP from
515         #       working.
516         #
517         #       For non-EAP authentication methods, and for accounting
518         #       packets, we recommend using "load-balance".  It will
519         #       ensure the highest availability for your network.
520         #
521         #  client-balance - the home server is chosen by hashing the
522         #       source IP address of the packet.  If that home server
523         #       is down, the next one in the list is used, just as
524         #       with "fail-over".
525         #
526         #       There is no way of predicting which source IP will map
527         #       to which home server.
528         #
529         #       This configuration is most useful to do simple load
530         #       balancing for EAP sessions, as the EAP session will
531         #       always be sent to the same home server.
532         #
533         #  client-port-balance - the home server is chosen by hashing
534         #       the source IP address and source port of the packet.
535         #       If that home server is down, the next one in the list
536         #       is used, just as with "fail-over".
537         #
538         #       This method provides slightly better load balancing
539         #       for EAP sessions than "client-balance".  However, it
540         #       also means that authentication and accounting packets
541         #       for the same session MAY go to different home servers.
542         #
543         #  keyed-balance - the home server is chosen by hashing (FNV)
544         #       the contents of the Load-Balance-Key attribute from the
545         #       control items.  The  request is then sent to home server
546         #       chosen by taking:
547         #
548         #               server = (hash % num_servers_in_pool).
549         #
550         #       If there is no Load-Balance-Key in the control items,
551         #       the load balancing method is identical to "load-balance".
552         #
553         #       For most non-EAP authentication methods, The User-Name
554         #       attribute provides a good key.  An "unlang" policy can
555         #       be used to copy the User-Name to the Load-Balance-Key
556         #       attribute.  This method may not work for EAP sessions,
557         #       as the User-Name outside of the TLS tunnel is often
558         #       static, e.g. "anonymous@realm".
559         #
560         #
561         #  The default type is fail-over.
562         type = fail-over
563
564         #
565         #  A virtual_server may be specified here.  If so, the
566         #  "pre-proxy" and "post-proxy" sections are called when
567         #  the request is proxied, and when a response is received.
568         #
569         #  This lets you have one policy for all requests that are proxied
570         #  to a home server.  This policy is completely independent of
571         #  any policies used to receive, or process the request.
572         #
573         #virtual_server = pre_post_proxy_for_pool
574
575         #
576         #  Next, a list of one or more home servers.  The names
577         #  of the home servers are NOT the hostnames, but the names
578         #  of the sections.  (e.g. home_server foo {...} has name "foo".
579         #
580         #  Note that ALL home servers listed here have to be of the same
581         #  type.  i.e. they all have to be "auth", or they all have to
582         #  be "acct", or the all have to be "auth+acct".
583         #
584         home_server = localhost
585
586         #  Additional home servers can be listed.
587         #  There is NO LIMIT to the number of home servers that can
588         #  be listed, though using more than 10 or so will become
589         #  difficult to manage.
590         #
591         # home_server = foo.example.com
592         # home_server = bar.example.com
593         # home_server = baz.example.com
594         # home_server = ...
595
596
597         #
598         #  If ALL home servers are dead, then this "fallback" home server
599         #  is used.  If set, it takes precedence over any realm-based
600         #  fallback, such as the DEFAULT realm.
601         #
602         #  For reasons of stability, this home server SHOULD be a virtual
603         #  server.  Otherwise, the fallback may itself be dead!
604         #
605         #fallback = virtual.example.com
606 }
607
608 ######################################################################
609 #
610 #
611 #  This section defines a new-style "realm".  Note the in version 2.0,
612 #  there are many fewer configuration items than in 1.x for a realm.
613 #
614 #  Automatic proxying is done via the "realms" module (see "man
615 #  rlm_realm").  To manually proxy the request put this entry in the
616 #  "users" file:
617
618 #
619 #
620 #DEFAULT        Proxy-To-Realm := "realm_name"
621 #
622 #
623 realm example.com {
624         #
625         #  Realms point to pools of home servers.
626 #
627         #  For authentication, the "auth_pool" configuration item
628         #  should point to a "home_server_pool" that was previously
629         #  defined.  All of the home servers in the "auth_pool" must
630         #  be of type "auth".
631         #
632         #  For accounting, the "acct_pool" configuration item
633         #  should point to a "home_server_pool" that was previously
634         #  defined.  All of the home servers in the "acct_pool" must
635         #  be of type "acct".
636         #
637         #  If you have a "home_server_pool" where all of the home servers
638         #  are of type "auth+acct", you can just use the "pool"
639         #  configuration item, instead of specifying both "auth_pool"
640         #  and "acct_pool".
641
642         auth_pool = my_auth_failover
643 #       acct_pool = acct
644
645         #
646         #  Normally, when an incoming User-Name is matched against the
647         #  realm, the realm name is "stripped" off, and the "stripped"
648         #  user name is used to perform matches.
649         #
650         #  e.g. User-Name = "bob@example.com" will result in two new
651         #  attributes being created by the "realms" module:
652         #
653         #       Stripped-User-Name = "bob"
654         #       Realm = "example.com"
655         #
656         #  The Stripped-User-Name is then used as a key in the "users"
657         #  file, for example.
658         #
659         #  If you do not want this to happen, uncomment "nostrip" below.
660         #
661         # nostrip
662
663         #  There are no more configuration entries for a realm.
664 }
665
666
667 #
668 #  This is a sample entry for iPass.
669 #  Note that you have to define "ipass_auth_pool" and
670 #  "ipass_acct_pool", along with home_servers for them, too.
671 #
672 #realm IPASS {
673 #       nostrip
674 #
675 #       auth_pool = ipass_auth_pool
676 #       acct_pool = ipass_acct_pool
677 #}
678
679 #
680 #  This realm is used mainly to cancel proxying.  You can have
681 #  the "realm suffix" module configured to proxy all requests for
682 #  a realm, and then later cancel the proxying, based on other
683 #  configuration.
684 #
685 #  For example, you want to terminate PEAP or EAP-TTLS locally,
686 #  you can add the following to the "users" file:
687 #
688 #  DEFAULT EAP-Type == PEAP, Proxy-To-Realm := LOCAL
689 #
690 realm LOCAL {
691         #  If we do not specify a server pool, the realm is LOCAL, and
692         #  requests are not proxied to it.
693 }
694
695 #
696 #  This realm is for requests which don't have an explicit realm
697 #  prefix or suffix.  User names like "bob" will match this one.
698 #
699 #realm NULL {
700 #       authhost        = radius.company.com:1600
701 #       accthost        = radius.company.com:1601
702 #       secret          = testing123
703 #}
704
705 #
706 #  This realm is for ALL OTHER requests.
707 #
708 #realm DEFAULT {
709 #       authhost        = radius.company.com:1600
710 #       accthost        = radius.company.com:1601
711 #       secret          = testing123
712 #}
713
714
715 #  This realm "proxies" requests internally to a virtual server.
716 #  The pre-proxy and post-proxy sections are run just as with any
717 #  other kind of home server.  The virtual server then receives
718 #  the request, and replies, just as with any other packet.
719 #
720 #  Once proxied internally like this, the request CANNOT be proxied
721 #  internally or externally.
722 #
723 #realm virtual.example.com {
724 #       virtual_server = virtual.example.com
725 #}
726 #
727
728 #
729 #  Regular expressions may also be used as realm names.  If these are used,
730 #  then the "find matching realm" process is as follows:
731 #
732 #    1) Look for a non-regex realm with an *exact* match for the name.
733 #       If found, it is used in preference to any regex matching realm.
734 #
735 #    2) Look for a regex realm, in the order that they are listed
736 #       in the configuration files.  Any regex match is performed in
737 #       a case-insensitive fashion.
738 #
739 #    3) If no realm is found, return the DEFAULT realm, if any.
740 #
741 #  The order of the realms matters in step (2).  For example, defining
742 #  two realms "*.example.com" and "*.test.example.com" will result in
743 #  the second realm NEVER matching.  This is because all of the realms
744 #  which match the second regex also match the first one.  Since the
745 #  first regex matches, it is returned.
746 #
747 #  The solution is to list the realms in the opposite order,. e.g.
748 #  "*.test.example.com", followed by "*.example.com".
749 #
750 #
751 #  Some helpful rules:
752 #
753 #   - always place a '~' character at the start of the realm name.
754 #     This signifies that it is a regex match, and not an exact match
755 #     for the realm.
756 #
757 #   - place the regex in double quotes.  This helps the configuration
758 #     file parser ignore any "special" characters in the regex.
759 #     Yes, this rule is different than the normal "unlang" rules for
760 #     regular expressions.  That may be fixed in a future release.
761 #
762 #   - use two back-slashes '\\' whenever you need one backslash in the
763 #     regex.  e.g. "~*\\.example\\.com", and not "~*\.example\.com".
764 #     This is because the regex is in a double-quoted string, and normal
765 #     rules apply for double-quoted strings.
766 #
767 #   - If you are matching domain names, use two backslashes in front of
768 #     every '.' (dot or period).  This is because '.' has special meaning
769 #     in a regular expression: match any character.  If you do not do this,
770 #     then "~*.example.com" will match "fooXexampleYcom", which is likely
771 #     not what you want
772 #
773 #   - If you are matching domain names, put a '$' at the end of the regex
774 #     that matches the domain name.  This tells the regex matching code
775 #     that the realm ENDS with the domain name, so it does not match
776 #     realms with the domain name in the middle.  e.g. "~*\\.example\\.com"
777 #     will match "test.example.comFOO", which is likely not what you want.
778 #     Using "~*\\.example\\.com$" is better.
779 #
780 #  The more regex realms that are defined, the more time it takes to
781 #  process them.  You should define as few regex realms as possible
782 #  in order to maximize server performance.
783 #
784 #realm "~*\\.example\\.com$" {
785 #      authhost = LOCAL      # not strictly necessary
786 #      accthost = LOCAL      # not strictly necessary
787 #}