Skip to content

Commit 47a0d04

Browse files
alandekokalandekok
committed
add example of converting v3 home_server_pool to v4
1 parent 9fd40f3 commit 47a0d04

3 files changed

Lines changed: 230 additions & 0 deletions

File tree

‎doc/antora/modules/reference/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@
233233
***** xref:raddb/mods-available/isc_dhcp.adoc[ISC DHCP]
234234
**** xref:raddb/mods-available/radius.adoc[RADIUS]
235235
***** xref:raddb/mods-available/cui.adoc[CUI]
236+
***** xref:raddb/mods-available/home_server_pool.adoc[home_server_pool]
236237
***** xref:raddb/mods-available/wimax.adoc[WiMAX]
237238

238239
*** xref:raddb/mods-available/doc/utility.adoc[Utility]

‎doc/antora/modules/reference/pages/raddb/mods-available/home_server_pool.adoc‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
2+
3+
4+
5+
= home_server_pool Example
6+
7+
This configuration file is an example of how to translate a v3
8+
`home_server_pool` into a v4 configuration.
9+
10+
You should not enable this module, as it does not contain the IP
11+
address, port, and secret information for your local network.
12+
Instead, you can use this file as template to translate a v3
13+
`home_server_pool` configuration into a v4 configuration.
14+
15+
16+
17+
== Name and Type
18+
19+
In v3, we have:
20+
21+
22+
23+
This translates to a `load-balance` section with name `pool1`, and the following contents.
24+
25+
26+
`home1`, `home2`, and `home3` should be instances of the `radius` module.
27+
28+
29+
If you are using a Load-Balance-Key in v3, that can be translated
30+
to a v4 configuration by simply specifying an option to the
31+
`load-balance` section. For example, to load balance on
32+
`link:https://freeradius.org/rfc/rfc2865.html#Calling-Station-Id[Calling-Station-Id]`, the above `pool1` configuration can be
33+
modified with one addition:
34+
35+
36+
See the `load-balance` keyword documentation for more information.
37+
38+
39+
40+
== Using the home_server_pool
41+
42+
In this configuration, `pool1` is a _virtual module_. That is, it
43+
can be referred to by name as a module: `pool1`. This name can be
44+
used anywhere that a module name is allowed.
45+
46+
The need to use the pool as a module is the one major difference in
47+
proxying between v3 and v4. In v3, proxying was an automatic thing
48+
that happened when a special attribute got set.
49+
e.g. `Proxy-To-Realm = ...`, or `Home-Server = ...`.
50+
51+
In v4, proxying happens only when you explicitly configure the
52+
server to run the `radius` module. The simplest way to do this is
53+
to add a section:
54+
55+
56+
And then set `Auth-Type := proxy`. See the sites-available/proxy
57+
example for more information.
58+
59+
60+
61+
62+
== home_server Example
63+
64+
In v3, we have:
65+
66+
67+
This translates to the `radius` module, with name `home1`, and the following contents.
68+
69+
See the `radius` module for more information about its full configuration.
70+
71+
72+
73+
74+
75+
You can add `home2`, `home3`, etc. here. They do not need to be in separate files.
76+
77+
78+
== Default Configuration
79+
80+
```
81+
# home_server_pool pool1 {
82+
# type = load-balance
83+
# home_server = home1
84+
# home_server = home2
85+
# home_server = home3
86+
# }
87+
load-balance pool1 {
88+
home1
89+
home2
90+
home3
91+
}
92+
# load-balance pool1 Calling-Station-Id {
93+
# ...
94+
# }
95+
# authenticate proxy {
96+
# pool1
97+
# }
98+
# home_server radius1 {
99+
# type = auth+acct
100+
# ipaddr = 192.0.2.1
101+
# port = 1812
102+
# secret = testing123
103+
# }
104+
radius home1 {
105+
transport = udp
106+
type = Access-Request
107+
type = Accounting-Request
108+
udp {
109+
ipaddr = 192.0.2.1
110+
port = 1812
111+
secret = testing123
112+
}
113+
}
114+
```
115+
116+
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
117+
// This documentation was developed by Network RADIUS SAS.

‎raddb/mods-available/home_server_pool‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# -*- text -*-
2+
#
3+
#
4+
# $Id$
5+
6+
#######################################################################
7+
#
8+
# = home_server_pool Example
9+
#
10+
# This configuration file is an example of how to translate a v3
11+
# `home_server_pool` into a v4 configuration.
12+
#
13+
# You should not enable this module, as it does not contain the IP
14+
# address, port, and secret information for your local network.
15+
# Instead, you can use this file as template to translate a v3
16+
# `home_server_pool` configuration into a v4 configuration.
17+
#
18+
19+
#
20+
# == Name and Type
21+
#
22+
# In v3, we have:
23+
#
24+
# home_server_pool pool1 {
25+
# type = load-balance
26+
#
27+
# home_server = home1
28+
# home_server = home2
29+
# home_server = home3
30+
# }
31+
#
32+
# This translates to a `load-balance` section with name `pool1`, and the following contents.
33+
#
34+
load-balance pool1 {
35+
#
36+
# `home1`, `home2`, and `home3` should be instances of the `radius` module.
37+
#
38+
home1
39+
home2
40+
home3
41+
}
42+
#
43+
# If you are using a Load-Balance-Key in v3, that can be translated
44+
# to a v4 configuration by simply specifying an option to the
45+
# `load-balance` section. For example, to load balance on
46+
# `Calling-Station-Id`, the above `pool1` configuration can be
47+
# modified with one addition:
48+
#
49+
# load-balance pool1 Calling-Station-Id {
50+
# ...
51+
# }
52+
#
53+
# See the `load-balance` keyword documentation for more information.
54+
#
55+
56+
#
57+
# == Using the home_server_pool
58+
#
59+
# In this configuration, `pool1` is a _virtual module_. That is, it
60+
# can be referred to by name as a module: `pool1`. This name can be
61+
# used anywhere that a module name is allowed.
62+
#
63+
# The need to use the pool as a module is the one major difference in
64+
# proxying between v3 and v4. In v3, proxying was an automatic thing
65+
# that happened when a special attribute got set.
66+
# e.g. `Proxy-To-Realm = ...`, or `Home-Server = ...`.
67+
#
68+
# In v4, proxying happens only when you explicitly configure the
69+
# server to run the `radius` module. The simplest way to do this is
70+
# to add a section:
71+
#
72+
# authenticate proxy {
73+
# pool1
74+
# }
75+
#
76+
# And then set `Auth-Type := proxy`. See the sites-available/proxy
77+
# example for more information.
78+
#
79+
#
80+
81+
#
82+
# == home_server Example
83+
#
84+
# In v3, we have:
85+
#
86+
# home_server radius1 {
87+
# type = auth+acct
88+
# ipaddr = 192.0.2.1
89+
# port = 1812
90+
# secret = testing123
91+
# }
92+
#
93+
# This translates to the `radius` module, with name `home1`, and the following contents.
94+
#
95+
# See the `radius` module for more information about its full configuration.
96+
#
97+
radius home1 {
98+
transport = udp
99+
100+
type = Access-Request
101+
type = Accounting-Request
102+
103+
udp {
104+
ipaddr = 192.0.2.1
105+
port = 1812
106+
secret = testing123
107+
}
108+
}
109+
110+
#
111+
# You can add `home2`, `home3`, etc. here. They do not need to be in separate files.
112+
#

0 commit comments

Comments
 (0)
⚡