Adding upstream version 3.2.5+dfsg.upstream/3.2.5+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 484 insertions, 3 deletions

diff --git a/doc/antora/modules/howto/pages/monitoring/index.adoc b/doc/antora/modules/howto/pages/monitoring/index.adoc
new file mode 100644
index 0000000..a08ffb4
--- /dev/null
+++ b/doc/antora/modules/howto/pages/monitoring/index.adoc
@@ -0,0 +1,67 @@
+= Monitoring
+
+Any good systems administrator will want to know how well
+their systems are operating, both to catch issues before they
+become a serious problem, or for long term analysis.
+The term "monitoring" can encompass all kinds of watching how the
+system is working, from generating and watching logs, gathering
+statistics or ensuring that the service daemon is still running
+and serving requests.
+
+We break the different types of monitoring down into the following
+sections.
+
+== Service checking
+
+Checking the running service can include the following:
+
+* Ensuring the daemon is still running, i.e. process monitoring
+* Sending regular RADIUS authentication or accounting requests and checking they are correctly responded to
+* Sending Status-Server RADIUS requests
+
+Within a proxy environment FreeRADIUS needs to know if upstream
+proxies are available. It can do this itself using the latter two
+options above.
+
+== Logging
+
+System logs are often the most critical part of a RADIUS system.
+They are necessary for the administrator to know who has logged in
+and when, for debugging purposes such as when an end user cannot
+connect, and often for regulatory or compliance purposes.
+
+RADIUS server logs are also often used as a basic form of
+recording accounting requests, which are in and of themselves a
+form of logging by the NAS. Getting correct logging systems
+operational is key to running an efficient and easy to maintain
+RADIUS server.
+
+FreeRADIUS has many options for being able to generate and store
+logs, including the following:
+
+* Main daemon logging, configured in `radiusd.conf`
+* Line-based text logging, using `rlm_linelog`
+* Detailed RADIUS packet logs, using `rlm_detail`
+
+As well as recording direct to disk, the above can be sent via a
+local syslog server, which opens up many opportunities for central
+logging.
+
+It is possible to integrate FreeRADIUS into other more complicated
+logging systems, some options may include:
+
+* To CSV files, for example via `rlm_linelog`
+* Writing entries to an SQL database using `rlm_sql`
+* Into a log management system such as Elasticsearch or Graylog
+
+
+== Statistics gathering
+
+It is often useful to collect statistics from a running RADIUS
+server. These are often plotted on graphs to show current load or
+for trend analysis, as well as an indication of system operation.
+
+Statistics are usually gathered in two ways:
+
+* FreeRADIUS xref:monitoring/statistics.adoc[internal statistics]
+* Analysing logs with some external tool
diff --git a/doc/antora/modules/howto/pages/monitoring/statistics.adoc b/doc/antora/modules/howto/pages/monitoring/statistics.adoc
new file mode 100644
index 0000000..0583f0a
--- /dev/null
+++ b/doc/antora/modules/howto/pages/monitoring/statistics.adoc
@@ -0,0 +1,336 @@
+= Server statistics
+
+FreeRADIUS collects statistics internally about certain operations
+it is doing, such as the number of authentication and accounting
+requests, how many accepts and failures, and server queue lengths.
+These can be queried by sending a specially-crafted RADIUS
+`Status-Server` packet to a "status" virtual server.
+
+== Configuring the status virtual server
+
+The `status` virtual server is present in the default
+configuration, but needs to be enabled before it can be used. To
+do this, create a symlink from `sites-enabled/status` to
+`../sites-available/status`:
+
+[source,shell]
+----
+# cd raddb/sites-enabled
+# ln -s ../sites-available/status
+----
+
+[NOTE]
+====
+If you are not starting from the default configuration, check that
+`status_server` is still set to `yes` in `raddb/radiusd.conf` as
+well.
+====
+
+While the default configuration will work for most setups, you may
+edit the virtual server configuration in `sites-enabled/status`.
+No major changes are necessary here, though the default secret,
+`adminsecret`, should be changed. Other possible changes may be
+the listening IP address and port, and the clients that are
+allowed to connect. By default, connections are restricted to the
+local host only.
+
+Having enabled and configured the status server, restart
+FreeRADIUS to make it active.
+
+== Querying the server
+
+To get the current statistics from the server, send a RADIUS
+request of type `Status-Server` to the status port. Unless edited
+above, the request must come from the same server that FreeRADIUS
+is running on, and be sent to port 18121 with the secret
+'adminsecret' . At a minimum, the `FreeRADIUS-Statistics-Type`
+attribute must be set. For example:
+
+    $ cat <<EOF | radclient -x localhost:18121 status adminsecret
+    > FreeRADIUS-Statistics-Type = 0x01
+    > Message-Authenticator = 0x00
+    > EOF
+    Sent Status-Server Id 145 from 0.0.0.0:b852 to 127.0.0.1:18121 length 62
+        FreeRADIUS-Statistics-Type = Authentication
+        Message-Authenticator = 0x00
+    Received Access-Accept Id 145 from 127.0.0.1:46c9 to 127.0.0.1:47186 length 152
+        FreeRADIUS-Total-Access-Requests = 27
+        FreeRADIUS-Total-Access-Accepts = 20
+        FreeRADIUS-Total-Access-Rejects = 1
+        FreeRADIUS-Total-Access-Challenges = 0
+        FreeRADIUS-Total-Auth-Responses = 5
+        FreeRADIUS-Total-Auth-Duplicate-Requests = 0
+        FreeRADIUS-Total-Auth-Malformed-Requests = 0
+        FreeRADIUS-Total-Auth-Invalid-Requests = 0
+        FreeRADIUS-Total-Auth-Dropped-Requests = 0
+        FreeRADIUS-Total-Auth-Unknown-Types = 0
+        FreeRADIUS-Total-Auth-Conflicts = 0
+
+The `FreeRADIUS-Statistics-Type` attribute is a bitmask - add
+together the following numbers to select the statistics required.
+Some options are mutually exclusive, so it might be necessary to
+send multiple requests to collect all information.
+
+[%header,cols="2,1,1,5"]
+|===
+|Name|Hex value|Decimal value|Description
+
+|Authentication
+|0x01
+|1
+|Stats about authentications
+
+|Accounting
+|0x02
+|2
+|Stats about accounting
+
+|Proxy Auth
+|0x04
+|4
+|Proxied authentication requests
+
+|Proxy Accounting
+|0x08
+|8
+|Proxied accounting requests
+
+|Internal
+|0x10
+|16
+|Queue lengths, thread information etc.
+
+|Client
+|0x20
+|32
+|Statistics about RADIUS clients e.g. defined in `clients.conf`
+
+|Server
+|0x40
+|64
+|Statistics about server 'listen' sockets e.g. in `sites-enabled/*`
+
+|Home Server
+|0x80
+|128
+|Statistics about a proxy home servers e.g. in `proxy.conf`
+|===
+
+== Worked examples
+
+To show the statistics available, a few examples follow.
+
+=== Global server authentications
+
+Using `FreeRADIUS-Statistics-Type = 0x01` requests stats about
+authentications. Because, for example, no "Client" qualifier has
+been added (`0x20`) the numbers are global to the server.
+
+[source,shell]
+----
+# cat <<EOF | radclient -x localhost:18121 status adminsecret
+FreeRADIUS-Statistics-Type = 0x01
+Message-Authenticator=0x00
+EOF
+Sent Status-Server Id 90 from 0.0.0.0:e008 to 127.0.0.1:18121 length 50
+	FreeRADIUS-Statistics-Type = Authentication
+	Message-Authenticator = 0x00
+Received Access-Accept Id 90 from 127.0.0.1:46c9 to 127.0.0.1:57352 length 152
+	FreeRADIUS-Total-Access-Requests = 133
+	FreeRADIUS-Total-Access-Accepts = 114
+	FreeRADIUS-Total-Access-Rejects = 13
+	FreeRADIUS-Total-Access-Challenges = 0
+	FreeRADIUS-Total-Auth-Responses = 127
+	FreeRADIUS-Total-Auth-Duplicate-Requests = 0
+	FreeRADIUS-Total-Auth-Malformed-Requests = 0
+	FreeRADIUS-Total-Auth-Invalid-Requests = 0
+	FreeRADIUS-Total-Auth-Dropped-Requests = 0
+	FreeRADIUS-Total-Auth-Unknown-Types = 0
+	FreeRADIUS-Total-Auth-Conflicts = 0
+----
+
+=== Global server authentication and accounting requests
+
+Sending `0x01` requests authentication statistics, and `0x02`
+requests accounting stats. To get both in one result, add them
+together, so we requst `0x03`. In this example we send decimal
+rather than hexadecimal.
+
+[source,shell]
+----
+# cat <<EOF | radclient -x localhost:18121 status adminsecret
+FreeRADIUS-Statistics-Type = 3
+Message-Authenticator=0x00
+EOF
+Sent Status-Server Id 216 from 0.0.0.0:ce7b to 127.0.0.1:18121 length 50
+	FreeRADIUS-Statistics-Type = Auth-Acct
+	Message-Authenticator = 0x00
+Received Access-Accept Id 216 from 127.0.0.1:46c9 to 127.0.0.1:52859 length 248
+	FreeRADIUS-Total-Access-Requests = 542
+	FreeRADIUS-Total-Access-Accepts = 451
+	FreeRADIUS-Total-Access-Rejects = 81
+	FreeRADIUS-Total-Access-Challenges = 0
+	FreeRADIUS-Total-Auth-Responses = 532
+	FreeRADIUS-Total-Auth-Duplicate-Requests = 0
+	FreeRADIUS-Total-Auth-Malformed-Requests = 0
+	FreeRADIUS-Total-Auth-Invalid-Requests = 0
+	FreeRADIUS-Total-Auth-Dropped-Requests = 0
+	FreeRADIUS-Total-Auth-Unknown-Types = 0
+	FreeRADIUS-Total-Auth-Conflicts = 0
+	FreeRADIUS-Total-Accounting-Requests = 0
+	FreeRADIUS-Total-Accounting-Responses = 0
+	FreeRADIUS-Total-Acct-Duplicate-Requests = 0
+	FreeRADIUS-Total-Acct-Malformed-Requests = 0
+	FreeRADIUS-Total-Acct-Invalid-Requests = 0
+	FreeRADIUS-Total-Acct-Dropped-Requests = 0
+	FreeRADIUS-Total-Acct-Unknown-Types = 0
+	FreeRADIUS-Total-Acct-Conflicts = 0
+----
+
+=== Internal server stats
+
+The value `0x10` requests information about the server such as queue
+lengths and thread state.
+
+[source,shell]
+----
+# cat <<EOF | radclient -x localhost:18121 status adminsecret
+FreeRADIUS-Statistics-Type = 0x10
+Message-Authenticator=0x00
+EOF
+Sent Status-Server Id 158 from 0.0.0.0:a090 to 127.0.0.1:18121 length 50
+	FreeRADIUS-Statistics-Type = Internal
+	Message-Authenticator = 0x00
+Received Access-Accept Id 158 from 127.0.0.1:46c9 to 127.0.0.1:41104 length 164
+	FreeRADIUS-Stats-Start-Time = "Aug  3 2023 13:36:24 UTC"
+	FreeRADIUS-Stats-HUP-Time = "Aug  3 2023 13:36:24 UTC"
+	FreeRADIUS-Queue-Len-Internal = 0
+	FreeRADIUS-Queue-Len-Proxy = 0
+	FreeRADIUS-Queue-Len-Auth = 0
+	FreeRADIUS-Queue-Len-Acct = 0
+	FreeRADIUS-Queue-Len-Detail = 0
+	FreeRADIUS-Queue-PPS-In = 0
+	FreeRADIUS-Queue-PPS-Out = 0
+	FreeRADIUS-Stats-Threads-Active = 0
+	FreeRADIUS-Stats-Threads-Total = 0
+	FreeRADIUS-Stats-Threads-Max = 0
+----
+
+=== Complete global server information
+
+A useful common request is all information about the server on a
+global basis: internal stats (16 / `0x10`) plus authentications (1
+/ `0x01`), accounting (2 / `0x02`), proxy authentications (4 /
+`0x04`) and proxy accounting (8 / `0x08`). The value `All` is
+defined in the dictionary as `0x1f` (decimal 31) to cover
+this common eventuality, and is what we demonstrate here.
+
+[source,shell]
+----
+# cat <<EOF | radclient -x localhost:18121 status adminsecret
+FreeRADIUS-Statistics-Type = All
+Message-Authenticator=0x00
+EOF
+Sent Status-Server Id 4 from 0.0.0.0:9ee4 to 127.0.0.1:18121 length 50
+	FreeRADIUS-Statistics-Type = All
+	Message-Authenticator = 0x00
+Received Access-Accept Id 4 from 127.0.0.1:46c9 to 127.0.0.1:40676 length 596
+	FreeRADIUS-Total-Access-Requests = 792
+	FreeRADIUS-Total-Access-Accepts = 659
+	FreeRADIUS-Total-Access-Rejects = 122
+	FreeRADIUS-Total-Access-Challenges = 0
+	FreeRADIUS-Total-Auth-Responses = 781
+	FreeRADIUS-Total-Auth-Duplicate-Requests = 0
+	FreeRADIUS-Total-Auth-Malformed-Requests = 0
+	FreeRADIUS-Total-Auth-Invalid-Requests = 0
+	FreeRADIUS-Total-Auth-Dropped-Requests = 0
+	FreeRADIUS-Total-Auth-Unknown-Types = 0
+	FreeRADIUS-Total-Auth-Conflicts = 0
+	FreeRADIUS-Total-Accounting-Requests = 0
+	FreeRADIUS-Total-Accounting-Responses = 0
+	FreeRADIUS-Total-Acct-Duplicate-Requests = 0
+	FreeRADIUS-Total-Acct-Malformed-Requests = 0
+	FreeRADIUS-Total-Acct-Invalid-Requests = 0
+	FreeRADIUS-Total-Acct-Dropped-Requests = 0
+	FreeRADIUS-Total-Acct-Unknown-Types = 0
+	FreeRADIUS-Total-Acct-Conflicts = 0
+	FreeRADIUS-Total-Proxy-Access-Requests = 0
+	FreeRADIUS-Total-Proxy-Access-Accepts = 0
+	FreeRADIUS-Total-Proxy-Access-Rejects = 0
+	FreeRADIUS-Total-Proxy-Access-Challenges = 0
+	FreeRADIUS-Total-Proxy-Auth-Responses = 0
+	FreeRADIUS-Total-Proxy-Auth-Duplicate-Requests = 0
+	FreeRADIUS-Total-Proxy-Auth-Malformed-Requests = 0
+	FreeRADIUS-Total-Proxy-Auth-Invalid-Requests = 0
+	FreeRADIUS-Total-Proxy-Auth-Dropped-Requests = 0
+	FreeRADIUS-Total-Proxy-Auth-Unknown-Types = 0
+	FreeRADIUS-Total-Proxy-Accounting-Requests = 0
+	FreeRADIUS-Total-Proxy-Accounting-Responses = 0
+	FreeRADIUS-Total-Proxy-Acct-Duplicate-Requests = 0
+	FreeRADIUS-Total-Proxy-Acct-Malformed-Requests = 0
+	FreeRADIUS-Total-Proxy-Acct-Invalid-Requests = 0
+	FreeRADIUS-Total-Proxy-Acct-Dropped-Requests = 0
+	FreeRADIUS-Total-Proxy-Acct-Unknown-Types = 0
+	FreeRADIUS-Stats-Start-Time = "Aug  3 2023 13:36:24 UTC"
+	FreeRADIUS-Stats-HUP-Time = "Aug  3 2023 13:36:24 UTC"
+	FreeRADIUS-Queue-Len-Internal = 0
+	FreeRADIUS-Queue-Len-Proxy = 0
+	FreeRADIUS-Queue-Len-Auth = 0
+	FreeRADIUS-Queue-Len-Acct = 0
+	FreeRADIUS-Queue-Len-Detail = 0
+	FreeRADIUS-Queue-PPS-In = 0
+	FreeRADIUS-Queue-PPS-Out = 0
+	FreeRADIUS-Stats-Threads-Active = 0
+	FreeRADIUS-Stats-Threads-Total = 0
+	FreeRADIUS-Stats-Threads-Max = 0
+----
+
+=== Client statistics
+
+Data can be provided about each RADIUS client defined in the
+server. Note that this is for the client definition, not for each
+client that connects - if a client definition has a wide netmask
+and permits multiple clients to connect, the statistics will be
+aggregate for all clients using that definition.
+
+[NOTE]
+====
+It is not possible to request global server statistics
+concurrently with client statistics as both use the same reply
+attributes.
+====
+
+Here we request accounting data for one particular client by IP
+address.
+
+[source,shell]
+----
+# cat <<EOF | radclient -x localhost:18121 status adminsecret
+FreeRADIUS-Statistics-Type = 0x2f
+FreeRADIUS-Stats-Client-IP-Address = 172.16.0.10
+Message-Authenticator=0x00
+EOF
+Sent Status-Server Id 194 from 0.0.0.0:d897 to 127.0.0.1:18121 length 62
+	FreeRADIUS-Statistics-Type = 47
+	FreeRADIUS-Stats-Client-IP-Address = 172.16.0.10
+	Message-Authenticator = 0x00
+Received Access-Accept Id 194 from 127.0.0.1:46c9 to 127.0.0.1:55447 length 236
+	FreeRADIUS-Stats-Client-IP-Address = 172.16.0.10
+	FreeRADIUS-Total-Access-Requests = 1491
+	FreeRADIUS-Total-Access-Accepts = 1240
+	FreeRADIUS-Total-Access-Rejects = 246
+	FreeRADIUS-Total-Access-Challenges = 0
+	FreeRADIUS-Total-Auth-Responses = 1486
+	FreeRADIUS-Total-Auth-Duplicate-Requests = 0
+	FreeRADIUS-Total-Auth-Malformed-Requests = 0
+	FreeRADIUS-Total-Auth-Invalid-Requests = 0
+	FreeRADIUS-Total-Auth-Dropped-Requests = 0
+	FreeRADIUS-Total-Auth-Unknown-Types = 0
+	FreeRADIUS-Total-Accounting-Requests = 0
+	FreeRADIUS-Total-Accounting-Responses = 0
+	FreeRADIUS-Total-Acct-Duplicate-Requests = 0
+	FreeRADIUS-Total-Acct-Malformed-Requests = 0
+	FreeRADIUS-Total-Acct-Invalid-Requests = 0
+	FreeRADIUS-Total-Acct-Dropped-Requests = 0
+	FreeRADIUS-Total-Acct-Unknown-Types = 0
+----
diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc
index 949868d..ca4d98f 100644
--- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc
+++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc
@@ -1,6 +1,6 @@
 == Configure common reply options
 
