1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
|
<!-- Creator : groff version 1.22.2 -->
<!-- CreationDate: Thu Sep 17 10:29:24 2015 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>radsecproxy.conf</title>
</head>
<body>
<h1 align="center">radsecproxy.conf</h1>
<a href="#NAME">NAME</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#CONFIGURATION SYNTAX">CONFIGURATION SYNTAX</a><br>
<a href="#BASIC OPTIONS">BASIC OPTIONS</a><br>
<a href="#BLOCKS">BLOCKS</a><br>
<a href="#CLIENT BLOCK">CLIENT BLOCK</a><br>
<a href="#SERVER BLOCK">SERVER BLOCK</a><br>
<a href="#REALM BLOCK">REALM BLOCK</a><br>
<a href="#TLS BLOCK">TLS BLOCK</a><br>
<a href="#REWRITE BLOCK">REWRITE BLOCK</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">radsecproxy.conf
− Radsec proxy configuration file</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">When the proxy
server starts, it will first check the command line
arguments, and then read the configuration file. Normally
radsecproxy will read the configuration file
<i>/usr/local/etc/radsecproxy.conf</i>. The command line
<b>−c</b> option can be used to instead read an
alternate file (see <b>radsecproxy</b>(1) for details).</p>
<p style="margin-left:11%; margin-top: 1em">If the
configuration file can not be found, the proxy will exit
with an error message. Note that there is also an include
facility so that any configuration file may include other
configuration files. The proxy will also exit on
configuration errors.</p>
<h2>CONFIGURATION SYNTAX
<a name="CONFIGURATION SYNTAX"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">When the
configuration file is processed, whitespace (spaces and
tabs) are generally ignored. For each line, leading and
trailing whitespace are ignored. A line is ignored if it is
empty, only consists of whitespace, or if the first
non-whitespace character is a #. The configuration is
generally case insensitive, but in some cases the option
values (see below) are not.</p>
<p style="margin-left:11%; margin-top: 1em">There are two
types of configuration structures than can be used. The
first and simplest are lines on the format <i>option
value</i>. That is, an option name, see below for a list of
valid options, followed by whitespace (at least one space or
tab character), followed by a value. Note that if the value
contains whitespace, then it must be quoted using
"" or ’’. Any whitespace in front of
the option or after the value will be ignored.</p>
<p style="margin-left:11%; margin-top: 1em">The other type
of structure is a block. A block spans at least two lines,
and has the format:</p>
<p style="margin-left:22%; margin-top: 1em">blocktype name
{ <br>
option value <br>
option value <br>
... <br>
}</p>
<p style="margin-left:11%; margin-top: 1em">That is, some
blocktype, see below for a list of the different block
types, and then enclosed in braces you have zero or more
lines that each have the previously described <i>option
value</i> format. Different block types have different rules
for which options can be specified, they are listed below.
The rules regarding white space, comments and quotes are as
above. Hence you may do things like:</p>
<p style="margin-left:22%; margin-top: 1em">blocktype name
{ <br>
# option value <br>
option "value with space" <br>
... <br>
}</p>
<p style="margin-left:11%; margin-top: 1em">Option value
characters can also be written in hex. This is done by
writing the character % followed by two hexadecimal digits.
If a % is used without two following hexadecimal digits, the
% and the following characters are used as written. If you
want to write a % and not use this decoding, you may of
course write % in hex; i.e., %25.</p>
<p style="margin-left:11%; margin-top: 1em">There is one
special option that can be used both as a basic option and
inside all blocks. That is the option Include where the
value specifies files to be included. The value can be a
single file, or it can use normal shell globbing to specify
multiple files, e.g.:</p>
<p style="margin-left:22%;">include
/usr/local/etc/radsecproxy.conf.d/*.conf</p>
<p style="margin-left:11%; margin-top: 1em">The files are
sorted alphabetically. Included files are read in the order
they are specified, when reaching the end of a file, the
next file is read. When reaching the end of the last
included file, the proxy returns to read the next line
following the Include option. Included files may again
include other files.</p>
<h2>BASIC OPTIONS
<a name="BASIC OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The following
basic options may be specified in the configuration file.
Note that blocktypes and options inside blocks are discussed
later. Note that none of these options are required, and
indeed in many cases they are not needed. Note that you
should specify each at most once. The behaviour with
multiple occurences is undefined. <br>
PidFile</p>
<p style="margin-left:22%;">The PidFile option specifies
the name of a file to which the process id (PID) will be
written. This is overridden by the <b>−i</b> command
line option. There is no default value for the PidFile
option.</p>
<p style="margin-left:11%;">LogLevel</p>
<p style="margin-left:22%;">This option specifies the debug
level. It must be set to 1, 2, 3, 4 or 5, where 1 logs only
serious errors, and 5 logs everything. The default is 2
which logs errors, warnings and a few informational
messages. Note that the command line option <b>−d</b>
overrides this.</p>
<p style="margin-left:11%;">LogDestination</p>
<p style="margin-left:22%;">This specifies where the log
messages should go. By default the messages go to syslog
with facility LOG_DAEMON. Using this option you can specify
another syslog facility, or you may specify that logging
should be to a particular file, not using syslog. The value
must be either a file or syslog URL. The file URL is the
standard one, specifying a local file that should be used.
For syslog, you must use the syntax:
x−syslog:///FACILITY where FACILITY must be one of
LOG_DAEMON, LOG_MAIL, LOG_USER, LOG_LOCAL0, LOG_LOCAL1,
LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6
or LOG_LOCAL7. You may omit the facility from the URL to
specify logging to the default facility, but this is not
very useful since this is the default log destination. Note
that this option is ignored if <b>−f</b> is specified
on the command line.</p>
<p style="margin-left:11%;">FTicksReporting</p>
<p style="margin-left:22%;">The FTicksReporting option is
used to enable F-Ticks logging and can be set to None, Basic
or Full. Its default value is None. If FTicksReporting is
set to anything other than None, note that the default value
for FTicksMAC is VendorKeyHashed which needs FTicksKey to be
set.</p>
<p style="margin-left:22%; margin-top: 1em">See
radsecproxy.conf−example for details. Note that
radsecproxy has to be configured with F-Ticks support
(−−enable−fticks) for this option to have
any effect.</p>
<p style="margin-left:11%;">FTicksMAC</p>
<p style="margin-left:22%;">The FTicksMAC option can be
used to control if and how Calling-Station-Id (the users
Ethernet MAC address) is being logged. It can be set to one
of Static, Original, VendorHashed, VendorKeyHashed,
FullyHashed or FullyKeyHashed.</p>
<p style="margin-left:22%; margin-top: 1em">The default
value for FTicksMAC is VendorKeyHashed. This means that
FTicksKey has to be set.</p>
<p style="margin-left:22%; margin-top: 1em">Before chosing
any of Original, FullyHashed or VendorHashed, consider the
implications for user privacy when MAC addresses are
collected. How will the logs be stored, transferred and
accessed?</p>
<p style="margin-left:22%; margin-top: 1em">See
radsecproxy.conf−example for details. Note that
radsecproxy has to be configured with F-Ticks support
(−−enable−fticks) for this option to have
any effect.</p>
<p style="margin-left:11%;">FTicksKey</p>
<p style="margin-left:22%;">The FTicksKey option is used to
specify the key to use when producing HMAC’s as an
effect of specifying VendorKeyHashed or FullyKeyHashed for
the FTicksMAC option.</p>
<p style="margin-left:22%; margin-top: 1em">Note that
radsecproxy has to be configured with F-Ticks support
(−−enable−fticks) for this option to have
any effect.</p>
<p style="margin-left:11%;">FTicksSyslogFacility</p>
<p style="margin-left:22%;">The FTicksSyslogFacility option
is used to specify a dedicated syslog facility for F-Ticks
messages. This allows for easier filtering of F-Ticks
messages. If no FTicksSyslogFacility option is given,
F-Ticks messages are written to what the LogDestination
option specifies.</p>
<p style="margin-left:22%; margin-top: 1em">F-Ticks
messages are always logged using the log level LOG_DEBUG.
Note that specifying a file in FTicksSyslogFacility (using
the file:/// prefix) is not supported.</p>
<p style="margin-left:11%;">ListenUDP</p>
<p style="margin-left:22%;">Normally the proxy will listen
to the standard RADIUS UDP port 1812 if configured to handle
UDP clients. On most systems it will do this for all of the
system’s IP addresses (both IPv4 and IPv6). On some
systems however, it may respond to only IPv4 or only IPv6.
To specify an alternate port you may use a value on the form
*:port where port is any valid port number. If you also want
to specify a specific address you can do e.g.
192.168.1.1:1812 or [2001:db8::1]:1812. The port may be
omitted if you want the default one (like in these
examples). These examples are equivalent to 192.168.1.1 and
2001:db8::1. Note that you must use brackets around the IPv6
address. This option may be specified multiple times to
listen to multiple addresses and/or ports.</p>
<p style="margin-left:11%;">ListenTCP</p>
<p style="margin-left:22%;">This option is similar to the
ListenUDP option, except that it is used for receiving
connections from TCP clients. The default port number is
1812.</p>
<p style="margin-left:11%;">ListenTLS</p>
<p style="margin-left:22%;">This is similar to the
ListenUDP option, except that it is used for receiving
connections from TLS clients. The default port number is
2083. Note that this option was previously called
ListenTCP.</p>
<p style="margin-left:11%;">ListenDTLS</p>
<p style="margin-left:22%;">This is similar to the
ListenUDP option, except that it is used for receiving
connections from DTLS clients. The default port number is
2083.</p>
<p style="margin-left:11%;">SourceUDP</p>
<p style="margin-left:22%;">This can be used to specify
source address and/or source port that the proxy will use
for sending UDP client messages (e.g. Access Request).</p>
<p style="margin-left:11%;">SourceTCP</p>
<p style="margin-left:22%;">This can be used to specify
source address and/or source port that the proxy will use
for TCP connections.</p>
<p style="margin-left:11%;">SourceTLS</p>
<p style="margin-left:22%;">This can be used to specify
source address and/or source port that the proxy will use
for TLS connections.</p>
<p style="margin-left:11%;">SourceDTLS</p>
<p style="margin-left:22%;">This can be used to specify
source address and/or source port that the proxy will use
for DTLS connections.</p>
<p style="margin-left:11%;">TTLAttribute</p>
<p style="margin-left:22%;">This can be used to change the
default TTL attribute. Only change this if you know what you
are doing. The syntax is either a numerical value denoting
the TTL attribute, or two numerical values separated by
column specifying a vendor attribute, i.e.
vendorid:attribute.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p>AddTTL</p></td>
<td width="2%"></td>
<td width="78%">
<p>If a TTL attribute is present, the proxy will decrement
the value and discard the message if zero. Normally the
proxy does nothing if no TTL attribute is present. If you
use the AddTTL option with a value 1-255, the proxy will
when forwarding a message with no TTL attribute, add one
with the specified value. Note that this option can also be
specified for a client/server. It will then override this
setting when forwarding a message to that client/server.</p></td></tr>
</table>
<p style="margin-left:11%;">LoopPrevention</p>
<p style="margin-left:22%;">This can be set to on or off
with off being the default. When this is enabled, a request
will never be sent to a server named the same as the client
it was received from. I.e., the names of the client block
and the server block are compared. Note that this only gives
limited protection against loops. It can be used as a basic
option and inside server blocks where it overrides the basic
setting.</p>
<p style="margin-left:11%;">IPv4Only and IPv6Only</p>
<p style="margin-left:22%;">These can be set to on or off
with off being the default. At most one of IPv4Only and
IPv6Only can be enabled. Enabling IPv4Only or IPv6Only makes
radsecproxy resolve DNS names to the corresponding address
family only, and not the other. This is done for both
clients and servers. Note that this can be overridden in
client and server blocks, see below.</p>
<p style="margin-left:11%;">Include</p>
<p style="margin-left:22%;">This is not a normal
configuration option; it can be specified multiple times. It
can both be used as a basic option and inside blocks. For
the full description, see the configuration syntax section
above.</p>
<h2>BLOCKS
<a name="BLOCKS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">There are five
types of blocks, they are client, server, realm, tls and
rewrite. At least one instance of each of client and realm
is required. This is necessary for the proxy to do anything
useful, and it will exit if not. The tls block is required
if at least one TLS/DTLS client or server is configured.
Note that there can be multiple blocks for each type. For
each type, the block names should be unique. The behaviour
with multiple occurences of the same name for the same block
type is undefined. Also note that some block option values
may reference a block by name, in which case the block name
must be previously defined. Hence the order of the blocks
may be significant.</p>
<h2>CLIENT BLOCK
<a name="CLIENT BLOCK"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The client
block is used to configure a client. That is, tell the proxy
about a client, and what parameters should be used for that
client. The name of the client block must (with one
exception, see below) be either the IP address (IPv4 or
IPv6) of the client, an IP prefix (IPv4 or IPv6) on the form
IpAddress/PrefixLength, or a domain name (FQDN). The way an
FQDN is resolved into an IP address may be influenced by the
use of the IPv4Only and IPv6Only options. Note that literal
IPv6 addresses must be enclosed in brackets.</p>
<p style="margin-left:11%; margin-top: 1em">If a domain
name is specified, then this will be resolved immediately to
all the addresses associated with the name, and the proxy
will not care about any possible DNS changes that might
occur later. Hence there is no dependency on DNS after
startup.</p>
<p style="margin-left:11%; margin-top: 1em">When some
client later sends a request to the proxy, the proxy will
look at the IP address the request comes from, and then go
through all the addresses of each of the configured clients
(in the order they are defined), to determine which (if any)
of the clients this is.</p>
<p style="margin-left:11%; margin-top: 1em">In the case of
TLS/DTLS, the name of the client must match the FQDN or IP
address in the client certificate. Note that this is not
required when the client name is an IP prefix.</p>
<p style="margin-left:11%; margin-top: 1em">Alternatively
one may use the host option inside a client block. In that
case, the value of the host option is used as above, while
the name of the block is only used as a descriptive name for
the administrator. The host option may be used multiple
times, and can be a mix of addresses, FQDNs and
prefixes.</p>
<p style="margin-left:11%; margin-top: 1em">The allowed
options in a client block are host, IPv4Only, IPv6Only,
type, secret, tls, certificateNameCheck,
matchCertificateAttribute, duplicateInterval, AddTTL,
fticksVISCOUNTRY, fticksVISINST, rewrite, rewriteIn,
rewriteOut, and rewriteAttribute. We already discussed the
host option. To specify how radsecproxy should resolve a
host given as a DNS name, the IPv4Only or the IPv6Only can
be set to on. At most one of these options can be enabled.
Enabling IPv4Only or IPv6Only here overrides any basic
settings set at the top level. The value of type must be one
of udp, tcp, tls or dtls. The value of secret is the shared
RADIUS key used with this client. If the secret contains
whitespace, the value must be quoted. This option is
optional for TLS/DTLS and if omitted will default to
"radsec". (Note that using a secret other than
"radsec" for TLS is a violation of the standard
(RFC 6614) and that the proposed standard for DTLS
stipulates that the secret must be
"radius/dtls".)</p>
<p style="margin-left:11%; margin-top: 1em">For a TLS/DTLS
client you may also specify the tls option. The option value
must be the name of a previously defined TLS block. If this
option is not specified, the TLS block with the name
defaultClient will be used if defined. If not defined, it
will try to use the TLS block named default. If the
specified TLS block name does not exist, or the option is
not specified and none of the defaults exist, the proxy will
exit with an error. NOTE: All versions of radsecproxy up to
and including 1.6 erroneously verify client certificate
chains using the CA in the very first matching client block
regardless of which block is used for the final decision.
This was changed in version 1.6.1 so that a client block
with a different tls option than the first matching client
block is no longer considered for verification of
clients.</p>
<p style="margin-left:11%; margin-top: 1em">For a TLS/DTLS
client, the option certificateNameCheck can be set to off,
to disable the default behaviour of matching CN or
SubjectAltName against the specified hostname or IP
address.</p>
<p style="margin-left:11%; margin-top: 1em">Additional
validation of certificate attributes can be done by use of
the matchCertificateAttribute option. Currently one can only
do some matching of CN and SubjectAltName. For regexp
matching on CN, one can use the value CN:/regexp/. For
SubjectAltName one can only do regexp matching of the URI,
this is specified as SubjectAltName:URI:/regexp/. Note that
currently this option can only be specified once in a client
block.</p>
<p style="margin-left:11%; margin-top: 1em">The
duplicateInterval option can be used to specify for how many
seconds duplicate checking should be done. If a proxy
receives a new request within a few seconds of a previous
one, it may be treated the same if from the same client,
with the same authenticator etc. The proxy will then ignore
the new request (if it is still processing the previous
one), or returned a copy of the previous reply.</p>
<p style="margin-left:11%; margin-top: 1em">The AddTTL
option is similar to the AddTTL option used in the basic
config. See that for details. Any value configured here
overrides the basic one when sending messages to this
client.</p>
<p style="margin-left:11%; margin-top: 1em">The
fticksVISCOUNTRY option configures clients eligible to
F-Ticks logging as defined by the FTicksReporting basic
option.</p>
<p style="margin-left:11%; margin-top: 1em">The
fticksVISINST option overwrites the default VISINST value
taken from the client block name.</p>
<p style="margin-left:11%; margin-top: 1em">The rewrite
option is deprecated. Use rewriteIn instead.</p>
<p style="margin-left:11%; margin-top: 1em">The rewriteIn
option can be used to refer to a rewrite block that
specifies certain rewrite operations that should be
performed on incoming messages from the client. The
rewriting is done before other processing. For details, see
the rewrite block text below. Similarly to tls discussed
above, if this option is not used, there is a fallback to
using the rewrite block named defaultClient if it exists;
and if not, a fallback to a block named default.</p>
<p style="margin-left:11%; margin-top: 1em">The rewriteOut
option is used in the same way as rewriteIn, except that it
specifies rewrite operations that should be performed on
outgoing messages to the client. The rewriting is done after
other processing. Also, there is no rewrite fallback if this
option is not used.</p>
<p style="margin-left:11%; margin-top: 1em">The
rewriteAttribute option currently makes it possible to
specify that the User-Name attribute in a client request
shall be rewritten in the request sent by the proxy. The
User-Name attribute is written back to the original value if
a matching response is later sent back to the client. The
value must be on the form
User-Name:/regexpmatch/replacement/. Example usage:</p>
<p style="margin-left:22%;">rewriteAttribute
User-Name:/^(.*)@local$/\1@example.com/</p>
<h2>SERVER BLOCK
<a name="SERVER BLOCK"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The server
block is used to configure a server. That is, tell the proxy
about a server, and what parameters should be used when
communicating with that server. The name of the server block
must (with one exception, see below) be either the IP
address (IPv4 or IPv6) of the server, or a domain name
(FQDN). If a domain name is specified, then this will be
resolved immediately to all the addresses associated with
the name, and the proxy will not care about any possible DNS
changes that might occur later. Hence there is no dependency
on DNS after startup. If the domain name resolves to
multiple addresses, then for UDP/DTLS the first address is
used. For TCP/TLS, the proxy will loop through the addresses
until it can connect to one of them. The way an FQDN is
resolved into an IP address may be influenced by the use of
the IPv4Only and IPv6Only options. In the case of TLS/DTLS,
the name of the server must match the FQDN or IP address in
the server certificate.</p>
<p style="margin-left:11%; margin-top: 1em">Alternatively
one may use the host option inside a server block. In that
case, the value of the host option is used as above, while
the name of the block is only used as a descriptive name for
the administrator. Note that multiple host options may be
used. This will then be treated as multiple names/addresses
for the same server. When initiating a TCP/TLS connection,
all addresses of all names may be attempted, but there is no
failover between the different host values. For failover one
must use separate server blocks.</p>
<p style="margin-left:11%; margin-top: 1em">Note that the
name of the block, or values of host options may include a
port number (separated with a column). This port number will
then override the default port or a port option in the
server block. Also note that literal IPv6 addresses must be
enclosed in brackets.</p>
<p style="margin-left:11%; margin-top: 1em">The allowed
options in a server block are host, port, IPv4Only,
IPv6Only, type, secret, tls, certificateNameCheck,
matchCertificateAttribute, AddTTL, rewrite, rewriteIn,
rewriteOut, statusServer, retryCount, dynamicLookupCommand
and retryInterval and LoopPrevention.</p>
<p style="margin-left:11%; margin-top: 1em">We already
discussed the host option. To specify how radsecproxy should
resolve a host given as a DNS name, the IPv4Only or the
IPv6Only can be set to on. At most one of these options can
be enabled. Enabling IPv4Only or IPv6Only here overrides any
basic settings set at the top level. The port option allows
you to specify which port number the server uses. The usage
of type, secret, tls, certificateNameCheck,
matchCertificateAttribute, AddTTL, rewrite, rewriteIn and
rewriteOut are just as specified for the client block above,
except that defaultServer (and not defaultClient) is the
fallback for the tls, rewrite and rewriteIn options.</p>
<p style="margin-left:11%; margin-top: 1em">statusServer
can be specified to enable the use of status-server messages
for this server. The value must be either on or off. The
default when not specified, is off. If statusserver is
enabled, the proxy will during idle periods send regular
status-server messages to the server to verify that it is
alive. This should only be enabled if the server supports
it.</p>
<p style="margin-left:11%; margin-top: 1em">The options
retryCount and retryInterval can be used to specify how many
times the proxy should retry sending a request and how long
it should wait between each retry. The defaults are 2
retries and an interval of 5s.</p>
<p style="margin-left:11%; margin-top: 1em">The option
dynamicLookupCommand can be used to specify a command that
should be executed to dynamically configure a server. The
executable file should be given with full path and will be
invoked with the name of the realm as its first and only
argument. It should either print a valid server option on
stdout and exit with a code of 0 or print nothing and exit
with a non-zero exit code. An example of a shell script
resolving the DNS NAPTR records for the realm and then the
SRV records for each NAPTR matching
’x-eduroam:radius.tls’ is provided in
tools/naptr−eduroam.sh. This option was added in
radsecproxy-1.3 but tends to crash radsecproxy versions
earlier than 1.6.</p>
<p style="margin-left:11%; margin-top: 1em">Using the
LoopPrevention option here overrides any basic setting of
this option. See section BASIC OPTIONS for details on this
option.</p>
<h2>REALM BLOCK
<a name="REALM BLOCK"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">When the proxy
receives an Access-Request it needs to figure out to which
server it should be forwarded. This is done by looking at
the Username attribute in the request, and matching that
against the names of the defined realm blocks. The proxy
will match against the blocks in the order they are
specified, using the first match if any. If no realm
matches, the proxy will simply ignore the request. Each
realm block specifies what the server should do when a match
is found. A realm block may contain none, one or multiple
server options, and similarly accountingServer options.
There are also replyMessage and accountingResponse options.
We will discuss these later.</p>
<p style="margin-left:11%; margin-top: 1em"><b>REALM BLOCK
NAMES AND MATCHING</b> <br>
In the general case the proxy will look for a @ in the
username attribute, and try to do an exact case insensitive
match between what comes after the @ and the name of the
realm block. So if you get a request with the attribute
value anonymous@example.com, the proxy will go through the
realm names in the order they are specified, looking for a
realm block named example.com.</p>
<p style="margin-left:11%; margin-top: 1em">There are two
exceptions to this, one is the realm name * which means
match everything. Hence if you have a realm block named *,
then it will always match. This should then be the last
realm block defined, since any blocks after this would never
be checked. This is useful for having a default.</p>
<p style="margin-left:11%; margin-top: 1em">The other
exception is regular expression matching. If the realm name
starts with a /, the name is treated as an regular
expression. A case insensitive regexp match will then be
done using this regexp on the value of the entire Username
attribute. Optionally you may also have a trailing / after
the regexp. So as an example, if you want to use regexp
matching the domain example.com you could have a realm block
named /@example\\.com$. Optinally this can also be written
/@example\\.com$/. If you want to match all domains under
the .com top domain, you could do /@.*\\.com$. Note that
since the matching is done on the entire attribute value,
you can also use rules like /^[a−k].*@example\\.com$/
to get some of the users in this domain to use one server,
while other users could be matched by another realm block
and use another server.</p>
<p style="margin-left:11%; margin-top: 1em"><b>REALM BLOCK
OPTIONS</b> <br>
A realm block may contain none, one or multiple server
options. If defined, the values of the server options must
be the names of previously defined server blocks. Normally
requests will be forwarded to the first server option
defined. If there are multiple server options, the proxy
will do fail-over and use the second server if the first is
down. If the two first are down, it will try the third etc.
If say the first server comes back up, it will go back to
using that one. Currently detection of servers being up or
down is based on the use of StatusServer (if enabled), and
that TCP/TLS/DTLS connections are up.</p>
<p style="margin-left:11%; margin-top: 1em">A realm block
may also contain none, one or multiple accountingServer
options. This is used exactly like the server option, except
that it is used for specifying where to send matching
accounting requests. The values must be the names of
previously defined server blocks. When multiple accounting
servers are defined, there is a failover mechanism similar
to the one for the server option.</p>
<p style="margin-left:11%; margin-top: 1em">If there is no
server option, the proxy will if replyMessage is specified,
reply back to the client with an Access Reject message. The
message contains a replyMessage attribute with the value as
specified by the replyMessage option. Note that this is
different from having no match since then the request is
simply ignored. You may wonder why this is useful. One
example is if you handle say all domains under say .bv. Then
you may have several realm blocks matching the domains that
exists, while for other domains under .bv you want to send a
reject. At the same time you might want to send all other
requests to some default server. After the realms for the
subdomains, you would then have two realm definitions. One
with the name /@.*\\.bv$ with no servers, followed by one
with the name * with the default server defined. This may
also be useful for blocking particular usernames.</p>
<p style="margin-left:11%; margin-top: 1em">If there is no
accountingServer option, the proxy will normally do nothing,
ignoring accounting requests. There is however an option
called accountingResponse. If this is set to on, the proxy
will log some of the accounting information and send an
Accounting-Response back. This is useful if you do not care
much about accounting, but want to stop clients from
retransmitting accounting requests. By default this option
is set to off.</p>
<h2>TLS BLOCK
<a name="TLS BLOCK"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The TLS block
specifies TLS configuration options and you need at least
one of these if you have clients or servers using TLS/DTLS.
As discussed in the client and server block descriptions, a
client or server block may reference a particular TLS block
by name. There are also however the special TLS block names
default, defaultClient and defaultServer which are used as
defaults if the client or server block does not reference a
TLS block. Also note that a TLS block must be defined before
the client or server block that would use it. If you want
the same TLS configuration for all TLS/DTLS clients and
servers, you need just a single tls block named default, and
the client and servers need not refer to it. If you want all
TLS/DTLS clients to use one config, and all TLS/DTLS servers
to use another, then you would be fine only defining two TLS
blocks named defaultClient and defaultServer. If you want
different clients (or different servers) to have different
TLS parameters, then you may need to create other TLS blocks
with other names, and reference those from the client or
server definitions. Note that you could also have say a
client block refer to a default, even defaultServer if you
really want to.</p>
<p style="margin-left:11%; margin-top: 1em">The available
TLS block options are CACertificateFile, CACertificatePath,
certificateFile, certificateKeyFile, certificateKeyPassword,
cacheExpiry, CRLCheck and policyOID. When doing RADIUS over
TLS/DTLS, both the client and the server present
certificates, and they are both verified by the peer. Hence
you must always specify certificateFile and
certificateKeyFile options, as well as
certificateKeyPassword if a password is needed to decrypt
the private key. Note that CACertificateFile may be a
certificate chain. In order to verify certificates, or send
a chain of certificates to a peer, you also always need to
specify CACertificateFile or CACertificatePath. Note that
you may specify both, in which case the certificates in
CACertificateFile are checked first. By default CRLs are not
checked. This can be changed by setting CRLCheck to on. One
can require peer certificates to adhere to certain policies
by specifying one or multiple policyOIDs using one or
multiple policyOID options.</p>
<p style="margin-left:11%; margin-top: 1em">CA certificates
and CRLs are normally cached permanently. That is, once a CA
or CRL has been read, the proxy will never attempt to
re-read it. CRLs may change relatively often and the proxy
should ideally always use the latest CRLs. Rather than
restarting the proxy, there is an option cacheExpiry that
specifies how many seconds the CA and CRL information should
be cached. Reasonable values might be say 3600 (1 hour) or
86400 (24 hours), depending on how frequently CRLs are
updated and how critical it is to be up to date. This option
may be set to zero to disable caching.</p>
<h2>REWRITE BLOCK
<a name="REWRITE BLOCK"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The rewrite
block specifies rules that may rewrite RADIUS messages. It
can be used to add, remove and modify specific attributes
from messages received from and sent to clients and servers.
As discussed in the client and server block descriptions, a
client or server block may reference a particular rewrite
block by name. There are however also the special rewrite
block names default, defaultClient and defaultServer which
are used as defaults if the client or server block does not
reference a block. Also note that a rewrite block must be
defined before the client or server block that would use it.
If you want the same rewrite rules for input from all
clients and servers, you need just a single rewrite block
named default, and the client and servers need not refer to
it. If you want all clients to use one config, and all
servers to use another, then you would be fine only defining
two rewrite blocks named defaultClient and defaultServer.
Note that these defaults are only used for rewrite on input.
No rewriting is done on output unless explicitly specified
using the rewriteOut option.</p>
<p style="margin-left:11%; margin-top: 1em">The available
rewrite block options are addAttribute, addVendorAttribute,
removeAttribute, removeVendorAttribute and modifyAttribute.
They can all be specified none, one or multiple times.</p>
<p style="margin-left:11%; margin-top: 1em">addAttribute is
used to add attributes to a message. The option value must
be on the form attribute:value where attribute is a
numerical value specifying the attribute. Simliarly, the
addVendorAttribute is used to specify a vendor attribute to
be added. The option value must be on the form
vendor:subattribute:value, where vendor and subattribute are
numerical values.</p>
<p style="margin-left:11%; margin-top: 1em">The
removeAttribute option is used to specify an attribute that
should be removed from received messages. The option value
must be a numerical value specifying which attribute is to
be removed. Similarly, removeVendorAttribute is used to
specify a vendor attribute that is to be removed. The value
can be a numerical value for removing all attributes from a
given vendor, or on the form vendor:subattribute, where
vendor and subattribute are numerical values, for removing a
specific subattribute for a specific vendor.</p>
<p style="margin-left:11%; margin-top: 1em">modifyAttribute
is used to specify modification of attributes. The value
must be on the form attribute:/regexpmatch/replacement/
where attribute is a numerical attribute type, regexpmatch
is regexp matching rule and replacement specifies how to
replace the matching regexp. Example usage:</p>
<p style="margin-left:22%;">modifyAttribute
1:/^(.*)@local$/\1@example.com/</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>radsecproxy</b>(1),
<br>
Transport Layer Security (TLS) Encryption for RADIUS ⟨
https://tools.ietf.org/html/rfc6614⟩</p>
<hr>
</body>
</html>
|
