** Tutorials
*** xref:new_user.adoc[New User]
+*** xref:matching_users.adoc[Matching Users]
*** xref:new_client.adoc[New Client]
+
*** xref:accounting.adoc[Accounting]
-*** xref:simultaneous_use.adoc[Simultaneous Use]
-*** xref:matching_users.adoc[Matching Users]
+**** xref:simultaneous_use.adoc[Simultaneous Use]
+
+*** Unlang
+**** xref:unlang_update_blocks_and_conditions.adoc[Update blocks and conditions]
+**** xref:unlang_splitting_strings.adoc[Splitting strings]
+**** xref:unlang_policies.adoc[Policies]
+
*** xref:proxy.adoc[Proxying]
**** xref:proxy_receive.adoc[Proxy Receive]
**** xref:proxy_failover.adoc[Proxy Fail-Over]
**** xref:proxy_load_balance.adoc[Proxy Load-Balance]
+
*** xref:sql.adoc[SQL]
**** xref:sql_user.adoc[SQL Users]
*** xref:variables.adoc[Variables]
-[[accounting]]
-Accounting Requests
--------------------
+= Accounting Requests
*Goal*: To send the server accounting requests and to have the server
log the accounting requests.
The "detail" module simply logs every accounting request to a file in a simple
textual format.
-[[accounting-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why do accounting messages require less configuration of the server
than authentication methods?
-[[autz-type]]
-Using the Autz-Type attribute
------------------------------
+= Using the Autz-Type attribute
*Goal:* To control which authorization modules are executed for an
`Access-Request`
--------------------------------------------------
[[autz-type-questions]]
-Questions
-~~~~~~~~~
+== Questions
// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// Development of this documentation was sponsored by Network RADIUS SAS.
-[[custom-dictionaries-and-attributes]]
-Custom Dictionaries and Attributes
-----------------------------------
+= Custom Dictionaries and Attributes
*Goal:* To understand how the dictionaries affect the server and to create
a new vendor-specific dictionary with a number of custom attributes; also, to test those attributes in the server.
contains the expected attributes.
[[dictionary-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What happens when the same attribute has multiple names, i.e.,
multiple names for one number?
-[[dynamic-translation]]
-Further dynamic translation
----------------------------
+= Further dynamic translation
*Goal:* To use dynamic translation of strings to perform inter-module
references.
In this case, the user "bob" is given one minute of access time,
multiplied by the value of the "UID" of the RADIUS server.
-[[further-considerations]]
-Further considerations
-~~~~~~~~~~~~~~~~~~~~~~
+== Further considerations
Run-time variables allow inter-module calling. The administator may perform LDAP
queries and SQL queries to use database information in other modules.
characters long in the current version of the server. This limitation may be
removed in a later version.
-[[dynamic-translation-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How would you perform an SQL query in a run-time variable, instead of
executing a program?
-[[eap-md5]]
-Other protocols within RADIUS: EAP-MD5
---------------------------------------
+= Other protocols within RADIUS: EAP-MD5
*Goal:* To configure the server to use the EAP-MD5 authentication
protocol and to send and receive test packets.
image::eap-md5.svg[Fig. EAP-MD5]
-[[eap-md5-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. In which of the following sections is the `eap` module used?
authorize, authenticate, and accounting.
-[[eap-peap]]
-EAP-PEAP: Tunneled authentication
----------------------------------
+= EAP-PEAP: Tunneled authentication
*Goal:* To configure the server to use the EAP-PEAP authentication
protocol and to send and receive test packets.
Verify that the authentication succeeded by using the `ping` command to
see if the wireless client now has network access.
-[[eap-peap-further-considerations]]
-Further Considerations
-~~~~~~~~~~~~~~~~~~~~~~
+== Further Considerations
Different wireless clients may implement different tunneled
authentication protocols inside of EAP-PEAP. These clients may not be
Set the above key to value ``1''. A file `RASTLS.LOG` will be created
and will contain the requested tracing information.
-[[eap-peap-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How does EAP-PEAP compare with EAP-TTLS?
2. What authentication protocols may be carried inside of the TLS
-[[eap-tls]]
-EAP-TLS: Certificate-based authentication
------------------------------------------
+= EAP-TLS: Certificate-based authentication
*Goal:* To configure the server to use the EAP-TLS authentication
protocol and to send and receive test packets.
Verify that the authentication succeeded by using the `ping` command to
see if the wireless client now has network access.
-[[eap-tls-further-considerations]]
-Further considerations
-~~~~~~~~~~~~~~~~~~~~~~
+== Further considerations
EAP-TLS is an authentication protocol and nothing more. As such, the
wireless client will still need to obtain an IP address. This address
ships with an EAP-PEAP client, which may influence any decision about
which wireless authentication protocol to use.
-[[eap-tls-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What other benefits does EAP-TLS have over EAP-MD5?
2. What happens to the user's password when they use EAP-TLS?
-[[eap-ttls]]
-EAP-TTLS: Tunneled authentication
----------------------------------
+= EAP-TTLS: Tunneled authentication
*Goal:* To configure the server to use the EAP-TTLS authentication
protocol and to send and receive test packets.
Verify that the authentication succeeded by using the `ping` command to
see if the wireless client now has network access.
-[[eap-ttls-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How is EAP-TTLS easier to use than EAP-TLS?
2. What authentication protocols may be carried inside of the TLS
-[[matching-users]]
-Matching entries in the users file
-----------------------------------
+= Matching entries in the users file
*Goal:* To configure multiple entries for a user in the "users" file
and to validate the server's configuration by sending test packets to
Save copies of the packets.
-[[matching-users-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What is the difference between the Framed-Route and Framed-Routing
Attributes?
-[[module-fail-over]]
-Module Fail-Over
-----------------
+= Module Fail-Over
*Goal:* To configure the server to use a "backup" module if a
"primary" module fails.
$ more /var/log/radius/radacct/detail2
-----------------------------------------------
-[[module-fail-over-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Could the configuration for the "group" section containing the
"detail1" and "detail2" modules be simplified? If so, how?
-[[multiple-modules]]
-Multiple instances of a module
-------------------------------
+= Multiple instances of a module
*Goal:* To configure the server to have multiple instances of a module.
Once you have verified that the files exist and that the correct
information is logged in them, you may stop the server.
-[[multiple-modules-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why is it useful to have multiple versions of a module?
-[[new-clients]]
-Adding a new client to the server
----------------------------------
+= Adding a new client to the server
*Goal:* To permit an additional RADIUS client to communicate with the
server.
If the server responds to the packet and the client accepts the
response, then the test was successful, and the server may be halted.
-[[new-client-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What happens when the server receives a packet from a machine not
listed in "clients.conf"?
-[[new-user]]
-Adding a new user to the server
--------------------------------
+= Adding a new user to the server
*Goal:* To configure the server with a new user, to send test packets as
that new user, and to receive a reply.
Stop the server.
-[[new-user-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What happens when using a PAP password with an incorrect shared secret, and why do we get this result?
2. What is different when using a CHAP password with an incorrect shared secret?
-[[prepaid]]
-A simple pre-paid example
--------------------------
+= A simple pre-paid example
*Goal:* To implement a simple "prepaid" functionality in the server.
should be near 3600. This value depends on the length of time passed
between when the server is started and when the `bob-acct-stop.sh` script is run.
-[[prepaid-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How would you configure the server to obtain the daily access limits
from an SQL database?
-[[proxy]]
-Configuring a server to proxy requests
---------------------------------------
+= Configuring a server to proxy requests
*Goal:* To configure the server to proxy packets to a remote (home)
RADIUS server and to perform test authentications against both the
They should then observe the resulting behavior of their server, as it
attempts to proxy to a home server that does not respond.
-[[proxy-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How would you configure "proxy.conf" so that "realm1" was not
proxied, but was instead handled by the local RADIUS server?
-[[proxy-fail-over]]
-Proxy Fail-over
----------------
+= Proxy Fail-over
*Goal:* To configure a "backup" home server that is used when the
"primary" home server fails.
If time permits, the group may switch roles, so that users have the
opportunity to set up a proxy and a home server.
-[[proxy-fail-over-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Which server for "realm2" is picked by "realm1"? Why?
2. Would the server for "realm1" ever again try to send packets to
-[[proxy-load-balance]]
-Proxy Load Balancing
---------------------
+= Proxy Load Balancing
*Goal:* To configure a server to load-balanceproxied requests across
multiple home servers.
requests to the server for "realm1", and observe how the proxied
requests are distributed among the servers for "realm2".
-[[proxy-load-balance-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why is load balancing useful?
2. How is load balancing different than fail-over?
-[[configuring_a_server_to_send_and_receive_proxy_requests]]
-Configuring a server to send and receive proxy requests
--------------------------------------------------------
+= Configuring a server to send and receive proxy requests
*Goal:* To configure the server to proxy packets to a remote (home)
RADIUS server and to receive packets from another proxy server.
RADIUS client and server in order to observe what the server's resulting behavior
will be.
-[[proxy-receive-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why is it necessary for each server to mark some realms as local?
2. What would happen if each user did not configure the other RADIUS
-[[radmin]]
-The Administration CLI
-----------------------
+= The Administration CLI
*Goal:* To understand how to use the `radmin` command.
and read the output. Use `radtest` to send the server packets, and see
how the statistics change.
-[[radmin-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. How can you modify the `control-socket` file so that you can change
the server configuration?
[[simultaneous-use]]
-Configuring users for limited simultaneous access
--------------------------------------------------
+= Configuring users for limited simultaneous access
*Goal:* To prevent a user from having more than one login session at a
time.
`bob-login-two.sh` script again, to verify that the other login attempt
is now permitted to succed.
-[[simultaneous-use-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why is it useful to prevent a user from having more than one
simultaneous login session?
-[[sql]]
-Communicating with an SQL database
-----------------------------------
+= Communicating with an SQL database
*Goal:* To configure the server to communicate with an SQL database.
Now stop the server. The next exercise will be to add the schema to the
database, and to populate it with a test entry.
-[[sql-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why is it important to test SQL connectivity, independently of
testing the ability to obtain user configuration from an SQL database?
-[[sql-user]]
-Configuring a user in an SQL database
--------------------------------------
+= Configuring a user in an SQL database
*Goal:* To configure the server to have a new user in an SQL database,
to send test packets as that user, and to receive a reply.
verified that the SQL test client returns the correct information for
the queries, then send the access request again.
-[[sql-user-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why do we not use an SQL database to "authenticate" users?
2. How do we have a DEFAULT entry in an SQL database?
+++ /dev/null
-[[unlang-conditions]]
-Unlang Conditions
------------------
-
-*Goal:* Explore uses of conditions in the policy language
-
-*Time:* 10-20 minutes
-
-*File:*
-
-- `etc/raddb/policy.d/*`
-
-*`man` page:* unlang
-
-*documentation page(s):*
-
-- xref:unlang:condition/index.adoc[Conditions]
-- xref:unlang:update.adoc[The Update Statement]
-
-The functionality of some modules can be replicated or augmented
-using the policy language.
-
-There are many reasons why you may want to change exactly how a module
-works, but the most common are to implement additional business logic
-or deal with failures in a specific way.
-
-The `suffix` module is used to split an incoming `User-Name` value into
-its components and setup the request for proxying.
-
-Create a policy "suffix" that splits an incoming `User-Name` into two
-components on the "@" separator.
-
-The first component should be written to the `&request:Stripped-User-Name`
-attribute and the second component should be written to the
-`&control:Proxy-To-Realm` attribute.
-
-Use `bob@realm1.sh` and `bob@realm2.sh` to test your new policy to ensure
-it works as expected.
-
-[[unlang-conditions-questions]]
-Questions
-~~~~~~~~~
-
-1. What is one feature of the regular expression operator which make
- it particularly powerful in unlang?
-2. Why might you want to re-implement functionality offered by modules
- in unlang?
-3. What is the advantage of using `return` to exit the section early?
-
-// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
-// Development of this documentation was sponsored by Network RADIUS SAS.
-[[unlang-policies]]
-Unlang Policies
----------------
+= Unlang Policies
*Goal:* Create and use policies for abstracting business logic
*`man` page:* unlang
+include::partial$unlang_start.adoc[]
+
Look through the existing files in `etc/raddb/policy.d/*` and `man unlang`
to get a feel for the unlang syntax and the tasks that policies can
be used for.
------------------------------------------------
Create a policy `proxy_to_realm` that forwards the incoming request
-to to a remote realm if the `User-Name` attribute ends in `@<remote realm>`,
-then use the `return` keyword to exit the authorize section.
-If the `User-Name` attribute does not end in `@<remote realm>` the policy
-should return `noop`, so the caller knows that it did nothing.
+to to a remote realm if the `User-Name` attribute ends in `@<remote realm>`.
+
+The contents of this policy should be identical to the the 'unlang'
+code written for the xref:unlang_splitting_strings.adoc[Splitting Strings]
+tutorial.
Call this policy at the start of the `authorize {}` section of the
`etc/raddb/sites-available/default` virtual server.
All the information you need to create this policy is contained within
`man unlang` pages and the examples in this exercise.
-[TIP]
-========================================================================
-Attributes in the `&control` list can control the behaviour of the server.
-Commonly used control attributes are:
-
-- `&control:Proxy-To-Realm` controls the realm that the incoming request
-is forwarded to.
-- `&control:Response-Packet-Type` overrides the RADIUS packet code
-FreeRADIUS responds with.
-- `&control:Autz-Type` specifies the `autz-type {}` section to run in the
-`authorize {}` section.
-- `&control:Auth-Type` specifies the `auth-type {}` section to run in the
-`authenticate {}` section.
-========================================================================
-
-[[unlang-policies-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What are the advantages of using the policy language over interpreted
language modules?
-2. What's the main difference between a policy and a function in other
+2. What are the main differences between a policy and a function in other
languages?
-3. What is the advantage of using `return` to exit the section early?
// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// Development of this documentation was sponsored by Network RADIUS SAS.
--- /dev/null
+= Module return codes
+
+*Goal:* Create and use policies for abstracting business logic
+
+*Time:* 10-20 minutes
+
+*File:*
+
+- `etc/raddb/policy.d/*`
+
+*`man` page:* unlang
+
+include::partial$unlang_start.adoc[]
--- /dev/null
+= Splitting strings
+
+*Goal:* Explore uses of regular expressions and subcapture groups
+
+*Time:* 10-20 minutes
+
+*File:*
+
+- `etc/raddb/policy.d/*`
+
+*`man` page:* unlang
+
+*documentation page(s):*
+
+- xref:unlang:condition/index.adoc[Conditions]
+- xref:unlang:condition/regex.adoc[Regular expressions]
+- xref:unlang:update.adoc[The Update Statement]
+
+include::partial$unlang_start.adoc[]
+
+include::partial$common_control_attrs_sidebar.adoc[]
+
+Regular expressions are an extremely powerful tool in the 'unlang' policy
+language. They provide both validation capabilities, allowing users
+to check the format of incoming attributes, and substring extraction
+(via capture groups).
+
+If you've completed the xref:proxy.adoc[Proxy] exercise you'll have
+used the `suffix` module to split an incoming `&User-Name` value into
+its components and setup the request for proxying.
+
+Create an unlang version of "suffix" that splits an incoming `&User-Name` into
+two components on the "@" separator.
+
+The first component should be written to the `&request:Stripped-User-Name`
+attribute and the second component should be written to the
+`&control:Stripped-User-Domain` attribute.
+
+Use `bob@realm1.sh` and `bob@realm2.sh` to test your new policy to ensure
+it works as expected.
+
+If you've completed the xref:proxy.adoc[Proxy] tutorial and have test
+realms setup, modify the policy code you have just written to proxy
+the request to the realm specified in the `&User-Name` attribute.
+
+== Questions
+
+1. Regular expressions can contain attribute expansions. Given that
+ all supported regular expression libraries support pre-compilation
+ of expressions, why would regular expressions containing expansions
+ be avoided when the server being deployed will be under heavy load?
+2. Why might you want to re-implement functionality offered by modules
+ in unlang?
+3. What is an advantage of using expression based string splitting
+ over the suffix module?
+
+// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.
--- /dev/null
+= Update blocks and simple conditions
+
+*Goal:* Explore uses of update blocks in the policy language
+
+*Time:* 10-25 minutes
+
+*File:*
+
+- `sites-available/default`
+
+*`man` page:* unlang
+
+*documentation page(s):*
+
+- xref:unlang:condition/index.adoc[Conditions]
+- xref:unlang:update.adoc[The Update Statement]
+
+include::partial$unlang_start.adoc[]
+
+Unlang `update` blocks are used to update one or attributes in one
+of the server's xref:unlang:list.adoc[attribute lists].s
+
+One common use of `update` blocks is to alter how a server processes
+requests.
+
+In previous tutorials we've used the `files` modules, and the authorize
+methods of authentication modules such as `pap` and `chap` to alter how
+the server processes requests. Here, we will emulate that behaviour
+using the policy language.
+
+* Create a condition (_condition 1_) to execute policy code if
+the `&User-Name` in the request is 'bob'.
+* Within that condition block, set the control attribute `&Cleartext-Password`
+to be 'hello', and instruct the server to run the the `authenticate { ... }`
+subsection for `pap`.
+* Use the `bob.sh` script to verify that you see an `Access-Accept` returned
+despite the `files` module not being called.
+
+Using additional conditions and update blocks, emulate the logic implemented
+using the files module in the xref:matching_users.adoc[Matching Users]
+exercise.
+
+To recap:
+
+* If an incoming request contains a `&User-Name` attribute with the value
+ 'bob', and contains and attribute `&Framed-Protocol` with value `PPP`
+ (_condition 2_), reply with a `&Framed-IP-Address` attribute with the value
+ `192.168.10.12`.
+* If an incoming request contains a `&Service-Type` attribute with a value
+ of `Framed-User` (_condition 3_), reply with a `&Framed-Route` attribute
+ assigning a default route of `192.168.10.1` (`0.0.0.0/0 192.168.10.1 1`) and
+ a `&Framed-IP-Netmask` attribute with a value of `255.255.255.0`.
+
+Again test the server with username "bob" and password "hello". Use the
+debug output of the server to see which unlang conditions evaluated to
+true. You may use `radclient` or the `bob.sh` script to send the packets.
+
+Perform other authentication tests, adding the appropriate attributes to
+the test requests to exercise the different conditions. If you already have
+test packets from the xref:matching_users.adoc[Matching Users] exercises,
+you may use those, otherwise continue until you have packets that will match:
+
+* conditions 1 and 2, but not 3.
+* conditions 1 and 3, but not 2.
+* conditions 1, 2, and 3.
+
+== Questions
+
+1. What are the advantages of unlang over the files module when creating
+ policies?
+2. What are the advantages of the files modules over unlang? Are there
+ any situations where you think the files module might be better suited
+ to a task than unlang?
+3. Can you think of any efficiencies the users module might have over
+ multiple conditions, where policies are being assigned to many different
+ users.
+
-[[variables]]
-Using configuration and run-time variables
-------------------------------------------
+= Using configuration and run-time variables
*Goal:* To use run-time variable expansion.
`Reply-Message` attributes contain the user name, NAS port, time, and a
copy of the `Class` attribute from the reply.
-[[variables-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. Why are run-time variables useful?
2. How would you configure that entry in the file to reply with the
-[[virtual]]
-Virtual Servers
----------------
+= Virtual Servers
*Goal:* To understand how to create and use a new virtual server.
Start the server in debugging mode, and use `radtest` to send a PAP
authentication request to the server at the port defined above.
-[[virtual-questions]]
-Questions
-~~~~~~~~~
+== Questions
1. What happens when you try to use CHAP or MS-CHAP? Why does this result occur?
2. How can you make that virtual server use CHAP or MS-CHAP?
--- /dev/null
+.Common control attributes
+****
+Attributes in the `&control` list can control the behaviour of the server.
+Commonly used control attributes are:
+
+- `&control:Proxy-To-Realm` controls the realm that the incoming request
+is forwarded to.
+- `&control:Response-Packet-Type` overrides the RADIUS packet code
+FreeRADIUS responds with.
+- `&control:Autz-Type` specifies the `autz-type {}` section to run in the
+`authorize {}` section.
+- `&control:Auth-Type` specifies the `auth-type {}` section to run in the
+`authenticate {}` section.
+****
--- /dev/null
+[TIP]
+====
+For this tutorial you should start with an empty authorization section
+(`recv Access-Request { ... }` or in ≤ v3.0.x `authorize { ... }`)
+in the virtual server you're using to process requests.
+====
** xref:list.adoc[Attribute Lists]
** xref:attr.adoc[Attribute References]
-** xref:regex.adoc[Regular Expressions]
** xref:keywords.adoc[Keywords]
*** xref:break.adoc[break]
*** xref:condition/or.adoc[The '||' Operator]
*** xref:condition/not.adoc[The '!' Operator]
*** xref:condition/para.adoc[The '( )' Operator]
+*** xref:condition/regex.adoc[Regular Expressions]
** xref:xlat/index.adoc[String Expansion]
| != | not equals
| >= | greater than or equals
| > | greater than
-| xref:regex.adoc[=~] | regular expression matches
-| xref:regex.adoc[!~] | regular expression does not match
+| xref:condition/regex.adoc[=~] | regular expression matches
+| xref:condition/regex.adoc[!~] | regular expression does not match
|=====
The comparison operators perform _type-specific_ comparisons. The
-only exceptions are the xref:regex.adoc[regular expression] operators,
+only exceptions are the xref:condition/regex.adoc[regular expression] operators,
which interpret the `lhs` as a printable string, and the `rhs` as a
regular expression.
= Built-in Modules
-In some cases, it is useful to reject a request immediately or
-perform another action on it. The built-in modules can be used to perform these actions. These modules are named for the return codes given in the
-xref:module.adoc[module] section.
+In some cases, it is useful to reject a request immediately or perform another
+action on it. The built-in modules can be used to perform these actions. These
+modules are named for the return codes given in the xref:module.adoc[module]
+section.
In practice, these modules are implemented by the
-xref:../raddb/mods-available/always.adoc[always] module and exist so that a
-success or failure can be forced during the processing of a
-policy.
+xref:raddb:mods-available/always.adoc[always] module and exist so that a
+success or failure can be forced during the processing of a policy.
The names and behaviours of these modules are given below:
projects / thirdparty / freeradius-server.git / commitdiff