-FreeRADIUS includes a powerful xref:unlang/index.adoc[policy language] called
+FreeRADIUS includes a powerful xref:index.adoc[policy language] called
 "unlang".
 
 Statements in unlang may be used to call further policies, update attribute
diff --git a/doc/antora/modules/howto/pages/protocols/proxy/enable_proxy_protocol.adoc b/doc/antora/modules/howto/pages/protocols/proxy/enable_proxy_protocol.adoc
index b689824..a4ab3db 100644
--- a/doc/antora/modules/howto/pages/protocols/proxy/enable_proxy_protocol.adoc
+++ b/doc/antora/modules/howto/pages/protocols/proxy/enable_proxy_protocol.adoc
@@ -47,7 +47,7 @@ Now reload the HAproxy service:
 [source,shell]
 ----
 service haproxy reload
----
+----
 
 
 For Traefik, enable the PROXY Protocol on connections to the RadSec
@@ -79,7 +79,7 @@ test authentication:
 
 [source,shell]
 ----
- echo "User-Name = bob" | radclient 127.0.0.1 auth testing123
+echo "User-Name = bob" | radclient 127.0.0.1 auth testing123
 ----
 
 You should expect to see the familiar output:
diff --git a/doc/antora/modules/howto/pages/simultaneous_use.adoc b/doc/antora/modules/howto/pages/simultaneous_use.adoc
new file mode 100644
index 0000000..b4a97ab
--- /dev/null
+++ b/doc/antora/modules/howto/pages/simultaneous_use.adoc
@@ -0,0 +1,78 @@
+= Simultaneous-Use checking
+
+There are a whole lot of pieces which have to work together for
+`Simultaneous-Use` to work.  In this guide, we assume that user
+sessions are stored in SQL.
+
+For `Simultaneous-Use` to work. the server needs to know who is
+online, which means that accounting must be configured and working.
+Start off by checking the basics, independent of `Simultaneous-Use`.
+
+As always, start off with reading the debug output, and use that
+information to answer a few questions.
+
+== Did the user get Access-Accept?
+
+*No* - Fix that.  Make sure that the user can be authenticated!
+
+*Yes* - FreeRADIUS told the NAS to allow the user online.  This usually
+ works, but perhaps the NAS disagreed, and still dropped the user.  It happens.
+
+The only way you know that a user is actually online is to check the
+accounting data.  So we will do that next.
+
+== Did the server then get an Accounting-Request for that user?
+
+*No* - The NAS isn't sending accounting packets, Simultaneous-Use will never work.
+
+Go fix the NAS so that it sends accounting packets.
+
+*Yes* - The NAS is telling FreeRADIUS that it allowed the user online,
+ and the user has an active session.  We now have to see where that data is stored.
+
+== Did the accounting data go into the radacct table?
+
+As always, Read the debug output.
+
+*No* - There is nothing in the debug output about radacct?  Configure the server to write accounting data to SQL 
+
+ou can use `radclient` to send fake accounting packets for testing.
+Use a real accounting packet as a template for input to `radclient`,
+but change the `User-Name` so that the tests don't affect real users.
+
+
+*Yes* - You see successful `INSERT` or `UPDATE` lines in `radacct`.   That's good!
+
+== One last check
+
+Double-check the radacct database using an SQL client.  Just to be sure that the data is really there.
+
+== It is now set up correctly to track user sessions
+
+If all that works, then the server is set up correctly to authenticate
+users, and to store their data in SQL.  This is the foundation for
+`Simultaneous-Use`.
+
+== Set Simultaneous-Use
+
+Then, configure the server to set `Simultaneous-Use=1`.  That tells the server to enforce `Simultaneous-Use`.  That configuration can go into the `files` module, `sql`, or whereever else you want.
+
+You will also need to configure the `default` virtual server to check session data in SQL.  Look for `Simultaneous-Use` in `sites-available/default`.  Uncomment the line containing `sql`
+
+== Double check that a user can still log in!
+
+Go through all of the above steps _again_, checking that the user can
+log in, and that the server is receiving accounting packets.
+
+This time, also look for the debug output to contain:
+
+```
+# Executing section session from file ...
+session {
+```
+
+That shows it is checking the `session` database.  If all goes well, the next few lines after that should show that it is checking `sql`.
+
+If the above text doesn't appear, then the server isn't getting told to set `Simultaneous-Use = 1`.  You will have to fix that before going to the next step.
+
+If the user has not logged in yet, you will see an `Access-Accept`.  Otherwise, if the user already has an active session, the server should say that the user is being rejected due to multiple logins.