December 3, 2014

Radiator RADIUS Server

Open System Consultants Pty. Ltd.
Copyright (C) 1998-2014

Radiator
Installation and Reference manual for
Radiator version 4.14

1.0 Table of Contents

1.0
2.0
3.0
3.1
3.2
3.3
3.4
3.5
3.6
3.7
4.0
4.1
5.0
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
5.9

Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Full source distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Linux RPM binary installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Solaris. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Windows XP/Vista/7/8/8.1 and Server 2003/2008/2012. . . . . . . . . . . . . . 12
NetWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Post installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Trouble? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Date Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
SQL Bind Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Address binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
IPv6 support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Global parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
<Client xxxxxx> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
<ClientListLDAP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1 of 397

Table of Contents

5.10
5.11
5.12
5.13
5.14
5.15
5.16
5.17
5.18
5.19
5.20
5.21
5.22
5.23
5.24
5.25
5.26
5.27
5.28
5.29
5.30
5.31
5.32
5.33
5.34
5.35
5.36
5.37
5.38
5.39
5.40
5.41
5.42
5.43
5.44
5.45
5.46
5.47
5.48
5.49
5.50

2 of 397

<ClientListSQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
<SessionDatabase SQL>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
<SessionDatabase DBM> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
<SessionDatabase NULL>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
<Log FILE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
<Log SYSLOG> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
<Log SQL>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
<Log EMERALD> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
<SNMPAgent> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
<Realm realmname> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
<Handler attribute=value,attribute=value, ....> . . . . . . . . . . . . . . . . . . . . . 70
<AuthBy xxxxxx> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
<AuthBy ACE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
<AuthBy TEST> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
<AuthBy FILE>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
<AuthBy DBFILE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
<AuthBy CDB>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
<AuthBy GROUP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
<AuthBy UNIX> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
<AuthBy EXTERNAL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
<AuthBy SQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
<AuthBy RADIUS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
<Host xxxxxx> within <AuthBy RADIUS> . . . . . . . . . . . . . . . . . . . . . . . 139
<AuthBy RADMIN> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
<AuthBy EMERALD> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
<AuthBy EMERALD4> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
<AuthBy PLATYPUS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
<AuthBy RODOPI> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
<AuthBy LDAP2> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
<AuthBy SYSTEM> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
<AuthBy TACACSPLUS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
<AuthBy NISPLUS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
<AuthBy PAM>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
<AuthBy ADSI> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
<AuthBy PORTLIMITCHECK>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
<AuthBy DYNADDRESS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
<AuthBy ROUNDROBIN>, <AuthBy VOLUMEBALANCE>, <AuthBy LOADBALANCE>, <AuthBy HASHBALANCE>, <AuthBy EAPBALANCE>175
<AuthBy OPIE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
<AuthBy LDAPRADIUS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
<AuthBy SQLRADIUS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
<AuthBy INTERNAL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Radiator RADIUS Server

Table of Contents

5.51
5.52
5.53
5.54
5.55
5.56
5.57
5.58
5.59
5.60
5.61
5.62
5.63
5.64
5.65
5.66
5.67
5.68
5.69
5.70
5.71
5.72
5.73
5.74
5.75
5.76
5.77
5.78
5.79
5.80
5.81
5.82
5.83
5.84
5.85
5.86
5.87
5.88
5.89
5.90
5.91
5.92

<AuthBy POP3> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

<AuthBy IMAP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
<AuthBy LSA> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
<AuthBy SOAP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
<AuthBy OTP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
<AuthBy RSAMOBILE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
<AuthBy RSAAM> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
<AuthBy SQLDIGIPASS> (was <AuthBy DIGIPASS>). . . . . . . . . . . . . . 204
<AuthBy LDAPDIGIPASS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
<AuthBy LDAP_APS> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
<AuthBy URL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
<AuthBy KRB5> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
<AuthBy MULTICAST>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
<AuthBy RADSEC> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
<Host xxxxxx> within <AuthBy RADSEC> . . . . . . . . . . . . . . . . . . . . . . . 226
<AuthBy SASLAUTHD> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
<AuthBy NTLM> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
<AuthBy DNSROAM> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
<Route> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
<AuthBy SAFEWORD> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
<AuthBy FREERADIUSSQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
<AuthBy HTGROUP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
<AuthBy FIDELIO> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
<AuthBy FIDELIOHOTSPOT> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
<AuthBy PRESENCESQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
<AuthBy HANDLER> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
<AuthBy WIMAX>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
<AuthBy SQLYUBIKEY> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
<AuthBy YUBIKEYVALIDATIONSERVER> . . . . . . . . . . . . . . . . . . . . . . 247
<AuthBy SQLHOTP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
<AuthBy SQLTOTP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
<AuthBy SQLAUTHBY> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
<AuthBy HEIMDALDIGEST> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
<AuthBy SIP2> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
<AuthBy DUO> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
<AuthBy DIAMETER> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
<AuthBy RATELIMIT> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
<AuthLog xxxxxx> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
<AuthLog FILE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
<AuthLog SQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
<AuthLog SYSLOG> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
<AddressAllocator SQL> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Radiator RADIUS Server

3 of 397

Table of Contents

5.93
<AddressAllocator DHCP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.94
<Resolver>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.95
<ServerDIAMETER> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.96
<ServerTACACSPLUS>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.97
<ServerRADSEC> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.98
<ServerHTTP> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.99
<StatsLog FILE> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.100 <StatsLog SQL>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.101 <Monitor> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.0
radiusd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.0
Web-based configuration GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1
Login page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2
Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3
Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6
Advanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.0
radpwtst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1
radpwtst option file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2
radpwtst examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3
The radpwtst GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.0
builddbm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.0
buildsql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.0
radacct.cgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.2
Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.3
Secure mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.0
radwho.cgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.1
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2
Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.0
Check and Reply items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1
Check items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2
Reply items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.0
Rewriting user names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.0
File formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.1
Dictionary File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.2
Flat file user database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.3
DBM user database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4
Unix password file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5
Accounting log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.6
Password log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.7
Portlist file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 of 397

Radiator RADIUS Server

269
271
275
278
287
293
296
298
299
302
305
305
306
307
309
312
315
316
322
322
323
324
326
328
328
329
330
332
332
332
333
334
349
353
354
354
358
359
359
360
360
361

Table of Contents

16.0
High availability for radiusd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
16.1
Using restartWrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
16.2
Using init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
16.3
Using inetd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
16.4
Unix SYSV startup script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
16.5
As a System Service on Windows with ActivePerl or Strawberry Perl . . 364
17.0
Adding custom AuthBy modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
17.1
Loading and configuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
17.2
Handling Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
17.3
AuthGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
17.4
Step-by-step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
17.5
Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
18.0
Compatibility with Livingston and other servers . . . . . . . . . . . . . . . . . . . . . 369
19.0
Execution sequence and Hook processing. . . . . . . . . . . . . . . . . . . . . . . . . 370
20.0
Interoperation with iPASS Roaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
20.1
iPASS Outbound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
20.2
iPASS Inbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
21.0
RadSec (RFC 6614) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
21.1
RadSec Certificate Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
22.0
Extensible Authentication Protocol (EAP). . . . . . . . . . . . . . . . . . . . . . . . . . 378
22.1
EAP MD5-Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
22.2
EAP One-Time-Password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
22.3
EAP Generic-Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
22.4
EAP TLS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
22.5
EAP LEAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
22.6
EAP TTLS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
22.7
EAP SIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
22.8
EAP AKA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
22.9
EAP AKA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
22.10 EAP PEAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
22.11 EAP MSCHAPV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
22.12 EAP PAX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
22.13 EAP PSK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
22.14 EAP PWD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
23.0
Monitor command language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
23.1
Object naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
23.2
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
24.0
Using SQL with various database vendors . . . . . . . . . . . . . . . . . . . . . . . . . 388
24.1
General. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
24.2
mSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
24.3
mysql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
24.4
Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Radiator RADIUS Server

5 of 397

Introduction

24.5
Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.6
PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.7
ODBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.8
Interbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.9
Informix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.10 CSV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24.11 SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25.0
Performance and Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.0
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.1
Support contract holders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.2
No support contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.3
What to do if you need help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.4
Announcements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.5
Bug reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26.6
RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

390
391
391
391
392
393
393
394
395
395
395
396
396
397
397

2.0 Introduction
This document describes how to install and configure the Radiator RADIUS server
from Open System Consultants.
RADIUS is the de facto standard protocol for authenticating users and for recording
accounting information. It is commonly used by Wireless Access Points (APs), Terminal Servers or Network Access Servers (NASs) whenever a user logs on and off network access devices or dialup Internet service. It is supported and used by most vendors
such as Cisco, Ericsson, Huawei, Juniper, Ruckus, Aruba, Alcatel-Lucent, 3Com, US
Robotics and others. See RFCs 2865 and 2866 for more details on the RADIUS protocol.
Radiator is a highly configurable and extensible RADIUS server that allows you to easily customize and control how you authenticate users and record accounting information. Radiator can authenticate users from passwords held in:

Remote RADIUS servers (proxying)

SQL databases, including Oracle, Sybase, Informix, Microsoft SQL Server, PostgreSQL, mSQL, MySQL, SQLite, ODBC and others.

6 of 397

LDAP
Microsoft Active Directory
RSA Securid
VASCO Digipass
YubiKey
Duo Security

Radiator RADIUS Server

Introduction

SIP2 - the 3M Standard Interchange Protocol (SIP) 2.0

RAdmin - the RADIUS User Administration system from Open System Consultants
Flat files
DBM files
Unix password files and similar formats
iPASS Roaming Network
RSA Mobile
Platypus ISP billing system from Boardtown
Rodopi ISP billing system
Emerald ISP billing system from IEA
Interbiller ISP billing system
Optigold ISP billing system
BillMax Unix ISP billing system
Other ISP billing packages ...
NIS+
PAM
TacacsPlus
your own legacy user database
External programs
Any external one-time-password system
Most external SOAP-based authentication methods
OPIE one-time-passwords
Hotel Property Management Systems
Other methods contributed by Radiator users

Radiator can record user accounting information in

Flat files in standard RADIUS detail file format

Unix wtmp format files
SQL databases, including Oracle, Sybase, Informix, Microsoft SQL Server, PostgreSQL, mSQL, MySQL, SQLite, ODBC and others.

Remote RADIUS servers

RAdmin, the RADIUS User Administration system from Open System Consultants
Platypus ISP billing system from Boardtown
Rodopi ISP billing system
Emerald ISP billing system from IEA
BillMax Unix ISP billing system
Other ISP billing packages ...
Your own legacy usage database

Radiator RADIUS Server

7 of 397

Installation

External programs
Radiator can provide external interfaces for and receive the following protocols:

RADIUS (including WiMAX)

TACACS+
SNMP
Telnet
HTTP
Diameter
RadSec

Radiator can manage multiple clients and realms, possibly with multiple different
authentication methods in each realm, and includes special features not found in other
servers like username rewriting and vendor-specific RADIUS attributes. A full suite of
load balancing modules is included.
Radiator works with a wide range of EAP (Extensible Authentication Protocol) methods, including TLS, TTLS, PEAP, MD5, MSCHAPV2, OTP, GTC, LEAP, FAST, PAX,
PSK, SIM, AKA, AKA and others.
Radiator runs on most Unix and Linux hosts, Windows XP/Vista/7/8 and Server 2003/
2008/2012 and MacOS X. It is written entirely in Perl, and is therefore highly portable.
Full source code is supplied, so you can alter the behavior of Radiators internals if you
need to. There is a standardized way of adding new authentication and accounting handlers, so you can easily integrate Radiator with other legacy systems and software.
You will need to be familiar with system administration to install Radiator. You will
need to have a basic understanding of RADIUS and your networks authentication and
accounting requirements in order to configure RADIUS. You will need to have a basic
understanding of SQL in order to configure AuthBy SQL if you require operation with
an SQL database. You will need to have a basic understanding of LDAP in order to configure AuthBy LDAP if you require operation with an LDAP server.
Radiator and the Radiator logo are registered trademarks of Open System Consultants
Pty. Ltd.

3.0 Installation
Radiator runs on a wide range of platforms. The installation procedure depends on the
platform and the type of package selected. Typical installation procedures are shown
below.
3.1 Prerequisites
Radiator requires a number prerequisite package to be installed before it will run correctly. These include:

8 of 397

Radiator RADIUS Server

Installation

3.1.1 Perl

This is the main program that runs Radiator. It must be installed on your Radiator host.
Platform specific methods for installing Perl are discussed below. Radiator requires Perl
5.8.8 or better. You should install and test Perl before proceeding further. Many Unix
packages include Perl as part of the standard installation. Common Windows Perl distributions include ActivePerl and Strawberry Perl.
3.1.2 Digest-MD5

Radiator requires the Digest-MD5 Perl library package (version 2.02 or later).
Hint: Most modern versions of Perl include the Digest-MD5 library.
If it is not present in your Perl distribution, it can be obtained from your nearest CPAN
archive. See
http://www.perl.org/CPAN/README.html.
If it is not present, you should install and test Digest-MD5 before proceeding further.
The general procedure for installing Digest-MD5 on Unix is:
1. Unpack the distribution in a work area with

zcat Digest-MD5-2.12.tar.gz|tar xvf -

2. cd Digest-MD5-2.12
3. perl Makefile.PL
4. make
5. make test
6. make install

On Windows with ActivePerl or Strawberry Perl, you can use the PPM command to
install Digest-MD5.
3.1.3 Digest::SHA

Radiator requires the Digest-SHA Perl library package (version 5 or later).

Hint: Most modern versions of Perl include the Digest-SHA library. If not, it can be
installed using a similar procedure to Digest-MD5 above.
3.1.4 Digest-MD4

If MSCHAP or MSCHAPV2 are to be required to be supported, Radiator requires the

Digest-MD4 Perl library package. This can be installed using a similar procedure to
Digest-MD5 above.
3.1.5 Net-SSLeay and OpenSSL

If EAP-TLS, PEAP, TTLS, EAP-FAST or any modules requiring TLS are to be required
to be supported, Radiator requires the Net-SSLeay Perl library package. The Perl distributions commonly include Net-SSLeay as a pre-packaged module.
On Windows with ActivePerl and Strawberry Perl, you can use the PPM command to
install Net-SSLeay.

Radiator RADIUS Server

9 of 397

Installation

3.1.6 SQL

If you wish to use Radiators AuthBy SQL module to authenticate and record accounting to an SQL database (not supplied), you must install the DBI Perl library, and the
DBD Perl library for your particular SQL database.
If you are going to use SQL, you should install and test your chosen RDBMS first, then
install and test DBI and then the DBD Perl module for your RDBMS.
On Windows with ActivePerl and Strawberry Perl, you can use the PPM command to
install the appropriate DBD support for your SQL server.
3.1.7 Memory

The Radiator installation requires about 32Mb of disk space. RAM requirements depend
strongly on your Radiator configuration and on the types of authentication being used:
If EAP authentication is not being used, Radiator typically starts running at about 20Mb
and may grow slowly to around 50Mb and plateau as RADIUS requests are received.
If EAP authentication types such as TLS, TTLS or PEAP are being used, the process
memory requirements can be much greater. This is because Radiator caches per-user
TLS session information in its process memory for EAPContextTimeout seconds
(defaults to 1000 seconds). On some platforms, the per-user TLS session information
can be as much as 50kb per session. This means that if you are handling large numbers
of TLS authentications, you may also need more memory.
3.2 Full source distribution
Also known as the tarball this is the most general and widely portable procedure, however a number of more specialised platform-specific installation methods are shown further below.
This installation method requires ExtUtils-MakeMaker which is part of Perl. Some
recent Linux distributions, such as CentOS 6.x, may not have ExtUtils-MakeMaker
installed by default but it can be installed with something like yum install perlExtUtils-MakeMaker
The Radiator full source distribution is supplied as a gzipped, tarred distribution file.
The standard distribution file name is Radiator-x.yy.tgz, where x.yy is the
revision number. Put the distribution archive somewhere suitable (perhaps /usr/
local/src) and unpack it with something like:
zcat Radiator-x.yy.tgz | tar xvf -

Where zcat is the GNU zcat command. If your path does not include the GNU zcat, you
could try:
cat Radiator-x.yy.tgz | gunzip -c| tar xvf -

In either case, this will create a directory called Radiator-X.Y in the current directory.

10 of 397

Radiator RADIUS Server

Installation

cd Radiator-x.yy
perl Makefile.PL
make test

which will run a fairly exhaustive test suite on your radius server which take a few minutes.
make install

This optional command will install the RADIUS modules that Radiator requires in your
site-perl directory (typically /usr/local/lib/perl5/site_perl). It will install the radius daemon (radiusd) and the command line password test program (radpwtst), the DBM
file builder (builddbm) and the SQL database builder (buildsql) in your usual
directory for local executables (typically /usr/local/bin).
If you wish (e.g. for test purposes), you can omit make install command and run
your Radiator directly out of the distribution directory.
3.3 Linux RPM binary installation
Linux users can easily install from an RPM binary package. Prerequisite is Perl 5.8.8 or
better and Digest-MD5 version 2.02 or better, which are both installed by default in
most recent Linux versions.
1. Log in as root
2. Install the package with
rpm -Uvh Radiator-x.yy-z.noarch.rpm
3. Start the server with
/etc/init.d/radiator start
4. Test authentication with
radpwtst
5. Edit /etc/radiator/radius.cfg to suit your site and needs.

See this reference manual in /usr/share/doc/Radiator-x.yy/doc/ref.* for more details.

The RPM package will arrange for Radiator to start automatically each time you reboot
your Linux host. By default, it creates the following directories:

/etc/radiator
/usr/lib/perl5/site_perl/Radius
/var/log/radius
/usr/share/doc/Radiator-x.yy

You can find documentation, additional dictionaries and the goodies collection in /usr/
share/doc/Radiator-x.yy.
3.4 Solaris
On Solaris, we recommend install from the tarball as described above. Previous Radiator versions were packaged for Solaris, but required Perl from Sunfreeware (http://
Radiator RADIUS Server

11 of 397

Installation

www.sunfreeware.com) to find the correct installation locations. We now recommend to

install Perl from your preferred source and then use the Radiator tar package for Radiator installation.
3.5 Mac OS X
While Perl comes standard with your Mac OS X installation, Digest-MD5 may not be
included if you are running an old version of OS X. To compile additional modules,
you will need to install Xcode or the MacOS X Developer Tools CD and then download,
build and install the modules, such as Digest-MD5. The you can unpack and test your
Radiator distribution.
You do not need to install Digest-MD5 on OS X 10.8 and later. It may also be included
with 10.7 and other recent versions.
3.6 Windows XP/Vista/7/8/8.1 and Server 2003/2008/2012
The installation procedure for Windows systems is similar to Unix.
You should download the self-extracting Radiator Zip file for Windows. Radiator will
run very nicely on Windows XP/Vista/7/8/8.1 and Server 2003/2008/2012 etc, provided
you have a suitably configured Perl available. Make sure you are (or have access to) a
system administrator and someone who understands your Radius authentication and
accounting requirements.
We recommend that you use the ActiveState distribution of Perl, called ActivePerl,
available from http://www.activestate.com, or Strawberry Perl from http://strawberryperl.com. Please see the respective links for support and other options you may
require.
The Active State port installs quickly and easily on all Windows platforms, and almost
all the optional modules are readily available and easy to install..
Strawberry Perl is another Perl distribution for installing Radiator on Windows but with
different packaging and support options .
Radiator comes with pre-compiled Perl modules required for AuthBy ACE, AuthBy
LSA and Digipass authentication. If you require one of these authentication methods, it
may limit your choice of Perl version to install.
If you require RSA AuthBy ACE support, Radiator currently comes with pre-compiled
modules up to Perl 5.16. Pre-compiled modules for Authen-Digipass and Win32-LSA
have been tested with ActivePerl up to version 5.16 and Strawberry Perl 5.20.
3.6.1 ActiveState ActivePerl
1. Download and install ActivePerl 5.8 or later from

http://www.ActiveState.com/ActivePerl
During installation, accept all the defaults. Allow setup to reboot your computer if it
needs to.

12 of 397

Radiator RADIUS Server

Installation

2. Connect your computer to the Internet so you can download any required Perl mod-

ules from ActiveState using PPM.

3. Open a Command Prompt window and change to the perl PPM directory. Install

some prerequisite Perl modules:

c:
cd \perl\bin
ppm install Win32::Daemon
ppm install Digest::HMAC
ppm install Digest::MD4
ppm install perl-ldap
4. If you plan to use SQL authentication, type ppm install DBI to install the main

DBI package. Then find the database specific module(s) you want by typing
search DBD, then install the one(s) you need for your database(s). (for example to
install DBD-ODBC, type ppm install DBD-ODBC).
5. Download and run the self-extracting Radiator Zip file from

http://www.open.com.au/radiator/downloads.html
(username and password required). Let it unpack to the default ___location, c:\Radiator.
If you have problems unpacking, refer the Radiator FAQ at http://
www.open.com.au/radiator/faq.html.

6. Open a Command Prompt window, change directories to the place where you

unpacked Radiator.
7. Type perl Makefile.PL. This will check that your distribution is complete.
8. Run the regression tests with perl test.pl. You should see lots of lines like ok

xx, and none saying not ok xx.

9. Type perl Makefile.PL install. This will install the Radiator programs

and libraries in the standard places, and will create a basic Radiator configuration
file in C:\Program Files\Radiator\radius.cfg and a sample users file in C:\Program
Files\Radiator\users
10. Run radiator with the sample configuration with perl c:\perl\bin\radi-

usd. You will see some messages, followed by

NOTICE: Server started:
Radiator is now waiting for RADIUS requests to arrive.

11. In another command window run the test client program with

perl C:\perl\bin\radpwtst -user mikem -password fred

You should see "OK". This proves that Radiator has correctly authenticated the user
mikem, whose login details are in the users file in C:\Program Files\Radiator\users.
12. Continue with post-installation tasks and configuration at Section 4.0 on page 16.
3.6.2 Strawberry Perl
1. Download and install Strawberry Perl from

http://strawberryperl.com/
During installation, we recommend installing it in C:\Perl. Accept all the
defaults. Allow setup to reboot your computer if it needs to.
2. Connect your computer to the Internet so you will be able download any required

Perl modules from CPAN in the next section.

Radiator RADIUS Server

13 of 397

Installation

3. Open a Command Prompt window. Install some prerequisite Perl modules

cpan Win32::Daemon
cpan Digest::MD4
4. If you plan to use SQL authentication, find the database specific Perl DBD mod-

ule(s) you want. For example, if you want to use ODBC to connect to your database,
type: cpan DBD::ODBC
5. If you plan to use LDAP for authentication and/or accounting, obtain and install

perl-ldap by typing: cpan Net::LDAP

6. If you plan to use EAP TLS, TTLS or PEAP for 802.1x authentication obtain and

install Net_SSLeay by typing: cpan NET::SSLeay

7. Download (username and password required) and run the self-extracting Radiator

Zip file for Windows. Let it unpack to the default ___location, c:\Radiator (we will
call this ___location the distribution directory).
8. Start a command window with administrator access, change directories to the distri-

bution directory.
9. Type perl Makefile.PL. This will check that your distribution is complete.
10. Run the regression tests with perl test.pl. You should see lots of lines like "ok

xx", and none saying "not ok xx".

11. Install Radiator with perl Makefile.PL install. This will install the Radiator programs

and libraries in the standard places, and will create a basic Radiator configuration
file in C:\Program Files\Radiator\radius.cfg and a sample users file
in C:\Program Files\Radiator\users.
12. Now test Radiator with the sample configuration file in

C:\Program Files\Radiator\radius.cfg which authenticates all

requests from the file C:\Program Files\Radiator\users, and logs
extensively to C:\Program Files\Radiator\logfile
13. Run radiator with

perl C:\perl\bin\radiusd
14. You will see some messages, followed by:

NOTICE: Server started:

Radiator is now waiting for requests to arrive.
15. In another command window run the test client program with:

perl radpwtst -user mikem -password fred

You should see OK.
16. Rerun radpwtst, this time with the wrong password for mikem:

perl radpwtst -user mikem -password wrong

You should see Rejected
17. If you configure a test NAS to use this server, you will able to log in as the user

"mikem" with password "fred".

18. Continue with post-installation tasks and configuration at Section 4.0 on page 16.
3.6.3 Notes for PC installers and users

The Radiator .tgz distribution file can be unpacked with recent versions of WinZip.
Some DBM file formats produced by AnyDBM_File on a PC and used by <AuthBy
DBM> are not compatible with DBM files formats produced by Unix. So if you cre-

14 of 397

Radiator RADIUS Server

Installation

ate them with builddbm on one host, they may not be readable by Radiator on a different kind of host. If in doubt, build the DBM file on the same type of machine as
the target host.

You can test and run Radiator from the directory where you unpacked it. After testing is complete, you can install the Radiator libraries and binaries in their usual
places as described in the following bullet.

If you have make available, you can install the software by running
make install
If you dont have a working make, you can use this instead:
perl Makefile.PL install

The installation process will install the Radiator executables in the Perl binary directory, typically c:\perl\bin. When you run radiusd, builddbm, buildsql and radpwtst, you will need to make sure Perl is in your path, and to run them like:
perl c:\perl\bin\radiusd

Perl on Windows automatically maps Unix style file names to DOS style (i.e
changes / to \ etc.), so when you specify file names in the Radiator configuration file
on Windows, you can use either Unix or DOS styles. Our best advice is to choose
one and use it consistently.

Some ODBC drivers (notably Oracle) intercept the SIGINT handler, which makes it
hard to kill radiusd with Control C from within an Command Prompt window. We
suggest you create a shortcut to run radiusd, then you can always shut the window to
kill radiusd.

Daemon mode is not supported on Windows platforms. However, radiusd can be

installed as a Windows Service.

Radpwtst in -gui mode does not work properly on Windows, due to a bug in Tk.
3.7 NetWare
Radiator runs on Novell NetWare 6.5. NetWare 6.5 comes with Perl already installed, so
you do not need to install perl.
The installation procedure is:
1. Start a System Console
2. Start bash:
#bash
3. Unpack the Radiator distribution in a work area:
#cd /path/to/work/area
#tar zxvf Radiator-x.yy.tgz
#cd Radiator-x.yy
4. Install the software
#perl Makefile.PL install

Radiator RADIUS Server

15 of 397

Post installation and configuration

This procedure will install the Radiator executables and libraries in the /perl directory
tree. It will install a basic AuthBy FILE configuration in /etc/radiator, and it will install
a startup script in /system/radiator.ncf.
To start Radiator, type
#radiator

at the System Console. To always start Radiator at boot time, add

radiator

to the end of the system startup file /system/autoexec.ncf

To add users to the AuthBy FILE, edit /etc/radiator/users. To alter the Radiator configuration, edit /etc/radiator/radius.cfg.

4.0 Post installation and configuration

By now, you should have Radiator installed and the regression test suite should have
reported all tests OK. You should now:

Study the configuration information in the rest of this document.

Find out which RADIUS clients and realms you need to serve.
Configure your Radiator by creating and editing the configuration file, or else by
enabling ServerHTTP and editing your configuration with the web based GUI. See
Section 5.0, Configuration, on page 17.

Create a directory for your user database(s) and dictionary file. Place your dictionary
there. Put a test user database there too. Make sure your configuration files DbDir
parameter specifies that directory.

Run the radiusd daemon, specifying where the configuration file is with the config_file flag. See Section 6.0, radiusd, on page 302.

Test Radiator with the radpwtst test utility. See Section 8.0, radpwtst, on
page 316.

Build your real user database(s).

Arrange for radiusd to start automatically at boot time. See Section 16.0 on
page 361.
4.1 Trouble?
If you have trouble installing or running Radiator, you should first consult the Radiator
Frequently Asked Questions at http://www.open.com.au/radiator/
faq.html. After that, try consulting the patches directory for your release, typically
something like http://www.open.com.au/radiator/downloads/
patches-x.yy. If you still have trouble, consult the instructions in Section 26.0 on
page 395.

16 of 397

Radiator RADIUS Server

Configuration

5.0 Configuration
5.1 General information
This section describes the Radiator configuration file and the statements that you can
use in the configuration file to control the behaviour of the Radiator server, radiusd.
When radiusd starts, it reads a configuration file. The default file name for the configuration file is

/etc/radiator/radius.cfg on Unix and Mac OS X

C:\Program Files\Radiator\radius.cfg on Windows
but you can specify an alternate configuration file with the -config_file flag.
There is a test configuration file (radius.cfg) in the Radiator distribution that shows
most of parameters and clauses that you can use in a configuration file, and examples of
how to use them. There is also a very simple example (simple.cfg) in the goodies directory in the Radiator distribution. It might be a good starting point for your
own configuration file.
In general terms, the configuration file allows you control the following things:

Behavior of the server in general, including Logging.

Which RADIUS clients the server will respond to.
Which RADIUS realms the server will work with.
Optionally, Handlers for specifying special ways to handle requests.
For each realm, what method(s) should be used for authenticating users and storing
accounting information.

For each authentication method for each realm, the configuration of the authentication module.

Optionally, custom Perl hooks that can be run during the processing of each request.
(see Execution sequence and Hook processing on page 370).
The configuration file is an ASCII text file that can be edited by any text editor. Leading
white space in each line is ignored, so you can use indentation to make your configuration file easier to read. Case is important in all parameter names and clauses.
Hint: An alternative to editing the configuration file directly is to use the ServerHTTP
clause (see Section 5.98, <ServerHTTP>, on page 293 and Section 7.0, Web-based
configuration GUI, on page 305) which allows you to connect to Radiator with standard web browser and examine, change and test the configuration with an easy to use
point and click web interface.
Each line in the configuration file can be one of:

Comment line with a # as the first character. Anything including and after the #
is ignored. Blank lines are also ignored. Example:
# This is a comment

Radiator RADIUS Server

17 of 397

Configuration

Caution: comments that do not start at the beginning of the line are likely to be taken
as part of a parameter value:
SomeParameter xxxx

# INCORRECT:this is not a comment

An include directive. The word include followed by a filename. The named file
will be opened and read to the end as a configuration file before processing of the
current file continues. Special filename characters are permitted (see Section 5.2 on
page 20). Files can be recursively included to any depth. The include keyword is
case insensitive. Examples:
include %D/clients.cfg
Include %D/realms.cfg

Filename can include csh(1) style wildcards and expansions such as *, ?, [...], {....},
~, etc. Files whose first character is a . are ignored unless explicitly matched. Wildcard files are included in lexicographic order of their filename.
# Reads all files with a .cfg extension:
include %D/*.cfg
# Matches radiator1.cfg, radiator2.cfg etc:
include /etc/radiator/radiator[0123456].cfg

You can also use the include mechanism to capture the output of a script. A program name followed by a vertical bar will run the named program and include its
output into the configuration file. This is a useful way for generating some or all of
your Radiator configuration programmatically. For example, you could write a script
to generate all your <Client> clauses by processing some external description of all
your NASs.
include %D/myClientScript.pl|

Parameter setting. The first word is the name of the parameter to set, all the following words and digits are the value to be used for the parameter. All the parameters
you can set in the configuration file are described in this document. Example:
Trace 4

Parameter setting from a file. If a parameter is set to the value like

file:filename
then the value of the parameter will be retrieved from the file named filename.
This is probably most useful for putting long parameters like a hook in an external
file. For example, this will load the code for PreAuthHook from the external file
hook.pl:
PreAuthHook file:hook.pl

Parameter setting from an SQL database query. If a parameter is set to a value like:
ParameterName sql:identifier:query
it will look for a previously defined AuthBy SQL clause with an Identifier of identifier and run the SQL query given by query. The first row in the result will be used
to set the parameter. The SQL database lookup is only done once at startup time.
<AuthBy SQL>
Identifier
DBSource
DBUsername
DBAuth

18 of 397

Radiator RADIUS Server

myidentifier
dbi:mysql:radius
mikem
fred

Configuration

</AuthBy>
Trace sql:myidentifier:select value from configuration where\
name = Trace

Start or end of a clause. A clause is a collection of parameter settings related to a single feature in the server. The first line in a clause is surrounded by angle brackets
(< and >), for example <Client fred>, which would mark the beginning of
the configuration for client with the DNS name fred. Subsequent lines are interpreted as parameter settings for the feature, until the end of the clause is seen. The
end of the clause is surrounded by angle brackets with a slash, for example:
<Client DEFAULT>
# Configuration parameters for the Client go here
.....
</Client>

Hint: The configuration file will usually contain the shared secrets that allow your
RADIUS clients to communicate with the Radiator RADIUS server. It might also contain passwords for access to databases etc. This means that for security reasons, you
should keep the configuration file as secure as possible. On Unix, you should make sure
that it is readable only by the user that radiusd runs as.
Hint: Parameters that are on/off flags, such as LogSuccess, or LogFailure can be
enabled or disabled in a number of ways. values of 0, no or false (case insensitive)
will turn the flag off, whereas any other value (including the empty string) will turn the
flag on:
These will all turn a flag parameter off:
IgnoreAcctSignature
IgnoreAcctSignature
IgnoreAcctSignature
IgnoreAcctSignature
IgnoreAcctSignature

0
no
NO
false
FALSE

These will all turn a flag parameter on:

IgnoreAcctSignature
IgnoreAcctSignature 1
IgnoreAcctSignature yes
IgnoreAcctSignature anythingatall
DefineGlobalVar myspecialflag yes
IgnoreAcctSignature %{GlobalVar:myspecialflag}

Hint: long lines in your configuration file can be split over multiple lines by using the
\ character at the end of each line except the last:
AuthSelect select s.password, g.session_timeout \
s.check_items s.reply_items \
from subscribers s, groups g \
where username=%n and s.group \
= g.name

Radiator RADIUS Server

19 of 397

Configuration

Hint: parameter values can contain escaped octal characters, for example, you could
specify an AcctLogFileFormat with newline (octal 012) separated lines with something
like:
AcctLogFileFormat %{Timestamp}\012%{Acct-Session-Id}\
\012%{User-Name}\012

Hint: The order of clauses in the Radiator configuration file is significant.All the
clauses are parsed and internal data structures constructed during the initial parse of the
configuration file. They are constructed in the order they appear in the configuration
file. For example, if a <Log xxx> clause is encountered, that logger will be created
immediately and used to log all subsequent parsing and startup errors. This means for
example that if a <Log xxx> clause is encountered in the configuration file, only errors
in clauses that appear after the Log clause will be logged using that method.
5.2 Special characters
Wherever you can specify a file name in the Radiator configuration file, you can use
some special characters in the path name. These special characters can also be used in a
number of other configuration file parameters. These special characters will be replaced
at run time, so you can dynamically change file paths and the like so they depend on
such things as the date, realm, username etc
Special characters are introduced by a %, followed by a single character. Different
characters are replaced at run-time by different information. The following special characters are available:

TABLE 1.

Special string formatting characters

Specifier

Is replaced at run-time by:

from the current time (according to the Radiator host machine):

20 of 397

%l

The current time in long format, e.g. Thu Jul 1 08:38:21 1999

%B

The current time in common SQL date time format, e.g. Sep 12, 2003 15:48

%G

The current time in extended SQL date format including seconds,

e.g. Sep 12, 2003 15:48:59

%t

The current time in seconds since Jan 1 1970

%S

the current second (00-59)

%M

The current minute (00-59)

%H

The current hour (00-23)

%d

Current day of the month (2 digits)

%m

Current month number (2 digits, 01-12)

%Y

Current year (4 digits)

%y

Last 2 digits of the current year (2 digits)

%q

Day of the week, abbreviated (e.g. Sun, Mon, Tue, ....)

Radiator RADIUS Server

Configuration

TABLE 1.

Special string formatting characters

Specifier

Is replaced at run-time by:

%Q

Day of the week (e.g. Sunday, Monday, Tuesday, ....)

%v

Month of the year, abbreviated (e.g. Jan, Feb, Mar, ...)

%V

Month of the year, (e.g. January, February, March, ...)

%s

Microseconds in the current second

%O

When FarmSize is used to specify a server farm, %O is replaced by the server

instance number, where 0 is the main (supervising) server.
from the Timestamp of the current packet (if any):

%o

The Timestamp in long format, e.g. Thu Jul 1 08:38:21 1999

%A

The Timestamp in common SQL date time format, e.g. Sep 12, 2003 15:48

%J

The Timestamp in another common SQL date time format: 2003-09-12 15:48:00

%F

The Timestamp in extended SQL date format including seconds,

e.g. Sep 12, 2003 15:48:59

%b

The Timestamp in seconds since Jan 1 1970

%p

the Timestamp second (0-59)

%k

The Timestamp minute (0-59)

%j

The Timestamp hour (0-23)

%i

The Timestamp day of the month (2 digits)

%g

The Timestamp month number (2 digits)

%f

The Timestamp year (4 digits)

%e

Last 2 digits of the Timestamp year (2 digits)

%E

The elapsed time in seconds since the packet was received. Can be used to log
processing time for proxied packets etc.
other information from the current request (if any):

%c

IP address of the client who sent the current request (if any)

%C

Client name of the client who sent the current request (if any). Caution: this does
a reverse name lookup on the address, and depending on your environment, this
may take a number of seconds to resolve.

%R

The realm of the username named in the current request (if any), after any
RewriteUsername was applied. This is everything following the first @ sign in
the User-Name.

%K

The trailing realm of the username named in the current request (if any), after
any RewriteUsername was applied. This is everything following the last @ sign
in the User-Name.

%N

The NAS-IP-Address in the current request (if any)

%n

The User-Name (i.e. the full user name, including the realm) currently being
authenticated, after any RewriteUsername was applied.

%U

The User-Name currently being authenticated with the realm (if any) stripped
off, after any RewriteUsername was applied.

Radiator RADIUS Server

21 of 397

Configuration

TABLE 1.

Special string formatting characters

Specifier

Is replaced at run-time by:

%u

The full original User-Name that was received, before any RewriteUsername
were applied.

%w

The user name part of the full original user name (before any RewriteUsername
rules were applied).

%W

The realm part of the full original user name (before any RewriteUsername rules
were applied).

%P

The decrypted User-Password from the current request

%T

The request type of the current request, if any (e.g. Access-Request, AccountingRequest)

%z

The User-Name in the current packet, hashed with MD5.

%I

The NAS identifier as an integer instead of dotted decimal character string. Useful for speeding up SQL queries.

%X

For EAP requests, the EAP identity, with any trailing @realm stripped off.

%x

The EAP Identity for PEAP and TTLS inner requests.

%Z

The RADIUS Identifier of the incoming request.

%{attr}

The value of the named attribute in the current packet (if any).
For example, %{User-Name} is the same as %n
miscellaneous

22 of 397

%%

The percent character

%r

A literal newline character

%D

The value of DbDir as configured in your Radiator configuration file

%L

The value of LogDir as configured in your Radiator configuration file

%h

The hostname this server is running on

%{Special:X}

Same as %X, where X is any of the single special characters listed above. For
example, %{Special:a} will produce the same result as just %a.

%{GlobalVar:name}

The value of the global variable called name. Global variables can bet set with
name=value on the command line, or with DefineFormattedGlobalVar name
value in the configuration file. If the variable name has not been defined,
replaced with an empty string.

%a

The Framed-IP-Address in the reply message being created (if any)

%{Request:name}

The value of the named attribute in the current request (if any). This is the same
as just %{name}, but may be used instead for clarity.

%{OuterRequest:name}

The value of the named attribute in the outer request (if any) of the current
request (if any). May be used where the request has been tunnelled using PEAP
or TTLS.

%{Reply:name}

The value of the named attribute in the reply currently being created (if any). For
example, %{Reply:Framed-IP-Address} is the same as %a. If there is no current
reply, or the attribute is not present in the reply, replaced with an empty string

%{Client:name}

The value of the named parameter from the Client clause that accepted the current packet (if any).

Radiator RADIUS Server

Configuration

TABLE 1.

Special string formatting characters

Specifier

Is replaced at run-time by:

%{Handler:name}

The value of the named parameter from the Handler clause that is handling the
current packet (if any).

%{AuthBy:name}

The value of the named parameter from the AuthBy clause that is handling the
current packet (if any).

%{Eval:expression}

Evaluates the perl expression. Any valid perl expression can be used
Support for %Eval was removed in version 3.3.

%{Server:name}

The value of the named parameter from the global server configuration (e.g.
%{Server:Trace} is replaced by the current value of the global Trace parameter).

%{IntegerVal:name}

The value of the named attribute in the current packet (if any), expressed as an
integer, instead of as a value name from the dictionary. (e.g. %{IntegerVal:Tunnel-Type} would be replaced by 3 if the Tunnel-Type is L2TP).

%{HexAddress:name}

Replaced by the named IPv4 attribute in the current packet (if any), expressed as
a hexadecimal string. (e.g. %{HexAddress: NAS-IP-Address} would be replaced
by CB3F9A01 if the NAS-IP-Address in the current request was 203.63.154.1).

%{Quote:somestring}

When used with SQL modules, replaced by somestring quoted with the appropriate quoting style for the SQL database in use. For example when
used with a mysql database, %{Quote:somestring} would be replaced by
somestring.

%{SQL:identifier:query}

Replaced with a value fetched from an SQL database. Looks for a previously
defined AuthBy SQL clause with an Identifier of identifier and runs the SQL
query given by query. The first row in the result will be used as the value of the
special character. This type of lookup is done whenever the special character is
evaluated.

%0 - %99

Depending on the context, these may be replaced with context specific values,
which are documented in the relevant sections below.

You should note that some of these specifiers are only valid when a RADIUS message is
being processed. In any other context, such a specifier will be replaced by an empty
string.
In the following example, the log file will be stored in LogDir, with a name that starts
with the current year. If LogDir was /var/log and the current year was 1998, this
would result in a logfile name of /var/log/1998-logfile.
LogFile %L/%Y-logfile

Hint: Special characters of the form %{x:y} may be nested and contain other %{a:b} or
%h special forms, such as %{x:%{y:z}}, or %{x:%h} This can be useful in an example
like this, where the resulting Host parameter will be desthostname.com.
DefineGlobalVar hostname myhostname
DefineGlobalVar role myrolename
DefineGlobalVar myhostname_myrolename desthostname.com
.....
Host %{GlobalVar:%{GlobalVar:hostname}_%{GlobalVar:port}}

Radiator RADIUS Server

23 of 397

Configuration

Hint: You can use the SQL form of the special characters to do arbitrarily complicated
arithmetic in your special characters, even without doing a database lookup (although it
will still use the database server to do the arithmetic), like this:
Port sql:identifier:select (17 + 23) / SQRT(64)

5.3 Date Formatting

When Radiator is required to format a date for use with SQL and other databases it uses
a configurable DateFormat. A DateFormat can include special characters which are
interpreted according to the following table. Any other characters will be used verbatim.

TABLE 2.

24 of 397

DateFormat special characters

Specifier

Is replaced at run-time by:

%%

The percent character

%a

Day of the week, abbreviated

%A

Day of the week

%b

Month, of the year, abbreviated

%B

Month of the year

%c

ctime format: e.g. Sat Nov 19 21:05:57 1994

%d

Numeric day of the month DD, with a leading 0 if necessary.

%e

Numeric day of the month, no leading 0.

%D

MM/DD/YY

%h

Month of year, abbreviated

%H

Hour, 24 hour clock, leading 0

%I

Hour, 12 hour clock, leading 0

%j

Day of the year

%k

Hour

%l

Hour, 12 hour clock

%m

Month number (starting with Jan = 1)

%M

Minute, leading 0

%n

NEWLINE character

%o

Ornate day of month e.g. "1st", "2nd", "25th", ...

%p

AM or PM

%r

Time format: 09:05:57 PM

%R

Time format: 21:05

%S

Seconds, leading 0

%t

TAB character

%T

time format: 21:05:57

%U

Week number, Sunday as first day of week

%w

Day of the week, numerically, Sunday == 0

Radiator RADIUS Server

Configuration

Specifier

Is replaced at run-time by:

%W

Week number, Monday as first day of week

%x

Date format: 11/19/94

%X

Time format: 21:05:57

%y

Year (2 digits)

%Y

Year (4 digits)

%Z

Timezone in ASCII. eg: PST

For example, a DateFormat of %b %e, %Y %H:%M would format a date and time
like: Sep 3, 1995 13:37
5.4 SQL Bind Variables
Some SQL servers support the use of bind variables. Bind variables are used by the
SQL server to do a dynamic replacement of variables in an SQL statement. In some
SQL servers this can increase query performance by allowing the server to compile and
reuse the SQL compiled SQL query many times.
With Radiator SQL clause query parameters that support bind variables, you can specify
the query separately from the values for the bind variables. With most SQL servers, the
position of each bound variable is marked by a question mark (?) character. The bound
variables will be replaced (after special characters are replaced) at run time one-by one
in the order of the question marks in the query, and in the order of the bound variable
specifications.
For example, <AuthBy SQL> supports bound variables with the AuthSelect query
parameter. In this sample configuration fragment:
AuthSelect select PASSWORD from SUBSCRIBERS where USERNAME=? and
CLIENT=?
AuthSelectParam %0
AuthSelectParam %N

%0 (username) will be used to replace the first ? (the one for the USERNAME column),
and %N (NAS id) will be used to replace the second (the one for the CLIENT column).
Some SQL queries are cached when configured with bind variables. By default as much
as 32 queries can be cached. This can be changed in SqlDb.pm if required.
Caution: Not all SQL servers and their perl DBD modules support bound variables.
Check the documentation for your SQL server, and the Perl DBD module for your
server.
5.5 Address binding
One of the main functions of Radiator is to listen for UDP packets and TCP connections
from other systems according to the Radiator configuration. The various Radiator
clauses that can accept packets or connections from other systems all support the
BindAddress parameter, which controls which IP addresses Radiator will listen on. IP

Radiator RADIUS Server

25 of 397

Configuration

packets sent to an IP address which is on the Radiator host, but which Radiator has not
bound with BindAddress will not be received by Radiator.
The driver for this is that a single host may have multiple IP addresses, and those
addresses may be IPv4, IPv6 and/or IPv6-over-IPv4. You may require Radiator to only
honour requests directed to one of or a subset of the IP addresses for the host.
With BindAddress you can control which destination IP addresses Radiator will accept.
You can specify one or more IPv4 or IPv6 addresses, including wildcard addresses, with
the BindAddress parameter. The following forms may be used:

0.0.0.0 (the default) Any IPv4 address on the host

1.2.3.4 A specific IPv4 address on the host
:: Any IPv6 address on the host (and this may include any IPv4 address too, depending on how the host is configured)

2001:db8:148:100::31 A specific IPv6 address on the host

They may be combined in one BindAddress parameter like so:
BindAddress 0.0.0.0
BindAddress 192.87.30.31,2001:db8:148:100::31
BindAddress ::, 0.0.0.0
IPv6 support and IPv6 wildcard addresses are discussed in more detail later. See IPv6
support on page 26.
5.6 IPv6 support
Radiator supports IPv6 transport for RADIUS over UDP, RadSec (RFC 6614), DIAMETER and TACACS+. In other words, Radiator can send, receive and proxy requests
over IPv6.
Technical Note: Older Perls require Socket6.pm for IPv6 support. If Radiator can not
find working IPv6 support during the startup, an INFO level message will be logged. If
there is no working IPv6 support, RADIUS attributes with IPv6 attributes will be available with binary values only. IPv6 sockets are not supported.
Technical Note: Radiator 4.13 does not require ipv6: prefix for IPv6 addresses anymore. It is still allowed but should be avoided in new configurations. This prefix can be
used to request IPv6 address resolution for names. By default names are currently
resolved to IPv4 addresses only.
Various modules describe their IPv6 support in more detail. For example, AuthBy
LDAP2 can connect to LDAP servers over IPv6 and the detailed IPv6 information is
described in <AuthBy LDAP2> on page 149. Another example is the Resolver clause
for AuthBy DNSROAM which can query DNS servers over IPv6 and optionally fetch
IPv6 records if configured to do so.
SNMP support for IPv6 is described in <SNMPAgent> on page 67.

26 of 397

Radiator RADIUS Server

Configuration

Supported RADIUS specific IPv6 RFCs include:

RFC 3162 which defines e.g., Framed-IPv6-Prefix

RFC 4818 which defines Delegated-IPv6-Prefix
RFCs 4669 and 4671 which define IPv6 RADIUS server MIBs
RFC 6911 which defines e.g., Framed-IPv6-Address
RFC 6930 which defines the 6rd IPv6 deployment mechanism

Many protocols, such as DIAMETER, do not require specifically IPv4 or IPv6. Radiator
will support these protocols over both IP versions as long as the underlying operating
system and Perl modules offer support for the both protocols.
5.6.1 IPv6 Clients

IPv6 Client clauses support single IPv6 addresses and IPv6 CIDR notation. When IPv6
CIDR client clauses are used, you may want to consider installing Math::BigInt::GMP
or Math::BigInt::Pari Perl modules for more efficient IPv6 network mask calculation.
5.6.2 IPv6 wildcard listen address

If you are using recent Perl or Socket.pm you can configure separate IPv4 and IPv6
wildcard listen sockets by specifying both IPv6 and IPv4 wildcard addresses and turning on IPV6_V6ONLY socket option:
BindAddress ::,0.0.0.0
BindV6Only

See BindV6Only on page 31 for important information about this parameter.

Note the differences between operating systems: For example, on Linux
IPV6_V6ONLY is off by default. When it is off, the following will BindAddress parameter not work as expected. The bind to IPv6 wildcard address is done first and this does
not allow binding to IPv4 wildcard address afterwards:
BindAddress ::, 0.0.0.0
If IPV6_V6ONLY is set to 1, the IPv6 bind will not affect the IPv4 bind and the example BindAddress will work as expected. On OS X 10.9 it is possible to bind to IPv4
wildcard address first followed by IPv6 wildcard address. On Windows IPV6_V6ONLY
behaviour is the default.
Hint: Linux has a sysctl kernel parameter net.ipv6.bindv6only and special file
to control the system wide behaviour:
/proc/sys/net/ipv6/bindv6only
5.6.3 IPv4-mapped IPv6 address

When IPv4 packets are received by a system that uses IPv6 wildcard listen sockets, the
client addresses may show as IPv4-mapped IPv6 addresses. See BindV6Only on
page 31 for more info about this feature and how to control IPv4 mapped IPv6
addresses.

Radiator RADIUS Server

27 of 397

Configuration

Hint: configuring the operating system or Radiator to not use IPv4-mapped IPv6
addresses allows you to keep IPv4 and IPv6 clearly separate.
5.7 Global parameters
These parameters apply to the server as a whole, and do not appear inside a clause. They
are used to control the behaviour of the server as a whole.
5.7.1 Foreground

If this parameter is set, it makes the server run in the foreground instead of as a detached
daemon. No argument is required. The default behaviour is to run as a daemon. You
must run in the foreground if you want to run Radiator in a console window, from inetd
(see Section 16.3 on page 363), or from restartWrapper (see Section 16.1 on page 361).
# Run in the foreground
Foreground
5.7.2 LogStdout

If this parameter appears, it makes all logging output appear on STDOUT as well as in
the log file. No argument is required. The default behaviour is not to log to STDOUT.
You must be running in Foreground mode for this to have an effect.
# Log to stdout
LogStdout
5.7.3 Trace

Sets the priority level of trace messages to be logged in the log file (and printed on stdout if LogStdout is defined). The argument is an integer from 0 to 5, with the following
meanings:

0 ERR. Error conditions. Serious and unexpected failures

1 WARNING. Warning conditions. Unexpected failures
2 NOTICE. Normal but significant conditions.
3 INFO. Informational messages.
4 DEBUG. Debugging messages.
5 EXTRA_DEBUG. Incoming raw packet dumps in hexadecimal.

A trace level of 4 or more will produce all the possible tracing messages, including
dumps of every RADIUS message received and sent: you probably dont want that in a
production environment. The default tracing level is 0. You can change the current tracing level while Radiator is running on Unix platforms by signalling it with SIGUSR1
and SIGUSR2. See Section 6.0 on page 302.
# Show everything up to and including INFO level
Trace
3
5.7.4 LogRejectLevel

Log level for rejected authentication attempts. Can be overridden by Handler. Defaults
to 3 (INFO).

28 of 397

Radiator RADIUS Server

Configuration

5.7.5 AuthPort

Specifies which port(s) Radiator will listen on for RADIUS authentication requests. The
argument may be either a numeric port number or an alphanumeric service name as
specified in /etc/services (or its equivalent on your system). Multiple commaseparated ports may be specified. The default port is 1645. Note that the officially
assigned port number for RADIUS authentication has been changed to 1812. AuthPort
may contain special formatting characters. A typical use of special formatting characters
is with GlobalVar and command line arguments.
# Listen for authentication requests on port 1812 as per RFC
# 2865
AuthPort 1812

Note: Actually Radiator will also service accounting requests received on the authentication port without complaint.
Hint: You can prevent Radiator from binding to an authentication port by undefining
AuthPort:
# Dont bind to an auth port:
AuthPort

Hint: You can pass any port number as a command line argument to radiusd with a configuration like this:
AuthPort %{GlobalVar:authport}

and then run radiusd with an argument to set the port number like this:
radiusd authport=1810 ...

Hint: You could listen for requests on the 2 most common RADIUS authentication port
numbers with
AuthPort 1645,1812

Hint: Radiator will listen for requests on each given AuthPort (default 1645), on each IP
address specified by BindAddress (default 0.0.0.0). See Global parameters on
page 28.
5.7.6 AcctPort

Specifies which port Radiator will listen on for RADIUS accounting requests. The argument may be either a numeric port number or an alphanumeric service name as specified in /etc/services (or its moral equivalent on your system). Multiple commaseparated ports may be specified. The default port is 1646. Note that the officially
assigned port number for RADIUS accounting has been changed to 1813. AcctPort may
contain special formatting characters. A typical use of special formatting characters is
with GlobalVar and command line arguments.
# Listen for accounting requests on port 1813 as
# per RFC 2866
AcctPort 1813

Radiator RADIUS Server

29 of 397

Configuration

Note: Actually Radiator will also service authentication requests received on the
accounting port without complaint.
Hint: You can prevent Radiator from binding to an accounting port by undefining AcctPort:
# Dont bind to an accounting port:
AcctPort

Hint: You could listen for requests on the 2 most common RADIUS accounting port
numbers with
AcctPort 1646,1813

Hint: Radiator will listen for requests on each given AcctPort (default 1646), on each IP
address specified by BindAddress (default 0.0.0.0). See Global parameters on
page 28.
5.7.7 KeepSocketsOnReload

Technical Note: this option was introduced in Radiator 4.13 and is currently considered
experimental.
This optional flag controls whether opened RADIUS listen sockets should be left intact
on a reload request. When enabled, the changes in BindAddress, AuthPort and AcctPort
are ignored during reload. You may consider enabling this option when incoming
RADIUS requests should be buffered during the reload instead of ICMP unreachable
messages being sent back to the RADIUS clients.
5.7.8 BindAddress

This optional parameter specifies one or more addresses to listen for RADIUS requests
on. It is only useful if you are running Radiator on a multi-homed host (i.e. a host that
has more than one network address). Defaults to 0.0.0.0 (i.e. listens on all IPv4 networks connected to the host). Multiple addresses can be comma separated. IPv6
addresses can be given with the prefix ipv6:. Radiator will listen for requests on each
AuthPort and AcctPort on each BindAddress address.
Using this parameter, you can run multiple instances of Radiator on the one computer,
where each Radiator listens to RADIUS requests directed to a different host address.
BindAddress can include special formatting characters and multiple IPv4 and IPv6
addresses.
# Only listen on one network address
BindAddress 203.63.154.1

You can listen for requests on only some of many multi-homed addresses on this host:
BindAddress 200.10.5.4,200.10.7.3,::1

You can listen for requests directed to a particular IPv6 address:

BindAddress 2001:db8:0100:f101:0210:a4ff:fee3:9566

30 of 397

Radiator RADIUS Server

Configuration

See IPv6 support on page 26. Also see BindV6Only on page 31 for more about
IPv6 wildcard address :: special handling.
5.7.9 BindV6Only

This optional parameter allows you to explicitly set the IPV6_V6ONLY option for the
sockets listening to IPv6 wildcard address.
RFC 3493 Basic Socket Interface Extensions for IPv6 specifies a boolean socket
option IPV6_V6ONLY. When this option is turned off, IPv6 wildcard listen socket can
receive both IPv6 and IPv4 packets. Received IPv4 packets use special IPv4-mapped
address format where the IPv4 address is encoded after the 96-bit prefix 0:0:0:0:FFFF.
For example, request from IPv4 address 172.16.172.2 is mapped to IPv6 address
::ffff:172.16.172.2. In this case you may need to configure your Client clause
as <Client ::ffff:172.16.172.2>
IPV6_V6ONLY socket option is by default turned on by some operating systems and
off by some others.
Perl 5.16 or later or recent enough Socket.pm module is required for this parameter.
For more about IPv6 support and address binding, see IPv6 support on page 26 and
BindAddress on page 30.
5.7.10 LogDir

Specifies the directory to be used to store log files. Defaults to /var/log/radius on

Unix and Windows and to Macintosh HD:Applications:Radiator:etc on
MacOS. For convenience, the LogDir directory name can be referred to as %L in any
file name path in this configuration file.
# Put log files in /opt/radius instead
LogDir /opt/radius
5.7.11 DbDir

Specifies the directory to be used for user database files. Defaults to /usr/local/
etc/raddb on Unix and Windows and to Macintosh HD:Applications:Radiator:etc on MacOS. For convenience, the DbDir directory name can
be referred to as %D in any file name path in this configuration file.
# Look in /opt/etc/raddb for username database
DbDir /opt/etc/raddb
5.7.12 LogFile

The name of the log file. All logging messages will be time stamped and written to this
file. Each time this file is written to by Radiator, it opens, writes and then closes the file.
This means that you can safely rotate the log file at any time. The file name can include
special path name characters as defined in Special characters on page 20. The default
is %L/logfile, i.e. a file named logfile in LogDir. Defaults to %L:logfile on
MacOS.
You can disable all logging to the log file by setting LogFile to be the empty string.

Radiator RADIUS Server

31 of 397

Configuration

# Log file goes in /var/log, with year number

LogFile /var/log/%Y-radius.log
# Disable logging to log file completely
LogFile

If the file name starts with a vertical bar character (|) then the rest of the filename is
assumed to be a program to which the output is to be piped. Otherwise the output will be
appended to the named file:
# Pipe to my-log-prog
LogFile |/usr/local/bin/my-log-prog

Technical note: If LogFile is defined in your configuration file, a <Log FILE> will be
invisibly created to handle it. See Section 5.14 on page 60. You can customize the logging format, and also log microseconds by using <Log FILE> and its parameters instead
of LogFile
5.7.13 DictionaryFile

The name of the RADIUS dictionary file. The dictionary file defines the names to be
used for RADIUS attributes and their values. Its format is described in Section 15.1 on
page 354. The file name can include special path name characters as defined in Special
characters in file names on page 4. It can also include multiple comma-separated file
names. The default is %D/dictionary, i.e. a file called dictionary in DbDir. A dictionary file called dictionary that will work with most NASs and Terminal Servers is
included in the Radiator distribution.
# Dictionary file is in the current directory
DictionaryFile ./dictionary

Hint: You can load the normal dictionary and the old fashioned Ascend attributes dictionary with something like this:
# need the old Ascend non-vendor-specific attributes too
DictionaryFile %D/dictionary,%D/dictionary.ascend
5.7.14 ProxyUnknownAttributes

If this optional parameter is set, Radiator will forward attributes that are not present in
the dictionary. Unknown attributes are not proxied by default.
5.7.15 DiameterDictionaryFile

This optional parameter specifies additional Diameter dictionary entries. The entries in
DiameterDictionaryFile can replace or override any of the default entries hardwired into
DiaDict.pm. Unlike DictionaryFile, only one dictionary file name can be specified. The
Diameter dictionary is only used if you have a ServerDIAMETER clause in your configuration file. The file name can include special path name characters as defined in
Special characters in file names on page 4. The default is to use only the hardwired
dictionary in DiaDict.pm
DiameterDictionaryFile %D/my_private_diameter_attrs.dat

32 of 397

Radiator RADIUS Server

Configuration

5.7.16 PidFile

The name of the file where radiusd will write its process ID (PID) at start-up.
Defaults to %L/radiusd.pid on Unix and Windows. Defaults to %L:radiusd.pid on
MacOS. The file name can include special path name characters as defined in Special
characters on page 20. If the directory containing the file does not exist, it will attempt
to create the directory first.
# So we dont conflict with another radiusd
PidFile /tmp/radiusd2.pid
5.7.17 Syslog

This parameter is now obsolete, and is replaced by the <Log SYSLOG> clause. See
Section 5.15 on page 62.
5.7.18 SnmpgetProg

Specifies the full path name to the snmpget program. This optional parameter is only
used if you are using Simultaneous-Use with a NasType of Livingston or any other NAS
type that uses SNMP (see Figure 3 on page 43) in one of your Client clauses. Defaults
to /usr/bin/snmpget.
Hint: You should use the snmpget from Net-SNMP (http://www.net-snmp.org/). Dont
use the snmpget from CMU: its style of output is not understood by Radiator.
SnmpgetProg /usr/local/bin/snmpget
5.7.19 SnmpwalkProg

Specifies the full path name to the snmpwalk program. This optional parameter is only
used if you are using Simultaneous-Use with a NasType of Ascend, CiscoVPDN or
TigrisOld in one of your Client clauses. Defaults to /usr/bin/snmpwalk.
Hint: You should use the snmpwalk from Net-SNMP (http://www.net-snmp.org/).
Dont use the snmpwalk from CMU: its style of output is not understood by Radiator.
SnmpwalkProg /usr/local/bin/snmpwalk
5.7.20 FingerProg

Specifies the full path name to an external finger program. This optional parameter is
only used if you are using Simultaneous-Use with a NasType of Portslave, Ascend,
Shiva, Computone or any other NAS type that uses finger (see Figure 3 on page 43) in
any of your Client clauses. Defaults to using the standard Perl Net::Finger client that
does not require an external program.
FingerProg /usr/local/bin/finger
5.7.21 PmwhoProg

Specifies the full path name to the pmwho program. This optional parameter is only
used if you are using Simultaneous-Use with a NasType of TotalControl or any other
NAS type that uses pmwho (see Figure 3 on page 43) in one of your Client clauses.
Defaults to /usr/local/sbin/pmwho.
PmwhoProg /usr/local/bin/pmwho

Radiator RADIUS Server

33 of 397

Configuration

5.7.22 LivingstonMIB

This optional parameter specifies the name of the Livingston SNMP MIB. It is only
used if you are using Simultaneous-Use with a NasType of Livingston in one of your
Client clauses. Defaults to .iso.org.dod.internet.private.enterprises.307
This parameter is deprecated and will not be supported in the future.
5.7.23 LivingstonOffs

Specifies the global default value of where the last S port is before the one or two ports
specified in LivingstonHole are skipped (usually 22 for US, 29 for Europe). This
optional parameter is only used if you are using Simultaneous-Use with a NasType of
Livingston in one of your Client clauses. Defaults to 29.This value can be overridden on
a per-Client basis by using LivingstonHole in a Client clause, see Section 5.8.13 on
page 47.
5.7.24 LivingstonHole

Specifies the global default value of the size of the hole in the port list (usually 1 for US,
2 for Europe) that occurs at LivingstonOffs. This optional parameter is only used if you
are using Simultaneous-Use with a NasType of Livingston in one of your Client clauses.
Defaults to 2. This value can be overridden on a per-Client basis by using LivingstonHole in a Client clause, see Section 5.8.14 on page 47.
5.7.25 RewriteUsername

This parameter enables you to alter the User-Name in authentication and accounting
requests. For more details, see Section 14.0 on page 353. You can also rewrite user
names on a per-Client or per-Realm basis (see Section 5.7.25 on page 34 and
Section 5.8.10 on page 46).
You can have any number of RewriteUsername parameters. The rewrites will be applied
to the user name in the same order that they appear in the configuration file. The
rewrites are applied before any per-Client or per-Realm rewrites. At Trace level 4, you
can see the result of each separate rewrite for debugging purposes.
# Convert all user@realm1 to user@realm2, then
# change any user named mikem into fred
RewriteUsername
s/^([^@]+)@realm1/$1@realm2/
RewriteUsername
s/^mikem@/fred@/

# Convert a MSN realm/user into user@realm

RewriteUsername
s/^(.*)\/(.*)/$2\@$1/

# Translate all uppercase to lowercase

RewriteUsername
tr/A-Z/a-z/

# Remove any spaces from a username

RewriteUsername
s/\s+//g
5.7.26 SocketQueueLength

This optional parameter allows you to alter the lengths of the radius socket queues from
their default Operating System specific value. You may wish to set the queue lengths to
be longer than the default if your Radiator server is handling very large numbers of

34 of 397

Radiator RADIUS Server

Configuration

requests, and is near its performance limits. You should never need to set them to shorter
than the default. SocketQueueLength affects the length of both the authentication and
the accounting socket queues. SocketQueueLength has no effect on Windows.
Hint: You may need special privileges, or you may need to change your Operating System configuration to permit longer queue lengths than the default. Consult your operating system manuals for details on how to do this.
# Make a long queue length
SocketQueueLength 1000000
5.7.27 DefineFormattedGlobalVar

Defines a value for a global variable that can be accessed anywhere special formatting
characters are permitted. The syntax is:
DefineFormattedGlobalVar

variablename value

This example defines the global variable called variablename to be the string value.
The value can be accessed where special formatting characters are permitted with
%{GlobalVar:variablename}.
Within value, special formatting characters are permitted, so you can have one global
variable that depends on another global variable.
In the following example, the log file will be called ./detail-server1:
DefineFormattedGlobalVar
servername server1
LogFile
./detail-%{GlobalVar:servername}
5.7.28 DefineGlobalVar

Similar to DefineFormattedGlobalVar, except that special formatting characters in value

are not honoured. Deprecated. In the future the functionality of this parameter will
become identical to DefineFormattedGlobalVar.
5.7.29 StartupHook

This optional parameter allows you to define a Perl function that will be called during
server startup and restarts. Only one argument is passed to the hook: $_[0] will be set to
undef during startup and 1 for a restart (usually due to a SIGHUP)
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
StartupHook can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change or set up environment variables, umasks etc.
# Set up a umask to use for the life of this process
StartupHook sub { umask(0222);}

Radiator RADIUS Server

35 of 397

Configuration

5.7.30 ShutdownHook

This optional parameter allows you to define a Perl function that will be called just
before exiting after receiving a SIGTERM. No arguments are passed.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
ShutdownHook can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change or set up environment variables, umasks etc.
# Delete a lock file
ShutdownHook sub { unlink /tmp/xyzzy.lck;}
5.7.31 PreClientHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PreClientHook is called for each request before it passed to a Client
clause. A reference to the current request is passed as the only argument.
Caution: At the time this hook is run, integer attributes have not yet been unpacked and
decoded, and encrypted attributes have not yet been decrypted. If you need unpacked,
decrypted versions of these attributes, consider using a per-client ClientHook instead.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
PreClientHook can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things. The current request has its {Client} member set to a pointer to the Client clause
handling the request.
# Fake a new attribute into the request
PreClientHook sub { ${$_[0]}->add_attr(test-attr, \
test-value);}
5.7.32 USR1Hook

This optional parameter allows you to define a Perl function that will be called when a
SIGUSR1 signal is received by Radiator. On Unix, SIGUSR1 normally increases the
logging level by 1. If you define a USR1Hook, your hook will be called instead.
5.7.33 USR2Hook

This optional parameter allows you to define a Perl function that will be called when a
SIGUSR2 signal is received by Radiator. On Unix, SIGUSR2 normally decreases the
logging level by 1. If you define a USR2Hook, your hook will be called instead.

36 of 397

Radiator RADIUS Server

Configuration

5.7.34 WINCHHook

This optional parameter allows you to define a Perl function that will be called when a
SIGWINCH signal is received by Radiator.
5.7.35 MainLoopHook

This optional parameter allows you to define a Perl function that will be called once per
second from within the main dispatch loop.
5.7.36 UsernameCharset

This optional parameter checks that every user name consists only of the characters in
the specified character set. This can be useful to reject access requests that are due to
modem line noise. The value of the parameter is a perl character set specification. The
default is to permit all ASCII characters. See your Perl reference manual for details
about how to construct perl character set specifications.
This example permits only alphanumeric, period, dash and the at sign (note that the special characters . is escaped with a backslash):
UsernameCharset a-zA-Z0-9\[email protected] User

On Unix, this optional parameter sets the effective user ID (UID) that radiusd will run
as, provided radiusd starts as a suitably privileged user (usually as root). The value can
be a valid Unix user name or an integer UID.
5.7.38 Group

On Unix, this optional parameter sets the effective group ID (GID) and supplementary
groups that radiusd will run as, provided radiusd starts as a suitably privileged user (usually as root). The value can be a comma separated list of valid Unix group names or
integer GIDs. The first group will be set as the effective group ID.
If all group names fail to resolve, the call to change the groups will not be done.
5.7.39 MaxChildren

Specifies the maximum number of Fork children permitted at any one time. Any attempt
by an AuthBy to Fork (if so configured) will fail and the RADIUS request will be
ignored if there are already that many Forked children in existence. Defaults to 0, meaning no limit.
5.7.40 SnmpNASErrorTimeout

This optional parameter specifies for how long (in seconds) SNMP simultaneous use
checks will be blocked after an SNMP error during communications with a given NAS.
Defaults to 60 seconds.
5.7.41 ForkClosesFDs

This optional parameter tells Radiator to forcibly close all the child processes files
descriptors after a fork() on Unix. This is only necessary in very unusual circumstances
where child processes interfere with the parents connections to an SQL database.

Radiator RADIUS Server

37 of 397

Configuration

5.7.42 LogMicroseconds

For all configured loggers and the LogStdout logger, enables microseconds in the time
stamp.
Hint: LogMicroseconds can also be enabled separately for specific loggers using the
LogMicroseconds parameter in the respective Log clause.
5.7.43 FarmSize

This optional parameter allows you to specify how many server instances to create in a
server farm. A server farm is a set of identical Radiator servers, all monitoring the same
RADIUS sockets. Incoming RADIUS requests are distributed among the child servers
in the server farm. The main server acts as a supervisor, and restarts children that die or
are terminated. Unix only. Defaults to 0, which means no server farm, and only a single
instance of Radiator is run.
Hint: this parameter can be used to improve performance in some cases on platforms
that support multiple cores and fork().
Caution: This parameter, and the use of server farms is not compatible with many EAP
protocols, such as TLS, TTLS, PEAP etc. This is because such protocols rely in authentication state being held within each server process, and it is necessary for all the
requests for such protocols to go to the same Radiator instance.
5.7.44 FarmChildHook

Perl hook that is run in each child when FarmSize is used. The hook is run when the
child is started or restarted.
5.7.45 ClientHook

This hook will be called for each request after the request has been decoded but before
any other per-Client processing is done. A reference to the current request is passed as
the first argument and the Client object as the second argument.
5.7.46 DisableMTUDiscovery

If this optional parameter is set, it disables MTU discovery on platforms that support
that behaviour (currently Linux only). This can be used to prevent discarding of certain
large RADIUS packet fragments on supporting operating systems.
5.7.47 PacketDumpOmitAttributes

This optional parameter specifies a comma separated list of RADIUS attribute names
which will be omitted from RADIUS packet dumps in logs.
PacketDumpOmitAttributes EAP-Message,User-Password
5.7.48 StatusServer

Global default for the Client specific StatusServer parameter. See StatusServer on
page 38 for the details and default value.
5.7.49 DisabledRuntimeChecks

Radiator will try to check for commonly required but missing modules, some known
security vulnerabilities and possible other runtime parameters when it starts up. Any

38 of 397

Radiator RADIUS Server

Configuration

Hooks may also call the runtime check module functions, as required by the Hook
authors. Special formatting characters are supported.
Any checks that do not pass are logged but no other action is taken.
The currently recognised built-in checks are:

CVE-2014-0160 - the OpenSSL vulnerability commonly called Heartbleed

Digest::MD4 - required by MSCHAP and MSCHAP-v2 and their derivatives
The optional DisabledRuntimeChecks parameter allows you to define the checks that
should not be run.
Check for CVE-2014-0160 is done by trying to load Net::SSLeay and using the functions it provides to check for vulnerable OpenSSL versions. Many vendors have patched
their OpenSSL for CVE-2014-0160 without changing the OpenSSL version number.
For this reason the check may report your OpenSSL as vulnerable. The Net::SSLeay
functions for reporting OpenSSL version are only present in recent Net::SSLeay versions. For this reason Radiator may log a message about version check not being able to
determine OpenSSL version.
Digest::MD4 is required by MSCHAP, MSCHAP-V2 and their derivatives such as
EAP-MSHCHAP-V2. We recommend having Digest::MD4 installed unless you are
sure you will never need to support these authentication protocols.
# Our OpenSSL is patched but still reports vulnerable version
DisabledRuntimeChecks CVE-2014-0160

5.8 <Client xxxxxx>

The beginning of a Client clause. The clause continues until </Client> is seen on a line.
A Client clause specifies a RADIUS client that this server will listen to. Requests
received from any client not named in a Client clause in the configuration file will be
silently ignored. The DEFAULT client (if defined) will handle requests from clients that
are not defined elsewhere.
You must have a Client clause for every RADIUS client which your server is expected
to serve, or else a DEFAULT Client. In each Client clause replace the xxxxxx with
either the DNS name or the IP address of the host machine where the RADIUS client is
running, or with MAC: and the MAC address of the client. IPv4 and IPv6 addresses are
supported. IPv6 addresses can only be received if an IPv6 BindAddress has been specified (See Global parameters on page 28.). IPv4 and IPv6 CIDR addresses are permitted.
If an incoming request is capable of matching multiple Client clauses, the clause is chosen as follows

If multiple Client clauses have an exact IP match (same IP address or hostname

resolving to the same IP address), the last one listed in the configuration is chosen.
The same applies between multiple clauses with the same CIDR value: the last one
listed in the configuration is chosen.

Radiator RADIUS Server

39 of 397

Configuration

Exact match is chosen over CIDR match

A longer prefix CIDR match is chosen over shorter prefix CIDR match
CIDR match is chosen over MAC match
MAC match is chosen over DEFAULT

Hint: IPv6 addresses are not required to be prefixed with ipv6: with Radiator 4.13 or
later.
In the following example, the radius server will only respond to requests received from
either oscar.open.com.au or from IPv4 address 203.63.154.7 or IPv4 network
203.10.1.0/24 or from IPv6 address 2001:db8:100:f101:0:0:0:1 or from IPv6 network
2001:db8:100::/64 and each client has a different shared secret.
<Client oscar.open.com.au>
Secret XG1gFty566
</Client>
<Client 203.63.154.7>
# An IPv4 client
Secret kj1fgkj77878&
</Client>
<Client 203.10.1.0/24>
# An IPv4 class C address group
Secret ljdfhjlsd
</Client>
<Client ::ffff:203.10.1.0/120>
# Same as above but for requests received via IPv6
# wildcard listen socket when IPV6_V6ONLY socket option is
# not enabled. See BindV6Only on page 31.
Secret ljdfhjlsd
</Client>
<Client 2001:db8:100:f101:0:0:0:1>
# An IPv6 client
Secret pqr
</Client>
<Client 2001:db8:100::/64>
# An IPv6 /64 sized network
Secret pqr
</Client>
<Client MAC:2a-1f-09-5a-25-2a>
# Client identified by its MAC address
Secret gshgs
</Client>
# Handle all other clients with this secret
<Client DEFAULT>
Secret xyzzy
</Client>

Each Client clause can have a number of different parameters set, as described below.
Hint: If you are using an SQL database, you can list your clients in a RADCLIENTLIST table and use <ClientListSQL> (See <ClientListSQL> on page 52.) instead of

40 of 397

Radiator RADIUS Server

Configuration

listing them in your config file. This may be convenient, especially if you are using
RAdmin to manage your RADIUS system.
5.8.1 Secret

This defines the shared secret that will be used to decrypt RADIUS messages that are
received from this client. You must define a shared secret for each Client, and it must
match the secret configured into the client RADIUS software. There is no default. The
secret can be any number of ASCII characters. Any ASCII character except newline is
permitted, but it might be easier if you restrict yourself to the printable characters. For a
reasonable level of security, the Secret should be at least 16 characters, and a mixture of
upper and lower case, digits and punctuation. You should not use just a single recognizable word.
# This better agree with the client at
# oscar.open.com.au or we wont understand them!
<Client oscar.open.com.au>
Secret 666obaFGkmRNs666
</Client>
5.8.2 TACACSPLUSKey

Per-client TACACSPLUS key which will be used as the TACACS+ key if there is no
Key defined in the Server TACACSPLUS clause. Not used with RADIUS requests.
5.8.3 DefaultRealm

This optional parameter can be used to specify a default realm to use for requests that
have a User-Name that does not include a realm. The realm can then be used to trigger a
specific <Realm> or <Handler> clause. This is useful if you operate a number of NASs
for different customer groups and where some or all of your customers log in without
specifying a realm.
# Realmless logins to this NAS will be treated
# as if they are for realm open.com.au
<Client acc1.open.com.au>
Secret ....
DefaultRealm open.com.au
</Client>
<Realm open.com.au>
.....
</Realm>

Hint: Under some circumstances, some NASs send requests with no User-Name (usually for administrative reports). In that case, DefaultRealm will not add a realm to the
User-Name, nor create a User-Name.
5.8.4 IgnoreAcctSignature

If defined, this parameter prevents the server from checking the authenticator (sometimes called the signature) in accounting requests received from this client. (Contrary to
its name, it also affects the checking of Message-Authenticator in Access-Request messages). This parameter is useful because some clients do not send Authenticators that
conform to RFC 2866, while some other NASs do not set the authenticator at all. By
default, the server will check the Authenticator in accounting requests. By default, it
will log and ignore (i.e. not respond to) accounting requests that do not have a correct
Radiator RADIUS Server

41 of 397

Configuration

Authenticator, or any request that does not have a correct Message-Authenticator.

Regardless of the setting of this parameter, the server will always send a correctly computed Authenticator in reply to accounting requests. If you keep seeing log messages
like:
Bad authenticator in request from <client name>

and your accounting requests are not being stored, but you are authenticating OK, and
you are sure the shared secrets are correct, you might try enabling this parameter.
If you are seeing log messages like:
Bad EAP Message-Authenticator

when you receive an Access-Request, and you are sure the shared secrets are correct,
then it is possible your NAS is sending an incorrect implementation of MessageAuthenticator. You should try setting IgnoreAcctSignature.
Hint: Some NASs have separate secrets for authentication and accounting requests.
# brian.open.com.au has a broken NAS
<Client brian.open.com.au>
Secret 666obaFGkmRNs666
IgnoreAcctSignature
</Client>

Hint: Some NASs implement an incorrect Message-Authenticator. You will need to set
IgnoreAcctSignature with that NAS.
5.8.5 DupInterval

If more than 1 RADIUS request is received with the same source and destination IP
address, source port, RADIUS authenticator and RADIUS Identifier within DupInterval
seconds, the 2nd and subsequent requests are deemed to be duplicates or retransmissions. If the earlier request has already been replied to, then that reply will be resent
back to the NAS. Otherwise the duplicate request will be dropped. A value of 0 means
duplicates and retransmissions are always accepted, which might not be very wise,
except during testing. RFC 5080 recommends a value between 5 and 30 seconds.
Default is 10 seconds, which will detect and ignore duplicates due to multiple transmission paths and common retransmission intervals. In general you should never need to
worry about or set this parameter. Ignore it and accept the default.
# brian.open.com.au is being tested
<Client brian.open.com.au>
Secret 666obaFGkmRNs666
DupInterval 0
</Client>

42 of 397

Radiator RADIUS Server

Configuration

5.8.6 NasType

This optional parameter specifies the vendor type of this Client. It is required if you
want Radiator to directly query the NAS to check on simultaneous sessions. The allowable values for NasType are:

TABLE 3.

Allowable values of NasType, and their NAS query method

NasType

Method used to connect to NAS

Livingston

SNMP

Portslave

Finger

PortslaveLinux

Finger. For use with Portslave running on

a Linux host, understands Linux finger
format.

PortslaveMoxa

Finger, requires ctlportslave to be

installed as fingerd on the target Linux
host. Supports Linux running Portslave
and a Moxa multiport.

Cisco

SNMP

CiscoVPDN

SNMP, detects users terminated on a l2tp,

pptp or l2f tunnel.

CiscoSessionMIB

SNMP, using the Session MIB available

in Cisco IOS 12.2.15T and later.

Colubris

SNMP

Ascend

Finger

AscendSNMP

SNMP

Computone

Finger

Cyclades

SNMP

Hiper

SNMP

NomadixSNMP

SNMP

Redback

SNMP

Shiva

Finger

TotalControl

pmwho

TotalControlSNMP

SNMP

Bay, Bay5399SNMP,
Bay8000SNMP

SNMP

Bay4000SNMP

SNMP

BayFinger

Finger

Tigris, TigrisNew

SNMP for new version of the Tigris MIB

(i.e. firmware revision 10.1.4.14 or
greater)

TigrisOld

SNMP for old versions of the Tigris MIB

NortelCVX1800

SNMP

Xyplex

Finger

Radiator RADIUS Server

43 of 397

Configuration

TABLE 3.

Allowable values of NasType, and their NAS query method

NasType

Method used to connect to NAS

Patton

SNMP

Portmaster3

SNMP

Portmaster4

pmwho For use with Portmaster 4s running ComOS 4.1 or later

Ping

Verifies a login by ICMP pinging the

Framed-IP-Address of the dialup user.
This is not foolproof if the IP address has
been reallocated. Requires that Radiator
be run with root permissions (on Unix).

ignore

Does not contact NAS under any circumstances. Always assumes that there are no
multiple logins.

unknown

The default value. Does not connect to

the NAS under any circumstances.
Always assumes the Session Database is
correct.

You can specify the maximum number of sessions allowable for a single user with the
Simultaneous-Use check item, or for all the users in a Realm with the MaxSessions
parameter in <Realm> or <Handler> clauses. In either case, during authentication,
Radiator first checks its Session Database (see Section 5.11 on page 54 and Section 5.12
on page 58) to see if the users session count is exceed. Since this count can be inaccurate in the face of NAS reboots, lost packets etc. Radiator can also double check the
count by interrogating the NAS directly (you enable this by specifying NasType in the
Client clause, see Section 5.8.6 on page 43).
If you specify unknown or do not specify any value at all, Radiator will never try to
contact the NAS to check the users sessions, and it will always assume that the sessions
it thinks are present are correct. If you specify ignore, Radiator will never try to contact the NAS to check the users sessions, and it will always assume that there are no
multiple sessions.
Hint: If Radiator detects problems or time-outs when using finger to verify simultaneous connections, it assumes that the user is still online (i.e. it assumes that the Session
Database is correct).
Hint: You can also use NasType as a check item, to confirm that a request came from a
client with a specific NasType.
Hint: You can add support for a new or custom NasTypes by adding a suitably named
module to the Radius/Nas directory. Your new module should implement the isOnline
function. See the existing Radius/Nas/*pm modules for examples. If you do implement
your own module, send us a copy so we may include it in future releases.

44 of 397

Radiator RADIUS Server

Configuration

Radiator uses a number of global parameters to specify how to communicate with the
NAS. See SnmpgetProg, FingerProg PmwhoProg, LivingstonMIB, LivingstonOffs and
LivingstonHole.
# Make Radiator ask the NAS to confirm multiple logins.
# its a Total Control box
NasType TotalControl
5.8.7 SNMPCommunity

This optional parameter specifies the SNMP Community name to use to connect to the
NAS when NasType uses SNMP. It is ignored for any other NasType. Defaults to public.
SNMPCommunity

private

5.8.8 FramedGroupBaseAddress

This optional parameter is used in conjunction with the Framed-Group reply attribute or
the FramedGroup AuthBy parameter to automatically generate IP addresses for users
logging in. It is ignored unless the user has a Framed-Group reply item, or unless their
AuthBy clause contains a FramedGroup parameter. You can have as many FramedGroupBaseAddress items as you like.
You would only need to use this mechanism if you are using a NAS that is unable to
choose IP addresses from an address pool, or if you want a more complicated address
allocation policy than your NAS can support.
When a user logs in, Radiator can automatically choose an IP address for the user and
return it to the NAS in a Framed-IP-Address reply attribute. To make this happen, you
must specify one or more FramedGroupBaseAddress items in each Client clause, and
you must specify a Framed-Group reply item for each user for whom you want address
allocation. If the user is authenticated, Radiator will generate a Framed-IP-Address
using Framed-Group reply item and the NAS-Port in the request. The Framed-Group in
a user record selects the nth FramedGroupBaseAddress (0 based) from the Client they
are logging in to, and NAS-Port is added to the last byte (modulo 255 or FramedGroupMaxPortsPerClassC) to generate a Framed-IP-Address.
Hint: Radiator also includes a much more sophisticated mechanism for allocating IP
addresses from an SQL database or DHCP. See <AuthBy DYNADDRESS> on
page 173.
In the example below, if the user logs in on the Client at port 5, and their Framed-Group
reply item is 1, they will be allocated a Framed-IP-Address of 10.0.1.6 (i.e. 10.0.1.1 + 5)
In the Radiator configuration file:
<Client ..>
# This is the base address for Framed-Group = 0
FramedGroupBaseAddress
10.0.0.1
# This is the base address for Framed-Group = 1
FramedGroupBaseAddress
10.0.1.1
# This is the base address for Framed-Group = 2
FramedGroupBaseAddress
10.0.2.1

Radiator RADIUS Server

45 of 397

Configuration

....
</Client>

In the users file for each user you want to allocate an address for:
mikem

User-Password = fred
Framed-Group = 1,
Framed-Protocol = PPP,
etc.

Alternatively, in an AuthBy clause:

<AuthBy whatever...>
# This will cause all users authorized by this clause
to get
# an address allocated from the block starting
10.0.1.1,
# unless overridden by a user-specific Framed-Group
FramedGroup 1
.....
</AuthBy>
5.8.9 FramedGroupMaxPortsPerClassC

This optional parameter defines the maximum number of ports that can be mapped to a
class C or class B FramedGroupBaseAddress. The default is 255, which means that any
address from 0 up to 255 in the 3rd or 4th octets will be permitted. It actually specifies
the modulus for computing the 3rd and 4th octets of addresses calculated from FramedGroupBaseAddress. You might use this to limit the number of addresses used in each
address block, or to prevent the allocation of the last address in a class C address block.
5.8.10 RewriteUsername

This parameter enables you to alter the user name in all authentication and accounting
requests from this client before being despatched to any Realm or Handler. For more
details, see Section 14.0 on page 353.
You can have any number of RewriteUsername parameters. The rewrites will be applied
to the user name in the same order that they appear in the configuration file. The
rewrites are applied after any global rewrites, but before any per-Realm rewrites. At
Trace level 4, you can see the result of each separate rewrite for debugging purposes.

# Convert all user@realm1 to user@realm2, then

# change any user named mikem into fred
RewriteUsername
s/^([^@]+)@realm1/[email protected]/
RewriteUsername
s/^mikem@/fred@/

# Convert a MSN realm/user into user@realm

RewriteUsername
s/^(.*)\/(.*)/$2\@$1/

# Translate all uppercase to lowercase

RewriteUsername
tr/A-Z/a-z/

46 of 397

Radiator RADIUS Server

Configuration

5.8.11 IdenticalClients

This optional parameter specifies a list of other clients that have an identical setup. You
can use this parameter to avoid having to create separate Client clauses for lots of otherwise identical clients. The value is a list of client names or addresses, separated by white
space or comma. Each client may be specified as an IP address (IPv4 or IPv6), a MAC
address in the form MAC:aa-bb-cc-dd-ee-ff, or an IPv4 or IPv6 CIDR address in the
form nn.nn.nn/nn. You can have any number of IdenticalClients lines.
Hint: When you use the Client-Id check item, it matches against the name or address in
the <Client xxxx> line, but not against any of the values listed in IdenticalClients.
IdenticalClients
IdenticalClients
IdenticalClients
IdenticalClients
IdenticalClients
IdenticalClients

10.1.1.1 10.1.1.2 nas.mydomain.com

10.1.1.7 10.1.1.8 10.1.1.9
203.63.154.1 localhost
MAC:11-22-33-44-55-66
203.10.1.0/24 220.10.0.0/16
2001:db8:22:1::/64 2001:db8:22:2::/64

5.8.12 PreHandlerHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PreHandlerHook is called for each request after per-Client username
rewriting and duplicate rejection, and before it is passed to a Realm or Handler clause.
A reference to the current request is passed as the only argument.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
PreHandlerHook can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things.
# Fake a new attribute into the request
PreHandlerHook sub { ${$_[0]}->add_attr(test-attr, \
test-value);}
5.8.13 LivingstonOffs

Specifies the value of where the last S port is before the one or two ports specified in
LivingstonHole are skipped (usually 22 for US, 29 for Europe). This optional parameter
is only used if you are using Simultaneous-Use with a NasType of Livingston in this
Client clause. Defaults to the global value of LivingstonOffs, see Section 5.7.23 on
page 34.
5.8.14 LivingstonHole

Specifies the value of the size of the hole in the port list (usually 1 for US, 2 for Europe)
that occurs at LivingstonOffs. This optional parameter is only used if you are using
Simultaneous-Use with a NasType of Livingston in this Client clause. Defaults to the
global value of LivingstonOffs, see Section 5.7.24 on page 34.

Radiator RADIUS Server

47 of 397

Configuration

5.8.15 UseOldAscendPasswords

This optional parameter tells Radiator to decode all passwords received from this Client
using the old style (non RFC compliant) method that Ascend used to use on some
NASs. The symptom that might indicate a need for this parameter is that passwords
longer than 16 characters are not decoded properly.
5.8.16 StatusServer

Normally, when a Status-Server request is received, Radiator will reply with some statistics including the total number of requests handled, the current request rate etc. You
can control Status-Server response by setting StatusServer to

off - Status-Server requests are ignored

minimal - Reply without any attributes
default - Reply with statistics
5.8.17 StatusServerShowClientDetails

Normally, when a Status-Server request is received, Radiator will reply with some statistics including the total number of requests handled, the current request rate etc. When
you set the optional StatusServerShowClientDetails for a Client, the reply to StatusServer will also include details about that Client. This can result in a lengthy reply
packet. The default is not to send the additional Client details for any Clients.
<Client xxx>
# Show stats about this client in Server-Status replies
StatusServerShowClientDetails
Secret xxx
....
</Client>
5.8.18 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It
can also be used in Client-Identifier matches with Handlers:
<Client www-proxy.open.com.au>
Secret
mysecret
Identifier
www-proxy
</Client>
# www-proxy
<Handler Client-Identifier=www-proxy>
<AuthBy FILE>
Filename
%D/www-proxy-users
</AuthBy>
</Handler>
5.8.19 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5. This is useful for logging packets that pass through this clause in more detail
than other clauses during testing or debugging. The packet tracing will stay in effect
until it passes through another clause with PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace

48 of 397

Radiator RADIUS Server

Configuration

5.8.20 DefaultReply, FramedGroup, StripFromReply,

AllowInReply, AddToReply, AddToReplyIfNotExist, DynamicReply

These optional parameters affect replies to packets that were handled by this Realm or
Handler clause. The parameters have the same meanings as described in <AuthBy
xxxxxx> on page 82. They can be used to make special adjustments to the contents of
reply packets.
5.8.21 NoIgnoreDuplicates

This optional parameter specifies one or more RADIUS packet types where duplicates
are not ignored. NoIgnoreDuplicates is a comma or space separated list of request types,
such as:

Access-Request
Accounting-Request
Status-Server
etc...

By default any request with an identical identifier received from the same NAS within
the DupInterval period will be ignored or the previous reply retransmitted. If the request
type is specified in NoIgnoreDuplicates, it will not be ignored, irrespective of the time
since reception of a previous copy.
# Always handle dups of Accounting-Request packets
NoIgnoreDuplicates Accounting-Request
5.8.22 StripFromRequest

Strips the named attributes from the request before passing it to any Handlers or
Realms. The value is a comma separated list of attribute names. StripFromRequest
removes attributes from the request before AddToRequest adds any to the request.
There is no default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.8.23 AddToRequest

Adds attributes to the request before passing it to any Handlers or Realms. Value is a list
of comma separated attribute value pairs all on one line, exactly as for any reply item.
StripFromRequest removes attributes from the request before AddToRequest and
AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.
# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h
5.8.24 AddToRequestIfNotExist

Adds attributes to the request before passing it to any Handlers or Realms. Unlike
AddToRequest, an attribute will only be added if it does not already exist in the request.
Value is a list of comma separated attribute value pairs all on one line, exactly as for any
reply item. StripFromRequest removes attributes from the request before AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.

Radiator RADIUS Server

49 of 397

Configuration

# Append a Filter-ID and host name if they are not there already
AddToRequestIfNotExist Calling-Station-Id=1,Login-IP-Host=%h
5.8.25 ClientHook

This hook will be called for each request after the request has been decoded but before
any other per-Client processing is done. A reference to the current request is passed as
the only argument.
5.8.26 UseContentsForDuplicateDetection

This optional flag causes the Client to use an alternative duplicate detection algorithm.
Normally, Client detects duplicate requests by looking at the source IP address, source
IP port, the RADIUS request authenticator and the RADIUS request identifier of incoming requests. Requests with those identical attributes received in the last DupInterval
seconds are deemed to be duplicates.
In a ServerFarm environment, where the server farm is being used to load balance
using, say, the EAPBALANCE module, the back end servers will receive requests (and
potentially duplicate requests) from any of the front end servers in the server farm. This
can defeat the normal duplicate detection algorithm. UseContentsForDuplicateDetection causes Client to look only at the contents of the request that would not be altered by
passing through a proxy server, allowing duplicates to be reliably detected, even in a
server farm. The packet contents used for duplicate detection when UseContentsForDuplicateDetection is set are:

RADIUS authenticator
User-Name
Called-Station-Id
Calling-Station-Id

It is essential that this parameter be defined in the Client clauses of back end servers of
an EAPBALANCE Server Farm architecture, otherwise duplicate detection will not be
performed correctly.
5.8.27 RequireMessageAuthenticator

Normally, Client clause checks the value of any Message-Authenticator attribute (if
present) in incoming requests (EAP or otherwise), and an incorrect authenticator causes
the request to be IGNOREd. The optional RequireMessageAuthenticator flag causes
this Client to require a (correct) Message-Authenticator attribute to be present in all
incoming requests.
5.9 <ClientListLDAP>
This optional clause allows you to specify your RADIUS clients in an LDAP database
in addition to (or instead of) your Radiator configuration file. When Radiator starts up
(and when it receives a SIGHUP signal), it queries the LDAP database with the SearchFilter, and the results of that query are used to add details of RADIUS Clients that Radiator will respond to. One Client clause is created for each matching LDAP record found.
ClientListLDAP fetches the LDAP attributes specified by the ClientAttrDef parameters,
and uses them to set the parameters in each Client clause. If you wish, you can have

50 of 397

Radiator RADIUS Server

Configuration

some client details in your Radiator configuration file, and some in ClientListLDAP
(although this might be confusing to future administrators).
Hint: There is a sample LDAP schema compatible with the default behaviour of ClientListLDAP in goodies/radiator-ldap.schema in your Radiator distribution. There are
some example LDAP records for this schema in goodies/radiator-ldap.ldif.
Hint: There is an example configuration file showing how to configure ClientListLDAP
in goodies/ldapradius.cfg in your Radiator distribution.
ClientListLDAP understands the following parameters:
5.9.1 BaseDN, Host, Port, UseSSL, UseTLS, AuthDN, AuthPassword, Debug, Timeout,
FailureBackoffTime, NoBindBeforeOp, Scope, SSLVerify, SSLCiphers, SSLCAPath,
SSLCAFile, SSLCAClientCert, SSLCAClientKey, Version, Deref

These parameters are used to control the connection to the LDAP server. ClientListLDAP opens a new connection to the LDAP server at the beginning of a query, and
closes it after getting the client data.
These parameters are set in the same was as described in <AuthBy LDAP2> on
page 149.
5.9.2 SearchFilter

This parameter specifies the LDAP search filter that will be used to find the LDAP
records that contain Client data. The default is (objectclass=oscRadiusClient), which is
compatible with the example schema provided in goodies/radiator-ldap.schema in your
Radiator distribution. Special characters are supported.
This example finds oscRadiusClient LDAP objects, but only the ones for a specific
___location. It shows how LDAP boolean expressions can be used to select records from
the LDAP database.
SearchFilter (&(objectclass=oscRadiusClient)(___location=my_pop_1))
5.9.3 ClientAttrDef

This optional parameter specifies the name of an LDAP attribute to fetch, and the name
of the Client parameter that it will be used for in the Client clause. The format is:
ClientAttrDef ldapattrname,clientparamname

where ldapattrname is the name of the LDAP attribute to fetch, and clientparamname is
the name of the Client clause parameter (See <Client xxxxxx> on page 39.). There
can be (and usually are) multiple ClientAttrDef parameters. If the specified ldapattrname is not present in a record, then the matching clientparamname will not be set and
will assume its default value according to the normal behaviour of the Client clause.
If no ClientAttrDef lines are defined, defaults to the equivalent of the following, which
is compatible with the example schema provided in goodies/radiator-ldap.schema. Note
that not all these attributes are required in your LDAP database. The only ones that must
be provided are for Name and Secret.

Radiator RADIUS Server

51 of 397

Configuration

ClientAttrDef oscRadiusClientName,Name
ClientAttrDef oscRadiusSecret,Secret
ClientAttrDef oscRadiusInoreAcctSignature,IgnoreAcctSignature
ClientAttrDef oscRadiusDupInterval,DupInterval
ClientAttrDef oscRadiusNasType,NasType
ClientAttrDef oscRadiusSNMPCommunity,SNMPCommunity
ClientAttrDef oscRadiusLivingstonOffs,LivingstonOffs
ClientAttrDef oscRadiusLivingstonHole,LivingstonHole
ClientAttrDef oscRadiusFramedGroupBaseAddress,FramedGroupBaseAddress

ClientAttrDef oscRadiusFramedGroupMaxPortsPerClassC,FramedGroupMaxPortsPerClassC
ClientAttrDef oscRadiusFramedGroupPortOffset,FramedGroupPortOffset
ClientAttrDef oscRadiusRewriteUsername,RewriteUsername
ClientAttrDef oscRadiusUseOldAscendPasswords,UseOldAscendPasswords
ClientAttrDef oscRadiusStatusServerShowClientDetails,StatusServerShowClientDetails
ClientAttrDef oscRadiusPreHandlerHook,PreHandlerHook
ClientAttrDef oscRadiusPacketTrace,PacketTrace
ClientAttrDef oscRadiusIdenticalClients,IdenticalClients
ClientAttrDef oscRadiusNoIgnoreDuplicates,NoIgnoreDuplicates
ClientAttrDef oscRadiusDefaultReply,DefaultReply
ClientAttrDef oscRadiusFramedGroup,FramedGroup
ClientAttrDef oscRadiusStripFromReply,StripFromReply
ClientAttrDef oscRadiusAllowInReply,AllowInReply
ClientAttrDef oscRadiusAddToReply,AddToReply
ClientAttrDef oscRadiusAddToReplyIfNotExist,AddToReplyIfNotExist
ClientAttrDef oscRadiusDynamicReply,DynamicReply
ClientAttrDef oscRadiusStripfromRequest,StripfromRequest
ClientAttrDef oscRadiusAddToRequest,AddToRequest
ClientAttrDef oscRadiusAddToRequestIfNotExist,AddToRequestIfNotExist
ClientAttrDef oscRadiusDefaultRealm,DefaultRealm
ClientAttrDef oscRadiusIdentifier,Identifier
5.9.4 RefreshPeriod

If this optional parameter is set to non-zero, it specifies the time period in seconds that
ClientListLDAP will refresh the client list by rereading the database. If set to 0, then
ClientListLDAP will only read the client list from the database at startup and on
SIGHUP. Defaults to 0.
# Reread the client list every hour
RefreshPeriod 3600

5.10 <ClientListSQL>
This optional clause allows you to specify your RADIUS clients in an SQL database
table in addition to (or instead of) your Radiator configuration file. When Radiator starts
up (and when it receives a SIGHUP signal), it queries the SQL database with the GetClientQuery SQL query, and the results of that query are used to add details of RADIUS

52 of 397

Radiator RADIUS Server

Configuration

Clients that Radiator will respond to. If you wish, you can have some client details in
your Radiator configuration file, and some in ClientListSQL (although this might be
confusing to future administrators).
Hint: The example database schemas provided in the goodies directory of your Radiator
distribution all include an example RADCLIENTLIST table that will work with ClientListSQL.
ClientListSQL understands the following parameters:
5.10.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database. They need to be set in a
similar way to as for <AuthBy SQL> (see Section 5.30 on page 111). They specify the
DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserspassword
5.10.2 GetClientQuery

This parameter specifies the SQL query that will be used to fetch client details from the
SQL database specified by DBSource. The database can store all the same parameters
that are used to configure a <Client> clause (See <Client xxxxxx> on page 39.)
The default for this parameter is:
select NASIDENTIFIER,SECRET,IGNOREACCTSIGNATURE,DUPINTERVAL,
DEFAULTREALM,NASTYPE,SNMPCOMMUNITY,LIVINGSTONOFFS,
LIVINGSTONHOLE,FRAMEDGROUPBASEADDRESS,
FRAMEDGROUPMAXPORTSPERCLASSC,REWRITEUSERNAME,
NOIGNOREDUPLICATES,PREHANDLERHOOK from RADCLIENTLIST

The default GetClientQuery will work with the sample database schemas provided in
the goodies directory of your Radiator distribution.
Your database table must include at least the first and second fields (i.e. the NAS name
or IP address or MAC address and the shared secret). All the other fields are optional,
but if they occur, they must occur in the given order. When they occur, they are used to
initialize the Client parameter of the same name as shown above. The
FRAMEDGROUPBASEADDRESS column may contain multiple comma-separated
base addresses. The PREHANDLERHOOK column can contain either the text of a
hook or a hook filename in the form file:/path/to/hook. You can customize
the GetClientQuery select clause to have additional fields. If they are present in the
result of GetClientQuery, they will be used as described below. Field numbers are 0
based, with field number 0 as the first field, so for example Identifier, field 14 has an
index of 14, but is the 15th entry in the returned array.

Identifier field as field 14,

DefaultReply as field 15,

Radiator RADIUS Server

53 of 397

Configuration

FramedGroup as field 16,

StripFromReply as field 17,
AllowInReply as field 18,
AddToReply as field 19,
AddToReplyIfNotExist as field 20,
DynamicReply as field 21,
AddToRequest as field 22,
StripFromRequest as field 23,
AddToRequestIfNotExist as field 24,
ClientHook as field 25,
UseContentsForDuplicateDetection as field 26
A comma-separated list of flag names as field 27. Each comma separated name in
the field will be used to set a Client flag type parameter. For example if field 27 has
the value: IgnoreAcctSignature,UseOldAscendPasswords,StatusServerShowClientDetails, it will set the IgnoreAcctSignature, UseOldAscendPasswords and StatusServerShowClientDetails flag parameters in the resulting Client.
# Our custom client table only has NAS identifier,
# shared secret and default realm in it:
GetClientQuery select NAME,SECRET,NULL,NULL,DREALM from CLIENTS

5.10.3 RefreshPeriod

If this optional parameter is set to non-zero, it specifies the time period in seconds that
ClientListSQL will refresh its client list by rereading the database. If set to 0, then ClientListSQL will only read the client list from the database once at startup and on
SIGHUP. Defaults to 0.
When the RefreshPeriod expires and the list of clients is read from the SQL database,
any Clients previously created by this ClientList are cleared and a new set of clients
read from the database. This means that Clients defined in the configuration file will not
be removed. It also means that multiple ClientListSQL clauses with non-zero RefreshPeriods will not remove each others Clients.
# Reread the client list every hour
RefreshPeriod 3600
5.10.4 DisconnectAfterQuery

This optional parameter causes the SQL database to be disconnected after each database
query. This can be helpful in cases where firewalls etc close connections that have been
idle for a long time.
5.11 <SessionDatabase SQL>
This optional clause specifies an external SQL Session Database for radiusd. The Session Database is used to hold information about current sessions as part of Simultaneous-Use limit checking. It can also be used by external utilities for querying the on-line
user population. If you dont specify a SessionDatabase clause in your configuration

54 of 397

Radiator RADIUS Server

Configuration

file, the database will be kept internal to radiusd, which is faster, but cant be used to
synchronize multiple instances of Radiator.
If you want to enforce Simultaneous-Use limits and you are running multiple instances
of Radiator, you must specify an external Session Database for each Radiator, and you
must ensure that all instances of Radiator use the same Session Database. If you fail to
do this, Radiator will not be able to correctly enforce Simultaneous-Use limits, and may
allow people to log in who have already exceeded their limit.
SessionDatabase SQL has a number of customizable SQL statements (AddQuery,
DeleteQuery, UpdateQuery, ReplaceQuery, ClearNasQuery and CountQuery). These
statements are used to add, remove, maintain and count the entries in the SQL Session
Database. The default statements will work with the example RADONLINE table in the
example SQL schemas in the goodies directory. If you wish, you can use more or fewer
columns in your SQL Session Database, and you can change the names of the columns
or the table. If you do use a different table schema, you will probably have to change
statements to match your schema.
You can configure the SQL database(s) that SessionDatabase SQL uses in the same way
as with AuthBy SQL: by defining one or more DBSource, DBUsername and DBAuth
lines. See Section 5.30 on page 111 for more details.
You can specify multiple databases by using multiple DBSource, DBUsername and
DBAuth parameters. Whenever Radiator tries to connect to an SQL Session Database,
SQL will try to connect to the first DBSource listed, using the first DBUsername and
DBAuth parameters. If that connection fails, it will try the second, third etc., until all the
databases are exhausted, and finally gives up.
SessionDatabase SQL is tolerant of database failures. If your database server goes
down, Radiator will try to reconnect to a database as described above, starting again at
the first database you specified. Whichever database Radiator connects to, it will stay
connected to it until that database becomes unreachable, at which time it will again
search for a database, starting at the first again. If on the other hand, Radiator is not able
to connect to any SQL server, it will stop enforcing Simultaneous-Use limits until one
of its databases comes back on line.
Hint: You can use radwho.cgi to view the contents of your Session Database. See
Section 12.0 on page 332.
SessionDatabase SQL understands the following parameters:
5.11.1 Identifier

This optional parameter assigns a name to the Session Database, so it can be referred to
in other parts of the configuration file, such as the SessionDatabase parameter in Handler.
# Here is a useful name for this Session Database
Identifier SDB1

Radiator RADIUS Server

55 of 397

Configuration

5.11.2 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database. They need to be set in a
similar way to as for <AuthBy SQL>. They specify the DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.11.3 SQL Bind Variables

All SessionDatabase SQL statements support SQL bind variables. See SQL Bind Variables on page 25 for more. An example of DeleteQuery with bind variables is:
DeleteQuery delete from RADONLINE where NASIDENTIFIER =?
and NASPORT=?
DeleteQueryParam %1
DeleteQueryParam %2
5.11.4 AddQuery

This SQL statement is executed whenever a new user session starts (i.e. when an
Accounting-Request Start message is received). It is expected to record the details of the
new session in the SQL database. Special formatting characters may be used (the
%{attribute} ones are probably the most useful). Special formatting characters may be
used. %1 by the NAS IP address, %2 by the NAS-Port, %3 by the SQL quoted AcctSession-Id. If AddQuery is defined as an empty string, then the query will not be executed.
%0 is replaced by the quoted original username or rewritten username, see SessionDatabaseUseRewrittenName on page 80.
It defaults to:
insert into RADONLINE (USERNAME, NASIDENTIFIER, NASPORT,
ACCTSESSIONID, TIME_STAMP, FRAMEDIPADDRESS, NASPORTTYPE,
SERVICETYPE) values (%0, %1, %2, %3, %{Timestamp},
%{Framed-IP-Address}, %{NAS-Port-Type}, %{Service-Type})
5.11.5 DeleteQuery

This SQL statement is executed whenever a user session finishes (i.e. when an Accounting-Request Stop message is received). It is expected to remove the details of the session from the SQL database. Special formatting characters may be used. %1 by the NAS
IP address, %2 by the NAS-Port, %3 by the SQL quoted Acct-Session-Id and %4 by the
Framed-IP-Address. If DeleteQuery is defined as an empty string, then the query will
not be executed.
%0 is formatted as defined in section AddQuery on page 56. SQL bind variables are
supported
It defaults to:
delete from RADONLINE where NASIDENTIFIER=%1 and NASPORT=0%2

56 of 397

Radiator RADIUS Server

Configuration

5.11.6 UpdateQuery

This SQL statement is executed whenever Accounting-Request Alive or Interim-Update

message is received. It is expected to update the details of the session in the SQL database. Special formatting characters may be used (the %{attribute} ones are probably the
most useful). %1 by the NAS IP address, %2 by the NAS-Port, %3 by the SQL quoted
Acct-Session-Id. If UpdateQuery is defined as an empty string, then the query will not
be executed and ReplaceQuery, if defined, or AddQuery otherwise, will be used. The
default is the empty string.
%0 is formatted as defined in section AddQuery on page 56. SQL bind variables are
supported.
5.11.7 ClearNasQuery

This SQL statement is executed whenever a NAS reboot is detected. It is expected to

clear the details of all sessions on that NAS from the SQL database. Special formatting
characters may be used (the %{attribute} ones are probably the most useful). %0 is
replaced by the NAS identifier. If ClearNasQuery is defined as an empty string, then the
query will not be executed. SQL bind variables are supported.
It defaults to:
delete from RADONLINE where NASIDENTIFIER=%0
5.11.8 CountQuery

This SQL statement is executed whenever a Simultaneous-Use check item or MaxSessions must be checked during an Access-Request. It is expected to find and return
details of all the user sessions currently in the Session Database for the given UserName. For each entry, it is expected to return the NAS-Identifier, NAS-Port and AcctSession-Id, IP Address and optionally a user name (in that order) of each session currently in the Session Database. The returned rows are counted, and if there are apparently too many sessions, SessionDatabase SQL will query each NAS and port to
confirm if the user is still on line at that port with that session ID. If a user name is present as the fifth field returned by the query, that is the user name that will be used to confirm the user is still on line. If CountQuery is defined as an empty string, then the query
will not be executed, and the current session count will be fixed at 0.
%0 is formatted as defined in section AddQuery on page 56. %1 replaced by the
AuthBys DefaultSimultaneousUse, Simultaneous-Use check item or Handlers MaxSessions value, depending on the context. SQL bind variables are supported.
It defaults to:
select NASIDENTIFIER, NASPORT, ACCTSESSIONID, FRAMEDIPADDRESS
from RADONLINE where USERNAME=%0

Hint: You can make SessionDatabase SQL count sessions in different ways depending
on how you want to restrict your sessions. For example, you could limit the number of
users permitted to log in to a particular realm with something like:

Radiator RADIUS Server

57 of 397

Configuration

CountQuery select NASIDENTIFIER, NASPORT, ACCTSESSIONID, \

FRAMEDIPADDRESS from\
RADONLINE where USERNAME like %%@%R

If your Session Database table included the Called-Station-Id for each session, you
could limit the maximum number of users with the same Called-Station-ID with something like:
CountQuery select NASIDENTIFIER, NASPORT, ACCTSESSIONID, \
FRAMEDIPADDRESS from RADONLINE \
where CALLEDSTATIONID =%{Called-Station-Id}
5.11.9 ReplaceQuery

If this optional parameter is defined, it will be used to replace a record in the session
database. If it is not defined, DeleteQuery and AddQuery will be used instead. By
default, ReplaceQuery is not defined. %1 by the NAS IP address, %2 by the NAS-Port,
%3 by the SQL quoted Acct-Session-Id.
%0 is formatted as defined in section AddQuery on page 56. SQL bind variables are
supported.
This option is provided because some databases (such as MySQL) offer a more efficient
way to insert or replace queries. Special formatting characters may be used.
5.11.10 CountNasSessionsQuery

This SQL statement is executed whenever Radiator needs the number of sessions currently logged on to a particular NAS. This is only required if HandleAscendAccessEventRequest is defined and an Ascend-Access-Event-Request is received. %1 is replaced
by the NAS IP address. SQL bind variables are supported.
It defaults to:
select ACCTSESSIONID from RADONLINE where NASIDENTIFIER=%0
5.11.11 ClearNasSessionQuery

This SQL statement is executed whenever Radiator needs the number of sessions currently logged on to a particular NAS. This is only required if HandleAscendAccessEventRequest is defined and an Ascend-Access-Event-Request is received and Radiator
finds that there is a session in the session database that is not recorded in the NAS. %1 is
replaced by the NAS IP address and %2 is replaced by the session ID. SQL bind variables are supported.
It defaults to:
delete from RADONLINE where NASIDENTIFIER=%0 \
and ACCTSESSIONID = %1

5.12 <SessionDatabase DBM>

This optional clause specifies an external DBM file Session Database for radiusd. The
Session Database is used to hold information about current sessions as part of Simultaneous-Use limit checking. It can also be used by external utilities for querying the online user population If you dont specify a SessionDatabase clause, the database will be

58 of 397

Radiator RADIUS Server

Configuration

kept internal to radiusd, which is faster, but does not make the data available to other
processes.
Caution: Because Radiator does not lock the DBM file, a single SessionDatabase DBM
file should never be used by more than one instance of Radiator. When attempting to
enforce Simultaneous-Use limits across multiple Radiator servers, always use SessionDatabase SQL.
Radiator will choose the best format of DBM file available to you, depending on
which DBM modules are installed on your machine. (Hint: You can force it to choose a
particular format by using the DBType parameter)
Hint: You can use radwho.cgi to view the contents of your Session Database. See
Section 12.0 on page 332.
SessionDatabase DBM understands the following parameters:
5.12.1 Identifier

This optional parameter assigns a name to the Session Database, so it can be referred to
in other parts of the configuration file.
# Here is a useful name for this Session Database
Identifier SDB1
5.12.2 Filename

Specifies the filename that holds the Session Database. Defaults to %D/online, The
actual file names will depend on which DBM format Perl selects for you, but will usually be something like online.dir and online.pag in DbDir. The file name can
include special formatting characters as described in Section 5.2 on page 20.
# Session database in called online2.* in DbDir
Filename %D/online
5.12.3 DBType

By default, Radiator and Perl will choose the best format of DBM file available to
you, depending on which DBM modules are installed on your machine. You can override this choice by specifying DBType as the name of one of the DBM formats supported on your platform. The typical choices are:

AnyDBM_File
NDBM_File
DB_File
GDBM_File
SDBM_File
ODBM_File

but not may be available on your platform. The default is AnyDBM_File, which
chooses the best available implementation.

Radiator RADIUS Server

59 of 397

Configuration

# Force it to use DB_File

DBType DB_File

Hint: If you alter this and your are using the radwho.cgi script, you will probably have
to alter the $dbtype variable at the top of that script so that it uses a compatible DBM
type.
5.13 <SessionDatabase NULL>
This type of session database stores no session details, and always permits multiple
logins. It is useful in environments with large user populations, and where no simultaneous-use prevention is required. <SessionDatabase NULL> uses much less memory and
fewer CPU cycles than <SessionDatabase INTERNAL> (which is the default session
database). The code for <SessionDatabase NULL> was contributed by Daniel Senie
([email protected]).
<SessionDatabase NULL> understands the following parameters:
5.13.1 Identifier

This optional parameter assigns a name to the Session Database, so it can be referred to
in other parts of the configuration file.
# Here is a useful name for this Session Database
Identifier SDB1

5.14 <Log FILE>

This optional clause creates a FILE logger, which will log all messages with a priority
level of Trace or more to a file. The logging is in addition to any logging to the file
defined by LogFile (see Section 5.7.12 on page 31). The log file will be opened, written
and closed for each message, which means you can rotate it at any time.
Hint: The logger becomes active when it is encountered in the configuration file. It will
log parse errors from later in the configuration file and subsequent run-time events.
Parse errors from earlier in the configuration file will not be logged through this clause.
Hint: LogStdout in the config file is basically the same as
<Log FILE>
# Log debugging information to STDOUT
Trace 4
Filename -
</Log>

however, you could also use LogMicroseconds or LogFormat to get your own format of
logging to stdout.
Hint: LogFile filename in the config file is basically the same as
<Log FILE>
#Trace 0
Filename filename
</Log>

60 of 397

Radiator RADIUS Server

Configuration

Hint: You can place a <Log xxx> clause inside any clause in the configuration file. This
will cause messages originating from within that clauses code to be logged with the logger prior to being logged with any global loggers. This can be handy for debugging or
tracing only certain Realms or AuthBy clauses:
<Handler>
# This will log messages from within the Handler
<Log FILE>
Trace 4
Filename xxxx
...
</Log>
</Handler>

Log FILE understands the following parameters:

5.14.1 Filename

The name of the file that will be logged to. The file name can include special path name
characters as defined in Special characters in file names and other parameters on
page 8. The default is %L/logfile, i.e. a file named logfile in LogDir. Special character
%0 is replaced by the priority integer and %1 by the log message.
# Log file goes in /var/log, with year number
Filename /var/log/%Y-radius.log

If the Filename parameter starts with a vertical bar character (|) then the rest of the
filename is assumed to be a program to which the output is to be piped. Otherwise the
output will be appended to the named file:
# Pipe to my-log-prog
Filename |/usr/local/bin/my-log-prog
5.14.2 LogMicroseconds

This optional parameter makes Log FILE log the current microseconds at the end of the
time string.
5.14.3 LogFormat

This optional parameter permits you to customize the log string when LogFormatHook
is not defined. Any special formatting character is permitted. %0 is replaced with the
message severity as an integer, %1 with the severity as a string, and %2 with the log
message. Default is similar to:
LogFormat %l: %1: %2
5.14.4 LogFormatHook

Specifies an optional Perl hook that will run for each log message when defined. The
hook must return the formatted log message. By default no hook is defined and LogFormat or the default format is used. The hook parameters are the message severity as an
integer, the log message and the reference to the current request.
5.14.5 Trace

Defines the priority level of messages to be traced. See Section 5.7.3 on page 28.

Radiator RADIUS Server

61 of 397

Configuration

Note: Packet dumps will only appear if the global Trace level is set to 4 or more.
5.14.6 IgnorePacketTrace

Exclude this logger from PacketTrace debugging.

5.14.7 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It
can also be referred to by Log xxx in any other clause.
<AuthBy whatever>
# With an Identifier, can refer to this logger from
# other clauses
<Log FILE>
Identifier mylogger
Filename xxx
</Log>
....
</AuthBy>
<AuthBy whatever>
# This AuthBy will log to the Log FILE above
Log mylogger
.....
</AuthBy>

5.15 <Log SYSLOG>

This optional clause creates a SYSLOG logger, which will log all messages with a priority level of Trace or more to the syslog system. Log SYSLOG requires Sys::Syslog.
The logging is in addition to any logging to the file defined by LogFile (see
Section 5.7.12 on page 31).
Messages are logged to syslog with priority levels that depend on the severity of the
message. 5 priority levels have been defined, and they are logged to the equivalent syslog priority. See the Trace parameter for a description of the priority levels supported.
You must also ensure that your hosts syslog is configured to do something with err,
warning, notice, info and debug priority messages from the Syslog facility you
specify, otherwise you wont see any messages. See /etc/syslog.conf, or it moral equivalent on your system.
Hint: The logger becomes active when it is encountered in the configuration file. It will
log parse errors from later in the configuration file and subsequent run-time events.
Parse errors from earlier in the configuration file will not be logged through this clause.
Hint: You can place a <Log xxx> clause inside any clause in the configuration file. This
will cause messages originating from within that clauses code to be logged with the logger prior to being logged with any global loggers. This can be handy for debugging or
tracing only certain Realms or AuthBy clauses:
<Handler>
# This will log messages from within the Handler
<Log SYSLOG>

62 of 397

Radiator RADIUS Server

Configuration

#Trace 2
...
</Log>
</Handler>

Log SYSLOG understands the following parameters:

5.15.1 Facility

The name of the syslog facility that will be logged to. The default is user.
# Log to the syslog facility called radius
Facility radius
5.15.2 Trace

Defines the priority level of messages to be traced. See Section 5.7.3 on page 28.
Note: Packet dumps will only appear if the global Trace level is set to 4 or more.
5.15.3 IgnorePacketTrace

Exclude this logger from PacketTrace debugging.

5.15.4 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It
can also be referred to by Log xxx in any other clause. See Section 5.14.7 on page 62
for an example.
5.15.5 LogSock

This optional parameter specifies what type of socket to use to connect to the syslog
server. Allowable values are native, eventlog, unix, inet, tcp, udp, stream, pipe, console.
The option inet means to try tcp first, then udp. The default is to use the Sys::Syslog
default of native, tcp, udp, unix, pipe, stream, console.
Caution: due to limitations in the Sys::Syslog perl module, if you have multiple AuthLog SYSLOG or Log SYSLOG clauses and if any one has LogSock defined, they must
all have LogSock defined.
5.15.6 LogHost

When LogSock is set to tcp or udp or inet, this optional parameter specifies the name or
address of the syslog host. Defaults to the local host. Special characters are supported.
Technical Note: The LogHost parameter is passed directly to Perls Sys::Syslog module
which will likely do a DNS query for each logged message. This can cause performance
problems and high number of DNS requests with verbose log levels. It is recommended
to log to local host and let the local syslog to do remote logging.
# Log to a remote host via syslog over udp:
LogSock udp
LogHost your.syslog.host.com

Radiator RADIUS Server

63 of 397

Configuration

5.15.7 LogOpt

This optional parameter allows control over the syslog options passed to Sys::Syslog::openlog. LogOpt is a comma separated list of words from the set:

cons
ndelay
nofatal
nowait
perror
pid

as described in the Perl Sys::Syslog documentation.

Defaults to pid. Special characters are supported.
LogOpt pid,perror
5.15.8 LogIdent

This optional parameter specifies an alternative ident name to be used for logging.
Defaults to the executable name used to run radiusd. Special characters are supported.
5.15.9 MaxMessageLength

This optional parameter specifies a maximum message length (in characters) for each
message to be logged. If specified, each log message is truncated to the specified number of characters prior to logging. Defaults to 0, which means no truncation.
5.16 <Log SQL>
This optional clause creates an SQL logger, which will log all messages with a priority
level of Trace or more to an SQL database. The logging is in addition to any logging to
the file defined by LogFile (see Section 5.7.12 on page 31).
The messages will be inserted with the following SQL statement:
insert into tablename (TIME_STAMP, PRIORITY, MESSAGE)
values (time, priority, message)

You must create a table to insert into before you can use this clause. There are example
logging tables created in the example SQL files in the goodies directory of the Radiator
distribution.
Hint: The logger becomes active when it is encountered in the configuration file. It will
log parse errors from later in the configuration file and subsequent run-time events.
Parse errors from earlier in the configuration file will not be logged through this clause.
Hint: You can place a <Log xxx> clause inside any clause in the configuration file. This
will cause messages originating from within that clauses code to be logged with the logger prior to being logged with any global loggers. This can be handy for debugging or
tracing only certain Realms or AuthBy clauses:

64 of 397

Radiator RADIUS Server

Configuration

<Handler>
# This will log messages from within the Handler
<Log SQL>
#Trace 2
DBSource dbi:.......
...
</Log>
</Handler>

Log SQL understands the following parameters:

5.16.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to as for <AuthBy SQL>. They specify the DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername yoursqlusername
DBAuth
yoursqlpassword

Note: It is good practice to use a different DBSource than for other SQL clauses in your
configuration file. This allows SQL errors on DBSource to be logged.
5.16.2 Table

Defines the name of the SQL table to insert into. Defaults to RADLOG. Special formatting characters are permitted.
# Insert into a table called mylog
Table mylog

Hint: You could have Log SQL log to a different table every month with something
like:
Table RADLOG%Y%m
5.16.3 Trace

Defines the priority level of messages to be traced. See Section 5.7.3 on page 28.
Special Note: Packet dumps will only appear if the global Trace level is set to 4 or more.
5.16.4 IgnorePacketTrace

Exclude this logger from PacketTrace debugging.

5.16.5 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It
can also be referred to by Log xxx in any other clause. See Section 5.14.7 on page 62
for an example.
5.16.6 LogQuery

This optional parameter allows you to control the SQL query that is used to insert log
messages into the database. Special formatting characters are permitted. %0 is replaced

Radiator RADIUS Server

65 of 397

Configuration

with the message severity as an integer, %1 with the severity as a string, and %2 with
the log message.
The default is:
insert into %3 (TIME_STAMP, PRIORITY, MESSAGE)
values (%t, %0, %2)

Where %t is translated as a special character to the current time, %0 is converted to the

message priority (in integer in the range 0 to 4 inclusive), %1 is converted to an ASCII
string describing the message priority, %2 is converted to the log message, quoted and
escaped, and %3 is converted to the table name defined by the Table parameter above.
%4 is replaced by the SQL quoted User-Name (or NULL if there is no current AccessRequest).
Hint: You might want to use either %1 or %2 in your query, but rarely both.
5.16.7 LogQueryParam

This optional parameter specifies a bind variable to be used with LogQuery. Special formatting characters %0 - %4 are not quoted when used with LogQueryParam. See SQL
Bind Variables on page 25 for information about how to use bind variables.
Note: Many databases do not allow the table name to be defined as a bind variable. If
you need %3 and want to use LogQueryParam, use something like this:
LogQuery insert into %3 (TIME_STAMP, PRIORITY_MESSAGE) values
(?, ?, ?)
LogQueryParam %t
LogQueryParam %0
LogQueryParam %2
5.16.8 ConnectionHook, ConnectionAttemptFailedHook and NoConnectionsHook

These hooks are called during SQL connection establishment and possible connection
failures. They have the same meaning as described in <AuthBy SQL> on page 111.
5.16.9 MaxMessageLength

This optional parameter specifies a maximum message length (in characters) for each
message to be logged. If specified, each log message is truncated to the specified number of characters prior to logging. Defaults to 0, which means no truncation.
Truncation is done prior to SQL quoting of escapes. MaxMessageLength is useful for
some types of SQL server that complain if given a string longer than the column it is
going in to.
5.17 <Log EMERALD>
This logging module is based on Log SQL and is used to log messages to the Emerald
RadLogs table. Emerald is a third-party commercial ISP billing package.
LogEMERALD understands the same parameters as Log SQL.

66 of 397

Radiator RADIUS Server

Configuration

5.18 <SNMPAgent>
This optional clause enables an SNMP Agent that will allow you to fetch statistics from
Radiator using SNMP version 1 or 2c. Radiator supports all the SNMP objects
described in the draft IETF standard defined in draft-ietf-radius-servmib-04.txt, as well
as:

RFC2619 - RADIUS Authentication Server MIB

RFC2621 - RADIUS Accounting Server MIB
RFC4669 - RADIUS Authentication Server MIB for IPv6
RFC4671 - RADIUS Accounting Server MIB for IPv6

Copies of the standards documents are included in the doc directory of the Radiator distribution.
SNMPAgent requires SNMP_Session-0.92.tar.gz or later from
http://code.google.com/p/snmp-session/downloads/list
to be installed first.
If you do not include this clause in your Radiator configuration file, it will not respond
to any SNMP requests.
# Example, showing how to enable SNMP handling
<SNMPAgent>
ROCommunity mysnmpsecret
</SNMPAgent>

If you enable SNMPAgent, you will be able to collect server statistics using a 3rd party
SNMP package such as MRTG, Open View etc. You can also use SNMP to reset the
server.
You can test that its working properly with a command on Unix like this one, that gets
the value of radiusServIdent from the old draft MIB:
$ snmpget -c public -v 1 localhost .iso.org.dod.internet.3.79.1.1.1.1
SNMPv2-SMI::experimental.79.1.1.1.1 = STRING: "Radiator 3.6 on
zulu"

And this gets the uptime from the new Authentication server MIB:
$ snmpget -c public -v 1 localhost .1.3.6.1.2.1.67.1.1.1.1.2
SNMPv2-SMI::mib-2.67.1.1.1.1.2 = Timeticks: (200) 0:00:02.00

SNMPAgent understands the following parameters:

5.18.1 Port

This optional parameter specifies the UDP port number that the SNMP Agent is to listen
on. It defaults to 161. There should only rarely be any reason to change it. The argument
may be either a numeric port number or an alphanumeric service name as specified in /
etc/services (or its moral equivalent on your system). Port may contain special

Radiator RADIUS Server

67 of 397

Configuration

formatting characters. A typical use of special formatting characters is with GlobalVar

and command line arguments.
# Use a non-standard port
Port 9991
5.18.2 BindAddress

This optional parameter specifies a single host address to listen for SNMP requests on.
It is only useful if you are running Radiator on a multi-homed host (i.e. a host that has
more than one network address). Defaults to the global value of BindAddress (usually
0.0.0.0 i.e. listen on all networks connected to the host, but see Section 5.7.8 on
page 30). BindAddress can include special formatting characters. Requires SNMP_Session version 0.92 or greater.
# Only listen on one network, not all the ones connected
BindAddress 203.63.154.0
5.18.3 Community (deprecated)

SNMP V1 provides a weak method of authenticating SNMP requests, using the community name. This optional parameter allows you to specify the SNMP V1 community
name that will be honoured by SNMPAgent. Any SNMP request that does not include
the correct community name will be ignored. Defaults to nothing. We strongly recommend that you choose a community name and keep it secret.
Community is now deprecated, but is still honoured for backwards compatibility. New
implementations should use ROCommunity and /or RWCommunity.
# Use a secret community.
Community mysnmpsecret
5.18.4 ROCommunity

SNMP V1 provides a weak method of authenticating SNMP requests, using the community name. This optional parameter allows you to specify the SNMP V1 community
name that will be honoured by SNMPAgent for read-only access. Defaults to nothing,
you have to define one by yourself.
We strongly recommend that you choose a community name and keep it secret.
# Use a secret community.
ROCommunity mysnmprosecret
5.18.5 RWCommunity

This optional parameter allows you to specify the SNMP V1 community name that will
be used by SNMPAgent to authenticate read-write access. Knowing this secret you are
able to reset Radiator via SNMP. Defaults to nothing. If you dont need resetting via
SNMP use only ROCommunity.
# only necessary for resetting via SNMP
RWCommunity extremelysecure
5.18.6 Managers

This optional parameter specifies a list of SNMP managers that have access to
SNMPAgent. The value is a list of host names or addresses, separated by white space or

68 of 397

Radiator RADIUS Server

Configuration

comma. You can have any number of Managers lines. Defaults to nothing with all hosts
allowed.
# allowed SNMP managers
Managers
foo.bar.edu 192.168.1.11, noc.rz.uni-ulm.de
Managers
baz.bar.com,10.1.1.254
5.18.7 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It is
not used by the standard Radiator code.
5.18.8 SNMPVersion

This optional parameter allows you to specify the SNMP version the agent uses. Currently supported versions are 1 and 2c. Defaults to 1.
5.19 <Realm realmname>
Technical note: we recommend using Handler clauses for all new configurations. Handlers provide more flexibility for defining how to match requests and make future configuration changes easier to manage.
Technical note: using both Realms and Handlers in the same configuration is allowed
but may make the Realm/Handler selection hard to understand. See <Handler attribute=value,attribute=value, ....> on page 70 for the details.
A Realm can be easily converted to a Handler. For example: <Realm example.com>
becomes <Handler Realm=example.com> and <Realm /\.example\.com$/> becomes
<Handler Realm=/\.example\.com$/>. The closing </Realm> must also be changed to
</Handler>
The beginning of a Realm clause. The clause continues until </Realm> is seen on a
line. A Realm clause specifies a single RADIUS realm that this server will service. A
realm is the part of the users login name that follows the @ sign. For example if a user
logs in as [email protected], then open.com.au is the realm. All requests from
all users with the realm named in the <Realm realmname> line will be handled in
the way specified by the rest of the Realm clause. You can configure one or more realms
into your server, possibly with a different AuthBy authentication method for each.
The realmname can be either an exact realm name or it can be a Perl regular expression
(regexp) including the opening and closing slashes that will match zero or more realms.
You can also use the x and i modifiers. If you use a regexp, you should be very careful to check that you regexp will match only those realms you mean it to. Consult your
Perl reference manual for more information on writing Perl regexps.
If you omit the realm name from the <Realm> line, the clause will match requests with
a NULL realm (i.e. where the user did not enter a realm-qualified user name, such as a
bare fred or alice).
When Radiator looks for a <Realm realmname> clause to match an incoming
request, it first looks for an exact match with the Realm name. If no match is found, it

Radiator RADIUS Server

69 of 397

Configuration

will try to do a regexp match against Realm names that look like regexps (i.e. have
slashes at each end). If still no match, it looks for a Realm called DEFAULT. If still no
match, it logs an error and ignores (i.e. does not reply to) the request (but see
Section 5.20 on page 70 for exceptions to this rule).
The special DEFAULT realm (if it is defined) will be used to handle requests from users
in realms for which there is no other matching Realm clause.
# Handle requests with no realm with UNIX,
# from [email protected] with SQL
# from any realm ending in .au by forwarding
# and from any other realm with DBFILE
<Realm>
<AuthBy UNIX>
.....
</AuthBy>
</Realm>
<Realm open.com.au>
<AuthBy SQL>
......
</AuthBy>
</Realm>
# Any realm ending in .au
<Realm /.*\.au/>
<AuthBy RADIUS>
.....
</AuthBy>
</Realm>
# Any realm ending in .au, .AU, .Au, .aU (ie its case
# insensitive)
<Realm /.*\.au/i>
<AuthBy RADIUS>
.....
</AuthBy>
</Realm>
# Any other realm
<Realm DEFAULT>
<AuthBy DBFILE>
.......
</AuthBy>
</Realm>

A <Realm> is a special type of <Handler>, and you can use all the same parameters that
are described in Handler (see Section 5.20 on page 70). However, you can only use
realms for selecting the requests. This will not work: <Realm example.com, ClientIdentifier=mynas>.
5.20 <Handler attribute=value,attribute=value, ....>
The beginning of a Handler clause. The clause continues until </Handler> is seen on
a line. A Handler clause causes all requests with a specific set of attributes to be handled
in the same way. You can configure one or more Handlers into your server, possibly
with a different AuthBy authentication method(s) for each.

70 of 397

Radiator RADIUS Server

Configuration

<Handler> differs from <Realm> because it can group together requests based on the
value of any attribute(s) in the request, not just the users realm. That makes Handlers
much more powerful, but they are not required as often: the most common situation is
that you will need to distinguish between authentication methods based on the users
realm. You may wish to use Handlers instead of Realms if you need to choose authentication methods based on, for example, Called-Station-Id, or Request-Type or some
other attribute in incoming RADIUS requests.
In <Handler checklist>, the checklist expression is a list of request attributes that must
all match before this Handler will be used to handle the request. The format is exactly
the same as a list of check items in a user file: a list of attribute=value pairs, separated
by commas. See Section 13.1 on page 334 for a description of all the check items you
can use.
If you omit the expression name from the <Handler> line, the clause will match all
requests
When Radiator looks for a <Handler> clause to match an incoming request, it will
look at each <Handler> clause in the order in which they appear in your configuration
file. It will continue looking until a <Handler> is found where every check item in the
expression matches the request. If any check item does not match, it will continue onto
the next Handler until all the Handlers are exhausted. If no Handlers match, AccessRequests will be rejected, and Accounting-Requests will be accepted.
Technical note: Radiator uses the following algorithm to find a Realm or Handler to
handle each request:

Look for a Realm with an exact match on the realm name

If still no exact match, look for a matching regular expression Realm
If still no match, look for a <Realm DEFAULT>
If still no match, look at each Handler in the order they appear in the configuration
file until one where all the check items match the request.

If still no match, ignore (i.e. do not reply to) the request.

Mixing Handlers and Realms in the same configuration file is permissible but may lead
to hard to understand handler selections, and difficult to understand behavior.
In the (contrived) example below, all requests with Called-Station-Id of 662543 and
Service-Type of Framed-User will be authenticated with SQL. All requests with CalledStation-Id of 678771 and a realm of open.com.au will be handled with a DBM, and all
other requests will forwarded to another RADIUS server. Much more complicated
authentication schemes are possible.
<Handler Called-Station-Id=662543,Service-Type=Framed-User>
<AuthBy SQL>
......
</AuthBy>
</Handler>
<Handler Called-Station-Id=678771,Realm=open.com.au>
<AuthBy DBM>

Radiator RADIUS Server

71 of 397

Configuration

.....
</AuthBy>
</Handler>
# Handles anything that was not handled above:
<Handler>
<AuthBy RADIUS>
.......
</AuthBy>
</Handler>
5.20.1 RewriteUsername

This parameter enables you to alter the user name in authentication and accounting
requests when they are handled by this Realm or Handler. See Section 14.0 on page 353.
You can have any number of RewriteUsername parameters in a Realm or Handler. The
rewrites will be applied to the user name in the same order that they appear in the configuration file. The rewrites are applied after any global or per-Client rewrites. At Trace
level 4, you can see the result of each separate rewrite for debugging purposes.
RewriteUsername will be ignored if there is a RewriteFunction defined for this Realm
or Handler.
# Strip the realm from all requests, because our
# database only has user names (no realm)
RewriteUsername
s/^([^@]+).*/$1/

# Translate all uppercase to lowercase

RewriteUsername
tr/A-Z/a-z/
5.20.2 RewriteFunction

This optional parameter allows you to define you own special Perl function to rewrite
user names. You can define an arbitrarily complex Perl function that might call external
programs, search in databases or whatever. The username is changed to whatever is
returned by this function.
If you define a RewriteFunction for a Realm or Handler, it will be used in preference to
any RewriteUsername. RewriteUsername will be ignored for that Realm or Handler.
# Strip out NULs, trailing realms, translate to
# lower case and remove single quotes
RewriteFunction sub { my($a) = shift; $a =~ s/[\000]//g; $a =~
s/^([^@]+).*/$1/; $a =~ tr/[A-Z]/[a-z]/; $a =~ s///g; $a; }
5.20.3 MaxSessions

This parameter allows you to apply a simple limit to the number of simultaneous sessions a user in this Realm is permitted to have. It is most common to limit users to either
one session at a time or unlimited, but Radiator also supports other numbers.
MaxSessions works by looking at each accounting request for a realm when it arrives.
whenever a Start is seen for a user, the count of their number if current sessions is incremented, and whenever a Stop is seen, it is decremented. When an access request is
received, the number of sessions current for that user is compared to MaxSessions. If

72 of 397

Radiator RADIUS Server

Configuration

the user already has MaxSessions sessions or more, Radiator replies with an access
denial. By setting MaxSessions to 0, you can temporarily deny access to all users in the
realm.
MaxSessions applies a hard limit that cant be overridden by DefaultSimultaneousUse
parameter (see Section 5.21.16 on page 87) or by per-user Simultaneous-Use check
items. For many applications, you may wish to consider using DefaultSimultaneousUse
instead of MaxSessions. You can control the maximum number of sessions on a per-user
basis with the Simultaneous-Use check item (see Section 13.1.14 on page 342).
The session count for each user is stored entirely within Radiator (unless you specify a
SessionDatabase clause). This means that if you restart or reinitialize Radiator, it will
lose count of the number of current sessions for each user. Radiator can use SNMP to
confirm whether a user is already logged in or not (see Section 5.8.6 on page 43).
You should note that if Radiator fails to receive an accounting Stop request, it might
result in incorrectly thinking the user is not permitted to log in when in fact they are.
You can correct this by restarting Radiator, or by sending an artificial accounting stop
for the user using the radpwtst utility (see Section 8.0 on page 316) or by configuring
Radiator to query the NAS directly (see Section 5.8.6 on page 43).
# Limit all users in this realm to max of 1 session
MaxSessions 1

Hint: You can set the maximum number of simultaneous sessions for individual users
with the Simultaneous-Use check item. In this case, the smaller of MaxSessions and the
users Simultaneous-Use will apply.
5.20.4 AcctLogFileName

The names of the files used to log Accounting-Request messages in the standard radius
accounting log format. All Accounting-Request messages will be logged to the files,
regardless of their Acct-Status-Type. The log file format is described in Section 15.5 on
page 360. If no AcctLogFileName is defined, accounting messages will not be logged
for this realm. The default is no logging. The file name can include special formatting
characters as described in Section 5.2 on page 20, which means that using the %C, %c
and %R specifiers, you can maintain separate accounting log files for each Realm or
Client or a combination. The AcctLogFileName files are always opened written and
closed for each message, so you can safely rotate them at any time.
If the AuthBy module you select does no special accounting logging, you may want to
enable this parameter for the Realm. Note that logging to AcctLogFileName is in addition to any recording that a specific AuthBy module might do (such as, say, AuthBy
SQL). The username that is recorded in the log file is the rewritten user name when
RewriteUsername is enabled.
You can specify any number of AcctLogFileName parameters. Each one will result in a
separate accounting log file.

Radiator RADIUS Server

73 of 397

Configuration

If the file name starts with a vertical bar character (|) then the rest of the filename is
assumed to be a program to which the output is to be piped. Otherwise the output will be
appended to the named file:
# Pipe to my-log-prog
AcctLogFileName |/usr/local/bin/my-log-prog

Hint: You can change the logging format with AcctLogFileFormat

# Log all accounting to a single log file in LogDir
AcctLogFileName %L/details
5.20.5 AcctLogFileFormat

This optional parameter is used to alter the format of the accounting log file from the
standard radius format when AcctLogFileFormatHook is not defined. AcctLogFileFormat is a string containing special formatting characters. It specifies the format for each
line to be printed to the accounting log file. A newline will be automatically appended.
It is most useful if you use the %{attribute} style of formatting characters (to print the
value of the attributes in the current packet).
AcctLogFileFormat %{Timestamp} %{Acct-Session-Id}\
%{User-Name}
5.20.6 AcctLogFileFormatHook

Specifies an optional Perl hook that will is used to alter the format of the accounting log
file from the standard radius format when defined. The hook must return the formatted
accounting record. A newline will be automatically appended. By default no hook is
defined and AcctLogFileFormat or the default format are used. The hook parameter is
the reference to the current request.
5.20.7 WtmpFileName

The name of a Unix SVR4 wtmp format file to log Accounting-Request messages. All
Accounting-Request messages will be logged. If WtmpFileName is not defined, no
messages will be logged in this format. The default is no logging. The file name can
include special formatting characters as described in Section 4.2 on page 4, which
means that using the %C, %c and %R specifiers, you can maintain separate accounting
log files for each Realm or Client or a combination. The WtmpFileName file is always
opened written and closed for each message, so you can safely rotate it at any time. Start
messages are logged as USER_PROCESS (7), all other messages are logged as DEAD_PROCESS (8).
You may wish to use your standard Unix administration tools (such as last(1)) to process information in the wtmp file.
Hint: RedHat Linux 6.1 and later uses a modified format for wtmp files, compared with
earlier versions. In order to use RedHat tools like last on a wtmp file produced by
Radiator, you will need to use the -o flag (which specifies lib5c format).
5.20.8 PasswordLogFileName

The name of file to log all authentication attempts to. The default is no logging. The file
name can include special formatting characters as described in Section 4.2 on page 4,

74 of 397

Radiator RADIUS Server

Configuration

which means that using the %C, %c and %R specifiers, you can maintain separate password log files for each Realm or Client or a combination.
Each login attempt that generates a password check will be logged to the file, one
attempt per line. The file format is described in Section 15.5 on page 360.
# Help desk want to see all password attempts
PasswordLogFileName %L/password.log

If the file name starts with a vertical bar character (|) then the rest of the filename is
assumed to be a program to which the output is to be piped. Otherwise the output will be
appended to the named file:
# Pipe to my-log-prog
PasswordLogFileName |/usr/local/bin/my-log-prog
5.20.9 ExcludeFromPasswordLog

For security reasons, you can exclude certain users from the passwords logged to PasswordLogFileName. The value is a white space separated list of user names.
# Dont log password from our sysadmin or root
ExcludeFromPasswordLog root admin ceo nocboss
5.20.10 ExcludeRegexFromPasswordLog

Similar to ExcludeFromPasswordLog, but the value is a Perl regular expression

# Dont log password from anyone that begins with root
ExcludeRegexFromPasswordLog ^root
5.20.11 AccountingHandled

Forces Radiator to acknowledge Accounting requests, even if the AuthBy modules for
the Realm would have normally ignored the request. This is useful if you dont really
want to record Accounting requests, but your NAS keeps retransmitting unless it gets an
acknowledgment.
Technical Note: All backend processing, such as SQL queries, is done first, before the
reply is sent back to the NAS.
# My AuthBy SQL ignores accounting
AccountingHandled
5.20.12 PreProcessingHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PreProcessingHook is called for each request before per-Realm username rewriting, before accounting log files are written, and before any PreAuthHooks.
A reference to the current request is passed as the first argument, and a reference to the
reply packet currently being constructed is passed as the second argument
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.

Radiator RADIUS Server

75 of 397

Configuration

PreProcessingHook Can be an arbitrarily complicated Perl function, that might run

external processes, consult databases, change the contents of the current request or
many other things.
# Fake a new attribute into the request, so its logged in the
# accounting log file
PreProcessingHook sub { ${$_[0]}->add_attr(My-Realm, \
some.realm.com);}
5.20.13 PostProcessingHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostProcessingHook is called for each request after all authentication
methods have been called and just before a reply is sent back to the requesting NAS. A
reference to the current request is passed as the first argument, and a reference to the
reply packet currently being constructed is passed as the second argument. If the processing results in no reply (for example if the request is proxied) then PostProcessingHook is not called.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
PostProcessingHook can be an arbitrarily complicated Perl function, that might run
external processes, consult databases, change the contents of the current reply or many
other things.
# Fake a new attribute into the reply
PostProcessingHook sub { ${$_[1]}->add_attr(Class, \
billing rate 1);}
5.20.14 PreAuthHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PreAuthHook is called for each request after per-Realm username
rewriting and before it is passed to any AuthBy clauses. A reference to the current
request is passed as the first argument, and a reference to the reply packet currently
being constructed is passed as the second argument
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
PreAuthHook Can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things.
# Fake a new attribute into the request
PreAuthHook sub { ${$_[0]}->add_attr(test-attr, \
test-value);}

76 of 397

Radiator RADIUS Server

Configuration

5.20.15 PostAuthHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostAuthHook is called for each request after it has been passed to
all the AuthBy clauses. A reference to the current request is passed as the first argument,
and a reference to the reply packet currently being constructed is passed as the second
argument. The third argument is a reference to the result of the authentication
($main::ACCEPT, $main::REJECT etc.). The fourth argument is a reference to a string
variable holding the reason for a reject, or undefined if none is available. To change the
type of reply, you should set the reference to third argument.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
PostAuthHook can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things.
# Add some reply attributes to the reply message
# if it is a REJECT and there is 1 or fewer there already
PostAuthHook sub { ${$_[1]}->add_attr(test-attr, \
test-value) \
if ${$_[2]} == $main::REJECT \
&& ${$_[1]}->attr_count() <= 1; }
5.20.16 AuthByPolicy

Allows you to control how multiple AuthBy clauses in this Handler or Realm will be
used. See section Section 5.27.1 on page 105.
5.20.17 AuthBy

This specifies that the Handler is to be authenticated with an <AuthBy> clause that is
defined elsewhere. The argument must specify the Identifier of the AuthBy clause to
use. The AuthBy clause may be defined anywhere else: at the top level, or in a Realm or
Handler clause. You can have as many AuthBy parameters as you wish. They will be
used in the order that they appear in the configuration file (subject to AuthByPolicy) in
the same way as <AuthBy > clauses.
Hint. This is a convenient way to reuse the same authenticator for many Realms or Handlers.
<AuthBy xxxxxx>
Identifier myidentifier
</AuthBy>
<Realm xxxx>
# This authenticates through the AuthBy defined above
AuthBy myidentifier
</Realm>

Radiator RADIUS Server

77 of 397

Configuration

5.20.18 Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It is
not used by the standard Radiator code.
5.20.19 StripFromRequest

Strips the named attributes from the request before passing it to any authentication modules. The value is a comma separated list of attribute names. StripFromRequest removes
attributes from the request before AddToRequest adds any to the request. There is no
default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.20.20 AddToRequest

Adds attributes to the request before passing it to any authentication modules. Value is a
list of comma separated attribute value pairs all on one line, exactly as for any reply
item. StripFromRequest removes attributes from the request before AddToRequest and
AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.
# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h
5.20.21 AddToRequestIfNotExist

Adds attributes to the request before passing it to any authentication modules. Unlike
AddToRequest, an attribute will only be added if it does not already exist in the request.
Value is a list of comma separated attribute value pairs all on one line, exactly as for any
reply item. StripFromRequest removes attributes from the request before AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.
# Append a Filter-ID and host name if they are not there already
AddToRequestIfNotExist Calling-Station-Id=1,Login-IP-Host=%h
5.20.22 <AuthBy xxxxxx>

This marks the beginning of an AuthBy clause in a Handler or Realm, which defines
how to authenticate and record accounting information for all the users in this Realm or
Handler. The xxxxxx is the name of a specific AuthBy module. See the following sections for how to configure specific AuthBy clauses.
You can have 0 or more AuthBy clauses in a Handler or Realm. The AuthBy clauses
will be executed in order until the AuthByPolicy for the Realm or Handler is satisfied.
<AuthBy xxxx> both defines an authentication method and specifies where it should be
used.
Note that something like
<Realm xxxx>
<AuthBy xxxxxx>
....
</AuthBy>

78 of 397

Radiator RADIUS Server

Configuration

....
</Realm>

Is equivalent to
<AuthBy xxxxxx>
Identifier myidentifier
.....
</AuthBy>
<Realm xxxx>
# This authenticates through the AuthBy defined above
AuthBy myidentifier
....
</Realm>
5.20.23 UsernameCharset

This optional parameter checks that every user name handled by this realm consists only
of the characters in the specified character set. This can be useful to reject access
requests that are due to modem line noise. The value of the parameter is a perl character
set specification. The default is to permit all ASCII characters. See your Perl reference
manual for details about how to construct perl character set specifications.
This example permits only alphanumeric, period, dash and the at sign (note that the special character . is escaped with a backslash):
UsernameCharset a-zA-Z0-9\.-_@

Hint: You can apply a UsernameCharset to every request by using the global UsernameCharset parameter (see Section 5.7.36 on page 37).
5.20.24 RejectHasReason

Normally, when Radiator rejects an Access-Request, it sets the reply message to

Request Denied. This optional parameter forces Radiator to put an additional ReplyMessage into Access-Reject indicating why the rejection occurred. This may be useful
for debugging in some cases, since some NASs will display the Reply-Message during
an interactive login. However it should be noted that some PPP clients do not show the
Reply-Message to the end user.
# Show any rejection reason to the end user (maybe)
RejectHasReason
5.20.25 SessionDatabase

This optional parameter specifies a particular Session Database to use for the enclosing
Realm or Handler. The value of the parameter must be the Identifier of a SessionDatabase clause. The default behaviour is to use the last global SessionDatabase specified in
the configuration file. If no SessionDatabases are specified in the configuration file,
then the default INTERNAL session database will be used.
Hint: The username used to access the session database depends on the setting of SessionDatabaseUseRewrittenName.

Radiator RADIUS Server

79 of 397

Configuration

Hint: This is an advanced use parameter. Only very unusual configurations will need
this parameter to be set. The default behavior will suit most situations.
<Handler xxxxxx>
# If this was not here, we would default to
# myspecialsessiondb2 (the last one in the config
file)
SessionDatabase myspecialsessiondb1
.....
</Handler>
<SessionDatabase SQL>
Identifier myspecialsessiondb1
....
</SessionDatabase>
<SessionDatabase SQL>
Identifier myspecialsessiondb2
....

</SessionDatabase>
5.20.26 SessionDatabaseUseRewrittenName

This optional parameter controls the username used to update and access the session
database for this Handler. If SessionDatabaseUseRewrittenName is true, the rewritten
username (as rewritten by RewriteUsername etc.) is used. Otherwise the original UserName attribute from the request is used. Defaults to false.
5.20.27 AuthLog

This specifies that the Handler is to log all authentications with an <AuthLog> clause
that is defined elsewhere. The argument must specify the Identifier of the AuthLog
clause to use. The AuthLog clause may be defined anywhere else: at the top level, or in
a Realm or Handler clause. You can have as many AuthLog parameters as you wish.
They will be used in the order that they appear in the configuration file in the same way
as <AuthLog xxx > clauses.
Hint. This is a convenient way to reuse the same authentication logger for many Realms
or Handlers.
<AuthLog xxxxxx>
Identifier myidentifier
....
</AuthLog>
<Realm xxxx>
# This logs through the AuthLog defined above
AuthLog myidentifier
</Realm>
5.20.28 <AuthLog xxx>

Indicates that logging of authentication success and failure should be handled in a special way. <AuthLog FILE> and <AuthLog SQL> are currently supported. When authentication is complete, each of the AuthLog clauses defined for the handler will be
executed in order. For each AuthLog, the authentication details will be logged according
to the parameters for that clause. You can have as many <AuthLog xxx> clauses as you
wish, or none at all.

80 of 397

Radiator RADIUS Server

Configuration

<AuthLog xxxx> both defines a logging method and specifies where it should be used.
Note that something like
<Realm xxxx>
<AuthLog xxxxxx>
....
</AuthLog>
....
</Realm>

Is identical to
<AuthLog xxxxxx>
Identifier myidentifier
</AuthLog>
<Realm xxxx>
# This log through the AuthLog defined above
AuthLog myidentifier
</Realm>

5.20.29 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5. This is useful for logging packets that pass through this clause in more detail
than other clauses during testing or debugging. The packet tracing will stay in effect
until it passes through another clause with PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace
5.20.30 LogRejectLevel

Log level for rejected authentication attempts. Defaults to global LogRejectLevel value.
5.20.31 HandleAscendAccessEventRequest

This optional parameter causes Radiator to respond to Ascend-Access-Event-Request

messages. These messages are sent by some types of specially configured Ascend
NASs. They contain a count of the number of sessions the NAS thinks it currently has in
each Class.
When HandleAscendAccessEventRequest is enabled, it causes Radiator to confirm that
its SQL Session Database is up to date. If the session counters dont agree, Radiator will
use snmpwalk to confirm the existence of its sessions, deleting from the SQL Session
Database the ones that dont really exist.
Hint: HandleAscendAccessEventRequest requires that an SQL Session Database is
configured for this Handler or Realm. See SessionDatabase on page 79.
Hint: You must set NasType to Ascend for the SNMP session confirmation to work correctly.
# handle Ascend-Access-Event-Request messages
HandleAscendAccessEventRequest

Radiator RADIUS Server

81 of 397

Configuration

5.20.32 DefaultReply, FramedGroup, StripFromReply,

AllowInReply, AddToReply, AddToReplyIfNotExist, DynamicReply

These optional parameters affect replies to packets that were handled by this Realm or
Handler clause. The parameters have the same meanings as described in <AuthBy
xxxxxx> on page 82. They can be used to make special adjustments to the contents of
reply packets.
5.21 <AuthBy xxxxxx>
This marks the beginning of an AuthBy clause, which defines how to authenticate and
record accounting information. The xxxxxx is the name of a specific AuthBy module.
See the following sections for how to configure specific AuthBy clauses. AuthBy
clauses may be defined at the top level or within a Realm or Handler clause.
Under special circumstances, you can have more than one AuthBy clause for a Realm or
Handler. This will make the Realm (or Handler) try each AuthBy method in turn until
one of them either Accepts or Rejects the request (you can change this with AuthByPolicy, see Section 5.20.16 on page 77). For example, it is useful to have an AuthBy SQL
followed by an AuthBy RADIUS, which will cause all authentication and accounting
requests to be forwarded, and also all accounting requests will be recorded in SQL. This
is good for keeping track of all requests forwarded to, say a global roaming server.
If there are no AuthBy clauses in a Realm or Handler, then Access requests will be
rejected, and Accounting requests will be ignored.
All AuthBy clauses understand the following parameters:
5.21.1 Fork

The parameter forces the authentication module to fork(2) before handling the request.
Fork should only be set if the authentication module or the way you have it configured is
slow i.e. takes more than a fraction of a second to process the request.
If you dont understand what forking is for or how it can improve the performance of
your Radiator server, talk about it with someone who does before using it. Not all
authentication methods will benefit from forking. Fork has no effect on Windows platforms.
Technical Note: In particular, it does not usually make sense to use Fork with AuthBy
SQL, AuthBy FILE, AuthBy LDAP or any of the other common authentication methods
provided with Radiator. Further, some SQL and LDAP client libraries are not robust
across forks. You might want to consider using Fork with AuthBy EXTERNAL or a
custom authentication module if it needs to do significant amounts of IO, or to communicate with a remote system.
# This AuthBy EXTERNAL program is very slow, and does lots of IO
Fork
5.21.2 UseAddressHint

This optional parameter forces Radiator to honour a Framed-IP-Address in an AccessRequest request unless it is overridden by a Framed-IP-Address in the users reply

82 of 397

Radiator RADIUS Server

Configuration

items. If you enable this, then users will get the IP Address they ask for. If there is a
Framed-IP-Address reply item for a user, that will override anything they might request.
# Let users get addresses they ask for
UseAddressHint
5.21.3 DynamicReply

This optional parameter specifies a reply item that will be eligible for run-time variable
substitution. That means that you can use any of the % substitutions in Table 1 on
page 20 in that reply item. You can specify any number of DynamicReply lines, one for
each reply item you want to do replacements on. Any packet-specific replacement values will come from the Access-Accept message being constructed, and not from the
incoming Access-Request. That means that special characters like %n will not be
replaced by the received User-Name, because User-Name is in the request, but not the
reply.
In the following example, substitution is enabled for USR-IP-Input-Filter. When a user
authenticates, the %a in the filter will be replaced by the users IP Address, which makes
the filter an anti-spoof filter.
<AuthBy whatever>
......
UseAddressHint
DynamicReply USR-IP-Input-Filter
</AuthBy>

In the users file:

DEFAULT User-Password = "UNIX"
Framed-IP-Address = 255.255.255.254,
Framed-Routing = None,
Framed-IP-Netmask = 255.255.255.255,
USR-IP-Input-Filter = "1 REJECT src-addr != %a;",
Service-Type = Framed-User

Technical Note: this parameter used to be called Dynamic. That name is still recognized as a synonym for DynamicReply.
5.21.4 DynamicCheck

This optional parameter specifies a check item that will be eligible for run-time variable
substitution prior to authentication. That means that you can use any of the % substitutions in Table 1 on page 20 in that check item. You can specify any number of DynamicCheck lines, one for each check item you want to do replacements on.
In the following example, substitution is enabled for the Group check item. When a user
authenticates, the %{Shiva-VPN-Group} in the check item will be replaced with the
value of the Shiva-VPN-Group attribute in the authentication request. You could use
this mechanism to verify that the user is in the Unix group corresponding to their ShivaVPN-Group.
<AuthBy whatever>
......

Radiator RADIUS Server

83 of 397

Configuration

DynamicCheck Group
</AuthBy>

In the users file:

DEFAULT Group=%{Shiva-VPN-Group}
Framed-IP-Address = 255.255.255.254,
Framed-Routing = None,
Framed-IP-Netmask = 255.255.255.255,
........
5.21.5 Identifier

This allows you to assign a symbolic name to an AuthBy clause and its configuration.
This allows you to refer to it by name in an Auth-Type check item when authenticating
a user.
The most common use of this is to create a System authenticator, typically with an
<AuthBy UNIX> clause. A typical example configuration file that uses this feature
might be:
<Realm DEFAULT>
<AuthBy FILE>
</AuthBy>
</Realm>
<AuthBy UNIX>
Identifier System
</AuthBy>

You can then have something like this in your users file:
DEFAULT Auth-Type = System
Framed-IP-Netmask .....
...........

In this example, all users in all realms will match the DEFAULT user in the users file.
This will in turn check their username and password against a UNIX password file as
configured by the AuthBy UNIX clause in the configuration file. If the password checks
out, they will get the RADIUS attributes specified in the second and subsequent lines of
the DEFAULT user entry in the users file (in this example, Framed-IP-Netmask).
5.21.6 StripFromReply

Strips the named attributes from Access-Accepts before replying to the originating client. The value is a comma separated list of RADIUS attribute names. StripFromReply
removes attributes from the reply before AddToReply adds any to the reply. There is no
default. This is most useful with AuthBy RADIUS to prevent downstream RADIUS
servers sending attributes you dont like back to your NAS.
# Remove dangerous attributes from the reply
StripFromReply Framed-IP-Netmask,Framed-Compression
5.21.7 AllowInReply

This optional parameter is the complement to StripFromReply: it specifies the only

attributes that are permitted in an Access-Accept. It is most useful to limit the attributes
84 of 397

Radiator RADIUS Server

Configuration

that will be passed back to the NAS from a proxy server. That way, you can prevent
downstream customer RADIUS servers from sending back illegal or troublesome attributes to your NAS.
AllowInReply does not prevent other attributes being added locally by DefaultReply,
AddToReply and AddToReplyIfNotExist.
# Only permit a limited set of reply attributes.
AllowInReply Session-Timeout, Framed-IP-Address
5.21.8 AddToReply

Adds attributes reply packets. Value is a list of comma separated attribute value pairs all
on one line, exactly as for any reply item. StripFromReply removes attributes from the
reply before AddToReply adds any to the reply. You can use any of the special % formats in the attribute values. There is no default. AddToReply adds attributes to replies
to all types of request that are handled by this AuthBy.
Although this parameter can be used in any AuthBy method, it is most useful in methods like AuthBy UNIX and AuthBy NT, which dont have a way of specifying per-user
reply items.
# Append some necessary attributes for our pops
AddToReply cisco-avpair="ip:addr_pool=mypool"
5.21.9 AddToReplyIfNotExist

Similar to AddToReply, but only adds an attribute to a reply if and only if it is not
already present in the reply. Therefore it can be used to add, but not override a reply
attribute. Contributed by Vincent Gillet <[email protected]>.
5.21.10 DefaultReply

This is similar to AddToReply (Section 5.21.8 on page 85) except it adds attributes to an
Access-Accept only if there would otherwise be no reply attributes. StripFromReply
will never remove any attributes added by DefaultReply. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. You can use any
of the special % formats in the attribute values. There is no default.
Although this parameter can be used in any AuthBy method, it is most useful in methods like AuthBy UNIX, AuthBy NT and AuthBy SYSTEM, which dont have a way of
specifying per-user reply items. In other AuthBy methods you can also very easily set
up a standard set of reply items for all users, yet you can still override reply items on a
per-user basis.
# If the user had no reply items set some
DefaultReply Service-Type=Framed,Framed-Protocol=PPP
5.21.11 FramedGroup

This optional parameter acts similarly to Framed-Group reply items, but it applies to all
Access-Requests authenticated by this AuthBy clause. If FramedGroup is set and a
matching FramedGroupBaseAddress is set in the Client from where the request came,
then a Framed-IP-Address reply item is automatically calculated by adding the NASPort in the request to the FramedGroupBaseAddress specified by FramedGroup. See
Section 5.8.8 on page 45 for more details.
Radiator RADIUS Server

85 of 397

Configuration

Hint: you can override the value of FramedGroup for a single user by setting a FramedGroup reply item for the user.
# Work out the users IP address from the first
# FramedGroupBaseAddress specified in out client
FramedGroup 0
5.21.12 NoDefault

Normally if Radiator searches for a user in the database and either does not find one, or
finds one but the users check items fail, Radiator will then consult the DEFAULT user
entry. However, if the NoDefault parameter is set, Radiator will never look for a
DEFAULT.
# Save time by never looking for a default
NoDefault
5.21.13 NoDefaultIfFound

Normally if Radiator searches for a user in the database and finds one, but the users
check items fail, Radiator will then consult the DEFAULT user entry. However, if the
NoDefaultIfFound parameter is set, Radiator will only look for a DEFAULT if there
were no entries found in the user database for the user.
# dont fall through to DEFAULT if a users check item failed
NoDefaultIfFound
5.21.14 DefaultLimit

This optional parameter specifies the maximum number of DEFAULT users to look up
in the database.
5.21.15 AcceptIfMissing

Normally, if a user is not present in the user database, they will always be rejected. If
this optional parameter is set, and a user is not in the database they will be unconditionally accepted. If they are in the database file, they will be accepted if and only if their
check items pass in the normal way.
This option is usually only useful in conjunction with a following AuthBy that will actually check all passwords. It can therefore be used to impose additional checks on a subset of your user population.
Note: When you specify AcceptIfMissing, all reply attributes set for this AuthBy (such
as DefaultReply, AddToReply, AddToReplyIfNotExist etc.) will be applied even if the
user is not explicitly named in the file.
Technical Note: it wont automatically accept DEFAULT users.
# Apply some extra checks for those users in the users file,
# then authenticate them with PLATYPUS
<Realm xxx>
AuthByPolicy ContinueWhileAccept
<AuthBy FILE>
AcceptIfMissing
Filename %D/users
</AuthBy>

86 of 397

Radiator RADIUS Server

Configuration

<AuthBy PLATYPUS>
# whatever
</AuthBy>
</Realm>
5.21.16 DefaultSimultaneousUse

This optional parameter defines a default value for Simultaneous-Use check items that
will apply only if the user does not have their own user-specific Simultaneous-Use
check item.
# Use sim-use of 2 unless there is a user-specific entry
DefaultSimultaneousUse 2
5.21.17 CaseInsensitivePasswords

This optional parameter permits case insensitive password checking for authentication
methods that support plaintext password checks, such as FILE, SQL, DBFILE and some
others. It has no effect on CHAP or MSCHAP passwords, or on password checking
involving any encrypted passwords.
# Permit case insensitive password checks
CaseInsensitivePasswords
5.21.18 RejectEmptyPassword

This optional parameter forces any Access-Request with an empty password to be

rejected. This is provided as a work around for some broken remote RADIUS servers
(VMS RADIUS server in particular) that incorrectly accept requests with empty passwords.
# Reject anything with an empty password
RejectEmptyPassword
5.21.19 AuthenticateAccounting

This optional parameter forces Radiator to authenticate accounting requests (as well as
the normal Access-Requests). It is very rarely required.
5.21.20 IgnoreAuthentication

This optional parameter causes the AuthBy to IGNORE all authentication requests. This
can be useful for providing fine control over authentication with multiple AuthBy
clauses.
5.21.21 IgnoreAccounting

This optional parameter causes the AuthBy to IGNORE all accounting requests. This
can be useful for providing fine control over authentication with multiple AuthBy
clauses.
5.21.22 RcryptKey

This optional parameter indicates that the passwords in the user database may have been
reversibly encrypted using Rcrypt. Any password in the database read by this AuthBy
and which is in the form {rcrypt}anythingatall will be interpreted as an Rcrypt password and the function Radius::Rcrypt::decrypt() will be used to decrypt it
before any password comparisons are made. Rcrypt encrypted passwords are compatible with PAP, CHAP, and MS-CHAP.

Radiator RADIUS Server

87 of 397

Configuration

Rcrypt reversible encryption allows you keep your user password database reasonably
secure, but still support CHAP, MS-CHAP and other authentication methods that
require access to the plaintext password. Rcrypt encryption is supported as an option by
the RAdmin RADIUS user administration package from Open System Consultants.
Hint: The value of RcryptKey must exactly match the key that was used to originally
encrypt the passwords.
Hint: You can add Rcrypt encryption and decryption to other programs with the
Radius::Rcrypt perl module supplied with Radiator.
5.21.23 EAPType

This optional parameter specifies which EAP authentication systems are permitted
when EAP authentication is requested by the NAS. See RFCs 3748, 5216, 2433 for
more details. When an EAP Identity request is received, Radiator will reply with an first
EAP type given. If the NAS requests another type, it will only be permitted if it appears
in EAPType. It is ignored and has no effect unless EAP authentication is requested. The
allowed values for EAPType are given by the following table.

TABLE 4.

88 of 397

Allowed values for EAPType

EAPType

Meaning

MD5
MD5-Challenge

Default. Use MD5-Challenge as per RFC 3748. Can be used with any authentication method that provides a plaintext password, such as AuthBy FILE, SQL,
LDAP, etc. Cannot be used with AuthBy NT, ADSI. See goodies/eap_md5.cfg
for example configuration.

One-Time-Password

Use One-time-password authentication as per RFC 3748. Requires a one-time

password authenticator such as AuthBy OPIE, AuthBy OTP

Generic-Token

Use Generic Token authentication as per RFC 3748. Requires a token-based

authenticator such as AuthBy OPIE, AuthBy OTP, AuthBy ACE, or AuthBy
RSAMOBILE.

TLS

Use Transport Layer Security (TLS). Can be used with any authentication
method. Checks that the client certificate is valid and has a short enough certificate chain to the root certificate. Requires an SSL certificate for the server and
one on each client requiring authentication. See goodies/eap_tls.cfg for example
configuration.

TTLS

Use Tunnelled TLS as required by Funk Odyssey wireless clients. Can be used
with any authentication method. TTLS does not usually involve a client certificate, but the client may be configured to check the servers SSL certificate. See
goodies/eap_ttls.cfg for example configuration.

PEAP

Use PEAP tunnel as used by Windows XP and others. Can be used with any
authentication method. See goodies/eap_peap.cfg for example configuration.

LEAP

Compatible with Cisco LEAP authentication, a proprietary authentication protocol. Requires an authenticator that supplies plaintext passwords (such as AuthBy
FILE, SQL, LDAP etc.), or MSCHAPV2 (such as AuthBy LSA etc.).

SIM

Use EAP-SIM which authenticates against SIM cards (requires the additional
EAP-SIM bundle from Open System Consultants)

Radiator RADIUS Server

Configuration

TABLE 4.

Allowed values for EAPType

EAPType

Meaning

AKA

Use EAP-AKA (requires the additional EAP-SIM bundle from Open System
Consultants, which contains support for EAP-AKA)

AKA-PRIME

Use EAP-AKA (requires the additional EAP-SIM bundle from Open System
Consultants, which contains support for EAP-AKA)

MSCHAP-V2

Use EAP-MSCHAPV2, which is commonly tunneled inside PEAP

TNC

Support EAP-TNC, a protocol for assessing the security posture of end points.

FAST

Use EAP-FAST, a little used protocol from Cisco

PAX

Use EAP-PAX (Password Authenticated Exchange)

PSK

Use EAP-PSK (Pre-Shared Key)

PWD

Use EAP-pwd, a method which uses a shared password for authentication

There is no default, which means that by default, Radiator will not perform EAP authentication.
5.21.24 EAPContextTimeout

This optional parameter specifies the maximum time period in seconds an EAP context
will be retained. Defaults to 1000 seconds. You should not need to change this.
5.21.25 EAPAnonymous

For tunnelling EAP types, such as TTLS and PEAP, this optional parameter specifies
the User-Name that will be used in the RADIUS request resulting from the EAP inner
request. Defaults to anonymous. Special characters may be used. %0 is replaced by the
EAP Identity of the inner EAP request.
This parameter can be useful when proxying the inner authentication. If there is a realm
in the EAPAnonymous name, it can be used to choose a local Realm to handle the inner
authentication.
5.21.26 EAPTLS_CAFile

For TLS based EAP types such as TLS, TTLS and PEAP, this parameter specifies the
name of a file containing Certificate Authority (CA) root certificates that may be
required to validate TLS client certificates. The certificates are expected to be in PEM
format. The file can contain several root certificates for one or more CAs. Radiator will
look for root certificates in EAPTLS_CAFile then in EAPTLS_CAPath, so there usually is no need to set both.
EAPTLS_CAFile is expected to contain a stack of CA one or more CA certificates that
will be used to validate client certificates. The list of CA issuers in that file will also be
sent to the client during handshaking to tell the client which certificates Radiator is willing to accept.

Radiator RADIUS Server

89 of 397

Configuration

So, EAPTLS_CAFile must contain all the CA root and intermediate certificates
required to validate all the various client certificates that may be installed on your supplicant devices.
Special characters are supported.
5.21.27 EAPTLS_CAPath

For TLS based EAP types such as TLS, TTLS and PEAP, this parameter specifies the
name of a directory containing CA root certificates that may be required to validate TLS
client certificates. The certificates are expected to one per file in PEM format. The files
names are looked up by the CA Subject Name hash value. Radiator will look for root
certificates in EAPTLS_CAFile then in EAPTLS_CAPath, so there usually is no need
to set both.
Special characters are supported.
5.21.28 EAPTLS_CertificateFile

For TLS based EAP types such as TLS, TTLS and PEAP, this parameter specifies the
name of a file containing the RADIUS server certificate. The server certificate will be
sent to the EAP client and validated by the client during EAP authentication. The certificate file may be in PEM or ASN1 format (depending on the setting of the
EAPTLS_CertificateType parameter). The certificate file can also contain the servers
TLS private key if the EAPTLS_PrivateKeyFile parameter specifies the same file. If the
server certificate is in fact a chain of certificates, then you should use EAPTLS_CertificateChainFile instead.
Special characters are supported.
5.21.29 EAPTLS_CertificateChainFile

For TLS based EAP types such as TLS, TTLS and PEAP etc, this parameter specifies
the name of a file containing a certificate chain for the Radius server certificate. The
server certificate chain will be sent to the EAP client and validated by the client during
EAP authentication. The certificate chain must be in PEM format. EAPTLS_CertificateChainFile may be used instead of EAPTLS_CertificateFile for explicitly constructing
the server certificate chain which is sent to the client.
You should use EAPTLS_CertificateChainFile to specify a chain of certificates that the
server uses to identify itself to the client. If there is only one server certificate (and not
a chain) then you can use EAPTLS_CertificateFile instead.
Special characters are supported.
5.21.30 EAPTLS_CertificateType

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the format of the EAPTLS_CertificateFile. Permitted options are:

PEM
ASN1
The default is ASN1.
90 of 397

Radiator RADIUS Server

Configuration

Special characters are supported.

5.21.31 EAPTLS_PrivateKeyFile

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the name of the file containing the servers private key. It is sometimes in the same
file as the server certificate (EAPTLS_CertificateFile). If the private key is encrypted
(which is usually the case) then EAPTLS_PrivateKeyPassword is the key to decrypt it.
Special characters are supported.
5.21.32 EAPTLS_PrivateKeyPassword

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the password that is to be used to decrypt the EAPTLS_PrivateKeyFile. Special
characters are permitted.
Special characters are supported.
5.21.33 EAPTLS_RandomFile

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the name of a file containing randomness. You should not normally need to set this
parameter.
Special characters are supported.
5.21.34 EAPTLS_DHFile

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the name of the DH group. You should not normally need to set this parameter, but
it may be required if you are using ephemeral DH keys.
Special characters are supported.
5.21.35 EAPTLS_AllowUnsafeLegacyRenegotiation

For TLS based EAP types such as TLS, TTLS and PEAP, and with versions of
OpenSSL 0.9.8m and later, this optional parameter enables legacy insecure renegotiation between OpenSSL and unpatched clients or servers. OpenSSL 0.9.8m and later
always attempts to use secure renegotiation as described in RFC5746. This counters the
prefix attack described in CVE-2009-3555 and elsewhere.
5.21.36 EAPTLS_MaxFragmentSize

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter specifies the maximum size in octets permitted for each TLS message fragment. Defaults to
2048, but many EAP clients, routers and wireless Access Points have limitations that
require EAPTLS_MaxFragmentSize to be set as low as 1000 or less. Setting this number too small can result in excessive RADIUS request round trips during EAP TLS
authentication, slowing down the authentication process. Setting this number too large
can result in failure to complete TLS authentication for some types of clients and
devices. Many customers find that 1300 is a good compromise.
The EAP packet that is encapsulated inside EAP-Message + all other radius attributes
must not exceed one Ethernet frame because EAP doesnt support fragmentation.
Radiator RADIUS Server

91 of 397

Configuration

Depending on the number of other radius attributes your switches or WLAN controllers
send to the RADIUS servers you can increase EAPTLS_MaxFragmentSize, which may
result in fewer RADIUS requests in the EAP conversation which reduces the authentication time and lowers to load on both the RADIUS client (switch, WLAN controller)
and RADIUS server.
If incoming RADIUS requests have Framed-MTU that is less than EAPTLS_MaxFragmentSize, then Radiator will use reported Framed-MTU to limit fragment size when
doing TLS, TTLS, PEAP and PSK.
Special characters are supported.
5.21.37 EAPTLS_CRLCheck

For TLS based EAP types such as TLS, TTLS and PEAP that have been configured to
check client certificates, this optional parameter specifies that Certificate Revocation
List must be checked for revoked certificates.
Special characters are supported.
5.21.38 EAPTLS_CRLFile

For TLS based EAP types such as TLS, TTLS and PEAP, and where CRL checking has
been enabled with EAPTLS_CRLCheck, this optional parameter specifies one or more
CRL files that will be used to check client certificates for revocation.
If a CRL file is not found, or if the CRL says the certificate has been revoked, TLS
authentication will fail with an error:
SSL3_GET_CLIENT_CERTIFICATE:no certificate returned
One or more CRLs can be named with the EAPTLS_CRLFile parameter. Alternatively,
CRLs may follow a file naming convention: the hash of the issuer Subject Name and a
suffix that depends on the serial number. e.g. ab1331b2.r0, ab1331b2.r1 etc.
You can find out the hash of the issuer name in a CRL with:
openssl crl -in crl.pem -hash -noout

CRLs with this name convention will be searched in EAPTLS_CAPath, else in the
openssl certificates directory (typically /usr/local/openssl/certs/)
CRLs are expected to be in PEM format. A CRL file can be generated with openssl like
this:
openssl ca -gencrl -revoke cert-clt.pem
openssl ca -gencrl -out crl.pem

Use of these flags requires Net_SSLeay-1.30 or later.

Technical Note: CRL reloading does not currently work as described with the recent
OpenSSL libraries. To ensure the CRL files are correctly used, you may need to restart
Radiator when the CRL files change.

92 of 397

Radiator RADIUS Server

Configuration

The intended way CRL reloading, see the technical note above, works is this: Each CRL
file named with a EAPTLS_CRLFile will be automatically reloaded and reread at the
start of each new EAP TLS, TTLS or PEAP session if the modification date of the
named CRL file has changed since the last time it was loaded. If the CRL for a particular issuer changes, it is sufficient to replace the existing CRL file with the newer version
and Radiator will reload the new CRL when required.
Hint: Operating system wildcards are supported, so you can name multiple CRLs with a
single wildcard like:
EAPTLS_CRLFile %D/crls/*.r0

Hint: dont use the issuer name hash as the CRL file name: it can confuse OpenSSL.
Use a text name like:
EAPTLS_CRLFile revocations.pem

Special characters are supported.

5.21.39 EAPTLS_SessionResumption

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter allows
you to enable or disable support for TTLS Session Resumption and PEAP Fast Reconnect. Default is enabled
# Disable session resumption
EAPTLS_SessionResumption 0

Special characters are supported.

5.21.40 EAPTLS_SessionResumptionLimit

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter allows
you to limit how long after the initial session that a session can be resumed (time in seconds). Defaults to 43200 seconds (12 hours)
Special characters are supported.
5.21.41 EAPTLSRewriteCertificateCommonName

For TLS based EAP types such as TLS, TTLS and PEAP, this optional parameter allows
you to rewrite the Common Name in the clients TLS certificate before using it to find
the username in the Radiator database:
EAPTLSRewriteCertificateCommonName s/testUser/mikem/
5.21.42 EAPTLS_PEAPVersion

For PEAP, his optional parameter allows you to control which version of the draft PEAP
protocol to honour. Defaults to 0. Set it to 1 for unusual clients.
5.21.43 EAPTLS_PEAPBrokenV1Label

This optional parameter makes PEAP Version 1 support compatible with non-standard
PEAP V1 clients that use the old broken TLS encryption labels that appear to be used
frequently, due to Microsofts use of the incorrect label in its V0 client.

Radiator RADIUS Server

93 of 397

Configuration

5.21.44 EAPTLS_RequireClientCert

This optional parameter forces TTLS and PEAP to require a valid client certificate to be
presented by the client. TLS always requires a valid client certificate, regardless of the
setting of this parameter. In this case valid means that the certificate is within its validity dates and has been signed by a CA for which Radiator has a root certificate.
5.21.45 EAP_PEAP_MSCHAP_Convert

For EAP-PEAP MSCHAPV2 authentication, this optional parameter tells Radiator to

convert the inner EAP-MSCHAPV2 request into a conventional RADIUS-MSCHAPV2
request. The new RADIUS-MSCHAPV2 request will be redespatched to the Handlers,
where it can be detected and handled with <Handler ConvertedFromEAPMCSCHAPV2=1>.
This can be useful when proxying PEAP-MSCHAPV2 inner requests to a remote
RADIUS server that can handle ordinary RADIUS-MSCHAPV2, but not EAP authentication. See goodies/eap_peap_mschap_proxy.cfg in your distribution for an example of
how to configure such a convert-and-proxy system.
5.21.46 EAP_LEAP_MSCHAP_Convert

For LEAP authentication, this optional parameter tells Radiator to convert the LEAP
request into a conventional RADIUS-MSCHAP request. The new RADIUS-MSCHAP
request will be redespatched to the Handlers, where it can be detected and handled with
<Handler ConvertedFromLEAP=1>.
This can be useful for proxying LEAP requests to a remote RADIUS server that cannot
handle LEAP, but which can handle RADIUS-MSCHAP. See goodies/
eap_leap_proxy.cfg in your distribution for an example of how to configure such a convert-and-proxy system.
5.21.47 EAPTLS_NoCheckId

For EAP-TLS authentication, this optional parameter prevents the comparison of the
username with the certificate common name. The certificate will be accepted based only
on the validity dates and the verification chain to the root certificate, and there is no
requirement for the user to be in any Radiator user database. This allows Radiator to
mimic the behaviour of some other RADIUS servers.
5.21.48 EAPTLS_CertificateVerifyHook

For EAP-TLS authentication, this optional parameter specifies a perl function that will
be called after the request username or identity has been matched with the certificate
CN. It is passed the certificate, and various other details, and returns a different user
name which will be used to do the user database lookup.
The function is passed the following arguments:
$matchedcn is the CN in the certificate that was matched against either the username or
EAP identity. It is normally used as the user name to do the user database lookup, but
you can return a new name from this function.

$_[0] is $matchedcn, the CN that matched the user name or identity (with or without
the ___domain name).

94 of 397

Radiator RADIUS Server

Configuration

$_[1] is $x509_store_ctx, the EAP SSLEAY store context (you can pass this to
Net::SSLeay::X509_STORE_CTX_get_current_cert)

$_[2] is $cert, the current certificate, result of Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);

$_[3] is $subject_name, the certificates subject name, result of

&Net::SSLeay::X509_get_subject_name($cert);

$_[4] is $subject, the certificate subject, result of

&Net::SSLeay::X509_NAME_oneline($subject_name);

$_[5] is $p, the current Radius::Radius request.

The function is expected to return a new value for $matchedcn, which will be used to do
the user database lookup. If it returns undef, the certificate verification will be deemed
to fail with the OpenSSL error X509_V_ERR_APPLICATION_VERIFICATION.
5.21.49 EAPTLS_CommonNameHook

This optional parameter specifies a Perl hook that can be used to choose the authenticated CN from the client certificate during EAP-TLS authentication. Normally EAPTLS attempts to match each CN in the client certificate (after EAPTLSRewriteCertificateCommonName is executed) against the User-Name (with and without any trailing
@___domain) and the EAP identity (with and without any trailing @___domain). If any match
is found, that will be the authenticated CN, and that will be the name that will be used to
look up the username in the user database.
If EAPTLS_CommonNameHook is defined it is a hook that will return the username
that is a correct match with the CN.
It is called for each CN in the client certificate with the following arguments:

$_[0] The CN
$_[1] The User-Name from the incoming request
$_[2] The EAP Identity of the TLS handshake
It is expected to return the matched CN or undef if no match occurred.
5.21.50 TranslatePasswordHook

This optional parameter specifies a Perl hook that can be used to convert, translate or
transform plaintext passwords after retrieval from a user database and before comparison with the submitted password received from the client. The hook is passed the following arguments:

$_[0] The correct password as retrieved from the user database.

$_[1] A reference to the current AuthBy module object.
$_[2] The user name being authenticated.
$_[3] A flag saying whether the correct password is encrypted by crypt() or
MSCHAP.

$_[4] A reference to the current RADIUS request.

Radiator RADIUS Server

95 of 397

Configuration

The hook is expected to return a single scalar value containing the transformed password. In the following example, all passwords are transformed to uppercase.
# Translate all passwords to UPPERCASE
TranslatePasswordHook sub {$_[0] =~ tr/a-z/A-Z/; return $_[0]}
5.21.51 CheckPasswordHook

This optional parameter specifies a Perl hook that can be used to compare password
retrieved from a user database with the submitted password received from the client.
The retrieved passwords must start with the leading prefix {OSC-pw-hook} The hook
must return true when the password is deemed correct. This hook is for proprietary hash
formats and other custom password check methods. This hook runs after TranslatePasswordHook. The hook is passed the following arguments:

$_[0] A reference to the current RADIUS request.

$_[1] The password submitted by the user.
$_[2] The correct password as retrieved from the user database without the prefix.
5.21.52 AutoMPPEKeys

Some NASs, PPoE, VPDN and wireless clients require MPPE keys in the AccessAccept message. If this AuthBy is doing MS-CHAP V1 authentication with a plaintext
password, then setting this optional parameter will force Radiator to automatically reply
with MS-CHAP-MPPE-Keys computed from the plaintext password. If this AuthBy is
doing MS-CHAP V2 authentication with a plaintext password, then setting this optional
parameter will force Radiator to automatically reply with MS-MPPE-Send-Key and
MS-MPPE-Recv-Key computed from the plaintext password. Has no effect with
encrypted passwords. Has no effect unless there is a User-Password check item for the
user. Defaults to no automatic MS-CHAP-MPPE-Keys.
Hint: This option is almost always necessary in the outer Handler for PEAP, TTLS, TLS
and other TLS based protocols to set the access points encryption keys correctly.
5.21.53 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5 until they have been completely processed. This is useful for logging packets
that pass through this clause in more detail than other clauses during testing or debugging. The packet tracing will stay in effect until it passes through another clause with
PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace
5.21.54 CachePasswords

This parameter enables a user password cache in this AuthBy. It can be used to improve
the performance of slow AuthBy clauses, or when large number of identical requests for
the same user are likely to occur, or when multiple request might result from a one-timepassword (in a multi-link or wireless roaming environment) etc.
If this parameter is set, all Access-Requests will first be checked against a password
cache that contains a copy of the last valid Access-Accept for that user. If the cache contains a matching password that has not exceeded its CachePasswordExpiry, the previous
96 of 397

Radiator RADIUS Server

Configuration

reply will be sent back, without looking up the user again in this AuthBy. Therefore the
possibly slow process of consulting the user database or proxying the request can be
sometimes avoided.
Hint: Not all AuthBy clauses support this parameter (or CachePasswordExpiry and
CacheReplyHook), but the ones that do include UNIX, FILE, DBFILE, EMERALD,
SQL, LDAP, ACE, OPIE, PLATYPUS, RADMIN and RADIUS. Other AuthBy clauses
may or may not support this parameter.
Hint: Use of this parameter with a large user population can cause large amounts of
memory use by the Radiator process.
Hint: If Radiator is restarted, the password cache is lost.
Note: Matching of cached passwords can never succeed for CHAP or MS-CHAP
authentication requests
5.21.55 CachePasswordExpiry

If CachePasswords is enabled, this parameter determined the maximum age (in seconds)
for cached passwords. Defaults to 86400 seconds (1 day). Cached passwords that are
more than this number of seconds old will not be used.
5.21.56 CacheReplyHook

This optional parameter allows you to define a Perl hook that runs when a cached reply
is about to be returned to the NAS because of CachePasswords.
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
The hook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change or set up environment variables, umasks etc.
The arguments passed to the hook are:

Argument 0 is the object handle for this AuthBy object.

Argument 1 is the user name being authenticated
Argument 2 is the received request packet.
Argument 3 is the cached reply packet that is about to be returned to the NAS.

5.21.57 ClearTextTunnelPassword

This optional parameter prevents Radiator from encrypting Tunnel-Password attributes

in replies. This is provided in order to support older NASs that do not support encrypted
Tunnel-Password.
# Old NAS does not support encrypted Tunnel-Password
ClearTextTunnelPassword
AddToReply Tunnel-Password=xxx

Radiator RADIUS Server

97 of 397

Configuration

5.21.58 NoCheckPassword

This optional parameter causes AuthBy not to check the password. This means that any
password entered by the user will be accepted.
This parameter is useful in conjunction with other authentication methods where the
password check is done elsewhere.
5.21.59 AuthenticateAttribute

This optional parameter allows you to control which RADIUS attribute is used to look
up the user database. Normally, Radiator uses the User-Name RADIUS attribute as the
key to find a user in the user database. If the AuthenticateAttribute parameter is defined,
it specifies the name of an alternative RADIUS attribute that will be used as the key during the lookup in the user database. This is useful in order to do authentication based on,
say, the Calling-Station-Id:
# look up database based on Calling-Station-Id
AuthenticateAttribute Calling-Station-Id
5.21.60 NoEAP

This optional parameter disables EAP authentication in this AuthBy. If the AuthBy
would otherwise do EAP authentication, this parameter forces it to do conventional
authentication. This can be useful for performing additional checks besides EAP
authentication, for example when doing MAC Address whitelist checking as well as
EAP authentication:
AuthByPolicy ContinueWhileAccept
# Check the MAC address is valid..
<AuthBy FILE>
NoEAP
AuthenticateAttribute Calling-Station-Id
Filename ...
...
</AuthBy>
# then check the username and password, perhaps by EAP
<AuthBy LDAP>
EAPType ....
....
</AuthBy>
5.21.61 UsernameMatchesWithoutRealm

This optional parameter forces authenticators to strip any realm from the username
before authenticating the name. This allows users to log in with user@realm, even
though their user database user name is just user.
5.21.62 Blacklist

Reverses the sense of authentication checks, making it easier to implement blacklists. If

the user name matches the user database, then they will be rejected. If there is no match
they will be accepted.
5.21.63 EAPFAST_PAC_Lifetime

For EAP-FAST, specifies the maximum lifetime for each PAC.

98 of 397

Radiator RADIUS Server

Configuration

5.21.64 EAPFAST_PAC_Reprovision

For EAP-FAST, specifies the time after which a PAC should be re-provisioned
5.21.65 EAPErrorReject

If an EAP error occurs, REJECT instead of IGNORE. The RFCs say that IGNORE is
the correct behaviour, but REJECT can work better in some load balancing situations.
5.21.66 PasswordPrompt

For AuthBys that support the feature, specifies the prompt to be used when asking for a
password.
5.21.67 PreHandlerHook

For EAP types that carry inner requests (such as PEAP, TTLS, FAST etc), specifies a
Perl hook to be called before the inner request is re-dispatched to a matching Realm or
Handler.
5.22 <AuthBy ACE>
The AuthBy ACE module performs authentication directly to an RSA Security Authentication manager (formerly SecurID ACE/Server). See www.rsasecurity.com for details.
RSA Security Authentication Manager provides a token-based one-time password system. AuthBy ACE requires the Authen-ACE4 Perl module from CPAN (pre-built binaries for Windows are available in your Radiator distribution).
Hint: AuthBy ACE works with RSA Authentication Manager 7.1 and later. If you have
AM 7.1 or later you might consider using <AuthBy RSAAM>, since it is more capable
and more portable.
Before using this AuthBy method you should ensure that you have:

Installed and configured Authentication Manager.

Purchased tokens for each user from RSA Security
Added the users that you wish to authenticate to Authentication Manager, and
assigned each one a token.

In Authentication Manager, added an Agent Host for each Radiator server host you
intend to operate. If Radiator will run on the same host as Authentication Manager,
make sure you add an Agent Host for that host.

On Unix, Installed and configured the ACE agent software, then Downloaded, built
and installed the Authen-ACE4 perl module, provided by Open System Consultants.

On Windows, install the pre built PPM package provided in the ppm directory of the
Radiator distribution, see the instructions in goodies/ace.txt in your distribution.
AuthBy ACE will also work with EAP-Generic-Token-Card and EAP-PEAP-GenericToken-Card authentication, as well as RADIUS PAP and TTLS-PAP.
Hint: There are more detailed installation and testing instructions in the goodies/ace.txt
file in your distribution.

Radiator RADIUS Server

99 of 397

Configuration

Hint: An alternative to using AuthBy ACE is to proxy requests to the optional RADIUS
server that comes with Authentication Manager (although that RADIUS server has
many fewer features and supported platforms than Radiator).
Hint: There is an example Radiator configuration file for AuthBy ACE in goodies/
ace.cfg in your Radiator distribution.
Hint: AuthBy ACE uses the State reply item to get the RADIUS client to carry the context from one step of authentication to the next. If you wish to test AuthBy ACE with
radpwtst, you should use the -interactive flag.
radpwtst -interactive -user fred -password 1234574424

Hint: AuthBy ACE and Authen-ACE4 can work across the network to a remote
Authentication Manager on another host. See the RSA Security ACE/Agent documentation for details on how to configure remote Agent access.
5.22.1 How to use RSA Security token cards to log in with AuthBy ACE

RSA Security produce 2 main types of hardware tokens. Standard cards and key fobs
tokens have an LCD display that changes every 60 seconds, but no other buttons or
switches. Pinpad cards have an LCD display, and also 0-9 keys, a diamond button and
a P button. The way you generate your password depends on the type of token you
have.
In RSA terminology, the number displayed by a token is called the tokencode The
number is typically 6 or 8 digits long and changes every 60 seconds. The PIN is a
secret 4 digit or longer number that you will be assigned (or may have selected) and
which you must remember. The passcode is what you use as your password to log in,
and consists of the PIN followed by the tokencode.
For standard tokens, the passcode is formed from the PIN followed by the tokencode
displayed on the token at that time. So, for example, if the PIN you have remembered
that was assigned to you is 1234, and the token is currently displaying the tokencode
627351, then the passcode that you will use as your password is 1234627351 (thats
10 digits). See Figure 1, Making a password from an RSA Security Token Code (not
for Pinpads), on page 100.
PIN
Assigned to you
or maybe
selected by you.
You must remember it
and enter it before the
tokencode

FIGURE 1.

1234627531

Tokencode
Displayed on the LCD
of the token

Making a password from an RSA Security Token Code (not for Pinpads)

When a standard token is set to New PIN Mode by the ACE administrator, you must
first login in with your PIN and the current tokencode, and you will then be prompted
100 of 397

Radiator RADIUS Server

Configuration

by Radiator for your new PIN. If the token is set to New PIN mode and also has a
Cleared PIN, you must omit your PIN
For Pinpad tokens, you have to enter the PIN into the token to generate the passcode. If
for example, your remembered PIN is 1234, enter the PIN into the Pinpad one digit at a
time (press 1 - 2 - 3 - 4), then press the diamond button. The token will then display a
new tokencode, say 736284. You would then use 736284 (thats only 6 digits) as your
password. When a Pinpad token is set to New Pin Mode by the ACE administrator, you
must create your passcode in the usual way and then the system will prompt them for
their new PIN., When a Pinpad is in New Pin Mode and also has a cleared PIN, the user
must enter the tokencode showing on the token (without using a PIN) first, and then the
system will prompt them for their new PIN.
Note that some types of tokens display an 8 digit tokencode, rather than a 6 digit tokencode.AuthBy ACE understands the following parameters as well as those described in
Section 5.21 on page 82:
5.22.2 ConfigDirectory

This optional parameter specifies the ___location of the ACE Agent sdconf.rec file, which
the ACE Agent client libraries use to find the ___location of the ACE server(s). It is also the
directory where the node secret files will be saved. The user ID that runs Radiator must
have read and write access to this directory. The file sdconf.rec must be present on the
machine where AuthBy ACE is running. Defaults to the value of the VAR_ACE environment variable, if set, else /var/ace. This parameter has no effect on Windows.
ConfigDirectory /opt/ace/data
5.22.3 Timeout

This optional parameter specifies the maximum time that a single ACE authentication is
allowed to take. A typical ACE authentication will require several RADIUS transactions, involving multiple requests and challenges until the final Access-Accept is sent,
and there is no guarantee that the user will complete the authentication process. If the
total time for the authentication exceeds this number of seconds, the authentication will
be abandoned. Defaults to 300 seconds (5 minutes).
5.22.4 EnableFastPINChange

Some NASs, notably some Juniper devices, have non-standard behaviour in New Pin
Mode: when the user is asked whether they want to set their PIN, the NAS automatically gets the new PIN from the user and returns it to the Radiator server, which is
expected to use it to set the PIN immediately. This flag enables compatibility with this
behaviour if the user/device enters a PIN instead of y or n. If EnableFastPINChange
is enabled and the token is in New PIN mode and the users response does not look like
y or n, then the response will be used to set the new PIN, bypassing the PIN confirmation dialogues. Defaults to disabled.
5.23 <AuthBy TEST>
The AuthBy TEST module always accepts authentication requests, and ignores (but
replies to) accounting requests. It is implemented in AuthTEST.pm. It is useful for
testing purposes, but you should be sure not to leave them lying around in your configu-

Radiator RADIUS Server

101 of 397

Configuration

ration file, otherwise you might find that users are able to be authenticated when you
really didnt want them to.
AuthBy TEST can also serve as a useful template for developing your own AuthBy
modules. See Section 16.0 on page 361.
AuthBy TEST understands the following parameters:
5.23.1 Identifier

This allows you to assign a symbolic name to an AuthBy clause and its configuration.
This allows you to refer to it by name in an Auth-Type check item when authenticating
a user.
5.24 <AuthBy FILE>
AuthBy FILE authenticates users from a user database stored in a flat file. It ignores
(but replies to) accounting requests. It is implemented in AuthFILE.pm. It understands standard Livingston user files as described in Section 15.2 on page 358.
For performance reasons, AuthBy FILE opens and reads the user database at start-up,
reinitialization and whenever the files modification time changes, (i.e. the database is
cached within Radiator). Since the user database is cached in memory, large databases
can require large amounts of memory.
AuthBy FILE supports a Nocache parameter that causes the user database to not be
cached, and forces the file to be reread for every authentication. It will do a linear search
for the user. You should be very careful about using this because it could be very slow
for more than 1000 users or so. Also, authentication speed will depend on the users
position in the file, and will be faster for users near the beginning of the file. If you need
Nocache in a production setting, you should consider DBFILE instead.
When attempting to authenticate a user, AuthBy FILE will first compare all the check
items associated with the user. It understands and handles check items as described in
Section 13.1 on page 334.
If all the check items agree with the attributes in the Access-Request message, AuthBy
FILE will reply with an Access-Accept message containing all the attributes given as
reply attributes in the user database. Some reply attributes are given special handling as
described in Section 13.2 on page 349. If the user does not appear in the database, or if
any check attribute does not match, an Access-Reject message is sent to the client.
AuthBy FILE understands the following parameters as well as those described in
Section 5.21 on page 82:
5.24.1 Filename

Specifies the filename that holds the user database. Defaults to %D/users, i.e. a file
named users in DbDir. The file name can include special formatting characters as
described in Section 5.2 on page 20.

102 of 397

Radiator RADIUS Server

Configuration

Hint: You should not use %U or %u (which are replaced by the user name) in Filename,
otherwise the filename used will change with every authentication.
# user database is called rad_users in DbDir
Filename %D/rad_users
5.24.2 Nocache

Disables caching of the user database, and forces Filename to be reread for every
Authentication. If not set, AuthBy FILE will only reread the user database when the
files modification time changes. Dont use this parameter unless you have to, because it
can be very slow for any more than 1000 users or so. If you need think you need
Nocache, you should consider DBFILE instead.
# Dont cache so we can do some simple testing
# without restarting the server all the time
Nocache

5.25 <AuthBy DBFILE>

AuthBy DBFILE authenticates users from a user database stored in a DBM file in the
standard Merit DBM format. It is implemented in AuthDBFILE.pm. It does not log
(but does reply to) accounting requests. The file format is described in Section 15.3 on
page 359. DBM files can be built from flat file user databases with the builddbm utility (see Section 9.0 on page 324).
AuthBy DBFILE opens and reads the user database for every authentication. This
means that if you change the user database DBM file, it will have an immediate effect.
The DBM file is not locked when it is accessed.
When attempting to authenticate a user, AuthBy DBFILE will first compare all the
check items associated with the user in the same way as <AuthBy FILE> on
page 102. If all those match the attributes in the Access-Request message, AuthBy
DBFILE will reply with an Access-Accept message containing all the attributes given
as reply attributes in the user database. If the user does not appear in the database, or if
any check attribute does not match, an Access-Reject message is sent to the client.
AuthBy DBFILE understands the following parameters as well as those described in
Section 5.21 on page 82:
5.25.1 Filename

Specifies the filename that holds the user database. Defaults to %D/users, i.e. files
named users.dir and users.pag in DbDir. The file name can include special formatting characters as described in Section 5.2 on page 20. Depending on the actual
DBM module that Perl chooses, the database files may have other extensions.
# user database is called rad_users in DbDir
Filename %D/rad_users
5.25.2 DBType

By default, Radiator and Perl will choose the best format of DBM file available to
you, depending on which DBM modules are installed on your machine. You can over-

Radiator RADIUS Server

103 of 397

Configuration

ride this choice by specifying DBType as the name of one of the DBM formats supported on your platform. The typical choices are:

AnyDBM_File
NDBM_File
DB_File
GDBM_File
SDBM_File
ODBM_File

but not may be available on your platform. The default is AnyDBM_File, which
chooses the best available implementation.
# Force it to use DB_File
DBType DB_File

Hint: If you alter this, you will probably have to use the -t flag set to the same type on
builddbm to force it to build a compatible database
5.26 <AuthBy CDB>
AuthBy CDB authenticates users from a user database stored in a CDB database file.
CDB is a fast, reliable, lightweight package for creating and reading constant databases.
More details about CDB can be found at http://cr.yp.to/cdb.html. It is implemented in
AuthCDB.pm, which was contributed by Pedro Melo ([email protected]). It does not log
(but does reply to) accounting requests. To use AuthBy CDB, you must install the
CDB_File package from CPAN (you dont need to install the cdb package from koobera; CDB_File is packaged with all the files you need).
AuthBy CDB opens and reads the user database for every authentication. This means
that if you change the user database CDB file, it will have an immediate effect. The
CDB file is not locked when it is accessed.
The CDB is indexed by username and the value is the check items followed by a newline followed by the reply items.
When attempting to authenticate a user, AuthBy CDB will first compare all the check
items associated with the user in the same way as <AuthBy FILE> on page 102. If all
those match the attributes in the Access-Request message, AuthBy CDB will reply with
an Access-Accept message containing all the attributes given as reply attributes in the
user database. If the user does not appear in the database, or if any check attribute does
not match, an Access-Reject message is sent to the client.
AuthBy CDB understands the following parameters as well as those described in
Section 5.21 on page 82:

104 of 397

Radiator RADIUS Server

Configuration

5.26.1 Filename

Specifies the filename that holds the user database. Defaults to %D/users.cdb. The
file name can include special formatting characters as described in Section 5.2 on
page 20.
# user database is called rad_users.cdb in DbDir
Filename %D/rad_users.cdb

5.27 <AuthBy GROUP>

AuthBy GROUP allows you to conveniently define and group multiple AuthBy clauses.
It is implemented in AuthGROUP.pm. This is most useful where you need to be able to
have multiple sets of authentication clauses, perhaps with different AuthByPolicy settings for each group. You can use an AuthBy GROUP (containing any number of
AuthBy clauses) anywhere that a single AuthBy clause is permitted. AuthBy GROUP
can be nested to any depth.
AuthBy GROUP will try each AuthBy method in turn until one of them either Accepts
or Rejects the request (you can change this with AuthByPolicy, see Section 5.20.16 on
page 77).
<AuthBy GROUP>
AuthByPolicy ContinueUntilReject
<AuthBy SQL>
...
</AuthBy>
<AuthBy DBM>
...
</AuthBy>
<AuthBy GROUP>
AuthByPolicy ContinueUntilAccept
RewriteUsername s/^(.+)$/cyb-$1/
<AuthBy FILE>
...
</AuthBy>

<AuthBy FILE>
...

</AuthBy>
</AuthBy>
</AuthBy>

AuthBy GROUP understands the following parameters as well as those described in

Section 5.21 on page 82.
5.27.1 AuthByPolicy

This parameter allows you to control the behaviour of multiple AuthBy clauses inside
this AuthBy GROUP. In particular, it allows you to specify under what conditions Radiator will try the next AuthBy clause. If you only have one AuthBy clause, AuthByPolicy is not relevant and is ignored.
Recall that for a single Realm, Handler or AuthBy GROUP, you can specify more than
one AuthBy clause. The normal behavior of Radiator is to try to authenticate with the

Radiator RADIUS Server

105 of 397

Configuration

first one. If that authentication method either Accepts or Rejects the request, then Radiator will immediately send a reply to the NAS. If on the other hand the AuthBy Ignores
the request, then the next one will be tried. That is the normal and default behavior, but
with AuthByPolicy, you can change it. The permissible values of AuthByPolicy are:

ContinueWhileIgnore
This is the default. Continue trying to authenticate until either Accept, Challenge or
Reject

ContinueUntilIgnore
Continue trying to authenticate until Ignore

ContinueWhileAccept
Continue trying to authenticate as long as it is Accepted

ContinueUntilAccept
Continue trying to authenticate until it is Accepted

ContinueWhileChallenge
Continue trying to authenticate as long as it is Challenged

ContinueUntilChallenge
Continue trying to authenticate until it is Challenged

ContinueWhileReject
Continue trying to authenticate as long as it is Rejected

ContinueUntilReject
Continue trying to authenticate until it is Rejected

ContinueWhileAcceptOrChallenge
Continue trying to authenticate as long as it is either Accepted or Challenged

ContinueUntilAcceptOrChallenge
Continue trying to authenticate until it is either Accepted or Challenged

anything else
Always do every authentication method. Returns the result of the last one.
# Authenticate with SQL, but if they are rejected
# fall back to a flat file
AuthByPolicy ContinueWhileReject
<AuthBy SQL>
....
</AuthBy>
<AuthBy FILE>
....
</AuthBy>

You should note that you can only have one AuthByPolicy parameter, and it applies to
all the AuthBy clauses. You cant change it between one AuthBy clause and another.
Hint: ContinueUntilAcceptOrChallenge is the most useful one when using EAP
requests in an AuthBy GROUP with multiple internal AuthBys.

106 of 397

Radiator RADIUS Server

Configuration

5.27.2 RewriteUsername

This parameter enables you to alter the user name in authentication and accounting
requests before they are passed to any of the AuthBy clauses in this group. See
Section 14.0 on page 353.
You can have any number of RewriteUsername parameters in a group. The rewrites will
be applied to the user name in the same order that they appear in the configuration file.
At Trace level 4, you can see the result of each separate rewrite for debugging purposes.
# Strip the realm from all requests, because our
# database only has user names (no realm)
RewriteUsername
s/^([^@]+).*/$1/

# Translate all uppercase to lowercase

RewriteUsername
tr/A-Z/a-z/
5.27.3 StripFromRequest

Strips the named attributes from the request before passing it to any lower authentication modules. The value is a comma separated list of attribute names. StripFromRequest
removes attributes from the request before AddToRequest adds any to the request.
There is no default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.27.4 AddToRequest

Adds attributes to the request before passing it to any lower authentication modules.
Value is a list of comma separated attribute value pairs all on one line, exactly as for any
reply item. StripFromRequest removes attributes from the request before AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.
# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h
5.27.5 AddToRequestIfNotExist

Adds attributes to the request before passing it to any lower authentication modules.
Unlike AddToRequest, an attribute will only be added if it does not already exist in the
request. Value is a list of comma separated attribute value pairs all on one line, exactly
as for any reply item. StripFromRequest removes attributes from the request before
AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any
of the special % formats in the attribute values. There is no default.
# Append a Filter-ID and host name if they are not there already
AddToRequestIfNotExist Calling-Station-Id=1,Login-IP-Host=%h

5.28 <AuthBy UNIX>

AuthBy UNIX authenticates users from a user database stored in a standard Unix password file or similar format. It is implemented in AuthUNIX.pm. It does not log (but
does reply to) accounting requests. The file format is described in Section 15.4 on
page 359. Since Unix password files only have encrypted passwords, AuthBy UNIX
can not work with CHAP or MSCHAP authentication.
Radiator RADIUS Server

107 of 397

Configuration

For performance reasons, AuthBy UNIX opens and reads the password and group files
at start-up, reinitialization and whenever the file modification times change, (i.e. they
are cached within Radiator). Since these files are cached in memory, large password
files can require large amounts of memory. If you set the Nocache parameter, the files
will be reread for every authentication, and will not be cached internally (this can be
slow if you have a large password or group files, and should rarely be necessary).
It is not necessary to be running on a Unix host in order to use AuthBy UNIX. It will
work equally well on Windows and NT, but you are probably less likely to need it there.
By using the Match parameter you can also specify other file formats if you need to.
When attempting to authenticate a user, AuthBy UNIX will encrypt the password from
the user and compare it to the one in the password file. If the encrypted passwords
match, AuthBy UNIX will reply with an Access-Accept message. If the user does not
appear in the password file, an Access-Reject message is sent to the client. AuthBy
UNIX caches the password file and group file internally, and rereads the files when the
modification time changes. If the Nocache parameter is set the password and group files
will be reread for every authentication.
It is important to note that on its own, AuthBy UNIX does not implement check or reply
items, and therefore can only be used for Authenticate only applications. However,
you can use it in conjunction with another AuthBy module that does use check and reply
items: see the Auth-Type check item in Section 13.0 on page 333. If you do this, you
can also use the Group check item, which will check whether the user is a member of a
group defined in the GroupFilename file.
Hint: You can use AddToReply (see Section 5.21.8 on page 85) to easily add standard
reply items to all users authenticated by <AuthBy UNIX>.
AuthBy UNIX understands the following parameters as well as those described in
Section 5.21 on page 82:
5.28.1 Filename

Specifies the filename of the password file. Defaults to /etc/passwd. The file name
can include special formatting characters as described in Section 5.2 on page 20.
Hint: On systems with shadow password files, such as Solaris, Filename can name the
shadow file. In order to support this, Radiator must have permission to read the shadow
file (this usually means it must run as root).
# password file is in /usr/local/etc/local_passwd
Filename /usr/local/etc/local_passwd
5.28.2 Match

This parameter allows you to use flat files with different formats to the standard Unix
password format. Match is a regular expression that is expected to match and extract the
username, password and (optional) primary group ID fields from each line in the password file. The default extracts the first two colon separated fields as username and pass-

108 of 397

Radiator RADIUS Server

Configuration

word, followed by a UID, followed by an (optional) primary group ID (i.e. standard

Unix password file format).
# fields are separated by vertical bar |
Match ^([^\|]*)\|([^\|]*)

Hint. The default Match expression is:

Match ^([^:]*):([^:]*):?[^:]*:?([^:]*)
5.28.3 GroupFilename

Specifies the name of the group file. The group file is in standard Unix group file format. Used to check Group= check items when authentication is cascaded from
another module. Defaults to /etc/group.
# group file is in /usr/local/etc/local_group
GroupFilename /usr/local/etc/local_group
5.28.4 Nocache

Disables caching of the password and group files, and forces them to be reread for every
Authentication. If not set, AuthBy UNIX will only reread the files when their modification time changes. Dont use this parameter unless you have to, because it can be very
slow for any more than 1000 users or so.
# Dont cache so we can do some simple testing
# without restarting the server all the time
Nocache

5.29 <AuthBy EXTERNAL>

AuthBy EXTERNAL passes all requests to an external program, which is responsible
for determining how to handle the request. It is implemented in AuthEXTERNAL.pm.
When the external command is run, all the attributes in the request will be formatted and
passed to its standard input (stdin), one per line, in the format:
<tab>

Attribute-Name = attribute_value

Each line output by the command on stdout is interpreted as a list of comma separated
attribute-value pairs in the format:
Attribute-Name = attribute_value

and are returned in the reply message (if any). Any output lines that cant be interpreted
in that form are put in a Reply-Message attribute and returned in the reply message (if
any). (This last behavior is for backwards compatibility only and will not be supported
indefinitely).
The exit status of the external command determines what type of reply is to be sent in
response to the request:

0 Means reply with an acceptance. For Access-Requests, an Access-Accept will be

sent. For Accounting-Requests, an Accounting-Response will be sent.

Radiator RADIUS Server

109 of 397

Configuration

1 Means reply with a rejection. For Access-Requests, an Access-Reject is sent. For

Accounting-Requests, no response is sent.

2 Means dont send any reply. This will also make the Realm fall through to the next
AuthBy module if you specified more than one for this Realm (but see also AuthByPolicy).

3 Means reply with an Access-Challenge for Access-Request. For AccountingRequests, no response is sent.

Any other value. No reply is sent, and no further action is taken.

AuthBy EXTERNAL will wait for the external process to complete before handling
more requests, so you should use this carefully, and avoid using long-running commands. If you cant avoid long-running EXTERNAL commands, you can use the Fork
parameter to force AuthBy EXTERNAL to fork before calling the external command.
This may improve performance.
NOTE: AuthBy EXTERNAL is not available on Windows 98. It works fine on later
versions of Windows, Linux and Unix.
AuthBy EXTERNAL understands the following parameters as well as those described
in Section 5.21 on page 82:
5.29.1 Command

Specifies the command to run. The command can include special formatting characters
as described in Section 5.2 on page 20. There is no default, and a Command must be
specified. See above for details of how stdin, stdout and exit status are interpreted.
# Interface to an external system
Command /usr/local/bin/doReq %T
5.29.2 DecryptPassword

This optional parameter makes AuthBy EXTERNAL decrypt the User-Password attribute before passing it to the external program. If you dont specify this, User-Password
will be passed exactly as received in the request (i.e. encrypted by MD5 according to the
RADIUS standard).
This is not able to decrypt CHAP or MSCHAP passwords.
# Pass plaintext passwords to the external program
DecryptPassword
5.29.3 ResultInOutput

If this optional parameter is set, AuthBy EXTERNAL will determine the type of the
reply from the first line of the stdout output of the external program, rather than the exit
code of the external program.
The following codes are recognized:

ACCEPT
Reply with an Access-Accept.

REJECT
110 of 397

Radiator RADIUS Server

Configuration

Reply with an Access-Reject

IGNORE
Do not reply.

CHALLENGE
Reply with an Access-Challenge

REJECT_IMMEDIATE
Reply with an Access-Reject, and do not consider any other DEFAULT users in a
chained Auth-Type request.
5.30 <AuthBy SQL>
AuthBy SQL authenticates users from an SQL database, and stores accounting records
to an SQL database. It is implemented in AuthSQL.pm. AuthBy SQL is very powerful
and configurable, and has many parameters in order to customize its behaviour, so
please bear with us. You will need to have some familiarity with SQL and relational
databases in order to configure and use AuthBy SQL.
AuthBy SQL uses the Perl DBI/DBD interface to connect to your database. You can
therefore use AuthBy SQL with a large number of commercial and free SQL database
systems. In order to use SQL, you will need to install your database software, install the
matching Perl DBD module, and install the Perl DBI module before AuthBy SQL will
work. This may seem a lot of work, but it is worth it for the scalability and flexibility it
can give you. Dont be put off by the fact that large SQL databases cost a lot of money:
there are a number of suitable SQL databases that can be bought for a few hundred dollars or less, and in some cases for free.
When AuthBy SQL receives an Access-Request message, it tries to find a password and
check and reply items for the user in a database table (you can change this behavior with
the AuthColumnDef parameter). Radiator constructs an SQL select statement from the
AuthSelect parameter. By changing AuthSelect, you can control the table it looks in,
and the names of the columns for the password, check and reply columns. If a user is
found, all the check items (if any) are compared with the attributes in the request,
including Expiration in the format Dec 08 1998.
If all the check items are satisfied by the attributes in the request, AuthBy SQL will
reply with an Access-Accept message containing all the attributes in the reply items (if
any). If the user does not appear in the database, or if any check attribute does not
match, an Access-Reject message is sent to the client.
If your AuthSelect statement does not generate a simple password, check items, reply
items result, you can tell Radiator how to interpret the columns in the result with the
AuthColumnDef parameter. If you dont specify any AuthColumnDef parameters, Radiator will assume that AuthSelect returns password, check items, reply items in that
order.
When AuthBy SQL receives an Accounting-Request message, it can store any number
of the attributes from the request in an SQL table. You can control the table it stores in,
and the names of the columns where the attributes are stored, and the attribute that is

Radiator RADIUS Server

111 of 397

Configuration

stored there. To enable SQL accounting you must define AccountingTable and you must
define at least one AcctColumnDef. If you dont do both of these AuthBy SQL will
acknowledge Accounting-Request message but will not store them anywhere. The
example goodies/sql.cfg in the Radiator distribution shows a typical setup that
will work with the table schemas in the goodies directory.
Some example scripts for constructing database tables for various RDBMSs can be
found in the goodies directory in the Radiator distribution. You should regard these as a
starting point for constructing large scalable user and accounting databases.
The AuthBy SQL parameters DBSource, DBUsername and DBAuth are passed to DBI
something like this:
DBI->connect(DBSource, DBUsername, DBAuth)

DBSource should be a new-style database specification something like dbi:drivername:..., but exact meaning of these variables depends on the Perl DBD driver
you wish to use. See Section 24.0 on page 388 for more details and examples on the
syntax of DBSource, DBUsername and DBAuth for different database vendors.
You can specify multiple databases by using multiple DBSource, DBUsername and
DBAuth parameters. Whenever Radiator tries to connect to a database, SQL will try to
connect to the first DBSource listed, using the first DBUsername and DBAuth parameters. If that connection fails, it will try the second, third etc., until all the databases are
exhausted, and finally gives up without replying to the NAS. This gives your NAS the
opportunity to fall back to another RADIUS server if all your SQL databases are down.
AuthBy SQL is tolerant of database failures. If your database server goes down, Radiator will try to reconnect to a database as described above, starting again at the first database you specified. Whichever database Radiator connects to, it will stay connected to it
until that database becomes unreachable, at which time it will again search for a database, starting at the first again. If, on the other hand Radiator is not able to connect to
any SQL server, it will return an IGNORE, which will cause Radiator to ignore (i.e. not
acknowledge) the request. This will cause most NASs to fall back to a secondary
RADIUS server.
Hint: When you make an SQL database part of your operation, you will find that it will
sometimes need maintenance. Make sure you have someone who is knowledgeable
about installing, configuring, maintaining and backing up your SQL database.
Hint: An SQL database server can use a significant number of CPU cycles and can
become a performance bottleneck. Doing a simple lookup on, say, a user/password database with a simple index on the username is usually very quick, in the order of milliseconds per lookup, even if the table has millions of rows. However, an insert into a large
accounting table with a complicated index can be very slow. Make sure you understand
how to design and tune your database tables, otherwise it could have a significant effect
on AuthBy SQL performance.
AuthBy SQL understands the following parameters as well as those described in
Section 5.21 on page 82:

112 of 397

Radiator RADIUS Server

Configuration

5.30.1 DBSource

This parameter is used by Perl DBI to specify the database driver and database system
to connect to. It will usually begin with dbi:drivername:. There is no standard for
the text following the driver name. You will have to consult the details for your DBD
driver. You can use any of the special characters described in Section 5.2 on page 20.
Some examples are given below
# Connect to mSQL database called radius on localhost, standard
# port
DBSource dbi:mSQL:radius
# Or... Connect to the Oracle sid called users
DBSource dbi:Oracle:users
# Or... Connect to mysql database called radius on localhost,
# standard port
DBSource dbi:mysql:radius

Hint: for some applications, it may be useful to use a GlobalVar to specify the name of
the SQL database. That way your Radiator can be parameterized from the command
line:
DBSource dbi:mSQL:%{GlobalVar:databasename}
radiusd -config_file xxx.cfg databasename=radius
5.30.2 DBUsername

For most database types, this specifies the username to log in to the database. For some
databases, this has a different meaning. For example, for mSQL its the name of the database to connect to. You can use any of the special characters described in Section 5.2 on
page 20.
# For mSQL, its ignored
DBUsername ignored
# For Oracle, its the name of the Oracle user to
# log in as
DBUsername scott
5.30.3 DBAuth

Usually used by Perl DBI to specify the password for the user specified in DBUsername. For some database, this has a different meaning. For example for mSQL and
mysql, its not used at all, and can be ignored. You can use any of the special characters
described in Section 5.2 on page 20.
# For mSQL, its ignored
DBAuth any old rubbish
# For Oracle, its Oracle password for DBUsername
DBAuth tiger
5.30.4 Timeout

This optional parameter specifies a timeout interval in seconds that Radiator will wait
for when trying to contact the SQL server specified by DBAuth. If the server does not
respond within the Timeout period, Radiator will consider the SQL server to be failed,
and will stop trying to contact the SQL server until the FailureBackoffTime is expired.
Defaults to 60 seconds. Setting Timeout to 0 will prevent any timeouts being imple-

Radiator RADIUS Server

113 of 397

Configuration

mented, and Radiator will rely on the underlying implementation to timeout any SQL
operations.
Note: Timeout is not supported on ActiveState Perl for Win32. On Windows platforms,
the timeout will usually be determined by the TCP timeouts built in to your Windows
TCP stack.
Hint: You should set Timeout to 0 If you are using Sybase ODBC libraries.
5.30.5 FailureBackoffTime

If Radiator detects an SQL server failure, it will wait for this number of seconds before
trying to contact the SQL server again. Defaults to 600 seconds (10 minutes).
5.30.6 SQLRetries

If Radiator detects certain SQL errors while running a query, it will reconnect and retry
until it has tried SQLRetries times, then declares an SQL server failure. Defaults to 2.
Applies to SQL errors other than primary key violations, or Oracle error ORA-00001.
Caution: If SQLRetries is set to 0, no connection will be made and no queries will be
executed.
5.30.7 RoundRobinOnFailure

This optional flag can help with some types of overloaded database that can be connected but then time out when a query is sent. It causes the next database in the
DBSource list to be tried next instead of the first one.
5.30.8 AuthSelect

This is an SQL select statement that will be used to find and fetch the password and possibly check items and reply items for the user who is attempting to log in. You can use
the special formatting characters. %0 (thats a zero) is replaced with the quoted and
escaped user name. The first column returned is expected to be the password; the second
is the check items (if any) and the third is the reply items (if any) (you can change this
expectation with the AuthColumnDef parameter). Defaults to select PASSWORD
from SUBSCRIBERS where USERNAME=%0, which does not return any check or
reply items. You can make arbitrarily complicated SQL statements so that you will only
authenticate users for example whose account status is OK or who have not exceeded
their download limit etc. See Section 13.0 on page 333 for information on how check
items and reply items are used. If the password (or encrypted password) column for a
user is NULL in the database, then any password will be accepted for that user.
The password column may be in any of the formats described in Section 13.1.1 on
page 334.
# Check user status is current. No reply items in DB
# Note: The entire statement must be on one line
AuthSelect select PW, CHECK from USERS where\
NAME=%0 and STATUS = 1

If AuthSelect is defined as an empty string, SQL will not attempt to authenticate at all.

114 of 397

Radiator RADIUS Server

Configuration

If one or more AuthSelectParam parameters are specified, they will be used in order to
replace any fields marked with a question mark (?) in AuthSelect.
Hint: By default, many SQL servers do case-insensitive string comparison. This means
that AuthBy SQL, AuthBy RADMIN etc. would match, for example mikem, MIKEM
and MiKeM as being the same user. Some SQL databases allow you to force case-sensitive comparisons. For example, In the case of MySQL, the BINARY keyword forces
the following comparison to be case-sensitive. Therefore you could force case-sensitive
user names in an AuthSQL for MySQL with something like:
AuthSelect select PASSWORD from SUBSCRIBERS \
where BINARY USERNAME=%0

Hint: You can improve the performance of AuthSelect queries executed by the SQL
server with AuthSelectParam.
Note: in the event of a SQL timeout, Radiator will reconnect to the database and the
AuthSelect query will be tried again. This means there may be up to 2 Timeout intervals
before the entire AuthSelect query fails.
5.30.9 AuthSelectParam

This optional parameter specifies a bind variable to be used with AuthSelect. See
Section 5.4 on page 25 for information about how to use bind variables.
5.30.10 AuthColumnDef

This optional parameter allows you to change the way Radiator interprets the result of
the AuthSelect statement. If you dont specify any AuthColumnDef parameters, Radiator will assume that the first column returned is the password; the second is the check
items (if any) and the third is the reply items (if any). If you specify any AuthColumnDef parameters, Radiator will use the column definitions you provide.
You can specify any number of AuthColumnDef parameters, one for each interesting
field returned by AuthSelect. The general format is:
AuthColumnDef n, attributename, type[, formatted]

n is the index of the field in the result of AuthSelect. 0 is the first field.
attributename is the name of the attribute to be checked or replied. The value of the
attribute is in the nth field of the result. The special attributename GENERIC indicates that it is a list of comma separated attribute=value pairs.

type indicates whether it is a check or reply item. A type of request sets the named
attribute in the incoming request, from where it can be retrieved later in the authentication process with special formatting characters.

formatted If this keyword is present, the value retrieved from the database will be
subject to special character processing before its value is used, and can therefore
contain %{something} forms which will be replaced at authentication time.
A few examples are in order:
Example 1

Radiator RADIUS Server

115 of 397

Configuration

The standard default AuthSelect statement:

AuthSelect select PASSWORD from SUBSCRIBERS \
where USERNAME=%0

returns a single plaintext password check item. The result could be interpreted with:
AuthColumnDef 0, User-Password, check

Example 2
A more complicated AuthSelect statement:
AuthSelect select PASSWORD, CHECKATTR, REPLYATTR \
from SUBSCRIBERS \
where USERNAME=%0

returns 3 fields in the result. The first is a plaintext password, the second is a string of
check items like Service-Type=Framed-User, Expiration="Feb 2 1999", and the third
field is a string of reply items like Framed-Protocol=PPP,Framed-IP-Netmask =
255.255.255.0,.... . The result could be interpreted with:
AuthColumnDef 0, User-Password, check
AuthColumnDef 1, GENERIC, check
AuthColumnDef 2, GENERIC, reply

Hint: this has the same effect as the default rule that Radiator applies if no AuthColumnDef parameters are specified at all.
Hint: if your PASSWORD column contains a Unix encrypted password and you are
using AuthColumnDef, you will need to set it like this:
AuthColumnDef 0, Encrypted-Password, check

Example 3
This AuthSelect statement:
AuthSelect select SERVICE, PASSWORD, MAXTIME
from SUBSCRIBERS \
where USERNAME=%0

returns 3 fields in the result. The first is a Service-Type to check, the next is a plaintext
password and the last is the number of seconds to send back in Session-Timeout. The
result could be interpreted with:
AuthColumnDef 0, Service-Type, check, formatted
AuthColumnDef 1, User-Password, check
AuthColumnDef 2, Session-Timeout, reply

In this example, column 0 will be interpreted for special characters before being used as
a check item for the Service-Type parameter.

116 of 397

Radiator RADIUS Server

Configuration

5.30.11 AccountingTable

This is the name of the table that will be used to store accounting records. Defaults to
ACCOUNTING. If AccountingTable is defined to be an empty string, all accounting
requests will be accepted and acknowledged, but no accounting data will be stored. You
must also define at least one AcctColumnDef before accounting data will be stored.
The AccountingTable table name can contain special formatting characters: table names
based on the current year and/or month might be useful, so you can rotate your accounting tables.
# store accounting records in RADUSAGEyyyymm table
AccountingTable RADUSAGE%Y%m
5.30.12 EncryptedPassword

This parameter should be set if and only if your AuthSelect statement will return a bare
Unix encrypted password, and you are not using AuthColumnDef. Encrypted passwords
cannot be used with CHAP or MSCHAP authentication. If the encrypted password column for a user is NULL in the database, then any password will be accepted for that
user. If the encrypted password column for a user is set to the empty string (as opposed
to NULL), then no password will be accepted for that user.
EncryptedPassword is a hint to Radiator about how to deal with passwords that have no
explicit password type prefix. If EncryptedPassword is not set, bare passwords (i.e.
without a {xxx} prefix) are treated as plaintext passwords. If EncryptedPassword is set,
they are treated as a Unix crypt password. If a password has a {xxx} prefix as described
in Section 13.1.1 on page 334, then the password will be interpreted according to that
type of password, independent of the setting of EncryptedPassword.
Hint: This parameter is ignored if you have defined your own AuthSelect column definitions with AuthColumnDef.
# unix Encrypted password are in CRYPTPW
AuthSelect select CRYPTPW from USERS where N = %0
EncryptedPassword
5.30.13 HandleAcctStatusTypes

This optional parameter specifies a list of Acct-Status-Types that will be processed in

Accounting requests. The value is a comma-separated list of valid Acct-Status-Type
attribute values (see your dictionary for a full list) including, Start, Stop, Alive, ModemStart, Modem-Stop, Cancel, Accounting-On, Accounting-Off etc.
If HandleAcctStatusTypes is specified and an Accounting request has an Acct-StatusType not mentioned in HandleAcctStatusTypes, then the request will be ACCEPTed but
not inserted or handled with AcctSQLStatement. The default is to handle all Acct-Status-Types.
# Only insert Start and Stop requests, ack everything else
HandleAcctStatusTypes Start,Stop

Radiator RADIUS Server

117 of 397

Configuration

5.30.14 AccountingStartsOnly

If this parameter is defined, it forces AuthBy SQL to only log Accounting Start requests
to the database. All other Accounting requests are accepted and acknowledged, but are
not stored in the SQL database.
Note: this parameter is now deprecated and will not be supported in the future. Use HandleAcctStatusTypes (see Section 5.30.13 on page 117) instead.
Hint: It does not make sense to set AccountingStartsOnly and AccountingStopsOnly.
5.30.15 AccountingAlivesOnly

If this parameter is defined, it forces AuthBy SQL to only log Accounting Alive
requests to the database. All other Accounting requests are accepted and acknowledged,
but are not stored in the SQL database.
Note: this parameter is now deprecated and will not be supported in the future. Use HandleAcctStatusTypes (see Section 5.30.13 on page 117) instead.
5.30.16 AccountingStopsOnly

If this parameter is defined, it forces AuthBy SQL to only log Accounting Stop requests
to the database. All other Accounting requests are accepted and acknowledged, but are
not stored in the SQL database.
Note: this parameter is now deprecated and will not be supported in the future. Use HandleAcctStatusTypes (see Section 5.30.13 on page 117) instead.
You may want to use this parameter if your accounting system does not use or need
Accounting Start to do its billing.
# We only want Stops
AccountingStopsOnly

Hint: It does not make sense to set AccountingStartsOnly and AccountingStopsOnly.

5.30.17 AcctColumnDef

AcctColumnDef is used to define which attributes in accounting requests are to be

inserted into AccountingTable, and it also specifies which column they are to be
inserted into, and optionally the data type of that column. The general form is
AcctColumnDef Column,Attribute[,Type][,Format]

Column is the name of the SQL column where the data will be inserted. Attribute is the
name of the RADIUS attribute to store there. Type is an optional data type specifier,
which specifies the data type of the SQL column. Format is an optional format string
that may be used to format the value. Columns and their values will be included in
accounting SQL statements in alphabetical order by column name.
The following types are recognized:

integer

118 of 397

Radiator RADIUS Server

Configuration

The insertion will be done as an integer data type. RADIUS attributes that have
VALUE names defined will be inserted as their integer RADIUS value.

integer-date
The attribute value will be converted from Unix seconds to an SQL datetime string
using the date formatting characters described in Date Formatting on page 24. The
Format field will be used as the date format (if it is present) otherwise the standard
DateFormat parameter for this AuthBy SQL will be used (which defaults to the format Sep 3, 1995 13:37). This is useful for inserting the Timestamp attribute as an
SQL datetime type. The default is compatible with at least MySQL, Microsoft SQL
and Sybase datetime columns. If it is not suitable for your database, consider defining your own DateFormat parameter for this AuthBy SQL.

formatted-date
Note: formatted-date is now deprecated, and new installations should use integerdate instead. It has a much wider range of formatting and date options.
The attribute will be converted by Date::Format according to the format string. You
must install the Perl TimeDate package from CPAN for this to work. It is most useful
for SQL databases with unusual date formats, like Oracle. formatted-date is now
only provided for historical reasons, and new installations should probably use integer-date in conjunction with DateFormat instead.

formatted
The attribute field will be processed looking for the special characters described in
Special characters on page 20. If the resulting string is empty it will not be
inserted. This can be useful for inserting data from other places besides the current
request, such as a GlobalVar you have defined elsewhere, or perhaps from a data
item that a previous AuthBy put in the current reply packet. The resulting data will
be quoted. See literal to generate unquoted data

literal
Similar to formatted, except that the resulting field will not be quoted.

inet_aton
Converts a dotted quad IP address (such as 10.1.1.5) to a 32 bit unsigned integer.

-anything elseAny other type string will cause the named RADIUS attribute to be inserted literally
as a string. Quotes and other control characters will be automatically escaped to suit
your database.
You can use formatted-date to create date formats to suit your SQL database. For example, this will insert the Timestamp into an Oracle date type column called TIME_STAMP:
AcctColumnDefTIME_STAMP,Timestamp,formatted-date,to_date\
(%e %m %Y %H:%M:%S, DD MM YYYY HH24:MI:SS)

This will result in a an insert statement something like this:

insert into ACCOUNTING(TIME_STAMP, ......) values
(to_date(16 02 1999 16:40:02, DD MM YYYY HH24:MI:SS), ....)

Radiator RADIUS Server

119 of 397

Configuration

For types other than formatted-date and integer-date, the format field can be used to
build custom values in your insert statement. This can be very useful to call SQL conversion functions on your data. If you specify a format, it will be used as a sprintf-style
format, where %s will be replaced by your value.
If any named attribute is not present in the accounting request, nothing will be inserted
in the column for that value. The attribute will not appear in the insert statement at all,
and the SQL servers default value (usually NULL) will be used for that column. With
some SQL servers, you can change the default value to be used when a column is not
specified in an insert statement.
You can have 0 or more AcctColumnDef lines, one for each attribute you want to store
in the accounting table. If there are no AcctColumnDef lines, then the accounting table
will never be updated.
The attribute Timestamp is always available for insertion, and is set to the time the
packet was received, adjusted by Acct-Delay-Time (if present), as an integer number of
seconds since Midnight Jan 1 1970 UTC. The Timestamp attribute is added by Radiator
to all received Accounting requests, and is set to the current time according to the host
on which the Radiator is running.
Here is an example column configuration:
AcctColumnDef
AcctColumnDef
AcctColumnDef
AcctColumnDef
AcctColumnDef
AcctColumnDef

USERNAME,User-Name
TIME_STAMP,Timestamp,integer
ACCTSTATUSTYPE,Acct-Status-Type
ACCTDELAYTIME,Acct-Delay-Time,integer
ACCTINPUTOCT,Acct-Input-Octets,integer
ACCTOUTPUTOCT,Acct-Output-Octets,inte-

AcctColumnDef
AcctColumnDef
AcctColumnDef
AcctColumnDef
AcctColumnDef

ACCTSESSIONID,Acct-Session-Id
ACCTSESSTIME,Acct-Session-Time,integer
ACCTTERMINATECAUSE,Acct_Terminate-Cause
NASIDENTIFIER,NAS-Identifier
NASPORT,NAS-Port,integer

ger

Hint: If your accounting table inserts arent working, run Radiator at a trace level of 4,
and you will see each insert statement logged before it is executed. This will help you
determine if your AcctColumnDef lines are correct.
Hint: If there are multiple definitions for the same column with non-null values, the last
one in the configuration file will be used.
Hint: SQL table and column names are generally case sensitive, and usually can consist
only of letters, digits or the underscore character _.
Hint: You can further customize the accounting insert query with AcctInsertQuery.
Hint: The formatted type is useful for inserting values set up in GlobalVars, or to get
values from the current reply (possibly put there by a preceding AuthBy).

120 of 397

Radiator RADIUS Server

Configuration

AcctColumnDef ACCOUNTTYPE,%{Reply:accounttype},formatted
AcctColumnDef SERVERNAME,%{GlobalVar:servername},formatted

Hint: You could get SQL to calculate the start time of an accounting packet with something like:
AcctColumnDef START_TIME,%b-0%{Acct-Session-Time},literal
5.30.18 AuthSQLStatement

This parameter allows you to execute arbitrary SQL statements each time an authentication request is received, but before authentication is done.
You can have as many AuthSQLStatement parameters as you like (i.e. 0 or more). Each
one will have its special formatting macros replaced at run time (the ones of the format
%{attribute-name} are probably the most useful). They are executed in the order they
appear in the configuration file, before AuthSelect is run. They are run even if AuthSelect is empty.
5.30.19 AcctSQLStatement

This parameter allows you to execute arbitrary SQL statements each time an accounting
request is received. You might want to do it to handle processing in addition to the normal inserts defined by AcctColumnDef, or you might want to construct a much more
complicated SQL statement than AcctColumnDef can handle. You only need this if the
accounting definitions provided by AcctColumnDef are not powerful enough.
You can have as many AcctSQLStatement parameters as you like (i.e. 0 or more). Each
one will have its special formatting macros replaced at run time (the ones of the format
%{attribute-name} are probably the most useful). They are executed in the order they
appear in the configuration file.
AcctSQLStatement delete from ONLINE where \
SessionID=%{Acct-Session-Id}

Hint: By having multiple AuthBy SQL clauses, and by using AccountingStartsOnly and
AccountingStopsOnly, in conjunction with AcctSQLStatement, you could implement a
who is online table.
5.30.20 AcctInsertQuery

This optional parameter allows you to customize the exact form of the insert query used
to insert accounting data. Any of the characters defined in Table 2 on page 24 are permitted. %0 is replaced with the value of the AccountingTable parameter. %1 is replaced
with the comma separated list of column names to be inserted (derived from AcctColumnDef), and %2 is replaced by the data values to be inserted for each column in the
same order as %1. The columns and values will be in alphabetical order by column
name. The default is insert into %0 (%1) values (%2).
You can use this to use special features in your SQL server, such as this for MySQL:
# maybe update if this is a duplicate
AcctInsertQuery update or insert into %0 (%1) values (%2)

Radiator RADIUS Server

121 of 397

Configuration

5.30.21 DateFormat

This optional parameter specifies the format to be used to format dates for insertion into
the AccountingTable. Any of the characters defined in Table 2 on page 24 are permitted.
Defaults to %b %e, %Y %H:%M (e.g. Sep 3, 1995 13:37).
# Include seconds in dates in a way that MS-SQL likes
DateFormat %b %e, %Y %H:%M:%S
5.30.22 AcctFailedLogFileName

The name of a file used to log failed Accounting-Request messages in the standard
radius accounting log format. If the SQL database insert fails, the accounting message
will be logged to the named file. The log file format is described in Section 15.5 on
page 360. If no AcctFailedLogFileName is defined, failed accounting messages will not
be logged. The default is no logging. The file name can include special formatting characters as described in Section 5.2 on page 20, which means that using the %C, %c and
%R specifiers, you can maintain separate accounting log files for each Realm or Client
or a combination. The AcctFailedLogFileName file is always opened written and closed
for each failed insertion, so you can safely rotate it at any time.
The username that is recorded in the log file is the rewritten user name when
RewriteUsername is enabled.
Hint: You can change the logging format with AcctLogFileFormat.
Hint: You may want to make the filename depend on the date, so you get one missed
accounting file per day.
# Log all accounting to a single log file in LogDir
AcctFailedLogFileName %L/misseddetails
5.30.23 AcctLogFileFormat

This optional parameter is used to alter the format of the failed accounting log file from
the standard radius format when AcctLogFileFormatHook is not defined. AcctLogFileFormat is a string containing special formatting characters. It specifies the format
for each line to be printed to the accounting log file. A newline will be automatically
appended. It is most useful if you use the %{attribute} style of formatting characters (to
print the value of the attributes in the current packet.
AcctLogFileFormat %{Timestamp} %{Acct-Session-Id}\
%{User-Name}
5.30.24 AcctLogFileFormatHook

Specifies an optional Perl hook that will is used to alter the format of the failed accounting log file from the standard radius format when defined. The hook must return the formatted accounting record. A newline will be automatically appended. By default no
hook is defined and AcctLogFileFormat or the default format are used. The hook
parameter is the reference to the current request.
5.30.25 SQLRecoveryFile

Caution: This feature is known not to work as expected with some types of database. Its
use is deprecated: you are strongly discouraged from using this feature. Support for it
may be removed in future versions.
122 of 397

Radiator RADIUS Server

Configuration

This optional parameter specifies the name of a file where any failed SQL do queries
will be logged, perhaps for later recovery. The default is no logging. The SQLRecoveryFile file is always opened written and closed for each failed SQL do query, so you can
safely rotate it at any time.
Hint: You may want to make the filename depend on the date, so you get one missed
accounting file per day.
# Log all failed SQL queries to a log file per day
SQLRecoveryFile %L/sqlfailures
5.30.26 ConnectionHook

This optional parameter specifies a Hook that will be run every time this clause (re)connects to the SQL database. This is most useful for executing func() to configure the
database connection in customized ways. The hook is called with 2 arguments. The first
is a reference to the clause object that is making the connection. The second argument is
the DBH handle to the newly connected database.
In the following example, the hook calls DBI func() to configure an Interbase database
connection for custom requirements:
ConnectionHook sub {$_[1]->func(-access_mode => read_write,\
-isolation_level => read_committed,\
-lock_resolution => wait,\
ib_set_tx_param)}
5.30.27 ConnectionAttemptFailedHook

You can run a hook whenever Radiator attempts to connect to an SQL database and fails
to connect. The default just logs the failure. The hook is called like hook($object,
$dbsource, $dbusername, $dbauth). $object is the SqlDb object that is doing the connecting, and the other parameters are the currently used values for DBSource, DBUsername and DBAuth.
ConnectionAttemptFailedHook sub { }
5.30.28 NoConnectionsHook

You can run a hook whenever Radiator fails connect to any SQL server. The default just
logs the failure. The hook is called like hook($object). $object is the SqlDb object that is
doing the connecting.
NoConnectionsHook sub { }
5.30.29 PostAuthSelectHook

This optional parameter allows you to define a Perl function that will be run during the
authentication process. The hook will be called after the AuthSelect results have been
received, and before Radiator has processed the attributes it is interested in.
The first argument passed to the hook is a handle to the current AuthBy SQL object. The
second argument is the name of the user being authenticated. The third argument is a
pointer to the current request. The fourth argument is a pointer to the User object being
constructed to hold the check and reply items for the user being authenticated. The fifth
argument ($_[4]) is a reference to the @row resulting from AuthSelect.

Radiator RADIUS Server

123 of 397

Configuration

# Change the flag in the first field to Accept or Reject

PostAuthSelectHook sub{my($self,$name,$p,$user,$row)=@_;\
my $flag = $row->[0];\
$row->[0] = $flag ? Reject:Accept;\
}
5.30.30 GroupMembershipQuery

This optional parameter defines an SQL query which will be used to determine whether
a user is a member of a group in order to implement the Group check item. Special characters are supported. %0 is replaced by the user name being checked. %1 is replaced by
the group name being checked. You can use bound variables with GroupMembershipQueryParam. GroupMembershipQuery is expected to return a single row, where the
first field is the name of the group the user belongs to.
5.30.31 GroupMembershipQueryParam

You can also use GroupMembershipQueryParam to provide bound variables for GroupMembershipQuery. %0 is replaced by the user name being checked. %1 is replaced by
the group name being checked.
5.30.32 AcctTotalQuery

This optional parameter defines an SQL query which will be used to determine the total
of all session times for a given user. Special characters are supported. %0 is replaced by
the user name being checked. It is expected to return a single field containing the total
session time in seconds.
It is used to get a count for the following check items:

Max-All-Session
SELECT SUM(AcctSessionTime) FROM radacct WHERE UserName=%0
5.30.33 AcctTotalSinceQuery

This optional parameter defines an SQL query which will be used to determine the total
of session times from a certain time until now for a given user. Special characters are
supported. %0 is replaced by the user name being checked. %1 is replaced by the Unix
epoch time in seconds in the start time of the query. It is expected to return a single field
containing the total session time in seconds.
It is used to get a count for the following check items:

Max-Hourly-Session
Max-Daily-Session
Max-Monthly-Session
5.30.34 AcctTotalOctetsSinceQuery

This optional parameter defines an SQL query which will be used to determine the total
of octets from a certain time until now for a given user. Special characters are supported.
%0 is replaced by the user name being checked. %1 is replaced by the Unix epoch time
in seconds of the start time of the query. It is expected to return a single field containing
the total octets.

124 of 397

Radiator RADIUS Server

Configuration

It is used to get a count for the following check items:

Max-Hourly-Octets
Max-Daily-Octets
Max-Monthly-Octets
5.30.35 AcctTotalOctetsQuery

This optional parameter defines an SQL query which will be used to determine the total
of octets for a given user. Special characters are supported. %0 is replaced by the user
name being checked. It is expected to return a single field containing the total octets.
It is used to get a count for the following check items:

Max-All-Octets
5.30.36 AcctTotalGigawordsSinceQuery

This optional parameter defines an SQL query which will be used to determine the total
of gigawords from a certain time until now for a given user. Special characters are supported. %0 is replaced by the user name being checked. %1 is replaced by the Unix
epoch time in seconds of the start time of the query. It is expected to return a single field
containing the total gigawords.
It is used to get a count for the following check items:

Max-Hourly-Gigawords
Max-Daily-Gigawords
Max-Monthly-Gigawords
5.30.37 AcctTotalGigawordsQuery

This optional parameter defines an SQL query which will be used to determine the total
of gigawords for a given user. Special characters are supported. %0 is replaced by the
user name being checked. It is expected to return a single field containing the total
gigawords.
It is used to get a count for the following check items:

Max-All-Gigawords
5.30.38 NullPasswordMatchesAny

Normally, a NULL password in the SQL table will match any submitted password. By
disabling this option, NULL passwords will not match any submitted password, causing
every authentication request for that user to be REJECTed.
5.31 <AuthBy RADIUS>
AuthBy RADIUS forwards all authentication and accounting requests for this Realm to
another (possibly remote) RADIUS server. This is often called proxying. It is implemented in AuthRADIUS.pm. If and when the remote radius server replies to us, we
will forward the reply back to the client that originally sent the request to us.

Radiator RADIUS Server

125 of 397

Configuration

This allows Radiator to act as a proxy RADIUS server, possibly running on the firewall
of your organization. You can also use it to set up roaming realms, or to make your
radius server act as a multiplexer for multiple realms. You can forward certain realms to
other servers within your organization in order to improve performance or redundancy.
You can arrange to forward to primary/secondary radius server pairs by specifying multiple Host lines. The normal behavior is to try to forward to the remote hosts in the order
the hosts are listed in the configuration file. This means that it will initially try to forward a request to the first host listed (unless that host was marked as failed recently). If
no reply is received from the first host (after Retries), it will be marked as failed for
FailureBackoffTime seconds, and the request will be forwarded to the next Host in the
list. This continues until a reply is received, or until; all the Hosts are exhausted. The
result is that if a primary remote server fails, the secondary will take over. After FailureBackoffTime seconds, the primary will be tried again. You can change this behavior by
choosing other load balancing versions of AuthBy RADIUS such as <AuthBy ROUNDROBIN> <AuthBy VOLUMEBALANCE> or <AuthBy LOADBALANCE> (see
Section 5.46 on page 175) instead of <AuthBy RADIUS>.
Important Note: Normally, an AuthBy RADIUS clause will complete as soon as the
request has been forwarded to the remote radius server. It will not wait for a reply before
moving on to other AuthBy clauses, or handling new requests. AuthBy RADIUS always
returns IGNORE for AuthByPolicy. You can change this behavior with the Synchronous
flag, but make sure you understand what you are doing before enabling the Synchronous
flag. It can have a significant impact on performance. AuthBy RADIUS always immediately returns IGNORE for use by AuthByPolicy, so care must be taken when using
sequences of AuthBy clauses that include <AuthBy RADIUS>. If you need to continue
processing the reply with another AuthBy clause, the correct way to do that is with a
ReplyHook.
Hint: If you a required to proxy RADIUS requests to a remote Radiator across an insecure or unreliable network such as the internet, you should consider the RadSec protocol, and use AuthBy RADSEC instead of AuthBy RADIUS. RadSec provides
encrypted, reliable transport of RADIUS requests to a remote Radiator. See <AuthBy
RADSEC> on page 219, <ServerRADSEC> on page 287 and RadSec (RFC 6614)
on page 376.
Hint: You can perform load balancing as well as simple proxying by using <AuthBy
ROUNDROBIN> <AuthBy VOLUMEBALANCE> or <AuthBy LOADBALANCE>
(see Section 5.46 on page 175) instead of <AuthBy RADIUS>.
Hint: Using Fork with AuthBy RADIUS will almost certainly not do what you expect.
It will usually result in requests being sent to the remote host, but the replies not being
received.
Hint: You can specify your remote RADIUS hosts either with Host parameters
(Section 5.31.2 on page 128), or <Host xxxxxx> clauses (Section 5.32 on page 139).
The Host parameter is simpler but less flexible than the <Host xxxxxx> clause. For ease
of understanding, you should not mix formats in the same <AuthBy RADIUS>

126 of 397

Radiator RADIUS Server

Configuration

Hint: Radiator automatically copies any Proxy-State attribute from the incoming
RADIUS request to the reply. If a request with a Proxy-State attribute is proxied to
another server by AuthBy RADIUS, and the reply from that server also has a copy of
Proxy-State in it, then the reply to the NAS will have 2 copies of the Proxy-State attribute. If this causes a problem with the upstream NAS (it usually doesnt) then you can
strip the Proxy-State from the forwarded request with:
StripFromRequest Proxy-State

Examples: In case its not obvious from the above, there are 2 ways of specifying which
remote RADIUS Hosts to proxy to. The simplest (and least flexible) way is to use Host
parameters, and have the same secrets, ports etc. for all hosts:
<AuthBy RADIUS>
# Same secret and timeout for all hosts
Secret xyzzy
RetryTimeout 2
Host host1.bigco.com
Host host2.bigco.com
</AuthBy>

The other way allows you to customize some parameters on a host-by-host basis by
using Host clauses:
<AuthBy RADIUS>
# Same secret for all hosts
Secret xyzzy
<Host host1.bigco.com>
# But a custom Timeout for this one
RetryTimeout 2
</Host>
<Host host2.bigco.com>
# And custom ports for this one
AuthPort 1001
AcctPort 1002
</Host>
</AuthBy>
5.31.1 Failure algorithm

AuthBy RADIUS implements a configurable algorithm to detect failed RADIUS hosts,

and to temporarily disregard failed hosts. The algorithm uses the MaxFailedRequests,
MaxFailedGraceTime and FailureBackoffTime parameters to customize the operation
of the algorithm. It also uses KeepaliveTimeout and UseStatusServerForFailureDetect
in order to use only Status-Server requests for failure detection, instead of any request.
AuthBy RADIUS initially assumes that each Host is not failed. After a request is sent to
a RADIUS server, if no reply is received after the ReplyTimeout, it is reset up to Retries
times. If there is still no reply, that request is deemed to have failed for that Host.
AuthBy RADIUS keeps track of how many consecutive requests failed for each Host
since the last time a reply was heard from that Host. If more than MaxFailedRequests
consecutive requests are deemed to have failed within MaxFailedGraceTime seconds of
that last reply heard from that Host, that Host is deemed to have failed.

Radiator RADIUS Server

127 of 397

Configuration

When the Host is deemed to be failed, AuthBy RADIUS will not attempt to send any
requests to it until FailureBackoffTime seconds have elapsed.. It will also skip sending
requests to that host, and will instead attempt to send to the next Host in its list of Hosts
(if any).
The default values for these parameters are:
Retries 3
RetryTimeout 5
MaxFailedRequests 1
MaxFailedGraceTime 0
FailureBackoffTime 0

These values mean that by default AuthBy RADIUS will declare the Host failed after a
3 retries packet transmission failure, but that it will always try to transmit the next
request to the Host. This means that AuthBy RADIUS will always try to send every
request to the first Host, and if nothing is heard from that Host within (Retries * RetryTimeout) seconds, it will attempt to send to the next Host.
Hint: Judicious use of these parameters allows you to implement a RADIUS Host fallback policy, where if one RADIUS Host fails to respond to requests, then it will automatically temporarily fall back to the next RADIUS Host and so on.

AuthBy RADIUS understands the following parameters as well as those described in

Section 5.21 on page 82:
5.31.2 Host

The host name(s) where the destination radius server is running. Can be either a DNS
name or an IP address. Multiple comma separated host names can be specified in one
Host parameter, or you can use multiple Host lines. Radiator will try up to Retries times
to contact each host that you specify. If no response it heard it will try the next host in
the list and so on until a reply is received or the list is exhausted. The Host name can
contain special formatting characters, which are resolved at startup.
Hint: If the DNS name for any Host resolves to multiple IP addresses, Radiator will forward to those addresses in a round-robin fashion. DNS names are resolved at startup
time.
# Send all requests for this realm to 203.63.154.2, if no reply
# try the secondary at 203.63.154.3, if no reply from that,
# try all the addresses that radiushosts.open.com.au resolves to
# in round-robin fashion.
Host 203.63.154.2,203.63.154.3
Host radiushosts.open.com.au

Hint: For greater flexibility, you can also specify the hosts with the <Host xxxxxx>
clause, which allows you to customize details for each host. See Section 5.32 on
page 139.

128 of 397

Radiator RADIUS Server

Configuration

# These are equivalent to the lines in the example above:

<Host 203.63.154.2>
# Put host-specific values for Secret, ports,
# retries etc. in here
</Host>
<Host 203.63.154.3>
</Host>
<Host radiushosts.open.com.au>
</Host>

Hint: In order to proxy to an IPv6 address, the first IPv6 address listed in LocalAddress
will be used as the source address. If LocalAddress does not contain any IPv6 address,
then the default IPv6 source address for that host will be used. A LocalAddress of :: is
equivalent to a locally allocated IPv6 address
<AuthBy RADIUS>
# send via IPv6. Packets will appear to come from
# the default IPv6 source address for this host
LocalAddress ipv6:::
Host 2001:db8:100:f101::1
Secret xxxx
.....
</AuthBy>

Hint: IPv6 addresses are not required to be prefixed with ipv6: with Radiator 4.13 or
later.
5.31.3 Secret

The default value of the secret we share with the destination radius servers. Radiator
acts like a RADIUS client when it forwards RADIUS request to another RADIUS
server.
You must define a shared secret for each Host in AuthBy RADIUS, and it must match
the secret configured into the destination RADIUS server. There is no default. The
secret can be any number of ASCII characters. Any ASCII character except newline is
permitted, but it might be easier if you restrict yourself to the printable characters. For a
reasonable level of security, the Secret should be at least 16 characters, and a mixture of
upper and lower case, digits and punctuation. You should not use just a single recognizable word. Can be overridden for an individual host inside its Host clause.
# This better agree with the server at
# eric.open.com.au or they wont understand us
<AuthBy RADIUS>
Host eric.open.com.au
Secret 666obaFGkmRNs666
</AuthBy>

Caution: Some NASs, notably Enterasys Smart Switch Routers support a maximum
shared secret length of 16 characters.

Radiator RADIUS Server

129 of 397

Configuration

5.31.4 AuthPort

Specifies the default UDP port on the destination Hosts to which Radiator will send
authentication requests. The argument may be either a numeric port number or an alphanumeric service name as specified in /etc/services (or its moral equivalent on
your system). The default port is 1645. Note that the officially assigned port number for
RADIUS accounting has been changed to 1812. AuthPort may contain special formatting characters. Can be overridden for an individual host inside its Host clause.
# Send authentication to port 1812 on the remote server
AuthPort 1812
5.31.5 AcctPort

Specifies the default UDP port on the destination Hosts to which Radiator will send
accounting requests. The argument may be either a numeric port number or an alphanumeric service name as specified in /etc/services (or its moral equivalent on your
system). The default port is 1646. Note that the officially assigned port number for
RADIUS accounting has been changed to 1813. AcctPort may contain special formatting characters. Can be overridden for an individual host inside its Host clause.
# Send accounting to port 1813 on the remote server
AcctPort 1813
5.31.6 OutPort

If this optional parameter is set, it forces a particular port number to be used for the forwarding port. Therefore if you have, for example:
OutPort 1001

then all requests forwarded will appear to come from port 1001 on this Radiator host.
This can be useful for implementing strict firewall rules. The argument may be either a
numeric port number or an alphanumeric service name as specified in /etc/services (or
its moral equivalent on your system). The default is to use a port number determined by
your operating system, which will typically be different every time you restart your
Radiator. OutPort may contain special formatting characters. A typical use of special
formatting characters is with GlobalVar and command line arguments.
Hint: Many operating systems require root or administrator privileges to use a socket
with a port number less than 1024.
5.31.7 Retries

If Radiator does not get a reply from the destination RADIUS server within RetryTimeout seconds, it will by default retransmit the request up to this number of retries. Default
is 3 (which means maximum of 4 transmissions). Can be overridden for an individual
host inside its Host clause.
# Its a poor link, so lots of retries
Retries 10
5.31.8 RetryTimeout

Specifies the default number of seconds to wait for a reply before retransmitting. The
default is 5 seconds, which is a common value for most RADIUS clients. If the destination RADIUS server is at the end of a distant or saturated link, you may want to set this
to 10 or 20 seconds. Can be overridden for an individual host inside its Host clause.
130 of 397

Radiator RADIUS Server

Configuration

# Its a poor link, wait 15 seconds before retransmission

RetryTimeout 15
5.31.9 KeepaliveTimeout

This optional integer specifies the maximum time in seconds that a RADIUS connection
can be idle before a Status-Server request is sent. Defaults to 0 seconds. If set to 0,
keepalives are not used.
5.31.10 UseStatusServerForFailureDetect

If this optional flag is enabled, use only Status-Server requests (if any) to determine that
a target server is failed when there is no reply. If not enabled (the default) use no-reply
to any type of request. Uses NoreplyTimeout, MaxFailedRequests, MaxFailedGraceTime, FailureBackoffTime during failure detection.
If you enable this, you should also ensure KeepaliveTimeout is set to a sensible interval
to balance between detecting failures early and loading the target server.
5.31.11 FailureBackoffTime

This optional parameter specifies how long a failed remote server will be removed from
the forwarding list. If no reply is received from a Host (after all the Retries have
expired) for MaxFailedRequests consecutive times, it will be marked as failed for FailureBackoffTime seconds. After that time has expired, it will again be eligible for forwarding. The default is 0, which means that the host is always regarded as working.
Caution: with most types of load balancing modules, the default of 0 will mean endless
retransmission of each request until a reply is received.
5.31.12 MaxFailedRequests

This optional parameter specifies how many requests must fail to receive a reply before
the remote radius server is marked as failed, and the FailureBackoffTime will be
applied. The default is 1, which means that one ignored request will cause the Host to be
marked as failed for FailureBackoffTime seconds.
5.31.13 MaxFailedGraceTime

This optional parameter specifies the time period (in seconds) over which MaxFailedRequests failures will cause the target host to be assumed to be failed. Defaults to 0.
After a host is declared to be failed, no request will be forwarded to it until FailureBackoffTime seconds have elapsed.
5.31.14 StripFromRequest

Strips the named attributes from the request before forwarding it to any Host. The value
is a comma separated list of attribute names. StripFromRequest removes attributes from
the request before AddToRequest adds any to the request. There is no default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.31.15 AddToRequest

Adds attributes to the request before forwarding to any Host. Value is a list of comma
separated attribute value pairs all on one line, exactly as for any reply item. StripFrom-

Radiator RADIUS Server

131 of 397

Configuration

Request removes attributes from the request before AddToRequest adds any to the
request. You can use any of the special % formats in the attribute values. There is no
default.
# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h
5.31.16 NoForwardAuthentication

Stops AuthBy RADIUS forwarding Authentication-Requests. They are ACCEPTED,

but no further action is taken with them. This is different in meaning to IgnoreAuthentication, which IGNOREs them.
# Just ACCEPT Authentication-Requests, dont forward them
NoForwardAuthentication
5.31.17 NoForwardAccounting

Stops AuthBy RADIUS forwarding Accounting-Requests. They are ACCEPTED, but

no further action is taken with them. This is different in meaning to IgnoreAccounting,
which IGNOREs them.
# Just ACCEPT Accounting-Requests, dont forward them
NoForwardAccounting
5.31.18 LocalAddress

This optional parameter specifies the local address(es) to bind the proxy forwarding
socket. This in turn specifies what the IP source address will be in forwarded requests.
Defaults to BindAddress (which defaults to 0.0.0.0, i.e. the default source address). If no
appropriate IPv4 or IPv6 address is found in LocalAddress, the default IPv4 or IPv6
source address for the host will be used. This parameter is usually only useful for multihomed hosts. If you dont understand what this is for, dont set it: the default behaviour
is fine for most situations. If BindAddress or LocalAddress are set to multiple comma
separated addresses, only the first IPv4 or IPv6 address (as appropriate) will be used for
outgoing IPv4 or IPv6 addresses.
Hint: IPv6 addresses are not required to be prefixed with ipv6: with Radiator 4.13 or
later.
# We are multi-homed, bind the proxy port so forwarded requests
# appear to come from 203.53.154.27
LocalAddress 203.53.154.27

Hint: You can make forwarded IPv4 requests appear to come from one address, and
IPv6 requests appear to come from a different address. In this example, requests will
usually be forwarded to 2002:721:1500:1::a101, and will have a source address of
2001:720:1500:1::a100. If 2002:721:1500:1::a101 does not reply, then requests will be
forwarded to 210.1.1.5 with a source address of 203.63.154.27.
LocalAddress 203.63.154.27,2001:720:1500:1::a100
Host 2002:721:1500:1::a101
Host 210.1.1.5

Technical Note: AuthBy RADIUS will create and use a separate UDP network socket
for each distinct source address used from the LocalAddress list.

132 of 397

Radiator RADIUS Server

Configuration

5.31.19 ReplyHook

This optional parameter allows you to define a Perl function that will be called after a
reply is received from the remote RADIUS server and before it is relayed back to the
original client. The following arguments are passed in the following order:

A reference to the reply received from the remote RADIUS server.

A reference to the reply packet being constructed for return to the NAS.
A reference to the original request from the NAS.
A reference to the request that was sent to the remote RADIUS server.
A reference to the Radius::Host structure for the remote host.
A reference to the redirected flag. If redirected is set by the hook, the ReplyHook has
redirected the request to another AuthBy.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
The response type can be enforced when needed. For example, when the remote
RADIUS server has rejected the request, the ReplyHook can do any local processing
required for rejects and then change the response type to accept.
# Change RadiusResult in the 3rd argument, the original request
ReplyHook sub { ${$_[2]}->{RadiusResult} = $main::ACCEPT; }

ReplyHook Can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other
things.
# Fake a new attribute into the reply going back to the client
ReplyHook sub { ${$_[0]}->add_attr(test-attr, \
test-value);}
5.31.20 NoReplyHook

This optional parameter allows you to define a Perl function that will be called if no
reply is received from any remote RADIUS server. A reference to the original request
received from the NAS is passed as the first argument. A reference to the request that
was forwarded to the remote RADIUS server is passed as the second argument. A reference to the reply packet being constructed for return to the NAS is passed as the third
argument (note that the normal behaviour in case of no reply, is for no reply to be sent to
the NAS).
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.

Radiator RADIUS Server

133 of 397

Configuration

NoReplyHook Can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things.
# Call an AuthBy SQL to handle accounting that
# failed to get to the remote server
NoReplyHook sub { Radius::AuthGeneric::find(SQL)\
->handle_request(${$_[0]}, ${$_[2]});}
5.31.21 ReplyTimeoutHook

This optional parameter allows you to define a Perl function that will be called if no
reply is received from the currently tried remote RADIUS server. A reference to the
original request received from the NAS is passed as the first argument. A reference to
the request that was forwarded to the remote RADIUS server is passed as the second
argument.
5.31.22 IgnoreReject

This optional parameter causes Radiator to ignore (i.e. not send back to the original
NAS) any Access-Reject messages received from the remote RADIUS server. This is
sometimes useful for authenticating from multiple RADIUS servers. However, you
should note that if all the remote radius servers reject the request, then the NAS will
receive no reply at all.
# If we get a reject from the remote, dont send it to the NAS
IgnoreReject
5.31.23 Synchronous

Normally, AuthBy RADIUS will complete as soon as the request has been forwarded to
the remote radius server. It will not wait for a reply before moving on to other AuthBy
classes, or handling new requests. You can change this behaviour with the Synchronous
flag, but make sure you understand what you are doing before enabling the Synchronous
flag.
If you enable the Synchronous flag, Radiator will wait for either a reply, or a timeout
from the remote radius server before processing any following AuthBy clauses, or
before handling any further requests. This means that handling requests will stop until a
reply is received or the reply times out (which might take 15 seconds or more, depending on the settings of your RetryTimeout and retries parameters). This can seriously
affect the performance of your RADIUS server, especially if the remote radius server is
slow, stopped, or at the end of a slow or unreliable link. You should therefore be very
cautious about setting this flag, and you should understand the consequences of remote
server failure. The performance impact of the Synchronous flag can be alleviated by use
of the Fork parameter (see Section 5.21.1 on page 82) at the cost of significant increase
in memory requirements.
Nevertheless, Synchronous can be very handy if you wish, for example, to forward a
request to remote server only if another server REJECTS the request. See the example
below for sample configuration.
# Auth to server2 only if server 1 rejects. Caution:
# accounting will normally go to server1, unless it rejects
<Realm xxx>

134 of 397

Radiator RADIUS Server

Configuration

AuthByPolicy ContinueWhileReject
<AuthBy RADIUS>
# Wait here until we get a reply or a timeout
Synchronous
Host server1
Secret xxx
</AuthBy>
<AuthBy RADIUS>
Host server2
Secret yyy
</AuthBy>
</Realm>
5.31.24 UseExtendedIds

This optional flag can be used to work around various problem that might arise with
remote RADIUS servers in some circumstances.
In the standard RADIUS protocol;, the packet identifier is only 8 bits (0 to 255), which
means that a RADIUS server can only have 256 requests pending from a given client at
any time. This flag forces AuthBy RADIUS to use a much larger range of identifiers (at
least 32 bits) carried in the Proxy-State attribute, meaning that many more requests can
be pending at a given time, and that replies from a remote RADIUS server are more
accurately matched to their original requests.
One such problem is flooding of remote servers by large number of new requests occurring at the same time, such as after a power failure in a large part of the city, resulting in
lots of requests being proxied all at the same time.
Another problem is in the case of some types of remote server which do not send their
replies from the same port and address to which they were sent.
Hint: The correct operation of this parameter requires that the remote RADIUS server
honours the Proxy-State attribute correctly by replying it back to the sender exactly as it
was sent. Most modern RADIUS server (including Radiator) behave correctly in this
respect.
5.31.25 UseOldAscendPasswords

Deprecated. See UseExtendedIds on page 135. instead.

This optional parameter tells Radiator to encode all passwords sent by this AuthBy
using the old style (non RFC compliant) method that Ascend used to use on some
NASs. The symptom that might indicate a need for this parameter is that passwords
longer than 16 characters are not decoded properly. Can be overridden for an individual
host inside its Host clause.
5.31.26 ServerHasBrokenPortNumbers

Deprecated. See UseExtendedIds on page 135. instead.

Some RADIUS servers (GoRemote (GRIC) on NT in particular) exhibit broken behaviour in that the reply does not come from the same UDP port that the request was sent
to! This broken behaviour would normally cause Radiator to ignore replies from such
broken servers. The optional ServerHasBrokenPortNumbers flag will permit interoperaRadiator RADIUS Server

135 of 397

Configuration

tion with such broken servers. Can be overridden for an individual host inside its Host
clause.
Beware: enabling this for _two_ remote servers at the same host will cause difficult to
trace problems.
# We are proxying to a GRIC server on NT
ServerHasBrokenPortNumbers
5.31.27 ServerHasBrokenAddresses

Some RADIUS servers (some rare accounting proxies) exhibit broken behaviour in that
the reply does not come from the same address that the request was sent to! This broken
behaviour would normally cause Radiator to ignore replies from such broken servers.
The optional ServerHasBrokenAddresses flag will permit interoperation with such broken servers. Can be overridden for an individual host inside its Host clause.
Beware: enabling this for _two_ remote servers at the same host will cause difficult to
trace problems.
ServerHasBrokenAddresses
5.31.28 CachePasswords

This parameter enables a user password cache in this AuthBy RADIUS. It allows proxying to be more robust when the remote server is not available. It can be very useful if
the remote server is unreliable, or at the end of a slow, saturated or unreliable link. The
exact behaviour of when the password cache is consulted is controlled by the CacheOnNoReply parameter.
Hint: Use of this parameter with a large user population can cause large amounts of
memory use by the Radiator process.
Hint: If Radiator is restarted, the password cache is lost.
Note: Matching of cached passwords can never succeed for CHAP or MS-CHAP
authentication requests
5.31.29 CacheOnNoReply

This flag controls when the password cache created by the CachePasswords parameter
is consulted.
If CacheOnNoReply is set (the default), then the Access-Request will always be proxied
to the remote RADIUS server, and password cache will only be consulted if there is no
reply from of any of the remote RADIUS servers. If no reply is received from any of the
remote RADIUS servers, and If there is a cached reply that matches the password and
has not exceeded the CachePasswordExpiry time limit, then the request will be
accepted.
If CacheOnNoReply is not set, then the password cache will consulted before proxying.
If there is a cached reply that matches the password and has not exceeded the CachePasswordExpiry time limit, then the request will be accepted immediately without being
proxied to any remote RADIUS server.
136 of 397

Radiator RADIUS Server

Configuration

5.31.30 IgnoreReplySignature

Deprecated. Normally, if a reply from a remote RADIUS server is received with a bad
authenticator, the reply will be logged and then ignored. This optional parameter tells
AuthBy RADIUS to ignore incorrect signatures in replies from remote RADIUS servers. Some RADIUS servers implement incorrect signature algorithms, and this flag will
prevent problems when interoperating with such servers. Can be overridden for an individual host inside its Host clause.
Caution: use of this flag can cause incorrect handling of replies in unusual circumstances.
You know you need this flag if you see an error like this, even when you are sure the
shared secret for the RADIUS server is correct.
Bad authenticator received in reply .....
5.31.31 IgnoreAccountingResponse

This optional flag causes AuthBy RADIUS to ignore replies to accounting requests,
instead of forwarding them back to the originating host. This can be used in conjunction
with the AccountingHandled flag in a Handler or Realm (see Section 5.20.11 on
page 75) to ensure that every proxied accounting request is replied to immediately, and
the eventual reply from the remote RADIUS server is dropped.
5.31.32 AcctFailedLogFileName

The name of a files used to log failed Accounting-Request messages in the standard
radius accounting log format. If no reply is ever received from any of the remote hosts,
the accounting message will be logged to the named file. The log file format is
described in Section 15.5 on page 360. If no AcctFailedLogFileName is defined, failed
accounting messages will not be logged. The default is no logging. The file name can
include special formatting characters as described in Section 5.2 on page 20, which
means that using the %C, %c and %R specifiers, you can maintain separate accounting
log files for each Realm or Client or a combination. The AcctFailedLogFileName file is
always opened, written and closed for each failure, so you can safely rotate it at any
time.
The username that is recorded in the log file is the rewritten user name when
RewriteUsername is enabled.
Hint: You can change the logging format with AcctLogFileFormat.
Hint: You may want to make the filename depend on the date, so you get one missed
accounting file per day.
# Log all accounting to a single log file in LogDir
AcctFailedLogFileName %L/misseddetails
5.31.33 AcctLogFileFormat

This optional parameter is used to alter the format of the failed accounting log file from
the standard radius format when AcctLogFileFormatHook is not defined. AcctLogFileFormat is a string containing special formatting characters. It specifies the format
for each line to be printed to the accounting log file. A newline will be automatically

Radiator RADIUS Server

137 of 397

Configuration

appended. It is most useful if you use the %{attribute} style of formatting characters (to
print the value of the attributes in the current packet.
AcctLogFileFormat %{Timestamp} %{Acct-Session-Id}\
%{User-Name}
5.31.34 AcctLogFileFormatHook

Specifies an optional Perl hook that will is used to alter the format of the failed accounting log file from the standard radius format when defined. The hook must return the formatted accounting record. A newline will be automatically appended. By default no
hook is defined and AcctLogFileFormat or the default format are used. The hook
parameter is the reference to the current request.
5.31.35 AccountingStartsOnly

If this parameter is defined, it forces AuthBy RADIUS to only forward Accounting Start
requests. All other Accounting requests are accepted and acknowledged, but are not forwarded.
Hint: It does not make sense to set AccountingStartsOnly and AccountingStopsOnly.
5.31.36 AccountingAlivesOnly

If this parameter is defined, it forces AuthBy RADIUS to only forward Accounting

Alive requests. All other Accounting requests are accepted and acknowledged, but are
not forwarded.
5.31.37 AccountingStopsOnly

If this parameter is defined, it forces AuthBy RADIUS to only forward Accounting Stop
requests. All other Accounting requests are accepted and acknowledged, but are not forwarded.
You may want to use this parameter if your accounting system does not use or need
Accounting Start to do its billing.
# We only want to forward Stops
AccountingStopsOnly

Hint: It does not make sense to set AccountingStartsOnly and AccountingStopsOnly.

5.31.38 ClearTextTunnelPassword

This optional parameter prevents Radiator decrypting and re-encrypting Tunnel-Password attributes in replies during proxying. This is provided in order to support older
NASs that do not support encrypted Tunnel-Password.
5.31.39 AllowInRequest

This optional parameter specifies a list of attribute names that are permitted in forwarded requests. Attributes whose names do not appear in this list will be stripped from
the request before forwarding.
# Strip everything except username and password
AllowInRequest User-Name,User-Password

138 of 397

Radiator RADIUS Server

Configuration

5.31.40 DisableMTUDiscovery

If this optional parameter is set, it disables MTU discovery on platforms that support
that behaviour (currently Linux only). This can be used to prevent discarding of certain
large RADIUS packet fragments on supporting operating systems.
5.32 <Host xxxxxx> within <AuthBy RADIUS>
This clause can be used to specify the name and details of remote RADIUS servers
inside <AuthBy RADIUS> and its subtypes. The <Host xxxxxx> clause further allows
you to customize details for individual hosts. <AuthBy RADIUS> permits one or more
Host clauses.
In a Host clause header, the xxxxxx is the Host name or IP address of the remote
RADIUS host to proxy to. The Host name can contain special formatting characters,
which are resolved at startup.
<AuthBy RADIUS>
<Host server1.test.com>
Secret xyzzy
AuthPort 1645
AcctPort 1646
</Host>
<Host server2.test.com>
Secret xyzzy
AuthPort 1645
AcctPort 1646
</Host>
</AuthBy>
5.32.1 Host Parameters from the enclosing AuthBy RADIUS

The following parameters can be used within a Host clause. They have the same meaning and default values as the parameter of the same name in the enclosing AuthBy
RADIUS:

Secret
AuthPort
AcctPort
Retries
RetryTimeout
UseOldAscendPasswords
UseExtendedIds
ServerHasBrokenPortNumbers
ServerHasBrokenAddresses
IgnoreReplySignature
FailureBackoffTime
MaxFailedRequests
MaxFailedGraceTime

Radiator RADIUS Server

139 of 397

Configuration

LocalAddress
OutPort
5.32.2 BogoMips

Used by AuthBy LOADBALANCE and VOLUMEBALANCE to determine which target RADIUS server to use. Defaults to 1. If set to 0, this Host will not be used for forwarding by AuthBy RADIUS or any of its sub-types.
5.33 <AuthBy RADMIN>
AuthBy RADMIN provides authentication and accounting using the RAdmin User
Administration package from Open System Consultants (http://www.open.com.au/radmin). RAdmin is a complete web-based package that allows you to maintain your
RADIUS user and accounting details in an SQL database. You can add, change and
delete users, examine connection history, control simultaneous login, get reports on
modem usage and many other functions. The combination of Radiator and RAdmin provides a complete solution to your RADIUS user administration requirements.
Hint: RAdmin is not a billing or invoicing system.
During authentication, Radiator checks the password in the RAdmin RADUSERS
table. Accounting details are added to the RADUSAGE table.
There is an example Radiator configuration file for RAdmin in goodies/radmin.cfg.
AuthBy RADMIN understands exactly the same parameters as <AuthBy SQL> (see
Section 5.30 on page 111) as well as:
5.33.1 AuthSelect

This SQL query is used to select details of users who are attempting to log in. %0 is
replaced by the (possibly rewritten) User-Name. Other special formatting characters
may be used.
Defaults to
select PASS_WORD, STATICADDRESS, TIMELEFT, MAXLOGINS, \
SERVICENAME, BADLOGINS, VALIDFROM, VALIDTO from RADUSERS \
where USERNAME=%0

Hint: You can force AuthBy RADMIN to honour additional fields in your AuthSelect
statement by using AuthColumnDef. For example, you might add 3 new columns to
your RADUSERS table and wish to use them as reply items. You could do that something like this:
# Honour FRAMED_NETMASK,FRAMED_FILTER_ID,MAXIDLETIME too
AuthSelect select PASS_WORD,STATICADDRESS,TIMELEFT,\
MAXLOGINS,SERVICENAME, BADLOGINS, VALIDFROM,
VALIDTO, FRAMED_NETMASK,FRAMED_FILTER_ID,MAXIDLETIME \
from RADUSERS where \
USERNAME=%0
AuthColumnDef
0,Framed-IP-Netmask,reply

140 of 397

Radiator RADIUS Server

Configuration

AuthColumnDef
AuthColumnDef

1,Filter-Id,reply
2,Idle-Timeout,reply

Note that the numbering of AuthColumnDef 0 starts with the field following the first 8
minimum and required fields.
5.33.2 LogQuery

This optional parameter allows you to control the SQL query that is used to insert log
messages into the database.
The default is:
insert into RADMESSAGES (TIME_STAMP, TYPE, MESSAGE)
values (%t, $p, $s)

Where %t is translated as a special character to the current time, $p is converted to the

message priority (in integer in the range 0 to 4 inclusive), and $s is converted to the log
message, quoted and escaped. MESSAGE will be truncated to MaxMessageLength
characters prior to insertion.
5.33.3 MaxMessageLength

The optional parameter sets the maximum length of message that will be inserted by
LogQuery. All messages longer than MaxMessageLength characters will be truncated to
MaxMessageLength. Defaults to 200, which is the default size of the MESSAGE column in the RADMIN.RADMESSAGES table.
5.33.4 UserAttrQuery

This optional parameter allows you to control the query used to get user-specific
RADIUS check and reply items. %0 is replaced by the (possibly rewritten) User-Name.
Other special formatting characters may be used.
Defaults to
select ATTR_ID, VENDOR_ID, IVALUE, SVALUE, ITEM_TYPE \
from RADCONFIG where NAME=%0 order by ITEM_TYPE
5.33.5 ServiceAttrQuery

This optional parameter allows you to control the query used to get service-specific
RADIUS check and reply items. %0 is replaced by the Service Profile name from the
SERVICENAME column in the users database record. Other special formatting characters may be used. ServiceAttrQuery will be run after UserAttrQuery if ServiceAttrQuery is non-empty, and if a non-empty servicename was found in the 5th field
returned from AuthSelect.
Defaults to
select ATTR_ID, VENDOR_ID, IVALUE, SVALUE, ITEM_TYPE \
from RADSTCONFIG where NAME=%0 order by ITEM_TYPE
5.33.6 AttrQueryParam

This optional parameter enables the use of bound variables (where supported by the
SQL server) and query caching in the UserAttrQuery and ServiceAttrQuery strings. If
Radiator RADIUS Server

141 of 397

Configuration

you specify one or more AttrQueryParam parameters, they will be used in order to
replace parameters named with a question mark (?) in the UserAttrQuery and ServiceAttrQuery queries, and the query will be cached for future reuse by the SQL server. %0
is replaced by the appropriate user name or service name. See SQL Bind Variables on
page 25.
5.33.7 IncrementBadloginsQuery

This optional parameter specifies the SQL query to issue if AuthBy RADMIN detects a
bad password. It is intended to increment a count of the number of bad logins, which
can then be checked during authentication. %0 is replaced with the name of the user
being authenticated. Other special formatting characters may be used.
Defaults to:
update RADUSERS set BADLOGINS=BADLOGINS+1 where USERNAME=%0
5.33.8 ClearBadloginsQuery

This optional parameter specifies the SQL query to issue if AuthBy RADMIN detects a
good password. It is intended to clear a count of the number of bad logins, which can
then be checked during authentication. %0 is replaced with the name of the user being
authenticated. Other special formatting characters may be used.
Defaults to:
update RADUSERS set BADLOGINS=0 where USERNAME=%0
5.33.9 MaxBadLogins

AuthBy RADMIN compares the bad login count in the RAdmin database with MaxBadLogins. If it is exceeded, it is assumed that password guessing has been attempted
and the user will be disabled until their bad login count is reset. Defaults to 5. If set to 0,
the bad login count is ignored.
5.34 <AuthBy EMERALD>
AuthBy EMERALD provides authentication and accounting using the popular Emerald
ISP billing package from IEA (http://www.iea-software.com). The combination of
Radiator and Emerald provides a very powerful and easy to use ISP billing and user
management system. You will be able to add users to Emerald, and have them able to
log in immediately. Changing their password takes effect immediately, and all user
logins are available as soon as they are completed: no need to import accounting files.
Hint: Users of Emerald version 4 should use the <AuthBy EMERALD4>, following the
instructions provided by IEA.
Hint: This AuthBy method will also work for Platypus when it has its optional RadiusNT compatibility package installed.
Emerald uses Microsoft SQL for its user database, so in order to make Radiator work
with Emerald on Unix, you will usually need to install an ODBC driver, plus the Perl
DBD-ODBC module. Alternatively, you can use the DBD-Sybase module and the Syb-

142 of 397

Radiator RADIUS Server

Configuration

ase client libraries. More details on connectivity between Unix and MS-SQL on NT can
be found in the Radiator FAQ.
During authentication, Radiator checks the password in the Emerald masteraccounts
and subaccounts tables. It also checks the expiry dates, extensions and time left. It
also gathers radius reply attributes from the RadConfigs and RadATConfigs tables. The
RadATConfigs table (which contains per-account-type radius reply items) is only consulted if there are no per-user reply items for the user in the RadConfigs table (but you
can change this behavior with AddATDefaults, see Section 5.34.2 on page 143).
Hint: By default, AuthBy EMERALD takes no notice of the LoginLimit from the Emerald database. If you wish to honour it to limit the maximum number of simultaneous
logins for a user, add this to your Radiator configuration:
# use the LoginLimit from the emerald database
AuthSelect ,sa.LoginLimit
AuthColumnDef 0,Simultaneous-Use,check

AuthBy EMERALD does not use the RADIUS client configuration and secrets entered
into the Emerald Radius Config. You still need to configure a <Client> clause in
Radiator for each NAS you are going to use.
AuthBy EMERALD will connect to the Emerald database as the user you specify in the
DBUsername parameter. You will probably have to create such a login in your database,
and make sure they are a member of the Emerald database group.
During accounting, Radiator logs call details from each Accounting request to the
Emerald Calls table.
There is an example Radiator configuration file for Emerald in goodies/emerald.cfg.
You should use this as the starting point for configuring Radiator to work with Emerald.
AuthBy EMERALD understands exactly the same parameters as <AuthBy SQL> (see
Section 5.30 on page 111). It also understands the following additional parameters:
5.34.1 TimeBanking

If this optional parameter is set, it will enable Time Banking, which can be used to limit
the longest possible user session for the user to a pre-paid limit. If TimeBanking is enabled and if the subaccounts.timeleft column for the user is not NULL, then Radiator
will use it to generate a Session-Timeout reply attribute. This has the effect of limiting
the user session to the number of minutes specified in the subaccounts.timeleft column.
5.34.2 AddATDefaults

If this optional parameter is defined, then the account-type-specific RADIUS reply

items will be used unless there was a user-specific reply item. This allows you to use the
account-specific reply items as defaults.

Radiator RADIUS Server

143 of 397

Configuration

5.35 <AuthBy EMERALD4>

<AuthBy EMERALD4> authenticates users from the Emerald version 4 database from
IEA (see http://www.iea-software.com). It also stores accounting and logs to the Emerald 4 SQL database.
Hint: There is a sample Radiator configuration file for Emerald 4 in goodies/emerald4.cfg in your Radiator distribution.
AuthBy EMERALD understands exactly the same parameters as <AuthBy SQL> (see
Section 5.30 on page 111). It also understands the following additional parameters:
5.35.1 AuthSelect

This optional parameter from AuthBy SQL is preconfigured or Emerald 4 and need not
be altered. Defaults to
AuthSelect exec RadGetUser %0, NULL
5.35.2 ConcurrencyControl

This optional flag controls whether to apply Simultaneous-Use limits to each user.
Defaults to false.
5.35.3 TimeBanking

This optional flag control whether Time Banking limits are to be enforced. Defaults to
false.
5.35.4 HonourServers

This optional flag controls whether this module will use the Rodopi Servers list as an
additional source of Radius Client addresses. ClientQuery is used to fetch the client list.
Defaults to false.
5.35.5 HonourServerPortAccess

This optional flag controls whether this module will enforce time-based access limits
for certain NAS ports. PortAccessQuery is used to fetch details of port restrictions.
Defaults to false.
5.35.6 HonourDNISGroups

This optional flag controls whether this module will enforce limits on Called-Station-Id.
DNISGroupQuery is used to fetch details of permitted groups. Defaults to false.
5.35.7 HonourRoamServers

This optional flag Controls whether RoamQuery will be used to get roaming restrictions. Defaults to false.
5.35.8 DNISGroupQuery

SQL query used to fetch DNIS Groups. This parameter is preconfigured for Emerald 4,
and should not need to be changed. Defaults to:
DNISGroupQuery select dn.DNISNumber from AccountTypes a, \
DNISNumbers dn where a.AccountType=%0 and \
a.DNISGroupID=dn.DNISGroupID \
and dn.DNISNumber=%1

144 of 397

Radiator RADIUS Server

Configuration

5.35.9 PortAccessQuery

SQL query used to fetch permitted ports This parameter is preconfigured for Emerald 4,
and should not need to be changed. Defaults to:
PortAccessQuery select sa.StartTime, sa.StopTime, \
sa.MaxSessionLength from Servers s, ServerAccess sa, \
AccountTypes at\
where s.IPAddress=%{Client:Name} \
and s.ServerID = sa.ServerID \
and (sa.Port=%0 or sa.Port=9214328)\
and sa.AccountTypeID=at.AccountTypeID\
and at.AccountType=%1\
order by sa.Port
5.35.10 RadUserQuery

SQL query used to fetch user attributes This parameter is preconfigured for Emerald 4,
and should not need to be changed. Defaults to:
RadUserQuery exec RadGetConfigs %0
5.35.11 ClientQuery

SQL query used to fetch RADIUS client details This parameter is preconfigured for
Emerald 4, and should not need to be changed. Defaults to:
ClientQuery select IPAddress, Secret, Community, ServerID \
from Servers
5.35.12 RoamQuery

SQL query used to fetch roaming restrictions This parameter is preconfigured for Emerald 4, and should not need to be changed. Defaults to:
RoamQuery exec RadRoamCache

5.36 <AuthBy PLATYPUS>

AuthBy PLATYPUS provides authentication and accounting using the popular Platypus
ISP billing package from Tucows (http://www.ispbilling.com/products/platypus.php).
The combination of Radiator and Platypus provides a very powerful and easy to use ISP
billing and user management system. You will be able to add users to Platypus, and have
them able to log in immediately. Deactivating a Platypus account or changing their password takes effect immediately, and all user logins are available as soon as they are completed: no need to import accounting files.
Platypus uses Microsoft SQL for its user database, so in order to make Radiator work
with Platypus on Unix, you will usually need to install an ODBC driver, plus the Perl
DBD-ODBC module.
During authentication, Radiator checks the password in the Platypus customer table. It
also checks the Block User state. If it is set to Y or G, Radiator will check the Platypus
Time Left field, and will reject the login if the time left is negative. Otherwise, it will
accept the login, and set Session-Timeout in the reply to the number of seconds of login
time left. This allows you to prevent users overspending the prepaid time.

Radiator RADIUS Server

145 of 397

Configuration

During accounting, Radiator logs call details from each Accounting Stop request to the
Platypus radiusdat table.
There is an example Radiator configuration file for Platypus in goodies/platypus.cfg.
You should use this as the starting point for configuring Radiator to work with Platypus.
Hint: Tucows have an optional package that makes Platypus compatible with RadiusNT, an NT-only radius server. With this package installed, Platypus will let you set up
per-user and per-service RADIUS reply attributes using Platypus editing screens in the
menu Maintenance->RadiusNT Setup. Radiator can also work with this, but you must
use <AuthBy EMERALD> instead of <AuthBy PLATYPUS>, and configure it as if for
Emerald. See Section 5.34 on page 142.
AuthBy PLATYPUS understands the following parameters:
5.36.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to <AuthBy SQL>. They specify the DBD driver, database and
username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.36.2 AccountingTable

This optional parameter specifies the name of the Platypus table to insert Accounting
Stop requests into. It defaults to radiusdat which is the usual name for that table in
Platypus. You will normally not want to change it. If you change it to the empty string,
Radiator will not store any Accounting requests to Platypus at all.
# dont store any accounting data to platypus
AccountingTable
BasicSelect
AuthSelect
5.36.3 AcctColumnDef

By default, AuthBy PLATYPUS only logs a few attributes to AccountingTable: user

name, call start time, call end time and session ID. You can log additional attributes
from Accounting Stop requests with AcctColumnDef in the same was as AuthBy SQL.
See Section 5.30.17 on page 118 for syntax. You must add the appropriate new columns
to your AccountingTable before you can log to them.
# Log some extra data from each Stop
AcctColumnDef NASIDENTIFIER,NAS-Identifier
AcctColumnDef ACCTTERMINATECAUSE,Acct-Terminate-Cause
5.36.4 BasicSelect

AuthBy PLATYPUS works slightly differently to AuthBy SQL when it comes to how
the user attribute selection query is assembled.

146 of 397

Radiator RADIUS Server

Configuration

BasicSelect specifies the SQL query used to fetch user attributes from the Platypus database. It is expected to return the following attributes in this order

password
active
timeleft
blockuser
guarantor
possibly other attributes as selected by AuthSelect.

%0 is replaced with the contents of AuthSelect, which is expected to be a list of additional columns to select from the database. See AuthSelect below
%1 is replaced with the user name
The default will work with the standard Platypus database and need not be changed:
BasicSelect select password, active, timeleft, blockuser, \
guarantor %0 from customer where username=%1
5.36.5 AuthSelect

This optional parameter specifies additional SQL columns to fetch with BasicSelect.
You can optionally fetch your own additional columns from the user database when you
fetch the password in a similar way to AuthSQL. In this example, you define an additional column in the customer table called maxsessions, which (if not NULL) will be
used to set Simultaneous-Use for the user. AuthSelect is the SQL required to select
additional columns from customer, so the comma is required
AuthSelect ,maxsessions
AuthColumnDef 0,Simultaneous-Use,check

5.37 <AuthBy RODOPI>

AuthBy RODOPI provides authentication and accounting using the popular Rodopi ISP
billing package (http://www.rodopi.com). The combination of Radiator and Rodopi provides a very powerful and easy to use ISP billing and user management system. You
will be able to add users to Rodopi, and they will be able to log in immediately. Changing their password takes effect immediately, and all user logins details are available as
soon as they are completed: no need to import accounting files.
Rodopi uses Microsoft SQL Server for its user database, so in order to make Radiator
work with Rodopi on Windows, you will usually need to install an ODBC driver, plus
the Perl DBD-ODBC module. On Unix, you will need to install DBD-Sybase and the
Sybase client library to allow Radiator to connect to Microsoft SQL Server.
During authentication, Radiator checks the password in the Rodopi Logins table. It
also gathers radius check and reply attributes from the RadiusUsers table.

Radiator RADIUS Server

147 of 397

Configuration

AuthBy RODOPI will connect to the Rodopi database as the user you specify in the
DBUsername parameter. The default username that Rodopi installs is Rodopi, with
password rodopi.
During accounting, Radiator logs call details from each Accounting request to the
Rodopi UsageOnlineHours table.
AuthBy RODOPI automatically handles Cisco VOIP authentication and Accounting
with the Rodopi 5.4 or later Cisco VOIP support. RADIUS requests that contain the
cisco-h323-conf-id attribute are handled with the VOIP stored procedures. All other
requests are handled with the non-VOIP procedures.
There is an example Radiator configuration file for Rodopi in goodies/rodopi.cfg. You
should use this as the starting point for configuring Radiator to work with Rodopi.
AuthBy RODOPI understands exactly the same parameters as <AuthBy SQL>.
# Authenticate everyone with Rodopi using the ODBC
# DSN called Rodopi
<Realm DEFAULT>
<AuthBy RODOPI>
DBSource
dbi:ODBC:Rodopi
DBUsername
Rodopi
DBAuth
rodopi
</AuthBy>
</Realm>
5.37.1 AuthSelect

Similar in meaning to AuthSelect in AuthBy SQL. Defaults to:

exec Interface_VircomUsers %0

where %0 is replaced with the User-Name.

5.37.2 AcctSQLStatement

This optional parameter defines the SQL query that will be used to insert accounting
details into the Rodopi database. Defaults to:
exec Interface_VircomDetails
%0, %1, %2, %3, %4, %5, %6, %7, %8, %9,
%10, %11, %12, %13, %14, %15, %16, %17, %18, %19,
%20

Where %0 is replaced with Acct-Session-Id, %1 with SQL formatted Timestamp, %2

with User-Name, %3 with Nas-IP-Address, %4 with Nas-Port, %5 with Service-Type ,
%6 with Framed-Protocol, %7 with Framed-IP-Address, %8 with Calling-Station-Id,
%9 with Nas-Identifier, %10 with Acct-Status-Type, %11 with Acct-Delay-Time, %12
with Acct-Input-Octets, %13 with Acct-Output-Octets, %14 with Acct-Session-Time,
%15 with Acct-Input-Packets, %16 with Acct-Output-Packets, %17 with Acct-Terminate-Cause, %18 with Nas-Port-Type, %19 with Connect-Info, %20 with Called-Station-Id.

148 of 397

Radiator RADIUS Server

Configuration

Unlike other AuthBy SQL clauses, if you define AcctSQLStatement in your AuthBy
RODOPI configuration file, it will replace the default AcctSQLStatement, rather than
add another AcctSQLStatement.
5.37.3 CiscoVoip

This optional parameter tells AuthBy RODOPI to handle Cisco VOIP requests using the
VOIP procedures specified by VoipAuthSelect and VoipAcctSQLStatement parameters.
Defaults to 1, meaning that Cisco VOIP requests will be handled. If this parameter is set
to 0, Cisco VOP requests will be handled using the AuthSelect and AcctSQLStatement
parameters.
# Dont handle Cisco VOIP specially
CiscoVoip 0
5.37.4 VoipAuthSelect

This optional parameter specifies the SQL query which will be used to authenticate
VOIP Access-Requests. May contain special characters. If CiscoVoip is enabled, then
any Access-Request containing a the cisco-h323-conf-id attribute will be authenticated with VoipAuthSelect. The default is:
exec Interface_VircomUsers2 %0, %1, %2, %3, %4, %5

Where %0 is replaced with the User-Name, %1 is replaced with Calling-Station-Id, %2

is replaced with Called-Station-Id, %3 is replaced with NAS-IP-Address, %4 is replaced
with cisco-h323-conf-id and %5 is replaced with Service-Type.
5.37.5 VoipAcctSQLStatement

This optional parameter defines the SQL query that will be used to insert VOIP accounting details into the Rodopi database. May contain special characters. If CiscoVoip is
enabled, then any Accounting-Request containing a the cisco-h323-conf-id attribute
will be authenticated with VoipAcctSQLStatement. Defaults to:
exec Interface_VircomDetails2
%0, %1, %2, %3, %4, %5, %6,
%10, %11, %12, %13, %14, %15,
%20, %21, %22, %23, %24, %25,

%7, %8, %9,

%16, %17, %18, %19,
%26, %27, %28, %29, %30, %31, %32

Arguments %0 to %20 inclusive are replaced the same was as specified in AcctSQLStatement above. %21 is replaced by cisco-h323-gw-id, %22 is replaced by cisco-h323conf-id, %23 is replaced by cisco-h323-call-origin, %24 is replaced by cisco-h323-calltype, %25 is replaced by cisco-h323-setup-time, %26 is replaced by cisco-h323-connect-time, %27 is replaced by cisco-h323-disconnect-time, %28 is replaced by ciscoh323-disconnect-cause, %29 is replaced by cisco-h323-voice-quality, %30 is replaced
by cisco-h323-remote-address, %31 is replaced by cisco-h323-ivr-out and %32 is
replaced by cisco-h323-call-treatment.
5.38 <AuthBy LDAP2>
AuthBy LDAP, AuthBy LDAP2 and AuthBy LDAPSDK provide authentication via
LDAP. They all provide much the same features, but they interface to the LDAP server
via different Perl modules. AuthBy LDAP2 is the preferred module to use. The others
are regarded as obsolete.

Radiator RADIUS Server

149 of 397

Configuration

AuthBy LDAP works with Clayton Donleys Net::LDAPapi module version 1.42 or
better (Available from CPAN). It is implemented in AuthLDAP.pm. The Net::LDAPapi
will work with both University of Michigan LDAP and Netscapes LDAP SDK. It is
now deprecated. You should use LDAP2 for new installations.
AuthBy LDAP2 works with the newer Net::LDAP module version in perl-ldap-0.09 or
better (Available from CPAN). It is implemented in AuthLDAP2.pm. The Net::LDAP
will work with University of Michigan LDAP, OpenLDAP, Netscapes LDAP SDK,
Novell eDirectory and others.
AuthBy LDAPSDK works with Netscapes PerLDAP module and the Netscape Directory SDK. We provide this in addition to the others because PerLDAP is readily available as an installable module for ActiveState Perl on NT. If you want to use LDAP on
NT, we recommend you use ActiveState Perl, the PerLDAP module and Netscape Suite
Spot directory server. LDAPSDK is now deprecated. You should use LDAP2 for new
installations.
All the AuthBy LDAP modules authenticate by issuing requests to an LDAP server.
When the LDAP server replies, Radiator fetches a number of attributes and looks in
them for the password, check items and reply items in order to authenticate the user. It
does not log (but does reply to) accounting requests. You will need to have a basic
understanding of LDAP servers and databases in order to configure AuthBy LDAP.
When an AuthBy LDAP module receives its first authentication request, it attempts to
connect to the LDAP server specified by Host. Optionally you can authenticate Radiator
as a valid user of the LDAP server by specifying AuthDN and AuthPassword. (This is
not the same thing as authenticating a user. It happens before authenticating a user, and
proves that this radiusd is allowed to talk to the LDAP database).
The AuthBy LDAP module will then try to fetch some attributes for the user. You can
specify the base DN to start looking in, and the attribute name with which to filter. You
also specify the attributes that contain the password, and (optionally) the names of the
attributes containing an encrypted password, RADIUS check items and RADIUS reply
items. This scheme allows you to work with almost any LDAP schema. All you have to
do is identify the right LDAP attribute names.
If all the check items are satisfied by the attributes in the request, the AuthBy LDAP
module will reply with an Access-Accept message containing all the attributes in the
reply items attribute (if any). If the user does not appear in the LDAP database, or if any
check attribute does not match, an Access-Reject message is sent to the client.
At present, AuthBy LDAP modules do synchronous connections and searches. This can
mean significant delays if your LDAP server is reached by a slow network connection,
and/or your LDAP server is slow. If this is the case, you should consider putting the
AuthBy LDAP realm in a sub-server, and having your main Radiator forward requests
for that realm to the RADIUS sub-server.
SASL Authentication of the LDAP connection

150 of 397

Radiator RADIUS Server

Configuration

AuthBy LDAP2 and other LDAP modules support SASL authentication of the connection to the LDAP server. If SASL authentication is specified in AuthBy LDAP2, then
the LDAP server will use SASL to authenticate the SASL user credentials specified by
SASLUser and SASLPassword. This will usually require some configuration of your
LDAP server to enable SASL authentication, and perhaps to map SASL user names to
LDAP server administrator names. For example, when using OpenLDAP, you will have
to add a SASL user to the SASL database with a command like:
/usr/sbin/saslpasswd2 -c saslusername

and also to tell the LDAP server to honour the SASL user as an LDAP administrator, by
adding to the LDAP server configuration file (typically /etc/openldap/slapd.conf), all on
one line:
sasl-regexp
uid=saslusername,cn=digest-md5,cn=auth
cn=Manager,dc=example,dc=com

AuthBy LDAP understands the following parameters as well as those described in

Section 5.21 on page 82:
5.38.1 Host

The name(s) of the LDAP host(s) to connect to. Defaults to localhost. Special formatting characters are permitted. Multiple space separated host names can be specified
and Net::LDAP will choose the first available one. If Host begins with "ipv6:" the subsequent host name(s) will be interpreted as IPv6 addresses where possible, and
Net::LDAP will use INET6 to connect to the LDAP server (requires IO::Socket::INET6
and Socket6 perl modules).
# Always connect to UMICH
Host ldap.itd.umich.edu

or...
# Connect to first available host:
Host ldaphost1 ldaphost2 ldaphost3
5.38.2 Port

Specifies the port to connect to on the LDAP host. Defaults to 389, the standard port for
unencrypted LDAP. If UseSSL is specified, it defaults to 636, the standard port for
encrypted LDAP. Can be a numeric port number or a symbolic service name from /etc/
services or its equivalent on your system. You should never need to override the
defaults. Port may contain special formatting characters. A typical use of special formatting characters is with GlobalVar and command line arguments.
# Connect using the SSL encrypted port
Port 636
5.38.3 UseSSL

This optional parameter specifies to use SSL to connect to the LDAP server. UseSSL is
supported with LDAP and LDAP2. The syntax is slightly different for the two versions.
See the alternative UseTLS parameter for TLS support.

Radiator RADIUS Server

151 of 397

Configuration

For AuthBy LDAP, UseSSL specifies the name of the certificate database.
# LDAP: Enable SSL and tell it where to find certificates
UseSSL /.netscape/cert5.db

Hint: The certificate database must either be the cert5.db certificate database used by
Netscape Navigator 3.x or the ServerCert.db certificate database used by Netscape 2.x
servers.
Hint: You can use special filename characters in the certificate filename.
For AuthBy LDAP2, you also need to specify some additional parameters describing
the ___location of certificate and private key files.
# LDAP2: Enable SSL and tell it where to find certificates
UseSSL
# Name of the client certificate file:
SSLCAClientCert /path/to/client/certificate.pem
# Name of the file containing the client private key
SSLCAClientKey /path/to/client/keyfile.pem
# only need to set one of the following
#SSLCAPath /path/to/CA/cert/dir
SSLCAFile /path/to/file/containing/certificate/of/CA.pem

Hint: You only need to set one of SSLCAFile or SSLCAPath, not both.
Hint: All LDAP2 certificates are required to be in PEM format.
Hint: If both UseSSL and UseTLS are specified, SSL will be used.
5.38.4 SSLVerify

This parameter may be used with the UseSSL or UseTLS parameters to control how the
LDAP servers certificate will be verified. The options are:

none
No server certificate is required, and if the server supplies a certificate it will not be
checked.

optional
Verify if the server offers a certificate

require
The server must provide a certificate, and it must be valid.
The default is require.
Hint: require is the most secure option.
5.38.5 UseTLS

This optional parameter is used in a similar way to UseSSL. It forces the LDAP connection to use TLS authentication and encryption. It is only available for AuthBy LDAP2.

152 of 397

Radiator RADIUS Server

Configuration

UseTLS takes the same parameters as UseSSL, including SSLVerify, SSLCiphers, SSLCAPath, SSLCAFile, SSLCAClientCert, and SSLCAClientKey. SSLVersion must be 3
to support TLS, and is silently forced.
Hint: If both UseSSL and UseTLS are specified, SSL will be used.
Note: Net::LDAP 0.57 and earlier had a bug where LDAP + STARTTLS followed by
LDAPS failed. This would happen when a clause with UseTLS is followed by another
clause with UseSSL.
5.38.6 AuthDN

This is the optional name to use to authenticate this Radiator server to the LDAP server.
You only need to specify this if the LDAP server requires authentication from its clients.
Netscape SuiteSpot servers almost always require this to be set.
# Log in to LDAP as admin
AuthDN admin
5.38.7 AuthPassword

This is the optional password to use to authenticate this Radiator server to the LDAP
server. You only need to specify this if the LDAP server requires authentication from its
clients, and you specify AuthDN. Netscape SuiteSpot servers almost always require this
to be set.
# log in to LDAP with password adminpassword
AuthPassword adminpassword
5.38.8 BaseDN

This is the base DN where searches will be made. For each authentication request, Radiator does a SUBTREE search starting at BaseDN, looking for a UsernameAttr that
exactly matches the user name in the radius request (possibly after username rewriting).
Special formatting characters are permitted, and %0 is replaced by UsernameAttr and
%1 by the user name.
# Start looking here
BaseDN o=University of Michigan, c=US

Hint: On some LDAP servers, you can get a significant performance increase by narrowing the search to the exact uid you are interested in. This example restricts the search
to uid=username,ou=foo,o=bar,c=au:
BaseDN
Scope

%0=%1,ou=foo,o=bar,c=au
base

5.38.9 Scope

This optional parameter allows you to control the search scope used to find the user.
Defaults to subtree in AuthBy LDAPSDK, and to sub in AuthBy LDAP2. Has no
effect in AuthBy LDAP.
In AuthBy LDAPSDK, the permitted options are:

base
Radiator RADIUS Server

153 of 397

Configuration

onelevel
subtree
In AuthBy LDAP2, the permitted options are:

base
one or single
sub or subtree
# Only makes sense to AuthBy LDAPSDK
Scope
onelevel
5.38.10 UsernameAttr

This is the name of the LDAP attribute that is required to match the username in the
authentication request (possibly after username rewriting by RewriteUsername).
Defaults to uid. The LDAP search filter is constructed from UsernameAttr and the
name of the user in the Access-Request like this: (UsernameAttr = username) For
example, if you UsernameAttr is uid, and user mikem tries to log in, Radiator will
use the LDAP filter (uid=mikem). This behaviour can be customized with the SearchFilter parameter.
# Use the uid attribute to match usernames
UsernameAttr uid
5.38.11 PasswordAttr

This is the name of the LDAP attribute that contains the password for the user. The
password may be in any of the formats supported by User-Password as described in
Section 13.1.1 on page 334. Most LDAP servers will only have a plaintext password if
they are secured in another way, and probably not even then. You must specify either
PasswordAttr or EncryptedPasswordAttr. There is no default.
Note: that OpenLDAPs userPassword is (a) encrypted and (b) only retrievable via an
appropriately authenticated binding to the slapd.
# Plaintext passwords. Gasp
PasswordAttr passwd

Hint: If there is no password to be checked (e.g. Wireless MAC Addresses) you should
specify PasswordAttr without a value, otherwise you will get a warning log message.
5.38.12 EncryptedPasswordAttr

This is the optional name of the LDAP attribute that contains a Unix crypt(3) encrypted
password for the user. If you specify EncryptedPasswordAttr, it will be used instead of
PasswordAttr, and PasswordAttr will not be fetched. You must specify either PasswordAttr or EncryptedPasswordAttr. There is no default.
Hint: If your passwords are in the form {crypt}1xMKc0GIVUNbE, {SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc= or {SSHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc= you should be using PasswordAttr, not EncryptedPasswordAttr. Only use
EncryptedPasswordAttr if the your password are plain old Unix crypt format, like:
1xMKc0GIVUNbE.

154 of 397

Radiator RADIUS Server

Configuration

# Get the encrypted password from cryptpw

EncryptedPasswordAttr cryptpw
5.38.13 CheckAttr

This is the optional name of the LDAP attribute that contains the RADIUS check items
for the user. During authentication, all the check items in this LDAP attribute (if specified) will be matched against the RADIUS attributes in the authentication request in the
same was as for AuthBy FILE and AuthBy SQL, including Expiration in the format
Dec 08 1998. Defaults to undefined. See Section 13.1 on page 334 for information on
how check items are used.
Hint: If there are multiple instances of the LDAP attribute for the user, they are concatenated together with commas. This means that you can have each RADIUS check attribute in its own LDAP attribute for easy reading and maintenance.
Hint: AuthAttrDef is a more general and easy to use method of defining check and reply
items. Support for CheckAttr will be discontinued sometime in the future.
# Check the radius items in checkitems
CheckAttr checkitems
5.38.14 ReplyAttr

This is the optional name of the LDAP attribute that contains the RADIUS reply items
for the user. If the user authenticates successfully, all the RADIUS attributes named in
this LDAP attribute will be returned to the user in the Access-Accept message. Defaults
to undefined. See Section 13.2 on page 349 for information on how reply items are
used.
Hint: If there are multiple instances of the LDAP attribute for the user, they are concatenated together with commas. This means that you can have each RADIUS reply attribute in its own LDAP attribute for easy reading and maintenance.
Hint: AuthAttrDef is a more general and easy to use method of defining check and reply
items. Support for ReplyAttr will be discontinued sometime in the future.
# Reply with all the items in replyitems
ReplyAttr replyitems
5.38.15 SearchFilter

Normally, the search filter that is used to find a matching user name is
(uid=name)

where uid is the name of the LDAP attribute defined by the UsernameAttr parameter,
and name is the name of the user currently being authenticated. For advanced applications, you can completely alter the search filter that Radiator will use by using the
optional SearchFilter parameter. It allows you to use arbitrarily complicated LDAP
search filters to select or exclude users based on attributes other than their user name.
Special formatting characters are permitted, and %0 is replaced by UsernameAttr and
%1 by the user name. For example, this SearchFilter will only match users with the
appropriate setting of their current attribute:

Radiator RADIUS Server

155 of 397

Configuration

SearchFilter (&(current=1)(uid=%1))

In SearchFilter, you an use any special formatting character. For backwards compatibility, perl variables used to be interpolated, but this has been removed. The default setting
for SearchFilter is (%0=%1), which will match the user name against the LDAP attribute defined by the UsernameAttr parameter (usually uid). Therefore the default
search string is (uid=name).
5.38.16 AuthAttrDef

This optional parameter allows you to specify LDAP attributes to use as general check
and reply items during authentication. AuthAttrDef is more general and useful than
CheckAttr and ReplyAttr, and should be used in preference to them.
Using AuthAttrDef you can specify multiple LDAP attributes and tell Radiator to use
them as check or reply items during authentication.
You can specify any number of AuthAttrDef parameters, one for each check or reply
attribute in your LDAP database. The general format is:
AuthAttrDef ldapattributename[, radiusattributename, type[,
formatted]]

ldapattributename is the name of the LDAP attribute to be used as the check or reply
item. If it is multi-valued, and this is a check item, then Radiator will permit a match
with any one of the values.

radiusattributename is the name of the RADIUS attribute that wall be used as the
check or reply item. The special radiusattributename GENERIC indicates that it is
a list of comma separated attribute=value pairs, similar to ReplyAttr or CheckAttr.

type indicates whether it is a check or reply item. It consists of the word check or
the word reply. If type is request the value is saved in the current request, from
where it can be later collected with a special formatting macro like: %{attributename}.

formatted indicates that the LDAP attributes are to be subject to special character
processing before being used.
A few examples are in order:
Example 1
Fetch the LDAP attribute called calledstationid, and use it as a check item against the
RADIUS Called-Station-Id
AuthAttrDef

calledstationid,Called-Station-Id,check

Example 2
Check the RADIUS Service-Type matches the LDAP attribute called servicetype, and
return the LDAP attribute called address as a static IP address (after special character
replacements):

156 of 397

Radiator RADIUS Server

Configuration

AuthAttrDef
AuthAttrDef

servicetype,Service-Type,check
address,Framed-IP-Address,reply,formatted

Example 3
During LDAP authentication, save 2 LDAP attributes into the current request:
# Put poolhint attribute into the request:
AuthAttrDef radiusUserPoolHint, X-userPoolHint, request
# Put Group Name attribute into the Request:
AuthAttrDef radiusSimultaneousUseGroupName,X-GroupName, request

Then use those attributes in a later AuthBy FILE:

fred

Group=%{X-GroupName}
PoolHint=%{X-userPoolHint}

Example 4
Check items handle multi-valued LDAP attributes in a special way: by permitting a
match with any one of the multiple values. For example, suppose you had callingstation LDAP attribute that could be multi-valued, and into which you put all the
numbers the user was permitted to call from (as a separate value for each number), then
you would use:
AuthAttrDef callingstation,Calling-Station-Id,check

Hint: The radiusattributename and type fields are optional. If they are not specified,
then the ldapattributename attribute will be fetched from LDAP, but the fetched value
of that attribute will not be used. This can be helpful for some types of LDAP query.
5.38.17 AttrsWithBaseScope

Tells Radiator to search first for the user DN then do a search with scope base to fetch
the attributes. Required, for example, to get access to Windows AD constructed attributes, such as tokenGroups, which are only returned when the search scope is set to base.
Defaults to off.
5.38.18 HoldServerConnection

By default, AuthBy LDAP, LDAP2 and LDAPSDK will disconnect from the LDAP
server after each authentication. This is because not all LDAP servers permit multiple
searches from the same LDAP connection. The HoldServerConnection optional parameter forces AuthBy LDAP to hold the connection to the LDAP server up for as long as
possible. Only some LDAP servers support this behaviour (notably University of Michigan, Netscape, Open Directory and Novell eDirectory), but for those servers it can significantly improve performance, especially where UseTLS or UseSSL is enabled. If you
enable this parameter and you start to get odd behaviour from your AuthBy LDAP, you
are probably using an unsupported LDAP server, and you should not use this parameter
on it.
# We are using UMich
HoldServerConnection

Radiator RADIUS Server

157 of 397

Configuration

5.38.19 ServerChecksPassword

Normally, Radiator fetches the users password attribute from the LDAP server (using
the PasswordAttr parameter), and checks the password internally. This optional parameter causes the LDAP server to check the password instead. This is useful with LDAP
servers that implement proprietary encryption algorithms in their passwords (notably
Open Directory from Platinum) can be used.
When ServerChecksPassword is specified, the password checking is performed using an
LDAP bind operation.
Not supported by AuthBy LDAP or AuthBy LDAPSDK.
# We are using Open Directory
ServerChecksPassword
5.38.20 Timeout

This optional parameter sets the TCP connection timeout period in seconds for the connection to the LDAP server. Defaults to 10 seconds. Available only with AuthBy LDAP
and LDAP2. If a connection times out, the authentication request will be IGNOREd. A
time of 0 means that Radiator will wait forever for LDAP connections and transactions.
# Make timeout really short, 2 seconds
Timeout 2
5.38.21 FailureBackoffTime

This optional parameter sets the period of time that AuthBy LDAP and LDAP2 will
stop trying to connect to its LDAP server after a connection failure. Defaults to 600 seconds (10 minutes). This is intended to give the LDAP server time to recover after a failure. During the failure backoff interval, all authentication requests will be IGNOREd.
5.38.22 PostSearchHook

This optional parameter allows you to define a Perl function that will be run during the
authentication process. The hook will be called after the LDAP search results have been
received, and after Radiator has processed the attributes it is interested in. Hook authors
can use the appropriate LDAP library routines to extract other attributes and process
them in any way.
The first argument passed to the hook is a handle to the current AuthBy LDAP object.
The second argument is the name of the user being authenticated. The third argument is
a pointer to the current request. The fourth argument is a pointer to the User object being
constructed to hold the check and reply items for the user being authenticated.
The fifth argument ($_[4]) has a different meaning in LDAP, LDAP2, or LDAPSDK. In
the case of LDAP, it is entry resulting from ldap_first_entry(). In the case of LDAP2, it
is the entry resulting from $result->entry(0) (i.e. the first match of the LDAP search). In
the case of LDAPSDK, it is the result of the LDAP search() function. The sixth argument to PostSearchHook is a pointer to the reply packet currently being constructed.
# this example for LDAP2 gets an additional attribute,
# multiplies it by 60 and uses it for Session-Timeout
# as a reply attribute for the user
PostSearchHook sub {my $attr = $_[4]->get(someldapattr);\

158 of 397

Radiator RADIUS Server

Configuration

$_[3]->get_reply->add_attr(Session-Timeout,\
$attr * 60);}

Hint: In order to get any attributes you may want to access in the PostSearchHook, you
will also need to add something like this to the AuthBy LDAP clause:
AuthAttrDef someldapattr,GENERIC,request

where someldapattr is the name of the LDAP attribute you are going to access in the
PostSearchHook.
5.38.23 Version

This optional parameter sets the LDAP version number to use. Currently supported values are 2 and 3. Defaults to 2. Setting Version to 3 may be useful for connecting to
Microsoft Active Directory. Available in AuthBy LDAP2 only. OpenLDAP 2 requires
Version 3 unless you have allow bind_v2 in your slapd.conf
# Support LDAP protocol version 3 as
# required by OpenLDAP 2 and others
Version 3
5.38.24 Deref

By default aliases are dereferenced to locate the base object for the search, but not when
searching subordinates of the base object. This may be changed by specifying the Deref
parameter with one of the following case sensitive values:

never
Do not dereference aliases in searching or in locating the base object of the search.

search
Dereference aliases in subordinates of the base object in searching, but not in locating the base object of the search.

find
Dereference aliases in locating the base object of the search, but not when searching
subordinates of the base object. This is the default.

always
Dereference aliases both in searching and in locating the base object of the search.
Hint: This is an advanced parameter. Most installations will not need to use it. Available
in AuthBy LDAP2 only.
5.38.25 AuthCheckDN

This optional parameter allows you to specify an alternate DN to use to check a users
password, instead of the one returned by the search result. Special formatting characters
are permitted, and %0 is replaced by the DN returned by the search.
Hint: This is an advanced parameter. Most installations will not need to use it. Available
in AuthBy LDAP2 only.
5.38.26 NoBindBeforeOp

This optional parameter prevents AuthBy LDAP2 from binding with the AuthDN and
password prior to a search operation.

Radiator RADIUS Server

159 of 397

Configuration

Hint: This is an advanced parameter. Most installations will not need to use it. Available
in AuthBy LDAP2 only.
5.38.27 UnbindAfterServerChecksPassword

This optional parameter works around problems with some LDAP servers. Normally,
when ServerChecksPassword is set, after Radiator checks a users password the LDAP
connection is not unbound. This can cause problems with some LDAP servers (notably
Oracle ID and Novell eDirectory), where they unexpectedly cause the following LDAP
query to fail with LDAP_INAPPROPRIATE_AUTH. Setting this flag causes an unbind
after each ServerChecksPassword bind.
5.38.28 MaxRecords

This optional parameter specifies the maximum number of matching LDAP records to
use for check and reply items. Default is 1 to be backwards compatible with earlier versions of AuthBy LDAP2. Only the first match (if any) is used for ServerChecksPassword. This parameter can be used to extract additional check and reply items from
LDAP records that define user roles.
5.38.29 GetNovellUP

This optional parameter can be used with the Novell eDirectory LDAP server to fetch
the users Universal Password and use it to authenticate the user. The eDirectory Universal Password is a single password for each user that can be used to authenticate a
range of Unix and Windows services. Normally it is not possible to fetch the users password from eDirectory, but GetNovellUP uses a special Novell API to fetch the users
plaintext password.
GetNovellUP will fetch the password if ServerChecksPassword is not set, and if PasswordAttr and EncryptedPasswordAttr are either not set or are not present in the users
LDAP record.
Passwords retrieved with GetNovellUP are in plaintext and are compatible with PAP,
CHAP, MSCHAP, MSCHAPV2, TLS, TTLS-*, PEAP-MSCHAPV2, EAP-MD5 etc.
The eDirectory server must be configured correctly before it will supply Universal Passwords to Radiator. The following conditions must be met.
1. An eDirectory Password Policy must be created and assigned to the group, organiza-

tional unit or organization that holds the users to be authenticated.

2. The Password Policy must have Universal Passwords enabled.
3. The password Policy must have Allow password retrieval by admin enabled.

See goodies/edirectory.txt for more details about how to install and configure eDirectory so that Radiator can use GetNovellUP successfully.
5.38.30 UseSASL

This optional parameter tells Radiator to request SASL authentication of the connection
to the LDAP server instead of the default simple authentication. AuthDN and AuthPassword will be used as the SASL credentials: AuthDN is the SASL user name and AuthPassword is the SASL users password.

160 of 397

Radiator RADIUS Server

Configuration

Requires the Authen-SASL-2.09 or later module from CPAN.

5.38.31 SASLMechanism

If UseSASL is enabled, this optional parameter specifies what SASL mechanism(s) are
to be used to authenticate the connection to the LDAP server. SASLMechanism is a
space separated list of mechanism names supported by Authen::SASL, such as

ANONYMOUS
CRAM-MD5
DIGEST-MD5
EXTERNAL
LOGIN
PLAIN.

Defaults to DIGEST-MD5. If you change this you may need to change your SASL to
LDAP user mapping. See your SASL system documentation for details on what mechanisms are supported.
SASLMechanism DIGEST-MD5,PLAIN
5.38.32 BindAddress

You can specify the local address for the client side of the LDAP connection with
BindAddress, in the form hostname[:port]. See Global parameters on page 28.
It will be used to set LocalAddr parameter of the underlying IO::Socket used as the
LDAP client. This is usually only useful on multihomed hosts, where you need to control the source address of the LDAP connection, perhaps for firewall rules.
5.38.33 Debug

Enables debugging of the Net::LDAP module. Sets the Net::LDAP debug parameter for
the connection, which prints to STDOUT. A bitmask with the following bits:
1
2
4
8

Show outgoing packets (using asn_hexdump).

Show incoming packets (using asn_hexdump).
Show outgoing packets (using asn_dump).
Show incoming packets (using asn_dump).

5.38.34 MultiHomed

This optional flag enables the MultiHomed option in Net::LDAP and IO::Socket for this
LDAP connection. If this is set then Net::LDAP will try all addresses for a multihomed
LDAP host until one is successful. Default is true (set).
5.38.35 GroupSearchFilter

For advanced applications, you can specify a search filter that Radiator will use to find
which user groups a user belongs to by using the optional GroupSearchFilter parameter.
It allows you to use arbitrarily complicated LDAP search filters to find the names of
user groups the user belongs to. Special formatting characters are permitted, and %0 is
replaced by UsernameAttr and %1 by the user name.

Radiator RADIUS Server

161 of 397

Configuration

5.38.36 GroupNameCN

When GroupSearchFilter is specified and Radiator looks for the user groups the user is a
member of, this parameter specifies the name of the Group name attribute in the LDAP
records. Defaults to "cn".
5.38.37 GroupBaseDN

When GroupSearchFilter is specified and Radiator looks for the user groups the user is a
member of, this parameter specifies an alternate LDAP base DN for the group search.
Defaults to the value of BaseDN.
5.39 <AuthBy SYSTEM>
AuthBy SYSTEM provides authentication with your getpwnam and getgrnam system
calls. On most Unix hosts, that will mean authentication from the same user database
that normal user logins occur from, whether that be /etc/passwd, NIS, YP, NIS+ etc. It is
implemented in AuthSYSTEM.pm. This allows you to hide whether its password files,
NIS+, PAM or whatever else might be installed on your system. It is not supported on
Windows, or on systems (such as Solaris) with shadow password files unless Radiator
runs with root permissions.
AuthBy SYSTEM honours the Group check item. The Group check item can match the
numeric or the symbolic group number of the primary or any secondary group.
AuthBy SYSTEM understands the following parameters as well as the generic ones
described in Section 5.21 on page 82.
5.39.1 UseGetspnam (deprecated)

On some operating systems (notably Solaris) AuthBy SYSTEM needs this parameter to
enable it to get the encrypted password from /etc/shadow or NIS+. You also need the
Shadows module from
ftp://ftp.eur.nl/pub/homebrew/Shadow-0.01.tar.gz or better.

Use this if you are running AuthBy SYSTEM on Solaris, or if Radiator reports Bad
Encrypted-Password even if you are sure the password and the shared secret are correct.
This parameter is deprecated and will be removed in a future version. It does not recognize password expiry dates. You should use UseGetspnamf instead.
# We are on Solaris, and have installed Shadows
UseGetspnam
5.39.2 UseGetspnamf

On some operating systems (notably Solaris) AuthBy SYSTEM needs this parameter to
enable it to get the encrypted password from /etc/shadow or NIS+. You also need the
Shadowf module from
ftp://ftp.eur.nl/pub/homebrew/Shadow-0.01.tar.gz or better.

162 of 397

Radiator RADIUS Server

Configuration

Use this if you are running AuthBy SYSTEM on Solaris, or if Radiator reports Bad
Encrypted-Password even if you are sure the password and the shared secret are correct.
This parameter will honour the password expiration date if there is one. It should be
used in preference to UseGetspnam, which is now deprecated.
# We are on Solaris, and have installed Shadowf
UseGetspnamf

5.40 <AuthBy TACACSPLUS>

AuthBy TACACSPLUS provides authentication via a TacacsPlus server. It supports
authentication only, not accounting or authorization. It requires the Authen::TacacsPlus
module from CPAN. You must use at least version TacacsPlus-0.15.tar.gz. Earlier versions will not work properly. If it is not available at CPAN, you can get it from the
authors at http://www.corbina.net/~msh/mytools/TacacsPlus-0.15.tar.gz. Version 0.15
will support PAP authentication only. Later versions will support both PAP and CHAP.
AuthBy TACACSPLUS understands the following parameters as well as the generic
ones described in Section 5.21 on page 82:
5.40.1 Host

This optional parameter specifies the name of the host where the TacacsPlus server is
running. It can be a DNS name or an IP address. Defaults to localhost.
Host oscar.open.com.au
5.40.2 Key

This mandatory parameter specifies the encryption key to be used to encrypt the connection to the TacacsPlus server. You must specify this. There is no default. It must
match the key specified in the TacacsPlus server configuration file.
# There is a line saying key = mytacacskey in my tac_plus
# config file
Key mytacacskey
5.40.3 Port

This optional parameter specifies the TCP port to be used to connect to the TacacsPlus
server. It can be a service name as specified in /etc/services or an integer port number.
Defaults to tacacs (TCP port 49). You should not need to change this unless your
TacacsPlus server is listening on a non-standard port.
5.40.4 Timeout

This optional parameter specifies the number of seconds timeout. Defaults to 15. You
would only need to change this under unusual circumstances.
5.40.5 AuthType

This optional parameter allows you to force the type of authentication to be used in the
Tacacs+ request sent to the Tacacs+ server. Options are PAP and ASCII. The default
is to choose PAP if the version of Authen::TacacsPlus is 0.16 or greater, otherwise
ASCII.
Radiator RADIUS Server

163 of 397

Configuration

# Force ASCII auth regardless of the version of

# Authen::TacacsPlus installed
AuthType ASCII

5.41 <AuthBy NISPLUS>

AuthBy NISPLUS provides authentication via your NIS+ database. It is implemented in
AuthNISPLUS.pm. It looks for user information in an NIS+ table, and uses that information as check and reply items for the user. It does not log (but does reply to) accounting requests. You will need to have a basic understanding of NIS+ databases in order to
configure AuthBy NISPLUS. AuthBy NISPLUS requires the NISPlus Perl module from
CPAN.
When AuthBy NISPLUS receives its first authentication request, it attempts to connect
to the NIS+ table defined by the Table parameter. AuthBy NISPLUS will then try to
fetch some fields for the user from the table. You can specify the query to use to locate
the user in the NIS+ table with the Query parameter. You also specify the NIS+ field
that contains the password, and (optionally) the names of fields containing an encrypted
password, RADIUS check items and RADIUS reply items. This scheme allows you to
work with almost any NIS+ table definition, however the defaults are set up so you can
authenticate from a standard NIS+ passwd table without having to add any special definitions.
If all the check items are satisfied by the request, AuthBy NISPLUS will reply with an
Access-Accept message containing all the attributes in the reply items (if any). If the
user does not appear in the NIS+ Table, or if any check item does not match, an AccessReject message is sent to the client.
AuthBy NISPLUS understands the following parameters as well as those described in
Section 5.21 on page 82:
5.41.1 Table

This optional parameter defines the name of the NIS+ table to search in. It defaults to
passwd.org_dir which is the name of the standard password table in NIS+. You
would not normally need to change this. You could define your own NIS+ table with
your own table structure to authenticate from, and define the name of the table with the
Table parameter. You might occasionally want to specify a table for a specific ___domain
with Table:
# Use the mydomain.com password table
Table passwd.org_dir.mydomain.com
5.41.2 Query

This optional parameter specifies how users are to be located in the NIS+ table. It is a
list of field=value pairs. You can use any of the special macros described in Section 5.2
on page 20. In addition, you can use %0 for the user name. The default is [name=%0],
which will find the user name in a standard NIS+ passwd table. You would only need to
define this if you define your own NIS+ table to authenticate from.
# Use cname and type in our own special table
Query [cname=%n,type=LOCAL]

164 of 397

Radiator RADIUS Server

Configuration

5.41.3 EncryptedPasswordField

This optional parameter specifies the name of the field in the NIS+ table that contains
the encrypted password for the user. It defaults to passwd, which is the name of the
password field in the standard NIS+ passwd table. Radiator will use this field as the
source of the encrypted password with which to check authentication requests.
If you define any AuthFieldDef parameters, EncryptedPasswordField will be ignored
completely, and you will have to define every check and reply item (including the
encrypted password) with an AuthFieldDef entry.
# Our special table has the password in pw
EncryptedPasswordField pw
5.41.4 AuthFieldDef

This optional parameter allows you to specify precisely how the fields in the NIS+ table
are to be interpreted. If any AuthFieldDef parameters are specified, EncryptedPasswordField will be completely ignored, and you will have to define every check and
reply item (including the encrypted password) with an AuthFieldDef entry.
You can specify as many AuthFieldDef parameters as you like, one for each check and
reply item in the NIS+ table.
You can specify any number of AuthFieldDef parameters, one for each interesting field
in the NIS+ table. The general format is:
AuthFieldDef fieldname,attributename,type

fieldname is the field in the NIS+ table that contains the value to check or reply. If
fieldname is not present in the NIS+ table, or is empty for the user, it wont be used.

attributename is the name of the radius attribute to be checked or replied. The special attributename GENERIC indicates that it is a list of comma separated attribute=value pairs, not just a single attribute

type indicates whether it is a check or reply item.

A few examples are in order:
Example 1
The standard NIS+ passwd table contains user name and encrypted password. You can
interface to such a table by having an empty AuthBy NISPLUS clause:
<AuthBy NISPLUS>
</AuthBy>

Just for illustration purposes, that is exactly equivalent to the following:

<AuthBy NISPLUS>
Table passwd.org_dir
Query [name=%n]
AuthFieldDef passwd,Encrypted-Password,check
</AuthBy>

Radiator RADIUS Server

165 of 397

Configuration

Example 2
You might define a special NIS+ table something like this: the table called users contains user names in the uname column, encrypted password in the pw column, and
an optional IP address to use in the address column:
<AuthBy NISPLUS>
Table users.org_dir
Query [uname=%n]
AuthFieldDef pw,Encrypted-Password,check
AuthFieldDef address,Framed-IP-Address,reply
</AuthBy>

5.42 <AuthBy PAM>

AuthBy PAM provides authentication via any method supported by PAM (Pluggable
Authentication Modules) on your host. It is implemented in AuthPAM.pm. It requires
that PAM be installed and configured on your host, and it also requires the Perl module
Authen-PAM-0.04 or later (available from CPAN).
AuthBy PAM asks PAM to authenticate the user using the PAM service specified with
the Service parameter (defaults to login).
AuthBy PAM has not been tested on Windows platforms.
Hint: make sure PAM is configured on your host before building and testing the
Authen-PAM Perl module, otherwise make test will report errors. This will usually
require configuring /etc/pam.conf, or perhaps /etc/pam.d/login for the
login service. For example, on our RedHat 5.2 Linux, we found that we had to remove
the pam_securetty from our /etc/pam.d/login file to enable testing from other
than a secure TTY. Consult your system documentation for details on configuring PAM.
AuthBy PAM understands the following parameters as well as those described in
Section 5.21 on page 82:
5.42.1 Service

This optional parameter specifies the PAM service to be used to authenticate the user
name. If not specified, it defaults to login.
# We want to use the PAM ppp service to authenticate our users
Service ppp
5.42.2 UsePamEnv

This optional parameter allow you to get UID, GID etc. if your PAM supports it, and
your Authen::PAM was compiled with -DHAVE_PAM_ENV_FUNCTIONS. This can
be useful with some PAM authenticators like Encotones TeleId, which can supply the
UID and GID of the user.

166 of 397

Radiator RADIUS Server

Configuration

If this parameter is set, AuthBy PAM will gather PAM Environment strings and use
them to set RADIUS reply attributes according to the following table:

TABLE 5.

How PAM Environment strings are converted to RADIUS reply attributes

PAM Env string

RADIUS reply attribute

UID

OSC-Uid

GID

OSC-Gid

HOME

OSC-Home

SHELL

OSC-Shell

5.42.3 PasswordPrompt

This optional parameter allows you to specify the prompt string which PAM uses to ask
for a password. Defaults to password. You may need to change this if your PAM module asks for data with a different prompt, such as Code.
5.43 <AuthBy ADSI>
AuthBy ADSI authenticates from Windows Active Directory, which is the user information database on Windows 2000 and later servers. It uses ADSI (Active Directory Service Interface) to get user information from any Active Directory service provider
available to your Windows server. It is only available on Windows 2000 and later server
platforms. It is implemented in AuthADSI.pm
ADSI is a unified interface to Windows user information that was introduced in Windows 2000. Active Directory can access user information from a range of provider
types:

NT Primary or Secondary ___domain controller (WinNT:)

Active Directory LDAP database (LDAP:)
Novell Directory Services (NDS:)
You can configure AuthBy ADSI to use any of these service providers.
More details about ADSI can be found at http://msdn.microsoft.com/library/psdk/adsi
During authentication, AuthBy ADSI check and honours AccountDisabled, IsAccountLocked and LoginHours for the user being authenticated. It also checks the users password (by attempting to change it). Because Active Directory does not make the
plaintext password available, <AuthBy ADSI> only supports PAP, not CHAP or
MSCHAP authentication.
AuthBy ADSI understands the following parameters as well as those described in
Section 5.21 on page 82:

Radiator RADIUS Server

167 of 397

Configuration

5.43.1 BindString

BindString is the string that defines what ADSI object will be bound in order to get user
details. You can bind to any Active Directory provider supported on your Radiator host,
but WinNT or LDAP will be the usual choices. BindString must specify which provider
to use and how to match the user. Use %0 to specify the user name to match.
WinNT means to use an NT 4.0 primary or backup ___domain controller, e.g.
WinNT:MyDomain/%0,User means to match Users in the Windows NT ___domain
called MyDomain. If the ___domain is omitted, the best ___domain controller in the default
___domain will be used.
Other acceptable variants are:
BindString WinNT://%0,User
BindString WinNT://___domain/%0,User
BindString WinNT://___domain/controller/%0,User

LDAP means to use an LDAP server, including Microsoft Exchange and Windows 2000
Active Directory e.g. LDAP://ldapsvr/cn=%n,cn=Users,dc=yourdomain,dc=com means to match a user with the given common name (cn), in the AD
___domain yourdomain.com. If ldapsvr is omitted, the default AD server will be used.
Other acceptable variants are:
BindString
BindString
BindString
BindString

LDAP://cn=%0.......
LDAP://controller/cn=%0.......
LDAP://msexchangeserver.bigco.com/cn=%0.......
LDAP://msexchangeserver:390/cn=%0.......

NDS means use Novell Directory Services. e.g.

NDS://MarsTree/O=MARS/OU=MARTIANS/CN=%0
The default is WinNT://%0,User which means a user with the given user name in
the default ___domain
# Get users from the OSC ___domain in NT
BindString WinNT://OSC/%0,User
# Get user details from the Users folder in Active Directory
# for the AD ___domain open.com.au
BindString LDAP://cn=%0,cn=Users,dc=open,dc=com,dc=au
5.43.2 AuthUser

This parameter defines how to construct the Active Directory user name to be authenticated by Active Directory. You can choose whether to use standard NTLM user names
or AD Distinguished Names. This is a different concept to BindString, which specifies
what AD object to get account details from.
The default is %0, which will try to authenticate the user name sent by the NAS (after
RewriteUsernames have been applied)

168 of 397

Radiator RADIUS Server

Configuration

This example will authenticate the user from an AD user record in the csx users Organizational Unit, and get account details from the same AD record. Unlike NTLM user
names, it will even work for user names with spaces in them. Note that you need to
specify AuthFlags of 0 in order to use an Active Directory DN in AuthUser.
BindString LDAP://cn=%0,ou=csx users,dc=open,dc=com,dc=au
AuthUser cn=%0,ou=csx users,dc=open,dc=com,dc=au
AuthFlags 0
5.43.3 AuthFlags

This optional parameter specifies flags to be passed to OpenDSObject. The default is 1,

which means NTLM secure authentication. For more details see http://msdn.microsoft.com/library/psdk/adsi/ds2_enum_760d.htm. You need to specify 0 to use an Active
Directory DN in AuthUser.
5.43.4 AuthAttrDef

This optional parameter allows you to use additional ADSI user information as
RADIUS check or reply items. This is most useful when you define new user attributes
in your Active Directory schema. It is beyond the scope of this document to describe
how to add new attributes to an Active Directory schema.
The general format is
AuthAttrDef

adsiname,radiusattr,type

adsiname is the name of an attribute in your Active Directory User schema. The value
of that attribute will be fetched using ADSI during authentication.
radiusattr is the name of the RADIUS attribute that the adsiname will be converted to.
check or reply item. The special radiusattr GENERIC indicates that it is
a list of comma separated attribute=value pairs, similar to ReplyAttr or CheckAttr.
type specifies whether to use the value as a check or reply item. type may be check,
reply or request. If type is request the value is saved in the current request, from
where it can be later collected with a special formatting macro like: %{attributename}.
For example,
AuthAttrDef address,Framed-IP-Address,reply

would get an attribute called address from the ADSI user record, and put it into
Framed-IP-Address attribute in the RADIUS reply. If address was not defined in your
schema, or there was no value defined for the user being authenticated, then Framed-IPAddress would not be set in the reply.
Multi-valued AD attributes can be used as check items, which results in Radiator passing the authentication if one of the multiple items matches. For example if you have this
in your AuthBy ADSI:
AuthAttrDef otherHomePhone,Calling-Station-Id,check

Radiator RADIUS Server

169 of 397

Configuration

and multiple entries in Home, Other.... tab of the Telephones tab. Then Radiator will
let the user log in if they call from any one of the Other Home Phone numbers.
5.43.5 GroupBindString

This optional parameter is used to generate an ADSI group identifier when checking
group membership through a Group= check item. Defaults to WinNT://%0,Group (i.e.
the named group in the default ___domain). Special characters can be used, and %0 is
replaced with the name of the group being checked, and %1 with the name of the user
whose group membership is being checked.
5.43.6 GroupUserBindString

This optional parameter is used to generate an ADSI user name identifier when checking group membership through a Group= check item. Defaults to WinNT://%1 (i.e. the
named user). Special characters can be used, and %0 is replaced with the name of the
group being checked, and %1 with the name of the user whose group membership is
being checked.
This example checks whether an NT user in the OSC ___domain is in an NT Group in the
OSC ___domain:
GroupBindString WinNT://OSC/%0,Group
GroupUserBindString WinNT://OSC/%1

This example checks whether the active directory user identified by GroupUserBindString is in the group defined by GroupBindString.
GroupBindString LDAP://cn=%0,dc=open,dc=com,dc=au
GroupUserBindString LDAP://cn=%1,cn=Users,dc=open,dc=com,dc=au

Hint: with AD, do not confuse Organizational Unit with group membership. They are
different ideas. A user can be in one OU, but be a member of multiple groups. Use
GroupBindString, GroupUserBindString and the Group= check item to check for AD
group members
5.43.7 CheckGroupServer

This optional parameter, in conjunction with CheckGroup, allows you to set a Class
reply attribute that depends on which NT group the user is a member of. CheckGroupServer is the name of an NT ___domain controller that contains group information.
<AuthBy ADSI>
CheckGroupServer brbaaa01
CheckGroup USVPN,ou=tcgic
CheckGroup UKVPN,ou=tcgic
....
</AuthBy>
5.43.8 CheckGroup

This optional parameter, in conjunction with CheckGroupServer, allows you to set a

Class reply attribute that depends on which NT group the user is a member of. Recall
that if you set the Class in an access reply, then subsequent accounting requests sent by
the NAS for that session will contain exactly the same Class attribute. This is useful for
remembering which accounting group or rate to charge the user.

170 of 397

Radiator RADIUS Server

Configuration

CheckGroup is a comma-separated pair of names. The first is an NT group name, the

second is an arbitrary string. During authentication, if the user is a member of the NT
group, then the Class attribute in the reply will be set to the arbitrary string. The first
match found will be used.
For example:
<AuthBy ADSI>
CheckGroupServer romeo
CheckGroup USVPN,premium
CheckGroup UKVPN,standard
....
</AuthBy>

In this example, if a user is a member of the NT group USVPN, then the reply will contain Class=premium. If they are in UKVPN group, then the reply will contain
Class=standard. If they are in neither group, then no Class will be set in the reply.
5.44 <AuthBy PORTLIMITCHECK>
AuthBy PORTLIMITCHECK can apply usage limits for arbitrary groups of users. It is
implemented in AuthPORTLIMITCHECK.pm. It requires that you have a <SessionDatabase SQL> defined in your Radiator configuration.
This module allows you to specify for example that up to 20 ports can be used by a customer with a certain DNIS, or 10 ports in one POP and 20 ports in another. Users can be
grouped by any attribute stored in your SQL Session Database.
Furthermore, you can arrange to set the Class attribute for the session depending on
bands of port usage. This could allow you to charge different amounts for the first 10
and the second 10 ports, for example, or to have a premium price for excessive port
occupancy. (The Class attribute set this way will be sent back by the NAS in all accounting requests for that session. You could then use the value of the Class attribute to tell
your billing system how much to charge for the session. The ability to actually charge
differently depends on the functions of your billing system.)
This module must be used in conjunction with some other module that actually performs the authentication of the user. PORTLIMITCHECK should be considered as a
pre-check to make sure that the login would be within the port occupancy limits you
have specified.
AuthBy PORTLIMITCHECK understands the following parameters as well as those
described in Section 5.21 on page 82:
5.44.1 CountQuery

This parameter specifies an SQL query that will be used to count the users currently
online according to the SQL Session Database. Defaults to select COUNT(*) from
RADONLINE where DNIS=%{Called-Station-Id}. AuthBy PORTLIMITCHECK
will compare the results of this query with SessionLimit in order to determine whether
the user will be permitted to log in at all.

Radiator RADIUS Server

171 of 397

Configuration

Hint: You must have a <SessionDatabase SQL> configured into Radiator. The Session
Database must be configured to save the columns that you plan to use to group users in
your CountQuery. So, if you are using the default CountQuery, your SQL Session Database must be configured to save the Called-Station-Id attribute to the DNIS column,
with something like:
<SessionDatabase SQL>
DBSourcedbi:mysql:radius
DBUsernamemikem
DBAuth
fred
# We want to save the DNIS as well as the usual
things.
# Requires a different schema to the example RADONLINE
# provided
AddQueryinsert into RADONLINE (USERNAME,\
NASIDENTIFIER, NASPORT, ACCTSESSIONID, TIME_STAMP,\
FRAMEDIPADDRESS, NASPORTTYPE, SERVICETYPE, DNIS) \
values (%n, %N,\
%{NAS-Port}, %{Acct-Session-Id}, %{Timestamp},\
%{Framed-IP-Address}, %{NAS-Port-Type}, \
%{Service-Type}, %{Called-Station-Id})
</SessionDatabase>
5.44.2 SessionLimit

This parameter specifies the absolute upper limit to the number of current logins permitted to this group of users. Defaults to 0. For example if SessionLimit is set to 10, then up
to 10 concurrent sessions are permitted. If an 11th user attempts to log in through this
AuthBy, they will be rejected. If LimitQuery is defined, and if it successfully gets an
integer from the database, then the result of the query will be used instead of SessionLimit. SessionLimit may contain special formatting characters.
# They have paid for 20 ports
SessionLimit20
5.44.3 ClassForSessionLimit

This optional parameter allows you to set up different charging bands for different levels of port occupancy in this group of users. You can have one or more ClassForSessionLimit lines. If the current level of port usage is below a ClassForSessionLimit, then the
class name will be applied as a Class attribute to that session. Your NAS will then tag all
accounting records for that session with the Class attribute. If your billing system
records and uses the Class attribute in accounting records, then you could use this to
charge differently for different levels of port occupancy.
# The first 2 users will be tagged with a Class of normal
# the next 2 with overflow. No more than 4 concurrent users
# permitted
SessionLimit 4
ClassForSessionLimit normal,2
ClassForSessionLimit overflow,4
5.44.4 LimitQuery

This optional parameter can be used to override the fixed session limit defined by SessionLimit. LimitQuery is an SQL query that is expected to return an integer that will be

172 of 397

Radiator RADIUS Server

Configuration

used as the limit instead of SessionLimit. If LimitQuery fails to execute, or if it does not
return any rows, then SessionLimit will be used as the limit instead.
LimitQuery select maxsessions from customers where\
dnis=%{Called-Station-Id}
5.44.5 IgnoreErrors

This optional parameter causes AuthBy PORTLIMITCHECK to IGNORE rather than

REJECT if the SQL query or SQL connection fails. It can be useful for recovering from
or working around SQL server failures.
5.45 <AuthBy DYNADDRESS>
AuthBy DYNADDRESS can be used to dynamically allocate IP addresses in conjunction with <AddressAllocator xxx> clauses. It is implemented in AuthDYNADDRESS.pm. At present, there are two Address Allocation engines provided.
<AddressAllocator SQL> (See Section 5.92 on page 264) can allocate addresses out of
an SQL database. <AddressAllocator DHCP> (See Section 5.93 on page 269) can allocate addresses from a DHCP server.
IP address allocation is usually the responsibility of your NAS, and most organizations
will wish to have address allocation done by their NASs. There are sometimes special
requirements that mean IP address allocation must be done by a central authority, and
AuthBy DYNADDRESS allows you to make your RADIUS server the address allocator. We recommend that, if possible, you should use your NASs native address allocation method to allocate IP addresses for your dialup users.
When using AuthBy DYNADDRESS, the usual arrangement is to make AuthBy DYNADDRESS the last AuthBy clause in a <Handler>. Some previous AuthBy clause(s)
would be responsible for authenticating the password of the user. Only if the authentication succeeds is AuthBy DYNADDRESS run and an address allocated.
It is common practice to maintain multiple IP address pools, with each pool used for a
different class of users, perhaps with different access controls. The features of AuthBy
DYNADDRESS allow you to control which address pool(s) to allocate addresses from,
and also how to translate an allocated address into a RADIUS reply attribute.
An example configuration file that does address allocation can be found in goodies/
addressallocator.cfg in the Radiator distribution.
AuthBy DYNADDRESS understands the following parameters as well as those
described in Section 6.15 on page 42:
5.45.1 AddressAllocator

This is the Identifier of an <AddressAllocator xxx>. It specifies which Address Allocation engine will be used to allocate the addresses. It must match the Identifier parameter
of an <AddressAllocator xxx> clause. Special formatting characters are permitted. The
named AddressAllocator will be used to allocate and deallocate addresses of all users
authenticated through this AuthBy.

Radiator RADIUS Server

173 of 397

Configuration

<AddressAllocator SQL>
Identifier SQLAllocator
DBSource ....
.....
</AddressAllocator>
<Handler>
AuthByPolicy ContinueWhileAccept
# This does the authentication
<AuthBy FILE>
Filename xxx
</AuthBy>
# If authentication succeeds, this allocates an
# address, using the AddressAllocator above
<AuthBy DYNADDRESS>
AddressAllocator SQLAllocator
</AuthBy>
</Handler>

Note. This parameter used to be called Allocator. This word is still supported but deprecated. Support will be removed some time in the future.

5.45.2 PoolHint

This optional parameter specifies how the pool hint is derived. A pool hint is generally
used by an AddressAllocator to determine which pool to allocate an address from. The
value of the pool hint will therefore depend on what type of Address Allocator you are
using, and usually which pools are available.
The default PoolHint (and the most common requirement) is %{Reply:PoolHint},
which means the pool hint is an attribute called PoolHint in the current reply. Presumably the PoolHint will have been set in the reply by some previous AuthBy clause. This
is easy to do for example in an AuthBy FILE, by adding the pool hint attribute to the
users file:
user1
user2

Password=x
PoolHint=pool1
Password=y
PoolHint=pool2

The PoolHint attribute will then be used by the Address Allocator to indicate which
pool to allocate from. The exact way the pool hint is used depends on the type of
Address Allocator you are using, so refer to the documentation for the Address Allocator.
Hint: If the pool hint resolves to an empty string, a DEBUG message will be issued, no
address will be allocated, but the request will be ACCEPTED. This allows you to
arrange for only some users to get an address allocated (and the NAS will allocate
addresses for the others).

174 of 397

Radiator RADIUS Server

Configuration

5.45.3 MapAttribute

This optional parameter allows you to specify how the results of the address allocation
are to be placed in the reply. If the yiaddr attribute (usually Framed-IP-Address) is
already set in the reply, then AuthBy DYNADDRESS will not allocate an address, and
will just ACCEPT the request. This means that if a user record has a fixed IP address in
it, then AuthBy DYNADDRESS will not allocate an address for that user.
Each MapAttribute specifies the name of the allocation variable, and the name of the
RADIUS attribute in which to place it (if it is not set already). The following allocation
variables are normally available. Some AddressAllocator clauses may not provide all of
these or may also make others available.

yiaddr, usually the allocated IP address in dotted quad format (e.g. 1.2.3.4)
subnetmask, usually the IP Subnet Mask in dotted quad format (e.g.
255.255.255.255)

dnsserver, usually the address of the DNS server to use in dotted quad format (e.g.
1.2.3.4) Only one DNS server address is permitted and supported.
The default behavior is to place the allocated IP address in Framed-IP-Address, and the
subnetmask in Framed-IP-Netmask. This is equivalent to:
MapAttribute yiaddr,Framed-IP-Address
MapAttribute subnetmask,Framed-IP-Netmask

5.46 <AuthBy ROUNDROBIN>, <AuthBy VOLUMEBALANCE>, <AuthBy

LOADBALANCE>, <AuthBy HASHBALANCE>, <AuthBy EAPBALANCE>
These authentication methods are sub-types of <AuthBy RADIUS> that also do load
distribution and balancing. They allow you to proxy RADIUS requests to any number of
remote RADIUS servers, and to distribute the RADIUS load amongst those servers (you
may wish to do this because your RADIUS authentication load exceeds that which can
be handled by a single server). Further, if any remote server fails to reply to a proxied
request, the remote server is marked as unavailable until the FailureBackoffTime
expires. During that period, no requests will be proxied to that remote RADIUS server.
5.46.1 <AuthBy ROUNDROBIN>

AuthBy ROUNDROBIN> distributes RADIUS requests according to the following

algorithm:
The first incoming RADIUS request is proxied to the first server listed, the next to the
second listed etc., until the list is exhausted, then it starts again at the top of the list. If at
any time a proxied request does not receive a reply from a remote server, that server is
marked as unavailable until FailureBackoffTime seconds has elapsed. Meanwhile that
request is retransmitted to the next host due to be used.
The result of this algorithm is to distribute the load equally amongst all the currently
operational remote RADIUS servers.

Radiator RADIUS Server

175 of 397

Configuration

5.46.2 <AuthBy VOLUMEBALANCE>

<AuthBy VOLUMEBALANCE> distributes RADIUS requests according to the following algorithm:

Incoming RADIUS requests are distributed between all the listed hosts according to the
relative values of their BogoMips attributes. BogoMips is intended to be a relative measure of the processing power of that host. A Host with a BogoMips rating of 2 will
receive twice as many request as one with the (default) BogoMips rating of 1. If at any
time a proxied request does not receive a reply from a remote server, that server is
marked as unavailable until FailureBackoffTime seconds has elapsed. Meanwhile that
request is retransmitted to the next host due to be used.
The result of this algorithm is to distribute the load amongst all the currently operational
remote RADIUS servers, according to the relative values of their BogoMips values.
See BogoMips on page 140 for configuring the BogoMips parameter.
AuthBy VOLUMEBALANCE recognizes an additional parameter:
5.46.3 MaxTargetHosts

Limits the number of different hosts a request will be proxied to in the case of no reply.
Defaults to 0 which mean no limit: if the load balancer does not receive a reply from a
host, it will keep trying until all hosts are exhausted.
5.46.4 <AuthBy LOADBALANCE>

<AuthBy LOADBALANCE> distributes RADIUS requests according to the following

algorithm:
Incoming RADIUS requests are distributed between all the listed hosts according to the
relative values of their BogoMips attributes and the time the remote server takes to process requests. BogoMips is intended to be a relative measure of the processing power of
that host. A Host with a BogoMips rating of 2 will receive twice as many requests as
one with the (default) BogoMips rating of 1 (all other things being equal). Every request
that is proxied and receives a reply has its turnaround time measured in microseconds. A
sliding average response time over the last 10 request is calculated. Requests are proxied to the server that is currently responding the fastest. If at any time a proxied request
does not receive a reply from a remote server, that server is marked as unavailable until
FailureBackoffTime seconds has elapsed. Meanwhile that request is retransmitted to the
next host due to be used.
The result of this algorithm is to distribute the load until the (BogoMips) weighted
response time is the same for all servers. This allows the load balancing to adapt to
changes in the available processing capacity of a remote host (perhaps due to other processes running on it).
See BogoMips on page 140 for configuring the BogoMips parameter.
Hint: You can find an example config file showing how to use various load balancing
modules in goodies/proxyalgorithm.cfg in the Radiator distribution.

176 of 397

Radiator RADIUS Server

Configuration

These authentication modules understand all the same parameters as <AuthBy

RADIUS> (see Section 5.31 on page 125). The only difference between them and
<AuthBy RADIUS> is the algorithm for choosing which remote host to proxy to.
Example. In this example, a Radiator running by itself on a host (perhaps in the demilitarized zone of your network) distributes RADIUS requests amongst 3 remote servers.
The second host has twice the processing power of the other 2, and therefore gets twice
as many requests as the other 2.
....
# Proxy all requests to remote hosts inside our network:
<Handler>
<AuthBy VOLUMEBALANCE>
# IF a host fails, dont send to it again
# for 100 seconds
FailureBackoffTime 100
# Default values for all hosts. You can
# change them for a single host in a Host
# clause
Secret mysecret
RetryTimeout 1
Retries 1
# Hosts to send to are listed below
<Host 203.63.154.2>
</Host>
<Host 203.63.154.3>
BogoMips 2
</Host>
# This host has non-standard ports
<Host 203.63.154.4>
AuthPort 1647
AcctPort 1648
</Host>
</AuthBy>
</Handler>

Hint: The default value for FailureBackoffTime of 0 will cause endless retransmission
of every packet until a reply is received.
5.46.5 <AuthBy HASHBALANCE>

<AuthBy HASHBALANCE> distributes RADIUS requests among a set of RADIUS

servers in such a way such that multiple related requests from the same user will go to
the same server (unless that server fails). This prevents the requests being distributed
among multiple servers, which might otherwise cause problems.
<AuthBy HASHBALANCE> distributes RADIUS requests according to the following
algorithm:
For each incoming request, a hash number is calculated from a number of attributes in
the incoming request. The hash number is used to select which host to use. If that Host
is unavailable, then the next one will be used in sequence until the Host list is exhausted.
This will result in random distribution of requests among the available server, and with
all requests related to a single user sent to the same server.
Radiator RADIUS Server

177 of 397

Configuration

The HashAttributes parameter specifies which attributes in the incoming request will be
used to select the server. Defaults to:
HashAttributes %{Request:Calling-Station-Id}:%n

which should be suitable for most applications.

Hint: in EAP capable environments and environments where all RADIUS clients are
known to support the RADIUS State attribute correctly, AuthBy HASBALANCE is
deprecated in favour of AuthBy EAPBALANCE, which has stronger protection for
EAP streams.
5.46.6 <AuthBy EAPBALANCE>

<AuthBy EAPBALANCE> is similar to <AuthBy HASHBALANCE> in that it is

intended to ensure that all EAP requests relating to a single session always go to the
same target RADIUS server. It uses the RADIUS State attribute to track EAP sessions,
and therefore relies on all the RADIUS clients supporting the State attribute correctly.
The target server for the first EAP request in a session is chosen in the same was as
<AuthBy HASHBALANCE>
<AuthBy EAPBALANCE> is to be preferred over <AuthBy HASHBALANCE> in
installations where all RADIUS clients are known to support the RADIUS State attribute correctly. This usually covers the network managed by a single organisation, but is
likely to not work with eduroam or other roaming services where remote or intermediate
proxies may add, change or remove the State attribute. With these services, HASHBALANCE with the default HashAttributes setting should ensure correct operation.
Caution: When EAPBALANCE is used in a ServerFarm architecture to proxy requests
to a set of back end RADIUS servers, the duplicate detection in the back end servers can
be defeated by changes to requests made by the server farm. It is therefore essential that
all the backend servers in such an architecture have the UseContentsForDuplicateDetection flag set in the receiving Client clauses.
5.47 <AuthBy OPIE>
This clause allows authentication from OPIE (One time Passwords In Everything), a
one-time password system based on S/Key, and written by Craig Metz. AuthBy OPIE
requires opie-2.4 or better and Authen::OPIE 1.0 from CPAN. OPIE is only supported
in Unix platforms. It can be used with PAP, but not CHAP or MS-CHAP. It can also be
used with EAP-One-Time-Passwords and EAP-Generic-Token-Card authentication in
802.1X wired and wireless networks.
OPIE is a one-time password system that prompts an intending user with a Challenge.
The user enters the challenge into a password calculator program which then tells them
the one-time password to use. A one-time password is 6 short words, separated by
spaces. A one-time password can only be used successfully once. Next time you log in,
you will be prompted with a different challenge and a different password will be
required. Opie can also generate lists of one-time-passwords that can be used in
sequence without prompts.

178 of 397

Radiator RADIUS Server

Configuration

AuthBy OPIE interfaces directly to OPIE using the OPIE Perl module. If you attempt to
log in with an empty password, AuthBy OPIE will issue an Access-Challenge, with the
Reply-Message containing the OPIE Challenge that must be entered into the password
calculator. The user can then use the Response from the calculator as the password for
the next attempt.
Caution: Not all PPP clients will show the user the contents of the Reply-Message. If
that is the case with your users, they will not be able to see the challenge, and hence will
not be able to log in with OPIE.
Hint: On Windows, in order to do interactive login, and so the end user can see the
OPIE challenge and enter the response, enable Show terminal window for the dial-up
connection.
When using AuthBy OPIE, Radiator must usually be run as root, so it can get access to
the OPIE password database, typically in /etc/opiekeys.
AuthBy OPIE understands no other parameters besides those described in Section 5.21
on page 82:
<Realm DEFAULT>
<AuthBy OPIE>
DefaultReply Service-Type=Framed-User,\
Framed-Protocol=PPP
</AuthBy>
</Realm>

5.48 <AuthBy LDAPRADIUS>

This clause proxies requests to one or more target RADIUS servers. The target host is
determined by a lookup in an LDAP database. This allows the easy management of
large numbers of downstream radius servers, such as in a wholesale ISP. It inherits from
both Ldap and AuthBy RADIUS.
AuthBy LDAPRADIUS runs the SearchFilter query to determine the details of the target RADIUS server until either an acknowledgment is received from the target or NumHosts is exceeded. This permits fallback radius servers to be configured.
SearchFilter can be configured to select the target RADIUS server based on any attribute in the incoming request. The default is the users Realm, but other possibilities,
such as Called-Station-Id may be more useful for your organization.
Hint: There is a sample LDAP schema for OpenLDAP in goodies/radiator-ldap.schema
in your Radiator distribution. This schema is compatible with the default behavior of
SearchFilter and HostAttrDef allowing the selection of a target host primary based on
Realm.
Hint: If SearchFilter fails to find any matching LDAP records, AuthBy LDAPRADIUS
will attempt to proxy according any <Host xxx> (see <Host xxxxxx> within <AuthBy
RADIUS> on page 139) clauses contained within the <AuthBy LDAPRADIUS>

Radiator RADIUS Server

179 of 397

Configuration

clause. This permits unknown realms to be proxied to a catchall target server, such as
GoRemote (GRIC), IPASS etc.
AuthBy LDAPRADIUS understands the following parameters.
5.48.1 SearchFilter

This parameter specifies the LDAP search filter that will be used to find the LDAP
records containing remote radius server data. The default is (oscRadiusTarget=%R),
which is compatible with the example schema provided in goodies/radiator-ldap.schema
in your Radiator distribution, and selects a record where oscRadiusTarget matches the
users realm. SearchFilter can contain any of the special characters defined in Special
characters on page 15. Also, %0 will be replaced by the number of times SearchFilter
has been called for this request, starting with 1. You can therefore use %0 to select a different record each time HostSelect is run for a given record, allowing you to choose,
say, primary or secondary server.
5.48.2 NumHosts

This parameter defines the maximum number of times that SearchFilter will be called
for as given request. If NumHosts is exceeded for a given request, the proxying of the
request fails. Defaults to 1. The current count is available as %0 in SearchFilter and
HostAttrDef.
5.48.3 HostAttrDef

This optional parameter specifies which parameters to get from an LDAP record and
how they are to be used to set the parameters of the Radiator Host clause for proxying.
Format is
HostAttrDef ldapattrname,hostparamname

where ldapattrname is the name of the LDAP attribute to fetch and hostparamname is
the name of the Radiator Host clause parameter it will be used to set. See <Host
xxxxxx> within <AuthBy RADIUS> on page 139 for details of the available hostparamname. If hostparamname is failurePolicy it will be used to specify how AuthBy
LDAPRADIUS will reply to the originating NAS if no reply is heard from any remote
server for this request. The following values are supported:

0 ACCEPT
1 REJECT
2 IGNORE
3 CHALLENGE

4 REJECT_IMMEDIATE
The default behaviour if no reply is heard from any remote server is to not reply to the
NAS. This will usually cause the NAS to re-send the request to its secondary RADIUS
server.
In HostAttrDef, the ldapattrname may contain special characters, and %0 is replaced by
hostCounter, an integer which starts at 1 and increases by one each time a search is
made for a given request. You can use that mechanism to fetch different LDAP attributes for the primary, secondary etc. RADIUS servers.

180 of 397

Radiator RADIUS Server

Configuration

If no HostAttrDef lines are specified, defaults to the equivalent of the following, which
is compatible the sample OpenLDAP schema in goodies/radiator-ldap.schema. Note
that not all LDAP parameters are required to be present. The minimum set required are
Host and Secret. Host can be an IPv4 or IPv6 address.
HostAttrDef oscRadiusHost,Host
HostAttrDef oscRadiusSecret,Secret
HostAttrDef oscRadiusAuthPort,AuthPort
HostAttrDef oscRadiusAcctPort,AcctPort
HostAttrDef oscRadiusRetries,Retries
HostAttrDef oscRadiusRetryTimeout,RetryTimeout
HostAttrDef oscRadiusUseOldAscendPasswords,UseOldAscendPasswords
HostAttrDef oscRadiusServerHasBrokenPortNumbers,ServerHasBrokenPortNumbers
HostAttrDef oscRadiusServerHasBrokenAddresses,ServerHasBrokenAddresses
HostAttrDef oscRadiusIgnoreReplySignature,IgnoreReplySignature
HostAttrDef oscRadiusFailurePolicy,failurePolicy
5.48.4 LDAP Server Connection parameters

A number of other parameters can be used to control where and how to connect to the
LDAP server. These parameters are described in Section 5.38, <AuthBy LDAP2>, on
page 149:

BaseDN
Scope
Host
Port
UseSSL
UseTLS
AuthDN
AuthPassword
Debug
Timeout
FailureBackoffTime
HoldServerConnection
NoBindBeforeOp
SSLVerify
SSLCiphers
SSLCAPath
SSLCAFile
SSLCAClientCert
SSLCAClientKey
Version

Radiator RADIUS Server

181 of 397

Configuration

Deref
UseSASL
SASLUser
SASLPassword
SASLMechanism

5.49 <AuthBy SQLRADIUS>

This clause proxies requests to a target RADIUS server. The target host is determined
by a table lookup in an SQL database. This allows the easy management of large numbers of downstream radius servers, such as in a wholesale ISP. It inherits from both
AuthBy SQL and AuthBy RADIUS.
AuthBy SQLRADIUS runs the HostSelect query to determine the details of the target
RADIUS server until either an acknowledgment is received from the target or NumHosts is exceeded. This permits fallback radius servers to be configured.
HostSelect can be configured to select the target RADIUS server based on any attribute
in the incoming request. The default is the users Realm, but other possibilities, such as
Called-Station-Id may be more useful for your organization.
Hint: There are example SQL table definitions in the goodies/*.sql scripts. These tables
will work with the default HostSelect allowing the selection of a target host primary and
secondary based on Realm.
Hint: If HostSelect fails to select any rows, AuthBy SQLRADIUS will attempt to proxy
according any <Host xxx> (see <Host xxxxxx> within <AuthBy RADIUS> on
page 139) clauses contained within the <AuthBy SQLRADIUS> clause. This permits
unknown realms to be proxied to a catchall target server, such as GoRemote (GRIC).
Historical Note: There was (and is) a similar module in goodies/AuthSQLRadius.pm,
that was contributed by Stephen Roderick ([email protected]). It has similar features
to AuthBy SQLRADIUS, but it is now obsolete.
AuthBy SQLRADIUS understands the following parameters from AuthBy SQL (see
Section 5.30 on page 111):

DBSource
DBUsername
DBAuth
Timeout
FailureBackoffTime
DateFormat

AuthBy SQLRADIUS also understands all the parameters from AuthBy RADIUS as
well as the following:

182 of 397

Radiator RADIUS Server

Configuration

5.49.1 HostSelect

This parameter defines the SQL statement that will be run to determine the details of the
target RADIUS server. It is run for each request that is handled by the AuthBy. If no
reply is received by the target RADIUS server for a given request, it will be rerun to find
a secondary server, and so on until either HostSelect returns no more rows, or the number of times exceeds NumHosts.
If HostSelect returns no rows, and if the AuthBy SQLRADIUS contains <Host xxx>
clauses, then the request will be proxied according to the <Host> clauses in order, the
same as with AuthBy RADIUS. This is a useful catchall for unknown realms, and could
be used to proxy to a GoRemote (GRIC) server or similar.
HostSelect is expected to return at least the target host name/address and the shared
secret in that order. Optionally, you can also fetch a number of other columns to control
the proxying process, including the RetryCount, target ports etc. The columns fetched
by HostSelect are used to determine the following AuthBy RADIUS Host parameters in
this order. Any column that is NULL is ignored.

target host name or IP address

Secret
AuthPort
AcctPort
Retries
RetryTimeout
UseOldAscendPasswords
ServerHasBrokenPortNumbers
ServerHasBrokenAddresses
IgnoreReplySignature
Failure policy. This is an integer in the range 0 to 4 inclusive that indicates what sort
of reply to send to the NAS in the event that proxying fails. 0 means ACCEPT, 1
means REJECT, 2 means IGNORE, 3 means CHALLENGE. You can use this to
determine how to handle the failure of a downstream radius server.

FailureBackoffTime
MaxFailedRequests
MaxFailedGraceTime
See <Host xxxxxx> within <AuthBy RADIUS> on page 139 for more details about
how these attributes are used to control proxying.
HostSelect can contain any of the special characters defined in Special characters on
page 20. Also, %0 will be replaced by the current host counter for this request. The
counter starts with the value of StartHost parameter which defaults to 1. You can therefore use %0 to select a different column each time HostSelect is run.
The default value is:

Radiator RADIUS Server

183 of 397

Configuration

HostSelect select HOST%0, SECRET, AUTHPORT, ACCTPORT,\

RETRIES, RETRYTIMEOUT, USEOLDASCENDPASSWORDS, \
SERVERHASBROKENPORTNUMBERS,SERVERHASBROKENADDRESSES, \
IGNOREREPLYSIGNATURE, FAILUREPOLICY from RADSQLRADIUS \
where TARGETNAME=%R

which will work with the example tables supplied in goodies/*.sql. Note that this allows
for up to 2 target hosts per Realm (i.e. primary and secondary), and that the Realm to
match goes in the TARGETNAME column.
Example: If you have a simple SQL table with one target host per Realm, AuthBy SQLRADIUS might contain:
HostSelect select HOST%0, SECRET, AUTHPORT, ACCTPORT, RETRIES,\
RETRYTIMEOUT, USEOLDASCENDPASSWORDS, \
SERVERHASBROKENPORTNUMBERS, SERVERHASBROKENADDRESSES, \
IGNOREREPLYSIGNATURE, FAILUREPOLICY from RADSQLRADIUS where \
TARGETNAME=%R
NumHosts 1

Advanced Example: If you want to choose the target RADIUS server based on CalledStation-Id and Realm, and multiple Called-Station-Ids can map to the same target
RADIUS servers, and if the target has a primary and a secondary RADIUS server, you
could use the example RADSQLRADIUS and RADSQLRADIUSINDIRECT tables,
plus an AuthBy SQLRADIUS containing:
HostSelect select R.HOST%0, R.SECRET, R.AUTHPORT, \
R.ACCTPORT, R.RETRIES, R.RETRYTIMEOUT, \
R.USEOLDASCENDPASSWORDS, R.SERVERHASBROKENPORTNUMBERS, \
R.SERVERHASBROKENADDRESSES, R.IGNOREREPLYSIGNATURE, \
R.FAILUREPOLICY from RADSQLRADIUS R, RADSQLRADIUSINDIRECT I \
where I.SOURCENAME=%{Called-Station-Id} and I.TARGETNAME=R.TARGETNAME
NumHosts 2

Technical Information: details about failure history, backoff times etc. are cached
within Radiator memory, not in the SQL database.
5.49.2 HostSelectParam

This optional parameter specifies a bind variable to be used with HostSelect. See
Section 5.4 on page 25 for information about how to use bind variables.
# Use bound parameters to improve performance in SQL
HostSelect select HOST%0, SECRET, AUTHPORT, ACCTPORT, RETRIES,\
RETRYTIMEOUT, USEOLDASCENDPASSWORDS, \
SERVERHASBROKENPORTNUMBERS, SERVERHASBROKENADDRESSES, \
IGNOREREPLYSIGNATURE, FAILUREPOLICY from RADSQLRADIUS where\
TARGETNAME=?
NumHosts 1
HostSelectParam %R

184 of 397

Radiator RADIUS Server

Configuration

5.49.3 NumHosts

This parameter defines the maximum number of times that HostSelect will be called for
as given request. If NumHosts is exceeded for a given request, the proxying of the
request fails. Defaults to 2. The current counter is available as %0 in HostSelect.
5.49.4 StartHost

StartHost sets the initial host number. Defaults to 1.

5.49.5 HostColumnDef

This optional parameter allows you to specify an alternate mapping between the fields
returned by HostSelect and the parameters used to define the Host. If HostColumnDef is
not specified, the mapping is the default as described in HostSelect above.
The format of a HostColumnDef parameter is:
HostColumnDef n,paramspec

Where n is the column number of the fields as returned by HostSelect (starting at 0), and
paramspec may be one of

Host,
failurePolicy
any valid Host parameter as described in the Host clause (see Section 5.32 on
page 139). Also StripFromRequest, RewriteUsername, AddToRequest.
In the following example, HostSelect returns five fields. The first defines the Host name
or address, the second is the shared secret for that host, the third is the maximum retry
count, and the fourth is the failure policy. The last is a comma-separated list of reply
items that will be added to the reply.
HostSelect select HOST%0, SECRET,RETRIES, FAILUREPOLICY,
ADDTOREQUEST from \
RADSQLRADIUS where TARGETNAME=%R
HostColumnDef 0, Host
HostColumnDef 1, Secret
HostColumnDef 2, Retries
HostColumnDef 3, failurePolicy
HostColumnDef 4, AddToRequest

Hint: If a Host has a FailurePolicy defined, and a NoReplyHook is defined, then the
NoReplyHook will be run before the automatic replies are sent.
5.50 <AuthBy INTERNAL>
This clause allows you permanently pre-define how to reply to a request, depending
only on the type of request. You can specify whether to ACCEPT, REJECT, IGNORE or
CHALLENGE each type of request. The default behaviour is to IGNORE all requests.
The following result codes are recognized. They are not case sensitive, and may be
embedded within a longer string:

ACCEPT
Radiator RADIUS Server

185 of 397

Configuration

REJECT
IGNORE
CHALLENGE
This clause can be useful in a number of cases:

As a fallback at the end of an AuthBy chain, so that if all your authentication methods are failing due to internal problems, you can let all users on, irrespective of password.

As a trap for certain types of requests, either in a distinct handler, or at the beginning
of a chain of AuthBy clauses.
Hint: The RADIUS protocol does not define an accounting reject message. For accounting requests, REJECT and CHALLENGE are the same as IGNORE.
Example: This clause will ACCEPT all Access Requests, ACCEPT Accounting Starts
and Stops, and REJECT everything else:
<AuthBy INTERNAL>
AuthResult
AcctStartResult
AcctStopResult
DefaultResult
</AuthBy>

ACCEPT
ACCEPT
ACCEPT
REJECT

AuthBy INTERNAL also supports a number of hooks. You can define a perl hook to
handle some or all requests. Requests that are not handled by a hook will be handled
according to the result code defined for that type of request. Hooks are passed information about the request, and the hook is expected to return one of:
$main::ACCEPT
$main::REJECT
$main::IGNORE
$main::CHALLENGE
$main::REJECT_IMMEDIATE

to indicate the result of the request. All hooks in AuthBy INTERNAL are passed the
same arguments in this order:

a reference to the current request, $p

a reference to the partly formed reply packet for $p
a (possibly zero length) array of additional check items. This can safely be ignored
in most circumstances.
Hint: AuthBy INTERNAL cannot be used to authenticate any EAP-TLS, TTLS or
PEAP protocols directly, but it can be used in conjunction with AuthBy FILE to achieve
the same thing:
<AuthBy INTERNAL>
Identifier myinternal
.....
</AuthBy>

186 of 397

Radiator RADIUS Server

Configuration

<Realm DEFAULT>
<AuthBy FILE>
Filename %D/users
EAPType TLS
.....

and in the users file:

DEFAULT Auth-Type=myinternal

This has the effect of using AuthBy FILE to do the EAP authentication handling, certificates etc., and the AuthBy INTERNAL to just authenticate the user name.
AuthBy INTERNAL understands the following parameters besides those described in
Section 5.21 on page 82:
5.50.1 DefaultResult

Specifies how to reply to any request for which there is no more specific result. The
default is to IGNORE.
# Accept everything not otherwise specified
DefaultResult ACCEPT
5.50.2 AuthResult

Specifies how to reply to all Access Requests. There is no default.

5.50.3 AcctResult

Specifies how to reply to all Accounting Requests for which there is no more specific
parameter. There is no default.
5.50.4 AcctStartResult

Specifies how to reply to all Accounting Start Requests. There is no default.

5.50.5 AcctStopResult

Specifies how to reply to all Accounting Stop Requests. There is no default.

5.50.6 AcctAliveResult

Specifies how to reply to all Accounting Alive Requests. There is no default.

5.50.7 RequestHook

This optional parameter allows you to define a perl program that will handle all requests
passed to this AuthBy INTERNAL.
5.50.8 AuthHook

This optional parameter allows you to define a perl program that will handle all AccessRequest requests passed to this AuthBy INTERNAL.
5.50.9 AcctHook

This optional parameter allows you to define a perl program that will handle all
Accounting-Request requests passed to this AuthBy INTERNAL.

Radiator RADIUS Server

187 of 397

Configuration

5.50.10 AcctStartHook

This optional parameter allows you to define a perl program that will handle all
Accounting-Request requests with an Acct-Type of Start passed to this AuthBy INTERNAL.
5.50.11 AcctStopHook

This optional parameter allows you to define a perl program that will handle all
Accounting-Request requests with an Acct-Type of Stop passed to this AuthBy INTERNAL.
5.50.12 AcctAliveHook

This optional parameter allows you to define a perl program that will handle all
Accounting-Request requests with an Acct-Type of Alive passed to this AuthBy
INTERNAL.
5.50.13 AcctOtherHook

This optional parameter allows you to define a perl program that will handle all
Accounting-Request requests with an Acct-Type other than Start, Stop and Alive passed
to this AuthBy INTERNAL.
5.50.14 OtherHook

This optional parameter allows you to define a perl program that will handle all requests
other than Access-Request and Accounting-Request passed to this AuthBy INTERNAL.
5.50.15 RejectReason

This optional parameter specifies a string which will be used as the Reply-Message if
the AuthBy INTERNAL rejects a request (the enclosing Realm or Handler must also
have RejectHasReason enabled for this to work).
RejectReason Your account has been disabled

5.51 <AuthBy POP3>

This clause authenticates from a POP3 server, according to RFC1939. It requires the
Mail::POP3Client perl module version 2.9 or better, available from CPAN. Supports
both plaintext and APOP authentication in the POP server. There is an example configuration file in goodies/pop3.cfg. AuthBy POP3 was mostly contributed by Karl Gaissmaier.
AuthBy POP3 can support SSL or non-SSL connections to the POP3 server. Use of SSL
connections requires IO::Socket::SSL from CPAN and OpenSSL.
AuthBy POP3 only supports PAP authentication in incoming RADIUS requests. CHAP
and MS-CHAP are not supported, since the plaintext password is not available within
Radiator.
AuthBy POP3 understands the following parameters besides those described in
Section 5.21 on page 82:

188 of 397

Radiator RADIUS Server

Configuration

5.51.1 Host

This parameter specifies the host name of the POP server. Defaults to pop3.
Host your.pop.server.com
5.51.2 Port

This optional parameter specifies the port number to contact on the POP server. Defaults
to 110, the standard pop3 port.
Port 9000
5.51.3 LocalAddr

Local host bind address.

5.51.4 AuthMode

This optional parameter specifies what types of POP authentication to permit.

PASS means use plaintext passwords

APOP means use APAP (MD5 encrypted) passwords
BEST means use APOP if possible, else PASS
Defaults to BEST.
AuthMode APOP
5.51.5 Timeout

This optional parameter specifies a timeout in seconds. If the connection to the POP
server is not complete within this time, the authentication will fail with REJECT.
Defaults to 10 seconds.
Timeout 2
5.51.6 LocalAddr

This optional parameter allows you to specify what local internet address (an optionally
port) to bind to. Format is xxx.xxx.xxx.xxx[:xx].
LocalAddr 203.63.154.2
5.51.7 Debug

If this optional parameter is set, Mail::POP3Client prints details of its transactions to

stdout.
5.51.8 UseSSL

This parameter forces AuthBy POP3 to use an SSL connection to the IMAP server. If
you wish to use UseSSL, you must also configure the SSL* parameters described
below.
5.51.9 SSLVerify

This optional parameter specifies what sort of SSL client verification that AuthBy POP3
will provide to the POP3 server. The options are none, optional or require. Defaults
to none.
SSLVerify require

Radiator RADIUS Server

189 of 397

Configuration

5.51.10 SSLCAFile

If you want to verify that the POP3 server certificate has been signed by a reputable certificate authority, then you should use this option to locate the file containing the certificate(s) of the reputable certificate authorities if it is not already in the OpenSSL file
certs/my-ca.pem. Special characters are permitted.
SSLCAFile %D/certificates/demoCA/cacert.pem
5.51.11 SSLCAPath

If you are unusually friendly with the OpenSSL documentation, you might have set
yourself up a directory containing several trusted certificates as separate files as well as
an index of the certificates. If you want to use that directory for validation purposes, and
that directory is not ca/, then use this option to specify the directory. There is no need to
set both SSLCAFile and SSLCAPath. Special characters are permitted.
SSLCAPath %D/cadirectory
5.51.12 SSLCAClientCert

This optional parameter specifies the ___location of the SSL client certificate that AuthBy
POP3 will use to verify itself with the POP3 server. If SSL client verification is not
required, then this option does not need to be specified. Special characters are permitted.
SSLCAClientCert %D/certificates/cert-clt.pem
5.51.13 SSLCAClientKey

This optional parameter specifies the ___location of the SSL private key that AuthBy POP3
will use to communicate with the POP3 server. If SSL client verification is not required,
then this option does not need to be specified. Special characters are permitted.
It is common for the SSL client private key to be in the same file as the client certificate.
In that case, both SSLCAClientCert and SSLCAClientKey will refer to the same file.
If SSLCAClientKey contains a private key in encrypted format, then you will need to
specify the decryption password in SSLCAClientKeyPassword.
SSLCAClientKey %D/certificates/cert-clt.pem
5.51.14 SSLCAClientKeyPassword

If the SSLCAClientKey contains an encrypted private key, then you must specify the
decryption password with this parameter. If a key is required, you will generally have
been given the password by whoever provided the private key and certificate.
SSLCAClientKeyPassword somepassword

5.52 <AuthBy IMAP>

This clause authenticates from an IMAP server. It requires the Mail::IMAPClient perl
module version 2.2.5 or better, available from CPAN. There is an example configuration
file in goodies/imap.cfg. AuthBy IMAP was mostly contributed by Karl Gaissmaier.
AuthBy IMAP can support SSL or non-SSL connections to the IMAP server. Use of
SSL connections requires IO::Socket::SSL from CPAN and OpenSSL.

190 of 397

Radiator RADIUS Server

Configuration

AuthBy IMAP only supports PAP authentication in incoming RADIUS requests. CHAP
and MS-CHAP are not supported, since the plaintext password is not available within
Radiator.
AuthBy IMAP understands the following parameters besides those described in
Section 5.21 on page 82:
5.52.1 Host

This parameter specifies the host name of the IMAP server.

Host your.imap.server.com
5.52.2 Port

This optional parameter specifies the port number to contact on the IMAP server.
Defaults to 143, the standard imap port.
Port 9000
5.52.3 LocalAddr

Local host bind address.

5.52.4 Timeout

This optional parameter specifies a timeout in seconds. If the connection to the IMAP
server is not complete within this time, the authentication will fail with REJECT.
Defaults to 10 seconds.
Timeout 2
5.52.5 Debug

If this optional parameter is set, Mail::IMAPClient prints details of its transactions to

stdout.
5.52.6 UseSSL

This parameter forces AuthBy IMAP to use an SSL connection to the IMAP server. If
you wish to use UseSSL, you must also configure the SSL* parameters described
below.
5.52.7 SSLVerify

This optional parameter specifies what sort of SSL client verification that AuthBy
IMAP will provide to the IMAP server. The options are none, optional or require.
Defaults to none.
SSLVerify require
5.52.8 SSLCAFile

If you want to verify that the IMAP server certificate has been signed by a reputable certificate authority, then you should use this option to locate the file containing the certificate(s) of the reputable certificate authorities if it is not already in the OpenSSL file
certs/my-ca.pem. Special characters are permitted.
SSLCAFile %D/certificates/demoCA/cacert.pem

Radiator RADIUS Server

191 of 397

Configuration

5.52.9 SSLCAPath

If you are unusually friendly with the OpenSSL documentation, you might have set
yourself up a directory containing several trusted certificates as separate files as well as
an index of the certificates. If you want to use that directory for validation purposes, and
that directory is not ca/, then use this option to specify the directory. There is no need to
set both SSLCAFile and SSLCAPath. Special characters are permitted.
SSLCAPath %D/cadirectory
5.52.10 SSLCAClientCert

This optional parameter specifies the ___location of the SSL client certificate that AuthBy
IMAP will use to verify itself with the IMAP server. If SSL client verification is not
required, then this option does not need to be specified. Special characters are permitted.
SSLCAClientCert %D/certificates/cert-clt.pem
5.52.11 SSLCAClientKey

This optional parameter specifies the ___location of the SSL private key that AuthBy IMAP
will use to communicate with the IMAP server. If SSL client verification is not required,
then this option does not need to be specified. Special characters are permitted.
It is common for the SSL client private key to be in the same file as the client certificate.
In that case, both SSLCAClientCert and SSLCAClientKey will refer to the same file.
If SSLCAClientKey contains a private key in encrypted format, then you will need to
specify the decryption password in SSLCAClientKeyPassword.
SSLCAClientKey %D/certificates/cert-clt.pem
5.52.12 SSLCAClientKeyPassword

If the SSLCAClientKey contains an encrypted private key, then you must specify the
decryption password with this parameter. If a key is required, you will generally have
been given the password by whoever provided the private key and certificate.
SSLCAClientKeyPassword somepassword

5.53 <AuthBy LSA>

This module provides authentication against user passwords in any Windows Active
Directory or NT Domain Controller, by using the Windows LSA (Local Security
Authority). Since it accesses LSA directly, it can authenticate dialup or wireless passwords with PAP, CHAP, MSCHAP, MSCHAPV2, LEAP and PEAP.
AuthBy LSA is only available on Windows XP/Vista/7/8 and Server 2003/2008/2012
(Home editions are not supported). It requires the Win32-Lsa Perl module from Open
System Consultants. Install the Win32-Lsa perl module using PPM and ActivePerl or
Strawberry Perl 5.6, 5.8, 5,10, 5.12, 5.14 or 5.16 like this:
ppm install http://www.open.com.au/radiator/free-downloads/Win32-Lsa.ppd

To use AuthBy LSA, Radiator must be run on Windows as a user that has the Act as
part of the operating system security policy (SE_TCB_PRIVILEGE) enabled. This is
not possible with Home editions.
192 of 397

Radiator RADIUS Server

Configuration

Hint: Users can only be authenticated with AuthBy LSA if they have the Access this
computer from the network security policy enabled (this is the normal configuration for
Windows Domains). AuthBy LSA honours the Logon Hours, Workstation Restrictions
and Account is Disabled flags in user accounts.
Hint: CHAP passwords can only be authenticated if the user has the Store password
using reversible encryption option enabled in their Windows Account.
Hint: See goodies/lsa.cfg and goodies/lsa_eap_peap.cfg for examples on how to configure Radiator to authenticate PAP, CHAP, MSCHAP, MSCHAPV2, LEAP and PEAP
against Windows user passwords.
Hint: If you are running Radiator on unix or Linux, and wish to authenticate to Windows Active Directory or to a Windows Domain Controller, see <AuthBy NTLM> on
page 228.
The <AuthBy LSA> clause understands the following parameters:
5.53.1 Domain

This optional parameter specifies which Windows ___domain will be used to authenticate
passwords, regardless of whether the user supplies a ___domain when they log in. It can be
the name of any valid ___domain in your network. The default is to authenticate against
local accounts on the machine that Radiator is running on. Special characters are permitted.
Domain OPEN
5.53.2 DefaultDomain

This optional parameter specifies the Windows Domain to use if the user does not specify a ___domain in their username. Special characters are supported. Can be an Active
directory ___domain or a Windows NT ___domain controller ___domain name. Empty string (the
default) means the local machine.
DefaultDomain OPEN
5.53.3 Workstation

This optional parameter specifies a workstation name that will be used to check against
workstation logon restrictions in the users account. If the user has any workstation
restrictions specified in their account, this is the workstation name that will be used to
check the restriction. Defaults to an empty string, which means that LSA will not check
any workstation logon restrictions.
Workstation WLAN
5.53.4 ProcessName

This optional parameter specifies a process name for LSA internal logging. Defaults to
Radiator.
5.53.5 Origin

This optional parameter specifies a request origin name for LSA internal logging.
Defaults to Radiator.

Radiator RADIUS Server

193 of 397

Configuration

5.53.6 Source

This optional parameter specifies a source name for LSA internal logging. Defaults to
Radiator.
5.53.7 Group

This optional parameter allows you to specify that each user must be the member of at
least one of the named Windows Global or Local groups. More than one required group
can be specified, one per Group line. Requires Win32::NetAdmin (which is installed by
default with ActivePerl). If no Group parameters are specified, then Group checks will
not be performed.
# Each user must be in Administrators and/or Domain Users
Group Administrators
Group Domain Users
5.53.8 DomainController

This optional parameter is used only if one or more Group check parameters are set. It
specifies the name of the Windows Domain Controller that will be used to check each
users Group membership. If no Group parameters are specified, DomainController will
not be used. Defaults to empty string, meaning the default controller of the host where
this instance of Radiator is running.
5.54 <AuthBy SOAP>
This module handles authentication and accounting by sending it to a remote RADIUS
server over TCP using the SOAP protocol. Each RADIUS request is transformed into a
SOAP request, which is sent by HTTP or HTTPS to a remote SOAP server. The Remote
SOAP server can be any implementation, but example SOAP server code is provided
with Radiator.
AuthBy SOAP can be useful in order to tunnel RADIUS requests through ports 80 or
443 in a firewall, where UDP port 1645 is not permitted thought the firewall. It can also
be used to improve reliability in some environments by using TCP rather than UDP.
And RADIUS security can be improved by using HTTPS as the transport protocol,
which will encrypt all the contents of the RADIUS request. Requires the SOAP::Lite
perl module and its prerequisites.
AuthBy SOAP uses a simple SOAP interface. An example Web Service Description
Language file (goodies/soaprequest.wsdl) is provided for people wishing to implement
their own SOAP RADIUS client.
Included with Radiator is a sample SOAP server CGI script and a SOAP handler module. The file goodies/soapradius.cgi receives SOAP radius requests as sent by AuthBy
SOAP and invokes Radius::SOAPRequest::radius(), which is provided by Radius/
SOAPRequest.pm. SOAPRequest transforms incoming SOAP requests into standard
RADIUS requests and sends them to a RADIUS server. The RADIUS reply is sent back
to AuthBy SOAP as the SOAP reply. In order to install the SOAP server, you will need
to edit SOAPRequest.pm and specify the ___location of your RADIUS dictionary, and the
address and port of the destination RADIUS server. The address defaults to localhost:1647. You must also install soapradius.cgi in a suitable ___location in your web

194 of 397

Radiator RADIUS Server

Configuration

servers CGI directory. You may also need to edit soapradius.cgi if your Radiator per
modules are not installed in the usual place.l
Hint: see goodies/soap.cfg for an example configuration file.
AuthBy SOAP understands the following parameters:
5.54.1 Endpoint

With this parameter, you can specify any number of SOAP proxy points. AuthBy SOAP
will try to contact each one in turn until the SOAP call succeeds in getting a reply.
Defaults to http://localhost/cgi-bin/soapradius.cgi.
Endpoint https://your.server.com/cgi-bin/soapradius.cgi
5.54.2 URI

This parameter specifies the SOAP URI that AuthBy SOAP will try to run. This is not a
URL. It is used by the server to deduce the right SOAP module to load. You should not
need to change this. Defaults to http://www.open.com.au/Radius/SOAPRequest.
5.54.3 SOAPTrace

This enables some or all of the SOAP::Lite internal tracing. Allowable values are

transport
dispatch
result
parameters
headers
objects
method
fault
freeform
trace
debug

all
or any combination. Defaults to no tracing. Tracing is printed to STDOUT.
SOAPTrace all
5.54.4 Timeout

With this optional parameter, you can control how long to wait for the SOAP reply from
the SOAP server. Time is in seconds. Defaults to 3 seconds.
5.55 <AuthBy OTP>
This module is extensible and customizable to support a range of One-Time-Password
(OTP) schemes, including automatic password generation and sending of passwords
through a back-channel such as SMS. AuthBy OPT is suitable for authenticating

Radiator RADIUS Server

195 of 397

Configuration

802.1X Wired and Wireless access with custom one-time-password and token card
authentication systems.
The default behavior of AuthBy OTP demonstrates how it can be used and tested, but it
is not suitable for use in a production environment: it tells the user the correct password
in the challenge. In almost all cases, you will need to develop at least your own ChallengeHook, and possible a VerifyHook to work with your local system.
In the most common use of AuthBy OTP, it will be configured to generate a random
password (according to a configurable password pattern) and then send it to the user by
SMS or some other channel. AuthBy OTP will then challenge the user to enter the correct password (after they have received it through the SMS system or whatever). In
order to achieve this, you must configure at least the ChallengeHook to call some external program that will deliver the password to the user.
AuthBy OTP works with EAP-OTP (One-Time-Password), EAP-GTC (Generic-TokenCard) as well as standard RADIUS PPP dialup. Caution: most PPP clients and modems
do not handle OTP challenges very well. AuthBy OTP supports PPP dialup in the following way: if the user attempts to log in with an empty (zero length) password, the
ChallengeHook will be called and the challenge will be sent back to the PPP client. This
may result in a message for the user, but often does not, depending on the PPP client on
the users computer.
Hint: see goodies/otp.cfg for an example configuration file.
Hint: You can test AuthBy OTP with the following radpwtst commands:
# Conventional RADIUS PPP
radpwtst -noacct -interactive -password
# EAP-OTP authentication
radpwtst -noacct -eapotp
# EAP-GTC auth (with EAPType set to Generic-Token):
# radpwtst -noacct -eapgtc

Hint: See <AuthBy OPIE> on page 178 for a one-time-password system that works
with PPP dialup as well as EAP-OTP and EAP-GTC using the well known OPIE onetime-password system.
AuthBy OTP understands the following parameters:
5.55.1 ChallengeHook

ChallengeHook is a fragment of perl code that is expected to generate a OTP (if necessary) save the OTP (in $context is sometimes convenient) and send the OTP to the user
by a back channel (if necessary). It should return a challenge string that will be presented to the user by the client, informing them of how to get or generate their password.
It is passed the following arguments:

reference to the current AuthBy module object

user name
196 of 397

Radiator RADIUS Server

Configuration

current RADIUS request packet

a user context that will be available later in VerifyHook. It can be used to store information such as the correct password until later in the authentication process.
The default ChallengeHook generates a random password according to PasswordPattern, saves it in the context and returns a challenge message telling the user what the
correct password is. The default ChallengeHook must not be used in a production environment.
This example shows how to generate a random password and pass it to an external program which must deliver it to the user through some back channel like SMS. The example just echoes it to stdout. You can see that the generate_password() function can be
used to generate a random password that conforms to PasswordPattern. The password is
stored in the context so it can be checked later in the VerifyHook
ChallengeHook sub {my ($self, $user, $p, $context) = @_;\
$context->{otp_password} = $self->generate_password();\
system(/bin/echo, "in sample ChallengeHook for", \
$user, "password is", $context->{otp_password});\
return "Your OTP password has been printed by Radiator on STDOUT";}

5.55.2 VerifyHook

VerifyHook is a fragment of perl code that is expected to validate a OTP and return 1 on
success. You will need to specify your own VerifyHook if you require an external program to verify the correct OTP.
VerifyHook is passed the following arguments:

reference to the current AuthBy module object

user name
the submitted OTP password in plaintext
current RADIUS request packet
the same user context that was passed to ChallengeHook for this user when the challenge was generated. $context->{otp_password} will generally contain the correct
plaintext password for this user.

The default VerifyHook compares the submitted password to

$context->{otp_password}
This example VerifyHook only accepts the password xyzzy
VerifyHook sub {my ($self,$user,$submitted_pw,$p,$context)=@_;\
return $context->{otp_password} eq xyzzy;}
5.55.3 PasswordPattern

This optional parameter specifies a character pattern that will be used to generate random passwords by generate_password() and the default ChallengeHook.

Radiator RADIUS Server

197 of 397

Configuration

a lowercase alphanumeric (abcdefghijklmnopqrstuvwxyz0123456789)

A uppercase alphanumeric (ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789)

c lowercase consonant (bcdfghjklmnpqrstvwxyz)

C uppercase consonant (BCDFGHJKLMNPQRSTVWXYZ)
v lowercase vowel (aeiou)
V uppercase vowel (AEIOU)
9 numeric (0123456789)
anything else is used literally

The default is cvcvcvc99 which produces passwords like:

vosuyic04
rezeqek86
jocupon50
etc.
5.55.4 ContextTimeout

This optional parameter specifies how long (in seconds) the context passed to ChallengeHook for a user will be kept. It defaults to 120 seconds, which is expected to be
enough time for most users to receive and enter their correct OTP. You should not need
to change this.
5.56 <AuthBy RSAMOBILE>
This module permits authentication from an RSA Mobile server. RSA Mobile is a token
authentication system from RSA Security. During authentication, the user provides a
password, then the RSA Mobile server sends a one-time-password by SMS, pager etc.
When the correct one-time-password is entered, then the authentication succeeds.
Hint: AuthBy RSAMOBILE is deprecated when used with RSA Authentication Manager 7.1 and later. If you have AM 7.1 or later you should use <AuthBy RSAAM>,
since it is more capable and more portable.
The <AuthBy RSAMOBILE> module is compatible with Radius-PAP, EAP-GenericToken-Card and EAP-PEAP-Generic-Token-Card authentication. It requires
SOAP::Lite and all its prerequisites from CPAN.
There is an example configuration file in goodies/eap_gtc_rsamobile.cfg in the Radiator
distribution showing how to configure Radiator to authenticate EAP-GTC using RSA
Mobile.
Caution: on some platforms and networks, the performance of the SOAP protocol used
by RSA Mobile can be poor. You should test <AuthBy RSAMOBILE> in your particular situation to confirm that it will meet your authentication volume requirements before
deploying it in production.
AuthBy RSAMOBILE understands the following parameters:

198 of 397

Radiator RADIUS Server

Configuration

5.56.1 Endpoint

This optional parameter specifies how to create the endpoint of the SOAP connection to
the RSA Mobile server. Special characters are permitted. %0 is replaced by the value of
the Protocol parameter (see Section 5.56.2 on page 199) and %1 is replaced by the value
of the Host parameter (see Section 5.56.2 on page 199). The default is
%0://%1/axis/services/AuthenticationAPI.
You should not normally need to change this.
5.56.2 Protocol

This optional parameter specifies the protocol that will be used to contact the RSA
Mobile server. It is used as %0 in the Endpoint parameter. The default is http. You
should not normally need to change this.
5.56.3 Host

This parameter specifies the address and port number of the RSA Mobile server. It is
used as %1 in the Endpoint parameter. The default is localhost:7001. You will usually
have to change this to the address and port number of your RSA Mobile server. 7001 is
the usual port number for RSA Mobile.
5.56.4 URI

This optional parameter specifies the SOAP URI that will be accessed in the RSA
Mobile server. The default is http://rsa.com/csf/clientservice/authenticationapi/AuthenticationAPI. You should not normally need to change this. Note that this is not the
address of a web resource and it is not accessed by Radiator during authentication.
5.56.5 Policy

This optional parameter specifies the authentication policy that is to be requested. The
RSA Mobile server can be configured to permit password or RSA SecurID authentication as well as RSA Mobile authentication. The permitted options are:

*System Policy: Password Only

*System Policy: RSA Mobile Only
*System Policy: RSA SecurID Only
*System Policy: RSA SecurID OR Password

The default is *System Policy: RSA Mobile Only

This example changes the requested policy to password only:
Policy *System Policy: Password Only
5.56.6 Resource

This optional parameter specifies an alternate resource for the RSA Mobile server to use
to authenticate each user. The default is an empty string. See your RSA Mobile administrator for information about what resources are available. You should not normally need
to set this parameter.
5.56.7 Lang

This optional parameter permits an alternate language to be specified for the RSA
Mobile server to use for the password prompts to be sent to the user. The default is
Radiator RADIUS Server

199 of 397

Configuration

empty string. See your RSA Mobile administrator for information about what Lang
options are available. You should not normally need to set this parameter.
5.56.8 Country

This optional parameter permits an alternate language to be specified for the RSA
Mobile server to use for the password prompts to be sent to the user. The default is
empty string. See your RSA Mobile administrator for information about what Lang
options are available. You should not normally need to set this parameter.
5.56.9 SessionUsername

This parameter specifies a username that will be used to contact the RSA Mobile HTTP
server. The default is authapiuser, which is the same as the default that is installed on
the RSA Mobile HTTP server. You will almost certainly have to set this to suit the configuration of your RSA Mobile server. See your RSA Mobile administrator for information about what the RSA Mobile Server HTTP access password and username is.
5.56.10 SessionPassword

This parameter specifies the password that will be used to contact the RSA Mobile
HTTP server. The default is changeit, which is the same as the default that is installed
on the RSA Mobile HTTP server. You will almost certainly have to set this to suit the
configuration of your RSA Mobile server. See your RSA Mobile administrator for information about what the RSA Mobile Server HTTP access password and username is.
5.56.11 SessionRealm

This optional parameter specifies the HTTP Realm that the SessionUsername and SessionPassword will be used for. The default is weblogic, which matches the RSA
Mobile Server SOAP implementation. You should not normally need to set this parameter.
5.56.12 Timeout

This optional parameter specifies the timeout in seconds that will be used during
authentication requests sent by Radiator to the RSA Mobile server. The default is 20
seconds.
5.56.13 SOAPTrace

This optional parameter enables low level protocol tracing in the SOAP::Lite module.
Setting it to 1 will cause details of each incoming and outgoing SOAP request to be
printed on STDOUT.
5.57 <AuthBy RSAAM>
This module provides authentication via RSA Authentication Manager AM 7.1 and
later. AM 7.1 provides more features than the ACE server and RSA Mobile servers it
replaces. <AuthBy RSAAM> supports more features than either <AuthBy ACE> or
<AuthBy RSAMOBILE>. Therefore <AuthBy RSAAM> may be your preferred module for use with AM 7.1 or later.
AM 7.1 supports traditional SecurID two-factor token cards, as well as static passwords.
It also supports OnDemand tokencodes, where a random tokencode is sent to the user

200 of 397

Radiator RADIUS Server

Configuration

via email or SMS. It also supports authentication through a series of user-configurable

security questions. All these authentication methods are supported by AuthBy RSAAM.
AuthBy RSAAM can authenticate the following protocols against AM. Note that
CHAP, MSCHAPV1, MSCHAPV2 and EAP-MSCHAPV2 cannot be authenticated
against AM.

PAP
TTLS-PAP
EAP-GTC
EAP-OTP
PEAP-GTC

AuthBy RSAAM works on all platforms supported by Radiator, including Windows,

Linux, Solaris, Unix etc. AuthBy RSAAM connects the AM server by SSL and SOAP,
and therefore required the following Perl modules from CPAN:

SOAP::Lite and its prerequisites

Either Crypt::SSLeay or IO::Socket::SSL
Net::SSLeay
Hint: Sample configuration files are provided in the goodies directory of your distribution in rsaam.cfg and eap_peap_gtc_rsaam.cfg.
Hint: RSA AM is not able to specify the preferred authentication policy to use for each
user. Therefore, if you need to use different authentication policies for different groups
of user, you will need an <AuthBy RSAAM> clause for each policy, and then direct
requests to the appropriate clause using one of the many methods supported by Radiator.
Hint: AuthBy RSAAM returns IGNORE if it unable to communicate with its configured AM server. This means you can chain several AuthBy RSAAM clauses together
using AuthByPolicy ContinueWhileIgnore to implement failover from one AM server
to another in the event of AM server unavailability.
Hint: In some circumstances, The Radiator connection to RSA AM may fail with an
error message in the RSA Weblogic server like:
Received fatal alert: bad_record_mac at sun.reflect.NativeConstructorAccessorImpl.newInstance0

This can be fixed by adding these lines to the weblogic server start file:
-Dhttps.protocols=SSLv3,TLSv1
-Dsun.security.ssl.allowLegacyHelloMessages=true
-Dsun.security.ssl.allowUnsafeRenegotiation=true
5.57.1 Configuring Authentication Manager for AuthBy RSAAM

In order to configure Authentication Manager to work with AuthBy RSAAM:

Radiator RADIUS Server

201 of 397

Configuration

1. Install RSA AM 7.1 on your platform of choice, or

Install 8.0 virtual appliance

2. Install Radiator on your platform of choice. It may be the same as the AM 7.1 host,

or a different one in case of AM 8.0.

3. Install SOAP::Lite and its prerequisites on the Radiator host.
4. Starting with one of the sample RSAAM configuration files, configure Radiator.
5. Get the username and password required for AuthBy RSAAM to connect to AM.

These commands will print out the username and password that AM automatically
generates during installation.
Do this on AM7.1 or earlier.
cd "C:\Program Files\RSA Security\RSA Authentication
rsautil manage-secrets -m <MASTERPWD> -a list

Manager\Utils

Do this on AM 8.0
cd /opt/rsa/am/utils
./rsautil manage-secrets --action list

This will print out the username and password required for Radiator to connect to
AM 7.1 or 8.0. Enter the username and password as SessionUsername and SessionPassword in your Radiator configuration file.
6. Select which authentication method you will use to authenticate all your users. Set

Policy in your Radiator configuration file.

7. Set Host in your Radiator configuration file to the FQDN (fully qualified ___domain

name) and port number of your AM host. For example

Host boodgie.open.com.au:7002
8. Add and configure a test user to AM. If required allocate a token to the user
9. Start Radiator and test with a command like:

radpwtst -noacct -user username -password password -interactive -timeout 60

AuthBy RSAAM understands the following parameters:
5.57.2 Host

This parameter specifies the address and port number of the RSA AM server. It is used
as %1 in the Endpoint parameter. The default is "localhost:7002". You will have to
change this to the hostname/address and port number of your RSA AM server, since by
default AM does not listen on localhost. 7002 is the usual port number for RSA AM.
5.57.3 Endpoint

This optional parameter specifies how to create the endpoint of the SOAP connection to
the RSA AM server. Special characters are permitted. %0 is replaced by the value of the
Protocol parameter (see Section 5.54.2 on page 174) and %1 is replaced by the value of
the Host parameter (see Section 5.54.2 on page 174). The default is %0://%1/ims-ws/
services/CommandServer.
You should not normally need to change this from the default.

202 of 397

Radiator RADIUS Server

Configuration

5.57.4 Protocol

This optional parameter specifies the protocol that will be used to contact the RSA AM
server. It is used as %0 in the Endpoint parameter. The default is "https". You should not
normally need to change this.
5.57.5 URI

This optional parameter specifies the SOAP URI that will be accessed in the RSA AM
server. The default is "http://webservice.rsa.com/". You should not normally need to
change this. Note that this is not the address of a web resource and it is not accessed by
Radiator during authentication.
5.57.6 Policy

This optional parameter specifies the authentication policy that is to be used. Defaults to
RSA_Password.
Options are:

SecurID_Native
Traditional SecurID two-factor token cards. User enters their PIN followed by the
tokencode currently showing on their token card.

OnDemand
User enters their PIN. AM sends a temporary tokencode to the user by email or
SMS, according to however AM is configured. User then enters the tokencode they
receive.

RSA_Password
Static password stored in the RSA internal database.

LDAP_Password
Static password stored in an LDAP database.

Security_Questions
User is asked a series of security questions, and enters answers that they have previously configured using the RSA Self-Service Console.

SecurID_Proxy
5.57.7 SessionUsername

Username used to authenticate the SSL connection to AM. Created automatically by

AM during installation. Use the instruction above to find the username.
5.57.8 SessionPassword

Password used to authenticate the SSL connection to AM. Created automatically by AM

during installation. Use the instruction above to find the password.
5.57.9 ChallengeHasPrompt

Add RADIUS Prompt attribute to Access-Challenge messages. Prompt value is based

on responses received from RSA AM. Default is not to add Prompt in Access-Challenges. Prompt attribute is a hint to the client software to echo or not echo sensitive user
input such as PINs or security question answers.

Radiator RADIUS Server

203 of 397

Configuration

5.57.10 SessionRealm (obsolete)

Previously, the realm name used to authenticate the SSL connection to AM. Now
unused and obsolete.
5.57.11 Timeout

This optional parameter specifies the timeout in seconds that will be used during
authentication requests sent by Radiator to the RSA AM server. The default is 20 seconds.
5.57.12 SOAPTrace

This optional parameter enables low level protocol tracing in the SOAP::Lite module.
Setting it to debug will cause details of each incoming and outgoing SOAP request to
be printed on STDOUT.
5.57.13 Message

This optional parameter enables customization of various user messages generated by

this module. The key for each message is the RSA AM message, and the value is the
string you want the user to see.
5.57.14 SSLVerify, SSLCAFile and SSLCAPath

The SSL* parameters allow controlling how the RSA AM server certificate is verified.
By default no SSL* parameters are set and the system defaults are used. SSLVerify,
SSLCAFile and SSLCAPath behave as described in <AuthBy IMAP> on page 190.
Technical Note: Server certificate certification requires Perl LWP 6.0 or later.
5.57.15 SSLVerifyCNName and SSLVerifyCNScheme

SSLVerifyCNName sets the name which is used when verifying the hostname against
the certificate presented by the RSA AM server. SSLVerifyCNScheme controls how the
verification is done, for example, if wildcards are allowed. These parameters behave as
described in SSLVerifyCNName and SSLVerifyCNScheme on page 256.
5.57.16 SSL_CertificateFile

Specifies the name of a client certificate file which will be use to authenticate SSL connection to the AM server. The certificate will be sent to the AM server SSL authentication. The certificate file must be in PEM. The certificate file can also contain the clients
TLS private key if the SSL_PrivateKeyFile parameter specifies the same file. Not
required if AM does not require client certificate authentication.
5.57.17 SSL_PrivateKeyFile

Specifies the name of the file containing the SSL clients private key. It is sometimes in
the same file as the client certificate (SSL_CertificateFile). The private key must not be
encrypted and must not require a passphrase.
5.58 <AuthBy SQLDIGIPASS> (was <AuthBy DIGIPASS>)
This module provides authentication of Vasco Digipass tokens (http://www.vasco.com)
from an SQL database. Digipass tokens are small hand-held devices that generate onetime-passwords that change every minute. They can be purchased from Vasco and
issued to your users. Such tokens provide much higher levels of security than static
204 of 397

Radiator RADIUS Server

Configuration

passwords. Additionally, with some types of token, users can set up individual PINs,
which provides even higher levels of security with two-factor authentication. Some
types of Digipass token can operate in a Challenge-Response mode. Vasco Digipass is
supported by Radiator on Solaris, Linux and Windows.
<AuthBy SQLDIGIPASS> can be used to authenticate PAP, CHAP, MSCHAP,
MSCHAPV2, EAP-MSCHAPV2, EAP-OTP and EAP-GTC protocols.
Note: AuthBy SQLDIGIPASS was previously called AuthBy DIGIPASS. AuthBy
SQLDIGIPASS is completely compatible with and replaces AuthBy DIGIPASS.
Although AuthBy DIGIPASS is still a recognized name, it is officially deprecated, and
support for it may be removed in the future. New installations are encouraged to use
AuthBy SQLDIGIPASS.
AuthBy SQLDIGIPASS supports for Response Only (RO) and Challenge/Response
(CR) tokens. It supports RADIUS PAP, TTLS-PAP, EAP-GTC and EAP-OTP authentication methods. When using Challenge/Response tokens with PAP or TTLS-PAP, when
the user enters an empty password, AuthBy SQLDIGIPASS will generate the Challenge
to enter into the Digipass token. The token will then generate a Response which the
users enters as their real password.
Radiator and AuthBy SQLDIGIPASS can be configured in several ways including:

As a simple stand-alone system. A single SQL table contains information about each
Digipass token and the user it is assigned to. You can use the digipass.pl program
supplied with Authen-Digipass to import tokens, assign them to users and otherwise
administer tokens and users. The example digipass.cfg Radiator configuration file
shows a simple example of how to configure Radiator for such a system. Sample
SQL database table definition files are provided with Radiator for a range of free and
commercial SQL databases.

As an addition to a Radiator-compatible user-management system or ISP billing system. In this mode, Radiator is configured to authenticate using AuthBy SQLDIGIPASS from an SQL table, but also uses other information from the user-management
system to save usage data, get user- or service-specific RADIUS reply items etc.

In conjunction with OSCs RAdmin RADIUS user management system (http://

www.open.com.au/radmin). RAdmin provides an easy-to-install, easy-to-use webbased graphical system for managing RADIUS users for dialup, wired and wireless
authentication. RAdmin version 1.9 includes support for importing, allocating and
administering Digipass tokens for authenticating users against Digipass instead of
static passwords. RAdmin also works with any free or commercial SQL database.
AuthBy SQLDIGIPASS requires an additional Authen-Digipass module to be installed.
The Authen-Digipass perl module provides access to the Vasco Controller software that
does the authentication of each token. Radiator includes pre-compiled binaries of the
Authen-Digipass module for Solaris, Linux and Windows. See goodies/digipassinstall.txt in your distribution for details on how to install and test Authen-Digipass for
your platform.

Radiator RADIUS Server

205 of 397

Configuration

AuthBy SQLDIGIPASS also requires an SQL database to hold information about each
Digipass token that your system knows about. When you purchase a Digipass token
from Vasco, you will also be supplied with a DPX file that contains important data
about the token. This DPX file must be imported into the AuthBy SQLDIGIPASS database before the token can be authenticated by Radiator. You can use any free or commercial SQL database with AuthBy SQLDIGIPASS.
If you intend to use Digipass tokens with RAdmin as your user administration program,
then you will find that RAdmin provides all the tools you need for importing, allocating
and administering Digipass tokens and users. In this case you should use goodies/radminDigipass.cfg as an example Radiator configuration.
If you intend to use Digipass tokens with the example SQL database schema supplied in
goodies/*.sql, you can use the digipass.pl program supplied and installed with
Authen-Digipass for importing, allocating and administering Digipass tokens and users.
In this case you should use goodies/digipass.cfg as an example Radiator configuration.
5.58.1 Using Vasco Digipass tokens to generate passwords for AuthBy SQLDIGIPASS

Vasco produce a number of different types of token, some which require a PIN to be
entered into the token, some which support user selected PINs and some which do not
support PINs. All tokens display a tokencode, usually in response to pressing a button
on the face of the token. The different types of token are described below.
The simplest Digipass tokens include the Go-3, and which have an LCD display and a
single button (but no keypad). For these tokens, you press the button and use the tokencode displayed on the token as your password. Note that any attempt to use the same
tokencode twice will result in a rejection (the error message on the Radiator log will say
Code Replay Attempt): you must wait for the next token code to be displayed by the
token.
Go-1 and Go-3 tokens (among others) support user-selected static PINs, and also support the ability to change your PIN dynamically. Your initial PIN may have been
selected by your administrator and given to you with your token. In any case, if you
have a PIN, the password is made from the PIN followed by the tokencode displayed on
the token. For example, if your PIN is 1234, and the token displays 89574526, then your
password is 123489574526. If you have not been assigned a PIN for your token, just
use the tokencode displayed on the token as your password: 89574526.
Go-1 and Go-3 tokens (among others) also support the ability to change your PIN. To
change your PIN, you form the login password from your current PIN, followed by the
tokencode, followed by the new PIN, followed by the new PIN again. For example, if
your current PIN is 1234, and you wish to change the PIN to 9876, and the token is displaying 89574526, then you use the password 12348957452698769876. After this password has been accepted, your new PIN will be active, and you must enter the new PIN
at the beginning of each subsequent password.

206 of 397

Radiator RADIUS Server

Configuration

FIGURE 2.

Digipass Go-1 PIN passwords

Tokencode
Current PIN

123489574526

Static PIN

12348957452698769876

Changing the PIN

Old PIN

Tokencode

New PIN

After resetting the PIN (using either the digipass.pl application that comes with AuthenDigipass or the Reset static password (PIN) for this token button in RAdmin), the
token has no PIN associated with it. In that case you must provide a new PIN with the
next authentication attempt.
To do this enter the tokencode from the token followed by the new PIN twice. For
example if the current tokencode is 656565 and you want your new PIN to be 1234, you
would enter 65656512341234 at your next authentication. For subsequent authentications, you would then prefix the token code with your new PIN.
Some Digipass tokens have a keypad, which requires the tokens PIN to be entered, and
which also support Challenge-Response (CR). In Challenge-Response, when you first
attempt to log in, Radiator sends a Challenge (a sequence of digits) that you must enter
into the token in order to generate the correct Response, which is then used as your
password.
The first step is to attempt to log in with an empty password (i.e. a password with nothing in it). If the users token supports CR, Radiator AuthBy SQLDIGIPASS will send a
challenge of (typically) 4 digits:
Digipass Challenge: 8077

You will use this challenge shortly. Now start the token by pressing the arrow button.
The token will ask for your PIN. Enter the 4 digit PIN (e.g. 1 - 2 - 3 - 4). The token will
then display APPL1. Press 3 to request Challenge-Response. The token will display
- - - -. Enter the Digipass Challenge sent to you by Radiator (e.g. 8 - 0 - 7 - 7). The
token will then display a tokencode of 7 digits. Use the tokencode as your password.
5.58.2 Virtual Digipass

AuthBy DIGIPASS supports Virtual Digipass. Virtual Digipass tokens to do require an

actual physical token. When the user attempts to log in, AuthBy SQLDIGIPASS generates the correct password and sends it to the user by a separate secure method such as
SMS, voice etc. The user then enters the tokencode they receive from the separate channel, and AuthBy SQLDIGIPASS authenticates it just like a normal Digipass tokencode.
Not all Vasco tokens support Virtual Digipass. This is determined by a flag in the

Radiator RADIUS Server

207 of 397

Configuration

tokens DPX data file. In order to use Virtual Digipass, you need to purchase one or
more Virtual Digipass token data files from Vasco. Real physical Digipass tokens can
have DPX token files that also permit use of Virtual Digipass as a backup for the case
where the token is lost or stolen.
Virtual Digipass allows Vasco token support even if the user does not have a physical
token (or has lost it). The SupportVirtualDigipass parameter makes AuthBy SQLDIGIPASS support Virtual Digipass tokens: If the incoming password is empty, and the token
supports Virtual Digipass, AuthBy SQLDIGIPASS generates the users correct tokencode and passes it to the VirtualTokencodeHook for delivery to the user by some secure
out-of-band method such as SMS.
AuthBy SQLDIGIPASS understands the following parameters:
5.58.3 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database that contains the Digipass
token data. They need to be set in a similar way to as for <AuthBy SQL>. They specify
the DBD driver, database and username to connect to, and how to handle SQL server
failures.
# Connect to MySQL with database named radius
DBSource
dbi:mysql:radius
DBUSername yoursqlusername
DBAuth
yoursqlpassword
5.58.4 AuthSelect

This optional parameter specifies the SQL query that will be used to fetch Digipass data
from the database. Special characters are permitted, and %0 is replaced with the quoted
user name. Defaults to select DP_DATA, DIGIPASS from TBL_VASCODP
where USER_ID=%0, which is compatible with the sample schemas provided in
goodies/*.sql. The query is expected to return 2 fields in this order:
1. Digipass data block. This is 248 characters of encrypted data about the Digipass. It is

encoded in printable characters. Example:

10AFIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGAAEAAAAgICAAAACx4
bwOmRYm8XYHErnjBAJIAWecbdhsRHIAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAA+RmOzmh1lFwAAAYAAQAAAERQMzAwAAAAAAAAAAAAAACNOQpB57zTB/XrAgg+7W/y
2. The Digipass serial number of 22 characters, including the token number and appli-

cation name, and often some spaces, Example: 0097123456APPL 1

spaces and application name are significant.

. The

5.58.5 UpdateQuery

This optional parameter specifies the SQL query that will be used to store Digipass
token data back to the database after authentication. The process of authentication
(whether or not it is successful) results in the Digipass data block for that token being
changed, and it must be written back to the database after each authentication attempt
for correct operation. Special characters are permitted, and %0 is replaced with the new
data block, and %1 is replaced with the Digipass serial number retrieved by AuthSelect.

208 of 397

Radiator RADIUS Server

Configuration

Defaults to update TBL_VASCODP set DP_DATA=%0 where DIGIPASS=%1, which is compatible with the sample schemas provided in goodies/*.sql.
5.58.6 ITimeWindow

This optional parameter specifies the size of the window of opportunity that a token can
login with (this is counted in multiples of one-time password "rollovers" in the token.
Value can be 2 to 1000. Default is 100 (that means +- 30 minutes for default tokens)
5.58.7 IThreshold

This optional parameter specifies the number of times that a person can unsuccessfully
try to login before being locked out. 0 means disabled. Defaults to 0.
5.58.8 SyncWindow

This optional parameter specifies the size of the larger window that is created for use the
first time after a token has been reset. This means that if a token gets out of sync (which
isnt an often occurrence), the user cant log in so the administrator resets the token,
then a larger sync window is produced after the reset so that the token can be recognized
and calibrated by the software to allow subsequent use. This parameter is expressed in
hours. Value can be 1 to 60. Default is 6 (hours)
5.58.9 CheckChallenge

This optional parameter specifies whether or not to check if the challenge has been corrupted before validation. Value can be 0 to 4:

0: no password checking
1: Check the parameter then verify (default)
2: Always use the DPData to validate responses
3: Avoid Challenge-Response Replay Attack by allowing only one challengeresponse authentication per timestep.

4: Avoid Challenge-Response Replay Attack by rejecting the second response if

responses from two consecutive authentication requests are equal and in the same
time-step
Defaults to 1.
5.58.10 ChkInactDays

This optional parameter specifies number of days of token inactivity. Past this number
of days, the token will have to be reset. Values from 0 to 1024. Default is 0, which
means the feature is disabled.
5.58.11 DeriveVector

This optional advanced parameter can be used to make data encryption unique for a
host. Defaults to 0x00000000.
5.58.12 EventWindow

This optional advanced parameter specifies the Event Window size by number of iterations. Represents the acceptable event counter difference between Digipass token a and
the host. It only applies to event-based operating modes. From 10 to 1000. Defaults to
100.
Radiator RADIUS Server

209 of 397

Configuration

5.58.13 HSMSlotId

This optional advanced parameter specifies the HSM slot ID which will be used to store
the Storage and Transport keys. 0 to 60. Defaults to 0.
5.58.14 StorageKeyId

This optional advanced parameter specifies the key which will be used to decrypt the
Digipass data retrieved from the database. 0x00000000 to 0xffffffff. Defaults to
0x00000000.
5.58.15 TransportKeyId

This optional advanced parameter specifies the key which will be used to encrypt the
Digipass data written to the database. 0x00000000 to 0xffffffff. Defaults to
0x00000000.
5.58.16 StorageDeriveKey1, StorageDeriveKey2, StorageDeriveKey3, StorageDeriveKey4

These optional advanced parameters specify the derivation keys used to make data
encryption unique for a host.
5.58.17 ChallengeMessage

This parameter allows you to customize or internationalize the Reply-Message sent

when the user is challenged to enter a Digipass tokencode. %0 is replaced with the digipass challenge string. Defaults to Digipass Challenge: %0
# French challenge message:
ChallengeMessage Votre challenge du Digipass: %0
5.58.18 SupportVirtualDigipass

This optional parameter causes AuthBy SQLDIGIPASS to support Vasco Virtual Digipass tokens.
5.58.19 VirtualTokencodeHook

If the SupportVirtualDigipass flag is enabled, this parameter specifies Perl code that is
called whenever a Virtual Digipass tokencode is to be sent to a user. The hook is
expected to transmit the tokencode to the user over some prompt, secure out-of-band
method, such as SMS. The VirtualTokencodeHook is called like:
VirtualTokencodeHook($self, $username, $tokencode, $p)

VirtualTokencodeHook must return an error message if it fails to start delivery of the

tokencode the user, otherwise it must return undef;
5.58.20 ChallengeTimeout

This optional parameter sets the maximum period of time that a challenge from a Challenge-Response (CR) token will be valid for. Time is in seconds and defaults to 300 seconds (5 minutes).
5.59 <AuthBy LDAPDIGIPASS>
This module provides authentication of Vasco Digipass tokens (http://www.vasco.com)
from an LDAP database. Details about Digipass tokens, how to obtain and operate them
can be found in <AuthBy SQLDIGIPASS> (was <AuthBy DIGIPASS>) on page 204.

210 of 397

Radiator RADIUS Server

Configuration

AuthBy LDAPDIGIPASS requires an additional Authen-Digipass module to be

installed. The Authen-Digipass perl module provides access to the Vasco Controller
software that does the authentication of each token. Radiator includes pre-compiled
binaries of the Authen-Digipass module for Solaris, Linux and Windows. The AuthenDigipass module also includes the digipass.pl command line application program for
administering Digipass tokens in SQL and LDAP databases. See goodies/digipassinstall.txt in your distribution for details on how to install and test Authen-Digipass for
your platform.
<AuthBy LDAPDIGIPASS> can be used to authenticate PAP, CHAP, MSCHAP,
MSCHAPV2, EAP-MSCHAPV2, EAP-OTP and EAP-GTC protocols.
<AuthBy LDAPDIGIPASS> can be configured to work in a wide variety of LDAP
environments and schemas. A sample LDAP schema to hold Digipass token data is
included in the goodies/radiator-ldap.schema file in your Radiator distribution. This
schema is suitable for OpenLDAP and other compatible LDAP servers. See the notes in
the top of that file for details on how to install the schema in your LDAP server, so that
you can use it to store Digipass token data. The digipass.pl program included in the
Authen-Digipass module can be used to import token data into this example schema,
and to assign them to users, reset tokens, get detailed token information etc. By default,
AuthBy LDAPDIGIPASS works with this sample schema on a local LDAP database,
but you can use the AuthBy LDAPDIGIPASS parameters to configure it to work with
other schemas and databases. There is a sample Radiator configuration file in goodies/
digipass_ldap.cfg in your Radiator distribution.
<AuthBy LDAPDIGIPASS> understands the following parameters besides those
described in Section 5.21 on page 82:
5.59.1 SearchFilter

This optional parameter specifies the LDAP search filter that is used to find the Digipass token record for the user attempting to log in. Special characters can be used. %0 is
replaced by the value of TokenDataAttr, and %1 is replaced by the User-Name of the
user logging in. Defaults to (%0=%1).
5.59.2 UsernameAttr

This optional parameter gives the name of the LDAP attribute that contains the username of the user assigned to that token. It is used as %0 in the SearchFilter. Defaults to
oscDigipassTokenAssignedTo.
5.59.3 TokenDataAttr

This parameter specifies the name of the LDAP attribute that contains the Digipass
token data, which is used to authenticate Digipass token logins. Defaults to oscDigipassTokenData.
5.59.4 MaxRecords

This optional parameter specifies the maximum number of Digipass tokens returned by
the SearchFilter that will be examined. Defaults to 1.

Radiator RADIUS Server

211 of 397

Configuration

5.59.5 Other LDAP Server Connection parameters

A number of other parameters can be used to control where and how to connect to the
LDAP server. These parameters are described in Section 5.38, <AuthBy LDAP2>, on
page 149:

BaseDN
Scope
Host
Port
UseSSL
UseTLS
AuthDN
AuthPassword
Debug
Timeout
FailureBackoffTime
HoldServerConnection
NoBindBeforeOp
SSLVerify
SSLCiphers
SSLCAPath
SSLCAFile
SSLCAClientCert
SSLCAClientKey
Version
Deref
UseSASL
SASLUser
SASLPassword
SASLMechanism

5.59.6 Vasco Controller Library parameters

A number of other parameters can be used to control the behaviour of the Vasco Controller Library. These parameters are described in Section 5.58, <AuthBy SQLDIGIPASS> (was <AuthBy DIGIPASS>), on page 204:

212 of 397

UpdateQuery
ITimeWindow
IThreshold
SyncWindow
CheckChallenge

Radiator RADIUS Server

Configuration

ChkInactDays
DeriveVector
EventWindow
HSMSlotId
StorageKeyId
TransportKeyId
StorageDeriveKey1
StorageDeriveKey2
StorageDeriveKey3
StorageDeriveKey4
ChallengeMessage

5.60 <AuthBy LDAP_APS>

This clause finds user details in a Mac OS-X Directory Server LDAP database, and then
authenticates the user password against a Mac OS-X Apple Password Server.
Mac OS-X Server includes a facility called Directory Server which provides information about users (amongst other things). Part of the Directory Server facility is an LDAP
server that contains the user details. However, the LDAP server never contains any user
passwords, it merely contains information about valid methods for authenticating that
user. Users that have been configured to use the Password Server authentication
method can have passwords authenticated by the Apple Password Server facility.
Therefore, AuthBy LDAP_APS can authenticate any user configured into the Apple
Directory Server LDAP server, and configured to use the Apple Password Server
authentication method.
AuthBy LDAP_APS is a subclass of AuthBy LDAP2. IT queries the Mac OS-X LDAP
server for information about a specific user in the same way as AuthBy LDAP2. It uses
the users authAuthority attribute from the LDAP database to determine how to authenticate the password. If the user is configured to be able to use the Apple Password
Server (i.e. the authAuthority contains ApplePasswordServer, a user id and a Password
Server address) then AuthBy LDAP_APS will authenticate the users password by contacting (via TCP/IP) the specified Apple Password Server.
At Mac OS-X Server 10.4, Apple Password Server does not support all possible password authentication methods. In particular, it supports Plaintext (via CRAM-MD5),
Digest-MD5 and MSCHAPV2. It does not support CHAP or MSCHAPV1. Therefore
you can only use AuthBy LDAP_APS to authenticate PAP, MSCHAPV2, TTLS-PAP,
TTLS-MSCHAPV2 or PEAP-MSCHAPV2 requests.
AuthBy LDAP_APS is configured in the same was as AuthBy LDAP2, except that you
must specify PasswordAttr as authAuthority, since AuthBy LDAP_APS uses that attribute to find and contact the Password Server for that user.

Radiator RADIUS Server

213 of 397

Configuration

Since standard TCP/IP is used to talk to the LDAP server and the Apple Password
Server, it is not necessary to run Radiator and AuthBy LDAP_APS on the Mac OS-X
Directory Server host. Radiator could run on a remote Mac, Linux, Windows or other
host, different to the Mac OS-X host running the Directory Server and, in the general
case, the Apple Password Server could be on a third host.
AuthBy LDAP_APS understands all the same parameters as AuthBy LDAP2. See
Section 5.38, <AuthBy LDAP2>, on page 149. There is a sample configuration file in
goodies/ldap-aps.cfg in your Radiator distribution.
5.60.1 PasswordServerAddress

If this optional parameter is set, it forces Radiator to use the specified address as the
address of the Apple Password server, instead of deducing it from the users data record.
Addresses may be one of the forms: 203.63.154.59, dns/yoke.open.com.au, ipv4/
203.63.154.59 or ipv6/2001:720:1500:1::a100. This can be useful with replicated password servers. It is common to set it to localhost:
PasswordServerAddress 127.0.0.1

5.61 <AuthBy URL>

This clause authenticates using HTTP from any URL. It can use any given CGI or ASP,
that validates username and password. It requires the Digest::MD5 and HTTP::Request
and LWP::UserAgent perl modules in libwww-perl-5.63 or later package available from
CPAN. Supports both GET and POST Method for http query strings.
The user name and password being authenticated are passed as URL tags to the program
(i.e. it does not use the web servers HTTP authentication). The CGI or ASP can then
validate the username and password and return a string that indicates whether the
authentication succeeded or not. Passwords may be sent in the clear, or Unix crypt or
MD5 encrypted. Example CGI scripts are available in the goodies directory of your
Radiator distribution. See goodies/README.
This module was contributed by Mauro Crovato <[email protected]>. See the
example configuration file in goodies/url.cfg in your Radiator distribution.
AuthBy URL understands the following parameters besides those described in
Section 5.21 on page 82:
Hint: The libwww module that AuthBy URL uses can also support HTTPS requests. In
order to enable this support, you must build and install either the Crypt::SSLeay or
IO::Socket::SSL Perl modules before building the libwww module (see the
README.SSL in the libwww distribution for more details). After that you can specify
an HTTPS URL with something like:
AuthUrl https://www.mysite.com/validate.cgi
5.61.1 AuthUrl

This optional parameter specifies the complete URL that will be used to authenticate the
username and password. It is usually set to the URL of a CGI or ASP program on a web

214 of 397

Radiator RADIUS Server

Configuration

server that you control. HTTPS is supported, but see the hint above for details on how to
enable HTTPS support.
AuthUrl www.mysite.com/validate.cgi
or ....
AuthUrl https://www.mysite.com/validate.cgi
5.61.2 AcctUrl

This optional parameter specifies the complete URL that will be used to save accounting data from Accounting-Request packets. All the attributes in the request will be sent
as HTTP tags, using either GET or POST, depending on the setting of UrlMethod.
AcctUrl http://www.mysite.com/cgi-bin/save-accounting.cgi
5.61.3 UrlMethod

This optional parameter specifies what type of submit method is going to be used to
pass user and pass to the URL. Possible values are GET or POST. It is not sensitive to
case. The default is GET.
UrlMethod POST
5.61.4 Debug

This optional flag parameter specifies if any incoming authentication that result in
Auth-Accept, will be logged with the Radiator logging system. The default is to not log.
Debug 1
5.61.5 Timeout

This optional parameter specifies the timeout (in seconds) for the http connection to the
web server. The default 5.
Timeout 3
5.61.6 UserParam

This optional parameter specifies the name of the URL tag variable used to pass the
Username being authenticated, to the URL The default is user.
UserParam username
5.61.7 PasswordParam

This optional parameter specifies the name of the URL tag variable used to pass the
Password being authenticated, to the URL The default is password.
PasswordParam key
5.61.8 AuthOKKeyword

This optional parameter specifies the name of the string that has to be found in the
response from the web server, to select an Auth-Accept response message The default is
AuthOK.
AuthOKKeyword "auth accept"

Radiator RADIUS Server

215 of 397

Configuration

5.61.9 AuthChallengeKeyword

This optional parameter specifies the name of the string that has to be found in the
response from the web server, to select an Auth-Challenge response message The
default is AuthChallenge.
5.61.10 BadUserKeyword

This optional parameter specifies the name of the string that has to be found in the
response from the web server, to select an Auth-Reject Bad User response message The
default is BadUser.
BadUserKeyword "auth reject bad user"
5.61.11 BadPasswordKeyword

This optional parameter specifies the name of the string that has to be found in the
response from the web server, to select an Auth-Reject Bad Password response message
The default is BadPassword.
BadPasswordKeyword "auth reject bad pass
5.61.12 PasswordEncryption

This optional parameter specifies the type of encryption that is going to be used, to send
the PAP password to the URL. The options available are Clear, Crypt and MD5 (case
insensitive). The default is Clear.
PasswordEncryption Md5
5.61.13 ChapChallengeParam

For CHAP authentication, the name of the web parameter to use to send the CHAP challenge. Not used for PAP or other types of authentication. Defaults to chap_challenge.
5.61.14 ChapResponseParam

For CHAP authentication, the name of the web parameter to use to send the CHAP
response. Not used for PAP or other types of authentication. Defaults to chap_response.
5.61.15 MSChapChallengeParam

For MSCHAP authentication, the name of the web parameter to use to send the
MSCHAP challenge. Not used for PAP or other types of authentication. Defaults to
mschap_challenge.
5.61.16 MSChapResponseParam

For MSCHAP authentication, the name of the web parameter to use to send the
MSCHAP response. Not used for PAP or other types of authentication. Defaults to
mschap_response.
5.61.17 MSChapV2ChallengeParam

For MSCHAPV2 authentication, the name of the web parameter to use to send the
MSCHAPV2 challenge. Not used for PAP or other types of authentication. Defaults to
mschapv2_challenge.

216 of 397

Radiator RADIUS Server

Configuration

5.61.18 MSChapV2ResponseParam

For MSCHAPV2 authentication, the name of the web parameter to use to send the
MSCHAPV2 response. Not used for PAP or other types of authentication. Defaults to
mschapv2_response.
5.61.19 CopyRequestItem

Adds a tagged item to the HTTP request. Format is CopyRequestItem xxx yyy. The text
of yyy (which may be contain special characters) will be added to the HTTP request
with the tag xxx. In the special case where yyy is not defined, the value of attribute
named xxx will be copied from the incoming RADIUS request and added to the HTTP
request as the tagged item yyy. All values are HEX encoded before adding to the HTTP
request. Multiple CopyRequestItem parameters are permitted, one per line.
CopyRequestItem NAS-Port
CopyRequestItem Calling-Station-Id %{OuterRequest:Calling-Station-Id}
5.61.20 CopyReplyItem

Copies an attribute=value pair in a successful HTTP response to the RADIUS reply.

Format is CopyReplyItem xxx yyy. If a successful HTTP reply contains a string like
"xxx=hexencodedvalue" the value will be copied to the RADIUS reply as attribute
yyy=value. Multiple CopyReplyItem parameters are permitted, one per line.
CopyReplyItem MS-CHAP2-Success
CopyReplyItem Reply-Message reply_tag

5.62 <AuthBy KRB5>

This clause authenticates using the Kerberos 5 authentication system, which is available
on most types of operating system. It authenticates from a previously defined Kerberos
KDC (Key Distribution Centre). There is a sample configuration file in goodies/
krb5.cfg in your distribution. AuthBy KRB5 can authenticate PAP and TTLS-PAP.
Accounting are ACCEPTed but discarded.
Requires the Authen::Krb5 module version 1.3 or later from CPAN.
AuthBy KRB5 understands the following parameters.
5.62.1 KrbRealm

This optional parameter is the name of the Kerberos realm that all Kerberos users are
assumed to be in. Defaults to the default Kerberos realm defined by your Kerberos
administrator.
Kerberos principal names are constructed by appending @KrbRealm to the RADIUS
username (after any RADIUS realm has been stripped off. So if a user tries to authenticate as [email protected], and KrbRealm is set to mykrb.com, then the Kerberos principal name that will be authenticated will be [email protected].
# All users are in this realm.
KrbRealm OPEN.COM.AU

Radiator RADIUS Server

217 of 397

Configuration

5.62.2 KrbServerRealm

This optional parameter is the name of the Kerberos realm that the Kerberos server is
assumed to be in. Defaults to the KrbRealm value.
5.62.3 KrbKeyTab

This optional parameter provides the path to a Kerberos keytab file. When this option is
present, a service ticket will be obtained as part of each Kerberos authentication attempt
to guard against Key Distribution Center spoofing. By default, the keytab is examined
to locate the key for the service radius/server@realm where server is the fully qualified
___domain name of the machine running Radiator and realm is the Kerberos realm used
during authentication. The name of the service may be overridden with the KrbService
parameter, the fully qualified ___domain name with the KrbServer parameter and the realm
with the KrbRealm parameter.
# Enable KDC spoof detection using service ticket
KrbKeyTab /etc/krb5-radius.keytab
5.62.4 KrbService

This optional parameter overrides the default value of "radius" for the service name
used when locating a key to obtain a service ticket as part of Kerberos Key Distribution
Center spoof detection. This parameter has no effect unless the KrbKeyTab parameter is
defined. See the KrbKeyTab parameter for more information. This parameter should be
set to the service name of the service key obtained from your Kerberos administrator.
# Service name for radius
KrbService radiusproxyauthentication
5.62.5 KrbServer

This optional parameter overrides the default value of the fully qualified ___domain name
of the server running radiator when locating a key to obtain a service ticket as part of
Kerberos Key Distribution Center spoof detection. This parameter has no effect unless
the KrbKeyTab parameter is defined. See the KrbKeyTab parameter for more information. This parameter should be set to the hostname included in the service key obtained
from your Kerberos administrator.
# Hostname of the server
KrbServer radius.example.com

5.63 <AuthBy MULTICAST>

This clause sends copies of some or all RADIUS requests to all the remote RADIUS
servers indicated by the embedded Host clauses. The syntax for this clause is very similar to <AuthBy RADIUS> on page 125, but where AuthBy RADIUS only sends to
the second and subsequent Host if no reply is heard from previous Hosts, AuthBy MULTICAST always sends to all of them. If any Hosts do not reply, the usual retransmissions will occur (the number and timeout is configurable on a per-Host basis).
Hint: It is not normally useful to send multiple copies of authentication requests to multiple hosts. However, it is sometimes desirable to send multiple copies of AccountingRequest. In this case, the IgnoreAuthentication flag will be useful.
This module was contributed by Andrew Ivins and Swiftel.
218 of 397

Radiator RADIUS Server

Configuration

AuthBy MULTICAST understands all the parameters of <AuthBy RADIUS> on

page 125, as well as the following:
5.63.1 HandleAcctStatusTypes

This optional parameter specifies a list of Acct-Status-Types that will be forwarded. The
value is a comma-separated list of valid Acct-Status-Type attribute values (see your dictionary for a full list) including, Start, Stop, Alive, Modem-Start, Modem-Stop, Cancel,
Accounting-On, Accounting-Off etc.
If HandleAcctStatusTypes is specified and an Accounting request has an Acct-StatusType not mentioned in HandleAcctStatusTypes, then the request will be ACCEPTed but
not forwarded to any of the Hosts. The default is to forward all Acct-Status-Types.
# Only forward Accounting Start and Stop requests,
# ack all other accounting without forwarding
HandleAcctStatusTypes Start,Stop
5.63.2 LoopDetection

If this optional parameter is set, Radiator will not forward a request to a Host if the
request to be forwarded was originally received from the same address. Defaults to no
loop detection.
# Enable loop detection
LoopDetection yes

5.64 <AuthBy RADSEC>

This clause proxies RADIUS requests to a <ServerRADSEC> clause on remote Radiator using the RadSec (RFC 6614) secure reliable RADIUS proxying protocol. It can be
used instead of AuthBy RADIUS when proxying across insecure or unreliable networks
such as the internet. See RadSec (RFC 6614) on page 376 for more details about the
RadSec protocol.
AuthBy RADSEC attempts to establish a RadSec connection to the server Hosts when
Radiator start up. If the connection subsequently fails or is disconnected, it will attempt
to reestablish the connection at ReconnectTimeout intervals.
AuthBy RADSEC can be configured for multiple target hosts by specifying multiple
Host clauses inside the AuthBy RADSEC clause. Normally when a packet is to forwarded, AuthBy RADSEC will attempt first to send it to the first Host. If no reply is
received from that Host within NoreplyTimeout seconds, it will attempt to send the
request to the next Host and so on. If no reply is heard from any Host, the NoReplyHook
is called
Hint: for compliance with RFC 6614, AuthBy RADSEC defaults to a Secret of radsec,
Transport of tcp and UseTLS enabled.
5.64.1 Failure algorithm

AuthBy RADSEC implements a configurable algorithm to detect failed RadSec hosts,

and to temporarily disregard failed hosts. The algorithm uses the MaxFailedRequests,
MaxFailedGraceTime and FailureBackoffTime parameters to customize the operation

Radiator RADIUS Server

219 of 397

Configuration

of the algorithm. It also uses KeepaliveTimeout and UseStatusServerForFailureDetect

in order to use only Status-Server requests for failure detection, instead of any request.
AuthBy RADSEC initially assumes that each Host is not failed. After a request is sent
to a RadSec server, if no reply is received after the NoreplyTimeout, that request is
deemed to have failed for that Host. AuthBy RADSEC keeps track of how many consecutive requests failed for each Host since the last time a reply was heard from that
Host. If more than MaxFailedRequests consecutive requests are deemed to have failed
within MaxFailedGraceTime seconds of that last reply heard from that Host, that Host is
deemed to have failed.
When the Host is deemed to be failed, AuthBy RADSEC will not attempt to send any
requests to it until FailureBackoffTime seconds have elapsed. In the meantime, AuthBy
RADSEC will attempt to connect or reconnect to the host according to ReconnectTimeout. It will also skip sending requests to that host, and will instead attempt to send to the
next Host in its list of Hosts (if any).
The default values for these parameters are:
MaxFailedRequests 1
MaxFailedGraceTime 0
FailureBackoffTime 0

These values mean that by default AuthBy RADSEC will declare the Host failed after a
single packet transmission failure, but that it will always try to transmit the next request
to the Host. This means that AuthBy RADSEC will always try to send every request to
the first Host, and if nothing is heard from that Host within NoreplyTimeout, it will
attempt to send to the next Host.
Hint: Judicious use of these parameters allows you to implement a RadSec Host fallback policy, where if one RadSec Host fails to respond to requests, then it will automatically temporarily fall back to the next RadSec Host and so on.
5.64.2 Certificate validation

When a RadSec Server presents a server certificate to an AuthBy RADSEC Client, the
Client performs a number of checks to validate the server certificate. The server certificate is checked for valid start and end dates, and it also checks the chain of validity back
to the issuing Certificate Authority, using the root certificates specified in TLS_CAFile
or TLS_CAPath. Also a server certificate will only be accepted if at least one of the following conditions are true:

The Host name used to connect to the server matches a subjectAltName with type
IPADD (IP Address) or DNS (DNS name) in the certificate. Exact or wildcard
matches are permitted, so a subjectAltName type DNS of *.xyz.com will match for
any Host in xyz.com. Or,

if there are no subjectAltNames of type DNS in the certificate, if one of the Subject
CN (Common Names) in the certificate matches the Host name used to connect to
the RadSec server. Exact or wildcard matches are permitted. Or,

220 of 397

Radiator RADIUS Server

Configuration

The Subject in the certificate matches the pattern specified by the TLS_ExpectedPeerName parameter in this AuthBy RADSEC clause.
and

If TLS_SubjectAltNameURI parameter is defined in the AuthBy RADSEC clause,

the certificate must contain a subjectAltName of type URI that matches the TLS_SubjectAltNameURI regular expression.

if TLS_CertificateFingerprint parameter is defined in the AuthBy RADSEC clause,

the certificates fingerprint must match at least one of the TLS_CertificateFingerprint options.
Note that the default TLS_ExpectedPeerName pattern is undefined, which means that
by default AuthBy RADSEC requires that the Host name used to connect to the RadSec
server matches the subjectAltName or CN in the Server Certificate.
These certificate validation rules are consistent with RFC 2595.
Important Note: Normally, an AuthBy RADSEC clause will complete as soon as the
request has been forwarded to the remote RadSec server. It will not wait for a reply
before moving on to other AuthBy clauses, or handling new requests. AuthBy RADSEC
always returns IGNORE for AuthByPolicy.
AuthBy RADSEC understands the following parameters:
5.64.3 Host

This parameter specifies the host name or address of a RadSec server (i.e. the instance
of Radiator with a ServerRADSEC clause) that this AuthBy RADSEC is to connect to.
The address may be an IPv4 or IPv6 name or address. Multiple Host lines are supported,
which is equivalent to specifying multiple <Host> clauses.
# Example Host lines for IPv4 and IPv6 addresses
Host 203.63.154.1
Host oscar.open.com.au
Host ipv6:your.ipv6.host.com
Host 2001:db8:1500:1::a100
# IPv6 loopback:
Host ::1
5.64.4 Secret

This parameter specifies the shared secret that will be used to encrypt passwords and
provide basic RADIUS protocol authentication mechanisms for requests and replies
passed over the RadSec connection. It must be the same as the Secret configured into
the <ServerRADSEC> this clause connects to. The Secret is used to protect passwords
even when TLS is not configured for use. If TLS is used, it is not necessary to change it
from the default, since the security of TLS does not depend on the shared secret. For
compliance with RFC 6614, defaults to radsec. There should be no need to change
this.

Radiator RADIUS Server

221 of 397

Configuration

5.64.5 Port

This optional parameter specifies the symbolic service name or port number of the port
to connect to on Host. Defaults to 2083, the official IANA port number for RadSec.
5.64.6 LocalAddress

This optional parameter specifies the address to bind to the RadSec client source port.
Defaults to the Operating Systems default for the protocol family of Host. Can be an
IPv4 or an IPv6 address.
5.64.7 LocalPort

If LocalAddress is specified, this optional parameter specifies the symbolic service

name or port number of the source port. Defaults to 0, which means to allocate a port
number automatically.
5.64.8 NoreplyTimeout

If no reply is received to a proxied request within this number of seconds, the request
will be sent to the next Host in the list (if any). If there are no further Hosts, the NoReplyHook will be called for this request. Defaults to 5 seconds.
5.64.9 KeepaliveTimeout

This optional integer specifies the maximum time in seconds that a RadSec connection
can be idle before a Status-Server request is sent to keep the current TCP connection
alive. This helps to keep TCP connections open in the face of "smart" firewalls that
might try to close idle connections down. Defaults to 0 seconds. If set to 0, keepalives
are not used.
5.64.10 UseStatusServerForFailureDetect

If this optional flag is enabled, use only Status-Server requests (if any) to determine that
a target server is failed when there is no reply. If not enabled (the default) use no-reply
to any type of request. Uses NoreplyTimeout, MaxFailedRequests, MaxFailedGraceTime, FailureBackoffTime during failure detection.
If you enable this, you should also ensure KeepaliveTimeout is set to a sensible interval
to balance between detecting failures early and loading the target server.
5.64.11 StripFromRequest

Strips the named attributes from the request before forwarding it to any Host. The value
is a comma separated list of attribute names. StripFromRequest removes attributes from
the request before AddToRequest adds any to the request. There is no default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.64.12 AddToRequest

Adds attributes to the request before forwarding to any Host. Value is a list of comma
separated attribute value pairs all on one line, exactly as for any reply item. StripFromRequest removes attributes from the request before AddToRequest adds any to the
request. You can use any of the special % formats in the attribute values. There is no
default.

222 of 397

Radiator RADIUS Server

Configuration

# Append a Filter-ID and host name

AddToRequest Calling-Station-Id=1,Login-IP-Host=%h
5.64.13 IgnoreReject

This optional parameter causes Radiator to ignore (i.e. not send back to the original
NAS) any Access-Reject messages received from the remote RadSec server. This is
sometimes useful for authenticating from multiple RADIUS servers. However, you
should note that if all the remote radius servers reject the request, then the NAS will
receive no reply at all.
# If we get a reject from the remote, dont send it to the NAS
IgnoreReject
5.64.14 IgnoreAccountingResponse

This optional flag causes AuthBy RADSEC to ignore replies to accounting requests,
instead of forwarding them back to the originating host. This can be used in conjunction
with the AccountingHandled flag in a Handler or Realm (see Section 5.20.11 on
page 75) to ensure that every proxied accounting request is replied to immediately, and
the eventual reply from the remote RADSEC server is dropped.
5.64.15 AcctFailedLogFileName, AcctLogFileFormat and AcctLogFileFormatHook

These parameters have the same meaning as described in <AuthBy RADIUS> on

page 125.
5.64.16 ReplyHook

This optional parameter allows you to define a Perl function that will be called after a
reply is received from a remote RadSec server and before it is relayed back to the original client. The following arguments are passed in the following order:

A reference to the reply received from the remote RadSec server is passed as the first
argument.

A reference to the reply packet being constructed for return to the NAS is passed as
the second argument.

A reference to the original request from the NAS is passed as the third argument.
A reference to the request that was sent to the remote RadSec server is passed as the
fourth argument.

A reference to the Radius::AuthRADSEC structure is passed as the fifth argument.

The response type can be enforced when needed. For example, when the remote RadSec
server has rejected the request, the ReplyHook can do any local processing required for
rejects and then change the response type to accept.
# Change RadiusResult in the 3rd argument, the original request
ReplyHook sub { ${$_[2]}->{RadiusResult} = $main::ACCEPT; }

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.

Radiator RADIUS Server

223 of 397

Configuration

ReplyHook Can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other
things.
# Fake a new attribute into the reply going back to the client
ReplyHook sub { ${$_[0]}->add_attr(test-attr, \
test-value);}
5.64.17 NoReplyHook

This optional parameter allows you to define a Perl function that will be called if no
reply is received from any RadSec server. A reference to the original request received
from the NAS is passed as the first argument. A reference to the request that was forwarded to the remote RADIUS server is passed as the second argument. A reference to
the reply packet being constructed for return to the NAS is passed as the third argument
(note that the normal behaviour in case of no reply, is for no reply to be sent to the
NAS).
The hook code is compiled by Perl when Radiator starts up. Compilation errors in your
hook code will be reported to the log file at start-up time. Runtime errors in your hook
will also be reported to the log file when your hook executes. Multiline hooks (i.e. with
trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should
not use trailing comments in your hook.
NoReplyHook Can be an arbitrarily complicated Perl function, that might run external
processes, consult databases, change the contents of the current request or many other
things. In particular, you can forward the request to another AuthBy RADSEC clause,
allowing you to implement automatic failover of RadSec hosts.
# Call another AuthBy RADSEC if this one fails to respond
NoReplyHook sub { Radius::AuthGeneric::find(RADSEC2)\
->handle_request(${$_[0]}, ${$_[2]});}
5.64.18 NoForwardAuthentication

Stops AuthBy RADSEC forwarding Authentication-Requests. They are ACCEPTED,

but no further action is taken with them. This is different in meaning to IgnoreAuthentication, which IGNOREs them.
# Just ACCEPT Authentication-Requests, dont forward them
NoForwardAuthentication
5.64.19 NoForwardAccounting

Stops AuthBy RADSEC forwarding Accounting-Requests. They are ACCEPTED, but

no further action is taken with them. This is different in meaning to IgnoreAccounting,
which IGNOREs them.
# Just ACCEPT Accounting-Requests, dont forward them
NoForwardAccounting
5.64.20 AllowInRequest

This optional parameter specifies a list of attribute names that are permitted in forwarded requests. Attributes whose names do not appear in this list will be stripped from
the request before forwarding.

224 of 397

Radiator RADIUS Server

Configuration

# Strip everything except username and password

AllowInRequest User-Name,User-Password
5.64.21 MaxBufferSize

This parameter has the same meaning as described in <ServerRADSEC> MaxBufferSize on page 289.
5.64.22 ReconnectTimeout

This optional parameter specifies the number of seconds to wait before attempting to
reconnect a failed, dropped or disconnected RadSec connection. It also specifies the
timeout for the initial connect.
5.64.23 Protocol

This parameter has the same meaning as described in <ServerRADSEC> Protocol on

page 290.
5.64.24 ConnectOnDemand

This optional parameter tells AuthBy RADSEC not to connect to the RadSec server as
soon as possible, but to wait until a request has been received that must be sent to that
server. After the RadSec connection has been established and request has been delivered, the connection will remain as long as possible. If the RadSec connection is lost for
any reason, it will only be re-established when and if there is another request to be sent.
5.64.25 TLS configuration parameters

These parameters have the same meaning as described in <ServerRADSEC> on

page 287:

UseTLS
TLS_CAFile
TLS_CAPath
TLS_CertificateFile
TLS_CertificateChainFile
TLS_CertificateType
TLS_PrivateKeyFile
TLS_PrivateKeyPassword
TLS_RandomFile
TLS_DHFile
TLS_CRLCheck
TLS_CRLFile

5.64.26 TLS_ExpectedPeerName

When a RadSec server presents a server certificate, this optional parameter specifies a
regular expression pattern that is required to match the Subject in the server certificate.
# Accept certificates with CN ending in .xyz.com
TLS_ExpectedPeerName CN=.*\.xyz\.com

Radiator RADIUS Server

225 of 397

Configuration

5.64.27 TLS_SubjectAltNameURI

When a RadSec server presents a server certificate, this optional parameter specifies a
regular expression pattern that must match against at least one subjectAltName of type
URI in the server certificate.
# Accept certificates that have a subjectAltName type URI that
# ends in open.com.au:
TLS_SubjectAltNameURI .*open.com.au
5.64.28 TLS_CertificateFingerprint

You can require that the peer matches one of a specified set of signatures with TLS_CertificateFingerprint. When a TLS peer presents a certificate, this optional parameter
specifies one or more fingerprints, one of which must match the fingerprint of the peer
certificate. Format is algorithm:fingerprint. Requires Net::SSLeay 1.37 or later
TLS_CertificateFingerprint sha1:8E:94:50:0E:2F:D6:DE:16:1D:84:76:FE:2F:14:33:2D:AC:57:04:FF
TLS_CertificateFingerprint sha1:E1:2D:53:2B:7C:6B:8A:29:A2:76:C8:64:36:0B:08:4B:7A:F1:9E:9D
TLS_CertificateFingerprint sha256:EC:14:77:FA:33:AD:2C:20:FF:D2:C8:1C:46:31:73:04:28:9E:ED:12
:D7:8E:79:A0:24:C0:DE:0B:88:A9:DB:3C
TLS_CertificateFingerprint
md5:2A:2D:F1:44:40:81:22:D4:60:6D:9A:B0:F4:BF:DD:24

5.65 <Host xxxxxx> within <AuthBy RADSEC>

This clause can be used to specify the name and details of remote RadSec servers inside
<AuthBy RADSEC> and its subtypes. The <Host xxxxxx> clause further allows you to
customize details for individual hosts. <AuthBy RADSEC> permits one or more Host
clauses.
In a Host clause header, the xxxxxx is the Host name or IP address of the remote RadSec host to proxy to. The Host name can contain special formatting characters, which
are resolved at startup.
<AuthBy RADSEC>
<Host server1.test.com>
Secret xyzzy
UseTLS
TLS_CAFile ....
......
</Host>
<Host server2.test.com>
Secret xyzzy
Port 1645
UseTLS 0
</Host>
</AuthBy>

226 of 397

Radiator RADIUS Server

Configuration

5.65.1 Host Parameters from the enclosing AuthBy RADSEC

The following parameters can be used within a Host clause. They have the same meaning and default values as the parameter of the same name in the enclosing AuthBy
RADSEC:

Secret
Port
NoreplyTimeout
FailureBackoffTime
MaxBufferSize
ReconnectTimeout
ConnectOnDemand
Protocol
UseTLS
TLS_CAFile
TLS_CAPath
TLS_CertificateFile
TLS_CertificateChainFile
TLS_CertificateType
TLS_PrivateKeyFile
TLS_PrivateKeyPassword
TLS_RandomFile
TLS_DHFile
TLS_CRLCheck
TLS_CRLFile
TLS_SessionResumption
TLS_SessionResumptionLimit
TLS_ExpectedPeerName
TLS_SubjectAltNameURI
TLS_CertificateFingerprint
MaxFailedRequests
MaxFailedGraceTime

5.66 <AuthBy SASLAUTHD>

This clause authenticates against a saslauthd server running on the same host as Radiator. Saslauthd is a Unix authentication server program, part of the Cyrus SASL suite. It
can be configured to authenticate from a variety of sources, including PAM, Kerberos,
DCE, shadow password files, IMAP, LDAP, SIA or a special SASL user password file.
It is part of the Cyrus SASL suite.

Radiator RADIUS Server

227 of 397

Configuration

AuthBy SASLAUTHD connects to the saslauthd server over a UNIX ___domain socket. It
sends the username, plaintext password, realm and a service name to saslauthd. Saslauthd then authenticates the user using whatever method it has been configured to use and
then sends the response back to AuthBy SASLAUTHD.
Requires that saslauthd be installed, configured and running on the Radiator host.
Hint: you can run saslauthd with the -d flag to get a fairly detailed log of what it is doing
printed to stdout. This can be helpful determining why authentication is failing.
Caution: AuthBy SASLAUTHD is synchronous: it waits until saslauthd responds to an
authentication request before sending a RADIUS response to the NAS. Some authentication methods implemented by saslauthd are slow. For example PAM will wait several
seconds before responding if the password is incorrect (this part of the normal behavior
of PAM; it discourages brute force cracking of passwords)
AuthBy SASLAUTHD understands the following parameters:
5.66.1 SocketPath

This optional parameter specifies the name of the UNIX ___domain socket to use to connect to the saslauthd server. Defaults to /var/lib/sasl2/mux.
# Connect to a non-standard socket
SocketPath /var/state/saslauthd
5.66.2 Service

This optional parameter specifies the service name that will be passed to saslauthd in
each authentication request. The service name is used by some types of saslauthd
authentication methods, for example if saslauthd is using PAM, then this specifies the
PAM service name to use. Defaults to login.
# Use the PAM system-auth method
Service system-auth

5.67 <AuthBy NTLM>

This clause authenticates against a Windows Domain Controller, using the ntlm_auth
program, which is part of the Samba suite (www.samba.org). ntlm_auth runs on all Unix
and Linux platforms, and therefore <AuthBy NTLM> can be used on Unix or Linux to
authenticate to a Windows Domain Controller.
<AuthBy NTLM> supports PAP, MSCHAP, MSCHAPV2 and EAP-MSCHAPV2
authentication. CHAP is not supported due to limitations in the Windows support for
CHAP authentication.
<AuthBy NTLM> requires that ntlm_auth and winbindd, both part of Samba, are
installed and configured correctly. See goodies/smb.conf.winbindd for sample configuration and installation hints.

228 of 397

Radiator RADIUS Server

Configuration

<AuthBy NTLM> runs the Samba utility ntlm_auth as a child process in order to
authenticate requests. It keeps ntlm_auth running between requests and passes it authentication information on stdin, and gets back the authentication results from stdout.
Because AuthBy NTLM requires that ntlm_auth be properly installed and configured
with winbindd, it is vitally important that you confirm that ntlm_auth is working properly before trying to use AuthBy NTLM. You can test ntlm_auth like this:
ntlm_auth --username=yourusername --___domain=yourdomain --password=yourpassword

if that does not work for a valid username and password, there is no way that AuthBy
NTLM will work. Make sure ntlm_auth works first!
Caution: AuthBy NTLM blocks while waiting for the result output of ntlm_auth.
Hint: If you are running Radiator on Windows, and wish to authenticate to Windows
Active Directory or to a Windows Domain Controller, see <AuthBy LSA> on
page 192.
Hint: Depending on the ownerships and permissions of certain samba files, Radiator
may need to run with root permission.
AuthBy NTLM understands the following parameters:
5.67.1 Domain

This optional parameter specifies which Windows ___domain will be used to authenticate
passwords, regardless of whether the user supplies a ___domain when they log in. It can be
the name of any valid ___domain in your network. Special characters are permitted. The
default is to use the ___domain configured into winbindd.
Domain OPEN
5.67.2 DefaultDomain

This optional parameter specifies the Windows Domain to use if the user does not specify a ___domain in their username. Special characters are supported. Can be an Active
directory ___domain or a Windows NT ___domain controller ___domain name. Empty string (the
default) means the ___domain configured into winbindd.
DefaultDomain OPEN
5.67.3 NtlmAuthProg

This optional parameter specifies the path name and arguments for the ntlm_auth program. Defaults to /usr/bin/ntlm_auth --helper-protocol=ntlm-server-1.
Hint: The --helper-protocol=ntlm-server-1 is an important part of the arguments to
ntlm_auth and is required for the correct interaction between AuthBy NTLM and ntlm_auth. If it is not included, AuthBy NTLM will not work correctly.
Hint: You can require that authenticated users belong to a certain group with:

Radiator RADIUS Server

229 of 397

Configuration

NtlmAuthProg /usr/bin/ntlm_auth --helper-protocol=ntlm-server1 --require-membership-of=MyGroupName

Hint: you can specify that the NTLM authentication requests appear to come from a
workstation with a specified name. This can be used to restrict authentication for certain
users by setting workstation requirements in their Windows user configuration.
NtlmAuthProg /usr/bin/ntlm_auth --helper-protocol=ntlm-server1 --workstation=MyWorkstationName
5.67.4 UsernameMatchesWithoutRealm

Forces AuthBy NTLM to strip any realm from the username before authenticating to the
___domain controller.
5.67.5 UsernameFormat

Controls how the user name that will be sent to NTLM will be derived from User-Name
in the incoming request. Special characters are permitted. %0 is replaced with the username portion of ___domain\username. Defaults to %0.
5.67.6 DomainFormat

Controls how the ___domain name that will be sent to NTLM will be derived from UserName in the incoming request. Special characters are permitted. %0 is replaced with the
___domain portion of ___domain\username. Defaults to %0.
5.68 <AuthBy DNSROAM>
This clause proxies RADIUS requests to remote RADIUS and/or RadSec servers based
on the Realm in the User-Name. The appropriate server to send to and the protocol to
use is discovered through DNS lookups configured through the Resolver clause (see
Section 5.94 on page 271). You must include a <Resolver> clause in your configuration
if you intend to use <AuthBy DNSROAM>.
AuthBy DNSROAM is intended to make it easy to set up a secure, reliable, low maintenance RADIUS/RadSec federation. A RADIUS federation (sometimes called a
RADIUS mesh) is a set of RADIUS servers, operated by a set of independent but cooperating organizations. The goal is to permit users who belong to one organization to be
able to use RADIUS-controlled resources at another organization. A typical example is
for a group of Universities to cooperate to permit a user from one University to
connect to the wireless network at any other University in the group using their home
username and password. Radiator also permits RADIUS requests to be sent to another
Radiator server through RadSec. RadSec provides secure, encrypted, reliable transport
of RADIUS requests, with optional mutual authentication of RadSec client and server.
See
http://www.open.com.au/radiator/radsec-whitepaper.pdf
for more details on the RadSec protocol.
Using AuthBy DNSROAM and DNS to hold information about the target server for
each Realm permits convenient and scalable administration of the routing topology
within a RADIUS/RadSec mesh.

230 of 397

Radiator RADIUS Server

Configuration

DNSROAM cooperates well with existing RADIUS infrastructure, and can interoperate
with other RADIUS servers and clients, as well as other RadSec servers and clients. It
supports hardwired preconfigured RADIUS and RadSec routes as well as DNS discovered routes. It can provide a default fallback, so that Realms that are neither discovered
nor hardwired can be forwarded to some catchall server (or dropped). It supports forwarding to IPv4 and/or IPv6 addresses. RadSec can use TCP or SCTP protocol for
transport over IPv4 or IPv6. DNSROAM supports discovering RADIUS proxy servers
as well as RadSec proxy servers.
The <AuthBy DNSROAM> clause can contain one or more <Route> subclauses which
specify hardwired target servers for certain Realms or a DEFAULT fallback server.
<Route> subclauses can specify RADIUS or RadSec target servers.
A sample configuration file showing how to use <Resolver>, <AuthBy DNSROAM>
and <Route> clauses together can be found in goodies/dnsroam.cfg in your
Radiator distribution.
AuthBy DNSROAM uses the following algorithm when it receives a RADIUS request
for handling:
1. Extract the Realm from the User-Name in the RADIUS request. (The username and/

or realm can be configured to be rewritten by patterns in the enclosing Handler or

Client clause).
2. Look for a preconfigured target server <Route> subclause for that Realm.
3. If no preconfigured target server <Route> subclause is found for that Realm, try to

discover a target server name or address using DNS (more below on exactly how this
is done).
4. If no target server is preconfigured or discovered, try to find a DEFAULT preconfig-

ured target server <Route> subclause.

5. If there is still no target server found, log and drop the request.
6. If the target server is a RadSec server (Protocol=radsec) establish a RadSec connec-

tion to the target server (using a private AuthBy RADSEC clause), and if so configured, set up TLS tunnel and perform mutual authentication based on PKI
certificates.
7. If the target server is a RADIUS server (Protocol=radius) forward the request using

RADIUS protocol over UDP (using a private AuthBy RADIUS clause).

8. When a reply is received from the target server, send the reply back to wherever the

request originally came from (there may be multiple proxying hops until the request
reaches the home RADIUS server for that Realm).
AuthBy DNSROAM creates private AuthBy RADIUS and/or AuthBy RADSEC
clauses to implement each discovered and hardwired RADIUS and RadSec Route. The
default values for the parameters for these private clauses are obtained from the enclosing <Route> and/or <AuthBy DNSROAM> clauses.
AuthBy DNSROAM clause, and can be overridden by <Route> clause parameters and
parameters discovered from DNS by the <Resolver> clause, as documented below.

Radiator RADIUS Server

231 of 397

Configuration

AuthBy DNSROAM understands the following parameters, as well as those described

in <AuthBy xxxxxx> on page 82.
5.68.1 RewriteTargetRealm

This optional parameter can be used to specify one or more rewriting rules which will
be used to rewrite the Realm name used by Resolver to discover the appropriate target
server.
# Find the target server for [email protected] by looking up
# as if it were @no.eduroam.org
RewriteTargetRealm s/uninett.no/no.eduroam.org/

You can also set up a default realm that will be used if there is no realm in the username
after rewriting by having the last RewriteTargetRealm like this:
RewriteTargetRealm s/^$/default.realm.com/
5.68.2 RedespatchIfNoTarget

For a given request, if Resolver does not find a target and there is no explicit Route, and
no DEFAULT Route and this flag is set, the request will be redespatched to the Handler/
Realm system for handling. This allows for a flexible fallback in the case where DNSROAM cannot find how to route a request. The redespatched request will have the
attribute OSC-Environment-Identifier set to the AuthBy DNSROAMs Identifier value
or DNSROAM if the Identifier is not set.
5.68.3 <Route> parameters

Any of the following <Route> parameters may be placed in <AuthBy DNSROAM> as

defaults for the enclosed <Route> clauses:
Address Transport Protocol Port UseTLS
5.68.4 <AuthBy RADIUS> parameters

Any of the following <AuthBy RADIUS> parameters may be placed in AuthBy DNSROAM as defaults for any RADIUS proxy. These defaults can be overridden for individual Routes in the <Route> clause, and can be overridden by automatically
discovered Routes. See <AuthBy RADIUS> on page 125 for more details.

StripFromRequest AddToRequest ReplyHook NoReplyHook NoForwardAuthentication NoForwardAccounting AllowInRequest AuthPort AcctPort Secret Retries RetryTimeout UseOldAscendPasswords ServerHasBrokenPortNumbers
ServerHasBrokenAddresses IgnoreReplySignature UseExtendedIds MaxFailedRequests MaxFailedGraceTime FailureBackoffTime.
5.68.5 <AuthBy RADSEC> parameters

Any of the following <AuthBy RADSEC> parameters may be placed in AuthBy DNSROAM as defaults for any RADSEC proxy. These defaults can be overridden for individual Routes in the <Route> clause, and can be overridden by automatically
discovered Routes. See <AuthBy RADSEC> on page 219 for more details.

232 of 397

Radiator RADIUS Server

Configuration

Port Secret UseTLS StripFromRequest AddToRequest ReplyHook NoReplyHook

NoForwardAuthentication NoForwardAccounting AllowInRequest NoreplyTimeout
IgnoreReject IgnoreAccountingResponse FailureBackoffTime MaxBufferSize ReconnectTimeout ConnectOnDemand UseTLS TLS_CAFile TLS_CAPath TLS_CertificateFile TLS_CertificateChainFile TLS_CertificateType TLS_PrivateKeyFile
TLS_PrivateKeyPassword TLS_RandomFile TLS_DHFile TLS_CRLCheck
TLS_CRLFile TLS_SessionResumption TLS_SessionResumptionLimit TLS_ExpectedPeerName TLS_SubjectAltNameURI TLS_CertificateFingerprint.
5.69 <Route>
Route clauses can be used inside an <AuthBy DNSROAM> clause to explicitly specify
target servers and protocols for certain Realms, or a DEFAULT fallback server.
The Route clause understands the following parameters. In general, all the Route
parameters default to the parameter of the same name in the enclosing AuthBy
DNSROAM.
5.69.1 Realm

Specifies the Realm that this Route will apply to. All requests with a User-Name whose
Realm component (after applying any RewriteTargetRealm rules) match this realm will
by processed using this Route. If the Realm is DEFAULT then this Route will be used
to process requests for which no explicit Route exists, and no route could be discovered
through DNS and the <Resolver> clause.
5.69.2 Address

Specifies the name or address of the target server to be used to process requests for this
Route. Defaults to localhost.
5.69.3 Transport

Specifies the transport to be used to contact the target server. Can be sctp, tcp, or
udp. Defaults to tcp.
5.69.4 Protocol

Specifies the protocol to be used to contact the target server. Can be radsec or radius.
Defaults to radsec.
5.69.5 Port

Specifies the port number to be used to contact the target server. Defaults to 2083, the
standard port number for RadSec protocol.
5.69.6 UseTLS

Specifies whether TLS is to be used to encrypt the connection to the target server. Valid
only for Protocol=radsec. Although it is possible to not use TLS for a RadSec connection, it is recommended that RadSec connections always be configured to use TLS.
Defaults to true.
5.69.7 <AuthBy RADIUS> parameters

Any of the following <AuthBy RADIUS> parameters may be placed in <Route> as

defaults for a RADIUS proxy. See <AuthBy RADIUS> on page 125 for more details.
Radiator RADIUS Server

233 of 397

Configuration

StripFromRequest AddToRequest ReplyHook NoReplyHook NoForwardAuthentication NoForwardAccounting AllowInRequest AuthPort AcctPort Secret Retries RetryTimeout UseOldAscendPasswords ServerHasBrokenPortNumbers
ServerHasBrokenAddresses IgnoreReplySignature UseExtendedIds MaxFailedRequests MaxFailedGraceTime FailureBackoffTime.
<AuthBy DNSROAM>
# Defaults for all enclosed Routes:
Port 1645

Transport udp
Protocol radius
Secret mysecret
<Route>
Realm realm3.open.com.au
Address oscar.open.com.au
# Override parameters for AuthBy RADIUS
Secret xyzzy
</Route>
...
</AuthBy>
5.69.8 <AuthBy RADSEC> parameters

Any of the following <AuthBy RADSEC> parameters may be placed in <Route> as

defaults for a RADSEC proxy. See <AuthBy RADSEC> on page 219 for more
details.
Port Secret UseTLS StripFromRequest AddToRequest ReplyHook NoReplyHook
NoForwardAuthentication NoForwardAccounting AllowInRequest NoreplyTimeout
IgnoreReject IgnoreAccountingResponse FailureBackoffTime MaxBufferSize ReconnectTimeout ConnectOnDemand UseTLS TLS_CAFile TLS_CAPath TLS_CertificateFile TLS_CertificateChainFile TLS_CertificateType TLS_PrivateKeyFile
TLS_PrivateKeyPassword TLS_RandomFile TLS_DHFile TLS_CRLCheck
TLS_CRLFile TLS_SessionResumption TLS_SessionResumptionLimit TLS_ExpectedPeerName TLS_SubjectAltNameURI TLS_CertificateFingerprint.
<AuthBy DNSROAM>
# Defaults for all enclosed Routes:
Port 1645

Transport tcp
Protocol radsec
UseTLS 1
Secret mysecret
TLS_CAFile ....
.....
<Route>
Realm realm3.open.com.au
Address oscar.open.com.au
# Override parameters for AuthBy RADSEC
Secret xyzzy
UseTLS 0
......
</Route>

234 of 397

Radiator RADIUS Server

Configuration

...
</AuthBy>

5.70 <AuthBy SAFEWORD>

This clause authenticates users from a local or remote SafeWord PremierAccess (SPA)
server. SafeWord PremierAccess and tokens are available from SecureComputing
(http://www.securecomputing.com). Supports PAP, CHAP, TTLS-PAP, EAP-OTP and
EAP-GTC. Supports password changing. Supports fixed (static) passwords and SafeWord Silver and Gold tokens.
Only the first authenticator configured into SPA for the user will be used by Radiator to
authenticate the user. The second and subsequent authenticators configured for a user
will be ignored.
Note: in order to support CHAP, the user must have a fixed password profile with case
sensitive password enabled in the SafeWord server.
Note: A user can changed their fixed password at any time by entering their current and
new passwords in a special format. The password change will only succeed if the old
password is correct, and the two copies of the new password are identical and conform
to the password length and other constraints configured into SPA for the users fixed
password authenticator.
oldpassword\cnewpassword,newpassword

AuthBy SAFEWORD understands the following parameters, as well as those described

in <AuthBy xxxxxx> on page 82.
5.70.1 Host

This parameter specifies the name or address of the SafeWord PremierAccess server to
connect to. The connection will be made with SSL. Defaults to localhost.
5.70.2 Port

This parameter specifies the port name or number to connect to on Host. Defaults to
5031, the default SafeWord EASSP2 port.
5.70.3 SSLVerify, SSLCAFile, SSLCAPath, SSLCAClientCert, SSLCAClientKey,
SSLCAClientKeyPassword

These parameters are used to control the SSL connection to the SafeWord server. They
do not usually need to be set or altered. They behave as described in <AuthBy IMAP>
on page 190.
5.71 <AuthBy FREERADIUSSQL>
This clause handles authentication and accounting from a FreeRadius compatible SQL
database. The default SQL queries use the standard FreeRadius tables radcheck, radreply, radgroupcheck, radgroupreply and radacct.

Radiator RADIUS Server

235 of 397

Configuration

Hint: the sample configuration file in goodies/freeradiussql.cfg in your

Radiator distribution shows how to set up a complete FreeRadius emulator. Use of this
configuration file can make migration from an existing FreeRadius installation easy.
AuthBy FREERADIUSSQL understands the following parameters besides those
described in <AuthBy SQL> on page 111:
5.71.1 AuthCheck

This optional parameter specifies an SQL query that is used to get check items for a
user. Special characters are supported, as well as a single bind variable for the user name
being searched. Defaults to:
SELECT id, UserName, Attribute, Value, op FROM radcheck WHERE
Username=? ORDER BY id
5.71.2 AuthReply

This optional parameter specifies an SQL query that is used to get reply items for a user.
Special characters are supported, as well as a single bind variable for the user name
being searched. Defaults to:
SELECT id, UserName, Attribute, Value, op FROM radreply WHERE
Username=? ORDER BY id
5.71.3 AuthGroupCheck

This optional parameter specifies an SQL query that is used to get check items for a
users group. Special characters are supported, as well as a single bind variable for the
group name being searched. Defaults to:
SELECT radgroupcheck.id,radgroupcheck.GroupName,radgroupcheck.Attribute,radgroupcheck.Value,radgroupcheck.op FROM
radgroupcheck,usergroup WHERE usergroup.Username = ? AND usergroup.GroupName = radgroupcheck.GroupName ORDER BY radgroupcheck.id
5.71.4 AuthGroupReply

This optional parameter specifies an SQL query that is used to get reply items for a
users group. Special characters are supported, as well as a single bind variable for the
group name being searched. Defaults to:
SELECT radgroupreply.id,radgroupreply.GroupName,radgroupreply.Attribute,radgroupreply.Value,radgroupreply.op FROM
radgroupreply,usergroup WHERE usergroup.Username = ? AND usergroup.GroupName = radgroupreply.GroupName ORDER BY radgroupreply.id
5.71.5 AcctOnoffQuery, AcctStartQuery, AcctStartQueryAlt, AcctUpdateQuery,
AcctUpdateQueryAlt, AcctStopQuery, AcctStopQueryAlt

These optional parameters specify SQL queries to handle various accounting requests
by inserting or updating the radacct table. The Alt versions are run if the non-Alt version fails (usually because the appropriate accounting record is missing).

236 of 397

Radiator RADIUS Server

Configuration

5.71.6 AcctFailedLogFileName, AcctLogFileFormat and AcctLogFileFormatHook

These parameters have the same meaning as described in <AuthBy SQL> on

page 111.
5.72 <AuthBy HTGROUP>
Checks group membership according to an Apache htgroup file. Apache is a popular
HTTP server, and supports flat group files for authenticating web access. With <AuthBy
HTGROUP> Radiator can authenticate users against the same files that Apache uses, in
order to provide a single source of authentication information for both Apache and
Radiator.
In order to use <AuthBy HTGROUP>, the user record must specify an AuthBy check
item naming the Identifier of the AuthBy HTGROUP to be used. See the example in
goodies/htgroup.cfg for details. During authentication, the users GroupList
check items will be used to check for group membership against the Apache group file
specified by the GroupFilename parameter.
<AuthBy GROUP> understands the following parameters:
5.72.1 GroupFilename

Specifies the name of the Apache group file to consult. Special characters are supported
(so you may have a different group files for different categories of users).
5.73 <AuthBy FIDELIO>
<AuthBy FIDELIO> authenticates users from Micros-Fidelio Opera. Opera is a popular
hotel Property Management System from Micros Fidelio (http://www.micros.com).
AuthBy FIDELIO acquires the hotel guest list from Opera, and by default, authenticates
each guest using their Room Number as the User-Name and their Guest Number as their
password (this is configurable). By default, RADIUS Accounting Stops generate Opera
PS simple postings. This can be changed with the PostingRecordID parameter.
Technical Note: If the acquired guest list is empty, this may be caused by Opera settings
where the full guest list synchronization is disabled. This option needs to be enabled for
AuthBy FIDELIO to work.
By default, accounting postings are sent to Opera following receipt of an AccountingStop. The default PS record will contain:

P# Automatically generated posting sequence number, starting at 1.

TA the cost computed by ComputeCostHook or CentsPerSecond.
DU The call duration in seconds.
PT fixed value of C (Direct Charge).
SO fixed value of Internet connection.
DD Called-Station-Id from the incoming request, with any non-digit characters
stripped out.

Radiator RADIUS Server

237 of 397

Configuration

Additional fields can be added to the Opera posting record with the PostingExtraFields
parameter.
AuthBy FIDELIO requires a connection to the Opera computer system. Both RS232
serial and TCP/IP (Ethernet) connections are supported. In order to support RS232,
requires Device::SerialPort, available from CPAN.
<AuthBy FIDELIO> understands the following parameters:
5.73.1 Protocol

Specifies the protocol to be used to connect to Opera. serial or tcp are supported. If
serial is specified, AuthBy FIDELIO will open the serial port specified by Port and
configure it to use the RS232 parameters specified by Baudrate, Databits, Parity and
Stopbits and Handshake. If tcp is specified, AuthBy FIDELIO will connect to Opera
by TCP/IP, using the parameters Host and Port. Defaults to tcp
5.73.2 Port

When Protocol is serial, specifies the device name of the serial port to use (defaults to /
dev/ttyS0). When Protocol is tcp, specifies the service name or number of the TCP/IP
port to connect to (defaults to 5010, the standard Opera TCP/IP port).
5.73.3 Host

When Protocol is tcp, specifies the DNS name or address of the Opera host. Defaults to
localhost.
5.73.4 Baudrate

When Protocol is serial, specifies the baud rate for the serial port. Defaults to 9600.
5.73.5 Databits

When Protocol is serial, specifies the number of data bits for the serial port. Defaults to
8.
5.73.6 Parity

When Protocol is serial, specifies the data parity for the serial port. May be odd, even
or n. Defaults to n.
5.73.7 Stopbits

When Protocol is serial, specifies the number of stop bits for the serial port. Defaults to
1.
5.73.8 Handshake

When Protocol is serial, specifies the handshaking standard for the serial port. May be
none, rts or xoff. Defaults to xoff.
5.73.9 ReadCharTimeout

When Protocol is serial, specifies the character read timeout in milliseconds. Defaults to
2000ms. This should not need to be changed.

238 of 397

Radiator RADIUS Server

Configuration

5.73.10 TransmitTimeout

Specifies the time in seconds to wait before retransmitting an unacknowledged message

to Opera. Default to 2 seconds. This should not need to be changed.
5.73.11 ReconnectTimeout

Specifies the time in seconds to wait before attempting to reconnect to Opera after the
connection is lost. Defaults to 5 seconds.
5.73.12 InterfaceFamily

Specifies the interface family that AuthBy FIDELIO will send to Opera, identifying the
type of interface Opera is to use to communicate with Radiator. Defaults to WW, the
standard Opera code for Internet.
5.73.13 FieldSeparator

Specifies the field separator character to be sued by Opera. Defaults to |. This should
not need to be changed.
5.73.14 BindAddress

When Protocol is tcp, specifies the bind address to be used for the TCP/IP port. Defaults
to the global BindAddress (if specified) or 0.0.0.0. Useful to specify the source address
interface to use for multi-homed hosts. See Global parameters on page 28.
5.73.15 MaxBufferSize

Specifies the maximum read buffer size. Defaults to 100000. Should not need to be
changed.
5.73.16 UseChecksums

Specifies whether to use checksums in the communications with Opera. The correct setting for this depends on the version of Opera, but a setting of disabled will work for
most modern installations. Defaults to enabled (1) for serial Protocol and disabled (0)
for tcp Protocol.
5.73.17 LinkRecords

Specifies the list of required fields for each message type in messages passed between
Radiator and Opera. May be specified one per line for each type of message. This
should only need to be changed if additional data is required for each gust in the GI
(Guest In), GO (Guest Out) and GC (Guest Change) messages. Defaults to:
GI
GO
GC
PS
PA

FLG#RNGNSF
FLG#RNS
FLG#RNGN
FLP#RNPTTATIDUDADDSOCT
FLASRNP#DATICT

5.73.18 GuestNameField

Specifies the name of the Opera guest field that will be used match the User-Name in
authentication requests. Defaults to RN (Room Number).

Radiator RADIUS Server

239 of 397

Configuration

5.73.19 ComputeCostHook

Specifies an optional perl hook that can be used to calculate the cost when a RADIUS
Accounting Stop is received. The hook is passed the call duration in seconds, and is
expected to return the cost in cents. If ComputeCostHook is not specified, then CentsPerSecond will be used to calculate the cost.
5.73.20 UserPasswordHook

Specifies an optional perl hook that can be used to determine the correct password for
the user. It is passed a reference to a hash containing the guests Opera data (as received
in a GI message from Opera). It is expected to return the correct user password in plaintext. The default is:
UserPasswordHook sub {return $_[1]->{G#}}

which specifies the guests Guest Number (G#) is to be used as their password.
5.73.21 CentsPerSecond

When UserPasswordHook is not specified, this number will be used to compute the cost
to be used in the accounting PS resulting from a RADIUS Accounting Stop. The charge
will be computed from the call duration (in seconds) times CentsPerSecond.
5.73.22 PostingRecordID

Defines the type of transaction code to be used for sending Posting records to Opera.
Defaults to PS but can be changed to PR. Caution: Use of PR would also require a suitable LinkRecords entry for the desired PR data (see example below).
See the Fidelio Interface Application Specification document for more details on field
types and codes that can be sent to Opera.
5.73.23 PostingExtraFields

List of fields that are to be added to the standard fields sent to Opera in a Posting transaction. These are sent in addition to the standard ones of P#, TA, DU, PT, SO, CT and
DD. Format is in the form: <fieldid>,<data>. Where <fieldid> is the 2 letter FieldID and
<data> is the data to be sent in that field (special characters are permitted).
The special characters in <data> may include:

%0 the user (room) name

%1 the posting sequence number
%2 the cost computed by CentsPerSecond or ComputeCostHook
%3 the duration of the connection in hhmmss format
%4 the reservation number (G#) corresponding to the room number

In the following example, the type of posting is changed to PR, and the PR is defined to
use the P#, TA, DU, PT, SO, CT and DD field (the defaults) and the additional field T1
(tax code). When a posting is sent, the T1 tax code is set to 3, and the additional G# (reservation number) is set to the users reservation number from the Opera database.
PostingRecordID PR
LinkRecords PR,FLP#RNPTTATIDUDADDSOCTT1

240 of 397

Radiator RADIUS Server

Configuration

PostingExtraFields T1,3
PostingExtraFields G#,%4
5.73.24 MessageHook

MessageHook is called after a message from Fidelio has been unpacked into a hash and
before the record is passed to handle_message(). It can be used to change or transform
any fields in the record before it is passed to handle_message() and processed by AuthFIDELIO. The first argument is a pointer to the AuthBy FIDELIO clause, and the second is a pointer to a hash containing the unpacked record fields.
5.73.25 CheckoutGraceTime

Specifies a number of seconds after check-out to still allow a user to log in. Defaults to
0.
5.74 <AuthBy FIDELIOHOTSPOT>
This specialization of AuthBy FIDELIO, provides an easy way to integrate WiFi hotspots and captive portals with Opera hotel Property Management System from Micros
Fidelio (http://www.micros.com).
It uses an SQL database to keep track of pre-paid access time blocks for Opera guests. It
authenticates new sessions with the guests room number and guest number (as with
AuthBy FIDELIO), creates new prepaid blocks (and posts the charge to Opera), and
keeps track of the remaining time left in each prepaid block.
<AuthBy FIDELIOHOTSPOT> understands the following parameters, as well as those
in <AuthBy FIDELIO> on page 237 and <AuthBy SQL> on page 111.
5.74.1 BlockDuration

Specifies a number of seconds a prepaid block of time will last for, from the time it is
first purchased. Defaults to 86400 (1 day).
5.74.2 BlockPrice

Specifies a number of cents a prepaid block of time costs. Defaults to 900 cents ($9.00).
This cost will be posted to Opera whenever a new block is purchased.
5.75 <AuthBy PRESENCESQL>
<AuthBy PRESENCESQL> authenticates users from an SQL database and records
presence (current user ___location) to an SQL database. Implements a special form of
RADIUS Access-Request that allows user presence data to be retrieved by suitably
authorized devices.
This module can be used with telephone and VOIP systems to automatically route telephone calls according to the users current ___location.
A sample configuration file and documentation can be found in goodies/presencesql.cfg in your distribution.

Radiator RADIUS Server

241 of 397

Configuration

5.76 <AuthBy HANDLER>

This clause allows requests to be redirected to a Handler based on the Handlers Identifier. This allows rapid selection of a Handler from amongst many Handlers using a
hash-based match, instead of relying on the normal linear search that is used to find
<Handler> clauses. This can be useful in special cases where there are many Handlers,
and where a PreHandlerHook is able to identify the correct Handler to use.
When <AuthBy HANDLER> runs, it uses the HandlerId to create the name of the
desired Handler to use. The named Handler is found based on its Identifier, and the
request is redirected to that Handler.
<AuthBy HANDLER> understands the following parameters:
5.76.1 HandlerId

This optional parameter specifies how to derive the Identifier of the Handler to use to
handle requests. When a request is received by AuthBy HANDLER, this string will be
used to derive a Handler Identifier. If a Handler with that Identifier is found, the request
will be redespatched to that Handler. Special characters are supported. Defaults to handler%{Request:Called-Station-Id}
5.77 <AuthBy WIMAX>
This clause handles requests from a WiMAX system. It handles, authentication,
accounting and DHCP server key distribution. It acts as a Home AAA (HAAA) as per
WiMAX End-to-End Network Systems Architecture Stage 2-3 Release 1.1.0 and
NWG_R1.1.0-Stage-3.pdf. Answers requests from NAS, HA and DHCP servers.
AuthBy WIMAX requires an SQL database to hold user details (including password),
and to cache various keys. WiMAX users must be added to the SQL database before
they can be authenticated.
Several types of reply attribute are handled specially by AuthBy WIMAX. If the attribute is present in a reply (perhaps from a users reply attributes or profile), they will be
converted from text format to the binary format required by WiMAX devices.

WiMAX-Packet-Flow-Descriptor
A WiMAX packet flow descriptor. Example:
Packet-Data-Flow-ID=01,Service-Data-Flow-ID=1,Direction=BiDirectional,Transport-Type=IPv4-CS,Activation-Trigger="Activate",Uplink-QoS-ID=1,Downlink-QoS-ID=2

WiMAX-QoS-Descriptor
A WiMAX QOS descriptor. Example:
QoS-ID=1,Media-Flow-Type=Robust-Browser,Schedule-Type=BESTEFFORT,Traffic-Priority=0,Maximum-Sustained-Traffic-Rate=128000

Sample configuration file, including explanation of supported parameters is available in

goodies/ wimax.cfg. Sample database schema appears in goodies/wimax.sql in your
Radiator distribution.

242 of 397

Radiator RADIUS Server

Configuration

5.77.1 KeyLifetime

This optional parameter specifies the lifetime for all mobility keys in seconds. Defaults
to 3600 (1 hour).
5.77.2 HAPassword

This optional parameter specifies the PAP password required for access by a WiMAX
HA (Home Agent). If not defined, HA does not have to present a password before its
requests are satisfied. If HAPassword is defined, the HA must present a PAP password
with an exact match, and the HA must be configured to send this password, otherwise
its requests will be REJECTed. Not all HAs are able to send a password with requests to
the HAAA, so use of this parameter depends on your HA. Defaults to undefined.
5.77.3 ProfileHotlining

This optional parameter indicates whether to provide profile-based hotlining. If set, and
the user has a Hotline Profile ID, the SQL database will be consulted for the Hotline
profile, and the contents of the hotline profile id will be returned. Defaults to not set.
5.77.4 RulebasedHotlining

This optional parameter indicates whether to provide rule-based hotlining. If set, and the
user has a Hotline Profile ID, the SQL database will be consulted for the Hotline profile,
and the contents of the hotline NAS-Filter-Rule will be returned. Defaults to not set.
5.77.5 HTTPRedirectionHotlining

This optional parameter indicates whether to provide HTTP Redirection-based hotlining. If set, and the user has a Hotline Profile ID, the SQL database will be consulted for
the Hotline profile, and the contents of the hotline HTTP-Redirection-Rule will be
returned. Defaults to not set.
5.77.6 IPRedirectionHotlining

This optional parameter indicates whether to provide IP Redirection-based hotlining. If

set, and the user has a Hotline Profile ID, the SQL database will be consulted for the
Hotline profile, and the contents of the hotline IP-Redirection-Rule will be returned.
Defaults to not set.
5.77.7 MSKInMPPEKeys

Forces the MSK to be encoded in MS-MPPE-Send-Key and MS-MPPE-Recv-Key, as

well as the usual WiMAX-MSK reply attributes. This is required by some non-compliant clients, such as some Alcatel-Lucent devices.
5.77.8 GetCachedKeyQuery

SQL query to get the cached keys for a given AAA-Session-ID. Defaults to:
select sessionid, mip_rk, mip_spi, fa_rk from device_session
where sessionid=?
5.77.9 InsertSessionQuery

SQL query to get create a new session for a given AAA-Session-ID. Defaults to:
insert into device_session (outer_nai, sessionid, napid, bsid,
nspid, msid, capabilities, timezoneoffset, nai, cui, mip_rk,

Radiator RADIUS Server

243 of 397

Configuration

mip_spi, fa_rk, key_expires) values (?, ?, ?, ?, ?, ?, ?, ?, ?,

?, ?, ?, ?, ?)
5.77.10 UpdateSessionQuery

SQL query to get update a session for a given AAA-Session-ID. Defaults to:
update device_session set outer_nai=?, nai=?, cui=?, mip_rk=?,
mip_spi=?, fa_rk=?, key_expires=? where sessionid=?
5.77.11 GetHotlineProfileQuery

SQL query to get hotlining parameters. Defaults to:

select profileid, httpredirectionrule, ipredirectionrule, nasfilterrule, sessiontimer from hotlineprofile where id=?
5.77.12 GetQosProfileQuery

SQL query to get QOS parameters. Defaults to:

select globalscname, scname, scheduletype, priority, maxsusrate, minresrate, maxburst, jitter, maxlatency, reducedresources, flowtype, grantinterval, sdusize, unsolpollinginterval
from qosprofile where id=?

5.78 <AuthBy SQLYUBIKEY>

Yubikeys are small USB tokens for one-time-password authentication. They are produced by Yubico (yubico.com) and are relatively inexpensive. Much of the surrounding
technology and sample code is open source. They can support one factor or 2 factor
authentication, but not challenge-response.
A Yubikey produces a unique one-time-password each time the little button on it is
pressed. The interesting thing is that the Yubikey acts like a USB keyboard, so the onetime-password is automatically typed into wherever the keyboard cursor is placed. This
means that the user does not have to type in their token code by hand, as with many
other tokens. It also means that it can work easily with many existing wired and wireless
authentication methods, supplicants, web pages, Radius clients and other applications.
The keys work on Windows, Linux, Mac OSX and other platforms.
Each Yubikey has a secret AES key programmed into it in the factory. This secret key
can be used to authenticate the key against any of the public services provided by
Yubico. In order to use a Yubikey in a 3rd party authentication service such as Radiator,
it is necessary to reprogram each token with a new (known) AES secret key, and to
record that same key in the Radiator database. See below for more information about
that process.
Yubico provide a number of sample open source programs for managing and authenticating Yubikeys. A typical one is the Yubico Java Server, a YubiKey OTP validation
server in Java. This is a Tomcat application which provides an HTTP based web service
API for authenticating Yubikeys. It looks up the secret key in a MySQL database and
checks whether a Yubikey one-time password is correct.

244 of 397

Radiator RADIUS Server

Configuration

Radiator now ships with the AuthBy SQLYUBIKEY module and a sample configuration file in goodies/yubikey.cfg. It supports RADIUS PAP, EAP-One-Time-Password
and EAP-Generic-Token-Card protocols.
RAdmin from Open System Consultants (http://www.open.com.au/radmin) also supports Yubikeys, and provides an easy-to-use web-based tool for administering users and
Yubikey tokens, including importing, allocating and deallocating tokens to users. 2 factor authentication is also supported in RAdmin.
The design of the AuthBy SQLYUBIKEY module allows it to be configured to work
with a wide range of database schemas, but by default it works with the same schema
that comes with the Yubico Java Server mentioned above. This means that you can provide web services API based authentication _and_ Radius authentication for Yubikeys
from the one token database.
AuthBy SQLYUBIKEY can be optionally configured to support or require 2 factor
authentication if the token database also contains a static password for each user. In this
case, the user types their static password first, followed by a colon (:), followed by the
output from the one-time-password token. The user will only be authenticated if both
the static password and the one-time password are correct. AuthBy SQLYUBIKEY supports replay attack detection: any attempt to use the same one-time-password twice in a
row will fail. For example, if the users static password was fred, the resulting password would be something like:
fred:ccccccccefeiujbfhkhfurbitjcvuvnedivhbeighuvf

Radiator does not come with any tools for managing the Yubikey token database. Use
RAdmin (http://www.open.com.au/radmin), or use one of the tools provided by Yubico.
It would be relatively easy to integrate this with almost any existing user database.
The example configuration file goodies/yubikey.cfg in the Radiator distribution shows
the main configuration options. It will work by default with the database schema provided with Yubico Java Server, but can be customized for many other SQL database
schemas. It assumes the token ID and secret are in the database in Hex (no spaces) format, and that there is a one-to-one mapping between Yubikeys and users. Other formats
and multiple key or multiple user mappings can be supported with custom SQL query
parameters.
Hint: Radiator can also authenticate Yubikeys against the Yubikey Validation Server.
See <AuthBy YUBIKEYVALIDATIONSERVER> on page 247. Another possibility
is to use the Yubikey PAM module and AuthBy PAM.
AuthBy SQLYUBIKEY supports EAP-OTP and EAP_GTC for use with various EAP
compatible devices.
AuthBy SQLYUBIKEY requires the Auth-Yubikey_Decrypter-0.05 module from
CPAN (www.cpan.org) and the Crypt::Rijndael module, also available from CPAN.
AuthBy SQLYUBIKEY understands the following parameters, as well as those
described in <AuthBy xxxxxx> on page 82.

Radiator RADIUS Server

245 of 397

Configuration

5.78.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database. They need to be set in a
similar way to as for <AuthBy SQL> (see Section 5.30 on page 111). They specify the
DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserspassword
5.78.2 AuthSelect

Specifies an SQL query that will be used to fetch Yubikey data from the database. Special characters are permitted, and %0 is replaced with the quoted user name, the Token
ID in Base64 format in %1, the Token ID in hex format in %2 and the Token ID in modhex format in %3. The result field 0 (secret) is the base64 encoded AES secret for the
key. It must be present for the authentication to succeed. All others fields are optional. If
field 1 (active) is defined is must be 1 else the authentication is rejected. Field 2 (userId)
is not currently used. Field 3 (counter) is the key use counter. If defined, it will be used
to detect replay attacks, and must be updated by UpdateQuery. Field 4 (session_use) is
the session_use counter. Field 5 is currently ignored. The static password field (field 6)
contains the users correct static password in any of the formats supported by Radiator
including plaintext, {SHA}, {crypt}, {MD5}, {rcrypt}, {mysql}, {mssql}, {nthash},
{dechpwd}, {NS-MTA-MD5}, {clear} etc. TranslatePasswordHook is also supported.
The default works with the sample Yubikey database created by db_schema.sql from the
YubiKey Validation Server. The default is:
AuthSelect select secret, active, userId, counter, low,
high,NULL from yubikeys where userId=%0

which assumes that there is a one-to-one mapping between Yubikeys and users. It also
assumes the Token ID and AES secret are in Hex (no spaces). You could support multiple tokens per user or multiple user per token with a custom AuthSelect like:
AuthSelect select secret, active, userId, counter, low,
high,NULL from yubikeys where tokenId=%1 and userId=%0
5.78.3 UpdateQuery

Specifies SQL query that will be used to store Yubikey token data back to the database
after authentication. Special characters are permitted, and %0 is replaced with the new
session counter, %1 with the new session_use counter, %2 with 0 (this column not currently used), %3 with the quoted user name, %4 with the quoted token ID in Base64,
%5 with the current time (seconds in the unix epoch), %6 with the token ID in Hex and
%7 with the token ID in modhex. The default works with the sample Yubikey database
created by db_schema.sql from the YubiKey Validation Server. The default is:
UpdateQuery update yubikeys set accessed=current_timestamp(),
counter=%0, low=%1, high=%2 where userId=%3

246 of 397

Radiator RADIUS Server

Configuration

which assumes that there is a one-to-one mapping between Yubikeys and users. You
could support multiple tokens per user or multiple user per token with a custom UpdateQuery like:
UpdateQuery update yubikeys set accessed=current_timestamp(),
counter=%0, low=%1, high=%2 where tokenId=%4 and userId=%3
5.78.4 Require2Factor

Forces all authentications to require 2 factor authentication. In 2 factor authentication,

the user is required to enter (as their password) both their static password (also called
their PIN) followed by the one-time-password from the Yubikey.
5.78.5 CheckSecretId

If CheckSecretId is set, then check that the secretId fetched from the database matches
the secretId encoded in the submitted Yubikey OTP. This increases the security of the
Yubikey OTP and is recommended best practice.
5.79 <AuthBy YUBIKEYVALIDATIONSERVER>
This module authenticates YubiKey tokens (yubico.com) against the YubiKey Validation Server. To use Radiator with YubiHSM (Hardware Security Module), a validation
server is needed that supports the YubiHSM to store the YubiKey secrets.
The validation server can run on the same or a different server than Radiator allowing
flexibility in deciding where to plug in the YubiHSM. This module does not require any
YubiKey specific modules because all required work is done by the validation server
and possibly YubiHSM.
See the example configuration file goodies/yubikey-validationserver.cfg for two-factor,
single factor and EAP configuration examples.
AuthBy YUBIKEYVALIDATIONSERVER understands the following parameters, as
well as those described in <AuthBy xxxxxx> on page 82
5.79.1 ValidationServerURL

The URL for Yubikey Validation server. Method (OTP or OATH-HOTP) specific part
and password will be appended to the ValidationServerURL. Defaults to
http://127.0.0.1:8003/yhsm/validate?
ValidationServerURL http://10.2.4.6:8003/yhsm/validate?
5.79.2 Timeout

Connection timeout in seconds. Defaults to 3.

5.79.3 SSLVerify

May be used to control how the Yubikey Validation Server's certificate will be verified.
May be one of "none" or "require".

Radiator RADIUS Server

247 of 397

Configuration

5.79.4 SSLCAPath

When verifying the XML Yubikey Validation Servers certificate, set this to the
pathname of the directory containing CA certificates. These certificates must all be in
PEM format. The directory in must contain certificates named using the hash value of
the certificates\' subject names.
5.79.5 SSLCAFile

When verifying the Yubikey Validation Server's certificate, set this to the filename containing the certificate of the CA who signed the server's certificate. The certificate must
all be in PEM format.
5.80 <AuthBy SQLHOTP>
This module supports authentication using HOTP (RFC 4226) authentication. HOTP is
an open specification for event-based one time passwords, developed by OATH (Initiative for Open AuTHentication, http://www.openauthentication.org).
HOTP is an event-based authentication protocol, and is designed for use in time-based 2
factor tokens and other similar authentication processes. It uses the well-known SHA-1
hash function, along with a secret key and an incrementing counter. The specification is
completely open and free and is the result of community collaboration with OATH.
The AuthBy SQLHOTP authentication module detects replay and brute-force attacks. It
supports optional PIN/static password for 2 factor authentication when the user prefixes
their static password before the HOTP one-time-password. It requires Digest::HMAC_SHA1 from CPAN.
The secret key, current counter etc. are stored in a SQL database. Any database supported by Radiator can be used. A sample configuration file and SQL schema for
MySQL are supplied in the goodies directory of your Radiator distribution.
AuthBy SQLHOTP understands the following parameters, as well as those described in
<AuthBy xxxxxx> on page 82.
5.80.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to <AuthBy SQL>. They specify the DBD driver, database and
username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.80.2 AuthSelect

AuthSelect is an SQL query that fetches HOTP data from the SQL database. It is passed
the user name in %0. It is expected to return (secret, active, userId, counter, staticpassword) Field 0 (secret) is the HEX encoded secret key for the token.. It must be present
for the authentication to succeed (Mandatory). Fields 1 and 2 are the counter high and
low parts respectively (Mandatory). All following fields are optional:

248 of 397

Radiator RADIUS Server

Configuration

If field 3 (active) is defined is must be 1 else the authentication is rejected. Field 4 (pin)
is the users static PIN It will be checked if the user specifies a static password or if
Require2Factor is set. Field 5 (digits) is the number of digits in the users HOTP code. If
NULL the value of DefaultDigits will be used. Field 6 (bad_logins) counts the number
of consecutive authentication failures. If defined it will be used to detect brute force
attacks and must be updated by UpdateQuery. Field 7 (last_time_accessed) is the unix
timestamp of the last authentication attempt. It is used to detect brute force attacks
The default works with the sample database schema provided in goodies/hotp.sql. The
default is:
select secret, counter_high, counter_low, active, pin, digits,
bad_logins, unix_timestamp(accessed) from hotpkeys where username=%0
5.80.3 UpdateQuery

UpdateQuery is an SQL query that updates the HOTP data in the SQL database. After a
successful authentication it will be passed the new authentication counter high in %0,
new authentication counter low in %1, bad login count in %2, the username in %3, The
default works with the sample database schema provided in goodies/hotp.sql. The
default is:
update hotpkeys set accessed=now(), counter_high=%0,
counter_low=%1, bad_logins=%2 where username=%3
5.80.4 Require2Factor

If Require2Factor is set, then the user must provide their static password as a prefix to
their HOTP one-time-password. The correct static password is retrieved from 4th field
returned by AuthSelect. If this flag is not set, but the user provides a static password
prefix, then the static password will be checked anyway.
5.80.5 DefaultDigits

DefaultDigits specifies the number of HOTP digits to use if the user record does not
define digits. Defaults to 6.
5.80.6 MaxBadLogins

MaxBadLogins specifies how many consecutive bad PINs or bad HOTP codes will be
tolerated in the last BadLoginWindow seconds. If more than MaxBadLogins bad
authentication attempts (according to field 5 from AuthSelect occurs and if the last one
is within the last BadLoginWindow seconds (according to field 6 from AuthSelect), the
authentication attempt will be rejected. The user must wait at least BadLoginWindow
seconds before attempting to authenticate again. MaxBadLogins defaults to 10.
5.80.7 BadLoginWindow

Period of time in seconds that the user will be locked out after MaxBadLogins have
occurred.
5.80.8 ResyncWindow

ResyncWindow Maximum number of missing authentications that will be tolerated for

counter resynchronisation. Defaults to 20.

Radiator RADIUS Server

249 of 397

Configuration

5.81 <AuthBy SQLTOTP>

This module supports authentication using TOTP (RFC 6238) authentication. TOTP is
an open specification for time-based one time passwords, developed by OATH (Initiative for Open AuTHentication, http://www.openauthentication.org).
TOTP is a time-based authentication protocol, and is designed for use in time-based 2
factor tokens and other similar authentication processes. It uses the well-known SHA-1,
SHA-256 or SHA-512 hash function, along with a secret key and a timestamp. The
specification is completely open and free and is the result of community collaboration
with OATH.
The AuthBy SQLTOTP authentication module detects replay and brute-force attacks. It
supports optional PIN/static password for 2 factor authentication when the user prefixes
their static password before the TOTP one-time-password.
The secret key, PIN etc. are stored in a SQL database. Any database supported by Radiator can be used. A sample configuration file and SQL schema for MySQL are supplied
in the goodies directory of your Radiator distribution.
Hint: Correct operation of time based authentication tokens such as TOTP requires
accurate synchronization of the clocks on the client and Radiator server computers.
AuthBy SQLTOTP understands the following parameters, as well as those described in
<AuthBy xxxxxx> on page 82.
5.81.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to <AuthBy SQL>. They specify the DBD driver, database and
username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.81.2 AuthSelect

AuthSelect is an SQL query that fetches TOTP data from the SQL database. It is passed
the user name in %0. It is expected to return (secret, active, userId, counter, staticpassword).Field 0 (secret) is the HEX encoded secret key for the token. It must be present
for the authentication to succeed (Mandatory). If field 1 (active) is defined is must be 1
else the authentication is rejected. Field 2 (pin) is the users static PIN It will be checked
if the user specifies a static password or if Require2Factor is set. Field 3 (digits) is the
number of digits in the users TOTP code. If NULL the value of DefaultDigits will be
used. Field 4 (bad_logins) counts the number of consecutive authentication failures. If
defined it will be used to detect brute force attacks and must be updated by UpdateQuery. Field 5 (last_time_accessed) is the unix timestamp of the last authentication
attempt. It is used to detect brute force attacks. Field 6 is the last TOTP timestep validated, which should be updated automatically by UpdateQuery.

250 of 397

Radiator RADIUS Server

Configuration

Optional field 7 (algorithm) is the SHA algorithm which defaults to SHA1 if the value is
NULL or empty. Optional field 8 (timestep) is the users time step which defaults to the
TimeStep configuration parameter if the value is 0 or NULL. Optional field 9 (timestep_origin) is the Unix epoch time of the first time step which defaults to TimeStepOrigin configuration parameter if the value is NULL.
The default works with the sample database schema provided in goodies/totp.sql. The
default is:
select secret, active, pin, digits, bad_logins, unix_timestamp(accessed), last_timestep from totpkeys where username=%0
5.81.3 UpdateQuery

UpdateQuery is an SQL query that updates the TOTP data in the SQL database. After a
successful authentication it will be passed the bad login count in %0, the username in
%1. The default works with the sample database schema provided in goodies/totp.sql.
The default is:
update totpkeys set accessed=now(), bad_logins=%0 where username=%1
5.81.4 Require2Factor

If Require2Factor is set, then the user must provide their static password as a prefix to
their HOTP one-time-password. The correct static password is retrieved from 4th field
returned by AuthSelect. If this flag is not set, but the user provides a static password
prefix, then the static password will be checked anyway.
5.81.5 DefaultDigits

DefaultDigits specifies the number of HOTP digits to use if the user record does not
define digits. Defaults to 6.
5.81.6 MaxBadLogins

MaxBadLogins specifies how many consecutive bad PINs or bad HOTP codes will be
tolerated in the last BadLoginWindow seconds. If more than MaxBadLogins bad
authentication attempts (according to field 5 from AuthSelect occurs and if the last one
is within the last BadLoginWindow seconds (according to field 6 from AuthSelect), the
authentication attempt will be rejected. The user must wait at least BadLoginWindow
seconds before attempting to authenticate again. MaxBadLogins defaults to 10.
5.81.7 BadLoginWindow

Period of time in seconds that the user will be locked out after MaxBadLogins have
occurred.
5.81.8 DelayWindow

DelayWindow is the maximum number of timeslots transmission delay that can be permitted between the client and server. Defaults to 1 (the value recommended by the
TOTP specification).
5.81.9 TimeStep

TimeStep is the size of the time step in seconds to use if the user record does not define
time step. Defaults to 30 seconds (the value recommended by the TOTP specification).

Radiator RADIUS Server

251 of 397

Configuration

5.81.10 TimeStepOrigin

TimeStepOrigin the Unix epoch time of the first time step to use if the user record does
not define the origin. Defaults to 0 seconds (Jan 1, 1970) the value recommended by the
TOTP specification).
5.82 <AuthBy SQLAUTHBY>
This clause does an SQL lookup for each incoming request to determine the actual
Radiator AuthBy Clause to use to handle the request. If the resulting Radiator clause has
not previously been used, it will be created using parameters retrieved from SQL and
the request will be given to it for authentication or other handling. If the resulting Radiator clause has been used previously, it will be reused and the request will be sent to it.
Any database supported by Radiator can be used. A sample configuration file is supplied in the goodies directory of your Radiator distribution.
AuthBy SQLAUTHBY understands the following parameters, as well as those
described in <AuthBy xxxxxx> on page 82.
5.82.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to <AuthBy SQL>. They specify the DBD driver, database and
username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.82.2 AuthBySelect

AuthBySelect is the SQL query used to retrieve AuthBy Clause configuration parameters based on the users realm. The clause is cached for reuse. You can use AuthBySelectParam to bind variables to the AuthBySelect query.
Defaults to:
select HOST, PORT, AUTHDN, AUTHPASSWORD, BASEDN,USERNAMEATTR,
PASSWORDATTR, HOLDSERVERCONNECTION from RADSQLAUTHBY where TARGETNAME=%R

which is suitable for an AuthBy LDAP2 clause.

5.82.3 Class

This parameter defines the type of Radiator AuthBy clause to create. The class name is
the type of AuthBy clause to create. For example
Class LDAP2

will cause <AuthBy SQLAYTHBY> to create clauses of type <AuthBy LDAP2>.

Defaults to LDAP2.

252 of 397

Radiator RADIUS Server

Configuration

5.82.4 DefaultParam

DefaultParam sets a default value for any clause parameter, which may be overridden
with a column from the SQL query using ParamColumnDef.
DefaultParam RewriteUsername s/^([^@]+).*/$1/
DefaultParam Version 3
5.82.5 ParamColumnDef

Maps the columns returned by AuthBySelect to parameter names in the target clause. If
non-NULL, each will override the corresponding default value given by DefaultParam.
ParamColumnDef
ParamColumnDef
ParamColumnDef
ParamColumnDef

0,Host
1,Port
2,AuthDN
3,AuthPassword

5.83 <AuthBy HEIMDALDIGEST>

This clause authenticates users against Heimdal Kerberos (http://www.h5l.org), using
the kdigest program part of Heimdal Kerberos.
Works with RADIUS-PAP, EAP-MD5, EAP-MSCHAPV2 (and therefore TTLS-PAP,
TTLS-EAP-MD5, PEAP-EAP-MD5, PEAP-EAP-MSCHAPV2, TTLS-EAPMSCHAPV2)
Other types of authentication cannot be supported by Heimdal for technical reasons.
See AuthBy KRB5 for a module that can work with any Kerberos, but is limited to PAP
and TTLS-PAP.
See goodies/heimdaldigest.cfg for an example configuration file. See goodies/heimdal.txt for guidance and help in setting up a simple Heimdal system for testing.
AuthBy HEIMDALDIGEST understands the following parameters, as well as those
described in <AuthBy xxxxxx> on page 82.
5.83.1 KdigestPath

The path to the executable Heimdal kdigest program. This program will be run externally by AuthBy HEIMDALDIGEST to authenticate each password.
Defaults to /usr/libexec/kdigest
KdigestPath /usr/heimdal/lib/kdigest
5.83.2 KdigestSuffix

String that will be added to the end of each username before authenticating with kdigest.
Defaults to empty string. See also default_realm in krb5.conf, which will be used if
username does not contain a Kerberos realm.
KdigestSuffix @MYCOMPANY.COM

Radiator RADIUS Server

253 of 397

Configuration

5.83.3 KdigestRealm

String specifying the Kerberos realm that will be used to authenticate each user. Used to
specify --kerberos-realm= to kdigest. Defaults to undefined
KdigestRealm OPEN.COM.AU

5.84 <AuthBy SIP2>

This clause authenticates users with 3M Standard Interchange Protocol 2 as used in 3Ms
Automated Circulation Systems (ACS) for book libraries. AuthBy SIP2 supports TCPIP connection to 3M ACS systems, and authenticates against library patron name and
password.
Works with EAP-GTC and PAP and therefore with e.g. EAP-TTLS/PAP. See goodies/
sip2.cfg for an example configuration file.
Note: SIP2 is not related to Session Initiation Protocol (SIP) used for Voice Over IP and
other multimedia applications.
AuthBy SIP2 understands the following parameters, as well as those described in
<AuthBy xxxxxx> on page 82.
5.84.1 Port

Port specifies the TCP port name or number of the ACS server. Defaults to 6001
5.84.2 Host

Host specifies the name or address of the ACS server. Defaults to localhost.
5.84.3 Delimiter

The field delimiter ACS server uses. Defaults to "|".

5.84.4 Timeout

Timeout interval in seconds that Radiator will wait for when trying to contact the SIP2
server. Defaults to 3.
5.84.5 LoginUserID

User ID that Radiator will use to log into the ACS server. If this is defined as an empty
string, then the login phase will not be performed. You need to be sure that this matches
what the SIP2 server expects from clients. Many servers do not require a login phase.
Defaults to scclient.
# LoginUserID is empty to skip the login phase
LoginUserID
5.84.6 LoginPassword

Password that Radiator will use to log into the ACS server. Defaults to clientpwd.
LoginPassword clientpwd
5.84.7 LocationCode

Location code that Radiator will use to log into the ACS server. Defaults to Radiator.

254 of 397

Radiator RADIUS Server

Configuration

5.84.8 TerminalPassword

Terminal Password that Radiator will use to log into the ACS server. Not all installations require this.
TerminalPassword terminal password
5.84.9 SendChecksum

This optional flag tells Radiator to send checksums in every request sent to ACS. This
must agree with the configuration of the ACS and defaults to off.
# This ACS requires sending checksums
SendChecksum
5.84.10 VerifyChecksum

Tells Radiator to verify checksums sent by ACS are present and correct. This must agree
with the configuration of the ACS and defaults to off.
# We want to verify the checksums this ACS sends
VerifyChecksum

5.85 <AuthBy DUO>

This clause authenticates users against two-factor authentication provided by Duo Security Auth API (http://www.duosecurity.com). AuthBy DUO requires Perl modules
HTTP::Async 0.19 or later and Net::HTTPS::NB.
To get started you need to sign up for a Duo account and create a new Auth API integration. Duo Security will then generate your API Hostname, integration key and secret
key which are used to set up Radiator configuration.
See goodies/duo.cfg for an example configuration file and examples of how to combine
the password and password factor (see below) for controlling how two-factor authentication is done. See goodies/duosim.cgi for setting up a partial authentication API simulator for testing.
AuthBy DUO understands the following parameters, as well as those described in
<AuthBy xxxxxx> on page 82.
5.85.1 Hostname, SecretKey and IntegrationKey

API Hostname, secret key and integration key are assigned by Duo. These are mandatory parameters and there are no default values.
Hostname api-aabbcczz.duosecurity.com
SecretKey aaaabbbbccccddddeeeeffffgggghhhhiiiijjjj
IntegrationKey kkkkllllmmmmnnnnoooo
5.85.2 DefaultFactor

If the user does not specify a valid password or factor, this will be the factor requested
from Duo. May be one of "push", "sms", "phone", "auto". Defaults to "auto".
DefaultFactor push

Radiator RADIUS Server

255 of 397

Configuration

5.85.3 Address

Address specifies what details in the incoming request will be used in the 'Address' field
sent to Duo. The contents of the field will show up in the Duo logs. It does not actually
have to be an address (which in any case is not usually available until after authentication is complete), and the default of Calling-Station-Id might be a sensible option.
Address %{Calling-Station-Id}
5.85.4 SSLVerify, SSLCAFile and SSLCAPath

The SSL* parameters allow controlling how the Duo server's certificate is verified. By
default no SSL* parameters are set and the system defaults are used. SSLVerify, SSLCAFile and SSLCAPath behave as described in <AuthBy IMAP> on page 190.
5.85.5 SSLVerifyCNName and SSLVerifyCNScheme

SSLVerifyCNName sets the name which is used when verifying the hostname against
the certificate presented by Duos server. SSLVerifyCNScheme controls how the verification is done, for example, if wildcards are allowed. See the documentation for
IO::Socket::SSL for the details.
The following allow wildcard certificate name *.duosecurity.com to match.
SSLVerifyCNName duosecurity.com
SSLVerifyCNScheme http
5.85.6 SSLCertificateVerifyHook

Further certificate checks can be added with a custom hook. See IO::Socket::SSL SSL_verify_callback for the details. The hook should return 0 or 1 for fail and pass respectively. The hook is called once for each certificate in the certificate chain.
The following arguments are passed to the hook (from IO::Socket::SSL documentation):
$_[0] is a true or false value indicating what OpenSSLs view of the cert
$_[1] is a C-style memory address of the certificate store
$_[2] is a string containing certificates issuer and owner
$_[3] is a string containing any errors encountered or 0 if there were no errors
$_[4] is a C-style memory address of current certificate in the chain.
5.85.7 PollTimerInterval

Number of seconds between checking for replies from the Duo auth API server.
Defaults to 1 second.
5.85.8 Slots

Specifies the maximum number of simultaneous requests outstanding to the Auth API
server, and the maximum number of HTTP connections to the server. If more than this
number of requests are waiting, then subsequent requests will be queued and sent after a
reply a received from an outstanding request. Defaults to 20.

256 of 397

Radiator RADIUS Server

Configuration

5.85.9 Timeout

Specifies the maximum number of seconds to wait for the start of a reply from the Auth
API server. The Auth API server can take up to 60 seconds to reply. Default is 100 seconds. You should not need to change this.
5.85.10 MaxRequestTime

Specifies the maximum number of seconds to wait for a complete reply from the Auth
API server. The Auth API server can take up to 60 seconds to reply. Default is 120 seconds. You should not need to change this.
5.85.11 ProxyHost

Specifies the name of a HTTP proxy to use to contact the Auth API server. The default
is not to use any proxy.
5.85.12 ProxyPort

Specifies the port on the ProxyHost to use to contact the Auth API server.
5.85.13 EndpointPrefix

The prefix for the Auth API. Defaults to /auth/v2. You should not need to change this.
See goodies/duo.cfg for how to set EndpointPrefix when using the Auth API simulator
duosim.cgi
5.85.14 Protocol

The protocol to use to connect to the Auth API server. Defaults to https. You should not
need to change this.
5.86 <AuthBy DIAMETER>
AuthBy DIAMETER converts and forwards all RADIUS authentication and accounting
messages to another (possibly remote) DIAMETER server. The DIAMETER replies are
converted back to RADIUS messages and returned to the requesting client which might
be a remote client or this Radiator instance itself.
The default for AuthBy DIAMETER is to advertise values 0 and 1 (Diameter common
message and NASREQ) with Auth-Application-Id. Value 3 (Diameter base accounting)
is advertised with Acct-Application-Id.
See goodies/diameter-authby.cfg for an example configuration file.
AuthBy DIAMETER understands the following parameters, as well as those described
in <AuthBy xxxxxx> on page 82.
5.86.1 Peer

Name or IP address of DIAMETER peer this AuthBy DIAMETER should connect to.
Note: Currently only one Peer is supported.

Radiator RADIUS Server

257 of 397

Configuration

5.86.2 Port

This optional parameter specifies port name or number of the Diameter peer. Defaults to
3868, the official IANA port number for Diameter. May be a numeric port number or
symbolic port/service name.
5.86.3 DestinationHost

If DestinationHost is unset, no Destination-Host attribute will be added to Diameter

messages. Setting DestinationHost is optional and there is no default value.
5.86.4 DestinationRealm

This optional parameter sets the Destination-Realm attribute in the Diameter messages
sent to the peer. If DestinationRealm is unset, the realm is deduced from RADIUS UserName or left empty if there is no realm part in the RADIUS User-Name attribute.
5.86.5 OriginHost

This parameter specifies the name that AuthBy DIAMETER will use to identify itself to
Diameter peer it connects to. It is sets the value of the Origin-Realm attribute in the
Diameter messages sent to the peer. OriginHost is not optional an must be specified in
the AuthBy DIAMETER clause. Diameter peers may use OriginHost to determine
whether they have connected to the correct peer, so it may be critical that it be configured correctly.
5.86.6 OriginRealm

This parameter specifies the name of the user Realm that AuthBy DIAMETER is willing to handle. It is sets the value of the Origin-Realm attribute in the Diameter messages
sent to the peer. OriginRealm is not optional an must be specified in the AuthBy DIAMETER clause.
5.86.7 PostDiaToRadiusConversionHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostDiaToRadiusConversionHook is called after an incoming Diameter request has been converted to its equivalent RADIUS request, allowing you to alter
or add to attribute conversions etc. It is passed references to the incoming Diameter
request and the converted RADIUS request.
5.86.8 PostRadiusToDiaConversionHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostRadiusToDiaConversionHook is called after an RADIUS reply
has been converted to its equivalent Diameter reply, prior to being sent back to the
Diameter client. It is passed references to the RADIUS reply and the converted Diameter reply.
5.86.9 Protocol

This optional parameter specifies which Stream protocol will be used to carry Diameter.
Options are tcp for TCP/IP or sctp for SCTP (Stream Control Transmission Protocol). Defaults to tcp. Not all hosts are able to support sctp: consult your vendor. The
protocol setting must be the same as that being used by the Diameter server.
Protocol sctp

258 of 397

Radiator RADIUS Server

Configuration

5.86.10 AuthApplicationIds

This optional parameter allows you to define the Auth Application Ids announced in
CER. Defaults to 0, 1, 5 (i.e. DIAMETER BASE, NASREQ and Diameter-EAP).
AuthApplicationIds 0, 1
5.86.11 AcctApplicationIds

This optional parameter allows you to define the Acct Application Ids announced in
CER. Defaults to 3 (i.e. BASE_ACCOUNTING).
AcctApplicationIds 3
5.86.12 SupportedVendorIds

This optional parameter allows you to define the Supported Vendor Ids announced in
CER. There is no default and no Supported-Vendor-Id is announced by default. Keyword "DictVendors" is an alias group for all vendors in the default dictionary and the
dictionary file configured with DiameterDictionaryFile.
# Tell the peer we support all the vendors in our
# default and DiameterDictionaryFile dictionaries
SupportedVendorIds DictVendors
5.86.13 UseTLS TLS_CAFile TLS_CAPath
TLS_CertificateFile TLS_CertificateChainFile TLS_CertificateType
TLS_PrivateKeyFile TLS_PrivateKeyPassword TLS_CRLCheck TLS_CRLFile
TLS_SessionResumption TLS_SessionResumptionLimit
TLS_ExpectedPeerName TLS_SubjectAltNameURI TLS_CertificateFingerprint
TLS_RequireClientCert

These parameters control the establishment of TLS encryption and mutual authentication on the Diameter connection. They have the same meaning as described in
<AuthBy RADSEC> on page 219.
5.86.14 LocalAddress and LocalPort

You can control the address and optionally the port number to use for the client source
port, although this is not usually necessary. LocalPort can be a port number or name. If
not specified, a port number will be allocated in the usual way.
LocalAddress 203.63.154.29
LocalPort 12345
5.86.15 ReconnectTimeout

This optional parameter specifies the number of seconds to wait before attempting to
reconnect a failed, dropped or disconnected Diameter connection. It also specifies the
timeout for the initial connect.
5.87 <AuthBy RATELIMIT>
AuthBy RATELIMIT allows to limit the maximum number of requests per second that
will be served. When the rate is exceeded, the requests will be ignored by default.

Radiator RADIUS Server

259 of 397

Configuration

5.87.1 MaxRate

Number of requests per second that will be accepted. Defaults to 0 which means no
limit.
5.87.2 MaxRateResult

Result to use when MaxRate is exceeded. Possible values are ACCEPT, REJECT,
IGNORE and CHALLENGE. Defaults to IGNORE.
5.88 <AuthLog xxxxxx>
This marks the beginning of an AuthLog clause, which defines how to log authentication failures and successes. The xxxxxx is the name of a specific AuthLog module. See
the following sections for how to configure specific AuthLog clauses. AuthLog clauses
may be defined at the top level or within a Realm or Handler clause.
You can have more than one AuthLog clause for a Realm or Handler. This will make the
Realm (or Handler) log to each AuthLog method in turn.
All AuthLog clauses understand the following parameters:
5.88.1 Identifier

Specifies an optional symbolic name that can be used to refer to the logger from somewhere else:
<AuthLog FILE>
Identifier logger1
...
</AuthLog>
<Handler>
AuthLog logger1
...
</Handler>
5.88.2 LogSuccess

Indicates whether authentication successes are to be logged. Default is not to log success.
# Change success logging to be on
LogSuccess 1
5.88.3 LogFailure

Indicates whether authentication failures are to be logged. Default is to log failures.

# Change failure logging to be off
LogFailure 0

5.89 <AuthLog FILE>

This clause logs authentication successes and failures to a flat file. You can define as
many <AuthLog FILE> clauses as you wish at the top level or within Realm or Handler
clauses. Each clause can specify different logging conditions and a different log file.

260 of 397

Radiator RADIUS Server

Configuration

# this auth logger logs both success and failure to a file

<AuthLog FILE>
Identifier myauthlogger
Filename %L/authlog
LogSuccess 1
LogFailure 1
</AuthLog>
<Realm DEFAULT>
<AuthBy FILE>
Filename %D/users
</AuthBy>
# Log authentication success and failure to the a file
AuthLog myauthlogger
</Realm>

As well as the generic parameters described in Section 5.73 on page 237, AuthLog
FILE understands the following parameters:
5.89.1 Filename

This optional parameter specifies the name of the file where authentication log messages are to be written. You can use any of the special characters defined in Section 5.2
on page 20. Defaults to %L/password.log. Special character %0 is replaced by the
result of the authentication and %1 by the reason string.
If the Filename parameter starts with a vertical bar character (|) then the rest of the
filename is assumed to be a program to which the output is to be piped. Otherwise the
output will be appended to the named file:
# Pipe to my-log-prog
Filename |/usr/local/bin/my-log-prog
5.89.2 SuccessFormat

This optional parameter specifies the format that is to be used to log authentication successes in Filename when LogFormatHook is not defined. You can use any of the special
characters defined in Section 5.2 on page 20. Also %0 is replaced by the message severity level, and %1 by the reason string (usually an empty string for success). Defaults to
%l:%U:%P:OK
Caution: The default SuccessFormat will log the plaintext password entered by the user.
Some organizations may prefer that user passwords not be logged. In that case, a SuccessFormat that does not include the %P (decoded password) special character may be
preferable.
5.89.3 FailureFormat

This optional parameter specifies the format that is to be used to log authentication failures in Filename when LogFormatHook is not defined. You can use any of the special
characters defined in Section 5.2 on page 20. Also %0 is replaced by the message severity level, and %1 by the reason string Defaults to %l:%U:%P:FAIL

Radiator RADIUS Server

261 of 397

Configuration

5.89.4 LogFormatHook

Specifies an optional Perl hook that will run for each log message when defined. The
hook must return the formatted log message. By default no hook is defined and SuccessFormat and FailureFormat are used for formatting. The hook parameters are the message severity level, the reason string and the reference to the current request.
5.90 <AuthLog SQL>
The clause indicates to log authentication successes and failures to an SQL database.
You can define as many <AuthLog SQL> clauses as you wish at the top level or within
Realm or Handler clauses. Each clause can specify different logging conditions and a
different log database.
As well as the generic parameters described in Section 5.73 on page 237, AuthLog SQL
understands the following parameters:
5.90.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the database to use for logging. They need
to be set in a similar way to as for <AuthBy SQL>. They specify the DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername yoursqlusername
DBAuth
yoursqlpassword
5.90.2 Table

This optional parameter specifies the name of the SQL table where the logging messages are to be inserted. Defaults to RADAUTHLOG.
5.90.3 SuccessQuery

This optional parameter specifies the SQL query that will be used to log authentication
successes if LogSuccess is enabled (LogSuccess is not enabled by default). There is no
default. If SuccessQuery is not defined (which is the default), no logging of authentication successes will occur. In the query, special formatting characters are permitted, %0
is replaced with the message severity level. %1 is replaced with the quoted reason message (which is usually empty for successes). %2 is replaced with the SQL quoted UserName. %3 is replaced with the SQL quoted decoded plaintext password (if any). %4 is
replaced with the SQL quoted original user name from the incoming request (before any
RewriteUsername rules were applied)
5.90.4 SuccessQueryParam

This optional parameter specifies a bind variable to be used with SuccessQuery. See
SQL Bind Variables on page 25 for information about how to use bind variables.
5.90.5 FailureQuery

This optional parameter specifies the SQL query that will be used to log authentication
failures if LogFailure is enabled (LogFailure is enabled by default). There is no default.
If FailureQuery is not defined (which is the default), no logging of authentication failures will occur. In the query, special formatting characters are permitted, %0 is replaced
with the message severity level. %1 is replaced with the quoted reason message. %2 is
262 of 397

Radiator RADIUS Server

Configuration

replaced with the SQL quoted User-Name. %3 is replaced with the SQL quoted decoded
plaintext password (if any). %4 is replaced with the SQL quoted original user name
from the incoming request (before any RewriteUsername rules were applied).
5.90.6 FailureQueryParam

This optional parameter specifies a bind variable to be used with FailureQuery. See
SQL Bind Variables on page 25 for information about how to use bind variables.
5.90.7 ConnectionHook, ConnectionAttemptFailedHook and NoConnectionsHook

These hooks are called during SQL connection establishment and possible connection
failures. They have the same meaning as described in <AuthBy SQL> on page 111.
5.91 <AuthLog SYSLOG>
This clause indicates to log authentication successes and failures to the syslog logging
facility. You can define as many <AuthLog SYSLOG> clauses as you wish at the top
level or within Realm or Handler clauses. Each clause can specify different logging conditions and a different log database. This module was contributed by Carlos Canau ([email protected]).
As well as the generic parameters described in Section 5.73 on page 237, AuthLog
SYSLOG understands the following parameters:
5.91.1 Facility

The name of the syslog facility that will be logged to. The default is user.
# Log to the syslog facility called radius
Facility radius
5.91.2 Priority

The syslog priority level that will be used for each log message. Default is info
5.91.3 SuccessFormat

The format for success messages. You can use any of the special characters defined in
Section 5.2 on page 20. Defaults to %l:%U:%P:OK.
5.91.4 FailureFormat

The format for failure messages. You can use any of the special characters defined in
Section 5.2 on page 20. Defaults to %l:%U:%P:FAIL. The reason message is automatically appended.
5.91.5 LogSock

This optional parameter specifies what type of socket to use to connect to the syslog
server. Allowable values are native, eventlog, unix, inet, tcp, udp, stream, pipe, console.
The option inet means to try tcp first, then udp. The default is to use the Sys::Syslog
default of native, tcp, udp, unix, pipe, stream, console.
Caution: due to limitations in the Sys::Syslog perl module, if you have multiple AuthLog SYSLOG or Log SYSLOG clauses and if any one has LogSock defined, they must
all have LogSock defined.

Radiator RADIUS Server

263 of 397

Configuration

5.91.6 LogHost

When LogSock is set to tcp or udp or inet, this optional parameter specifies the name or
address of the syslog host. Defaults to the local host. Special characters are supported.
See Section 5.15.6 on page 63 for more advice about setting LogHost.
# Log to a remote host via syslog over udp:
LogSock udp
LogHost your.syslog.host.com
5.91.7 LogOpt

This optional parameter allows control over the syslog options passed to Sys::Syslog::openlog. LogOpt is a comma separated list of words from the set:

cons
ndelay
nofatal
nowait
perror
pid

as described in the Perl Sys::Syslog documentation.

Defaults to pid. Special characters are supported.
LogOpt pid,perror
5.91.8 LogIdent

This optional parameter specifies an alternative ident name to be used for logging.
Defaults to the executable name used to run radiusd. Special characters are supported.
5.92 <AddressAllocator SQL>
AddressAllocator SQL works in conjunction with <AuthBy DYNADDRESS> (See
Section 5.45 on page 173) to allocate IP addresses from an SQL database. The default
behaviour is to allocate the oldest unused address from the RADPOOL table. During
deallocation, the address is marked is unused. Addresses that remain in use for more
than DefaultLeasePeriod seconds are automatically reclaimed (this protects against lost
Accounting Stop requests).
Starting from Radiator 4.14, you can define UpdateQuery to refresh address TIME_STAMP and EXPIRY when accounting Alive requests are received. This keeps the
addresses from being automatically reclaimed while they are periodically updated by
Alive requests.
The table definition of a sample RADPOOL table for a range of SQL databases can be
found in the goodies/*.sql files in the Radiator distribution.

264 of 397

Radiator RADIUS Server

Configuration

AddressAllocator SQL uses the PoolHint to determine which pool to use. It uses the
pool hint in the SQL select statement that is used to find an available address. It does an
exact match on the POOL column of the RADPOOL table.
When an address is allocated for a user, it is leased to the user for a fixed period. It is
available exclusively for that user until either they terminate their session (i.e. an
Accounting Stop is received) or until the lease expires. The purpose of this is to protect
against lost Accounting Stops such as might occur with poor network connectivity, or
a crashed NAS. However it also means that you should set the lease period to be longer
than the longest legitimate session time, otherwise users may find their addresses being
reallocated to another user.
Since Radiator 4.14 you can use shorter lease period if accounting Alive messages are
used and UpdateQuery is configured.
The default lease period is 1 day, and you can control this with DefaultLeasePeriod.
Every LeaseReclaimInterval seconds, expired leases are reclaimed and made available
for allocation again.
AddressAllocator SQL makes the following allocation variables available for replies.
These names can be used in MapAttribute in AuthBy DYNADDRESS.

yiaddr, the allocated IP address from the YIADDR column of the RADPOOL table.
subnetmask, the subnet mask from the SUBNETMASK column of the RADPOOL
table.

dnsserver, the DNS server address from the DNSSERVER column of the RADPOOL table.
AddressAllocator SQL can also optionally populate the RADPOOL table at startup, by
defining <AddressPool xxxx> clauses inside the <AddressAllocator SQL> clause.
AddressAllocator SQL understands the following parameters:
5.92.1 Identifier

This mandatory parameter specifies an symbolic name for this AddressAllocator clause.
It must exactly match the Allocator parameter in an AuthBy DYNADDRESS in order
for it to be used to allocate addresses.
Identifier mySQLallocator
5.92.2 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database. They need to be set in a
similar way to as for <AuthBy SQL>. They specify the DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword

Radiator RADIUS Server

265 of 397

Configuration

5.92.3 DefaultLeasePeriod

This optional parameter defines how long the default lease period is in seconds.
Defaults to 86400 seconds (24 hours).
# We have long sessions, set the lease to be 2 days
DefaultLeasePeriod 172800
5.92.4 LeaseReclaimInterval

This optional parameter defines how often expired leases are looked for. Every LeaseReclaimInterval seconds, AddressAllocator SQL will check the RADPOOL table for
expired leases, using the ReclaimQuery. Any that are found will be marked as available
again. Defaults to 86400 seconds (24 hours).
# Look for expired leases every hour
LeaseReclaimInterval 3600
5.92.5 FindQuery

This optional parameter allows you to define a custom SQL query to find an available
address. Defaults to
select TIME_STAMP, YIADDR, SUBNETMASK, DNSSERVER from RADPOOL
where POOL=%0 and STATE=0 order by TIME_STAMP

%0 is replaced by the pool hint. %1 is replaced by the username. %2 is replaced with the
lease expiry time.
Hint: You can get a substantial speedup during address allocation with mysql by adding
limit 1 to the end of the FindQuery.
5.92.6 FindQueryBindVar

This optional parameter specifies a bind variable to be used with FindQuery. See
Section 5.4 on page 25 for information about how to use bind variables.
5.92.7 AllocateQuery

This optional parameter allows you to define a custom SQL query to allocate an address
that was found with FindQuery. Defaults to
update RADPOOL set STATE=1,TIME_STAMP=%0,
EXPIRY=%1, USERNAME=%2 where YIADDR=%3 and STATE=0 and TIME_STAMP %4

%0 is replaced by the current time in Unix epoch seconds, %1 by the lease expiry time
(the current time + the lease period), %2 by the user name, %3 by the address, %4 by a
timestamp comparison operator. If the AllocateQuery is an empty string, the query will
not be executed. This may be useful if the FindQuery does all the allocation work.
5.92.8 AllocateQueryBindVar

This optional parameter specifies a bind variable to be used with AllocateQuery. See
Section 5.4 on page 25 for information about how to use bind variables.

266 of 397

Radiator RADIUS Server

Configuration

5.92.9 UpdateQuery

This optional parameter allows you to define a custom SQL query to update the address
when accounting Alive requests are received. There is no default.
UpdateQuery update
YIADDR=?
UpdateQueryBindVar
UpdateQueryBindVar
UpdateQueryBindVar

RADPOOL set TIME_STAMP=?, EXPIRY=? where

%t
%0
%1

%0 is replaced by the lease expiry time (the current time + the lease period) and %1 by
the address. If the UpdateQuery is an empty string, the query will not be executed.
5.92.10 UpdateQueryBindVar

This optional parameter specifies a bind variable to be used with UpdateQuery. See
Section 5.4 on page 25 for information about how to use bind variables.
5.92.11 CheckPoolQuery

This optional parameter allows you to define a custom SQL query to check whether an
address exists in the pool. Defaults to
select STATE from RADPOOL where YIADDR=%0

%0 is replaced by the address.

If CheckPoolQuery is set to an empty string, no pool checking will be done at startup.
5.92.12 CheckPoolQueryBindVar

This optional parameter specifies a bind variable to be used with CheckPoolQuery. See
Section 5.4 on page 25 for information about how to use bind variables.
5.92.13 AddAddressQuery

This optional parameter allows you to define a custom SQL query to add an address to
the pool if it is not found by CheckPoolQuery. Defaults to
insert into RADPOOL (STATE, TIME_STAMP,
POOL, YIADDR, SUBNETMASK, DNSSERVER) values (0, %t, %0, %1,
%2, %3)

%t is replaced by the current time in Unix epoch seconds, %0 by the pool name, %1 by
the address, %2 by the subnet mask, and %3 by the DNS server address.
If AddAddressQuery is set to an empty string, addresses will not be automatically added
to the pool.
5.92.14 AddAddressQueryBindVar

This optional parameter specifies a bind variable to be used with AddAddressQuery.

See Section 5.4 on page 25 for information about how to use bind variables.

Radiator RADIUS Server

267 of 397

Configuration

5.92.15 DeallocateQuery

This optional parameter allows you to define a custom SQL query to deallocate a previously allocated address. If the DeallocateQuery is an empty string, no deallocation
query will be executed. Defaults to
update RADPOOL set STATE=0,TIME_STAMP=%t where YIADDR=%0

%0 is replaced the address.

5.92.16 DeallocateQueryBindVar

This optional parameter specifies a bind variable to be used with DeallocateQuery. See
Section 5.4 on page 25 for information about how to use bind variables.
5.92.17 ReclaimQuery

This optional parameter allows you to define a custom SQL query to reclaim an address
whose lease has expired. If the ReclaimQuery is an empty string, no reclaim query will
be executed. Defaults to
update RADPOOL set STATE=0 where STATE!=0 and EXPIRY < %0

%0 is replaced by the current time in Unix epoch seconds.

5.92.18 ReclaimQueryBindVar

This optional parameter specifies a bind variable to be used with ReclaimQuery. See
Section 5.4 on page 25 for information about how to use bind variables.
5.92.19 AddressPool

The AddressPool clause allows you to define what address pools are to be made available. When Radiator is started, each AddressPool will ensure there is an entry for each of
its addresses in the RADPOOL table.
AddressPool is a simple alternative to maintaining the contents of the RADPOOL table
through some other method. You may wish to use another method for initializing and
maintaining the RADPOOL table, in which case it is not necessary to have any AddressPool clauses at all.
An AddressPool can define a range of available addresses. Each address in the range has
the same Subnet mask, and DNS Server address. The Subnetmask and the DNS server
address specify the values to use if an address allocated from an address range. The
default for Subnetmask is 255.255.255.255. There is no default for DNSServer.
Address ranges can be specified either as lower and upper addresses (inclusive) within a
class C block, or as a CIDR block.
The step size between consecutive addresses can be controlled with the Step parameter,
which defaults to 1. A Step of other than 1 can be useful where you need to allocate subnets of more than one address, rather than individual host addresses.
The following example defines two pools of addresses. The first pool is called pool1.
It contains addresses in the ranges 192.1.1.1 to 192.1.1.50 (inclusive) and 192.1.1.60 to
192.1.1.120 (inclusive) and the entire 192.1.2.0 class C block. The IP Subnet mask for
268 of 397

Radiator RADIUS Server

Configuration

each address is 255.255.255.255. The second pool is called pool2 and contains
addresses in the range 192.2.2.62 to 192.2.2.99 (inclusive).
<AddressAllocator SQL>
.....
# Defines the addresses that we are prepared
# to allocate:
<AddressPool pool1>
Subnetmask
255.255.255.0
DNSServer 10.1.1.1
Range 192.1.1.1 192.1.1.50
Range 192.1.1.60 192.1.1.120
Range 192.1.2.0/24
</AddressPool>
<AddressPool pool2>
Subnetmask
255.255.255.127
Range 192.2.2.62 192.2.2.99
</AddressPool>
</AddressAllocator>

5.93 <AddressAllocator DHCP>

AddressAllocator DHCP works in conjunction with <AuthBy DYNADDRESS>
(Section 5.45 on page 173) and a DHCP server to dynamically allocate IP addresses.
AddressAllocator DHCP has been tested with a number of DHCP servers, however it
works best with the latest versions of the DHCP server from the Internet Software Consortium (www.isc.org) that support the Subnet Selection Option.
The Subnet Selection Option has recently been adopted by the IETF as a standard part
of the RFC for DHCP, and it allows server-to-server operation such as that supported by
Radiator.
Note: the PoolHint supplied in the AuthBy DYNADDRESS clause must be a subnet
definition that is understood by the DHCP server for the purposes of address allocation.
AddressAllocator DHCP makes the following allocation variables available for replies.
These names can be used in MapAttribute in AuthBy DYNADDRESS.

yiaddr, the allocated IP address from DHCP

subnetmask, the subnet mask from DHCP
dnsserver, the DNS server address from DHCP
An example AddressAllocator DHCP configuration file can be found in the distribution
in the file goodies/addressallocatordhcp.cfg.
Caution: because AddressAllocator DHCP binds to the DHCP server address, it is not
possible to run the DHCP server on the same host as Radiator.
Because the DHCP address allocator binds to port 67, Radiator must be run as root, or at
least with root privileges.

Radiator RADIUS Server

269 of 397

Configuration

AddressAllocator DHCP understands the following parameters:

5.93.1 Identifier

This mandatory parameter specifies a symbolic name for this AddressAllocator clause.
It must exactly match the Allocator parameter in an AuthBy DYNADDRESS in order
for it to be used to allocate addresses.
Identifier

DHCPallocator

5.93.2 Host

The host name or IP address of the DHCP server. The address may be either a single
host address or a broadcast address. If a broadcast address is specified, Radiator will
allocate an address from the first DHCP host to answer a discover request.
Host 1.2.3.4
5.93.3 Port

The DHCP port number on the DHCP host. Defaults to port 67.
Port 67
5.93.4 LocalAddress

The local IP address to bind to. Defaults to the main IP address of the Radiator host.
LocalAddress 1.1.1.1
5.93.5 DHCPClientIdentifier

The Client Identifier to be used by the DHCP server to track allocations. Defaults to the
username in the current request.
DHCPClientIdentifier %{User-Name}
5.93.6 DefaultLease

Specifies the default lease period requested. Defaults to one day (86400 seconds).
DefaultLease 86400
5.93.7 TimeoutMinimum

The DHCP RFC specifies timeout and retry behavior while attempting to contact a
DHCP server. The TimeoutMinimum specifies the initial timeout in seconds. Defaults
to 2 seconds.
TimeoutMinimum 4
5.93.8 TimeoutMaximum

The TimeoutMaximum specifies how long to keep retrying a request in seconds.

Defaults to 16 seconds.
TimeoutMaximum 64
5.93.9 TimeoutFactor

The TimeoutFactor indicates how to recalculate the timeout for each attempt. Defaults
to multiplying the timeout by 2 for each attempt.
TimeoutFactor 2

270 of 397

Radiator RADIUS Server

Configuration

5.93.10 ServerPort

Specifies the local DHCP server port. Defaults to port 67.

ServerPort 67
5.93.11 Synchronous

Normally DHCP requests are processed asynchronously. This optional parameter can be
used to make the requests synchronous.
Synchronous
5.93.12 SubnetSelectionOption

This optional parameter can be used to enable the Subnet Selection Option as described
above. Note that the official RFC option is 118, which is what this option defaults to if
no value is specified. Early versions of the ISC DHCP server used option 211.
If the SubnetSelectionOption parameter is not present, any PoolHint value provided will
be used in the giaddr field in the DHCP request, instead of LocalAddress.
SubnetSelectionOption 211
5.93.13 UserClass

This optional parameter can be used to specify a User Class to be passed to the DHCP
server to assist with address allocation. Any text and/or Radiator special characters are
permitted. Refer to the DHCP server documentation for further details regarding the use
of classes.
UserClass %{Client:Identifier}
5.93.14 ClientHardwareAddress

ClientHardwareAddress is an attribute in the incoming address which contains the hex

encoded MAC address of the client. If present, it will be used as CHADDR in the
DHCP request. If not present, and fake CHADDR based on the request XID will be
used. The DHCP server may use this when allocating an address for the client. The
MAC address can contain extraneous characters such as . or : as long as it contains
the 12 hex characters (case insensitive) of the MAC address. Special characters are permitted
# Use contents of an attribute to tell the DHCP server the
# hardware address of the client
ClientHardwareAddress %{Unisphere-Dhcp-Mac-Addr}
5.93.15 UseClassForAllocationInfo

When this optional parameter is set, information about the allocation is stored in reply
attribute Class instead of in memory. Required for server farm where different farm
members are likely to handle the allocation and deallocation. Defaults to off.
5.94 <Resolver>
The Resolver clause provides DNS and name resolution services for the AuthBy DNSROAM clause (see Section 5.68 on page 230). It is only required and should only be
used if you have an AuthBy DNSROAM clause in your configuration.

Radiator RADIUS Server

271 of 397

Configuration

AuthBy DNSROAM uses the resolver clause to do NAPTR, SRV, A and AAAA lookups on a DNS Name Server in order to discover the name, address and possibly other
attributes (such as protocol and whether to use TLS encryption) of a server that will be
used to handle requests for a certain Realm.
The default behavior of Resolver is to consult DNS using the standard resolver configuration for your host (e.g. on Unix/Linux, it find the resolver details by consulting /etc/
resolv.conf, $HOME/.resolv.conf or ./.resolv.conf). However, you can override these
defaults and specify the DNS nameserver to use, the search path etc. by using parameters in the Resolver clause.
Resolver requires the Net::DNS Perl module which in turn requires the Socket6 module
(and the IO::Socket::INET6 module if you wish to consult a DNS server via IPv6).
These are all available as source from CPAN, or as binary PPM packages for ActivePerl
on Windows.
Resolver uses the following algorithm to discover server names and addresses for a
given Realm:
1. Look for NAPTR records for the Realm.
2. For each NAPTR found record, examine the Service field and use that to determine

the transport, protocol and TLS requirements for the server. The Service field starts
with AAA for insecure and AAAS for TLS secured. The Service field contains
+RADSECS for RadSec over SCTP, +RADSECT for RadSec over TCP or
+RADIUS for RADIUS protocol over UDP. The most common Service field you
will see will be AAAS+RADSECT for TLS secured RadSec over TCP.
3. If the NAPTR has the S flag, look for SRV records for the name. For each SRV

record found, note the Port number and then look for A and AAAA records corresponding to the name in the SRV record.
4. If the NAPTR has the A flag, look for a A and AAAA records for the name.
5. If no NAPTR records are found and DirectAddressLookup is enabled, look for A

and AAAA records based directly on the realm name. For example, if the realm is
examplerealm.edu, it looks for records such as _radsec._tcp.examplerealm.edu,
_radsec._sctp.examplerealm.edu and _radius._udp.examplerealm.edu.
6. All A and AAAA records found are ordered according to their Order and Preference

fields. The most preferable server address is used as the target server address, along
with any other server attributes discovered from DNS. If no SRV records was found
for the address, the DNSROAM configured Port is used.
For example, if the User-Name was [email protected] (i.e. the Realm is example.com), and DNS contained the following records:
example.com.IN NAPTR 50 50 "s" "AAAS+RADSECT" "" _radsec._tcp.example.com.
_radsec._tcp.example.com. IN SRV 0 10 2083 radsec.example.com.
radsec.example.com. IN AAAA 2001::202:44ff:fe0a:f704

Then the target selected would be a RadSec server on port 2083 at IPv6 address
2001::202:44ff:fe0a:f704. The connection would be made over TCP/IP, and TLS
encryption would be used. This complete specification of the realm is the most flexible
272 of 397

Radiator RADIUS Server

Configuration

and is recommended. However, other, more concise DNS configurations are possible, as
described below:
If the DNS contained these records:
example.com. IN NAPTR 50 50 "a" "AAAS+RADSECS" "" radsec.example.com.
radsec.example.com. IN AAAA 2001::202:44ff:fe0a:f704

Then the target selected would be a RadSec server at IPv6 address

2001::202:44ff:fe0a:f704. The connection would be made over SCTP, and TLS encryption would be used. The port used would be the default Port configured into AuthBy
DNSROAM.
If the DNS contained just this record:
_radius._udp.example.com.

IN A 203.63.154.10

Then the target selected would be a RADIUS server at IPv4 address 203.63.154.10. The
connection would be made over UDP. The Port and Secret used would be the defaults
configured into AuthBy DNSROAM.
Hint: the simplest Resolver clause you can have is:
<Resolver>
</Resolver>

which gets all its configuration from /etc/resolv.conf or the equivalent on your platform.
Resolver understands the following parameters:
5.94.1 Nameservers

This optional parameter specifies the name or address of one or more DNS Name Servers passed to Net::DNS. Nameservers with IPv6 addresses are supported if Socket6 is
installed. Defaults to the value of nameserver in resolv.conf (see above). Note: current
Net::DNS implementations appear not to use multiple nameservers with the bgsend
method Radiator uses. Only the first server is used for the query.
# Look first on one server and then another if it times out:
Nameservers 203.63.154.100
Nameservers 203.63.154.101
5.94.2 Debug

This optional flag enables debugging within the Net::DNS module. It will print to stdout
the details of all DNS requests sent and replies received. Defaults to no debugging.
# Enable debug logging in Net::DNS:
Debug
5.94.3 Recurse

This optional flag enables recursive DNS lookups. Defaults to no recurse.

Radiator RADIUS Server

273 of 397

Configuration

5.94.4 TCPTimeout

This optional flag specifies the timeout (in seconds) for DNS lookups over TCP connections. Defaults to 5 seconds.
5.94.5 UDPTimeout

This optional flag specifies the timeout (in seconds) for DNS lookups over UDP connections. Defaults to 5 seconds.
5.94.6 TCPPersistent

This optional flag tells Net::DNS to keep a TCP socket open for each host:port to which
it connects. This is useful if youre using TCP and need to make a lot of queries to the
same nameserver. Defaults to true.
5.94.7 UDPPersistent

This optional flag tells Net::DNS to keep a single UDP socket open for all DNS queries.
This is useful if youre using UDP and need to make a lot of queries to the same nameserver. Defaults to true.
5.94.8 GetIPV4

This optional flag specifies whether Resolver will attempt to find an IPv4 (A) address
for any names it discovers. Defaults to true.
5.94.9 GetIPV6

This optional flag specifies whether Resolver will attempt to find an IPv6 (AAAA)
address for any names it discovers. Defaults to true.
5.94.10 GetRadius

This optional parameter specifies whether Resolver is required to attempt to discover

RADIUS servers from

NAPTR records of type AAA with +RADIUS or

IPv4 (A) or IPv6 (AAAA) records for _radius._udp.realmname
Defaults to true.
5.94.11 GetRadSec

This optional parameter specifies whether Resolver is required to attempt to discover

RADSEC servers from

NAPTR records of type AAA or AAAS with +RADSECS or +RADSECT or

IPv4 (A) or IPv6 (AAAA) records for _radsec._sctp.realmname
IPv4 (A) or IPv6 (AAAA) records for _radsec._tcp.realmname
Defaults to true.
5.94.12 DirectAddressLookup

If DirectAddressLookup is enabled, and if there are no NAPTR records for the

requested Realm, Resolver will attempt lookups of A and AAAA records for _rad-

274 of 397

Radiator RADIUS Server

Configuration

sec._sctp.<REALM>, _radsec._tcp.<REALM> and _radius._udp.<REALM> Enabled

by default.
5.94.13 NAPTR-Pattern

NAPTR-Pattern is an optional parameter that specifies a regexp that will be used to

match the contents of NAPTR records during Resolver service discovery.
If NAPTR-Pattern is defined and matches a NAPTR DNS record, it will be used to
determine the protocol and transport to be used. The regexp is expected to match 2 substrings. The first is the protocol and can be 'radsec' or 'radius'. The second is the transport to use, and can be 'tls', 'tcp' or 'udp'.
5.94.14 NegativeCacheTtl

This optional value specifies how long a negative lookup (ie failure to resolve the
realm) will be cached until another lookup will be made. Defaults to 21600 seconds (6
hours).
5.94.15 FailureBackoffTime

If the lookup failed to discover any results and there was a timeout when waiting for the
nameserver, this optional value specifies how long Radiator will wait before another
lookup will be made. This will give the target server time to become available without
resorting to potentially long NegativeCacheTtl. Defaults to 3 seconds.
5.95 <ServerDIAMETER>
This clause tells Radiator to act as a Diameter to RADIUS gateway.
Diameter is an AAA protocol described in RFC 6733 (and others). It provides for TCPIP or SCTP transport and TLS encryption. It makes specific provision for carrying
RADIUS compatible requests and defines Diameter to RADIUS gateways. ServerDIAMETER implements such a Diameter to RADIUS gateway.
Incoming Diameter requests are converted as far as possible into RADIUS requests and
then dispatched internally within Radiator. A Realm or Handler can be configured to
handle the request either locally or proxy it (as a RADIUS request) to another RADIUS
server. RADIUS replies are sent back to the originating Diameter peer. Handlers may
use the Client-Identifier to match requests received by a particular ServerDIAMETER
clause.
By default ServerDIAMETER listens for connections from Diameter peers on TCP port
3868. By default it does not require TLS encryption of the Diameter connection. ServerDIAMETER never contacts a Diameter peer by itself: it always acts only as a Diameter
server.
By default, ServerDIAMETER uses a hardwired internal dictionary to translate Diameter requests into readable parameters. You can use the global configuration parameter
DiameterDictionaryFile to alter the hardwired internal dictionary.
<ServerDIAMETER> understands the following parameters:

Radiator RADIUS Server

275 of 397

Configuration

5.95.1 Port

This optional parameter specifies which network port ServerDIAMETER will listen on
for connections from Diameter peers. Defaults to 3868, the official IANA port number
for Diameter. May be a numeric port number or symbolic port/service name.
5.95.2 BindAddress

This optional parameter specifies one or more network interface addresses to listen for
incoming Diameter connections on. It is only useful if you are running Radiator on a
multi-homed host (i.e. a host that has more than one network address). Defaults to the
global BindAddress, which defaults to 0.0.0.0 (i.e. listens on all networks connected to
the host). See Global parameters on page 28.
Using this parameter, you can run multiple instances of Radiator on the one computer,
where each Radiator listens to Diameter connections directed to a different host address.
BindAddress can include special formatting characters, and multiple comma separated
IPv4 and IPv6 addresses.
# Only listen on one IPv4 address and the IPv6 loopback
BindAddress 203.63.154.1, ::1
5.95.3 MaxBufferSize

This optional advanced parameter specifies the maximum number of octets that will be
output buffered. Defaults to 10000. 0 means no output buffering. This advanced parameter should not need adjusting.
5.95.4 Protocol

This optional parameter specifies which Stream protocol will be used to carry Diameter.
Options are tcp for TCP/IP or sctp for SCTP (Stream Control Transmission Protocol). Defaults to tcp. Not all hosts are able to support sctp: consult your vendor. The
protocol setting must be the same as that being used by connecting Diameter peers.
Protocol sctp

Hint: On modern Linux hosts, SCTP support is in a loadable module, and can be
enabled with:
modprobe sctp
5.95.5 ReadTimeout

This optional parameter specifies the maximum time to wait for incoming Diameter
connections to complete their initial handshaking. Defaults to 10 seconds. If a Diameter
CER message is not received from the peer by ServerDIAMETER within this time
period, the connection will be shut down.
5.95.6 OriginHost

This parameter specifies the name that ServerDIAMETER will use to identify itself to
any connecting Diameter peers. It is sent to the peer in the Diameter CER message. It is
not optional an must be specified in the ServerDIAMETER clause. Diameter peers may
use OriginHost to determine whether they have connected to the correct peer, so it may
be critical that it be configured correctly.

276 of 397

Radiator RADIUS Server

Configuration

5.95.7 OriginRealm

This parameter specifies the name of the user Realm that ServerDIAMETER is willing
to handle. It is sent to connecting Diameter peers in the CER message, and the peer will
use it to determine which requests are to be routed to this ServerDIAMETER. It is not
optional an must be specified in the ServerDIAMETER clause.
5.95.8 ProductName

This optional parameter is used to identify the product name of this Diameter peer. It is
sent to connecting Diameter peers in the CER message. It defaults to Radiator.
5.95.9 AddToRequest

This optional parameter is used to add extra RADIUS attributes to the RADIUS request
generated from each incoming Diameter request. It can be used to tag requests arriving
from ServerDIAMETER for special handling within Radiator or in remote RADIUS
servers.
AddToRequest NAS-Identifier=DIAMETER
5.95.10 DefaultRealm

This optional parameter can be used to specify a default realm to use for received Diameter requests that have a username that does not include a realm. If the incoming user
name does not have a realm (i.e. there is no @something following the user name) and
if DefaultRealm is specified, the User-Name in the resulting RADIUS request will have
@defaultrealm appended to it. The realm can then be used to trigger a specific <Realm>
or <Handler> clause. This is useful if you operate a number of Diameter peers for different customer groups and where some or all of your customers log in without specifying
a realm.
# Realmless logins to this NAS will be treated
# as if they are for realm open.com.au
<ServerDIAMETER>
OriginHost ....
DefaultRealm open.com.au
</ServerDIAMETER>
<Realm open.com.au>
.....
</Realm>
5.95.11 PreHandlerHook

This optional parameter operates in the same way as PreHandlerHook in the Client
clause. See PreHandlerHook on page 47.
5.95.12 SupportedVendorIds

This optional parameter allows you to define the Supported Vendor Ids announced in
CER. There is no default and no Supported-Vendor-Id is announced by default. Keyword "DictVendors" is an alias group for all vendors in the default dictionary and the
dictionary file configured with DiameterDictionaryFile.
# Tell the peer we support all the vendors in our
# default and DiameterDictionaryFile dictionaries
SupportedVendorIds DictVendors

Radiator RADIUS Server

277 of 397

Configuration

5.95.13 UseTLS TLS_CAFile TLS_CAPath

TLS_CertificateFile TLS_CertificateChainFile TLS_CertificateType
TLS_PrivateKeyFile TLS_PrivateKeyPassword TLS_RandomFile TLS_DHFile
TLS_CRLCheck TLS_CRLFile TLS_SessionResumption
TLS_SessionResumptionLimit TLS_ExpectedPeerName TLS_SubjectAltNameURI
TLS_CertificateFingerprint TLS_RequireClientCert

These parameters control the establishment of TLS encryption and mutual authentication on the Diameter connection. They have the same meaning as described in
<ServerRADSEC> on page 287.
5.95.14 AuthApplicationIds

This optional parameter allows you to define the Auth Application Ids announced in
CER. Defaults to 0, 1, 5 (i.e. DIAMETER BASE, NASREQ and Diameter-EAP).
AuthApplicationIds 0, 1
5.95.15 AcctApplicationIds

This optional parameter allows you to define the Acct Application Ids announced in
CER. Defaults to 3 (i.e. BASE_ACCOUNTING).
AcctApplicationIds 3
5.95.16 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5. This is useful for logging packets that pass through this clause in more detail
than other clauses during testing or debugging. The packet tracing will stay in effect
until it passes through another clause with PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace
5.95.17 PostDiaToRadiusConversionHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostDiaToRadiusConversionHook is called after an incoming Diameter request has been converted to its equivalent RADIUS request, allowing you to alter
or add to attribute conversions etc. It is passed references to the incoming Diameter
request and the converted RADIUS request.
5.95.18 PostRadiusToDiaConversionHook

This optional parameter allows you to define a Perl function that will be called during
packet processing. PostRadiusToDiaConversionHook is called after an RADIUS reply
has been converted to its equivalent Diameter reply, prior to being sent back to the
Diameter client. It is passed references to the RADIUS reply and the converted Diameter reply.
5.96 <ServerTACACSPLUS>
This clause tells Radiator to act as a Tacacs+ server (as well as a RADIUS server).
Tacacs+ is an older Authentication, Authorization and Accounting (AAA) protocol
developed by Cisco, and supported by some Cisco devices. It uses TCP connections
between the client (usually some kind of router) and the Tacacs+ server. Newer Cisco
278 of 397

Radiator RADIUS Server

Configuration

devices generally support both RADIUS and Tacacs+, or perhaps just RADIUS. While
some older Cisco devices only support Tacacs+. In addition, there are some Cisco security facilities that are only available through Tacacs+.
The <ServerTACACSPLUS> clause handles Tacacs+ Authentication, Authorization
and Accounting requests in the following way:

Incoming TACACS+ requests are decrypted using the TACACSPLUSKey or Secret

from a matching Client clause. The search first look for an exact IP address match. If
this is not found, look for a CIDR address match. If this is not found look for a
DEFAULT Client clause. The key used to decrypt the request will be the Client
TACACSPLUSKey. If that is not defined, the Server TACACSPLUS Key will be
used. If that is not defined, the Client Secret will be used.
Technical Note: Radiator 4.13 and earlier looked for DEFAULT Client clause before
CIDR match.

TACACS+ authentication requests are converted into RADIUS Access-Request

requests. Tacacs+ ASCII, PAP, CHAP and MSCHAP are supported, and the resulting passwords are converted into the appropriate RADIUS attributes. The action,
priv_lvl, authen_type and service values in the TACACS+ authentication request are
converted to OSC-TACACS-Action, OSC-TACACS-Privilege-Level, OSCTACACS-Authen-Type and OSC-TACACS-Service RADIUS attributes. The
RADIUS Access-Request is dispatched to a matching <Realm> or <Handler>
clause, which can service the request locally using any of the Radiator AuthBy
clauses, or perhaps proxy it to another RADIUS server.

TACACS+ authorization requests are approved subject to any AuthorizeGroupAttr

reply items from the previous RADIUS Access-Accept and AuthorizeGroup parameters from the configuration file. In addition, any cisco-avpair reply items from the
previous RADIUS Access-Accept are used as authorization attribute-value pairs.
TACACS+ authorization requests can optionally be converted to RADIUS AccessRequests as described below.

TACACS+ accounting requests are converted into RADIUS Accounting-Requests.

The converted RADIUS requests are dispatched to a matching Realm or Handler
clause, using the same rules as RADIUS requests.
Hint: By default Radiator requires that the user has previously authenticated with this
Radiator instance before accepting any TACACS+ authorization requests. The authentication reply provides the authorization information Radiator needs to handle the subsequent TACACS+ authorization requests. If the optional parameter
AllowAuthorizeOnly on page 285 is enabled, Radiator will request authorization
information even if the user has not previously authenticated with this Radiator
instance.
Hint: If <ServerTACACSPLUS> is used to authenticate administrator access to a Cisco
device, you may need to add specific authorization attributes to allow administrative
access. For example, to get administrative access to a Cisco Aironet wireless Access
Point requires that the authorization include a Tacacs+ attribute-value pair like:
aironet:admin-capability=ident+admin

Radiator RADIUS Server

279 of 397

Configuration

You can achieve this by having a suitable cisco-avpair reply item for the relevant user in
your Radiator database:
ciscouser User-Password=fred
cisco-avpair="aironet:admin-capability=ident+admin"

or by having an AuthorizationAdd parameter in your <ServerTACACSPLUS> clause:

AuthorizationAdd aironet:admin-capability=ident+admin

This example enables only some levels of administrative access (ident and admin). See
your Cisco device documentation for more details.
Hint: Devices from other vendors than Cisco, such as Juniper, may also accept ciscoavpair attributes.
<ServerTACACSPLUS> can be used with any Radiator authentication method that
understands plaintext passwords (such as FILE, SQL, LDAP, DBFILE, etc.), and also
with any method that might Challenge the user for additional authentication data (such
as DIGIPASS, ACE, OPIE, OTP, INTERNAL etc.).
Hint: You can use the Tacacs+ test client goodies/tacacsplustest in your distribution to
send test Tacacs+ requests.
During request processing, Server TACACSPLUS looks for a Client clause that
matches the origin of the TACACS+ request, as described above. If found, a number of
parameters from the Client clause are used during processing:

TACACSPLUSKey
Secret
RewriteUsername
StripFromRequest
AddToRequest
AddToRequestIfNotExist
PreHandlerHook
DefaultRealm (overrides DefaultRealm in ServerTACACSPLUS)

<ServerTACACSPLUS> understands the following parameters:

5.96.1 Key

This parameter specifies the default shared secret to be used to decrypt Tacacs+ messages. When a new connection from a Tacacs+ client is received, Server TACACSPLUS
tries to find a Key to use for decrypting that connection. It looks in the following places
for a Key until it finds one that has been defined:

The TACACSPLUSKey parameter of a matching Client clause

This Key parameter.
The Secret parameter of a matching Client clause.

280 of 397

Radiator RADIUS Server

Configuration

The search for the matching Client clause is done in the following order (Caution: this is
slightly different to the order for RADIUS clients):

Exact IP address match

DEFAULT clause
CIDR Address match.
Hint: this search order means you can use the Secret parameter in Clients loaded by
<ClientListSQL> to specify per-client Tacacs+ keys, provided you do not specify Key
in the <Server TACACSPLUS> clause.
Hint: If all your Tacacs+ devices use the same key, you should probably use this Key
parameter. If some or all of your Tacacs+ devices use different keys, you should define a
Client and TACACSPLUSKey for each differing one, and set this Key as the default for
the rest. If some Tacacs+ clients are also RADIUS clients, you should define a Client
clause for each one, specifying the RADIUS secret in Secret, and the Tacacs+ key in
TACACSPLUSKey.
Key mysecret
5.96.2 Port

This optional parameter specifies which TCP port the server will listen on for incoming
Tacacs+ connections. Defaults to 49 (which generally requires root or other privileged
access) Any valid port number or service name can be used.
Port 1024
5.96.3 BindAddress

This optional parameter specifies one or more network interface addresses to listen for
incoming Tacacs+ connections on. It is only useful if you are running Radiator on a
multi-homed host (i.e. a host that has more than one network address). Defaults to the
global BindAddress, which defaults to 0.0.0.0 (i.e. listens on all networks connected to
the host). See Global parameters on page 28.
Using this parameter, you can run multiple instances of Radiator on the one computer,
where each Radiator listens to Tacacs+ connections directed to a different host address.
BindAddress can include special formatting characters, and multiple comma separated
IPv4 and IPv6 addresses.
# Only listen on one IPv4 address and the IPv6 loopback
BindAddress 203.63.154.1, ::1
5.96.4 AuthorizationReplace

This optional parameter specifies Tacacs+ authorization attribute-value pairs that are to
replace those suggested by the Tacacs+ client. It effectively overrides the default
authorization that the client would use.
You can have as many AuthorizationReplace parameters as you wish, one for each
Tacacs+ authorization attribute-value pair:

Radiator RADIUS Server

281 of 397

Configuration

AuthorizationReplace service=aironet
AuthorizationReplace protocol=shell
AuthorizationReplace aironet:admin-capability=ident+admin
5.96.5 AuthorizationAdd

This optional parameter specifies Tacacs+ authorization attribute-value pairs that are to
be added to those suggested by the Tacacs+ client. It effectively increases the default
authorization that the client would use.
You can have as many AuthorizationAdd parameters as you wish, one for each Tacacs+
authorization attribute-value pair:
AuthorizationAdd aironet:admin-capability=ident+admin
5.96.6 AddToRequest

This optional parameter adds any number of RADIUS attributes to the RADIUS
requests generated by ServerTACACSPLUS. It can be used to tag requests arriving
from Tacacs+ for special handling within Radiator or in remote RADIUS servers.
AddToRequest NAS-Identifier=TACACS
5.96.7 AuthorizationTimeout

This optional parameter changes the timeout period for handling a complete TACACS+
conversation, including the authentication any subsequent authorization requests.
Defaults to 600 seconds. If the timeout expires, further authorizations for an earlier
authentication will not be valid, and will be rejected.
5.96.8 DefaultRealm

This optional parameter can be used to specify a default realm to use for received
TACACS requests that have a username that does not include a realm. If the incoming
user name does not have a realm (i.e. there is no @something following the user name)
and if DefaultRealm is specified, the User-Name in the resulting RADIUS request will
have @defaultrealm appended to it. The realm can then be used to trigger a specific
<Realm> or <Handler> clause. This is useful if you operate a number of TACACS clients for different customer groups and where some or all of your customers log in without specifying a realm.
Hint: You can override this on a per-client basis by setting DefaultRealm in the Client
clause.
# Realmless logins to this NAS will be treated
# as if they are for realm open.com.au
<ServerTACACSPLUS>
Key ....
DefaultRealm open.com.au
</ServerTACACSPLUS>
<Realm open.com.au>
.....
</Realm>

282 of 397

Radiator RADIUS Server

Configuration

5.96.9 GroupMemberAttr

When AuthorizeGroup is use to specify TACACS+ user privileges, GroupMemberAttr

specifies the name of the RADIUS reply attribute in the Access-Accept that is expected
to contain the name of the TACACS+ users privilege group. This group name will then
be used by AuthorizeGroup to determine which privileges can be extended to that user.
If there is no such attribute in the Access-Accept, the TACACS+ group name for the
user will be assumed to be DEFAULT. If GroupMemberAttr is not defined in the configuration file, then all TACACS+ users will be assumed to have a TACACS+ group
name of DEFAULT.
The RADIUS attribute named by GroupMemberAttr may be a real RADIUS attribute
received from a remote RADIUS server (in the case where the remote RADIUS server
provides the authentication of TACACS+ requests). Or it could be pseudo RADIUS
attribute added to the reply by an AuthBy internal to the current Radiator server.
# Name of the pseudo attribute containing the TACACS group name
# in RADIUS Access-Accepts:
GroupMemberAttr tacacsgroup
5.96.10 AuthorizeGroup

Some TACACS+ clients can request per-command authorization of commands from the
TACACS+ server. When this occurs, one or more AuthorizeGroup parameters can be
used to specify privilege levels, permitted TACACS commands and TACACS restrictions for various TACACS+ privilege groups. If no AuthorizeGroup parameters are
specified in the Radiator configuration file then all TACACS+ commands will be
authorized by <Server TACSCPLUS>.
Hint: You should have a thorough and complete understanding of TACACS+ command
authorization and how to configure your TACACS+ client for command authorization
before attempting to configure privilege control with AuthorizeGroup.
The general format of the AuthorizeGroup parameter is (all on one line):
AuthorizeGroup <groupname> <permit|permitreplace|deny> pattern1 pattern2 ... {attr1=val attr2=val ...}

Each AuthorizeGroup parameter specifies a privilege rule for a TACACS+ privilege

group. You can specify zero or more AuthorizeGroup parameters for each privilege
group in use in your organization. The AuthorizeGroup parameters will be considered
for a group in the order in which they are given in the Radiator configuration file.
When a tacacs authorization request is received, the list of AuthorizeGroup rules is
searched for rules matching the group name identified by the GroupMemberAttr attribute (See Section 5.96.9, GroupMemberAttr, on page 283). Each rule is examined in
order until a matching rule is found. The patterns are used to do the matching. Each pattern is a perl Regular Expression (regexp). Pattern1 is matched against the first
TACACS+ request argument (usually service=xyz), pattern2 is matched against the
second TACACS+ request argument etc. If every pattern matches its TACACS+ argument, then the rule matches.
If the first matching rule is a deny, the authorization will be denied.

Radiator RADIUS Server

283 of 397

Configuration

If the first matching rule is permit, the request is authorized, and the list of reply
attr=val entries are sent back to the TACACS+ client to be added to the users command arguments.
If the first matching rule is permitreplace, the request is authorized, and the list of
reply attr=val entries are sent back to the TACACS+ client and are used to replace the
users requested command arguments.
Hint: Some Cisco devices have authorization for optional roles with the * character.
This is not a wildcard character, but indicates the following is optional. For example, the
following rule automatically selects the right role(s) depending on the shell:contextname in the authorization request. Only the set of roles corresponding to the requested
contextname will be returned.
AuthorizeGroup group1 permit service=shell\
{shell:contextname1*"role1 role2 role3"\
shell:contextname2*role2}

Hint: AuthorizeGroup replaces the old CommandAuth parameter. Support for CommandAuth will be removed some time in the future.
In order to provide per-user privilege control for TACACS+ users, you need to follow
these steps:
1. Divide your TACACS+ users into groups where all the members in the group have

the same privileges.

2. Assign a unique name to each group.
3. Choose a RADIUS Reply attribute that will contain the group name for each user.

Set this attribute name in GroupMemberAttr.

4. Arrange for each user to have their specific group name (from step 1) in their

RADIUS Reply attribute selected in the previous step.

5. Add one or more AuthorizeGroup parameters specifying the privileges for all of the

possible group names from step 1 above.

6. Configure your TACACS+ client to perform per-command authorization with its

TACACS+ server.
7. Test that your TACACS+ client enforces the correct privileges specified in step 5 for

each user group.

Examples.
In these examples, there are two different Tacacs groups. Group1 is only permitted to do
show commands but group2 is allowed to do anything. Group1 is allowed to start a
PPP IP session, which will get an inacl of 101 and an outacl of 102.
AuthorizeGroup
AuthorizeGroup
outacl=102}
AuthorizeGroup
AuthorizeGroup

284 of 397

group1 permit service=shell cmd=show cmd-arg=.*

group1 permit service=ppp protocol=ip {inacl=101
group1 deny .*
group2 permit .*

Radiator RADIUS Server

Configuration

As an alternative to controlling individual command authorization, you can set a privilege level for the user when they start their exec session. Thereafter, the router will limit
which command the user can use, depending on the priv-lvl. 0 is the lowest, and permits
disable, enable, exit, help, and logout. priv-lvl=1 is the non-privileged user. priv-lvl=15
is the highest privilege level, the level after going into enable mode. Here users in group
3 get a priv-lvl of 15. The start of a session sends the args service=shell cmd*
AuthorizeGroup group3 permit service=shell cmd\* {priv-lvl=15}
5.96.11 AuthorizeGroupAttr

If this parameter is specified, it specifies the name of an attribute in Access-Accept that

will contain per-command authorization patterns for authorizing TACACS+ commands
for this user. Multiple attributes are supported with each attribute containing one pattern. The format is the same as the AuthorizeGroup parameter above excluding the
group name. These patterns are processed before any configured-in AuthorizeGroup
parameters.
5.96.12 AllowAuthorizeOnly

When enabled, allows Radiator to create a RADIUS Access-Request with Service-Type

attribute set to Authorize-Only when TACACS+ authorization request is received but
Radiator has no previous information about the user's authorization. This may happen if
the TACACS+ client does not use TACACS+ for authentication, has authenticated
against another TACACS+ server, Radiator has been reloaded or AuthorizationTimeout
has expired. Defaults to disabled.
5.96.13 GroupCacheFile

CAUTION: this option is deprecated and no longer does anything. AllowAuthorizeOnly

replaces GroupCacheFile.
5.96.14 UsernamePrompt

This optional parameter sets the prompt that ServerTACSPLUS will use to prompt the
client for a user name when the Tacacs authen-type of ASCII is used. Defaults to Username: .
5.96.15 PasswordPrompt

This optional parameter sets the prompt that ServerTACSPLUS will use to prompt the
client for a password when the Tacacs authen-type of ASCII is used. Defaults to Password: .
5.96.16 IdleTimeout

If a TACACS+ client stays connected for more than this number of seconds without
sending any requests it will be disconnected. Defaults to 180 seconds. A Value of 0
means no idle timeout will apply, and clients can stay connected forever.
5.96.17 AuthenticationStartHook

If this hook is defined it is expected to handle the START of a TacacsPlus authentication. If it is not defined, the authentication START will be handled internally by Server
TACACSPLUS as described above.
The hook is passed the following arguments:

Radiator RADIUS Server

285 of 397

Configuration

Pointer to the temporary RADIUS request that has been constructed to represent the
TACACSPLUS authentication request.

The action attribute from the incoming TACACSPLUS request. This describes the
authentication action to be performed. One of $Radius::Tacacsplus::TAC_PLUS_AUTHEN_*

The authen_type attribute from the incoming TACACSPLUS request. The type of
authentication that is being performed. One of $Radius::Tacacsplus::TAC_PLUS_AUTHEN_TYPE_*

The priv_lvl attribute from the incoming TACACSPLUS request. This indicates the
privilege level that the user is authenticating as. One of $Radius::Tacacsplus::TAC_PLUS_PRIV_LVL_*.

The service attribute from the incoming TACACSPLUS request. This is the service
requesting the authentication. One of
$Radius::Tacacsplus::TAC_PLUS_AUTHEN_SVC_*
5.96.18 AuthenticationContinueHook

If this hook is defined it is expected to handle the CONTINUE of a TacacsPlus authentication. If it is not defined, the authentication CONTINUE will be handled internally by
Server TACACSPLUS as described above.
The hook is passed the following arguments:

The body of the request a received in the incoming TACACSPLUS CONTINUE

request. Contains the undecoded flags and fields from the request.
5.96.19 SingleSession

This optional parameter tells the server to try to maintain a single TCP connection for
all TACACS+ requests from the same client if the client permits. If this flag is set and if
the TACACS+ client indicates a willingness to support single connections with the
TAC_PLUS_SINGLE_CONNECT_FLAG, the TCP connection will not be closed by
Radiator after each TACACS+ session. Defaults to 1.
Single sessions can be disabled regardless of client options by setting the SingleSession
flag to 0.
Note: Default behavior changed in 4.8. In versions of Radiator prior to 4.8, the default
behavior was to always try to keep the session open.
5.96.20 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5. This is useful for logging packets that pass through this clause in more detail
than other clauses during testing or debugging. The packet tracing will stay in effect
until it passes through another clause with PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace

286 of 397

Radiator RADIUS Server

Configuration

5.96.21 AuthenticationStartHook

Specifies a Perl hook to run when a TACACS+ Authentication Start is received. It can
be used for special processing of TACACS+ Start requests. If the hook returns an empty
list, normal processing of the request will continue else no further processing will be
done and the hook is expected to handle the request.
It is passed the following arguments:

Pointer to the current Server TACACSPLUS clause.

Pointer the Radius::Radius packet being constructed.
The action from the incoming TACACS+ request.
The authen_type from the incoming TACACS+ request.
The priv_lvl from the incoming TACACS+ request.
The service from the incoming TACACS+ request.

5.96.22 AuthenticationContinueHook

Specifies a Perl hook to run when a TACACS+ Authentication Continue is received. It

can be used for special processing of TACACS+ Continue requests. If the hook returns
an empty list, normal processing of the request will continue else no further processing
will be done and the hook is expected to handle the request.
It is passed the following arguments:

Pointer to the current Server TACACSPLUS clause.

The body from the incoming TACACS+ request.
5.97 <ServerRADSEC>
This clause accepts RadSec (RFC 6614) connections from AuthBy RADSEC clauses in
other Radiators and processes RADIUS requests sent over the RadSec connection in a
similar way to how a Client clause received conventional UDP RADIUS requests. RadSec can be used to provide secure reliable proxying of RADIUS requests from one
Radiator to another, even over insecure networks. See http://www.open.com.au/radiator/
radsec-whitepaper.pdf for more information about RadSec.
Both <ServerRADSEC> and any <AuthBy RADSEC> clauses that connect to it must
have the same Secret configured, otherwise they will not be able to exchange RADIUS
requests correctly, irrespective of whether any TLS or other configuration parameters
are correct.
All valid RADIUS requests received by <ServerRADSEC> are dispatched to the first
matching <Realm> or <Handler> clause, in the same was as the <Client> clause. The
reply to any incoming request will be automatically delivered back to the original
requesting AuthBy RADSEC client.
When UseTLS is enabled, <AuthBy RADSEC> clients always expect to receive a TLS
server certificate from <ServerRADSEC>. This means that if you enable UseTLS, you
must configure a server certificate, otherwise <AuthBy RADSEC> will not be able to
establish a TLS encrypted connection to <ServerRADSEC>.
Radiator RADIUS Server

287 of 397

Configuration

Hint: Operators can use a third party free or commercial Certificate Authority to generate private certificates for RadSec clients and servers.
Hint: for compliance with RFC 6614, ServerRADSEC defaults to a Secret of radsec,
Transport of tcp, UseTLS enabled, and TLS_RequireClientCert enabled
When a RadSec Client presents a certificate to the RadSec Server, the RadSec server
performs a number of checks to validate the client certificate. The client certificate is
checked for valid start and end dates, and also checks the chain of validity back to the
issuing Certificate Authority, using the root certificates specified in TLS_CAFile or
TLS_CAPath. Also a client certificate will only be accepted if at least one of the following conditions are true:

The IP address of the client exactly matches a subjectAltName with type IPADD (IP
Address) in the certificate. Or,

The Subject in the certificate matches the pattern specified by the TLS_ExpectedPeerName parameter in this ServerRADSEC clause.
and

If TLS_SubjectAltNameURI parameter is defined in the ServerRADSEC clause, the

certificate must contain a subjectAltName of type URI that matches the TLS_SubjectAltNameURI regular expression.

If TLS_CertificateFingerprint parameter is defined in the AuthBy RADSEC clause,

the certificates fingerprint must match at least one of the TLS_CertificateFingerprint options.
Note that the default TLS_ExpectedPeerName pattern is .+, which matches any Subject. This means than in the default configuration, ServerRADSEC will accept any client whose client certificate can be validated against a root certificate specified by
TLS_CAFile or TLS_CAPath.
These certificate validation rules are consistent with RFC 2595.
<ServerRADSEC> understands the following parameters:
5.97.1 Port

This optional parameter specifies which network port ServerRADSEC will listen on for
connections from RadSec clients. Defaults to 2083, the official IANA port number for
RadSec. May be a numeric port number or symbolic port/service name.
5.97.2 BindAddress

This optional parameter specifies one or more network interface addresses to listen for
incoming RadSec connections on. It is only useful if you are running Radiator on a
multi-homed host (i.e. a host that has more than one network address). Defaults to the
global BindAddress, which defaults to 0.0.0.0 (i.e. listens on all networks connected to
the host). See Global parameters on page 28.
Using this parameter, you can run multiple instances of Radiator on the one computer,
where each Radiator listens to RadSec connections directed to a different host address.
288 of 397

Radiator RADIUS Server

Configuration

BindAddress can include special formatting characters, and multiple comma separated
IPv4 and IPv6 addresses.
# Only listen on one IPv4 address and the IPv6 loopback
BindAddress 203.63.154.1, ::1
5.97.3 MaxBufferSize

This optional advanced parameter specifies the maximum number of octets that will be
output buffered. Defaults to 10000. 0 means no output buffering. This advanced parameter should not need adjusting.
5.97.4 Secret

This parameter specifies the shared secret that will be used between this ServerRADSEC and the AuthBy RADSEC clients that will connect to it. The shared secret is used
in the same was as Secret parameter in the Client clause: to encrypt passwords and generate message authenticators. The shared secret must be configured identically into
ServerRADSEC and all the AuthBy RADSEC clients that will connect to it (regardless
of whether TLS is enabled). Failure to do this will result in authentication errors. For
compliance with RFC 6614, Secret defaults to radsec.
5.97.5 StripFromRequest

This optional parameter strips the named RADIUS attributes from the RADIUS
requests received by ServerRADSEC before passing them to any authentication modules. The value is a comma separated list of attribute names. StripFromRequest removes
attributes from the request before AddToRequest adds any to the request. There is no
default.
# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port
5.97.6 AddToRequest

This optional parameter adds any number of RADIUS attributes to the RADIUS
requests received by ServerRADSEC. It can be used to tag requests arriving from RadSec for special handling within Radiator or in remote RADIUS servers.
AddToRequest NAS-Identifier=RADSEC
5.97.7 DefaultRealm

This optional parameter can be used to specify a default realm to use for received RadSec requests that have a username that does not include a realm. If the incoming user
name does not have a realm (i.e. there is no @something following the user name) and
if DefaultRealm is specified, the User-Name in the resulting RADIUS request will have
@defaultrealm appended to it. The realm can then be used to trigger a specific <Realm>
or <Handler> clause. This is useful if you operate a number of RadSec clients for different customer groups and where some or all of your customers log in without specifying
a realm.
# Realmless logins to this NAS will be treated
# as if they are for realm open.com.au
<ServerRADSEC>
Secret ....
.....

Radiator RADIUS Server

289 of 397

Configuration

DefaultRealm open.com.au
</Client>
<Realm open.com.au>
.....
</Realm>
5.97.8 Protocol

This optional parameter specifies which Stream protocol will be used to carry RadSec.
Options are tcp for TCP/IP or sctp for SCTP (Stream Control Transmission Protocol). Defaults to tcp. Not all hosts are able to support sctp: consult your vendor. The
protocol setting must be the same in each RadSec server and client.
Protocol sctp

Hint: On modern Linux hosts, SCTP support is in a loadable module, and can be
enabled with:
modprobe sctp
5.97.9 PreHandlerHook

This optional parameter operates in the same way as PreHandlerHook in the Client
clause. See PreHandlerHook on page 47.
5.97.10 UseTLS

This optional parameter forces the use of TLS for authentication and encryption of the
RadSec connection. Requires Net::SSLeay Perl module from CPAN. When this parameter is enabled, the following TLS_* parameters become available for use. For compliance with RFC 6614, defaults to enabled.
It is strongly recommended that TLS be enabled for proxying across any insecure network such as the internet.
UseTLS
5.97.11 TLS_CAFile

When UseTLS is enabled, this parameter specifies the name of a file containing Certificate Authority (CA) root certificates that may be required to validate TLS client certificates. The certificates are expected to be in PEM format. The file can contain several
root certificates for one or more Certificate Authorities. Radiator will look for root certificates for RadSec connections in TLS_CAFile then in TLS_CAPath, so there usually
is no need to set both.
5.97.12 TLS_CAPath

When UseTLS is enabled, this parameter specifies the name of a directory containing
CA root certificates that may be required to validate TLS client certificates. The certificates are expected to one per file in PEM format. The files names are looked up by the
CA Subject Name hash value. Radiator will look for root certificates for RadSec connections in TLS_CAFile then in TLS_CAPath, so there usually is no need to set both.
5.97.13 TLS_CertificateFile

When UseTLS is enabled, this parameter specifies the name of a file containing the
server certificate to be used for this RadSec server. The server certificate will be sent to
290 of 397

Radiator RADIUS Server

Configuration

the RadSec client and validated by the client during TLS setup. The certificate file may
be in PEM or ASN1 format (depending on the setting of the TLS_CertificateType
parameter). The certificate file can also contain the servers TLS private key if the
TLS_PrivateKeyFile parameter specifies the same file. RadSec clients expect the server
certificate to have a common name (CN) the same as the RadSec servers DNS host
name or address.
5.97.14 TLS_CertificateChainFile

When UseTLS is enabled, this parameter specifies the name of a file containing a server
certificate chain. The server certificate chain will be sent to the RadSec client and validated by the client during TLS setup. The certificate chain must be in PEM format. This
should be used alternatively and/or additionally to TLS_CertificateFile for explicitly
constructing the server certificate chain which is sent to the client in addition to the
server certificate.
5.97.15 TLS_CertificateType

When UseTLS is enabled, this optional parameter specifies the format of the TLS_CertificateFile. Permitted options are:

PEM
ASN1
The default is ASN1.
5.97.16 TLS_PrivateKeyFile

When UseTLS is enabled, this optional parameter specifies the name of the file containing the servers private key. It is sometimes in the same file as the server certificate
(TLS_CertificateFile). If the private key is encrypted (which is usually the case) then
TLS_PrivateKeyPassword is the key to decrypt it.
5.97.17 TLS_PrivateKeyPassword

When UseTLS is enabled, this optional parameter specifies the password that is to be
used to decrypt the TLS_PrivateKeyFile. Special characters are permitted.
5.97.18 TLS_RandomFile

When UseTLS is enabled, this optional parameter specifies the name of a file containing
randomness. You should not normally need to set this parameter.
5.97.19 TLS_DHFile

When UseTLS is enabled, this optional parameter specifies the name of the DH group.
You should not normally need to set this parameter, but it may be required if you are
using ephemeral DH keys.
5.97.20 TLS_CRLCheck

When UseTLS is enabled and TLS has been configured to check client certificates with
TLS_RequireClientCert, this optional parameter specifies that Certificate Revocation
List (CRL) must be checked for revoked certificates during validation of the client certificate

Radiator RADIUS Server

291 of 397

Configuration

5.97.21 TLS_CRLFile

When UseTLS is enabled and TLS has been configured to check client certificates with
TLS_RequireClientCert, and where CRL checking has been enabled with TLS_CRLCheck, this optional parameter specifies one or more CRL files that will be used to
check client certificates for revocation.
If a CRL file is not found, or if the CRL says the certificate has been revoked, TLS
authentication will fail with an error:
SSL3_GET_CLIENT_CERTIFICATE:no certificate returned
One or more CRLs can be named with multiple TLS_CRLFile parameters. Alternatively, CRLs may follow a file naming convention: the hash of the issuer Subject Name
and a suffix that depends on the serial number. e.g. ab1331b2.r0, ab1331b2.r1 etc.
You can find out the hash of the issuer name in a CRL with:
openssl crl -in crl.pem -hash -noout

CRLs with this name convention will be searched in TLS_CAPath, else in the openssl
certificates directory (typically /usr/local/openssl/certs/)
CRLs are expected to be in PEM format. A CRL file can be generated with openssl like
this:
openssl ca -gencrl -revoke cert-clt.pem
openssl ca -gencrl -out crl.pem

Use of these flags requires Net_SSLeay-1.30 or later.

Each CRL file named with a TLS_CRLFile will be automatically reloaded and reread at
the start of each new RadSec session if the modification date of the named CRL file has
changed since the last time it was loaded. If the CRL for a particular issuer changes, it is
sufficient to replace the existing CRL file with the newer version and RadSec will
reload the new CRL when required.
Hint: Operating system wildcards are supported, so you can name multiple CRLs with a
single wildcard like:
TLS_CRLFile %D/crls/*.r0
5.97.22 TLS_ExpectedPeerName

When a RadSec client presents a client certificate, this optional parameter specifies a
regular expression pattern that is required to match the Subject in the client certificate.
Defaults to .+ which means to accept any Subject.
# Accept certificates with CN ending in .xyz.com
TLS_ExpectedPeerName CN=.*\.xyz\.com
5.97.23 TLS_SubjectAltNameURI

When a RadSec client presents a client certificate, this optional parameter specifies a
regular expression pattern that must match against at least one subjectAltName of type
URI in the client certificate.

292 of 397

Radiator RADIUS Server

Configuration

# Accept certificates that have a subjectAltName type URI that

# ends in open.com.au:
TLS_SubjectAltNameURI .*open.com.au
5.97.24 TLS_CertificateFingerprint

You can require that the peer matches one of a specified set of signatures with TLS_CertificateFingerprint. When a TLS peer presents a certificate, this optional parameter
specifies one or more fingerprints, one of which must match the fingerprint of the peer
certificate. Format is algorithm:fingerprint. Requires Net::SSLeay 1.37 or later
TLS_CertificateFingerprint sha1:8E:94:50:0E:2F:D6:DE:16:1D:84:76:FE:2F:14:33:2D:AC:57:04:FF
TLS_CertificateFingerprint sha1:E1:2D:53:2B:7C:6B:8A:29:A2:76:C8:64:36:0B:08:4B:7A:F1:9E:9D
TLS_CertificateFingerprint sha256:EC:14:77:FA:33:AD:2C:20:FF:D2:C8:1C:46:31:73:04:28:9E:ED:12
:D7:8E:79:A0:24:C0:DE:0B:88:A9:DB:3C
TLS_CertificateFingerprint
md5:2A:2D:F1:44:40:81:22:D4:60:6D:9A:B0:F4:BF:DD:24
5.97.25 TLS_RequireClientCert

This optional flag specifies that the RadSec server requires each RadSec client to present a valid client certificate during TLS handshake. If no valid certificate (according to
the root certificate(s) installed on the RadSec server using TLS_CAFile or TLS_CAPath), the TLS handshake will fail and the RadSec connection will be disconnected. For
compliance with RFC 6614, TLS_RequireClientCert is enabled by default.
5.97.26 Identifier

This optional parameter can be used to match Client-Identifier check items in Handler
and other clauses, so that you can trigger special behavior for requests received by a particular ServerRADSEC clause.
5.97.27 PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace
level 5. This is useful for logging packets that pass through this clause in more detail
than other clauses during testing or debugging. The packet tracing will stay in effect
until it passes through another clause with PacketTrace set to off or 0.
# Debug any packets that pass through here
PacketTrace

5.98 <ServerHTTP>
The ServerHTTP clause presents a HTTP interface that allows Radiator to be monitored, configured and reconfigured through a standard Web browser. The Graphical
User Interface (GUI) that it presents is designed to be easy to use and intuitive, and to
allow access to the full range of detailed configuration options that are usually access
directly by editing the configuration file.
The GUI presented by ServerHTTP can be considered a useful alternative to the more
traditional editing of the Radiator configuration file. Further it allows access to other

Radiator RADIUS Server

293 of 397

Configuration

useful information about the host that Radiator is running on, the details of the version
of Perl installed, and details about the versions and modules of Radiator installed on that
host.
The GUI presented by this interface is described in Section 7.0, Web-based configuration GUI, on page 305.
Authentication: Any user attempting to connect to ServerHTTP is subject to authentication. If authentication does not succeed, then the user is unable to access any web pages.
Once logged in, the information the user is permitted to see, and the actions the user is
permitted to do are controlled by the users Privilege Level. The authentication steps
are:
1. Check all the clauses in the AuthBy list, if any, continuing until the AuthByPolicy is

met.
2. If no AuthBy clause succeeds (or if there are no AuthBy clauses), authenticate

against the hardwired Username and Password in this clause.

3. If the hardwired Username is not defined permit authentication as the user anony-

mous without a password.

An authentication lasts for the time period given by SessionTimeout, after which the
user will be required to log in again.
The users Privilege Level is determined in the following way:
1. If the successful authentication was from an AuthBy clause, and the user had a Man-

agement-Policy-Id reply item, then the Privilege Level is given by the integer in the
Management-Policy-Id.
2. Otherwise the Privilege Level is given by the DefaultPrivilegeLevel parameter.

Privilege Level: the information the user is permitted to see, and the actions the user is
permitted to do are controlled by the users Privilege Level. The Privilege Level is a
number from 0 to 15, where 0 is the lowest privilege, (and which does not even permit
logging in), and 15 is the highest, which allows all actions.
The Privilege Level is a bitmask obtained by adding together the following numbers:
1 Permission to view basic (non-security-critical) status only.
2 Permission to reset the server.
4 Permission to edit and change the running configuration (but not save it).
8 Permission to save changes to the configuration file.
For example, to grant privilege to view status and to reset the server, the Privilege Level
should be set to 3 (1 + 2). To grant all privileges, the Privilege Level should be set to 15
(1 + 2 + 4 + 8).
CAUTION: Careless configuration of this clause can open security holes in your
RADIUS host. In order to limit the possibility of security compromise, It is recommended that you:

294 of 397

Radiator RADIUS Server

Configuration

1. Limit the clients that can connect with the Clients parameter
2. Make sure the Radiator configuration file is only readable by root
3. Consider making Radiator run as a non-privileged user
4. Use secure usernames and password to authenticate access to this server.
5. Enable SSL connections only with the UseSSL flag.
6. Disable this clause when not required.

ServerHTTP understands the following parameters:

5.98.1 Port

Port number to listen for connections. Service names or integer port numbers are permitted.
5.98.2 Username

Fallback username to log in as. If there is no Username and no AuthBy clauses, users
will not be required to authenticate in order to use the web interface
5.98.3 Password

Fallback password for Username. Password can be plaintext or any of the encrypted formats such as {crypt}....., {nthash}....., {SHA}...., {SSHA}....., {mysql}...., {msssql}....,
{dechpwd}...., {MD5}......, {clear}.... etc.
5.98.4 AuthBy

List of AuthBy clauses to use to handle authentication for new web connections.
Requests are processed by each AuthBy in order until AuthByPolicy is satisfied. If there
are no AuthBy clauses, the fallback Username and Password will be used
5.98.5 AuthByPolicy

Specifies whether and how to continue authenticating after each AuthBy

5.98.6 AuthLog

List of AuthLog clauses which will be used to log authentication of users logging in the
Server HTTP interface.
5.98.7 AuditTrail

Optional filename where all editing and configuration changes will be logged. Special
characters are supported.
5.98.8 LogMicroseconds

When logging, include microseconds in the time.

5.98.9 SessionTimeout

Maximum time in seconds a session is permitted to continue without logging in again.

5.98.10 LogMaxLines

Maximum number of recent log lines which will be displayed on the Log page.

Radiator RADIUS Server

295 of 397

Configuration

5.98.11 Trace

Logging trace level. Only messages with the specified or higher priority will be logged.
5.98.12 DefaultPrivilegeLevel

Privilege level to be used if a per-user Management-Policy-Id is not available from a

successful authentication from the AuthBy list. The privilege level is a bitmask
described above.
5.98.13 PageNotFoundHook

If a page is requested but not found in the set of built-in pages PageNotFoundHook is
called to try to handle the request. PageNotFoundHook is passed the requested URI and
a reference to the ServerHTTP connection. If it can handle the request, it returns an
array of ($httpcode, $content, @httpheaders), else undef.
PageNotFoundHook sub {return (200, "your HTML content");}
5.98.14 UseSSL, TLS_CAFile, TLS_CAPath, TLS_CertificateFile, TLS_CertificateChainFile,
TLS_CertificateType, TLS_PrivateKeyFile, TLS_PrivateKeyPassword,
TLS_RandomFile, TLS_DHFile, TLS_CRLCheck, TLS_CRLFile,
TLS_ExpectedPeerName, TLS_SubjectAltNameURI, TLS_CertificateFingerprint,
TLS_RequireClientCert

If the UseSSL parameter is set, then all connections to the ServerHTTP port must use
SSL. The behaviour of the SSL connection is controlled by the other TLS_* parameters.
These parameters have the same meaning as described in Section 5.97, <ServerRADSEC>, on page 287.
5.99 <StatsLog FILE>
This clause logs statistics from all Radiator internal objects to a flat file. There is an
example configuration file in goodies/statslog.cfg.
Radiator collects statistics for the server as a whole, as well as for each Client, Realm,
Handler, AuthBy and Host that a packet passes through. The following statistics are collected for each object or clause:

TABLE 6.

296 of 397

Statistics collected within Radiator and usage in Format parameter.

Symbolic name

Description

Format character

requests

Total requests

%22

droppedRequests

Total dropped requests

%14

duplicateRequests

Total duplicate requests

%17

proxiedRequests

Total proxied requests

%21

proxiedNoReply

Total proxied requests with no reply

%20

badAuthRequests

Total Bad authenticators in requests

%11

responseTime

Average response time (seconds). This is a cumulative moving average of the per-request elapsed processing time for the last 100 requests.

%23

Radiator RADIUS Server

Configuration

TABLE 6.

Statistics collected within Radiator and usage in Format parameter.

Symbolic name

Description

Format character

accessRequests

Access requests

%6

dupAccessRequests

Duplicate access requests

%15

accessAccepts

Access accepts

%3

accessRejects

Access rejects

%5

accessChallenges

Access challenges

%4

malformedAccessRequests

Malformed access requests

%18

badAuthAccessRequests

Bad authenticators in authentication requests

%9

droppedAccessRequests

Dropped access requests

%12

accountingRequests

Accounting requests

%7

dupAccountingRequests

Duplicate accounting requests

%16

accountingResponses

Accounting responses

%8

malformedAccountingRequests

Malformed accounting requests

%19

badAuthAccountingRequests

Bad authenticators in accounting requests

%10

droppedAccountingRequests

Dropped accounting requests

%13

In StatsLogFILE, the specified filename is opened every Interval seconds, and the statistics for each object are logged, one line per object. An optional header line is also
logged. For each object logged, the log contains a timestamp (in seconds since 1970),
the type of the object and a unique identifier, if available, followed by the value of each
statistic in alphabetical order by their symbolic name (see table above). It will use the
Identifier field of available, otherwise the object Name.
Statistics for the server as a whole (ServerConfig) will be logged first, followed by each
Client, each Realm, each Handler. Within each Realm and Handler, each AuthBy used
by that clause will be logged (recursively for AuthBy GROUP). Within any AuthBy
RADIUS, statistics for Host clauses will be logged. You can find an example of the log
format in goodies/statslog.cfg.
Caution: In the case of AuthBy clauses you should set a unique Identifier in each
clause, otherwise you will not necessarily be able to distinguish between each AuthBy
clause in StatsLog statistics.
Hint: responseTime measures the per-request processing time, the time required for
Radiator to fully process a single request. It does not measure the Access-Request/
Access-Accept delay.
Hint: responseTime will be computed based on time measurements accurate to 1 microsecond when Time::HiRes module is available. This should be the case with all modern
Perl versions.

Radiator RADIUS Server

297 of 397

Configuration

StatsLogFILE understands the following parameters:

5.99.1 Interval

This is the time interval (in seconds) between each set of statistics. Defaults to 600 seconds (10 minutes).
# Log once per day
Interval 86400
5.99.2 Filename

This is the name of the file to log statistics to. Defaults to %L/statistics. The file
name can include special formatting characters as described in Section 5.2 on page 20,
although data from the current request or reply are never available (logging is never
done in the context of a current request).
Filename /path/to/my/stats.dat
5.99.3 Format

This optional parameter specifies the format for each logging line. You can use this to
control exactly what statistics are logged and in what order they appear.
If Format is not defined, statistics data will be logged in the following order (also shown
is the special character that is available for that data in the Format specification). All
fields will be colon separated.

The current timestamp in seconds since 1970 (%0)

The Type of object whose data is being logged (%1)
The Identifier of the object (if present) else its Name (%2)
Each statistic in alphabetical order of its symbolic name (%3 to %23). See Table 6
on page 296.
# Log the timestamp, objtype, name and average response time
Format %0:%1:%2:%23

5.99.4 Header

This optional parameter allows you to customize the Header line that is logged before
each set of statistics. It can be useful for describing the contents of each column when
importing into Excel etc.
The default is a single line beginning with a hash, followed a name for each column,
colon separated.
If Header is defined as an empty string, no Header lines will be written.
# No headers
Header

5.100 <StatsLog SQL>

This clause logs statistics from all Radiator internal objects to an SQL database. There is
an example configuration file in goodies/statslog.cfg.

298 of 397

Radiator RADIUS Server

Configuration

See Section 5.99 on page 296 for a discussion about what data is available for logging.
By default, StatsLog SQL executes an SQL insert statement for each object to be
logged, which includes a timestamp, object type, object name, and each statistic available for logging.
StatsLog SQL understands the following parameters:
5.100.1 DBSource, DBUsername, DBAuth, Timeout, FailureBackoffTime

These parameters specify how to connect to the SQL database. They need to be set in a
similar way to as for <AuthBy SQL> (see Section 5.30 on page 111). They specify the
DBD driver, database and username to connect to, and how to handle SQL server failures.
# Connect to mSQL with database named radius
DBSource
dbi:mSQL:radius
DBUSername sqlusername
DBAuth
sqluserpassword
5.100.2 Interval

This is the time interval (in seconds) between each set of statistics. Defaults to 600 seconds (10 minutes).
# Log once per day
Interval 86400
5.100.3 InsertQuery

This optional parameter specifies the SQL query to be used for each log. It can include
special formatting characters as described in Section 5.2 on page 20. %0 to %23 are
replaced by statistics data as described in Section 5.99.3 on page 298.
The default is an SQL query something like this, which is compatible with the example
RADSTATSLOG table created by the example database schemas in goodies.
insert into RADSTATSLOG (TIME_STAMP, TYPE, IDENTIFER, <symbolic
stats names>) values (9999999, objectname, objectidentifier, <statistics values>)

Here is an example that only logs a subset of the statistics:

InsertQuery insert into MYTABLE (TIME_STAMP, TYPE, ID, \
RESPONSETIME) values (%0, %1, %2, %23)

5.101 <Monitor>
This clause enables external client programs to make an (authenticated) TCP connection
to Radiator, and use that connection to monitor, probe, modify and collect statistics from
Radiator. One such external client program is Radar, a real-time interactive GUI that
permits monitoring, plotting of statistics and much more. See http://www.open.com.au/
radar for more details.

Radiator RADIUS Server

299 of 397

Configuration

Monitor also permits telnet connections and implements a simple command syntax that
allows various simple and complex actions to be executed. See Section 23.0 on
page 384 for details on the command language that Monitor implements. Monitor permits multiple simultaneous independent connections. Radiator also permits multiple
Monitor clauses (each listening on a different Port or BindAddress, See Global parameters on page 28.).
Monitor authenticates incoming connections. Only if the connection submits a valid
username and password will Monitor honour any requests on that connection. You can
configure Monitor with either a hardwired username and password, or with a standard
Radiator AuthBy clause. You can specify one or more AuthBy parameters or AuthBy
clauses and an AuthByPolicy similar to AuthBy GROUP (see Section 5.27 on
page 105). As a security measure, if a Monitor connection fails authentication 5 times,
the connection will be automatically disconnected.
CAUTION: Careless configuration of this clause can open security holes in your
RADIUS host. It is recommended that you:
1. Limit the clients that can connect with the Clients parameter
2. Make sure the configuration file is only readable by root
3. Consider making radiusd run as a non-privileged user
4. Use secure usernames and password to authenticate access to this server.
5. Disable this clause when not required.

Monitor understands the following parameters:

5.101.1 Port

This optional parameter specifies the TCP port number to listen on. The argument may
be either a numeric port number or an alphanumeric service name as specified in
/etc/services (or its moral equivalent on your system). Defaults to 9048.
Hint: You can pass the port number as a command line argument to radiusd with a configuration like this:
Port %{GlobalVar:monitorport}

and then run radiusd with an argument to set the port number like this:
radiusd monitorport=9000 ....
5.101.2 Clients

This optional parameter specifies a list of IP addresses that Monitor will accept connection from. You can specify one or more comma or space separated IP addresses on each
Client line. You can specify multiple Client parameters. Only exact matches are supported at present. The default is to accept connections from any and all clients.
If Clients is specified and a client attempts to connect from an IP address that is not
named, Monitor will print a WARNING message then reject and close the connection.

300 of 397

Radiator RADIUS Server

Configuration

# Only accept connections from some addresses

Clients 127.0.0.1, 203.63.154.29
Clients 203.63.154.27
5.101.3 BindAddress

This optional parameter specifies a single host address to listen for Monitor connections
on. It is only useful if you are running Radiator on a multi-homed host (i.e. a host that
has more than one network address). Defaults to 0.0.0.0 (i.e. listens on all networks connected to the host). See Global parameters on page 28.
Using this parameter, you can run multiple instances of Radiator on the one computer,
where each Radiator listens to Monitor requests directed to a different host address. BindAddress can include special formatting characters.
# Only listen on one network address
BindAddress 203.63.154.1
5.101.4 AuthBy, <AuthBy xxxx> and AuthByPolicy

Monitor supports either a hardwired username and password, or one or more AuthBy
parameters or <AuthBy xxx> clauses in a similar way to AuthBy GROUP See
Section 5.27 on page 105 for more information. If there are no AuthBy clauses, or if
they all IGNORE the authentication, the hardwired Username and Password will be
tried.
Hint: If you are configuring Monitor in order to accept connections from Radar, or any
other application that uses the Monitor {chap} passwords, the AuthBy needs to be one
that contains plaintext passwords in its database.
5.101.5 Username

This optional parameter specifies the username that must authenticate any connection
through this Monitor clause. Username and Password will be checked if there are no
AuthBy clauses, or if they all IGNORE the authentication.
# Hardwired username and password
Username mikem
Password fred
5.101.6 Password

This optional parameter specifies the password that must authenticate any connection
through this Monitor clause. Username and Password will be checked if there are no
AuthBy clauses, or if they all IGNORE the authentication.
5.101.7 TraceOnly

This optional parameter prevents connections through this Monitor from getting statistics, getting or setting configuration data, or restarting the server. It inhibits the following Monitor commands:

STATS
DESCRIBE
SET
LIST

Radiator RADIUS Server

301 of 397

radiusd

RESTART
GET
This flag is useful for limiting access to privileged data by certain staff.
Hint: You can have multiple Monitor clauses on different Ports, so it is possible to have
one with TraceOnly and one without. This would allow you to permit some Radar users
to get access only to Trace data, and some to have access to all functions:
# This one is restricted
<Monitor>
Port 9001
TraceOnly
Username xxx
Password xxx
</Monitor>
# This one allows a superuser to get access to all data
<Monitor>

Port 9002

Username yyy
Password yyy
</Monitor>
5.101.8 StatisticsOnly

This optional parameter prevents connections through this Monitor from tracing, getting
or setting configuration data, or restarting the server. It inhibits the following Monitor
commands:

TRACE
TRACE_USERNAME
DESCRIBE
SET
LIST
RESTART
GET

This flag is useful for limiting access to privileged data by certain staff.
5.101.9 LogMicroseconds

This optional parameter makes Monitor log the current microseconds at the end of the
time string.

6.0 radiusd
Radiusd is the Radiator RADIUS server. At start-up, radiusd will try to open and
read its configuration file. By default the configuration file is /etc/radiator/
radius.cfg, but this can be changed with the -config_file flag. When started,

302 of 397

Radiator RADIUS Server

radiusd

radiusd will create a PID file in the ___location specified by PidFile in the configuration file
(the default is /etc/radiusd.pid).
If radiusd is signalled with SIGHUP, it will reinitialize by rereading the configuration
file. All Clients, Realms, Handlers etc. defined in the old configuration file will be lost,
and new ones will be configured. The effect of SIGHUP is expected to be the same as if
you killed and then restarted radiusd.
If radiusd is signaled with SIGTERM, it will exit gracefully.
If radiusd is signaled with SIGUSR1, it will increase its current Trace level by 1.
SIGUSR2 will decrease it by one.
Command line arguments given to radiusd will override parameter settings in the configuration file. You should consult the section on global configuration file parameters
(See Section 5.4 on page 25) for the meaning of those parameters.
The arguments are:

radiusd [-I dirname] [-h] [-v] [-c] [-auth_port port] [-acct_port port]
[-db_dir dirname] [-log_dir dirname]
[-bind_address dotted-ip-address]
[-log_file filename]
[-config_file filename]
[-dictionary_file filename,filename]
[-foreground] [-daemon] [-log_stdout]
[-trace n] [-pid_file filename]
[-service] [-installservice] [-uninstallservice] [-servicename name]
[-serviceperlargs perlargs]
[globalvarname=value]

-h
Print usage information and exit.

-I dirname
Prepend dirname to the module search path.

-v
Print version information and exit.

-c
Parse the configuration file, reporting errors in the usual way, then exit.

-auth_port port,port,...
Specifies the port(s) to listen for Access-Requests. Overrides AuthPort.

-acct_port port,port,...
Specifies the port(s) to listen for Accounting-Requests. Overrides AcctPort.

-db_dir dirname
Specifies the database directory. Overrides DbDir.

-log_dir dirname
Specifies the log file directory. Overrides LogDir.

Radiator RADIUS Server

303 of 397

radiusd

-log_file filename
Specifies the name of the log file. Overrides LogFile.

-config_file filename
Read filename as the configuration file. Defaults to
/etc/radiator/radius.cfg on Unix,
C:\Program Files\Radiator\radius.cfg on Windows and
Macintosh HD:Applications:Radiator:etc:radius.cfg on Mac
OS9.

-dictionary_file filename,filename
Specifies the name of one or more dictionary file. Overrides DictionaryFile.

-foreground
Run in the foreground, not as a daemon. The default behavior is to run as a daemon.

-daemon
Forces radiusd to run as a daemon (in the background) regardless of the setting of
Foreground in the configuration file.

-log_stdout
Log to STDOUT as well as to LogFile, if running in the foreground.

-trace n
Set the trace level to n. Overrides Trace.

-pid_file filename
Write the PID to filename. Overrides PidFile.

-bind_address dotted-ip-address
Specifies a single IP address to listen on. Overrides BindAddress. See Global
parameters on page 28.

-service
For specialized use on Windows only. Tells Radiator to run as a Windows Service.
Requires Win32::Daemon, and requires that the service have been previously
installed with -installservice. Requires Win32::Daemon.

-installservice
On Windows, installs or reinstalls Radiator to run as a Windows Service. The service
will be configured to run Radiator with all the same arguments as was passed with installservice, and it will add the -service flag. After this, the Radiator service will
appear in the Windows Service list as Radiator Radius Server. The Service will
automatically start next time the host is booted. Requires Win32::Daemon.
On Win7 and others, the command prompt needs to be started with right click ->
"Run as administrator". Otherwise even as user with administrator privileges, the
service does not get installed

-uninstallservice
On Windows, removes Radiator from Running as a Windows Service. Ensure the
service is stopped before uninstalling it. Requires Win32::Daemon. If a -servicename argument was used with -installservice, then the same -servicename argument
must be used to uninstall the service.

304 of 397

Radiator RADIUS Server

Web-based configuration GUI

-servicename
On Windows, if Radiator is being installed or uninstalled as a service, this argument
specifies the name that the service will be installed under. Defaults to Radiator.
Specifying a different service name allows multiple Radiator services to be run at the
same time.

-serviceperlargs args
On Windows, if Radiator is being installed or uninstalled as a service, this argument
specifies extra arguments to pass to perl when the service starts. This is useful for
specifying an alternative install directory for the Radiator perl modules:
perl c:/Radiator/radiusd -installservice -serviceperlargs -I
c:/Radiator

globalvarname=value
Defines the global variable called globalvarname to be defined as the string
value. The value can be accessed anywhere special formatting characters are permitted with %{GlobalVar:globalvarname}. This argument has exactly the same
effect as
DefineFormattedGlobalVar globalvarname value

in the configuration file.

7.0 Web-based configuration GUI

If your Radiator configuration file has a <ServerHTTP> clause configured (See
<ServerHTTP> on page 293.) then you can connect to Radiator with any standard
Web browser and use it to inspect, monitor, configure, restart, reconfigure, save and
check statistics of your Radiator server from anywhere in your network.
This makes configuration and maintenance of your Radiator easier for staff that are not
familiar with more traditional command-line tools and configuration file editing.
Hint: a simple configuration file that enables <ServerHTTP>, allowing you to get
started with using the Web-based configuration GUI is in goodies/serverhttp.cfg in your
distribution.
Hint: The default port number that ServerHTTP uses is 9048. Use a URL of
http://localhost:9048

If UseSSL is enabled in your ServerHTTP clause, use a URL of

https://localhost:9048

7.1 Login page

When you first connect to the HTTP server port, you will be presented with a login
page. Log in with the Username and Password configured into the Radiator configuration file (the default shipped in the sample configuration file is Username mikem Password fred).

Radiator RADIUS Server

305 of 397

Web-based configuration GUI

Hint: If the HTTP server has been configured not to require a username and password,
you will be logged in immediately without seeing the Login page.

FIGURE 3.

Login page

Enter your Username and

Password here.

After successful authentication, you will see the Home Page:

7.2 Home Page

FIGURE 4.

Home Page
See your username
and Privilege Level here

Navigation Area
GUI Overview

306 of 397

Radiator RADIUS Server

Web-based configuration GUI

The Home page displays basic information about the GUI and provides a Navigation
Area, from which you can access all the functions available to you.
The Navigation area contains links to each type of page you are authorized to see. The
list of links depends on your Privilege Level (see Section 5.98, <ServerHTTP>, on
page 293 for details on Privilege Levels).
7.3 Administration
7.3.1 Server status

FIGURE 5.

Server status Page

The Server Status page shows details about this instance of Radiator, including the command line used to start it, the name of the configuration file, how long the server has
been running for and how many requests it has processed.

Radiator RADIUS Server

307 of 397

Web-based configuration GUI

7.3.2 View log

FIGURE 6.

View log Page

The GUI log collects and displays the last LogMaxLines of log messages at or above the
current Trace level. To renew the displayed list, click Refresh on your browser.
To change the number or severity of collected log messages, click on Edit and see the
ServerConfig page. Click on Show Advanced Options. Click on Server ServerHTTP
and see the ServerHTTP configuration page. Adjust Trace on this page and LogMaxLines on the Advanced Options page.
7.3.3 Logout

The logout link logs you out of the GUI. A new Login page will be displayed (see
Section 7.1, Login page, on page 305).

308 of 397

Radiator RADIUS Server

Web-based configuration GUI

7.4 Configuration
7.4.1 Edit

FIGURE 7.

Edit Page

Edit Basic Options

on this page.

Edit various basic

parameters here

Click here to see more

advanced options

Hover the mouse here

to see basic online
help for each
parameter

Click here to edit a

Client sub clause
Click here to create a new
Client sub clause

Click here to apply

any edits made to
this page

Click here to delete this

Realm sub clause

The Edit page displays configuration details for a single configurable Radiator object.
Each Edit page corresponds to a Radiator configuration clause. By clicking on appropriate links you can drill down into the hierarchy of configuration clauses and examine and
change the configuration of each clause.
The first page you see when you click on the Edit link is the ServerConfig page, which
is the main (top-level) configuration page. All the Radiator configuration clauses and
their sub-clauses are accessed starting at the ServerConfig page and drilling down into
subclauses.
For a given configuration object, the GUI displays up to four different pages, one for
each level of configuration detail:

Basic Options
Displays the most basic configuration options that must be configured in order for
the object to work at all.

Radiator RADIUS Server

309 of 397

Web-based configuration GUI

Advanced Options
Shows more advanced options that can fine tune the basic operation of the object.

Very Advanced Options

Shows options that are rarely used and which are only required under unusual circumstances.

Deprecated Options
Shows options that should never be used in a new installation. They are only provided for compatibility with old deprecated (discouraged) options.
7.4.2 Load config file

FIGURE 8.

Load config Page

This page allows you to upload an entire new configuration file into Radiator.
After uploading, the new configuration will take effect. However the new configuration
will not be saved until you click on Save on the Save page (see Section 7.4.3, Save,
on page 311).
Hint: if the new configuration does not include a ServerHTTP clause, you will not be
able to reconnect to the server with the browser.
Hint: there are many sample configuration files included in the goodies directory of
your Radiator distribution.

310 of 397

Radiator RADIUS Server

Web-based configuration GUI

7.4.3 Save

FIGURE 9.

Save Page

This page allows you to save the currently running Radiator configuration to the configuration file specified on the Radiator command line. The original configuration file will
be saved and renamed with a .bak extension.
Caution: The newly saved configuration file will not include any formatting or comments that may have been present in the original configuration file.

Radiator RADIUS Server

311 of 397

Web-based configuration GUI

7.5 Miscellaneous
7.5.1 License

FIGURE 10.

License Page

This page displays the software license that applies to your copy of Radiator.
7.5.2 Support

FIGURE 11.

Support Page

312 of 397

Radiator RADIUS Server

Web-based configuration GUI

This page displays useful information about what levels of support are available for
Radiator and how to access them.
7.5.3 System

FIGURE 12.

System Page

This page shows information about the machine that this instance of Radiator is running
on.

Radiator RADIUS Server

313 of 397

Web-based configuration GUI

7.5.4 Perl

FIGURE 13.

Perl Page

This page shows information about the version of the Perl interpreter that Radiator is
using on this machine.
7.5.5 Modules

FIGURE 14.

Modules Page

Main Radiator version

number

Individual module
versions

314 of 397

Radiator RADIUS Server

Web-based configuration GUI

This page lists all the Radiator perl modules that are currently loaded into Radiator, and
the version number of each one. Also shown is the main Radiator version number.
Hint: The list of modules you see will depend on the precise configuration your Radiator is running, since many Radiator modules are only loaded when required.
7.6 Advanced
7.6.1 Manual edit

FIGURE 15.

Manual edit Page

Text of the current

configuration file

Saves the text to the

configuration file, but
does not run it.

This page allows direct manual editing of the configuration file without having to start a
text editor on the host machine. In order to use this interface, you need to be familiar
with Radiator configuration file format and syntax, as described in Section 5.0, Configuration, on page 17. The original configuration file will be saved and renamed with
a .bak extension.
Saving a new configuration with the Save button saves the edited text to the configuration file (after making a backup of the original), but Radiator will not run with the new
configuration until it is reset with the Reset server page (see Section 7.6.2, Reset
server, on page 316).

Radiator RADIUS Server

315 of 397

radpwtst

7.6.2 Reset server

FIGURE 16.

Reset server Page

Unsaved configuration changes

will be flagged here

Causes Radiator to reread the

configuration and restart

This page allows you to Reset Radiator. Resetting causes Radiator to reread the configuration file and restart. Any unsaved configuration changes in the currently running
configuration will be lost. If there are any unsaved configuration changes you will be
informed of this.

8.0 radpwtst
Radpwtst sends requests to a RADIUS server such as Radiator, and waits for a reply.
You can use it to send Access-Request, Accounting-Request (Stop and Start) and StatusServer requests. Radpwtst is good for checking that your Radiator server (or any other
RADIUS server for that matter) is configured and behaving correctly, and also for
checking that a users password is correct.
By default, radpwtst will send an Access-Request, wait up to 5 seconds for a reply, send
an Accounting-Request (Start), wait for a reply, then send an Accounting-Request
(Stop) and wait for a reply. You can change this behavior with the command line flags.
Hint: If a Framed-IP-Address is received in an Access Accept, then radpwtst will use
that address in subsequent Accounting Starts and Stops (unless the -framed_ip_address
flag has been set. This allows simple testing of address allocation modules etc.
Hint: A fundamental requirement of the RADIUS protocol is that the RADIUS Client
(in this case radpwtst) and the RADIUS Server (in this case Radiator) must use the same
shared secret. If Radiator keeps rejecting your request with a Bad Password, even
though you are sure the password is correct, it may be because the shared secrets are not

316 of 397

Radiator RADIUS Server

radpwtst

correct. Check the Secret line in your Radiator config file, and perhaps use the secret command line argument to radpwtst. If you dont specify a -secret argument to radpwtst, it will use mysecret by default.
Hint: While testing with radpwtst, you should set up a Client for localhost with a DupInterval to 0 in Radiator, otherwise Radiator may report duplicate requests and other
misleading errors. Add something like this to your Radiator configuration file, and you
will be able to run radpwtst freely on the same host as where Radiator is running.
<Client localhost>
Secret mysecret
DupInterval 0
</Client>

The arguments to radpwtst are:

radpwtst [-h] [-time] [-iterations n]
[-trace [level]] [-notrace]
[-user username] [-password password]
[-s server] [-secret secret] [-auth_port port] [-acct_port port]
[-noauth] [-noacct] [-nostart] [-nostop] [-alive] [-status]
[-chap] [-chap_nc] [-mschap] [-mschapv2] [-eapmd5] [-eapotp] [eapgtc] [-sip] [-leap]
[-motp_secret xxxxxxxxxxxxxxxx] [-eaphex xxxxxxxxxxxxx]
[-interactive] [-code requestcode] [-accton] [-acctoff]
[-identifier n] [-framed_ip_address address]
[-nas_ip_address address] [-nas_identifier string]
[-nas_port port] [-nas_port_type type] [-service_type service]
[-calling_station_id string] [-called_station_id string]
[-session_id string] [-session_time n]
[-delay_time n] [-input_octets n] [-output_octets n]
[-timeout n] [-retries n] [-dictionary file,file]
[-class string] [-message_authenticator]
[-raw data] [-rawfile filename] [-rawfileseq filename]
[-outport port] [-bind_address address]
[-options optionfile] [-gui]
[attribute=value]...

-h
Print usage and exit.

-time
Specifies that radpwtst will print the elapsed time taken to send and receive all iterations when it is finished. Useful for testing purposes, since it is a measure of how
fast the radius server can handle requests.

-iterations n
Send all the selected requests n times, instead of just once.

-trace [n]
Print useful trace information, including the full contents of all transmitted and
received requests. Default is to print limited information from the reply. The trace
level is optional and defaults to level 1. -trace 5 will produce hex packet dumps of
requests and replies.

Radiator RADIUS Server

317 of 397

radpwtst

-notrace
Dont print any trace information. Default is to print limited information from the
reply.

-user username
Requests will be tagged with User-Name of username. Default is mikem.

-password password
In Access-Requests, the password will be password. Default is fred.

-s server
Send all the requests to server, which can be either the IP address or the DNS
name of the host where the destination RADIUS server runs. The default is localhost.

-secret secret
Use secret as the shared secret. The default is mysecret.

-auth_port port
Port to use for authentication requests . The default is 1645.

-acct_port port
Port to use for accounting requests. The default is 1646.

-noauth
Dont send the Access-Request.

-noacct
Dont send either of the Accounting-Request.

-nostart
Dont send the Access-Request Start.

-nostop
Dont send the Access-Request Stop.

-alive
Send an Accounting-Request with Acct-Status-Type of Alive.

-status
Send a Server-Status. The contents of the reply will be printed.
Note: The Status-Server RFC requires Message-Authenticator. In most cases you
need the -message_authenticator option also.

-chap
Authenticate with CHAP, instead of PAP.

-chap_nc
Authenticate with CHAP, instead of PAP, with the CHAP Challenge in the authenticator, and not in a separate CHAP-Challenge attribute.

-mschap
Authenticate with MSCHAP, instead of PAP or CHAP. Requires Digest-MD4-1.0 or
better from CPAN or ActiveState.

-mschapv2
318 of 397

Radiator RADIUS Server

radpwtst

Authenticate with MSCHAP V2, instead of MSCHAP, PAP or CHAP. Requires

Digest-MD4 version 1.1 or better and Digest-SHA version 5.0 or better from CPAN
or ActiveState.

-eapmd5
Authenticate with EAP-MD5. This will usually involve 2 requests being sent to the
server. The first is the EAP Identity, the second is the EAP-MD5 response.

-eapotp
Authenticate with EAP-One Time Password. This will usually involve 2 requests
being sent to the server. The first is the EAP Identity, the second is the EAP-One
Time Password response.

-eapgtc
Authenticate with EAP-Generic Token Card. This will usually involve 2 requests
being sent to the server. The first is the EAP Identity, the second is the EAP-Generic
Token Card response.

-sip
Do SIP Digest authentication as per draft-sterman-aaa-sip-00.txt. Requires special
attributes in the additional dictionary.sip in your distribution, so it should be used
with -dictionary dictionary,dictionary.sip

-leap
Do EAP-LEAP authentication. This will usually involve 3 requests being sent to the
server. The first is the EAP Identity, the second is the LEAP client response and the
third is the LEAP Access Point Challenge.

-motp_secret xxxxxxxxxxxxxxxx
Make Mobile OTP request using the password as PIN and motp_secret as the
MOTP secret key.

-eaphex xxxxxxxxxxx
Add an EAP-Message attribute to the request. Argument is the message contents in
hex. The correct Message-Authenticator will be automatically added.

-interactive
If an Access-Challenge is received in response to an Access-Request, radpwtst will
display the Reply-Message, read a new password from STDIN and send a new
Access-Request, automatically copying any State attribute to the new request. This
flag is useful for testing methods like AuthBy ACE and AuthBy OPIE, which use
Access-Challenge to prompt the user during a series of steps in an authentication
conversation.

-code requestcode
Tells radpwtst to send (in addition to any other request required) a RADIUS request
with the given code name. Code names such as Ascend-Access-Next-Code, Disconnect-Request and Change-Filter-Request are all supported. Note that -code Status-Server is identical in meaning to -status.

-accton
Send Accounting-On request.

-acctoff

Radiator RADIUS Server

319 of 397

radpwtst

Send Accounting-Off request

-framed_ip_address address
Access requests will be sent with the given Framed-IP-Address. Defaults to 0.0.0.0.
If the address is 0.0.0.0, it will not be sent in the request. Be default radpwtst takes
notice of any Framed-IP-Address returned in a Access-Accept, and uses it in subsequent Accounting Stops and Starts. Setting -framed_ip_address causes the same
address to be used for all Accounting Stops and Starts.

-nas_ip_address address
Access and Accounting requests will have NAS-IP-Address of address. Default is
203.63.154.1.

-nas_identifier identifier
Access and Accounting requests will have NAS-Identifier of identifier.
Default is 203.63.154.1.

-nas_port port
Access and Accounting request will have NAS-Port of port. Default is 1234.

-nas_port_type type
Access and Accounting request will have NAS-Port-Type of type. Default is
Async.

-service_type service
Access and Accounting request will have Service-Type of service. Default is
Framed-User.

-called_station_id string
Access and Accounting requests will have Called-Station-Id of string. Default is
123456789. If set to an empty string, Called-Station-Id will not be included in the
request.

-calling_station_id string
Access and Accounting requests will have Calling-Station-Id of string. Default is
987654321. If set to an empty string, Calling-Station-Id will not be included in the
request.

-session_id string
Accounting request will have Acct-Session-ID of string. Default is 00001234.

-session_time n
Accounting request will have Acct-Session-Time of n. Default is 1000.

-delay_time n
Accounting request will have Acct-Delay-Time of n. Default is 0.

-input_octets n
Accounting request will have Acct-Input-Octets of n. Default is 20000.

-output_octets n
Accounting request will have Acct-Output-Octets of n. Default is 30000.

-timeout n

320 of 397

Radiator RADIUS Server

radpwtst

Specifies the time in seconds that radpwtst will wait for a reply. Default is 5 seconds.
If you specify 0, it will not wait for a reply at all.

-retries n
If there is no reply, send up to n retries . The default is 0 and no retries are sent.

-dictionary file,file
Use file as the dictionary file. Multiple dictionary files may be specified as
comma-separated file names. If -dictionary is not specified, radpwtst will automatically load for the first file that exists from this list: ./dictionary /etc/radiator/dictionary /usr/local/etc/raddb/dictionary /usr/local/etc/radiator/dictionary.

-class string
Tells radpwtst to send string as the Class attribute in any accounting requests. Class
will default to the Class returned by any previous access-accepts.

-message_authenticator
Send a correctly calculated Message-Authenticator attribute with the request.
Note: Some authentication methods already add Message-Authenticator automatically. For example, EAP requires Message-Authenticator.
Note: Trace 4 output shows sent Message-Authenticator before its final value is calculated.

-useoldascendpasswords
Tells radpwtst to encode passwords using the old (non RFC compliant) method that
Ascend used to use for some NASs. The default is to us the RFC2865 compliant
algorithm.

-raw data
Send raw data literally. An example of suitable raw data is trace 5 packet dump output. White space in the data is ignored.

-rawfile filename
Read raw data from file called filename and send it literally. Raw data can be split
to multiple lines

-rawfileseq filename
Read a sequence of raw data from file called filename and send it literally. The
requests are separated with delimiter NewPacket.

-outport port
Tells radpwtst to send requests from the given port. Port can be a port number or a
port service name as used in /etc/services or it equivalent on your system. Defaults to
0, meaning allocate a random port.

-bind_address address
Tells radpwtst to send requests through the network interface for the given IP
address. Requests will appear to originate from the specified IP address Defaults to
0.0.0.0, which means the default address of the default network interface. If the destination address (i.e. the -s flag) is an IPv6 address and -bind_address is specified,
bind_address must also be an IPv6 address.

-options optionfile

Radiator RADIUS Server

321 of 397

radpwtst

Read the command line options from the file specified with optionfile. The file
format is described in Section 8.1 on page 322.

-gui
Present a Graphical User Interface that allows easy interactive testing. This GUI will
run on Unix. The GUI is not yet available on Windows hosts. Requests will be sent
when the Send button is pressed, and the GUI will stay up after the requests have
been sent, so you can send more. Requires Perl Tk module.

attribute=value
You can also force any number of additional attributes to be sent in each request by
naming them with their values on the command line. attribute must be the name of
an attribute in your dictionary, and value must be a valid value for that attribute.
8.1 radpwtst option file
radpwtst options can be placed in an option file. The file format is one option per line.
Leading and trailing white space is ignored. To preserve leading or trailing white space,
use double quotes () to surround the value. Empty lines and lines with # as first nonwhite space character are ignored. Use only one space between option name and value.
See the example below.
radpwtst looks for options in /etc/radpwtstrc and $HOME/.radpwtstrc
# Set some defaults. Note: just one space between
# the option name and value
-trace 4
-nas_identifier name with leading and trailing spaces

# Attributes can have whitespace in the value only. Surround

# the value with if there is trailing or leading space
Connect-Info=52100/31200 V91

8.2 radpwtst examples

Send Access-Request and Accounting Start to server oscar.open.com.au for user
[email protected] and password jim. Authenticate with CHAP. Make sure the request
includes Connect-Info of 52100/31200 V91:
radpwtst -s oscar.open.com.au -nostop -chap
-user [email protected] -password jim
Connect-Info=52100/31200 V91

Send Server-Status request to fred.open.com.au, print the reply:

radpwtst -status -noauth -noacct -s fred.open.com.au
-trace -message_authenticator

Send 1000 Access-Requests to 1.2.3.4 for user fred, password jim, and print out how
long it took:
radpwtst -iterations 1000 -noacct -user fred
-password jim -time

322 of 397

Radiator RADIUS Server

radpwtst

Send a Disconnect-Request:
radpwtst -noacct -noauth -code Disconnect-Request NAS-Port=1234

Make the GUI appear for extended interactive testing:

radpwtst -gui

Send an Access-Request to an IPv6 address

radpwtst -noacct -s 2001:db8:100:f101::1

Send an Access-Request to the localhost loopback address using IPv6

radpwtst -noacct -s ::1

8.3 The radpwtst GUI

The radpwtst program will present a Graphical User Interface (GUI) when it is
started with the -gui flag. If you select this option, the GUI will stay visible until dismissed. This allows you to send a number of different requests with a single mouse
click, and to quickly and easily change the attributes to be sent. These features allow
easy testing of Radiator (or any other RADIUS server for that matter), particularly when
configuring a new realm or user.
Note: radpwtst -gui requires the Perl Tk module to be installed on your host machine.
The command line flags given to radpwtst are used to preconfigure the values you see in
the interface. You can change the values at any time to affect the next request to be sent.
Press the Start button to commence sending, and the Stop button to stop sending.
On each iteration, radpwtst will send one of each of the requests selected in the middle
panel. The requests will contain attributes and values configured in the first panel, and
the requests will be sent to the server and ports configured in the third panel. Not all
attributes are sent in every request type: only the usual ones for that request type.
In the lower panel, you can trace the progress of each request and the reply, You can
control the level of detail seen for each request and reply with the Options->Trace Level
menu.

Radiator RADIUS Server

323 of 397

builddbm

FIGURE 17.

radpwtst Graphical User Interface

Options->Trace Level changes the level of
detail seen

Press Send
to start
sending

Control what types of requests

to send here
This section controls which
server to send to

Set up the attributes

you want to send here

See the details of requests and replies here

9.0 builddbm
builddbm can create and update DBM format user database files (see Section 15.3 on
page 359) from flat file format user database files (see Section 15.2 on page 358). It can
also be used to print or delete the information for a single user from a DBM file.

324 of 397

Radiator RADIUS Server

builddbm

DBM files should be used with Radiator if you require fast authentication, but also need
to change your user database on-the-fly while Radiator is running, and you dont or
cant use AuthBy SQL or AuthBy FILE in Nocache mode.
Radiator will choose the best format of DBM file available to you, depending on
which DBM modules are installed on your machine. (Hint: You can force it to choose a
particular DBM file format by using the -t flag)
The arguments are:
builddbm [-z] [-u] [-f flatfile] [-d user] [-l user]
[-p]
[-t type] dbfile

-z
Delete all entries from the database before processing other commands.

-u
Update mode. Replace user entries that already exist in the DBM file rather than
complaining.

-f flatfile
The name of the flat file format user database to be used to populate the DBM file.
Defaults to dbfile, i.e. the name of the DBM file, without the .pag or .dir suffixes.

-d user
Delete the entry for user from the DBM file

-l user
Print out the entry for user in a format that could be re-imported into builddbm.

-p
Print the contents of the DBM file in standard Livingston flat file format. The check
and reply attributes of all users in the database are printed out in no particular order.
The printed output goes to stdout.

-t dbmtype
Forces builddbm to use a particular format of DBM file. The value of dbmtype can
be AnyDBM_File, NDBM_File, DB_File, GDBM_File, SDBM_File or ODBM_File. Defaults to AnyDBM_File, which selects the best format on the host machine.

dbfile
The base name of the DBM files to create or use. The actual filenames will depend
on the DBM module that Perl has selected, but, it will usually be something like
dbfile.dir and dbfile.pag. Mandatory.
Examples:
Rebuild the entire DBM database in users.dir and users.pag from the users
file, clearing old entries first:
builddbm -z users

Radiator RADIUS Server

325 of 397

buildsql

Update the Berkeley DB format database files all.db with the users in the file
users:
builddbm -u -f users -t DB_File all.db

Print the entry associated with the user mikem in the DBM files staff.dir,
staff.pag:
builddbm -l mikem staff

10.0 buildsql
The buildsql utility creates or updates an SQL authentication table from the contents
of a Unix password file or from a (Livingston) standard RADIUS users file. It can also
be used to print or delete the information for a single user from an SQL authentication
table.
An SQL database should be used with Radiator if you require fast authentication, large
user populations and also need to change your user database on-the-fly while Radiator is
running, and you dont or cant use AuthBy DBM, or AuthBy FILE in Nocache mode.
By default, buildsql connects to the SQL database specified by the -dbsource, -dbusername and -dbauth command line flags. You must specify these flags. See Section 24.0
on page 388 for details on how to set these flags for different database vendors
By default, buildsql inserts or updates records in a table called SUBSCRIBERS, but
you can change this with a command line flag. By default, it only affects four columns
in the table: USERNAME, PASSWORD, CHECKATTR, REPLYATTR, but you can
change this with command line arguments. All other columns are unaffected by
buildsql, so you can have arbitrarily complicated tables. You can change the names
of the columns that buildsql uses with command line arguments. The default names
are compatible with the default names used by the SQL authentication module.
The arguments are:
buildsql [-z] [-u] [-f] [-d user] [-l user] [-v]
-dbsource dbi:drivername:option
[-dbusername dbusername] [-dbauth auth]
[-password | -dbm | -flat]
[-tablename name]
[-username_column columnname]
[-password_column columnname]
[encryptedpassword]
[-checkattr_column columnname]
[-replyattr_column columnname] file ....

-z
Delete all user entries from the database before processing other commands.

-u
326 of 397

Radiator RADIUS Server

buildsql

Update mode. Replace user entries that already exist in the database rather than complaining about constraint violations.

-f
Force database update for non defined fields

-d user
Delete user from the SQL database

-l user
Print out the entry for user in a format that could be re-imported into buildsql.

-v
Print out every SQL statement being issued before its executed

-dbsource dbi:drivername:option
Specifies the data source name of the database to connect to. Must be specified.
-dbusername username
Specifies the username to use to connect to the SQL database.

dbauth password
Specifies the password for dbusername. Not required for some database types.

-password
The source files are in Unix password file format. See Section 15.4 on page 359.

-dbm
The source files are in DB file format. See Section 15.3 on page 359.

-t dbmtype
Forces buildsql to use a particular format of DBM file. The value of dbmtype can be
AnyDBM_File, NDBM_File, DB_File, GDBM_File, SDBM_File or ODBM_File.
Defaults to AnyDBM_File, which selects the best format on the host machine.

-flat
The source files are in standard radius flat file format. See Section 15.2 on page 358.
This is the default. If no input file type is specified, -flat is assumed.

-tablename name
Specifies the name of the database table to use Defaults to SUBSCRIBERS.

-username_column columnname
Specifies the name of the column where the user name will be stored. Defaults to
USERNAME.

-password_column columnname
Specifies the name of the column where the passwords will be stored. Defaults to
PASSWORD.

-checkattr_column columnname
Specifies the name of the column where the Check Items will be stored. Defaults to
CHECKATTR.

-replyattr_column columnname

Radiator RADIUS Server

327 of 397

radacct.cgi

Specifies the name of the column where the Reply Items will be stored. Defaults to
REPLYATTR.

-encryptedpassword
Handle and print all passwords as if they were encrypted. When printing passwords
with -l, the password is given with Encrypted-Password.
If neither -password or -dbm is specified, the input files are assumed to be Flat File
format. See Section 15.2 on page 358.
Examples:
Rebuild the entire SQL database from the /etc/passwd file, clearing old entries
first. Connects to an Oracle database sid called osc as user system and password manager. Uses the default table and column names
buildsql -z -dbsource dbi:Oracle:osc \
-dbusername system -dbauth manager \
-password /etc/passwd

Print out the attributes for user mikem in the same database:
buildsql dbsource dbi:Oracle:osc \

-dbusername system -dbauth manager -l mikem

Delete user mikem from the same database:

buildsql dbsource dbi:Oracle:osc \

-dbusername system -dbauth manager -d mikem

11.0 radacct.cgi
The CGI script radacct.cgi enables you to generate usage summaries from your
accounting log files or SQL database and to drill down to reveal user and session
details. This enables you to generate billing summaries, and to investigate the history of
user activities in order to resolve service problems. This script will work with any standard RADIUS accounting log file as produced by Radiator or many other RADIUS servers. It will work with compressed or uncompressed detail files. Find it in the goodies
directory of your distribution.
This script can also be configured so that it will show to your customers their own (and
only their own) usage details. This is called Secure mode
11.1 Installation
Radacct.cgi is not automatically installed during make install. In order to use
radacct.cgi, you must have a Web server installed that implements the Common
Gateway Interface (CGI). Most common web servers will suit, such as Apache, NCSA,
Netscape etc. Since radacct.cgi can display details for individual users, you should
normally only allow nominated staff to run it. You can prevent unwanted people from
running CGI scripts by configuring your web server to require a password.
328 of 397

Radiator RADIUS Server

radacct.cgi

1. If you are running on Unix, ensure the #! line at the top of radacct.cgi specifies the

name of your perl executable.

2. If you are using flat accounting files, edit the definition of $filename in the configu-

ration variable section near the top of the file so that it refers to your most recent
RADIUS detail file. (Hint: You might want to use a symbolic link that changes each
time a new detail file is created). If $filename has a .gz extension then $gzip_prog
will be used to uncompress it as it is read.
3. If you are using an SQL database instead of flat accounting files, uncomment and

edit DBSource, DBUsername and DBAuth in the configuration variable section near
the top of the file so it refers to the SQL database where your accounting details are
held.
4. Install radacct.cgi on a private internal web server or in a protected directory (i.e.

that requires a username and password to access it), so that only your administrators
can access it. Consult your Web server vendors documentation for details on how to
configure your web server for password protected directories. You should not allow
this script to be run by the general public unless you are using the Secure mode
described below.
Hint: You might want to set up a page of links to old detail files using the filename tag
with lines like:
<a href=localhost/cgi-bin/radacct.cgi?filename=/usr/local/
radius/detail199802>Jan 98</a>

This will allow your administrators to easily browse through old log files. Exactly how
you do this will depend on how you decide to organize your log files
Hint: If you are installing on IIS or some other web server on Windows or NT, you may
need to rename radacct.cgi to radacct.pl so your web server knows to run it with the Perl
interpreter.
11.2 Usage
The script will generate usage summaries and reports by scanning an accounting log file
or SQL database. You will normally use it by typing the URL into your Web browser,
something like this:
http://localhost/cgi-bin/radacct.cgi

When used with flat accounting files, the default file name of the log file it will use is /
var/log/radius/detail, but you can force it to use a different file by using the
filename tag:
http://localhost/cgi-bin/radacct.cgi?filename=xxx

where xxx is the full path name of the accounting log file you wish to summarize. If you
have several accounting log files, you might want to set up a special web page with a
link to radacct.cgi for each log file.

Radiator RADIUS Server

329 of 397

radacct.cgi

The default report is the All Users report (see Figure 18, All Users, on page 330). The
All Users report shows all the users in all sessions covered by the accounting log file.
For each user, it shows the total connection time, and the total bytes and packets in and
out. You can drill down to see all the sessions for a single user by clicking on the user
name.
11.3 Secure mode
You can configure radacct.cgi so that your customers can see their own usage (but not
the usage of other users). This means that you can set up a public web page to allow customers to review their recent usage. To install radacct.cgi in a secure mode:
1. Edit radacct.cgi, uncomment the line $secure = 1; in the configuration variable sec-

tion near the top of the file.

2. Edit the definition of $filename in the configuration variable section near the top of

the file so that it refers to your most recent RADIUS detail file. (Hint: You might
want to use a symbolic link that changes each time a new detail file is created).
3. If you are using an SQL database instead of flat accounting files, uncomment and

edit DBSource, DBUsername and DBAuth in the configuration variable section near
the top of the file so it refers to the SQL database where your accounting details are
held.
4. Install radacct.cgi on your web server in a protected directory (i.e. that requires a

username and password to access it).

5. Configure your web server so that only your customers can run the script. (Hint: You

might want to use the Pam Radius module for Apache to authenticate them using
radius. This has the added benefit of only allowing access to your current customers,
and they can use their normal radius password).
6. Test your setup to ensure that only registered customers can get access to the script,

and that they see only information about themselves.

FIGURE 18.

All Users

Total time for

each user
Click here to see
all sessions for a single
user

330 of 397

Radiator RADIUS Server

Total bytes
and packets
in and out
for each user

radacct.cgi

The All Sessions for User report (see Figure 19, All Sessions for User, on page 331)
shows selected detail for all the sessions covered by the accounting log file. The date
shown is the date and time that the session ended. The sessions are listed in the order
they occur in the accounting log file (i.e. by the time the session ended).

FIGURE 19.

All Sessions for User

Click here to see

all the details for
a single session

Selected details for

a single session, one
per line

The All Records for Session report (see Figure 20, All Records for Session, on
page 331) shows all the details for all the records for a single session. This format is
useful to see in exhaustive detail all the accounting records for a single session.

FIGURE 20.

All Records for Session

Date and time the event

occurred

All attributes and values

in the record

Radiator RADIUS Server

331 of 397

radwho.cgi

12.0 radwho.cgi
If you are using an external SessionDatabase such as DBM or SQL, you can use radwho.cgi to examine the details of the all the current sessions. This is useful for administrators to investigate current NAS usage, and possible Simultaneous-Use problems.
Radwho.cgi is a CGI script that will display all the current sessions in an external Session Database. See Section 5.11 on page 54, and Section 5.12 on page 58 for information about how to set up external Session Databases. Find it in the goodies directory of
your distribution.
12.1 Installation
Radwho.cgi is not automatically installed during make install. In order to use
radwho.cgi, you must have a Web server installed that implements the Common
Gateway Interface (CGI). Most common web servers will suit, such as Apache, NCSA,
Netscape etc. Since radwho.cgi can display details about individual users, you
should normally only allow nominated staff to run it. You can prevent unwanted people
from running CGI scripts by configuring your web server to require a password.
1. If you are running on Unix, ensure the #! line at the top of radwho.cgi specifies the

name of your perl executable.

2. Edit the definition of $filename in the configuration variable section near the top of

the file so that it refers to your external DBM Session Database file. Alternatively,
you can define DBSource, DBUsername and DBAuth so that session details come
from your external SQL Session Database.
3. If you are using a DBM Session Database file, ensure that the DBM database file(s)

are readable and writable by the user that your web server runs as. Often this will
mean that the file must be read/write anybody (i.e. mode 0666 on Unix).
4. Install radwho.cgi on a private internal web server or in a protected directory (i.e.

that requires a username and password to access it), so that only your administrators
can access it. Consult your Web server vendors documentation for details on how to
configure your web server for password protected directories. You should not allow
this script to be run by the general public.
5. If you have an external program that can terminate a user session by communicating

with your NAS, uncomment and edit $sessionTerminateProg. This will cause radwho to show a hotlink for each session, allowing you to terminate the session by
clicking on the web page.
Hint: If you are installing on IIS or some other web server on Windows or NT, you may
need to rename radwho.cgi to radwho.pl so your web server knows to run it with the
Perl interpreter.
12.2 Usage
The script shows details of each current session in a session database, one per line. You
will normally use it by typing the URL into your Web browser, something like this:
http://localhost/cgi-bin/radwho.cgi

332 of 397

Radiator RADIUS Server

Check and Reply items

You can change the sort order by clicking on the headers at the top of the table. You can
delete incorrect sessions by clicking on the delete session hotlink.

FIGURE 21.

Typical radwho listing

Click on the
headings to
change the
sort order

Click here to delete sessions

that are not correct

Details about each current session, one per line

13.0 Check and Reply items

Check items and reply items are used to authenticate users when an Access-Request
message is received. Different AuthBy modules use different methods to store the check
and reply items, but regardless of the module and how the user information is stored, all
such items are used in the same way.
The general form of a check and reply item is
attribute-name = value

Attribute-name must be an attribute defined in your dictionary. Value may be surrounded by double quotes (). Value must be surrounded by double quotes if it contains
a comma. If a value is surrounded by double quotes use backslash (\) to escape embedded double quotes. You can have binary characters in a quoted string by specifying the
octal code, preceded by a backslash. The spaces around the equals sign are optional.
Multiple check or reply items can be combined on a single line if they are separated by
commas. Thus the following are all legal:
User-Password = fred
User-Password="fred"
User-Password = "fred",Service-Type = Framed-User
Reply-Message="this, has commas, and quotes\" in it"

Radiator RADIUS Server

333 of 397

Check and Reply items

Tunnel-Server-Endpoint = "\000191.165.126.240 fr:20"

The RADIUS attributes in check and reply items must be a defined in your dictionary.
13.1 Check items
Check items is the name given to the RADIUS attributes in the Access-Request that
will be checked before the user will be granted an Access-Accept. All the check items
for a user will be checked before the user will be granted an Access-Accept. If any
check item is not satisfied the user will be denied access. You can have multiple check
items for the same attribute, and the check will only pass if all check items pass.
Most (but not all) check items permit exact match, alternation or regular expression
matches. See Section 13.1.45, Any other attribute defined in your dictionary, on
page 348 for more details on how these can be used.
These check items can also be used in the request selection expression in a <Handler>
clause (see Section 5.20 on page 70).
You will usually use this to limit the conditions under which a user will be permitted to
log on to your system. You will usually want to have a User-Password or EncryptedPassword, and you may also want to limit access via certain NASs, or at certain times.
You can use any RADIUS attribute as a check item, and there are also some special
attributes that are handled within Radiator in order to provide extra ways of controlling
user access.
Since different brands and models of NAS implement different subsets of the RADIUS
specification, it is not possible here to describe all the things you can configure in your
NAS with reply items. Refer to your NAS vendors documentation.
The following check items are supported by Radiator:
13.1.1 User-Password, Password

A (usually) plaintext password. Passes only if the given password matches that sent in
the Access-Request. If CHAP-Password attribute appears in the request then CHAP
authentication will be attempted. If MS-CHAP-Challenge and MS-CHAP-Response
attributes appears in the request then MSCHAP authentication will be attempted. CHAP
and MSCHAP authentication is only supported with plaintext or Rcrypt encrypted passwords. You may user either Password or User-Password as the attribute name, the effect
is the same.
Radiator also supports HTTP Digest password authentication with plaintext passwords.
Digest authentication is supported by some web servers (e.g. Apache) and some web
proxies (e.g. squid). You can add RADIUS Digest authentication to Apache with the
Apache-AuthenRadius-0.3 module, and a patch available from Open System Consultants.

334 of 397

Radiator RADIUS Server

Check and Reply items

User-Password can be in a number of formats, not necessarily in plaintext. Radiator

looks for some special format passwords and interprets them as special encryptions. The
following formats are supported, along with example versions of the password fred

Standard Unix crypt.This format is also compatible with Unix password encryption
as used in Netscape LDAP server. Passwords starting with a leading {crypt} or
{CRYPT} are interpreted as a standard Unix crypt password, using the native version of crypt() on your platform.
User-Password = {crypt}1xMKc0GIVUNbE

Linux MD5 password hashing. Passwords starting with $1$ are interpreted as
hashed with Linux MD5 password hashing.
User-Password = $1$cTpht$Obu9PLSMst1TDou.mN5bk0

Linux SHA256 and SHA512 crypt. Passwords starting with $5$ or $6$ are
interpreted as hashed with Linux SHA256 or SHA512 password hashing, respectively.
User-Password =
$5$cTpht$i4ihNcS7lC1orrwWu/IfHrhxdDIkjBu095szYO4AucD
User-Password = $6$cTpht$Z2pSYxleRWK8IrsynFzHcrnPlpUhA7N9AM/
8O8se885W45WHyJ2K6bXsygHI46.cjqgl2hucmKtX1shWTL1zU1

Linux Blowfish crypt. Passwords starting with $2a$, $2x$ or $2y$ are interpreted as hashed with Linux Blowfish password hashing. Support for these algorithms depends on the system crypt() implementation support. See the system
documentation on crypt() about caveats with these hashes.

Netscape SHA password hashing as used in Netscape LDAP server. Passwords starting with {SHA}, {SSHA}, {sha} or {ssha} are interpreted as being hashed with
Netscape SHA hashing. (Requires Digest-SHA version 5.0 or later, and also
Mime::Base64 from MIME-Base64-2.11.tar.gz).
User-Password = {SHA}MQF6ciZl5K/OWGlQ9ClEptMx2r8=
User-Password = {SSHA}k1qAjger6rE9fhCrig+QPZ/HTrJhYWE=

SHA-2 hashes SHA 256, 384 and 512. These are similar to {SHA} and {SSHA}
above. See goodies/sha.pl and goodies/ssha.pl for a utility to generate hashes.
User-Password =
{SHA256}0M/C5TGbgs3HGjOHPoJsk9fuETY/iskcT6Oiz80ihuU=
User-Password =
{SSHA256}abN9UTbhi3evQvdk7uYNML+UMZn8/BnWdxJUApQ0NzGkLQTd
User-Password ={SHA384}QoAkviNtBCtNyjN+yAkEEL6ChjtUVFKDTKHrIlx/
YqIHrDG7Tx2eJhbBPKAX0mo5
User-Password =
{SSHA384}DLZqetLxS6JPok1QcugKji0U8lxt6Zq7SYoGoK5JRVeeOqCuGHwxXf
1ZYGLg8pXqgms3jw==
User-Password = {SHA512}NWbDPDXFm6JYe6wqgVJs8z6gkoER7Z4WFqpD/
P+8P10H4FjICJjNKGCVt1h61e3TUR/ZQ/19d0Ox3tckJiAm8w==
User-Password =
{SSHA512}u+34y2JyCKoVRty0ADABlzhETpPv1HnShr2427qjsn7tgSoOaP8cHB
J95GT28ENlA7vySsjBVOMiuPqk2qgPvJOV4IM=

MD5 Hex digest. Passwords starting with {MD5} or {md5}. Note that all hex digits are required to be lower case.

Radiator RADIUS Server

335 of 397

Check and Reply items

User-Password = {MD5}570a90bfbf8c7eab5dc5d4e26832d5b1

MD5 with Mime, as used in some other LDAP servers

User-Password = {MD5}qP0OV/oViFka8YbFMWEWeg==

Rcrypt reversibly encrypted passwords. This reversible encryption format depends

on a secret key. Radiator includes a reusable code module (Radius::Rcrypt) with
encrypt and decrypt routines that you can call from third party programs. Rcrypt
passwords require that you define the RcryptKey attribute in the AuthBy clause. The
leading string can be {rcrypt} or {RCRYPT}.
User-Password = "{rcrypt}nYXkJKLrxm/e3RfU0aT7w4al"

A predigested hex MD5 signature of the concatenation of the username, a realm and
the correct password. This is only valid for Digest and SIP authentication. In this
example, the username is mikem, the realm is open.com.au and the correct password is fred.
User-Password = \
"{digest-md5-hex}884663db69c36190cf4c05c068a1a303

A MySQL hashed password, as produced by the MySQL password() function.

User-Password = "{mysql}0569ef75321b8fed"

An MD5 hashed password in the format used by old Netscape Mail Servers.
{NS-MTAMD5}b6b49e37d494a09bfde663033274bc83cd1bf318fa32c5866166a7edcb1
e1c87

A Django style password, as specified by

http://docs.djangoproject.com/en/dev/topics/auth/#passwords
User-Password =\
sha1$a1976$065f52b49153328da76e13c2b462b860a70eb78b
User-Password = md5$a1976$e67d1ca20e9c28321b86e34076cc48ab

A DEC Hashed Password as used by DEC VMS and maybe others. Contains the
algorithm type number, a salt and the hashed password, separated by vertical bars.
The valid algorithm numbers are 1 (PURDY), 2 (PURDY_V) or 3 (PURDY_S) The
hashed password depends on the user name as well as the algorithm and salt, so the
hashed passwords are not portable between users. In VMS, user names are by convention all uppercase, and passwords are case sensitive. In this example for username MIKEM, the algorithm type number is 3 (PURDY_S), the salt is 1234, and the
hashed password (fred) is 85ad61e72a41dec4.
User-Password = {dechpwd}3|1234|85ad61e72a41dec4

An NT Hashed Password, as used by Microsoft, Samba and others. This format is

compatible with Samba SMB passwords (either in a flat file or in LDAP). Such password hashes can be generated with the Samba mkntpwd program.
User-Password = {nthash}DCB8E94AC7D0AADC8A81D9C895ACE5F4

A password encrypted with the Microsoft SQL pwdencrypt() function. Passwords

encrypted with pwdencrypt() are case insensitive. Requires Digest::SHA module.
Note that the encrypted password produced by pwdencrypt() is a 46 octet binary
string. Radiator recognizes the encrypted password as either 46 octets of binary or

336 of 397

Radiator RADIUS Server

Check and Reply items

92 octets of ASCII Hex characters. You can use the MS SQL + string concatenation operator to prepend the {mssql} to the encrypted password, e.g.
select {mssql} + password, ..... from .....
User-Password =
{mssql}01003A54FC73501798169BEC84C05CA0D2FBB70009C2556313DA7959
C1A798ECD34514694A13D29ED57BE9CBE5DA

A flagged plaintext password.

User-Password = {clear}fred

A PBKDF2 (Password-Based Key Derivation Function 2) derived password. Radiator currently supports password derivation with Pseudo Random Function (PRF)
HMAC-SHA1 and the following password format (PRF:rounds:salt:hash). See
goodies/pbkdf2.pl for the format details. Requires Digest::HMAC_SHA1 and
MIME::Base64.
User-Password = {PBKDF2}HMACSHA1:9000:h9Pwh4tcu0w=:iN9vitCZ1mqBKEu21dlc0RW2tlc=

Custom format for CheckPasswordHook. See Section 5.21.50 on page 95 for information about CheckPasswordHook.
User-Password = {OSC-pw-hook}.......

Plaintext. Any other format is interpreted as a plain text password.

User-Password = fred
User-Password = password with spaces
13.1.2 Encrypted-Password

An encrypted password. Passes only if the password sent in the Access-Request

matches the given encrypted password. Most types of encrypted password only support
PAP, not CHAP, MSCHAP or MSCHAPV2 authentication. Passwords encrypted with
NT Hashed passwords can support PAP, MSCHAP and MSCHAPV2 authentication.
Encrypted-Password understands a number of encrypted formats: SHA, MD5, MD5
Mime, DEC Hashed passwords, NT Hashed passwords and standard Unix crypt. All the
following match the plaintext password fred:
Encrypted-Password = "{SHA}k1qAjger6rE9fhCrig+QPZ/HTrJhYWE="
Encrypted-Password = "{crypt}1xMKc0GIVUNbE"
# This next one is also crypt:
Encrypted-Password = "1xMKc0GIVUNbE"
Encrypted-Password = "$1$cTpht$Obu9PLSMst1TDou.mN5bk0"
Encrypted-Password = "1xMKc0GIVUNbE"
Encrypted-Password = {MD5}qP0OV/oViFka8YbFMWEWeg==
Encrypted-Password = {MD5}570a90bfbf8c7eab5dc5d4e26832d5b1
Encrypted-Password = {dechpwd}3|1234|85ad61e72a41dec4
Encrypted-Password = {nthash}DCB8E94AC7D0AADC8A81D9C895ACE5F4
# This next one is also nthash:
Encrypted-Password = DCB8E94AC7D0AADC8A81D9C895ACE5F4
Encrypted-Password =
{mssql}01003A54FC73501798169BEC84C05CA0D2FBB70009C2556313DA7959
C1A798ECD34514694A13D29ED57BE9CBE5DA

Radiator RADIUS Server

337 of 397

Check and Reply items

If there is no indication of the encryption type in an Encrypted-Password, Radiator will

assume it is a Unix crypt(3) password if it is 13 or 20 bytes long (20 bytes is the BSD/
OS DES extended format for crypt(3)), a binary NT hashed password if it is 16 bytes
long and a hex encoded NT hashed password if it is 32 bytes long.
# Unix Crypt:
Encrypted-Password = 1xMKc0GIVUNbE
# Hex encoded NT Hashed password
Encrypted-Password = DCB8E94AC7D0AADC8A81D9C895ACE5F4

When Radiator authenticates an MSCHAP or MSCHAP2 request, the default encrypted

password format is taken to be an MD4 hashed password, in the standard Windows NT
hashed password format (either hex encoded or binary).
13.1.3 Realm

Checks that the realm in the login name matches. The realm is the part following the @
in the user name. You can use either exact match, alternation, or a regular expression.
Realm = open.com.au
13.1.4 Expiration, ValidTo

Specifies the account expiry date with an optional time component. Passes only if the
current local date and time (according to the clock on the host where Radiator is running) is prior to the given date and time. If no time is given, it assumes midnight at the
beginning of the date given. The check items Expiration and ValidTo have identical
meaning. The following formats are supported:

Mmm dd yy(yy) (hh:mm:ss)

Mmm dd, yy(yy) (hh:mm:ss)

Note the optional comma

dd Mmm yy(yy) (hh:mm:ss)

yyyy-mm-dd (hh:mm:ss)
dd/mm/yy(yy) (hh:mm:ss)
dd.mm.yy (hh:mm:ss)

Some valid examples are:

Dec 30 1998
Dec 30, 2000
30 Dec 2000
Dec 30, 2000 11:30:00
30 Dec, 2000 09:32:00
2002-02-02 23:00:00
30/12/2002 01:00:00
30.12.2002

All the following Expiration check items are equivalent.

338 of 397

Radiator RADIUS Server

Check and Reply items

Expiration =
Expiration =
Expiration =
# Unix epoch
Expiration =

Jan 02 1999 23:30:00

1999-01-02 23:30:00
02/01/99 23:30:00
seconds (seconds since midnight, Jan 1 1970):
915280200

Hint: you can use Session-Timeout=until ValidTo or Session-Timeout=until Expiration as a reply item, which will set the session timeout to be the number of seconds
until the Expiration date and time. See Section 13.2.8 on page 351.
13.1.5 ValidFrom

Specifies a starting validity date. The same date formats as ValidTo are supported.
ValidFrom Jan 02 1999 23:30:00
13.1.6 Auth-Type

Auth-Type triggers special behaviour for authenticating the user. The possible values
are:

Reject. Any access request will always be rejected. This is useful for temporarily
disabling logins for a given user.

Accept. Forces acceptance, regardless of any following check items. Use with caution.

Reject:message. Same as for Reject, except that the message (which can be any
string) will be sent back to the user in a Reply-Message (provided the enclosing
Realm or Handler has RejectHasReason set). This may be useful for telling your
user why their login has been rejected.

Ignore. Any access request will always be ignored (i.e. no reply will be sent back to
the NAS). This is sometimes useful for triggering special behavior in cascaded
AuthBy clauses.

Anything else. Any other word specifies an Identifier in an AuthBy clause which
will used to authenticate the user. The name is matched with the name specified in
the Identifier parameter in an AuthBy clause. You can name any other type of
AuthBy module, be it SQL, RADIUS, UNIX etc. Specifying Auth-Type for a user
causes the authentication to be cascaded to another authentication module. You can
cascade authentications like this to any arbitrary depth.
The Auth-Type check item is most useful when you want to have check items and/or
reply items, but also want to authenticate with native Unix or NT passwords.
Checks all users using the authentication method that has the identifier System:
DEFAULT Auth-Type = System

If you want to temporarily disable logins for a single user:

username Auth-Type = Reject

This one rejects the user and tells them why:

username Auth-Type = Reject:you did not pay your bill

Radiator RADIUS Server

339 of 397

Check and Reply items

This will first authenticate with the Identifier System, and if they are also in the group
staticip, they will continue to be authenticated with the AuthBy clause that has the
Identifier statics:
DEFAULT Auth-Type=System, Group=staticip, Auth-Type=statics
13.1.7 Group

The meaning of Group depends on the type of module that is doing the authentication:
For UNIX and SYSTEM, it means whether the user is a member of the group as defined
by the group file (usually /etc/group). AuthBy SYSTEM supports both numeric and
symbolic group names. For AuthBy NT, it means whether the user is a member of the
Global or Local Group for the host where Radiator is running.
For AuthBy SQL, it will run and use the result of the GroupMembershipQuery if
defined. See GroupMembershipQuery on page 124.
For AuthBy LDAP2, it will require GroupSearchFilter and related options to be defined.
See GroupSearchFilter on page 161.
For other AuthBy modules, it has no meaning, and will always cause a rejection.
Group = wheel
13.1.8 GroupList

Works similarly to Group, but succeeds if the user is in any of the space separated group
names.
GroupList = wheel dialupusers nocstaff
13.1.9 Block-Logon-From

Specifies a time in the format 9:00 am or 15:22. Attempts to authenticate after this time
of day will fail. If Block-Logon-To is also specified for a later time of day, access is
blocked between those times. The time of day that is used is the local time on the host
where Radiator is running. Block-Logon-From is superseded by the Time check item
(see Section 13.1.13 on page 341) and will not be supported in the future.
13.1.10 Block-Logon-To

Specifies a time in the format 9:00 am or 15:22. Attempts to authenticate before this
time of day will fail. If Block-Logon-From is also specified for an earlier time of day,
access is blocked between those times. The time of day that is used is the local time on
the host where Radiator is running. Block-Logon-From is superseded by the Time check
item (see Section 13.1.13 on page 341) and will not be supported in the future.
Block-Logon-From = 9:00 am,
Block-Logon-To = 5.00 pm
13.1.11 Prefix

This check item checks for the presence of a certain prefix in the user name. If it is not
present the check item will fail. If it is present, it will be removed from the user name
and accepted. This is most useful in DEFAULT items to handle different variations of
the same users name, but with different reply attributes.

340 of 397

Radiator RADIUS Server

Check and Reply items

In this example, there might be a user mikem in the System authentication method.
These user entries will allow Pmikem to log in as a PPP user, and Smikem to login as a
Slip user:
DEFAULT

DEFAULT

Prefix = P, Auth-Type = System

Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-MTU = 1500
Prefix = S, Auth-Type = System
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-Compression = None

Hint: Prefix should appear before any Auth-Type check items.

13.1.12 Suffix

This check item is very similar to Prefix above, but checks for the presence of a certain
suffix in the user name. If it is not present the check item will fail. If it is present, it will
be removed from the user name and accepted. This is most useful in DEFAULT items to
handle different variations of the same users name, but with different reply attributes.
In this example, there might be a user mikem in the System authentication method.
These user entries will allow mikem.ppp to log in as a PPP user, and mikem.slip to login
as a Slip user:
DEFAULT

DEFAULT

Suffix = .ppp, Auth-Type = System

Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-MTU = 1500
Suffix = .slip, Auth-Type = System
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-Compression = None

Hint: Suffix should appear before any Auth-Type check items.

13.1.13 Time

This check item allows you to specify which times of day and which days of the week
the user is allowed to log on. The Time check is preferred to the Block-Logon-From and
Block-Logon-To check items, which will not be supported in the future.
The format consists of day specifiers followed by hours intervals. Multiple day specifications are permitted with multiple values separated by commas (if you use commas,
the entire check item must be enclosed with double quotes (). Authentication will be
permitted if the current local time on the Radiator server is within at least one of the
time intervals specified.

Radiator RADIUS Server

341 of 397

Check and Reply items

Day specifiers are Mo, Tu, We, Th, Fr, Sa, Su for the days of the week. Wk means MoFr and Al means any day. Hours intervals are specified as HHMM-HHMM. Typical
examples are:
Time = "MoTuWe0800-1400,Wk2200-0400"
Time = "Al1800-0600,Wk1000-1330"

Hint: you can use Session-Timeout=until Time as a reply item, which will set the session timeout to be the number of seconds until the end of the valid time period. See
Section 13.2.8 on page 351.
13.1.14 Simultaneous-Use

Specifies the maximum number of simultaneous sessions permitted for this user. Radiator keeps track of the number of current sessions for a user by counting the Accounting
Start and Stop requests received for that user. The value of this check item is either an
integer or the name of a file that contains an integer. You can use any of the special formatting characters in the file name. The file will be reread for each authentication: it is
not cached, so using a file name can have a slight impact on performance.
Hint: You can set the maximum number of simultaneous sessions for all the users in a
Realm or Handler by using the Handler MaxSessions parameter. In this case, the smaller
of MaxSessions and the users Simultaneous-Use will apply. See section DefaultSimultaneousUse on page 87 for setting default limit within an AuthBy.
Simultaneous-Use = 1
13.1.15 Connect-Rate

Specifies the maximum connection speed that this user is permitted to use. Uses the
Connect-Info attribute in the request to determine the speed the user is requesting. If
Connect-Info is not present in the request, looks for USR-Connect-Speed. Note: not all
NASs send Connect-Info or USR-Connect-Speed. in Access Requests. Check with your
NAS vendors documentation.
Connect-Rate = 28800
13.1.16 NAS-Address-Port-List

Specifies the name of a file that contains a list of permitted NAS address/port combinations. See Section 15.7 on page 361 for the Portlist file format. The filename can contain
any of the special file name characters. The contents of the file are read at most once,
and the port list is cached inside Radiator. If the user is not attempting to log in on one
of the permitted address/port combinations, they will be rejected.
NAS-Address-Port-List %D/portlist

Hint: You can limit users to a particular NAS, irrespective of the port by using the NASIP-Address check item, possibly with a regular expression.
Hint: You can limit users to a particular port or set of ports on all NASs by using the
NAS-Port check item, possibly with a regular expression.

342 of 397

Radiator RADIUS Server

Check and Reply items

13.1.17 Client-Id

Specifies the name of a Client that the request must come from. You can use an exact,
alternation or regular expression match. The match is against the Client name (i.e. the
word following Client in a <Client xxx> clause). Note that it is legal to use ClientId=DEFAULT to match requests that arrive through a <Client DEFAULT> clause.
<Client nas1.open.com.au>
....
</Client>
<Client nas2.open.com.au>
....
</Client>
<Client DEFAULT>
....
</Client>
# This user can only log in through nas2.open.com.au:
username1 Password=fred,Client-Id=nas2.open.com.au
# And this one only through NASs other than nas1 and nas2
username2 Password=jim,Client-Id=DEFAULT

Hint: When you use the Client-Id check item, it matches against the name or address in
the <Client xxxx> line, but not against any of the values listed in IdenticalClients.
13.1.18 Client-Identifier

Specifies the Identifier of a Client that the request must come from. You can use an
exact, alternation or regular expression match. The match is against the Client Identifier
(i.e. the value of the Identifier parameter in a <Client xxx> clause).
# Several NASs at pop1
<Client nas1.open.com.au>
IdenticalClients 1.1.1.1,1.1.1.2,1.1.1.3
Identifier pop1
...
</Client>
# Several NASs at pop2
<Client nas2.open.com.au>
IdenticalClients 2.1.1.1,2.1.1.2,2.1.1.3
Identifier pop2
....
</Client>
# This user can only log in at NASs in pop1
username1 Password=fred,Client-Identifier=pop1
# And this one only through NASs in pop2
username2 Password=jim,Client-Identifier=pop2
13.1.19 NasType

Specifies that the request must come from a Client with the specified NasType. You can
use an exact, alternation or regular expression match.
<Client xxx>
NasType Livingston

Radiator RADIUS Server

343 of 397

Check and Reply items

....
</Client>
<Client yyy>
NasType Ascend
....
</Client>
# This is can only log in through xxx, since it has a NasType
# of Livingston
username Password=fred,NasType=Livingston
13.1.20 Request-Type

Specifies that the type of the request must match the name given. You can use an exact,
alternation or regular expression match. Typical values of request types are:

Access-Request
Accounting-Request
Status-Server
This type of check item is mostly useful in Handlers for selecting special handling for
particular request types:
<Handler Request-Type=Access-Request>
# Accounting wont be handled here, only access requests
</Handler>
13.1.21 MS-Login-Hours

Specifies a map of permitted login hours per day. The value is an array of bits, one per
hour starting at 0000 Sun UTC, 24 bits per day, 7 days. It is not an ASCII array, but an
array of binary bytes. The format is exactly compatible with the LoginHours user attribute in Microsoft Active Directory, and can therefore be used when accessing Active
Directory via LDAP:
<AuthBy LDAP2>
Host
uniform
AuthDN cn=Administrator,cn=Users,dc=open,dc=com,dc=au
AuthPasswordadmin
BaseDN
ou=csx users,dc=open,dc=com,dc=au
ServerChecksPassword
UsernameAttr sAMAccountName
AuthAttrDef logonHours,MS-Login-Hours,check
</AuthBy>
13.1.22 Tagged Tunnel attributes and other tagged attributes

Radiator supports the IETF RFC 2868 standard tunnel attributes, and also permits you
to specify tagged tunnel attributes. Tags are a method of grouping attributes in the same
packet which refer to the same tunnel. A tag is an integer from 1 to 31 inclusive. In
Radiator you can specify a tag for a tunnel attribute by prefixing it with the tag number
and a colon (:). For example, here are 3 tunnel reply attributes, all with a tag of 1:
Tunnel-Type=1:L2F,
Tunnel-Client-Endpoint=1:xyz,
Tunnel-Password=1:1234

344 of 397

Radiator RADIUS Server

Check and Reply items

Note: If a tag and colon are not specified, the tag is assumed to be 0. A tag with value 0
in reply attributes may confuse some clients. We recommend using a non-0 value for
reply attributes.
Radiator reply attributes that support tags are:

Tunnel-Type
Tunnel-Medium-Type
Tunnel-Client-Endpoint
Tunnel-Server-Endpoint
Acct-Tunnel-Connection (also called Tunnel-ID)
Tunnel-Password
Tunnel-Private-Group-ID
Tunnel-Assignment-ID
Tunnel-Preference
Tunnel-Client-Auth-ID
Tunnel-Server-Auth-ID

13.1.23 EAPType

If the request is an EAP request, this check item matches the EAP type number. Available EAPType numbers include 4 (MD5-Challenge), 13 (TLS) and 26 (MSCHAP-V2).
Not useful for tunnelling EAP types, such as TTLS or PEAP.
13.1.24 EAPTypeName

If the request is an EAP request, this check item matches the EAP type name. Available
EAPType numbers include MD5, TLS and MSCHAP-V2. Not useful for tunnelling
EAP types, such as TTLS or PEAP.
13.1.25 TunnelledByTTLS

Specifies that the current request was tunnelled by EAP-TTLS.

13.1.26 TunnelledByPEAP

Specifies that the current request was tunnelled by PEAP.

13.1.27 TunnelledByFAST

Specifies that the current request was tunnelled by EAP-FAST.

13.1.28 RecvFromAddress

Specifies the IP address of the RADIUS, Radsec or TACACS+ client the request was
received from. IPv4 and IPv6 addresses are supported. You can use an exact, alternation
or regular expression match.
RecvFromAddress=203.63.154.29
RecvFromAddress=::1

Radiator RADIUS Server

345 of 397

Check and Reply items

Hint: This can be useful in Handler clauses to provide special handling of requests
received from a specific client:
<Handler RecvFromAddress=203.63.154.29>
....
<Handler>
13.1.29 RecvFromName

Specifies the DNS name of the RADIUS, Radsec or TACACS+ client the request was
received from. IPv4 and IPv6 addresses are supported. You can use an exact, alternation
or regular expression match.
# Exact match
RecvFromName=radserver.open.com.au
# Regular expression:
RecvFromName=/.*\.open\.com\.au/

Hint: This can be useful in Handler clauses to provide special handling of requests
received from a specific client:
<Handler RecvFromName=radsec.open.com.au>
....
<Handler>
13.1.30 Max-All-Session

Compares the total of all session times for the user against the given number. If it is
exceeded, the user will be rejected. Otherwise, the time left will be available for use
with Session-Timeout = until ValidTo to limit the remaining time for the user. Supported with AuthBy SQL when AcctTotalQuery is defined.
13.1.31 Max-Hourly-Session

Compares the total of all session times for the user from the beginning of the current
hour against the given number. If it is exceeded, the user will be rejected. Otherwise, the
time left will be available for use with Session-Timeout = until ValidTo to limit the
remaining time for the user. Supported with AuthBy SQL when AcctTotalQuery is
defined.
13.1.32 Max-Daily-Session

Compares the total of all session times for the user from the beginning of the current day
against the given number. If it is exceeded, the user will be rejected. Otherwise, the time
left will be available for use with Session-Timeout = until ValidTo to limit the remaining time for the user. Supported with AuthBy SQL when AcctTotalQuery is defined.
13.1.33 Max-Monthly-Session

Compares the total of all session times for the user from the beginning of the current
month against the given number. If it is exceeded, the user will be rejected. Otherwise,
the time left will be available for use with Session-Timeout = until ValidTo to limit the
remaining time for the user. Supported with AuthBy SQL when AcctTotalQuery is
defined.

346 of 397

Radiator RADIUS Server

Check and Reply items

13.1.34 Max-All-Octets

Compares the total of all traffic octets for the user against the given number. If it is
exceeded, the user will be rejected. Supported with AuthBy SQL when AcctTotalOctetsQuery is defined.
13.1.35 Max-All-Gigawords

Compares the total of all traffic for the user in GigaWords against the given number. If it
is exceeded, the user will be rejected. Supported with AuthBy SQL when AcctTotalGigawordsQuery is defined.
13.1.36 Max-Hourly-Octets

Compares the total of all traffic octets for the user from the beginning of the current
hour against the given number. If it is exceeded, the user will be rejected. Supported
with AuthBy SQL when AcctTotalOctetsSinceQuery is defined.
13.1.37 Max-Hourly-Gigawords

Compares the total of all traffic GigaWords for the user from the beginning of the current hour against the given number. If it is exceeded, the user will be rejected. Supported
with AuthBy SQL when AcctTotalGigawordsSinceQuery is defined.
13.1.38 Max-Daily-Octets

Compares the total of all traffic octets for the user from the beginning of the current day
against the given number. If it is exceeded, the user will be rejected. Supported with
AuthBy SQL when AcctTotalOctetsSinceQuery is defined.
13.1.39 Max-Daily-Gigawords

Compares the total of all traffic GigaWords for the user from the beginning of the current day against the given number. If it is exceeded, the user will be rejected. Supported
with AuthBy SQL when AcctTotalGigawordsSinceQuery is defined.
13.1.40 Max-Monthly-Octets

Compares the total of all traffic octets for the user from the beginning of the current
month against the given number. If it is exceeded, the user will be rejected. Supported
with AuthBy SQL when AcctTotalOctetsSinceQuery is defined.
13.1.41 Max-Monthly-Gigawords

Compares the total of all traffic GigaWords for the user from the beginning of the current month against the given number. If it is exceeded, the user will be rejected. Supported with AuthBy SQL when AcctTotalGigawordsSinceQuery is defined.
13.1.42 Variable names prefixed with GlobalVar:

The attribute to be compared is taken from a GlobalVar. GlobalVar variables can be set
from the command line, or with the DefineFormattedGlobalVar parameter. This can be
useful for activating different sets of users in multiple instances of Radiator.
# In the config file:
DefineFormattedGlobalVar system mysystem
# in a users file:
username Password=fred,GlobalVar:system=mysystem

Radiator RADIUS Server

347 of 397

Check and Reply items

13.1.43 Attributes prefixed with Reply:

You can specify a check item that checks an attribute in the currently constructed reply
(instead of the incoming request) by prefixing it with Reply:. This can be a convenient
way to set up user profiles or similar.
# This will set up one of 2 different user profiles, depending
# on the value of the pseudo-attribute Profile, which was set in
# and earlier AuthBy:
DEFAULT
Reply:Profile=premium
Session-Timeout=1000000
DEFAULT
Reply:Profile=cheap
Session-Timeout=1000
13.1.44 Attributes prefixed with DiaRequest:

You can specify a check item that checks a Diameter attribute in an incoming Diameter
request. This can be useful for choosing a Handler based on Diameter attributes, for
example:
<Handler DiaRequest:Auth-Application-Id=NASREQ>

or
<Handler DiaRequest:Disconnect-Cause=CREDIT_CONTROL>

13.1.45 Any other attribute defined in your dictionary

Checking of all other attributes passes only if the corresponding attribute exists in the
request and matches the value specified for the check item.
Radiator allows check items to be specified either as an exact match or as a Perl regular
expression (regexp). Radiator regards check items whose value is surrounded with
slashes (/) as a regular expression. Anything else is regarded as an exact match.

Exact match
The check item will pass only if there is an exact match. The comparison is case sensitive. Radiator will look for an exact match if the value to be matched is not surrounded
by slashes.
NAS-IP-Address = 203.63.200.5
Calling-Station-Id = 121284

Alternation
Specify multiple permitted values, separated by vertical bars (|). The check item will
pass if at least one of the permitted values is an exact match.
Calling-Station-Id = 121284|122882

Perl Regular expression

If the check item is surrounded by slashes (/), it is regarded as a Perl regular expression, and Perl is used to test whether the value of the attribute in the request matches the
regexp. The expression modifiers i (case insensitive) and x (ignore white space in the
pattern) are also permitted.

348 of 397

Radiator RADIUS Server

Check and Reply items

Perl regular expressions give you an enormous amount of power to control the conditions under which a user can log in. The first example below only matches if the user
logs in from the phone numbers 95980981, 95980982, 95980983 or 95980984. The second example only matches of they log into a port number with one digit (i.e. ports 1-9).
Calling-Station-Id = /9598098(1|2|3|4)/
NAS-Port = /^\d$/

Hint: Perl regexps are very powerful, but they also take some getting used to. You
should use them carefully, and test to make sure they really do what you want. Consult
some Perl manuals or a Perl guru for tips on writing regexps.
Hint: You can use the i and x pattern modifiers to get case-insensitive or extended
expressions like this, to match a Class attribute set to myclass without regard to case.
Class = /myclass/i

Hint: You can set up negative matches (i.e. that only match if the check is not equal
to some string) by using Perl negative lookahead assertions in a regexp. For example,
this check item will match all Service-Types except for Framed-User:
Service-Type = /^(?!Framed-User)/

Hint: You can match a string that contains unprintable characters by using a character
class negation. For example to match a user name that contains any character not in a-z,
A-Z or 0-9:
User-Name = /[^a-zA-Z0-9]/

13.2 Reply items

Reply items are RADIUS attributes that are used to configure the Terminal Server or
NAS when a user is successfully authenticated.
In order to determine what RADIUS attributes you need to configure your NAS, you
will need to consult your NAS vendors documentation. Some RADIUS attributes are
common to all NASs, and can be used with any NAS, while some are specific to a particular vendor or model of NAS. All reply items that you use must be defined in your
dictionary.
If the user is granted access, all the reply items will be returned in the Access-Accept
message to the NAS. This is usually used to configure the NAS in the correct way for
that user. Since different brands and models of NAS implement different subsets of the
radius specification, it is not possible here to describe all the things you can configure in
your NAS with reply items. Refer to your NAS vendors documentation. Here is a typical example to configure a NAS for a dialup PPP session:
Framed-Protocol = PPP,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

Radiator RADIUS Server

349 of 397

Check and Reply items

Some reply items are given special treatment:

13.2.1 Framed-Group

The reply attribute is used in conjunction with FramedGroupBaseAddress in order to

allocate an IP address for the user and return it in a Framed-IP-Address attribute. See
Section 5.8.8 on page 45 for more details
Framed-Group = 1
13.2.2 Ascend-Send-Secret

Causes the value to be encrypted with the Clients shared secret and returned to the Client.
Ascend-Send-Secret = mysecret
13.2.3 Tunnel-Password and other tagged attributes

Causes the password to be encrypted with the Clients shared secret according to RFC
2868. This is used by NASs for managing VPN tunnels. See Tagged Tunnel attributes
and other tagged attributes on page 344 for more information.
Tunnel-Password = 1:yourtunnelpassword
13.2.4 MS-CHAP-MPPE-Keys

Causes 2 session keys to be generated from the given string and then encrypted with the
Clients shared secret according to RFC 2548. This is used by Microsoft MS-CHAP tunnelling. If the value is exactly 24 octets long, it is assumed to already contain 2 session
keys, and will only be encrypted. Requires the Digest::MD4 perl module to be installed.
MS-CHAP-MPPE-Keys = mymppekey

Hint: If you are doing MS-CHAP authentication with plaintext passwords and your
NAS requires MS-CHAP-MPPE-Keys in the reply, then setting the AutoMPPEKeys
parameter in your AuthBy clause will force Radiator to automatically reply with MSCHAP-MPPE-Keys set from the plaintext password.
13.2.5 MS-MPPE-Send-Key

Causes the key to be encrypted with the Clients shared secret according to RFC 2548.
This is used by Microsoft MS-CHAP tunnelling.
MS-MPPE-Send-Key = mysendkey
13.2.6 MS-MPPE-Recv-Key

Causes the key to be encrypted with the Clients shared secret according to RFC 2548.
This is used by Microsoft MS-CHAP tunnelling.
MS-MPPE-Recv-Key = myrecvkey
13.2.7 Fall-Through

This attribute is not actually returned to the NAS. Its presence causes Radiator to continue looking for a match with the next DEFAULT user name.
Fall-Through = yes

350 of 397

Radiator RADIUS Server

Check and Reply items

13.2.8 Session-Timeout

If your NAS supports the Session-Timeout RADIUS attribute, this attribute can be used
in several ways.
As a simple number, it specifies the maximum time (in seconds) that the session is
allowed to run for:
Session-Timeout=6300

With the special form until nnnn, it will specify that the maximum time the session
will last is until the time of day specified. The time is the local time (according to the
host where Radiator is running). If the current time is after the time specified, the cutoff
time will be that time on the following day. For example to specify that the maximum
time for any session is up until 6am today:
Session-Timeout=until 0600

With the special form until Time, it will set the session timeout to be the number of
seconds until the end of the Time check item that permitted the user to log in. This
allows you to restrict users so they are only able to connect for the specified time period.
In the following example, user fred can log on between 1000 and 1700 each week day,
and they will be disconnected (by Session-Timeout) at 1700.
fred Password=jim, Time=Wk1000-1700
Session-Timeout=until Time

With the special form until Expiration or until ValidTo, it will set the session timeout
to be the number of seconds until the Expiration or ValidTo check item that permitted
the user to log in. This allows you to restrict users so they are only able to connect until
the end of their account validity period. In the following example, user fred can log on
up until January 1 2003 and they will be disconnected (by Session-Timeout) at midnight
of December 31 2002.
fred Password=jim, ValidTo=2003-01-01
Session-Timeout=until ValidTo
13.2.9 Exec-Program

This pseudo reply does not actually add any reply items to the reply. It runs the external
program given by the argument and waits for it to terminate. It is only run during reply
handling, which means that it is only run if the user successfully authenticates. This is a
handy way to run an external program when a user successfully logs in. The argument
may contain any special characters described in Special characters on page 20.
Hint: there is no guaranteed environment for the external program to run in, so you
should specify a program with its full path name.
Exec-Program=/usr/local/bin/sendgreeting %u

Hint: Radiator is blocked while the external program runs. On Unix, If you dont want
Radiator to wait for the program to terminate, use an & at the end of the line:
Exec-Program=/usr/local/bin/myslowprogram %u &

Radiator RADIUS Server

351 of 397

Check and Reply items

13.2.10 Ascend-Data-Filter, Ascend-Call-Filter

Radiator supports Ascend Binary Filters, which are given the type of abinary in the
dictionary. The standard dictionary contains the standard abinary attributes AscendData-Filter and Ascend-Call-Filter.
Ascend Binary Filters are binary encoded strings formatted according to http://support.baynetworks.com/library/tpubs/pdf/remote/bsac22/BSAC22RN.PDF. However
Radiator allows you to create filters in a symbolic, textual form. See you NAS documentation about the meaning, construction and use of Ascend Binary Filters with your
NAS.
Radiator supports three basic types of filter, each with slightly different syntax.
Caution: Radiator is very strict in its interpretation of filters. You cannot change the
order of filter elements, but you can omit the ones shown in square brackets [...]

IP Filter
The general syntax of an IP filter is:
ip dir action [dstip n.n.n.n/nn] [srcip n.n.n.n/nn] [proto [dstport cmp port]
[srcport cmp port] [est]]

dir is IN or OUT, Case insensitive

action is FORWARD or DROP. Case insensitive.
proto is a protocol name, such as ip, icmp, tcp etc. Lower case.
cmp is a port comparison operator like <, =, > or !=
port is a defined port name or integer port number, such as ftp-data, telnet, smtp
etc. Lower case.
Examples:
Ascend-Data-Filter = "ip in forward icmp"
Ascend-Data-Filter = "ip in forward dstip 1.2.3.4/24 tcp"
Ascend-Data-Filter = "ip in forward dstip 195.174.219.30 tcp
dstport=20",

Generic filter
The general syntax of a generic filter is:
generic dir action offset mask value [cmp] [more]

dir is IN or OUT, Case insensitive

action is FORWARD or DROP. Case insensitive.
offset is an integer offset.
cmp is == or !=
Examples:
Ascend-Data-Filter = "generic in forward 0 0 0"
Ascend-Data-Filter = generic in drop 0 ffff 0080 != more

IPX Filter

352 of 397

Radiator RADIUS Server

Rewriting user names

The general syntax for an IPX filter is:

ipx dir action [srcipxnet nnnn srcipxnode mmmmm [srcipxsoc cmp value]]

[dstipxnet nnnn dstipxnode mmmmm [dstipxsoc cmp value]]

dir is IN or OUT, Case insensitive
action is FORWARD or DROP. Case insensitive.
cmp is a comparison operator like <, =, > or !=
Examples:
Ascend-Call-Filter = ipx in forward srcipxnet 1 srcipxnode
0x11223344aabb srcipxsoc > abcd dstipxnet 5678 dstipxnode 0xaabbccddee00 dstipxsoc > 1234

13.2.11 Any other attribute defined in your dictionary

Any other attribute will be returned to the client in the reply message. All attributes
must be defined in your dictionary.
Framed-Protocol = PPP,
Framed-IP-Netmask = 255.255.255.0,
Framed-Routing = None,Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

Attributes that are defined as type ipaddr in the dictionary (e.g. Framed-IP-Address,
Framed-IP-Netmask etc.) can be specified either in dotted-quad notation (e.g. 1.2.3.4)
or as 4 bytes of binary. This is most useful if you want to keep addresses in a database in
binary format.
Attributes that are defined as type integer can be specified with either:

A RADIUS attribute value name

A decimal (i.e. base 10) integer
A hex (i.e. base 16) integer (with a leading 0x)
Therefore, the following reply items are all equivalent:
Framed-Protocol = PPP
Framed-Protocol = 1
Framed-Protocol = 0x01

14.0 Rewriting user names

You can change the User-Name attribute in each request by using the RewriteUsername
parameter. This allows you to apply separate rewriting rules to the User-Name:

In every request received by Radiator (see Section 5.7.25 on page 34). This occurs
prior to Client or Realm rewrites.

In every request handled by a Client clause (see Section 5.8.10 on page 46). This
occurs after global rewrites, but prior to Realm rewrites.

Radiator RADIUS Server

353 of 397

File formats

In every request handled by a Realm clause (see Section 5.20.1 on page 72). This
occurs after global and Client rewrites.

In every request handled by an <AuthBy GROUP> clause. This occurs before any of
the <AuthBy> clauses in the group are called.
The parameter is a Perl substitution regular expression that is applied to the User-Name
attribute in the request. If you dont know how to write Perl substitution regexps, you
should consult a Perl programmer. At Trace level 4, you can see the result of each separate rewrite for debugging purposes.
You can have any number of RewriteUsername parameters. The rewrites will be applied
to the user name in the same order that they appear in the configuration file.
This feature can be very useful in a variety of circumstances, for example

Strip the realm name from the user name. This is handy if your user database contains only the user names without the realm extension (i.e. fred instead of
[email protected])
# Strip realm
RewriteUsername s/^([^@]+).*/$1/

Convert Microsoft or other style user names from ___domain\user to the user@realm
form that Radiator uses
# Convert a MSN realm/user into user@realm
RewriteUsername
s/^(.*)\/(.*)/$2\@$1/

Force all user names to be lower case or upper case

# Translate all uppercase to lowercase
RewriteUsername
tr/A-Z/a-z/

15.0 File formats

15.1 Dictionary File
The dictionary file defines easy to read names for the attributes and values used in
RADIUS messages. It defines how RADIUS attribute numbers map to readable attribute names, and how RADIUS value numbers map to readable value names. The dictionary also defines the type of data that each attribute can hold.
The dictionary file is an ASCII text file. Each definition occupies one line. # Marks the
beginning of a comment. Comment and blank lines are ignored. The following line formats are understood:
15.1.1 ATTRIBUTE attrname attrnum type [flags]

This defines the name, RADIUS attribute number and type for an attribute.
ATTRIBUTE Service-Type 6 integer

ATTRIBUTE is the keyword that says this is an attribute definition. Service-Type is the
name of the attribute: the string that will be used as the attribute name when printing the

354 of 397

Radiator RADIUS Server

File formats

attribute and when setting attributes in the user database. 6 is the standard RADIUS
attribute number for this attribute (see RFC 2865), and integer is the data type for this
attribute. The supported data types are when you assign values to attributes in the user
database are:

string

An ASCII string of up to 253 bytes. Trailing NULs will be stripped.

integer

A decimal integer.

date

A date as an integer number of seconds since 00:00:00 UTC Jan 1 1970.

ipaddr

An IP address in the form aaa.bbb.ccc.ddd, or a 4 byte binary

string.

binary
abinary

data
boolean

Binary data.
Ascend filter, using the special Ascend filter definition syntax.
Radiator is very strict about the syntax. You must follow the
filter definition syntax exactly.
Binary data, same as binary.
Required only by some Nortel/Aptis CVX vendor-specific attributes. A
single byte attribute. Values of 0 or 1 are permitted.

integer8
A 8 bit unsigned value
integer16 A 16 bit unsigned value using network byte order
tagged-integer See Tagged Tunnel attributes and other tagged attributes on
page 344 for more about tagged attributes.

tagged-string
ipaddrv6

An IPv6 address in the form 2001:db8:148:100::31

ipv6prefix An IPv6 prefix in the form 2001:db8:148:100::/64

ifid

An IPv6 interface identifier in the form aaaa:bbbb:cccc:dddd

ipv4prefix An IPv4 prefix in the form 192.168.1.0/24

If you redefine an ATTRIBUTE by defining a new name for an previously defined attribute number, the new definition will silently replace the old one. The first will be a synonym for the second when used in a reply.
Attrnum may be in decimal, hex (prefixed by 0x) or octal (prefixed by 0).
ATTRIBUTE also supports optional flags to control whether the attribute is tagged or
requires encryption like this:
ATTRIBUTE Tunnel-Password 69 string has_tag,encrypt=2

The permitted flags are:

has_tag
Specifies that the encoded attribute is prefixed a tag octet. The value of the tag can
be specified in an attribute value with a leading tag number and a colon.

encrypt=n (n = 1, 2 or 3)

Radiator RADIUS Server

355 of 397

File formats

Specified that the attribute is to encrypted with the specified algorithm. The following algorithms are supported:
1 RADIUS User-Password encryption.
2 The SALT algorithm as described by RFC 2548.
3 Symmetric encoding and decoding as required for Ascend-Send-Secret.
15.1.2 VALUE attrname valuename value

This defines a symbolic name for an integer type attribute. When setting the value of an
integer attribute in a check or reply item, you can use the symbolic name instead of the
raw integer.
VALUE Service-Type Login-User 1

VALUE is a keyword that says this is a value definition. Service-Type means that this is
a definition of a value for the Service-Type attribute (which should be of type integer).
Login-User is the symbolic name for the value, and 1 is the value that Login-User translates to.
If you redefine a VALUE by defining a new name for a previously defined value number, the new definition will silently replace the old one. The first will be a synonym for
the second when used in a reply.
15.1.3 VENDORATTR vendornum attrname attrnum type [flags]

This defines a vendor-specific attribute. RADIUS defines a special attribute number 26

that can be used to hold any vendor defined data type. This allows NAS vendors to add
their own NAS-specific codes.
VENDORATTR 9 cisco-avpair 1 string

VENDORATTR is a keyword that says this is a vendor-specific attribute definition. 9 is

the SMI Network Management Private Enterprise Code of the vendor (Cisco in this
example). cisco-avpair is the symbolic name for the attribute, and string is the data type.
The same data types as for ATTRIBUTE are supported. Radiator supports both hex and
decimal attribute numbers in VENDORATTR.
After an integer VENDORATTR is defined, you can have VALUE definitions in the
same format as for other ATTRIBUTES.
If you redefine a VENDORATTR by defining a new name for an previously defined
vendor attribute number, the new definition will silently replace the old one.
Attrnum may be in decimal, hex (prefixed by 0x) or octal (prefixed by 0).
VENDORATTR also supports the same optional flags as described in ATTRIBUTE
attrname attrnum type [flags] on page 354.
15.1.4 VENDOR vendorname vendornumber

Specifies that the decimal number vendornumber can be used to refer to the Vendor
given by vendorname.

356 of 397

Radiator RADIUS Server

File formats

15.1.5 BEGIN-VENDOR vendorname

Specifies that all subsequent ATTRIBUTE keywords, until the next END-VENDOR are
to be interpreted as VENDORATTR definitions for the named vendor.
15.1.6 END-VENDOR

Terminates the previous BEGIN-VENDOR.

15.1.7 include filename

Includes the dictionary file specified by filename. Special characters are supported.
15.1.8 $INCLUDE filename

FreeRadius style include command, includes the dictionary file specified by filename.
Relative filenames are relative to the directory of the current dictionary. Special characters are not supported.
15.1.9 Available dictionaries

Radiator comes with a single main dictionary, plus an optional add-on dictionaries.

dictionary. The is the normal and default one. It merges attribute definitions
from several sources, and should be satisfactory for most configurations.

dictionary.ascend. This is an add-on dictionary that includes definitions for

some old-fashioned Ascend non-vendor-specific attributes that would normally conflict with newer attributes. If you need these old attributes, you can specify it as a
second dictionary

dictionary.* and goodies/dictionary.* These dictionary files have

more attributes for special cases. See the individual files for more details.
Under very unusual circumstances, you may wish to modify your dictionary. In any
case, your dictionary must have entries for at least the following attributes, which are
referred to by name in the radiusd code.

User-Name
User-Password
Encrypted-Password
Acct-Delay-Time
Any other attributes that are required by your AuthBy SQL configuration (if any) or
the check and reply items your user database.

Wherever possible, use the generic dictionary: it will work with the vast majority of
cases.If you are operating with NASs from only one vendor, choose the standard dictionary, or dictionary for that vendor. If you are operating in a mixed environment, use the
default dictionary. If that does not work for you, try concatenating the dictionaries for
the vendors you are using into one big dictionary. You are of course free to modify any
of the dictionaries to add attributes or values that are missing for your particular NAS.
If you need to add attributes, we recommend adding them to your own site-specific dictionary, and then add that dictionary to the list of dictionaries given by the DictionaryFile parameter in your configuration file.

Radiator RADIUS Server

357 of 397

File formats

Whichever dictionary you choose to use, you should place it in the directory where
radiusd expects to find it before starting radiusd. You should also be careful to
specify the same dictionary to radpwtst with the -dictionary argument if you
use it for testing.
15.2 Flat file user database
Flat file user databases are used to list all the legitimate users for the AuthBy FILE module. You can also use Flat file user databases as input to the builddbm and
buildsql utility to create a DBM user database. See the users file in the Radiator
distribution for an example.
Flat file user databases are ASCII text files containing zero or more user definitions.
Lines beginning with # are ignored. Each user definition is one or more lines. The first
line must start with the user name in the first column. Subsequent lines for the user must
begin with white space.
Usernames may be quoted with double quotes () if they contain white space. The user
name must be followed by some white space, followed by zero or more check items.
Each check item is in the form Attribute = Value, and it defines a RADIUS attribute
that will be checked in Access-Requests before the user will be authenticated. Multiple
check items are separated by commas (,). There must be no comma after the last check
item in the line. Values may optionally be surrounded by double quotes, which are
ignored. See Section 13.0 on page 333 for more details on check items.
The second and subsequent lines are reply items. Each line must commence with
white space. Each reply item is in the form Attribute = Value, and it defines a
RADIUS attribute that will be returned to the NAS if the authentication succeeds. Such
reply items will generally be used to configure the NAS for the user. Each reply item
must have a trailing comma (,) except the last item on the last line. Values may optionally be surrounded by double quotes, which are ignored.
In the example given in Figure 22 on page 359, if the user mikem is granted access,
their modem will be configured for Framed-Protocol of PPP, and IP Netmask of
255.255.255.0, Framed-Routing of None and a Framed-MTU of 1500.

358 of 397

Radiator RADIUS Server

File formats

FIGURE 22.

Typical user entry in a flat file user database

mikem

No comma
at end of
check items

Check items

User name

User-Password = "fred", Service-Type = Framed-User

Framed-Protocol = PPP, Framed-IP-Netmask = 255.255.255.0,

Framed-Routing = None, Framed-MTU = 1500
white space
Reply items

No comma at end of last

reply item

15.3 DBM user database

DBM user database file is in similar format to the DBM files supported by Merit and
other RADIUS servers. Entries are hashed by username, which is unique. Each user
entry consists of two strings separated by newline characters. The first line is a list of
comma separated Check items in the form Attribute = Value. The second line is a list
of comma separated Reply items in the form Attribute = Value. During authentication,
the check and reply items are used in exactly the same way as for a Flat file user database (see Section 13.0 on page 333).
Radiator will choose the best format of DBM file available to you, depending on
which DBM modules are installed on your machine. (Hint: You can force it to choose a
particular format by using the DBType parameter, and by using the -t flag with
builddbm)
You can convert a flat file user database directly into a DBM user database with
builddbm utility, and you can also use builddbm to print the attributes for a particular user. You can convert a DBM user database into an SQL database with the
buildsql utility.
A DBM database can have multiple DEFAULT users. During authentication, if no user
name is found in the DBM database, the DEFAULT users will be tried in the order that
they appeared in the input file, until a match is found. Technical Note: when the
DBM file is built from a flat file, the first DEFAULT user encountered is added to the
DBM file with the name DEFAULT. The seconds and subsequent DEFAULT entries are
added as DEFAULT1, DEFAULT2 etc. Therefore the uniqueness and order of
DEFAULT users in the database is guaranteed.
15.4 Unix password file
A Unix password file as understood by the AuthBy UNIX module is an ASCII file consisting of one line per user. There are at least 2 colon (:) separated fields per line. The
first field is the user name, and the second is the crypt(3) encrypted password. The third
and subsequent fields (if they are present) are ignored.

Radiator RADIUS Server

359 of 397

File formats

It will be recognized that this description fits the standard Unix password file format,
and Radiator will work with /etc/password on Unix implementations that do not
use a password shadow file. It will work with /etc/shadow on Unix implementations that do use a password shadow file (Radiator will need to run as root to get read
access to /etc/shadow).
15.5 Accounting log file
The accounting log file is used to store the details of every Accounting-Request
received for a Realm if the AcctLogFileName parameter is defined for the Realm. It is
an ASCII text file with each entry occupying one or more lines and followed by a blank
line. The log file format is identical to the format used by Livingston and other
RADIUS servers. The first line gives the date and time the request was received by the
server. The subsequent lines give the values for every attribute in the request. Every
Accounting-Request, regardless of Acct-Status-Type is stored in the log file.

Date and time received

Mon Feb 9 22:07:20 1998

User-Name = mikem
Service-Type = Framed-User
NAS-IP-Address = 203.63.154.1
NAS-Port = 1234
Acct-Status-Type = Stop
Acct-Delay-Time = 0
Acct-Session-Time = 1000
Acct-Input-Octets = 20000
Acct-Output-Octets = 30000
Acct-Session-Id = 00001234
String type attributes are quoted
Every attribute in the request

FIGURE 23.

Typical accounting log file entry

15.6 Password log file

The Password log file is useful for your help desk to diagnose user logon problems. It is
only written if you define PasswordLogFileName for a Realm. It is an ASCII text file
containing the results of password checks, one check per line. Each line contains 5
colon (:) separated fields:
time:seconds:user:submitted_password:correct_password:result

The time is the full date time string, seconds is the number of seconds since January 1
1970 (Unix epoch). Result is the word PASS or FAIL. For example:
Mon Jun 29 12:24:21 1999:899087061:mikem:fredd:fred:FAIL
Mon Jun 29 12:24:38 1999:899087078:mikem:fred:fred:PASS

360 of 397

Radiator RADIUS Server

High availability for radiusd

Mon Jun 29 12:38:53 1999:899087933:mikem:fred:fred:PASS

The file is opened, written and closed for each entry, so it can be safely rotated at any
time.
15.7 Portlist file
A portlist file contains a list of permitted NAS address/port combinations that are permitted for a user or group of users. It is used by the NAS-Address-Port-List check item.
It is an ASCII file, with two white space separated fields. The first field is the NAS
address (either as a DNS name or IP address). The second field contains the lower and
upper permitted port numbers in the format lowport-highport. Blank lines and lines
starting with hash (#) are ignored. You can have any number of entries for each NAS,
and any number of NASs.
Technical Note: iPASS roaming users do not get their real NAS Address sent to Radiator. Radiator considers these to be address 0.0.0.0 for the purposes of NAS-AddressPort-List.
# Users can log into ports 1-10 and 21-30 inclusive
# on 10.1.1.1 or into ports 100 to 115 inclusive on
# 10.1.1.2, or into ports 16 to 20 inclusive on
# mynas.___domain.com
10.1.1.1 1-10
10.1.1.1 21-30
10.1.1.2 100-115
mynas.___domain.com 16-20
# For iPASS roaming:
0.0.0.0 0-1000

16.0 High availability for radiusd

In a typical ISP, your RADIUS server is an important part of your customer service, and
it is important that it is available all the time. Although the Radiator RADIUS server is
very reliable, it is possible that it might be accidentally killed, or that a system problem
could cause it to exit. You should make provisions for Radiator to be started automatically at system boot time, and make sure it is available all the time.
In a Unix environment, there are 3 ways you can achieve this. The preferred method is
to start and restart radiusd with restartWrapper, but you may prefer to start and restart it
with inetd(1) or init. On Windows, you can run Radiator as a system service.
16.1 Using restartWrapper
In a Unix environment, you can arrange for radiusd (or any other program, for that
matter) to be restarted automatically if it exits unexpectedly by using the restartWrapper script. restartWrapper is included in the goodies directory of the
Radiator distribution. It is not installed automatically, so if you want to use it, you will
probably want to copy it to your local binaries directory. Radiator must be run in the
foreground with the Foreground parameter or the -foreground argument (see

Radiator RADIUS Server

361 of 397

High availability for radiusd

Section 5.7.1 on page 28).

restartWrapper never terminates, so you will probably want to run it in the background
with an ampersand (&), especially if you are calling it from a system boot script.
You will probably want to put a call to restartWrapper in your Unix system boot script
so that radiusd is started automatically at boot time by restartWrapper. This will usually involve modifying /etc/rc.local or adding a new script to /etc/rc2.d, depending on
what type of Unix you are running. See your system documentation for more details
about system start-up scripts.
The arguments are:
restartWrapper [-h] [-delay n] [-mail address]
[-min_interval n (default: 0)]
[-sendmail path-to-sendmail]
[-syslog facility.level (default: user.err)]
[-logger path-to-logger (default: /usr/bin/logger)]
command to run

-h
Print usage help message.

-delay n
Number of seconds to wait before restarting the command. Defaults to 10 seconds.

-min_interval n
Minimum interval in seconds between successive restart. Defaults to 0 seconds.

-mail address
The email address to send a message to when the command exits. By default, no
email is sent.

-sendmail path-to-sendmail
Specifies an alternate path to the sendmail program which will be used to send email
if the -mail argument is specified. Defaults to /usr/lib/sendmail.

-syslog facility.level
Specifies an optional syslog facility and level to be used to log messages using syslog. If this is not specified, syslog will not be used to log messages.

-logger path-to-logger
Specifies the syslog logger program which will be used to log syslog messages.
Defaults to /usr/bin/logger.

command to run
This is the complete command that is to be run, including arguments if any. You
should enclose the entire command in double quotes, especially if the command contains arguments that might be mistaken for arguments to restartWrapper. You will
probably want to specify the full path to the command.
Examples:

362 of 397

Radiator RADIUS Server

High availability for radiusd

Run radiusd with a specified config file. If it stops, send email to [email protected]
and wait 2 seconds before restarting it.
restartWrapper -mail [email protected] -delay 2 \
/bin/radiusd -config_file /etc/radius.cfg \
-foreground &

Hint: make sure that Radiator is running in foreground mode, either with -foreground
in the command line arguments, or with Foreground the configuration file
Hint: if you are starting restartWrapper from inside a Unix startup script, you will need
to follow the command line with an ampersand (&), otherwise the unix startup script
will never complete.
16.2 Using init
On Unix systems that support it, you can start and restart Radiator automatically with
init(1). Add something like this to /etc/inittab:
ra:2345:respawn:/usr/bin/radiusd -config_file \
/etc/raddb/radius.cfg -foreground

Hint: make sure that Radiator is running in foreground mode, either with -foreground
in the command line arguments, or with Foreground in the configuration file.
16.3 Using inetd
If you dont wish to use restartWrapper or init, you can instead arrange for the
Unix inetd(1) superserver to start radiusd the first time it is required (and to restart
it if it stops unexpectedly). In order to do this, you must add a new line to the inetd
configuration file (usually /etc/inetd.conf). You must also ensure that the radius
port number you wish to use is configured into the /etc/services file. You must
also ensure that Radiator is configured to run in the foreground with the Foreground
parameter or the -foreground argument (see Section 5.7.1 on page 28).
The inetd line you add will look something like this (the line has been wrapped due to
its length in this example):
# Start Radiator on demand
radius dgram udp wait root /bin/radiusd radiusd
-config_file /etc/radius.cfg
-foreground

After changing /etc/inetd.conf, you will need to tell inetd to reread its configuration file
by sending it a HUP signal with something like
kill -HUP pid-of-inetd

Whenever a radius request is received and radiusd is not already running, inetd
will automatically start radiusd. If radiusd stops some time later, inetd will
restart it when the next request arrives. For more details on using and configuring inetd,
consult your Unix vendors documentation.

Radiator RADIUS Server

363 of 397

High availability for radiusd

Hint: make sure that Radiator is running in foreground mode, either with -foreground
in the command line arguments, or with Foreground the configuration file
16.4 Unix SYSV startup script
The Radiator distribution contains a Unix/Linux SYSV compatible startup script in
goodies/linux-radiator.init.
To use this script to start and stop Radiator by hand or automatically at boot time, on
Linux as root:
cp goodies/linux-radiator.init /etc/init.d/radiator
chmod 755 /etc/init.d/radiator
chkconfig -add radiator

This startup script responds to the following commands:

/etc/init.d/radiator start
Starts the Radiator server running in the background as a service. This is the default
command which will be used to start Radiator automatically at boot time when the
startup script is automatically run.

/etc/init.d/radiator stop
Stop the Radiator server.

/etc/init.d/radiator restart
Stop then restart the Radiator server.

/etc/init.d/radiator reload
Forces the Radiator server to reread its configuration file. It does this by sending a
HUP signal to the server.

/etc/init.d/radiator status
Prints the current status of the Radiator server process.

/etc/init.d/radiator traceup
Increases the current Radiator server Trace level by one. It does this by sending a
USR1 signal to the server.

/etc/init.d/radiator tracedown
Decreases the current Radiator server Trace level by one. It does this by sending a
USR2 signal to the server.
16.5 As a System Service on Windows with ActivePerl or Strawberry Perl
On Windows XP/Vista/7/8 and Server 2003/2008/2012 etc, you can arrange for Radiator to run as a Windows Service. It will then be automatically started at boot time, and
you can start, stop and pause it with the Administrative Tools->Services dialogue. This
is the preferred way to get Radiator to run automatically every time a Windows server is
started.
1. Install ActivePerl from ActiveState or Strawberry Perl making sure you install the

appropriate version for your platform (32 or 64 bit).

2. Start a command window.

364 of 397

Radiator RADIUS Server

Adding custom AuthBy modules

3. In the command window, use the Perl PPM package manager to install the Perl

Win32::Daemon module with this command

ppm install Win32::Daemon
4. Download and install Radiator using the Windows executable. This will install the

Radiator software to c:\Radiator\Radiator-<version>. (You can also use the ZIP or

tgz packages if you prefer, and have the appropriate unpacking tools, ZIP or tar).
5. In the command window, change directories to the place where Radiator has been

installed (typically c:\Radiator\Radiator-<version>) and install the Radiator Perl

modules. This will copy the required Radiator perl modules to the Perl libraries. It
will also create a minimal configuration in C:\Program Files\Radiator\radius.cfg
cd c:\Radiator\Radiator-4.7
perl Makefile.PL install
6. In the command window, create the Radiator service with
perl c:\perl\bin\radiusd -install

This will install Radiator as a Windows Service so that it uses the default configuration file in C:\Program Files\Radiator\radius.cfg
7. Click on Start->Setting->Control Panel->Administrative Tools->Services. You

should see Radiator Radius Server as one of the available services. Using the Services window you can start, stop, pause and disable the Radiator service. Start the
Service.
8. Test that the Service is running correctly by sending a test request with

perl c:\perl\bin\radpwtst -user mikem -password fred

9. Edit and test the configuration in C:\Program Files\Radiator\radius.cfg. You should

stop and restart the Radiator service using the Services control panel after making
any change to the configuration file in order for the change to take effect.
10. Next time the computer reboots, the Radiator Service will start automatically.

Hint: You can only expect Radiator to run successfully as a service if it will run properly using the same command line that you enter in item 4 above, but without the -install
argument. Try running your command line from the root directory of the C: drive. Since
a Windows service has no current directory or Current drive, you must be very sure
that your radiator configuration file contains no relative file names. Every file name
mentioned must be a fully qualified path name, including the drive name, e.g.:
DbDir

C:\Program Files\Radiator

Hint: A Windows Service usually runs as the System User, not as a logged in user. This
means that to run as a Service, you must configure your Radiator so it does not rely on
remote shares etc. that may not be accessible to the System User. This generally means
that all Radiator configuration files, the Radiator program etc. must be on the local disk.

17.0 Adding custom AuthBy modules

Radiator provides an easy way of plugging in and integrating additional custom AuthBy
modules. This allows you to use Radiator to authenticate from and store accounting
information to other databases and storage types not currently supported by Radiator.

Radiator RADIUS Server

365 of 397

Adding custom AuthBy modules

You will need to be a competent Perl programmer in order to implement custom AuthBy
modules.
Custom modules are usually written in Perl. They are automatically loaded when a
matching <AuthBy ...> clause is read in the configuration file. Details on how to load,
configure and implement a custom AuthBy module are described in this section.
There is a simple AuthBy module called AuthTEST.pm included in the RADIUS directory. It implements the <AuthBy TEST> clause, and would be a good starting point if
you want to write your own custom AuthBy module. You should copy it to a new name
and modify the copy to suit your needs.
17.1 Loading and configuring
When radiusd sees an <AuthBy XYZ> clause while parsing a Realm or Handler, it will
load the file Radius/AuthXYZ.pm with a Perl require. AuthXYZ.pm is expected to be a
Perl package that implements the class Radius::AuthXYZ. Realm.pm will then
instantiate a new Radius::AuthXYZ by calling the constructor with
Radius::AuthXYZ->new($file). The constructor is expected to create an
instance of Radius::AuthXYZ that can handle all the requests for that type of
authentication.
The constructor is passed a filehandle $file, which is the configuration file being currently read. The constructor is expected to configure its instance from lines read from
the configuration file up until it sees a </AuthBy> line. This is made very easy by the
Radius::Configurable class, which your AuthBy module should inherit from.
If the Radius::AuthXYZ constructor fails, it is expected to return undef.
17.2 Handling Requests
After construction and initialization, your instance will be called upon to handle
requests that are sent to it. For each request received, the Handler.pm module will call
($result, $reason) = Radius::AuthXYZ->handle_request($p, $rp), where
$p is a reference to the Radius::Radius packet received from the client, and $rp is an
empty reply packet, ready for you to fill. Client.pm and Handler.pm will filter out duplicate requests, requests from unknown clients and requests with bad authenticators, so
your handle_request will only be called for new, good requests from known clients. The
contents of the request will have been unpacked into the Radius::Radius instance passed
in as $p, so you can immediately start examining attributes and doing things.
handle_request returns an array. The first element is a result code, and the second is an optional reason message.
The result code from handle_request will indicate whether Handler.pm should
automatically send the reply to the original requester:

If handle_request returns $main::ACCEPT, Handler.pm will send back $rp as

an accept message appropriate to the type of request received (i.e. it will turn $rp
into an Access-Accept if the original request was an Access-Request). In the case of

366 of 397

Radiator RADIUS Server

Adding custom AuthBy modules

Accounting-Request, this is the only result code that will cause a reply to be sent
back.

If handle_request returns $main::REJECT, Handler.pm will send back $rp as a

reject message appropriate to the type of request received (i.e. it will turn $rp into an
Access-Reject if the original request was an Access-Request). In this case the reason message should be supplied.

If handle_request returns $main::CHALLENGE, Handler.pm will send back

$rp as a Access-Challenge message.

If handle_request returns $main::IGNORE, Handler.pm will not send any

reply back to the originating client. You should only use this if the request is to be
completely ignored, or if your module undertakes to send its own reply some time in
the future. If the Handler or Realm has more than one AuthBy handler module specified, it will continue calling handlers in the order in which they were specified until
one returns something other than $main::IGNORE (you can change this behavior
with AuthByPolicy, see Section 5.20.16 on page 77).
Your handle_request function may want to use utility functions in Radius::Radius (see
Radius.pm) to examine attributes in the incoming request, and to construct replies.
There are some convenience routines in Client.pm for packing and sending replies to the
original requester, such as
$p->{Client}->replyTo($rp, $p);

If your handler cannot successfully handle the request, perhaps due to some unforeseen
event, software failure, system unavailability etc., it is common to not reply at all to the
original request. This will usually force the original NAS to retransmit to another server
as a fallback. You can do this by returning $main::IGNORE from handle_request.
17.3 AuthGeneric
This is a generic authentication module superclass. It implements behaviour that will be
required in most authentication modules, and therefore most modules should inherit
from it. Most simple authentication can be handled merely by overriding the findUser()
method, which is expected to find and return a User object given a user name. The
AuthGeneric::handle_request handles all the cascading of DEFAULT users, checking of
check items, assembling replies etc. All you have to do is find the user in your database
and return it in findUser().
AuthGeneric only responds to Access-Request messages. Accounting-Requests are
accepted but ignored (i.e. it does nothing with them). If you want to do something with
accounting messages (other than what Realm.pm does, such as logging to the accounting log file or wtmp file), you will probably want to override handle_request, pass
Access-Request messages to $self->SUPER::handle_request(), and process Accounting-Request messages yourself.
If your handler needs to fork so it can do a slow authentication or accounting task,
you can call AuthGeneric::handlerFork, which will arrange for the handler to
fork(2), and also arrange for the child to exit after handling is complete.

Radiator RADIUS Server

367 of 397

Adding custom AuthBy modules

AuthGeneric has a number of other methods that you can override for specific functions
like:

log($p, $s) Logs a message that originated in that class. $p is a message priority (see Log.pm). $s is a message. The base class behavior is to log to the all the logging systems configured into Radiator by calling main::log($p, $s)
17.4 Step-by-step
Assuming you want to create a custom AuthBy module called XYZ, these are the basic
steps:

Figure out what parameters your new module needs from the Radiator configuration
file to configure its behavior.

Copy AuthTEST.pm to AuthXYZ.pm

Replace all instances of TEST in AuthXYZ.pm with XYZ.
Implement the keyword function so it parses the parameters that your new module
needs.

If your module needs any sub-objects, implement the object function to parse out
any sub-objects (see example code in Radius::Realm->object)

Implement the handle_request function. You may wish to handle Access-Requests

and Accounting-Requests differently.

Add a test realm to the configuration file with something like:

<Realm xxxx>
RealmParameter1 ....
<AuthBy XYZ>
AuthByParameter1 ....
.....
</AuthBy>
</Realm>

Restart or SIGHUP Radiator.

Test your new module by sending requests to the server with the radpwtst utility.
Install your new module with make install.
If your authentication method is simple and synchronous, your class only has to override the following methods in AuthGeneric:

new Create a new instance by calling $class->SUPER::new($file);

keyword Recognize any class specific parameter keywords from the configuration
file and remember them.

findUser Construct and return a User object if the named user can be found in
your database.
17.5 Class Hierarchy
This section is only of interest to developers who plan to build new Radiator classes. It
shows the class inheritance hierarchy of all the classes provided with Radiator.

368 of 397

Radiator RADIUS Server

Compatibility with Livingston and other servers

FIGURE 24.

Radiator Class inheritance hierarchy

AuthSQLRADIUS

AuthPLATYPUS,
AuthRODOPI,
AuthEMERALD

AuthLDAPSDK
AuthLDAP2
AuthLDAP

AuthUNIX
AuthDBFILE

AuthSYSTEM
AuthOPIE AuthIPASS
AuthGROUP
AuthNT
AuthPAM

AuthRADIUS
AuthFILE

AuthSQL

SessDBM
SessNULL
SessSQL
SessINTERNAL

ClientListSQL

AuthINTERNAL
AuthACE
AuthDYNADDRESS
AuthTACACSPLUS
AuthLSA
AuthTEST
AuthDIGIPASS
AuthEXTERNAL
AuthNISPLUS
AuthCDB

ClientListLDAP
AddressAllocatorDHCP
AddressAllocatorSQL

Ldap

LogEMERALD
LogSQL LogSYSLOG

SqlDb

AuthLDAPRADIUS

AuthVOLUMEBALANCE
AuthROUNDROBIN
AuthLOADBALANCE

AuthLogSYSLOG
AuthLogSQL
AuthLogFILE

LogFILE

LogGeneric ServerConfig

SessGeneric

AddressAllocatorGeneric
Realm

StatsLogGeneric

AuthLogGeneric
AuthGeneric Client Handler

Configurable

User

Radius

Context
AttrVal

RDict

Select

SNMPAgent
Log

RadpwtstGui
Mib
Monitor

18.0 Compatibility with Livingston and other servers

The flexibility of Radiator allows you to easily emulate the behaviour of Livingston and
other similar radius servers. These radius servers use special entries in the user database

Radiator RADIUS Server

369 of 397

Execution sequence and Hook processing

file to control the behaviour of the server. Radiator, in contrast, uses the configuration
file for controlling the server. Nevertheless, Radiator allows you to use the Group and
Auth-Type check items that are sometimes used with Livingston.
There is an example configuration file in goodies/livingCompat.cfg in the Radiator distribution. That configuration file makes Radiator behave in the same way as a Livingston or Cistron radius server. If you use Auth-Type = System in a user entry in the
user file, Radiator will consult the UNIX password file /etc/password to authenticate the
user. Radiator will also behave in the same way with respect to DEFAULT users. You
can have multiple DEFAULT users in a user database. During authentication, if there is
no username entry found for the user, the DEFAULT entries are checked in the order in
which they appear in the file (this is the case with both AuthBy FILE and AuthBy
DBM). The DEFAULT entries will continue to be checked in order until one is found
where all the check items match and where the Fall-Through reply item is not set to
Yes.
Open System Consultants can assist with converting database dumps from other commercial RADIUS servers to standard Livingston format users file, including:

Cisco ACS database dump files

Funk RIF database export files
Contact [email protected] for more details.

19.0 Execution sequence and Hook processing

This section describes when and how hooks are processed.
Radiator supports perl Hooks in many places in the configuration file. A hook is a
piece of perl code (in fact a perl subroutine) that will be run by Radiator at specified
times. This allows the configurer to add custom code to handle unique or special processing requirements at run-time.
Hooks are specified verbatim, or by file name in the Radiator configuration file.
Hooks are parsed by perl at startup time, when the Radiator configuration file is read or
re-read. Any syntax or compile-time errors in the hook will be reported at that time.
Hooks are run at their specified times inside a perl eval. This means that run-time
errors, or a perl die() command will result in a ERROR level message logged by Radiator.
Each hook is passed a set of run-time arguments, which depend on the type of hook
being called. Arguments might include, for example, a reference to the request currently
being processed, allowing the custom code to inspect and depend on the contents of the
request. Hook arguments are documented separately for each hook above.
The code for a hook may be placed verbatim in the configuration file:
UserPasswordHook sub {return $_[1]->{GN}}

370 of 397

Radiator RADIUS Server

Execution sequence and Hook processing

and it may extend over several lines, with the use of the backslash line ending:
ConnectionHook sub {$_[1]->func(-access_mode => read_write,\
-isolation_level => read_committed,\dd
-lock_resolution => wait,\
ib_set_tx_param)}

or it may be placed in a separate external file that is named in the configuration file:
AcctHook file:"%d/hooks/sqlradacct.pl"

and in the named file:

# Contents of file sqlradacct.pl:
sub
{
use DBI;
my ($p, $rp, $handled, $reason) = @_;
........
}

Hint: An external file can define several perl functions that can be called from other
functions in that file, or by another hook.
The standard hooks are:

StartupHook($restarted)
PreClientHook(\$request)
ClientHook(\$request)
PreHandlerHook(\$request)
PreProcessingHook(\$request, \$reply)
PreAuthHook(\$request, \$reply)
PostAuthHook(\$request, \$reply, \$handledflag, \$reason)
PostProcessingHook(\$request, \$reply)
MainLoopHook()
ReplyHook(\$replyfromproxy, \$replytonas, \$originalrequest, \$senttoproxy,$host)
(AuthBy RADIUS only, when a reply is received)

CacheReplyHook($authobject, $user_name, $request, $reply)

(Some authenticators, such as AuthBy RADIUS, when no reply is received, and
CachePasswords is set)

NoReplyHook(\$originalrequest, \$senttoproxy \$replytonas)

(AuthBy RADIUS only, when no reply is received)

PostSearchHook($self, $name, $p, $user, $entry, $rp)

(AuthBy LDAP* only, after the LDAP search has completed)
Note that arguments preceded by \ are passed by reference. You will need to dereference them to get at the actual parameter. Why do we do it this way, instead of just passing a handle to the object? So you can switch the object it points to (if you wish). In any

Radiator RADIUS Server

371 of 397

Execution sequence and Hook processing

case, to reference the request in, say PreClientHook, you would need to refer to it as
${$_[0]}, and the second argument to a hook would be accessed as ${$_[1]}, etc. For
example to get an attribute from the request in PreClientHook, you would use something like:
my $modtype = ${$_[0]}->get_attr(USR-Modulation-Type);

Some example hooks may be found in goodies/hooks.txt in your distribution.

Hooks are executed at fixed times during request processing:
1. Server started
2. StartupHook called.
3. Radiator waits for requests.
4. Request received from NAS
5. Global RewriteUsernames applied
6. PreClientHook called
7. Client clause selected
8. Global ClientHook called
9. Client-specific ClientHook called
10. Client RewriteUsernames applied
11. Duplicate detection done
12. PreHandlerHook called
13. Handler selected
14. PreProcessingHook called
15. Handlers RewriteUsername and RewriteFunction applied
16. Session database updated (accounting requests only)
17. Accounting log files (AcctLogFileName and WtmpFileName) written
18. PreAuthHook called
19. AuthBy clauses invoked
20. PostAuthHook called
21. Statistics updated
22. PostProcessingHook called (if there is a reply to be sent)
23. Reply sent to NAS (unless request was proxied)
24. (if the request was proxied to another RADIUS server...) Reply received from proxy

server
25. ReplyHook called
26. PostProcessingHook called
27. Reply sent to NAS
28. If no reply was received from a proxy server by AuthBy RADIUS, even after multiple retransmissions and timeouts, CacheReplyHook is called (if CachePasswords is
specified), then NoReplyHook is called.
29. After all requests have been satisfied and timers run at the end of the main loop,
MainLoopHook is run. Typically this happens once per second.

372 of 397

Radiator RADIUS Server

Interoperation with iPASS Roaming

20.0 Interoperation with iPASS Roaming

iPASS (TM) operate a Global Roaming system that can allow your users to log in at any
cooperating ISP around the world. See http://www.ipass.com for more details.
In order to interoperate you must enter into a commercial arrangement with iPASS.
iPASS will then be able to provide the software that Radiator needs to communicate
with the iPASS network.
iPASS regard roaming as two distinct products:

NetServer, where you originate authentication and accounting requests for users who
dial in to your POP. The requests are sent to the iPASS network, where they are
authenticated, possibly by someone elses Roam Server. This happens when someone elses customers dial in to your POP. We call this outbound.

RoamServer, where authentication and accounting requests arrive from the iPASS
network. This happens when your customers dial in to someone elses POP. We call
this inbound.
Radiator uses different methods for handling inbound and outbound iPASS requests,
and each must be set up separately with Radiator and with iPASS.
20.1 iPASS Outbound
Outbound requests must be proxied to an NetServer, configured to work with the iPASS
system. The NetServer is provided by iPASS. The NetServer may be run either on the
same host as Radiator, or on a different host. If the NetServer is run on the same host as
Radiator, it must be configured to use different ports to Radiator.
As an example, here is part of a typical configuration that will handle requests for local
users from a file, and proxy all other realms to an NetServer running on another host:
# Local realm is handled locally
<Realm my.local.realm>
<AuthBy FILE>
Filename xxx
</AuthBy>
</Realm>
# Al other realms are proxied to NetServer on fred
<Realm DEFAULT>
<AuthBy RADIUS>
Host fred
Secret mysecret
</AuthBy>
</Realm>

Radiator RADIUS Server

373 of 397

Interoperation with iPASS Roaming

FIGURE 25.

Schematic diagram of how iPASS outbound requests are handled

RADIUS request

NAS

RADIUS reply

<Client ...>

Radiator

<Realm DEFAULT>

Plug-In
authentication
modules

AuthBy ...

AuthBy ...

AuthBy
RADIUS

iPASS
NetServer

encrypted
proprietary
protocol

iPASS Network

In order to configure Radiator to handle outbound iPASS requests, you need to do the
following things:
1. Enter into a commercial arrangement for iPASS to provide Net Server access to you.

iPASS will provide you with an ISP partner number.

2. Download, install and configure the iPASS software. You will need to configure

both the RoamServer and RADIUS server. This will involve configuring the package, requesting and receiving an encryption certificate, and submitting details of
your server and realm to iPASS. Install the package in the normal place (/usr/ipass).
3. Test the installed iPASS package by using the test programs provided with it. Make

sure it is really working properly before you go on to the next step.

4. Configure Radiator so that all realms that are not handled locally are forwarded to

the NetServer.
5. Test Radiator with the radpwtst program to make sure that requests for non-local

realms are forwarded to iPASS.

20.2 iPASS Inbound
Inbound requests are received by a special server that you also must get from iPASS
called RoamServer. RoamServer receives requests from the iPASS network and then
sends them to Radiator as ordinary RADIUS requests. See Figure 26 on page 375.

374 of 397

Radiator RADIUS Server

Interoperation with iPASS Roaming

RoamServer will usually run on the same host as Radiator, or possibly on a different
host in your network.

FIGURE 26.

iPASS Network

Schematic diagram of how iPASS inbound requests are handled

encrypted
proprietary
protocol

RoamServer

RADIUS
requests and
replies
Radiator

<Client ...>
<Realm ...>

Plug-In
authentication
modules

AuthBy ...

AuthBy ...

AuthBy ...

In order to configure Radiator to handle inbound iPASS requests, you need to do the following things:
1. Enter into a commercial arrangement for iPASS to provide Roam Server access to

you. iPASS will provide you with an ISP partner number.

2. Request the iPASS RoamServer software for your platform from iPASS.
3. Install and configure the RoamServer software according to the instructions included

with it. This will involve configuring the package, requesting and receiving an
encryption certificate, and submitting details of your server and realm to iPASS.
Install the package in the normal place (/usr/ipass). If you have already done this for
outbound requests above, you dont need to do it again.
4. Configure Radiator in the usual way for your local realms. Add a Client clause spec-

ifying the host where the RoamServer software is running, and the shared secret you
configured into RoamServer:
<Client localhost>
Secret secret
</Client>
<Realm ...>
....

Radiator RADIUS Server

375 of 397

RadSec (RFC 6614)

5. Test that RoamServer sends requests to Radiator by using the test software provided

with RoamServer.

21.0 RadSec (RFC 6614)

It is often the case that RADIUS requests need to be sent from one RADIUS server to
another. This is called proxying. It is commonly used to send requests to another
RADIUS server that is better able to handle the request. In Radiator proxying is usually
implemented with the <AuthBy RADIUS> clause.
Conventional UDP based RADIUS proxying is inherently unreliable and insecure. It is
unreliable because the UDP protocol does not guarantee delivery, and the RADIUS protocol only requires a limited number of retransmits. Therefore, in an unreliable or congested network, RADIUS packets may be irretrievably lost. Further, conventional
RADIUS requests are not encrypted, and most of the attributes (other than the password) in a RADIUS request are in plaintext. This means that eavesdroppers can obtain
valuable information from unprotected RADIUS requests.
As a result, RFC 6614 Transport Layer Security (TLS) Encryption for RADIUS was
created to specify a secure, reliable RADIUS transport. RFC 6614 is based on the original RadSec protocol in Radiator, and the Radiator RadSec implementation is by default
compliant with RFC6614.
RFC 6614 RadSec is a communication protocol that provides secure, reliable proxying
of RADIUS requests from one Radiator to another. It can be used in place of AuthBy
RADIUS when proxying across insecure or unreliable networks.
When using RadSec, one Radiator is designated the RadSec client, and the other is the
RadSec server. The RadSec client establishes the connection to the RadSec server, and
sends RADIUS requests to the RadSec server over a reliable stream connection. The
RadSec server sends any replies to each RADIUS request back to the RadSec client. A
RadSec server can accept connections from any number of RadSec clients.
RadSec uses the TCP/IP (or optionally SCTP) stream protocol to transport requests
from the RadSec client to the RadSec server and replies from the server to the client. By
default, TLS is used to encrypt the requests, and to enforce server authentication with a
server PKI certificate (i.e. the RadSec client confirms that it is connected to the RadSec
server it expects by checking a server certificate). By default, the Radiator RadSec
server requires that clients confirm their identity by requiring a PKI client certificate.

376 of 397

Radiator RADIUS Server

RadSec (RFC 6614)

FIGURE 27.

Using RadSec to proxy request from one Radiator to another

Radius Clients
Dialup
Router
Access
Point

RADIUS
requests

<AuthBy RADSEC>
Host h2.com
Secret mysecret
UseTLS
......
</AuthBy>

RadSec RADIUS packets encrypted

with TLS on a TCP/IP stream
...JKiJ@K$hj^uygJKUgKJYg547bN(8nbn(jn)...

host h1.com

<ServerRADSEC>
.....
Secret mysecret
UseTLS
......
</Server>

host h2.com

For more information about RadSec, including a description of the RadSec protocol, see
http://www.open.com.au/radiator/radsec-whitepaper.pdf. See also RFC 6614.
21.1 RadSec Certificate Validation
During the establishment of a TLS RadSec connection between a RadSec client and
RadSec server, certificate validation is performed in order to confirm that they are connected to the peer they expect to be connected to. This is a brief description of how validation is performed.
If a peer presents a certificate (TLS_RequireClientCert), then it is always validated
using the peer certificate issuers Root Certificate (see TLS_CAFile or TLS_CAPath)
and any certificate revocation list (CRL) for the certificates issuer (see TLS_CRLCheck, TLS_CRLFile). If that is successful, the contents of the peer certificate are
checked:
In the RadSec server the client certificate is examined. It is accepted if:

the certificate contains a subjectAltName extension of type IPADDR that matches

the clients IP address or,

there were no subjectAltName extensions, but the certificate Subject contains a

Common Name (CN) that matches the clients IP address or,

the certificate Subject matches the TLS_ExpectedPeerName pattern,

and

If TLS_SubjectAltNameURI parameter is defined in the ServerRADSEC clause, the

certificate must contain a subjectAltName of type URI that matches the TLS_SubjectAltNameURI regular expression.

If TLS_CertificateFingerprint parameter is defined in the ServerRADSEC clause,

the certificates fingerprint must match at least one of the TLS_CertificateFingerprint options.
Radiator RADIUS Server

377 of 397

Extensible Authentication Protocol (EAP)

In the RadSec client, the server certificate is examined. It is accepted if:

the certificate contains a subjectAltName extension of type IPADDR or DNS that

matches the Host name used to connect to the server or,

there were no subjectAltName extensions, but the certificate Subject contains a

Common Name (CN) that matches the Host name used to connect to the server or,

the certificate Subject matches the TLS_ExpectedPeerName pattern,

and

If TLS_SubjectAltNameURI parameter is defined in the AuthBy RADSEC clause,

the certificate must contain a subjectAltName of type URI that matches the TLS_SubjectAltNameURI regular expression.

If TLS_CertificateFingerprint parameter is defined in the AuthBy RADSEC clause,

the certificates fingerprint must match at least one of the TLS_CertificateFingerprint options.

22.0 Extensible Authentication Protocol (EAP)

Extensible Authentication Protocol (EAP) is a standard for defining and extending
authentication protocols. EAP is defined by RFC 3748, and RFC 2869 defines how EAP
authentication messages can be carried in RADIUS packets. Radiator complies with
these standards, and can be extended to handle any EAP-compliant protocol. Because
EAP is designed to be easily extensible, a number of EAP protocols have been defined
(through RFCs available from the Internet Engineering Task Force www.ietf.org) for
various special requirements, including mutual authentication between client and
RADIUS server, and for encryption of the authentication conversation. EAP over
RADIUS is commonly used as the authentication protocol for 802.1X wired and wireless networks.
While conventional RADIUS requests send the User-Name in one RADIUS attribute
and the User-Password in another attribute, all EAP-over-RADIUS requests send their
authentication information in the EAP-Message attribute. Usually the client will send
some EAP protocol information in the EAP-Message attribute in a RADIUS AccessRequest message, and the RADIUS server will ask for some more information from the
client by sending back another EAP-Message in a RADIUS Access-Challenge. When
the server has enough information from the client, the RADIUS server will reply with
an Access-Accept or an Access-Reject message. Some EAP protocols (such as TLS,
TTLS and PEAP) often require a number of messages (10 or more) to be exchanged
between client and RADIUS server during authentication. Such a group of EAP-overRADIUS messages while authenticating a user is called a conversation.
It should be noted that many EAP protocols hide or encrypt the identity of the real user
name of the user being authenticated, and send a generic name (typically anonymous)
as the visible User-Name in the RADIUS requests.
Radiator supports many different EAP protocols, and this section describes their characteristics, and how Radiator can be configured to support each one. In order to configure

378 of 397

Radiator RADIUS Server

Extensible Authentication Protocol (EAP)

Radiator to support EAP, the relevant AuthBy clauses need to have the EAPType
parameter set to the names of the EAP type(s) that you wish to support. In addition, a
number of other special configuration parameters may have to be set in order to support
those EAP type(s). An AuthBy clause can be configured to accept more than one EAP
type. When that is the case, the first one in the list will be the default EAP method
offered to the client. The client can accept the offered method, or request another EAP
method. If the requested method is one of the methods named in the EAPType parameter, then EAP authentication will continue with that method.
There are many example configuration files covering various EAP authentication
requirements in the goodies directory of the Radiator distribution.
See goodies/README for details.
22.1 EAP MD5-Challenge
In EAP MD5-Challenge, the RADIUS server sends a random challenge to the client.
The client forms an MD5 hash of the users password and the challenge and sends the
result back to the server. The server then validates the MD5 hash using the known correct plaintext password from the user database. EAP MD5-Challenge does not support
dynamic WEP keys.
EAP MD5-Challenge can work with most Radiator AuthBy clauses that support the
retrieval of a plaintext password, such as FILE, DBFILE, SQL, LDAP etc.
22.2 EAP One-Time-Password
In EAP One-Time-Password, the client sends a plaintext one-time-password to the
server, which then checks the password and either accepts or rejects the request. The
one-time-password is sent in the clear, so it is subject to eavesdropping, and should not
be used with static password. EAP One-Time-Password does not support dynamic WEP
keys.
EAP One-Time-Password can work with Radiator AuthBy clauses that support onetime-passwords, such as AuthBy OPIE, OTP and LDAPDIGIPASS and SQLDIGIPASS.
22.3 EAP Generic-Token
EAP Generic-Token is intended to support a range of authentication tokens from various vendors. In this context, a token is a small device that the end user carries and
which displays a login passcode that is used to authenticate the user. Examples are RSA
SecurID, Encotone TeleID and Vasco tokens. Most such systems have back end servers
that do the actual authentication. EAP Generic-Token does not support dynamic WEP
keys.
EAP Generic-Token can be used with Radiator AuthBy clauses ACE, LDAPDIGIPASS,
SQLDIGIPASS, OTP, OPIE, RSAMOBILE to support one-time passwords. It can also
be used with all AuthBy clauses that support static passwords, such as FILE, SQL,
LDAP, UNIX etc. In this case, it prompts the user Enter your static password.

Radiator RADIUS Server

379 of 397

Extensible Authentication Protocol (EAP)

22.4 EAP TLS

EAP TLS uses Public Key Infrastructure (PKI) digital certificates to provide mutual
authentication between the EAP client and the RADIUS server. A PKI certificate is a
file created by a program called a Certificate Authority. The certificate contains the
name of the server or user that has been issued to. The EAP client and RADIUS server
use the certificates to verify that the other party is indeed who it claims to be. In EAP
TLS, a PKI certificate is required for the Radiator RADIUS server and for each and
every EAP TLS client. EAP TLS does support dynamic WEP keys.
You can obtain certificates from a Public Certificate authority such as Thawte
(www.thawte.com). The advantage of Public Certificates is that they will generally be
recognized by any client or server without taking any special steps. A disadvantage of
Public certificates is that you usually have to pay an annual fee for each one. With a Private Certificate Authority, you can generate your own server and client certificates for
free, but you will generally have to install the Root Certificate from your Certificate
Authority on each client before it will recognize a private server certificate. Private Certificates are considered by many to be more secure that Public Certificates.
The basic steps of EAP TLS authentication are:
1. The EAP TLS client and RADIUS server establish a communications channel via

the RADIUS protocol.

2. The RADIUS server sends its Server PKI Certificate to the client.
3. The client verifies that the server certificate is valid and is the correct certificate for

the RADIUS server it is communicating with. It uses the Root Certificate of the Certificate Authority that issued the Server Certificate to validate the Server Certificate.
(Root Certificates for most Public Certificate Authorities are built in to most clients.
If the Server Certificate was issued by a Private Certificate Authority, the client
requires a copy of the Root Certificate to be installed in order to validate the Server
Certificate.)
4. If the client validates the server certificate, it then sends the users PKI certificate to

the RADIUS server.

5. The RADIUS server verifies that the client certificate is valid and is the correct cer-

tificate for the user name that is being authenticated. The RADIUS server can be
configured to validate Private Client Certificates using a locally installed copy of the
Root Certificate of the Certificate Authority that issued the client certificate.
6. If the RADIUS server validates the client certificate then the authentication is suc-

cessful, and the client is permitted to be connected to the network.

EAP TLS does not use or exchange any passwords, but you can use AuthBy methods in
Radiator to enable or disable EAP TLS users based on their user name, time of day etc.
22.5 EAP LEAP
EAP LEAP (often called just LEAP) is a proprietary protocol from Cisco
(www.cisco.com). It provides password based authentication that can be used with any
Radiator authentication method that stores plaintext passwords (such as FILE, SQL,
LDAP) etc., as well as direct Windows authentication using AuthBy LSA. LEAP
authentication requires a special LEAP client that is only available from Cisco.
380 of 397

Radiator RADIUS Server

Extensible Authentication Protocol (EAP)

22.6 EAP TTLS

Like EAP TLS (See EAP TLS on page 380.), EAP TTLS uses Public Key Infrastructure (PKI) digital certificates. Unlike TLS, it only uses a Server Certificate so the client
can validate the server, and then establish a secure, encrypted communications channel
with the RADIUS server. When this channel is established, it is used to tunnel conventional RADIUS attributes, such as User-Name, User-Password etc. to the RADIUS
server. Radiator converts each of these so-called inner requests into a new RADIUS
request which can be authenticated by any supported AuthBy method. So EAP TTLS
authentication happens in 2 phases following these basic steps:
1. The EAP TTLS client and RADIUS server establish a communications channel via

the RADIUS protocol.

2. The RADIUS server sends its Server PKI Certificate to the client.
3. The client verifies that the server certificate is valid and is the correct certificate for

the RADIUS server it is communicating with. It uses the Root Certificate of the Certificate Authority that issued the Server Certificate to validate the Server Certificate.
(Root Certificates for most Public Certificate Authorities are built in to most clients.
If the Server Certificate was issued by a Private Certificate Authority, the client
requires a copy of the Root Certificate to be installed in order to validate the Server
Certificate.)
4. If the client validates the server certificate, it then sends the real user name and pass-

word in a RADIUS request through the encrypted TLS tunnel. Any conventional
RADIUS authentication system may be used depending on the client configuration,
such as PAP, CHAP, MSCHAP, MSCHAPV2 etc.
5. Radiator converts this inner request into a new RADIUS request and dispatches it

to the first matching Realm or Handler clause, where it can be handled by one or
more AuthBy clauses. To assist in discriminating TTLS inner requests, each inner
request is tagged with the pseudo-attribute TunnelledByTTLS set to 1.
6. The result of the inner authentication is sent back to the client through the TLS tun-

nel.
In order to use EAP TTLS, you must install a unique Server Certificate on your
RADIUS server host, and configure Radiator to use it. See the comments in EAP TLS
on page 380 concerning Public and Private certificates and how to obtain them. EAP
TTLS does support dynamic WEP keys.
You can configure Radiator to handle the inner and outer requests in separate Handler or
Realm clauses. You can also configure Radiator to proxy the inner RADIUS requests to
another RADIUS server, which means that Radiator can server as a gateway between
EAP TTLS clients and a non-EAP enabled RADIUS server.
22.7 EAP SIM
This protocol is used to authenticate using a GSM SIM card. EAP-SIM support is available as a premium add-on package for Radiator. Contact [email protected] for more
details.

Radiator RADIUS Server

381 of 397

Extensible Authentication Protocol (EAP)

22.8 EAP AKA

This protocol is used to authenticate using a UMTS SIM card. EAP-AKA support is
available as a premium add-on package for Radiator. Contact [email protected] for
more details.
22.9 EAP AKA
This protocol is a revision of EAP-AKA and is used to authenticate using a UMTS SIM
card. EAP-AKA support is available as a premium add-on package for Radiator. Contact [email protected] for more details.
22.10 EAP PEAP
Like EAP TLS (See EAP TLS on page 380.), EAP PEAP (often called just PEAP)
uses Public Key Infrastructure (PKI) digital certificates. Unlike TLS, it only uses a
Server Certificate so the client can validate the server, and then establish a secure,
encrypted communications channel with the RADIUS server. When this channel is
established, it is used to tunnel encrypted EAP messages to the RADIUS server. Radiator converts each of these so-called inner requests into a new RADIUS request which
can be authenticated by any supported AuthBy method. So EAP PEAP authentication
happens in 2 phases following these basic steps:
1. The EAP PEAP client and RADIUS server establish a communications channel via

the RADIUS protocol.

2. The RADIUS server sends its Server PKI Certificate to the client.
3. The client verifies that the server certificate is valid and is the correct certificate for

the RADIUS server it is communicating with. It uses the Root Certificate of the Certificate Authority that issued the Server Certificate to validate the Server Certificate.
(Root Certificates for most Public Certificate Authorities are built in to most clients.
If the Server Certificate was issued by a Private Certificate Authority, the client
requires a copy of the Root Certificate to be installed in order to validate the Server
Certificate.)
4. If the client validates the server certificate, it then sends one or more EAP requests

through the encrypted TLS tunnel. The type of inner EAP request depends on the
PEAP client configuration, but the most common types of inner EAP requests are
EAP MSCHAPV2 and EAP TLS.
5. Radiator converts this inner request into a new RADIUS request and dispatches it

to the first matching Realm or Handler clause, where it can be handled by one or
more AuthBy clauses. To assist in discriminating PEAP inner requests, each inner
request is tagged with the pseudo-attribute TunnelledByPEAP set to 1.
6. The result of the inner authentication is sent back to the client through the TLS tun-

nel.
In order to use EAP PEAP, you must install a unique Server Certificate on your
RADIUS server host, and configure Radiator to use it. See the comments in EAP TLS
on page 380 concerning Public and Private certificates and how to obtain them. EAP
PEAP does support dynamic WEP keys.

382 of 397

Radiator RADIUS Server

Extensible Authentication Protocol (EAP)

You can configure Radiator to handle the inner and outer requests in separate Handler or
Realm clauses. You can also configure Radiator to convert an inner EAP-MSCHAPV2
request into a conventional RADIUS-MSCHAPV2 request, which means that Radiator
can server as a gateway between EAP PEAP clients and a non-EAP enabled RADIUS
server
22.11 EAP MSCHAPV2
EAP MSCHAPV2 is an EAP version of the common MSCHAPV2 authentication
mechanism. It provides mutual authentication between client and server. It is most commonly used as the inner authentication protocol with EAP PEAP on Microsoft Windows
clients. EAP MSCHAPV2 does support dynamic WEP keys.
EAP MSCHAPV2 can be used with any Radiator AuthBy that has access to plaintext
passwords, such as FILE, SQL, LDAP, DBM etc. It can also be used with AuthBy LSA
to authenticate with a Windows Local Security Authority, Windows Domain Controller
etc. It can also be used with LDAPDIGIPASS and SQLDIGIPASS.
22.12 EAP PAX
EAP PAX provides strong encryption and mutual authentication between supplicant and
server based on a per-user Authentication Key (AK). It is described in RFC 4746. Based
on the per-user AK, the server and supplicant derive strong cryptographic keys and
authenticate each others knowledge of the AK. The derived keys can be used for
dynamic WEP and WPA keys.
The AK is required to be configured into the per-user data in the Radiator user database,
and also into each users EAP-PAX supplicant configuration. The AK is required to be
16 bytes. It can be specified in a Radiator user database as 32 hex digits:
pskuser

User-Password=1234567890123456789012345678901

EAP PAX can be used with any Radiator user database that supports a plaintext UserPassword. Requires Crypt::Rijndael and Digest::HMAC_SHA1, bother from CPAN.
22.13 EAP PSK
EAP PSK provides strong encryption and mutual authentication between supplicant and
server based on a per-user Pre-Shared-Key (PSK). It is described in RFC 4764. Based
on the per-user PSK, the server and supplicant derive strong cryptographic keys and
authenticate each others knowledge of the PSK. The derived keys can be used for
dynamic WEP and WPA keys.
The PSK is required to be configured into the per-user data in the Radiator user database, and also into each users EAP-PSK supplicant configuration. The PSK is required
to be 16 bytes. It can be specified in a Radiator user database as 32 hex digits:
pskuser

User-Password=1234567890123456789012345678901

If the User-Password does not appear to be 32 hex digits, it will be regarded as a plaintext password, and will be converted into a PSK using the algorithm described in RFC

Radiator RADIUS Server

383 of 397

Monitor command language

4764. The conversion to a PSK depends on the plaintext password and the server and
supplicant IDs. Use of such plaintext passwords is discouraged by RFC 4764 (because
the PSK then becomes vulnerable to dictionary attacks) and is not supported by all EAP
PSK supplicants. We also discourage use of such plaintext passwords.
EAP PSK can be used with any Radiator user database that supports a plaintext UserPassword. Requires Crypt::Rijndael and Digest::HMAC_SHA1, both from CPAN.
22.14 EAP PWD
EAP PWD provides strong encryption and mutual authentication between supplicant
and server based on a shared password. It is described in RFC 5931. Based on the peruser password, the server and supplicant derive strong cryptographic keys and authenticate each others knowledge of the password. The derived keys can be used for dynamic
WEP and WPA keys.
EAP PWD is highly secure (the password is never transmitted, even in encrypted form),
and does not require PKI certificates, and also requires only 3 authentication roundtrips. Further, it is not encumbered by intellectual property issues. So it is considered
efficient to roll out in e.g. eduroam and other environments.
Authentication of EAP PWD by Radiator depends in having access to the users plaintext password:
username

User-Passsword=fred

EAP PWD can be used with any Radiator user database that supports a plaintext UserPassword. Requires OpenSSL 0.9.8i libraries or later, Crypt::OpenSSL::EC and
Crypt::OpenSSL::Bignum 0.04+patches or later. A patch for Crypt::OpenSSL::Bignum
0.04 is available in the goodies directory to add features required by EAP-PWD.
Hint: Crypt::OpenSSL::EC and Crypt::OpenSSL::Bignum may not be readily available
for Windows. We recommend Linux or Unix hosts for deployment or EAP PWD.

23.0 Monitor command language

The Monitor clause (see Section 5.101 on page 299) enables external client programs to
make an (authenticated) TCP connection to Radiator, and use that connection to monitor, probe, modify and collect statistics from Radiator.
Monitor implements a simple command language, which is described in this section.
All Monitor connections must be authenticated with the LOGIN command before any
significant command can be executed. If a connection has not been authenticated, the
only commands that can be executed are LOGIN, HELP and QUIT.
Monitor supports 2 basic connection types:

ASCII text with line-feed terminators, which permits use by Telnet or other interactive TCP programs. New connections always start in this mode.
384 of 397

Radiator RADIUS Server

Monitor command language

BINARY mode, which permits specialized external client programs (such as Radar
from Open System Consultants) to exchange information more efficiently. BINARY
mode is entered with the BINARY command.
Monitor supports 2 types of authentication in the LOGIN command:

Plaintext. The password is supplied as plaintext. Since the password will be transmitted as plaintext on a TCP connection, it is possible for eavesdroppers to sniff the
password. Therefore you should only use this on interactive Telnet connections over
trusted connections.

CHAP. The password is supplied as CHAP response to a CHAP challenge. This is

suitable for client programs to authenticate Monitor connections. CHAP passwords
start with {chap}.
23.1 Object naming
Some Monitor commands accept Radiator object names as arguments. This allows you
to identify specific internal Radiator objects to operate on or to monitor. A Radiator
object is an internal Radiator structure which generally corresponds to a clause in the
Radiator configuration file. There always exists a main object (ServerConfig) that represents the server as a whole, and which is the ultimate parent of all the other objects.
The Radiator objects form a tree structure with ServerConfig as the root.
You can identify specific Radiator objects with an object name. An object name consists
of a number of dot (.) separated words. A single dot is taken to mean the root, the main
ServerConfig object. In object names, case is significant.
Consider this skeleton Radiator configuration file:
DbDir ....
Trace 4
...
<Client 1.2.3.4>
...
</Client>
<Realm xyz.com>
<AuthBy FILE>
...
</AuthBy>
</Realm>

Then the following object names could be used:

.
A single dot refers to the server as a whole, or ServerConfig. If you got STATS from
. then you would receive the statistics for the whole server.

.Client.0
This refers to the first (and only) Client 1.2.3.4 clause.

.Realm.0
This refers to the first (and only) Realm xyz.com clause.

Radiator RADIUS Server

385 of 397

Monitor command language

.Realm.0.AuthBy.0
This refers to the AuthBy FILE clause inside the Realm clause
23.2 Commands
All command names are case insensitive, but arguments to commands may be case sensitive.
23.2.1 BINARY

Makes the connection run in BINARY mode. In BINARY mode, commands and their
responses are separated by NULL characters. BINARY mode is only suitable for Monitor client programs. Do not use BINARY for interactive Telnet connections.
23.2.2 CHALLENGE

Requests a CHAP challenge from Monitor. The reply may be used to generate a CHAP
response in a subsequent LOGIN command. This allows client programs to avoid sending plaintext passwords on the Monitor TCP connection.
23.2.3 DESCRIBE objectname

Describes the named object by returning a list of its attributes and their types.
23.2.4 GET objectname

Not implemented.
23.2.5 HELP

Prints a list of the supported commands.

23.2.6 ID

Prints the Radiator server identification string.

23.2.7 LIST objectname

If objectname names an object array parameter (such as a Client, Realm or Handler

array), prints a list of the objects in the array and their indexes.
23.2.8 LOGIN username password

Authenticate the connection, so that privileged commands can be executed. Username

and password must be authenticated by one of the Monitors AuthBy clauses, or by the
hardwired Username and Password (if present).
Password may be either a plaintext password or a CHAP response to a previously issued
CHALLENGE command.
LOGIN mikem fred
LOGGEDIN

or
CHALLENGE
CHALLENGE 5b0e00b1a379ae225634946268cc0144
LOGIN mikem {chap}4bda435ca72249c0e9fe05d32775eb6e98
LOGGEDIN

386 of 397

Radiator RADIUS Server

Monitor command language

23.2.9 RESTART

Causes Radiator to restart and reread its configuration file, with the same effect as a
SIGHUP.
23.2.10 TRACE n

Causes Radiator to start printing log message at or below the given log level. The number n can be 0 to 5 inclusive. Each new Monitor connection starts out at level 0 (ERR
level). Level 4 is DEBUG level. After setting a new Trace level, Radiator will send all
log messages at or below that level on the Monitor connection.
If a TRACE_USERNAME is in force, only messages that result from requests from that
specific User-Name will be printed.
23.2.11 TRACE_USERNAME username

Causes TRACE to only print log messages that result from a RADIUS request from the
given User-Name. This is handy for seeing only log messages for a given user when
debugging connection problems.
The username is compared to the User-Name in the incoming request after any
RewriteUsername rules have been applied. Setting the TRACE_USERNAME to an
empty string (the default) turns off this special behavior, and all messages that are at or
below the current TRACE level will be output.
In the following example, the TRACE level is set to 4, meaning all DEBUG and lower
level log messages will be printed. Then the TRACE_USERNAME is set to
[email protected], which means that only DEBUG and lower log messages due to
requests from [email protected] will be printed. Finally the TRACE_USERNAME
is set to an empty string, which means that all DEBUG and lower level log messages
will be printed again.
TRACE 4
TRACE_USERNAME [email protected]
<<< only messages that are at or below the current TRACE level
for requests from [email protected]
are output here.>>>
TRACE_USERNAME
<<< no more user-specific logging now. All trace level 4
messages will be output >>>
23.2.12 SET objectname parameter value

Sets a new value for the named parameter in the named object. The new value will persist in the Radiator until it is restarted. This is useful for experimenting with new configuration values without having to restart the server. It is probably most useful for setting
the PacketTrace parameter, permitting DEBUG level tracing of all packets that pass
through a given object.
For example, this command will set PacketTrace on the first Client clause. Subsequently, all packets arriving from that Client will by logged to this Monitor connection
(and any other logger) at DEBUG level:
SET .Client.0 PacketTrace 1

Radiator RADIUS Server

387 of 397

Using SQL with various database vendors

23.2.13 STATS objectname

Requests all the statistics available from the named object.

23.2.14 QUIT

Forces disconnection from Monitor.

24.0 Using SQL with various database vendors

Radiators AuthBy SQL clause and buildsql utility can be used with any Relational
Database that is supported by a Perl DBD module. That currently includes:

DB2
Fulcrum
Informix
Ingres
mSQL
mysql
ODBC
Oracle
pNET
PostgreSQL
Qbase
Solid
Sybase
Xbase

We have not directly tested every one of these. We have tested some of them, and this
section contains some tips about using Radiator with them. We supply some simple
schemas with Radiator for a few databases. See the goodies directory in the distribution
for scripts to create them. You will probably want to create a more elaborate schema to
handle the tasks you need, and the schemas we supply should be regarded as a starting
point only. You should probably consult with a Database Analyst to maximize the performance of your SQL database.
24.1 General
Whenever Perls DBI module is used to work with a database, you need to supply up to
3 pieces of information in order to specify the database to which you want to connect:

DBSource
This is the data source name. It has the special format: dbi:drivername:options,
where drivername is the name of the DBI driver to use, and options is an option
string whose exact format depends on the DBI driver you are using.

DBUsername

388 of 397

Radiator RADIUS Server

Using SQL with various database vendors

This is usually the SQL user name to use to connect to the SQL database, but for
some database types, it has a different meaning.

DBAuth
This is usually the password for DBUsername, but for some database types, it has a
different meaning or is not required
24.2 mSQL
In DBSource, drivername is mSQL, and options is the database name. You can also
specify the host where the server is running and the port number of the server. DBUsername is the database name to user, and DBAuth is not required
To create a new database:
msqladmin create radius
msql radius <msqlCreate.sql

Configure your SQL clause like this:

DBSource dbi:mSQL:radius
DBUsername sqlusername
DBAuth
sqluserpassword

Use buildsql like this:

buildsql -dbsource dbi:mSQL:radius
-dbusername sqlusername -dbauth sqluserpassword ...

You must use the DBD module Msql-Mysql-modules-1.1828 or better to connect to

mSQL.
Hint: The general format for DBSource is:
dbi:mSQL[:database[:hostname[:port]]]
24.3 mysql
In DBSource, drivername is mysql, and options is the database name. You can also
specify the host where the server is running and the port number of the server. DBUsername is the database name to user, and DBAuth is not required
To create a new database:
mysqladmin create radius
mysql radius <mysqlCreate.sql

Configure your SQL clause like this:

DBSource
DBUsername
DBAuth

dbi:mysql:radius
radius
password

Use buildsql like this:

buildsql -dbsource dbi:mysql:database
-dbusername radius -dbauth password

Radiator RADIUS Server

389 of 397

Using SQL with various database vendors

You must use the DBD module Msql-Mysql-modules-1.1828 or better to connect to

mysql.
Hint: The general format for DBSource is:
dbi:mysql[:database[:hostname[:port]]]
24.4 Oracle
In DBSource, drivername is Oracle, and options is the SID of the Oracle database
instance you want to use. DBUsername is the Oracle user name, and DBAuth is the
password for the Oracle user.
To create a new database:
sqlplus user/password@sid @ansiCreate.sql

Configure your SQL clause like this:

DBSource
DBUsername
DBAuth

dbi:Oracle:sid
user
password

Use buildsql like this:

buildsql -dbsource dbi:Oracle:sid
-dbusername user -dbauth password ...

24.5 Sybase
In DBSource, drivername is Sybase, and options is the server name of the Sybase
server to use. DBUsername is the Sybase user name, and DBAuth is the password for
the Sybase user.
To create a new database:
isql -Uuser -Ppassword -Sserver -i sybaseCreate.sql

Configure your SQL clause like this:

DBSource
dbi:Sybase:server
DBUsername user
DBAuth
password

Hint. DBSource can also contain other hints and directives for connecting to the Sybase
server, for example:
DBSource

dbi:Sybase:server=SERVERNAME;database=DBNAME

Use buildsql like this:

buildsql -dbsource dbi:Sybase:sid
-dbusername user -dbauth password ...

390 of 397

Radiator RADIUS Server

Using SQL with various database vendors

24.6 PostgreSQL
In DBSource, drivername is Pg, and options is the database name to use. DBUsername is the PostgreSQL user name, and DBAuth is the password for the PostgreSQL
user. You should note that some versions of PostgreSQL do not permit columns with the
name PASSWORD. Therefore, you may have to alter the name of the PASSWORD column to PASS_WORD, and use that column name in your AuthSelect configuration
parameter.
To create a new database (make sure you are a postgres DBA before running these commands, otherwise they wont work):
createuser user
createdb radius
psql -f postgresCreate.sql radius

Configure your SQL clause like this:

DBSource
DBUsername
DBAuth

dbi:Pg:dbname=radius
user
password

Use buildsql like this:

buildsql -dbsource dbi:Pg:dbname=radius
-dbusername user -dbauth password ...

24.7 ODBC
To use ODBC, you must first create the database and tables in a way that depends on the
type of database to which you are going to connect. See your vendors documentation.
You will also need to install and configure your ODBC manager. The way to do this also
depends on your ODBC data manager. For Intersolve DataDirect on Solaris, you will
need to set up a .odbc.ini file in your home directory. For Win95 and NT, you will need
to use the ODBC administration tools and add a System DSN (data source name).
Configure your SQL clause like this:
DBSource
DBUsername
DBAuth

dbi:ODBC:datasourcename
user
password

Use buildsql like this:

buildsql -dbsource dbi:ODBC:datasourcename
-dbusername user -dbauth password ...

24.8 Interbase
Interbase is a full ANSI compliant database server available for free on a number of
Unix platforms including Linux, see http://www.interbase.com. There is also a DBDInterbase now available from CPAN.
There is an example schema in goodies/interbaseCreate.sql. You can then use AuthBy
SQL in the usual way, with a couple of little tweaks. Note that the name of the password
column is PASS_WORD (PASSWORD is a reserved word in Interbase)
Radiator RADIUS Server

391 of 397

Using SQL with various database vendors

To create a new database

$ /usr/interbase/bin/isql
SQL> create database /path/to/your/database.gdb user username password password;
SQL> exit;
/usr/interbase/bin/isql -input interbaseCreate.sql /path/to/
your/database.gdb

Configure your SQL clause like this:

DBSource
base.gdb
DBUsername
DBAuth
AuthSelect

dbi:InterBase:database=/path/to/your/datausername
password
select PASS_WORD from SUBSCRIBERS where\
USERNAME=%n

Use buildsql like this:

buildsql -dbsource dbi:InterBase:database=/path/to/your/database.gdb -dbusername user -dbauth password ...

24.9 Informix
Informix is a fully featured commercial database, available on a number of platforms,
including Linux. See http://www.informix.com. The Perl DBD-Informix module is very
mature and was developed in conjunction with Informix development staff. Building
DBD-Informix requires that you have a working Informix installation and DBA access
to a test database. We recommend that you carefully follow the procedures in the DBDInformix README file, then build, test and install DBD-Informix before attempting to
create and configure a Radiator database on Informix.
The create a new database, you must ensure you have your INFORMIXDIR and
INFORMIXSERVER environment variable set up specifying an operating Informix
server.
$ dbaccess - -
> create database radius@stores;
Database created.
connect to radius@stores;
grant connect to public;
Permission granted.
^C
$ dbaccess radius@stores - <goodies/informixCreate.sql
.......

Configure your SQL clause like this:

DBSource
DBUsername
DBAuth

dbi:Informix:radius@stores
user
password

Use buildsql like this:

392 of 397

Radiator RADIUS Server

Using SQL with various database vendors

buildsql -dbsource dbi:Informix:radius@stores -dbusername user

-dbauth password ...

24.10 CSV
DBD::CSV is a perl database driver that uses flat text files as the database. The default
supports comma separated files, but that can be customized in many ways, to support
for example Unix password format and Excel spreadsheet formats. DBD::CSV is available from CPAN.
In DBSource, drivername is CSV, and a required option is f_dir, which specifies the
directory where the database files exist. DBUsername and DBAuth are not required and
are ignored.
DBD::CSV databases are flat text files. The first line of a database file contains the
names of the columns in the file. To create a new database file, you need to create the
text file with an editor, for example, a simple database for subscribers that will work the
default AuthSelect in AuthBy SQL would look like this:
USERNAME,PASSWORD
mikem,fred
jim,jim
......
<more lines, one per user>
......

For DBD::CSV on Unix, configure your SQL clause like this. DBUsername and
DBAuth are not required. f_dir specifies the directory where the database files are
located. csv_eol in this example specifies that the line separators are Unix newlines.
You must have this for a Unix style text file. You can leave it off to get Windows standard text files.
DBSource

dbi:CSV:f_dir=/your/data/dir;csv_eol=\012

24.11 SQLite
DBD::SQLite is a lightweight integrated SQL library that keeps its database in a single
flat file. It does not use a separate SQL server: all the SQL functions are embedded in
the SQLite library. DBD::SQLite is available from CPAN.
In DBSource, drivername is SQLite, and a required option is dbname, which specifies
the path name of the single file where the database is to be stored. It can be an absolute
file path or a relative path. DBUsername and DBAuth are not required and are ignored.
To create a new database:
dbish -batch dbi:SQLite:dbname=/path/to/your/dbfile <goodies/
sqliteCreate.sql

For DBD::SQLite, configure your SQL clause like this. DBUsername and DBAuth are
not required.
DBSource

dbi:SQLite:dbname=/path/to/your/dbfile

Radiator RADIUS Server

393 of 397

Performance and Tuning

25.0 Performance and Tuning

Radiator has been tuned for maximum performance. You can find some examples of
server performance on the Radiator web site. The performance you achieve will depend
on many factors including the hardware and the authentication type. If you find you
need to get better performance than you are achieving, you might try the following ideas
and suggestions:

Operate multiple radius servers, and share the load between them. You would normally make each radius server the primary radius server for some of your NASs, and
the secondary for a different group of NASs. You should probably consider doing
this anyway in order to make your network more robust in the face of a network or
server failure. Consider using LOADBALANCE, VOLUMEBALANCE or ROUNDROBIN to distribute the incoming request load among multiple servers)

Use DBM, SQL, cached FILE or UNIX authentication in preference to any other
method.

If you are using SQL, make sure that your User and Accounting tables have been
designed for performance. This will usually mean adding indexes to the tables.
Without indexes, selects on large tables can be very slow. A properly designed index
will usually speed them up enormously.

Deploy Radiator on a different (faster) machine. Radiator is highly portable and will
run on most Unix hosts, Windows XP/Vista/7/8 and Server 2003/2008/2012.

Use exact Realm names instead of regexps

If you are authenticating multiple realms, consider creating sub-servers, one for each
realm, and a main server that uses AuthBy RADIUS to retransmit to the sub-servers.

Deploy any sub-servers on other machines on the same network as the main server.
If you are using SQL, deploy the SQL server and Radiator on different hosts.
If you are using LDAP, deploy the LDAP server and Radiator on different hosts.
Dont specify RewriteUsername unless you need it.
If you dont need accounting log files (perhaps you are already getting accounting
logged by SQL?) turn off AcctLogFileName.

If you dont need wtmp log files (perhaps you are already getting accounting logged
by SQL? or AcctLogFileName) turn off WtmpFileName.

Use the lowest Trace level you really need. Higher levels slow radiusd down.
Use as few check items as possible.
Dont use Simultaneous-Use check items that specify a filename.
Dont use check items that are regular expressions.
Use the Fork parameter if your authentication method is slow.
Dont specify MaxSessions or Simultaneous-Use. If you do, dont specify the NasType in the <Client> clause (interrogating the NAS to confirm when logins are
exceeded slows Radiator down).

Dont use PasswordLogFileName unless you really need it.

394 of 397

Radiator RADIUS Server

Getting Help

Dont specify an external Session Database with the <SessionDatabase ...> clause
unless you need Simultaneous-Use limits and you running multiple instances of
Radiator.

Consider running separate servers, one for accounting and one for authentication.
If you have large number of concurrent users and require an external session database, consider using SessionDatabase SQL instead of SessionDatabase DBM.

26.0 Getting Help

26.1 Support contract holders
Your Radiator license package may include email support, and Radiator support may be
purchased at the time you purchase Radiator. See http://www.open.com.au/
ordering.html for details. Support contracts last for a limited period (typically one
year) and may include a limited amount of pre-paid email support.
Open System Consultants will respond promptly to support email during business
hours, Australian Eastern Standard time. Telephone support is not provided. We will
keep track of the effort required to answer your support email, and inform you when
your prepaid support time has expired.
If you have a Radiator or RADIUS support contract, you may send email to
[email protected]

Include your support contract identifier in the Subject line. If you dont have a support
contract, we will not respond to your query on this address.
If you need an urgent response outside of the standard email support hours, you may
want to post to the Radiator mailing list instead. Someone will be sure to be awake
somewhere in the world.
26.2 No support contract
The standard Radiator license does not include support, but it does include the full
source code and free access to the Radiator mailing list. This means you can help yourself, and you can work with other Radiator users in the user community. In order to participate with others in this effort, you can join the Radiator mailing list at:
https://www.open.com.au/mailman/listinfo/radiator

The staff of OSC monitor the Radiator mailing list and frequently answer questions. Its
very active so dont hesitate to use it. There is an archive of the mailing list available at
http://www.open.com.au/pipermail/radiator/
Please, dont post HTML to the Radiator mailing list. Not everyone is using HTML
compatible mailers.

Radiator RADIUS Server

395 of 397

Getting Help

26.3 What to do if you need help

Before you post to the support address or mailing list asking for assistance, we suggest
you go through the following check list:
1. Consult this reference manual.
2. Consult the FAQ at http://www.open.com.au/radiator/faq.html for extra hints and

up-to-date information.
3. Consult the mailing list archive at http://www.open.com.au/pipermail/

radiator/for more hints. You can search this archive for items related to your
problem.
4. Check that you are using the latest version of Radiator. See

http://www.open.com.au/radiator/downloads.html, use the username and password

we have issued to you. Upgrade if you need to.
5. Check whether there are any patches that address your problem. See the index file in

the patches directory for your release at

http://www.open.com.au/radiator/downloads.html. Apply the patch set if you think
you might need it.

6. If you still have the problem, post to the mailing list by mailing to:

[email protected]. If you have a support contract, send email to

[email protected].
Be sure to include at least the following information:

Your company name and license details.

A detailed description of the problem.
Your Radiator configuration file (remove any secrets and passwords first).
An extract from your Radiator log file (with Trace level of 4) illustrating the problem, or at least what is happening at the time of the problem.

Details of the computer type, operating system etc.

7. Professional services for design, installation, configuration and training are available

with hourly and daily rates. Send requests to [email protected].

This information helps people to understand your problem and help find a solution more
quickly.
26.4 Announcements
There is a separate Radiator mailing list that just carries product announcements and
upgrades. If you want to know about upgrades available, but do not want all the technical volume from the normal mailing list, this may be the one for you. Radiator product
announcements will be posted to both lists.
You can join the Radiator Announcements mailing list by sending email with the single
word subscribe in the body (not in the subject line) to
[email protected]

396 of 397

Radiator RADIUS Server

Getting Help

26.5 Bug reports

We are interested in your feedback, both positive and negative, and bug reports. Please
send them to [email protected]. Licensees are entitled to free upgrades, and we do fix
bugs that are reported to us, so if you report a bug, you can expect to get an upgrade
with a fix one day. If you dont report it, it might never get fixed.
26.6 RFCs
A number of relevant RFCs can be found in the doc directory of the Radiator distribution. A full set of RFCs including the ones relevant to RADIUS, RFC 2865 and RFC
2866, can be found at
http://tools.ietf.org/html/

Radiator RADIUS Server

397 of 397