== Enabling PROXY Protocol
-Now that we have a working configuration in which RadSec connections from the
-test client are successfully proxied to the RadSec server via HAproxy and/or
-Traefik we are finally ready to enable PROXY Protocol.
+Now that we have a working configuration which used RadSec and HAproxy
+or Traefik, we are finally ready to enable PROXY Protocol.
-Configure FreeRADIUS on `radsecsvr` to expect PROXY Protocol for RadSec
-connections by editing the `listen {}` section of the `tls` virtual server to
-include the following:
+Configure FreeRADIUS on the `radsecsvr` host to expect the PROXY
+Protocol for RadSec connections. This is done by editing the `listen
+{}` section of the `tls` virtual server to include a reference to the
+proxy protocol:
.Enabling PROXY Protocol in a FreeRADIUS virtual server
=======================================================
----
-For HAproxy, enable PROXY Protocol on connections to the RadSec backend by
-amending the backends as follows:
+For HAproxy, you should enable the PROXY Protocol on connections to
+the RadSec backend, by editing the `backend` definition to add a
+`send-proxy` argument:
.Example HAproxy backend configuration with PROXY Protocol
==========================================================
==========================================================
-Note the `send-proxy` argument in the server definition.
+Note the `send-proxy` argument in the `server` definition.
Now reload the HAproxy service:
- service haproxy reload
+[source,shell]
+----
+service haproxy reload
+---
-For Traefik, enable PROXY Protocol on connections to the RadSec backend by
-amending the `radsec-service` definition, as follows:
+For Traefik, enable the PROXY Protocol on connections to the RadSec
+backend by editing the `radsec-service` definition to add a reference
+to the proxy protocol"
.Example Traefik service configuration with PROXY Protocol
==========================================================
Note the `proxyProtocol` and `version: 1` directives.
-Traefik should automatically detect the updates and reconfigure the service.
+Traefik should automatically detect the updates and reconfigure the
+service.
=== Testing RadSec connectivity via a proxy using PROXY Protocol
-Finally, with your test client configured to use the correct proxy homeserver,
-perform a test authentication:
+Finally, with your test client configured to use the proxy, perform a
+test authentication:
[source,shell]
----
======================================================
-The output indicates that FreeRADIUS is receiving the originating connection
-information for the RadSec connection using PROXY Protocol. It is then treating
-requests that are sent over the proxied RadSec connection as though they were
-being received directly from the originating client.
+The output indicates that FreeRADIUS is receiving the originating
+connection information from the PROXY Protocol. FreeRADIUS then
+handles the RadSec requests as though they have been received directly
+from the originating client.
Our first task is to set up a RadSec server by configuring an instance of
FreeRADIUS to accept RADIUS over TLS requests.
-The following steps should be performed on the `radsecsvr` host.
+The following steps should be performed on the host which will be the
+RadSec server, we will call it `radsecsvr`.
-Install FreeRADIUS using the NetworkRADIUS packages by following the
-instructions provided here:
+You can install FreeRADIUS using the NetworkRADIUS packages by
+following the instructions provided here:
<https://networkradius.com/packages/>
-Stop the radiusd service:
+Before making any configuration changes, you should stop the radiusd
+service:
[source,shell]
----
service radiusd stop
----
-Enable the `tls` virtual server:
+Then, enable the `tls` virtual server:
[source,shell]
----
ln -s ../sites-available/tls
----
-The FreeRADIUS distribution contains an example Certificate Authority that will
-have generated the necessary CA, server and client certificates and keys during
-package installation.
+The FreeRADIUS distribution contains an example Certificate Authority
+that will have generated the necessary CA, server and client
+certificates and keys during package installation. You can use this
+CA, or you can use your own CA and certificates.
[TIP]
====
-If the example certificates are not present (for example of FreeRADIUS was
-installed from source) then FreeRADIUS will fail to start up. They can be
+If the example certificates are not present (for example if FreeRADIUS was
+installed from source) then FreeRADIUS will fail to start. The files can be
regenerated by running `make` in the `/etc/raddb/certs` directory.
====
-Edit the `tls` virtual server configuration to add definitions for the possible
-clients by extending the `clients radsec {}` section:
+Edit the `tls` virtual server configuration, in order to add
+definitions for the clients by extending the `clients radsec {}` section:
.Example radsec client definitions in `/etc/raddb/sites-available/tls`
====
====
-The client `ipaddr` configuration item is used to match the source IP address
-of incoming connections. You must therefore add client definitions for each
-of the proxy servers for the case where clients are connected via proxy.
-
-When a proxy server is used FreeRADIUS will treat the proxy server as the
-client and its corresponding configuration items will be in effect for all
-clients connecting via the proxy. This is the case until PROXY Protocol is
-enabled, after which the proxy server's configuration will only be used to
-accept the connection. After receiving the original connection data via PROXY
-Protocol the indicated client's definition will be used, allowing you to
-configure distinct `virtual_servers` to handle requests for each end client.
-
-In the case that a client using a proxy with PROXY Protocol enabled is unknown,
-the connection will be immediately closed.
+The client `ipaddr` configuration item is used to match the source IP
+address of incoming connections. You must add client definitions for
+each of the clients which will connect.
+For RadSec, you can just list the IP address of the RadSec client.
+This client definition is used for processing RADIUS packets from the
+RadSec client.
[NOTE]
====
-The RadSec protocol always uses the shared secret "radsec" which does not need
-to be provided since it is the default.
+A `secret` does not have to be specified for RadSec clients, as the
+default is `radsec`. If you specify a secret, then that will be used
+instead of `radsec`.
====
-For testing purposes, we want to amend the `default` virtual server so that it
-unconditionally accepts authenticaiton reqeusts and immediately responds to
-accounting requests.
+When the PROXY protocol is used, you must _also_ define a client which
+matches the IP address of the proxy (haproxy, etc). This client is
+only used to check that the source IP is permitted to connect to the
+server. Fields other than `ipaddr` can be specified (and in some
+cases may be required). However, all other fields will be ignored.
+
+For testing purposes, we want to amend the `default` virtual server so
+that it accepts all authentication reqeusts and immediately responds
+to accounting requests.
-Amending the `/etc/raddb/sites-enabled/default` file such that the beginning of
-the `authorize` and `preacct` sections is as follows:
+Edit the `/etc/raddb/sites-enabled/default` file so that the beginning of
+the `authorize` and `preacct` sections looks as follows:
.Example default virtual server modification to unconditionally accept Access-Requests
====
====
+This change makes the `authorize` section always "accept" the user,
+and makes the `preacct` section always say "we handled the accounting
+request". These changes are only for testing, and should never be
+used in production.
+
Start the FreeRADIUS service in the foreground with debugging enabled:
[source,shell]
====
-FreeRADIUS is now ready to process RadSec traffic, but PROXY Protocol is not
-yet enabled.
-
-Our strategy is to first test basic RADIUS over UDP functionality, then
-exercise the RadSec connection using a test client, then introduce a proxy
-server, and finally enable PROXY Protocol.
+FreeRADIUS is now ready to process RadSec traffic.
+For testing, we first test normal RADIUS over UDP functionality, then
+the RadSec connection using a test client, then introduce a proxy
+server, and finally we enable PROXY Protocol. Doing the tests in this
+way ensures that we know that all previous steps work before trying
+the next step. This process allows us to quickly narrow down
+problems, and gets us to the final goal _faster_ than just "doing
+everything all at once".
=== Testing the RADIUS policy
-Before moving on, verify that the FreeRADIUS policy is able to authenticate a
-local test RADIUS Access-Request over UDP:
+Before moving on, verify that the FreeRADIUS policy is able to
+authenticate a local test RADIUS Access-Request over UDP:
[source,shell]
----
echo "User-Name = terry" | radclient 127.0.0.1 auth testing123
----
-Due to the test policy modification made above the expected output should
-indicate that an Access-Accept is received:
+Due to the `accept` we added in the `authorize` section, the expected
+output should be an Access-Accept:
.Expected output from radclient
===============================
===============================
Any other output indicates that there is a problem with the FreeRADIUS
-configuration which must be solved before testing RadSec. Carefully verify that
+configuration which *must* be solved before testing RadSec. Carefully verify that
you have carried out each of the above steps correctly and examine the debug
-output from FreeRADIUS which will usually tell you what is wrong.
+output from FreeRADIUS, which will usually tell you what is wrong.
+
+See [how to read the debug
+output](http://wiki.freeradius.org/radiusd-X) for instructions on
+reading amd understanding the debug output.
-Now we must xref:protocols/proxy/radsec_client.adoc[configure FreeRADIUS as a
-RadSec test client] so that we can verify that our RadSec server is working
-properly.
+The next step is to xref:protocols/proxy/radsec_client.adoc[configure
+FreeRADIUS as a RadSec test client] so that we can verify that our
+RadSec server is working.
== Configuring FreeRADIUS as a RadSec test client
-The FreeRADIUS client utilities do not directly support making RadSec
-connections. We must therefore configure an instance FreeRADIUS as a transport
-converter that proxies UDP-based RADIUS requests to a RadSec destination of our
-choice.
+Unfortunately, the `radclient` program does not support RadSec. We
+must therefore configure an instance of FreeRADIUS as a "transport
+converter" which proxies UDP-based RADIUS requests to a RadSec
+destination of our choice.
-The following steps should be performed on the `radseccli` host.
+The following steps should be performed on a client system, which we
+will call `radseccli`. This system should be a new system, with a
+different IP address. That is, you shoudl not edit the configuration
+on the `radsecsvr` host. Doing so will break the RadSec configuration.
Install FreeRADIUS using the NetworkRADIUS packages by following the
instructions provided here:
<https://networkradius.com/packages/>
-Stop the radiusd service:
+Before making any configuration changes, you should stop the radiusd
+service:
[source,shell]
----
service radiusd stop
----
-Add a new `tls` homeserver definition that we will initially point directly to
-our FreeRADIUS RadSec server by creating a file
-`/etc/raddb/sites-enabled/radsec-homeserver` with the following contents:
+Add a new `tls` home server definition, which will point to the RadSec
+server. We do this by creating a file
+`/etc/raddb/sites-enabled/radsec-homeserver` with the following
+contents:
.Example homeserver, pool and realm definitions for the RadSec service
====
home_server tls {
- ipaddr = 172.23.0.3 # Initially directly to our RadSec server
+ ipaddr = 172.23.0.3 # IP address of our RadSec server
port = 2083
type = auth+acct
proto = tcp
[TIP]
====
-Descriptions of each of the above configuration items can be found in the
-`[raddb]/sites-available/tls` example site, however for testing purposes the
-above will suffice.
+Complete descriptions of each of the above configuration items can be found in the
+`[raddb]/sites-available/tls` example configuration file. For simple tests, however,
+we can omit all of the comments from the file.
====
-To use this `tls` homeserver we modify the `default` virtual server to proxy
-all authentication and accounting requests by amending the
-`/etc/raddb/sites-enabled/default` file such that the beginning of the
-`authorize` and `preacct` sections is as follows:
+To use this `tls` home server, we change the `default` virtual server to proxy
+all authentication and accounting requests to it.
+
+Edit the `/etc/raddb/sites-enabled/default` file so that the beginning of
+the `authorize` and `preacct` sections looks as follows:
.Example default virtual server modification to proxy requests to a RadSec proxy server
====
====
-We must now copy the example CA certificate as well as the client certificate
-and key files that were generated automatically during the installation of
-FreeRADIUS on the `radsecsrv` host to this test client.
+These changes make the `tls` virtual server always proxy packets.
+These changes are only for testing, and should never be used in
+production.
+
+We must now copy the example CA certificate as well as the client
+certificate and key files which are on the `radsecsrv` host to this
+test client.
Replace the following files on `radseccli` with the equivalent files from
`radsecsrv`:
|/etc/raddb/certs/ca.pem
|`ca_file`
-|CA certificate that is used to authenticate the server certificate presented to the client by the RadSec server
+|CA certificate which is used to authenticate the server certificate presented by the RadSec server to the client.
|/etc/raddb/certs/client.pem
|`certificate_file`
-|Client certificate (signed by the CA certificate) that is presented by the test client to the RadSec server
+|Client certificate (signed by the CA certificate) that is presented by the test client to the RadSec server.
|/etc/raddb/certs/client.pem
|`private_key_file` and `private_key_password`
|Private key corresponding to the client certificate
|===
-Note that the client certificate and key are bundled into a single file.
+Note that the client certificate and key are typically bundled into a single file.
[CAUTION]
====
-If you do not correctly replace the CA and client certificate and key material
-on the test client then the RadSec client and RadSec server will fail to
-mutually authenticate each other since they will not be operating under the
-same CA.
+If you do not correctly replace the CA, client certificate, and key
+material on the test client then the RadSec client and RadSec server
+will fail to mutually authenticate each other as they do not share a
+trusted CA. If you see messages like `unknown CA`, then you know that
+the certificates have not been set up correctly.
====
Start the FreeRADIUS service in debug mode:
requests directly to the RadSec server.
Run the following to send a RADUS (UDP) Access-Request to the local FreeRADIUS
-instance which should proxy the request by making a RadSec connection to
+instance. It should then proxy the request over RadSec connection to
the remote RadSec server:
[source,shell]
echo "User-Name = bob" | radclient 127.0.0.1 auth testing123
----
-If the test client is able to successfully establish the RadSec connection and
-the RadSec server replies with an Access-Accept response then the output will
-be as follows:
+If the test client is able to successfully establish the RadSec
+connection, and the RadSec server replies with an Access-Accept
+response, then the output will be as follows:
.Expected output from radclient
===============================
server. In many cases it will tell you exactly what the problem is.
Do not proceed with any further steps until direct connections between the
-RadSec client and FreeRADIUS are working properly.
+RadSec client and Radsec Server are working properly.
Once things are working we are ready to
xref:protocols/proxy/radsec_with_haproxy.adoc[configure HAproxy to proxy RadSec
connections] or to xref:protocols/proxy/radsec_with_traefik.adoc[configure
Traefik to proxy RadSec connections].
-
======================================
-Note the `mode tcp` directive which tells HAproxy to act as a Layer 4 proxy so
-that it doesn't attempt to perform SSL termination or to decode the protocol.
+Note the `mode tcp` directive which tells HAproxy to act as a Layer 4
+proxy, so that it doesn't attempt to perform SSL termination or
+decode the RADIUS protocol.
[NOTE]
====
configuration will conflict with `mode tcp` (Layer 4 proxying) and should be
removed if HAproxy complains about them.
-However, you should first get things working with the minimal configuration
-which is known to work, and them make customisations.
+However, you should first get things working with the minimal
+configuration which is known to work, and then make customisations.
+If you start off with a complex configuration, then there may be a
+large number of things which are broken, and debugging them all will
+be difficult. Start simple, and then add complexity!
====
Restart the haproxy service in foreground mode for debugging purposes:
=== Testing RadSec connectivity via HAproxy
-Now amend the test RadSec client so that instead of making connections directly
-to the RadSec server it makes them via HAproxy.
+Now edit the test RadSec client, so that instead of making connections directly
+to the RadSec server it makes connections to the HAproxy server.
-On `radseccli` amend `/etc/raddb/sites-enabled/tls` and set the IP address to
-that of the `haproxy` host.
+On `radseccli` edit the `/etc/raddb/sites-enabled/tls` file, and set
+the IP address to the address of the `haproxy` host.
.Example updated test client homeserver configuration
=====================================================
echo "User-Name = bob" | radclient 127.0.0.1 auth testing123
----
-If the test client is able to successfully establish the RadSec connection via
-HAproxy and the RadSec server replies with an Access-Accept response then the
-output will be as follows:
+If the test client is able to successfully establish the RadSec
+connection via HAproxy, and the RadSec server replies with an
+Access-Accept response, then the output will be as follows:
.Expected output from radclient
===============================
=============================
-Any other output from radclient or HAproxy indicates that there is a problem
-with the HAproxy configuration or that FreeRADIUS is not accepting connection
-from the `haproxy` host, which must be solved before continuing.
+Any other output from radclient or HAproxy indicates that there is a
+problem with the HAproxy configuration, or that FreeRADIUS is not
+accepting connection from the `haproxy` host, which must be solved
+before continuing.
Once proxied connections are working we are ready to
-xref:protocols/proxy/enable_proxy_protocol.adoc[enable the PROXY Protocol] on
-both HAproxy and the RadSec server.
+xref:protocols/proxy/enable_proxy_protocol.adoc[enable the PROXY
+Protocol] on both HAproxy and the RadSec server.
projects / thirdparty / freeradius-server.git / commitdiff
