From: Alan T. DeKok Date: Tue, 26 Sep 2023 18:06:22 +0000 (-0400) Subject: point to the global.d/ directory for more information. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c3eb814e7ba4efef7743f433a7c73aa988ce46d3;p=thirdparty%2Ffreeradius-server.git point to the global.d/ directory for more information. --- diff --git a/doc/antora/modules/raddb/pages/mods-available/ldap.adoc b/doc/antora/modules/raddb/pages/mods-available/ldap.adoc index 2853a731e92..2514295c3bf 100644 --- a/doc/antora/modules/raddb/pages/mods-available/ldap.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/ldap.adoc @@ -11,6 +11,9 @@ NOTE: May also perform user authentication using LDAP binds, or by retrieving the contents of a password attribute for later comparison by a module such as `pap`, or an `eap` method. +Please see the file `global.d/ldap` for server-global configuration items +which control LDAP library debugging. + ## Configuration Settings @@ -44,7 +47,8 @@ port:: Port to connect on, defaults to 389, will be ignored for LDAP URIs. identity:: Administrator account for searching and possibly modifying. -WARNING: If using SASL + KRB5 these should be commented out. +WARNING: If using SASL + (KRB5 | EXTERNAL) identity should be commented out +as it will set an authzid, which is likely not what you want. @@ -239,6 +243,11 @@ mech:: SASL mechanism. +authname:: SASL authentication name. Mechanism specific value +to use when prompted for the client authentication name. + + + proxy:: SASL authorisation identity to proxy. @@ -247,6 +256,11 @@ realm:: SASL realm. Used for kerberos. +password_attribute:: Which attribute in the request should be used as +the password when performing user binds. + + + scope:: Search scope, may be `base`, `one`, `sub' or `children`. @@ -301,6 +315,16 @@ Will result in the user being locked out. +access_value_negate:: Which value we look for in access_attribute +to indicate that we should negate the result. + + + +access_value_suspend:: Which value we look for in access_attribute +to indicate that the user should be suspended. + + + ### User membership checking @@ -405,6 +429,13 @@ filter:: Filter for RADIUS profile objects. +scope:: Search scope, may be `base`, `one`, `sub` or `children`. + +Should usually be left as "base", to retrieve the specific profile +specified by 'default' or in the user or group objects. + + + default:: The default profile. This may be a DN or an attribute reference. NOTE: To get old v2.2.x style behaviour, or to use the `&User-Profile` attribute @@ -421,6 +452,16 @@ is successful. +attribute_suspended: The LDAP attribute containing profile DNs to apply +in addition to the default profile above, when the user account is in +the suspended state + +These are retrieved from the user object, at the same time as the +attributes from the update section, are are applied if authorization +is successful. + + + ### Modify user object on receiving Accounting-Request Useful for recording things like the last time the user logged @@ -546,6 +587,12 @@ NOTE: `LDAP_OPT_X_KEEPALIVE_INTERVAL` is set to this value. +net_timeout:: Sets the timeout for establishing connections. + +NOTE: `LDAP_OPT_NETWORK_TIMEOUT` is set to this value. + + + reconnection_delay:: Sets the time in seconds before a failed connection will attempt reconnection. This includes failures to bind as the admin user due to incorrect credentials. @@ -597,11 +644,13 @@ setting this to "1.2" ### Connection Pool -The connection pool is new for >= 3.0, and will be used in many -modules, for all kinds of connection-related activity. +The connection pool is a set of per-thread parameters for connections +to the LDAP server. + +This connection pool is used for LDAP queries run as the administrative user. -When the server is not threaded, the connection pool limits are -ignored, and only one connection is used. +All LDAP operations are perfomed asynchronously, meaning that many queries +can be active on a single connection simultaneously. start:: Connections to create during module instantiation. @@ -619,22 +668,14 @@ 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. +If these connections are all fully in use (refer to per_connection_max below) +and a new one is requested, the request will NOT get a connection. -spare:: Spare connections to be left idle. +connecting:: Number of connections which can be starting at once -NOTE: Idle connections WILL be closed if `idle_timeout` -is set. This should be less than or equal to `max` above. +Used to throttle connection spawning. @@ -644,43 +685,58 @@ NOTE: A setting of `0` means infinite (no limit). -retry_delay:: The number of seconds to wait after the server tries -to open a connection, and fails. +lifetime:: The lifetime (in seconds) of the connection. -During this time, no new connections will be opened. +open_delay:: Open delay (in seconds). -lifetime:: The lifetime (in seconds) of the connection. +How long must we be above the target utilisation for connections to be openned. +close_delay:: Close delay (in seconds). -idle_timeout:: Idle timeout (in seconds). +How long we must be below the target utilisation for connections to be closed -A connection which is unused for this length of time will be closed. +manage_interval:: How often to manage the connection pool. -connect_timeout:: Connection timeout (in seconds). -The maximum amount of time to wait for a new connection to be established. -NOTE: Sets `LDAP_OPT_NETWORK_TIMEOUT` in libldap. +request:: Options specific to requests handled by this connection pool +per_connection_max:: Maximum number of active queries there can be on a +single connection. -[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. -==== + + +per_connection_target:: Target number of active queries on a single connection. + + + +free_delay:: How long must a request in the unassigned (free) list not have been +used for before it's cleaned up and actually freed. + +Unassigned requests can be re-used, multiple times, reducing memory allocation +and freeing overheads. + + + +### Bind Connection Pool + +This connection pool is used for LDAP binds used to authenticate requests when +calling the ldap module in authenticate context. If passwords are retrieved +from the ldap directory and FreeRADIUS performs the authentication then this is +not used. + +The options are essentially identical to the pool section above with certain +limitations. Since only one bind operation can be in progress on a connection at +a time, `per_connection_max` and `per_connection_target` are always set to 1. + +This limitation means that `max` represents the maximum number of in progress +binds which there can be on a single thread. @@ -698,8 +754,12 @@ Escape a string for use in an LDAP filter or DN. [source,unlang] ---- -&control.Tmp-String-0 := "ldap:///ou=profiles,dc=example,dc=com??sub?(objectClass=radiusprofile)" -&reply.Reply-Message := "The LDAP url is %{ldap_escape:%{control.Tmp-String-0}}" +update control { + &Tmp-String-0 := "ldap:///ou=profiles,dc=example,dc=com??sub?(objectClass=radiusprofile)" +} +update reply { + &Reply-Message := "The LDAP url is %{ldap_escape:%{control.Tmp-String-0}}" +} ---- .Output @@ -718,8 +778,12 @@ Unescape a string for use in an LDAP filter or DN. [source,unlang] ---- -&control.Tmp-String-0 := "ldap:///ou=profiles,dc=example,dc=com??sub?\28objectClass=radiusprofile\29" -&reply.Reply-Message := "The LDAP url is %{ldap_unescape:%{control.Tmp-String-0}}" +update control { + &Tmp-String-0 := "ldap:///ou=profiles,dc=example,dc=com??sub?\28objectClass=radiusprofile\29" +} +update reply { + &Reply-Message := "The LDAP url is %{ldap_unescape:%{control.Tmp-String-0}}" +} ---- .Output @@ -765,13 +829,17 @@ ldap { # filter = "(&(objectClass=user)(sAMAccountName=%{%{Stripped-User-Name}:-%{User-Name}})(memberOf:1.2.840.113556.1.4.1941:=cn=group,${..base_dn}))" sasl { # mech = 'PLAIN' +# authname = &User-Name # proxy = &User-Name # realm = 'example.org' } +# password_attribute = &User-Password # scope = 'sub' # sort_by = '-uid' # access_attribute = 'dialupAccess' # access_positive = yes +# access_value_negate = 'false' +# access_value_suspend = 'suspended' } group { base_dn = "${..base_dn}" @@ -788,8 +856,10 @@ ldap { } profile { # filter = '(objectclass=radiusprofile)' +# scope = 'base' # default = 'cn=radprofile,dc=example,dc=org' # attribute = 'radiusProfileDn' +# attribute_suspended = 'radiusProfileDn' } accounting { reference = "%{tolower:type.%{Acct-Status-Type}}" @@ -828,6 +898,7 @@ ldap { idle = 60 probes = 3 interval = 3 + net_timeout = 10 reconnection_delay = 10 } tls { @@ -842,14 +913,24 @@ ldap { } pool { start = 0 - min = 0 -# max = - spare = 1 + min = 1 + max = 5 + connecting = 2 uses = 0 - retry_delay = 30 lifetime = 0 - idle_timeout = 60 - connect_timeout = 3.0 +# open_delay = 0.2 +# close_delay = 10 +# manage_interval = 0.2 + request { +# per_connection_max = 2000 +# per_connection_target = 1000 +# free_delay = 10 + } + } + bind_pool { + start = 0 + min = 1 + max = 1000 } } ``` diff --git a/doc/antora/modules/raddb/pages/mods-available/python.adoc b/doc/antora/modules/raddb/pages/mods-available/python.adoc index f6c5c1d7995..4a9149bf845 100644 --- a/doc/antora/modules/raddb/pages/mods-available/python.adoc +++ b/doc/antora/modules/raddb/pages/mods-available/python.adoc @@ -14,6 +14,9 @@ NOTE: Uncomment any `func_*` configuration items below which are included in your module. If the module is called for a section which does not have a function defined, it will return `noop`. +Please see the file global.d/python for server-global configuration +items which control the Python path. + ## Configuration Settings @@ -28,53 +31,6 @@ Module to load functions from. -cext_compat:: - -Uncomment the following line (and set to true) if you need -to call Python C extensions that acquire the GIL. - -This will use the first Python interpreter (*not a sub-interpreter*) -to provide the execution environment for this module instance. - -The tradeoff is, that any module instance with `cext_compat = true`, -will share the same environment, and will use the same user -configurable configuration items, and `python_path`, as the first -instance of `rlm_python` to be loaded with `cext_compat` enabled. - -Not all Python functions use the GIL as it prevents parallel -execution. A good indication of whether `cext_compat` is needed -is whether your script locks up or crashes when calling a -Python C extension. - -[NOTE] -==== -This functionality is only available when building with Python 2.7 -or below. For Python 3 you should build against Python 3.8 which -has a proper fix for this issue (per interpreter GILs) -==== - - - -python_path:: - -The search path for Python modules. It must include the path to your -Python module. - - - -python_path_include_conf_dir:: - -If "yes", include the directory containing this file in Python's -module search path. - - - -python_path_include_default:: - -If "yes", retain the default search path. Any additional search -path components will be prepended to the the default search path. - - [NOTE] ==== * You may set `mod_
` for any of the section to module @@ -115,10 +71,6 @@ radiusd.config['sub-config']['name'] ``` python { module = example -# cext_compat = false -# python_path = ${modconfdir}/${.:name} -# python_path_include_conf_dir = "yes" -# python_path_include_default = "yes" # func_instantiate = instantiate # func_detach = detach # func_authorize = authorize diff --git a/raddb/mods-available/ldap b/raddb/mods-available/ldap index c775687bad6..85b23957e1d 100644 --- a/raddb/mods-available/ldap +++ b/raddb/mods-available/ldap @@ -14,6 +14,9 @@ # the contents of a password attribute for later comparison by a module such # as `pap`, or an `eap` method. # +# Please see the file `global.d/ldap` for server-global configuration items +# which control LDAP library debugging. +# # # ## Configuration Settings diff --git a/raddb/mods-available/python b/raddb/mods-available/python index 748852f6214..31b15f90c42 100644 --- a/raddb/mods-available/python +++ b/raddb/mods-available/python @@ -17,6 +17,9 @@ # included in your module. If the module is called for a section which # does not have a function defined, it will return `noop`. # +# Please see the file global.d/python for server-global configuration +# items which control the Python path. +# # # ## Configuration Settings