diff options
Diffstat (limited to 'doc/antora/modules/howto')
6 files changed, 487 insertions, 3 deletions
diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 351200b..dab23f8 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -17,3 +17,6 @@ ***** xref:protocols/proxy/radsec_with_haproxy.adoc[Proxying RadSec with HAproxy] ***** xref:protocols/proxy/radsec_with_traefik.adoc[Proxying RadSec with Traefik] ***** xref:protocols/proxy/enable_proxy_protocol.adoc[Enabling PROXY Protocol for RadSec] +** xref:monitoring/index.adoc[Monitoring] +*** xref:monitoring/statistics.adoc[Server statistics] +** xref:simultaneous_use.adoc[Simultaneous-Use] 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. |