From 44eafeee62e6982131c62df6f74335114ca53024 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 26 Aug 2024 12:41:52 +0200 Subject: Adding upstream version 3.2.5+dfsg. Signed-off-by: Daniel Baumann --- .../modules/howto/pages/monitoring/index.adoc | 67 ++++ .../modules/howto/pages/monitoring/statistics.adoc | 336 +++++++++++++++++++++ .../protocols/dhcp/policy_common_options.adoc | 2 +- .../protocols/proxy/enable_proxy_protocol.adoc | 4 +- .../modules/howto/pages/simultaneous_use.adoc | 78 +++++ 5 files changed, 484 insertions(+), 3 deletions(-) create mode 100644 doc/antora/modules/howto/pages/monitoring/index.adoc create mode 100644 doc/antora/modules/howto/pages/monitoring/statistics.adoc create mode 100644 doc/antora/modules/howto/pages/simultaneous_use.adoc (limited to 'doc/antora/modules/howto/pages') 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 < 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 <