From: Alan T. DeKok Date: Sat, 30 Sep 2023 14:15:25 +0000 (-0400) Subject: move docs and examples to new function syntax X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5b406f9affa74be90308c88f90e7dc6b1fd9e75f;p=thirdparty%2Ffreeradius-server.git move docs and examples to new function syntax --- diff --git a/doc/antora/modules/raddb/pages/mods-available/cipher.adoc b/doc/antora/modules/raddb/pages/mods-available/cipher.adoc index f4208615904..06fced06f10 100644 --- a/doc/antora/modules/raddb/pages/mods-available/cipher.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/cipher.adoc @@ -12,24 +12,24 @@ Registers the following expansions: [options="header,autowidth"] |=== | XLAT | Description -| `%{_encrypt:...}` | Encrypts plaintext using `certificate_file` -| `%{<inst>_decrypt:<ciphertext>...}` | Decrypts ciphertext using `private_key_file` -| `%{<inst>_sign:<plaintext>...}` | Signs plaintext using `private_key_file` -| `%{<inst>_verify:<signature> <plaintext>...}` | Validates a signature using `certificate_file` -| `%(<inst>_certificate:serial)` | Returns the serial of `certificate_file` -| `%(<inst>_certificate:fingerprint <hash>)` | Produces a fingerprint of `certificate_file` using the specified hash. -| `%(<inst>_certificate:not_before)` | Retrieves the notBefore time from `certificate_file`. -| `%(<inst>_certificate:not_after)` | Retrieves the notAfter time from `certificate_file`. +| `%<inst>_encrypt(<plaintext>...)` | Encrypts plaintext using `certificate_file` +| `%<inst>_decrypt(<ciphertext>...)` | Decrypts ciphertext using `private_key_file` +| `%<inst>_sign(<plaintext>...)` | Signs plaintext using `private_key_file` +| `%<inst>_verify(<signature>, <plaintext>...)` | Validates a signature using `certificate_file` +| `%<inst>_certificate(serial)` | Returns the serial of `certificate_file` +| `%<inst>_certificate(fingerprint, <hash>)` | Produces a fingerprint of `certificate_file` using the specified hash. +| `%<inst>_certificate(not_before)` | Retrieves the notBefore time from `certificate_file`. +| `%<inst>_certificate(not_after)` | Retrieves the notAfter time from `certificate_file`. |=== NOTE: `<ciphertext>` and `<signature>` are ingested and excreted to in their raw form. -You should use armouring expansions i.e. `%(base64.encode:)`, `%(base64.decode:)` if the values +You should use armouring expansions i.e. `%base64.encode(...)`, `%base64.decode(...)` if the values are to be passed outside of FreeRADIUS. e.g: - %(base64.encode:%(cipher_encrypt:<plaintext>)) - %{cipher_decrypt:%(base64.decode:<ciphertext>)} + %base64.encode(%cipher_encrypt(<plaintext>)) + %cipher_decrypt(%base64.decode(<ciphertext>)) NOTE: The supported versions are determined _entirely_ by the version of OpenSSL used, we pass the name of the digest off to OpenSSL and it tells _us_ whether it's valid/supported diff --git a/doc/antora/modules/raddb/pages/mods-available/client.adoc b/doc/antora/modules/raddb/pages/mods-available/client.adoc index 2e78555f4b1..9942fd1eb0a 100644 --- a/doc/antora/modules/raddb/pages/mods-available/client.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/client.adoc @@ -72,10 +72,9 @@ map client [<ipaddr>] { // <1> [options="header,autowidth"] |=== -| XLAT | Description -| `%(client:<field>)` | Expands to a field in the client definition. -| `%(client:<field> <ipaddr>)` | Expands to a field in the client definition specified - by `<ipaddr>`. +| XLAT | Description +| `%client(<field>)` | Expands to a field in the client definition. +| `%(client(<field>, <ipaddr>)` | Expands to a field in the client definition specified by `<ipaddr>`. |=== diff --git a/doc/antora/modules/raddb/pages/mods-available/date.adoc b/doc/antora/modules/raddb/pages/mods-available/date.adoc index 2fe5e4f0f54..edae92b431f 100644 --- a/doc/antora/modules/raddb/pages/mods-available/date.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/date.adoc @@ -44,7 +44,7 @@ The core `xlat`, `%T` returns the request timestamp in `ISO` format including milliseconds. This expansion returns it without the millisecond component. -Use e.g. `%(date_iso:request):` +Use e.g. `%date_iso(request):` diff --git a/doc/antora/modules/raddb/pages/mods-available/eap.adoc b/doc/antora/modules/raddb/pages/mods-available/eap.adoc index 6ac5e1e4c26..49a11a9e237 100644 --- a/doc/antora/modules/raddb/pages/mods-available/eap.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/eap.adoc @@ -212,7 +212,7 @@ the following sections: |=== More information about the various sections can be found in -link:../sites-available/tls.adoc[sites-available/tls]. +link:../../../../../../sites-available/tls.adoc[sites-available/tls]. auto_chain:: @@ -862,7 +862,7 @@ Both `copy_request_to_tunnel` and `use_tunneled_reply` have been removed in v4.0. See the new policy `copy_request_to_tunnel` in -link:../sites-available/inner-tunnel.adoc[sites-available/inner-tunnel], and in `policy.d/eap` +link:../../../../../../sites-available/inner-tunnel.adoc[sites-available/inner-tunnel], and in `policy.d/eap` for more information. ==== @@ -971,7 +971,7 @@ Both `copy_request_to_tunnel` and `use_tunneled_reply` have been removed in v4.0. See the new policy `copy_request_to_tunnel` in -link:../sites-available/inner-tunnel.adoc[sites-available/inner-tunnel], and in `policy.d/eap` +link:../../../../../../sites-available/inner-tunnel.adoc[sites-available/inner-tunnel], and in `policy.d/eap` for more information. ==== @@ -1180,7 +1180,7 @@ require user configuration. The rlm_eap module provides the below functions to interact with the `3GPP` and `SIM` protocols. -### %(3gpp_pseudonym_decrypt:...) +### %3gpp_pseudonym_decrypt('...) TODO @@ -1199,7 +1199,7 @@ TODO TODO ``` -### %(3gpp_pseudonym_encrypt:...) +### %3gpp_pseudonym_encrypt(...) TODO @@ -1218,7 +1218,7 @@ TODO TODO ``` -### %(3gpp_pseudonym_key_index:...) +### %3gpp_pseudonym_key_index(...) TODO @@ -1237,7 +1237,7 @@ TODO TODO ``` -### %(aka_sim_id_method:...) +### %aka_sim_id_method(...) TODO @@ -1256,7 +1256,7 @@ TODO TODO ``` -### %(aka_sim_id_type:...) +### %aka_sim_id_type(...) TODO @@ -1342,7 +1342,7 @@ eap { } session { # mode = auto -# name = "%{EAP-Type}%(interpreter:server)" +# name = "%{EAP-Type}%interpreter(server)" # lifetime = 86400 # require_extended_master_secret = yes # require_perfect_forward_secrecy = no diff --git a/doc/antora/modules/raddb/pages/mods-available/exec.adoc b/doc/antora/modules/raddb/pages/mods-available/exec.adoc index f51fcb7798c..cb73349015a 100644 --- a/doc/antora/modules/raddb/pages/mods-available/exec.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/exec.adoc @@ -10,7 +10,7 @@ This module provides an `xlat`. To use it, put `exec` into the `instantiate` section. You can then do dynamic translation of attributes like: - Attribute-Name = "%(exec:/path/to/program args)" + Attribute-Name = "%exec(/path/to/program,args, ...)" The value of the attribute will be replaced with the output of the program which is executed. Due to RADIUS protocol limitations, @@ -78,11 +78,11 @@ Allowed values are: [options="header,autowidth"] |=== -| Pairs | Description -| request | attributes from the request -| config | attributes from the configuration items list -| reply | attributes from the reply -| session-state | attributes that persist over multiple request/response rounds. +| Pairs | Description +| &request | attributes from the request +| &config | attributes from the configuration items list +| &reply | attributes from the reply +| &session-state | attributes that persist over multiple request/response rounds. |=== @@ -137,8 +137,8 @@ responsiveness. exec { wait = yes # program = "/bin/true %{User-Name}" - input_pairs = request -# output_pairs = reply + input_pairs = &request +# output_pairs = &reply shell_escape = yes # env_inherit = no timeout = 10 diff --git a/doc/antora/modules/raddb/pages/mods-available/icmp.adoc b/doc/antora/modules/raddb/pages/mods-available/icmp.adoc index 980751e555f..c46357a860c 100644 --- a/doc/antora/modules/raddb/pages/mods-available/icmp.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/icmp.adoc @@ -68,8 +68,8 @@ Copy of the `icmp` module, as it may be easier to remember `ping` than `icmp`. == Default Configuration ``` -# `%(icmp:192.0.2.1)` -# `%(icmp:%{NAS-IP-Address})` +# `%icmp(192.0.2.1)` +# `%icmp:(%{NAS-IP-Address})` # $ setcap cap_net_raw+ep ${bindir}/radiusd icmp { # interface = eth0 diff --git a/doc/antora/modules/raddb/pages/mods-available/json.adoc b/doc/antora/modules/raddb/pages/mods-available/json.adoc index 2007c616c0f..d23adb426a0 100644 --- a/doc/antora/modules/raddb/pages/mods-available/json.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/json.adoc @@ -64,7 +64,7 @@ fields can be accessed using 'map' as shown in the example below. [source, unlang] ---- -map json "%(rest:GET http://example.org/api/user/%{User-Name})" { +map json "%rest(GET http://example.org/api/user/%{User-Name})" { &Tmp-Integer-0 := '$.account number' &Group += '$.groups.*' } diff --git a/doc/antora/modules/raddb/pages/mods-available/mschap.adoc b/doc/antora/modules/raddb/pages/mods-available/mschap.adoc index 201478c9553..33d6681ee2a 100644 --- a/doc/antora/modules/raddb/pages/mods-available/mschap.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/mschap.adoc @@ -115,7 +115,7 @@ module will do the authentication itself, without calling `ntlm_auth`. You can also try setting the user name as: -`... --username=%(mschap:User-Name) ...` +`... --username=%mschap(User-Name) ...` In that case, the `mschap` module will look at the `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]` attribute, and do prefix/suffix checks in order to obtain the _best_ @@ -184,19 +184,16 @@ configuration items below are the same for all modules which use the connection pool. -start:: +start:: Connections to create during module instantiation. -Connections to create during module instantiation. If the server cannot create specified number of connections during instantiation it will exit. -Set to 0 to allow the server to start without the -winbind daemon being available. +Set to `0` to allow the server to start without the +external service being available. -min:: - -Minimum number of connections to keep open. +min:: Minimum number of connections to keep open. @@ -205,13 +202,16 @@ max:: Maximum number of connections. If these connections are all in use and a new one is requested, the request will NOT get a connection. -Setting `max` to LESS than the number of threads means +Setting `max` to *LESS* than the number of threads means that some threads may starve, and you will see errors -like 'No connections available and at max connection limit' +like _No connections available and at max connection limit_. Setting `max` to MORE than the number of threads means that there are more connections than necessary. +If `max` is not specified, then it defaults to the number +of workers configured. + spare:: Spare connections to be left idle. @@ -324,6 +324,72 @@ retry_msg:: An optional retry message. + +.Attributes + +The `mschap` module needs to be configured with which attributes contain +MS-CHAP data in the request and which should be used for MS-CHAP data +in the reply. + +This varies for different protocols. The defaults show below are for +RADIUS. + + +username:: The attribute containing the user name. + + + +chap_challenge:: The attribute containing the CHAP Challenge. + + + +chap_response:: The attribute containing the CHAP Response for MS-CHAPv1. + + + +chap2_response:: The attribute containing the CHAP Response for MS-CHAPv2. + + + +chap2_success:: The attribute MS-CHAPv2 success messages are returned in. + + + +chap_error:: The attribute CHAP error messages are returned in. + + + +chap_mppe_keys:: The attribute MPPE keys are returned in for MS-CHAPv1 + + + +mppe_recv_key:: The attribute MPPE recv key is returned in for MS-CHAPv2 + + + +mppe_send_key:: The attribute MPPE send key is returned in for MS-CHAPv2 + + + +mppe_encryption_policy:: The attribute that MPPE encryption policy is returned in. + + + +mppe_encryption_types:: The attribute that MPPE encryption type is returned in. + + + +chap2_cpw:: The attribute used to change a users' password + + + +To use this instance of the mschap module to handle TACACS+ the attribute +section should be replaced with the following. + +TACACS+ does not have any inherent support for MPPE keys or password +changing using MSCHAP. + + == Default Configuration ``` @@ -333,11 +399,11 @@ mschap { # require_encryption = yes # require_strong = yes # with_ntdomain_hack = no -# ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{%{Stripped-User-Name}:-%{%{User-Name}:-None}} --challenge=%{%(mschap:Challenge):-00} --nt-response=%{%(mschap:NT-Response):-00}" +# ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{%{Stripped-User-Name}:-%{%{User-Name}:-None}} --challenge=%{%mschap(Challenge):-00} --nt-response=%{%mschap(NT-Response):-00}" # ntlm_auth_timeout = 10 winbind { -# username = "%(mschap:User-Name)" -# domain = "%(mschap:NT-Domain)" +# username = "%mschap(User-Name)" +# domain = "%mschap(NT-Domain)" # retry_with_normalised_username = no } pool { @@ -353,13 +419,35 @@ mschap { } passchange { # ntlm_auth = "/usr/bin/ntlm_auth --helper-protocol=ntlm-change-password-1" -# ntlm_auth_username = "username: %(mschap:User-Name)" -# ntlm_auth_domain = "nt-domain: %(mschap:NT-Domain)" -# local_cpw = "%(exec:/path/to/script %(mschap:User-Name) %{MS-CHAP-New-Password.Cleartext})" -# local_cpw = "%{sql:UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{User-Name}' and attribute='Password.NT'}" +# ntlm_auth_username = "username: %mschap(User-Name)" +# ntlm_auth_domain = "nt-domain: %mschap(NT-Domain)" +# local_cpw = "%exec(/path/to/script %mschap(User-Name) %{MS-CHAP-New-Password.Cleartext})" +# local_cpw = "%sql(UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{User-Name}' and attribute='Password.NT'}" } # use_open_directory = yes # allow_retry = yes # retry_msg = "Re-enter (or reset) the password" + attributes { + username = &User-Name + chap_challenge = &Vendor-Specific.Microsoft.CHAP-Challenge + chap_response = &Vendor-Specific.Microsoft.CHAP-Response + chap2_response = &Vendor-Specific.Microsoft.CHAP2-Response + chap2_success = &Vendor-Specific.Microsoft.CHAP2-Success + chap_error = &Vendor-Specific.Microsoft.CHAP-Error + chap_mppe_keys = &Vendor-Specific.Microsoft.CHAP-MPPE-Keys + mppe_recv_key = &Vendor-Specific.Microsoft.MPPE-Recv-Key + mppe_send_key = &Vendor-Specific.Microsoft.MPPE-Send-Key + mppe_encryption_policy = &Vendor-Specific.Microsoft.MPPE-Encryption-Policy + mppe_encryption_types = &Vendor-Specific.Microsoft.MPPE-Encryption-Types + chap2_cpw = &Vendor-Specific.Microsoft.CHAP2-CPW + } +# attributes { +# username = &User-Name +# chap_challenge = &MS-CHAP-Challenge +# chap_response = &MS-CHAP-Response +# chap2_response = &MS-CHAP2-Response +# chap2_success = &Data +# chap_error = &Server-Message +# } } ``` diff --git a/doc/antora/modules/raddb/pages/mods-available/ntlm_auth.adoc b/doc/antora/modules/raddb/pages/mods-available/ntlm_auth.adoc index a7bc565cf93..b707ed2ef90 100644 --- a/doc/antora/modules/raddb/pages/mods-available/ntlm_auth.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/ntlm_auth.adoc @@ -39,6 +39,6 @@ local system. The other fields can be left alone. # http://deployingradius.com/documents/configuration/active_directory.html exec ntlm_auth { wait = yes - program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%(mschap:User-Name) --password=%{User-Password}" + program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%mschap(User-Name) --password=%{User-Password}" } ``` diff --git a/doc/antora/modules/raddb/pages/mods-available/redis.adoc b/doc/antora/modules/raddb/pages/mods-available/redis.adoc index 32ca313158b..f8a3fef434a 100644 --- a/doc/antora/modules/raddb/pages/mods-available/redis.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/redis.adoc @@ -44,12 +44,62 @@ port:: Port to connect to The default port is 6379. + password:: The password used to authenticate to the server. We recommend using a strong password. +use_tls:: Use TLS (requires hiredis 1.0+) + +TLS parameters can be specified in the optional adjacent tls {} section + + + +use_cluster_map:: Use cluster map + +Build cluster map during initialization. + +The cluster client can operate, albeit inefficiently, without a cluster map +by following '-ASK' and '-MOVE' redirects. + +Disabling cluster map can be required for stunnel-based deployments. +Alternatively, cluster map is not built during initialization when pool.start == 0 + + +lua { ... }:: + +Configuration options which control the execution of lua scripts +on redis nodes. + + +function <name> { ... }:: + +Every function section listed here will be registered as an expansion with a name +in the format `<inst>.<name>`. + +For example the function below would be callable as `%redis.hello_world(...)`. + +expansion functions take the same arguments as the redis `EVALSHA` command, +i.e. `<numkeys> [<key> [<key> ...]] [<arg> [<arg> ...]]`. + +`numkeys` specifies how many of the proceeding arguments should be treated as keys. + +The redis module will use the first key to determine which cluster node the function +should called on. + +The redis module pre-calcualtes the SHA1 hash of all lua functions on startup. +When an expansion function is called, it uses the `EVALSHA` command to attempt to +call lua function on a remote redis node. If `EVALSHA` fails with an error indicating +no script could be found with the calculated SHA1 hash, the lua function will be +loaded transparently using `SCRIPT LOAD`. + + +body:: Lua code to send to redis nodes with SCRIPT LOAD + + + pool { ... }:: Information for the connection pool. The configuration items below @@ -57,11 +107,11 @@ are the same for all modules which use the new connection pool. start:: Connections to create during module instantiation. -If the server cannot create specified number of connections -during instantiation it will exit. -Set to `0` to allow the server to start without the web service -being available. +If the server cannot create specified number of +connections during instantiation it will exit. +Set to `0` to allow the server to start without the +external service being available. @@ -74,13 +124,16 @@ max:: Maximum number of connections. If these connections are all in use and a new one is requested, the request will NOT get a connection. -Setting `max` to LESS than the number of threads means +Setting `max` to *LESS* than the number of threads means that some threads may starve, and you will see errors -like 'No connections available and at max connection limit' +like _No connections available and at max connection limit_. Setting `max` to MORE than the number of threads means that there are more connections than necessary. +If `max` is not specified, then it defaults to the number +of workers configured. + spare:: Spare connections to be left idle. @@ -152,6 +205,14 @@ redis { # database = 0 port = 6379 # password = thisisreallysecretandhardtoguess +# use_tls = no +# tls { } +# use_cluster_map = yes + lua { + function hello_world { + body = 'return "hello world"' + } + } pool { start = 0 min = 0 diff --git a/doc/antora/modules/raddb/pages/mods-available/rest.adoc b/doc/antora/modules/raddb/pages/mods-available/rest.adoc index c8a7c2e8447..fda58b3d86f 100644 --- a/doc/antora/modules/raddb/pages/mods-available/rest.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/rest.adoc @@ -180,6 +180,7 @@ The following config items may be listed in any of the sections: variables set like http_proxy. | `method` | HTTP method to use, one of 'get', 'post', 'put', 'patch', 'delete' or any custom HTTP method. +| `header` | A custom header in the format '<header>: <value>'. | `body` | The format of the HTTP body sent to the remote server. May be 'none', 'post' or 'json', defaults to 'none'. | `data` | Send custom freeform data in the HTTP body. `Content-type` @@ -206,7 +207,7 @@ The values of those attributes should be in the format: <attribute>: <value> `control.REST-HTTP-Header` attributes will be consumed after each call -to the rest module, and each `%(rest:)` expansion. +to the rest module, and each `%rest(...)` expansion. @@ -331,106 +332,49 @@ Same as `Accounting { ... }` -pool { ... }:: +connection { ... }:: Configure how connection handles are +managed per thread. -This pool controls the number of handles available per-thread. -Each handle represents a single HTTP request. - -[NOTE] -==== - * With HTTP <= 1.1, each request is bound to a single connection -so this pool, so these configuration items are useful for limiting -the number of outbound requests to the server. - - * With HTTP >= 2.0 with multiplexing enabled, multiple requests are -sent over a single HTTP connection, so the pool is more useful -for limiting the number of outstanding requests, and allowing for -handle reuse. -==== - - -start:: Connections to create during module instantiation. -If the server cannot create specified number of connections -during instantiation it will exit. - -Set to `0` to allow the server to start without the web service -being available. - - - -min:: Minimum number of connections to keep open. - - - -max:: Maximum number of connections. - -If these connections are all in use and a new one -is requested, the request will NOT get a connection. - -Setting `max` to LESS than the number of threads means -that some threads may starve, and you will see errors -like 'No connections available and at max connection limit' - -Setting `max` to MORE than the number of threads means -that there are more connections than necessary. +Reusable connection handles are allocated in blocks. These +parameters allow for tuning how that is done. +Since http requests are performed async, the settings here +represent outstanding http requests per thread. -spare:: Spare connections to be left idle. -NOTE: Idle connections WILL be closed if `idle_timeout` -is set. This should be less than or equal to `max` above. +min:: The minimum number of connection handles to +keep allocated. -uses:: Number of uses before the connection is closed. -NOTE: `0` means "infinite". +max:: The maximum number of reusable connection handles +to allocate. +Any requests to allocate a connection handle beyond +this number will cause a temporary handle to be allocated. +This is less efficient than the block allocation so +`max` should be set to reflect the number of outstanding +requests expected at peak load. -retry_delay:: The number of seconds to wait after the server tries -to open a connection, and fails. +cleanup_interval:: How often to free un-used connection +handles. -During this time, no new connections will be opened. +Every `cleanup_interval` a cleanup routine runs which +will free any blocks of handles which are not in use, +ensuring that at least `min` handles are kept. -lifetime:: The lifetime (in seconds) of the connection. - -NOTE: `0` means "infinite". - - - -idle_timeout:: The idle timeout (in seconds). - -A connection which is unused for this length of time will be closed. - -NOTE: `0` means "infinite". - - connect_timeout:: Connection timeout (in seconds). The maximum amount of time to wait for a new connection to be established. - -[NOTE] -==== -All configuration settings are enforced. If a connection is closed because of -`idle_timeout`, `uses`, or `lifetime`, then the total number of connections MAY -fall below `min`. - -When that happens, it will open a new connection. It will also log a *WARNING* -message. - -The solution is to either lower the "min" connections, -or increase lifetime/idle_timeout. -==== - - == Default Configuration ``` @@ -475,15 +419,12 @@ rest { method = 'POST' tls = ${..tls} } - pool { - start = 20 - min = 1 - max = 50 - spare = 1 - uses = 0 - retry_delay = 30 - lifetime = 0 - idle_timeout = 60 + connection { + reuse { + min = 10 + max = 100 + cleanup_interval = 30s + } connect_timeout = 3.0 } } diff --git a/doc/antora/modules/raddb/pages/mods-available/unbound.adoc b/doc/antora/modules/raddb/pages/mods-available/unbound.adoc index de55d9dbeb0..a3e63f38377 100644 --- a/doc/antora/modules/raddb/pages/mods-available/unbound.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/unbound.adoc @@ -42,8 +42,8 @@ An xlat based on the instance name can be used to perform DNS lookups. .Example ``` -%(dns:www.example.com A) -%(dns:www.example.com AAAA) +%dns(www.example.com, A) +%dns(www.example.com, AAAA) ``` Given an instance `dns` the above xlats will perform A record and @@ -52,7 +52,7 @@ AAAA record lookups on www.example.com. .Example ``` -%(dns:1.1.168.192.in-addr.arpa PTR) +%dns(1.1.168.192.in-addr.arpa, PTR) ``` The above example will perform reverse DNS lookup on 192.168.1.1 @@ -60,7 +60,7 @@ The above example will perform reverse DNS lookup on 192.168.1.1 .Example ``` -%(dns:example.com MX 1) +%dns(example.com, MX, 1) ``` The above example will perform an MX lookup on example.com returning diff --git a/doc/antora/modules/raddb/pages/mods-available/unpack.adoc b/doc/antora/modules/raddb/pages/mods-available/unpack.adoc index 94b1c371504..984c993587c 100644 --- a/doc/antora/modules/raddb/pages/mods-available/unpack.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/unpack.adoc @@ -19,7 +19,7 @@ NOTE: The module is useful only for `xlat`. To use it, add it to the `raddb/mods-enabled/` directory. Then, use it on the right-hand side of a variable assignment. - %(unpack:<data> <offset> <data_type>) + %unpack(<data>, <offset>, <data_type>) The arguments are three fields: @@ -44,7 +44,7 @@ the data type to unpack at that offset. e.g. `integer`, `ipaddr`, `byte`, `short if we have `Class = 0x000001020304`, then - %(unpack:%{Class} 4 uint16) + %unpack(%{Class}, 4, uint16) will unpack octets `4` and `5` as a `uint16`, which has value `0x0304`. diff --git a/raddb/mods-available/cipher b/raddb/mods-available/cipher index 2408216dea6..47a3e80e2c8 100644 --- a/raddb/mods-available/cipher +++ b/raddb/mods-available/cipher @@ -15,24 +15,24 @@ # [options="header,autowidth"] # |=== # | XLAT | Description -# | `%{<inst>_encrypt:<plaintext>...}` | Encrypts plaintext using `certificate_file` -# | `%{<inst>_decrypt:<ciphertext>...}` | Decrypts ciphertext using `private_key_file` -# | `%{<inst>_sign:<plaintext>...}` | Signs plaintext using `private_key_file` -# | `%{<inst>_verify:<signature> <plaintext>...}` | Validates a signature using `certificate_file` -# | `%(<inst>_certificate:serial)` | Returns the serial of `certificate_file` -# | `%(<inst>_certificate:fingerprint <hash>)` | Produces a fingerprint of `certificate_file` using the specified hash. -# | `%(<inst>_certificate:not_before)` | Retrieves the notBefore time from `certificate_file`. -# | `%(<inst>_certificate:not_after)` | Retrieves the notAfter time from `certificate_file`. +# | `%<inst>_encrypt(<plaintext>...)` | Encrypts plaintext using `certificate_file` +# | `%<inst>_decrypt(<ciphertext>...)` | Decrypts ciphertext using `private_key_file` +# | `%<inst>_sign(<plaintext>...)` | Signs plaintext using `private_key_file` +# | `%<inst>_verify(<signature>, <plaintext>...)` | Validates a signature using `certificate_file` +# | `%<inst>_certificate(serial)` | Returns the serial of `certificate_file` +# | `%<inst>_certificate(fingerprint, <hash>)` | Produces a fingerprint of `certificate_file` using the specified hash. +# | `%<inst>_certificate(not_before)` | Retrieves the notBefore time from `certificate_file`. +# | `%<inst>_certificate(not_after)` | Retrieves the notAfter time from `certificate_file`. # |=== # # NOTE: `<ciphertext>` and `<signature>` are ingested and excreted to in their raw form. -# You should use armouring expansions i.e. `%(base64.encode:)`, `%(base64.decode:)` if the values +# You should use armouring expansions i.e. `%base64.encode(...)`, `%base64.decode(...)` if the values # are to be passed outside of FreeRADIUS. # # e.g: # -# %(base64.encode:%{cipher_encrypt:<plaintext>}) -# %{cipher_decrypt:%(base64.decode:<ciphertext>}) +# %base64.encode(%cipher_encrypt(<plaintext>)) +# %cipher_decrypt(%base64.decode(<ciphertext>)) # # NOTE: The supported versions are determined _entirely_ by the version of OpenSSL used, we # pass the name of the digest off to OpenSSL and it tells _us_ whether it's valid/supported diff --git a/raddb/mods-available/client b/raddb/mods-available/client index 3429e94caad..cf438c6a891 100644 --- a/raddb/mods-available/client +++ b/raddb/mods-available/client @@ -75,10 +75,9 @@ # # [options="header,autowidth"] # |=== -# | XLAT | Description -# | `%(client:<field>)` | Expands to a field in the client definition. -# | `%(client:<field> <ipaddr>)` | Expands to a field in the client definition specified -# by `<ipaddr>`. +# | XLAT | Description +# | `%client(<field>)` | Expands to a field in the client definition. +# | `%(client(<field>, <ipaddr>)` | Expands to a field in the client definition specified by `<ipaddr>`. # |=== # diff --git a/raddb/mods-available/date b/raddb/mods-available/date index ee5fbe190f0..2e7f8b511e0 100644 --- a/raddb/mods-available/date +++ b/raddb/mods-available/date @@ -51,7 +51,7 @@ date { # including milliseconds. This expansion returns it without the # millisecond component. # -# Use e.g. `%(date_iso:request):` +# Use e.g. `%date_iso(request):` # date date_iso { format = "%Y-%m-%dT%H:%M:%SZ" @@ -59,7 +59,7 @@ date date_iso { } # -# ### xlat expansions +# ### xlat expansions # # The `date` module defines an expansion `%{date:}` When the # expansion is not passed an argument, it returns the current date diff --git a/raddb/mods-available/eap b/raddb/mods-available/eap index ba26d9dd657..4374f244e70 100644 --- a/raddb/mods-available/eap +++ b/raddb/mods-available/eap @@ -783,7 +783,7 @@ eap { # NOTE: OpenSSL only allows 32 bytes of session ctx, so # the value provided here is digested with SHA256. # -# name = "%{EAP-Type}%(interpreter:server)" +# name = "%{EAP-Type}%interpreter(server)" # # lifetime:: @@ -1298,7 +1298,7 @@ eap { # # The rlm_eap module provides the below functions to interact with the `3GPP` and `SIM` protocols. # -# ### %(3gpp_pseudonym_decrypt:...) +# ### %3gpp_pseudonym_decrypt('...) # # TODO # @@ -1317,7 +1317,7 @@ eap { # TODO # ``` # -# ### %(3gpp_pseudonym_encrypt:...) +# ### %3gpp_pseudonym_encrypt(...) # # TODO # @@ -1336,7 +1336,7 @@ eap { # TODO # ``` # -# ### %(3gpp_pseudonym_key_index:...) +# ### %3gpp_pseudonym_key_index(...) # # TODO # @@ -1355,7 +1355,7 @@ eap { # TODO # ``` # -# ### %(aka_sim_id_method:...) +# ### %aka_sim_id_method(...) # # TODO # @@ -1374,7 +1374,7 @@ eap { # TODO # ``` # -# ### %(aka_sim_id_type:...) +# ### %aka_sim_id_type(...) # # TODO # diff --git a/raddb/mods-available/exec b/raddb/mods-available/exec index 0fe751ca562..6012813e5b9 100644 --- a/raddb/mods-available/exec +++ b/raddb/mods-available/exec @@ -13,7 +13,7 @@ # the `instantiate` section. You can then do dynamic translation of # attributes like: # -# Attribute-Name = "%(exec:/path/to/program args)" +# Attribute-Name = "%exec(/path/to/program,args, ...)" # # The value of the attribute will be replaced with the output of the # program which is executed. Due to RADIUS protocol limitations, diff --git a/raddb/mods-available/icmp b/raddb/mods-available/icmp index a6bf27adeca..a945ba5d7c1 100644 --- a/raddb/mods-available/icmp +++ b/raddb/mods-available/icmp @@ -11,7 +11,7 @@ # # This module is useful only for `xlat`. Use it via the following expansion: # -# `%(icmp:192.0.2.1)` +# `%icmp(192.0.2.1)` # # The module will "ping" the given IP address. If that IP address responds # with an ICMP Echo Reply, then the result of the expansion will be `yes`. @@ -21,7 +21,7 @@ # The IP address does not have to be a fixed string. It can be another # expansion, such as: # -# `%(icmp:%{NAS-IP-Address})` +# `%icmp:(%{NAS-IP-Address})` # # # == Capabilities and Permissions diff --git a/raddb/mods-available/json b/raddb/mods-available/json index e4b50573e04..d92a744fc1f 100644 --- a/raddb/mods-available/json +++ b/raddb/mods-available/json @@ -67,7 +67,7 @@ # # [source, unlang] # ---- -# map json "%(rest:GET http://example.org/api/user/%{User-Name})" { +# map json "%rest(GET http://example.org/api/user/%{User-Name})" { # &Tmp-Integer-0 := '$.account number' # &Group += '$.groups.*' # } diff --git a/raddb/mods-available/mschap b/raddb/mods-available/mschap index 60b14bd20e5..b8512c819d6 100644 --- a/raddb/mods-available/mschap +++ b/raddb/mods-available/mschap @@ -124,7 +124,7 @@ mschap { # # You can also try setting the user name as: # - # `... --username=%(mschap:User-Name) ...` + # `... --username=%mschap(User-Name) ...` # # In that case, the `mschap` module will look at the `User-Name` # attribute, and do prefix/suffix checks in order to obtain the _best_ @@ -139,7 +139,7 @@ mschap { # WARNING: Be VERY careful when editing the following line! # Change the path, and ideally nothing else. # -# ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{%{Stripped-User-Name}:-%{%{User-Name}:-None}} --challenge=%{%(mschap:Challenge):-00} --nt-response=%{%(mschap:NT-Response):-00}" +# ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{%{Stripped-User-Name}:-%{%{User-Name}:-None}} --challenge=%{%mschap(Challenge):-00} --nt-response=%{%mschap(NT-Response):-00}" # # ntlm_auth_timeout:: Time to wait for `ntlm_auth` to run. @@ -176,8 +176,8 @@ mschap { # later to be installed. Make sure that `ntlm_auth` above is # commented out. # -# username = "%(mschap:User-Name)" -# domain = "%(mschap:NT-Domain)" +# username = "%mschap(User-Name)" +# domain = "%mschap(NT-Domain)" # # retry_with_normalised_username:: @@ -322,8 +322,8 @@ mschap { # Uncomment the three lines below, and change the path to `ntlm_auth. # # ntlm_auth = "/usr/bin/ntlm_auth --helper-protocol=ntlm-change-password-1" -# ntlm_auth_username = "username: %(mschap:User-Name)" -# ntlm_auth_domain = "nt-domain: %(mschap:NT-Domain)" +# ntlm_auth_username = "username: %mschap(User-Name)" +# ntlm_auth_domain = "nt-domain: %mschap(NT-Domain)" # # local_cpw:: @@ -335,8 +335,8 @@ mschap { # # TIP: We give both examples here, but *only one should be used*. # -# local_cpw = "%(exec:/path/to/script %(mschap:User-Name) %{MS-CHAP-New-Password.Cleartext})" -# local_cpw = "%{sql:UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{User-Name}' and attribute='Password.NT'}" +# local_cpw = "%exec(/path/to/script %mschap(User-Name) %{MS-CHAP-New-Password.Cleartext})" +# local_cpw = "%sql(UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{User-Name}' and attribute='Password.NT'}" } # diff --git a/raddb/mods-available/ntlm_auth b/raddb/mods-available/ntlm_auth index 3806a5e46fc..cec810312aa 100644 --- a/raddb/mods-available/ntlm_auth +++ b/raddb/mods-available/ntlm_auth @@ -38,5 +38,5 @@ exec ntlm_auth { # You will need to edit the path and domain to match your # local system. The other fields can be left alone. # - program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%(mschap:User-Name) --password=%{User-Password}" + program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%mschap(User-Name) --password=%{User-Password}" } diff --git a/raddb/mods-available/redis b/raddb/mods-available/redis index 63f9185e3dc..bfb7d0879f8 100644 --- a/raddb/mods-available/redis +++ b/raddb/mods-available/redis @@ -91,7 +91,7 @@ redis { # Every function section listed here will be registered as an expansion with a name # in the format `<inst>.<name>`. # - # For example the function below would be callable as `%(redis.hello_world:...)`. + # For example the function below would be callable as `%redis.hello_world(...)`. # # expansion functions take the same arguments as the redis `EVALSHA` command, # i.e. `<numkeys> [<key> [<key> ...]] [<arg> [<arg> ...]]`. diff --git a/raddb/mods-available/rest b/raddb/mods-available/rest index 15c166eba49..e15482ba038 100644 --- a/raddb/mods-available/rest +++ b/raddb/mods-available/rest @@ -228,7 +228,7 @@ rest { # <attribute>: <value> # # `control.REST-HTTP-Header` attributes will be consumed after each call - # to the rest module, and each `%(rest:)` expansion. + # to the rest module, and each `%rest(...)` expansion. # # @@ -403,8 +403,8 @@ rest { # Any requests to allocate a connection handle beyond # this number will cause a temporary handle to be allocated. # This is less efficient than the block allocation so - # `max` should be set to reflect the number of outstanding - # requests expected at peak load. + # `max` should be set to reflect the number of outstanding + # requests expected at peak load. max = 100 # diff --git a/raddb/mods-available/unbound b/raddb/mods-available/unbound index b817e31098e..9cced9705f0 100644 --- a/raddb/mods-available/unbound +++ b/raddb/mods-available/unbound @@ -47,8 +47,8 @@ unbound dns { # .Example # # ``` -# %(dns:www.example.com A) -# %(dns:www.example.com AAAA) +# %dns(www.example.com, A) +# %dns(www.example.com, AAAA) # ``` # # Given an instance `dns` the above xlats will perform A record and @@ -57,7 +57,7 @@ unbound dns { # .Example # # ``` -# %(dns:1.1.168.192.in-addr.arpa PTR) +# %dns(1.1.168.192.in-addr.arpa, PTR) # ``` # # The above example will perform reverse DNS lookup on 192.168.1.1 @@ -65,7 +65,7 @@ unbound dns { # .Example # # ``` -# %(dns:example.com MX 1) +# %dns(example.com, MX, 1) # ``` # # The above example will perform an MX lookup on example.com returning diff --git a/raddb/mods-available/unpack b/raddb/mods-available/unpack index cafdd2160dc..9c8c5dd7d15 100644 --- a/raddb/mods-available/unpack +++ b/raddb/mods-available/unpack @@ -22,7 +22,7 @@ # To use it, add it to the `raddb/mods-enabled/` directory. Then, # use it on the right-hand side of a variable assignment. # -# %(unpack:<data> <offset> <data_type>) +# %unpack(<data>, <offset>, <data_type>) # # The arguments are three fields: # @@ -47,7 +47,7 @@ # # if we have `Class = 0x000001020304`, then # -# %(unpack:%{Class} 4 uint16) +# %unpack(%{Class}, 4, uint16) # # will unpack octets `4` and `5` as a `uint16`, which has value `0x0304`. #