Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

Common Configurations

This section explains the common configurations of LDAP plug-ins.

[Bootstrap] Section

The [Bootstrap] section (Table 163) of the LDAP configuration file specifies information that Steel-Belted Radius Carrier uses to load and start the LDAP method.

Table 163: [Bootstrap] Syntax

Parameter

Function

LibraryName

Specifies the name of the LDAP module, for example, ldapauth.so or ldapaccessor.so.

Enable

  • If set to 1, the LDAP module is enabled.
  • If set to 0, the LDAP module is disabled.

Default value is 0.

InitializationString

Specifies the identifier for the LDAP module.

The name of each LDAP module must be unique.

Default value is LDAP.

[Settings] Section

The [Settings] section of the LDAP configuration file forms a basis for all Bind and Search requests to the LDAP database server(s).

Search sequencing is flexible. You can override search results using the $reject and $accept keywords.

You can proceed to a new search even if the current search returns no data by using the OnNotFound parameter.

For examples of using flexible searching, see [Server/name] Sections.

The parameters in the [Settings] section apply to all LDAP servers listed in the configuration file. The following parameters are usually present. If any of these parameters is not provided in the [Settings] section, the parameter assumes a system default value.

The values set in [Settings] for some parameters, such as ConnectTimeout, MaxConcurrent, or WaitReconnect, provide defaults that apply to all servers. These default values can be overridden for a particular server by entering the same parameter with a different value in a [Server/ name ] section.

Table 164: [Settings] Syntax

Parameter

Function

MaxConcurrent

Specifies the maximum number of LDAP requests that may be executing at one time.

You can enter the value in the range from 1 through 1000. Default value is 1.

Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

Note: A setting of MaxConcurrent = 1 is sufficient for all but the most demanding environments. Increase this value slowly and conservatively. For more information about executing overlapping LDAP statements, see the SBR Carrier Administration and Configuration Guide.

Timeout

Specifies the maximum number of seconds for the overall timeout for each request, which includes the delay in acquiring resources, attempts against multiple LDAP servers, and so forth.

Default value is 20 seconds.

ConnectTimeout

Specifies the number of seconds to wait when attempting to establish the connection to the database before timing out. This value is passed to the client database engine, which may or may not implement the feature.

Default value is 25 seconds.

Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

QueryTimeout

Specifies the timeout value in seconds for an individual search performed against the LDAP server.

Default value is 10 seconds.

WaitReconnect

Specifies the number of seconds to wait after a failure of the database connection before trying to connect again.

Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

MaxWaitReconnect

Specifies the maximum number of seconds to wait after successive failures to reconnect after a failure of the database connection.

WaitReconnect specifies the time to wait after failure of the database connection. This value is doubled on each failed attempt to reconnect, up to a maximum of MaxWaitReconnect.

Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

BindName

For BindName, you must omit the Bind parameter from the LDAP configuration file. Use the BindName and BindPassword parameters instead.

In the [Settings] section, BindName and BindPassword specify a default LDAP Bind template to use for all servers. You can also use BindName and BindPassword in [Server/name] sections to override this default for an individual server

See [Server/name] Sections.

LogLevel

Activates logging for the LDAP method and sets the level of detail of the message. This value may be the number 0, 1, or 2, where 0 is the lowest logging level, 1 is intermediate, and 2 is the most verbose.

If the LogLevel that you set in the configuration file is different than the LogLevel in radius.ini, the lower value of the setting controls.

UpperCaseName

  • If set to 0, preserves the case of the username.
  • If set to 1, converts the username to uppercase.

Default value is 0.

PasswordCase

  • If set to U or Upper, the password returned from the LDAP database is converted to uppercase before authentication.
  • If set to L or Lower, the password is converted to lowercase.
  • If set to O or Original, the password is not altered before authentication.

Default value is Original.

PasswordFormat

By default, the PasswordFormat parameter is not listed in the [Settings] section of the LDAP configuration file. With no listing, Steel-Belted Radius Carrier expects the user's password in the LDAP table is in cleartext format.

If you want to configure Steel-Belted Radius Carrier to automatically handle password values correctly when it detects that they have been encrypted using UNIXcrypt or a SHA1+Base64 hash, set PasswordFormat to auto.

Search

Specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same *.aut file.

SSL

  • If set to 0, SSL is not used over the LDAP connection.
  • If set to 1, SSL is used over the LDAP connection.

Default value is 0.

Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

If SSL=1, then the Host parameter in [Server/name] accepts LDAP-style URIs. For example, ldaps://hostname:port.

MaxScriptSteps

Specifies the maximum number of statements that a script can execute before terminating. You can use the MaxScriptSteps parameter to make sure a script does not get caught in an infinite loop.

Default value is 10000.

ScriptTraceLevel

Specifies the level of detail for line-by-line script tracing in the log.

  • If set to 0, no traces are logged.
  • If set to 1, traces are only logged when the SbrTrace() function is executed by the script.
  • If set to 2, a trace is generated for every line executed by the script.

Default value is 0.

ShutdownTimeout

Specifies the maximum number of seconds to wait for outstanding database transactions when the server is in the process of shutting down. If this timeout expires, then any outstanding database transactions are forcibly aborted in order to allow the server to shut down.

Default value is 180 seconds.

Note: Changing the default value is not recommended.

FilterSpecial CharacterHandling

  • If set to 1, specifies that non-alphanumeric characters, such as (’), is converted to an ASCII hex value preceded by a backslash when they are encountered in a username during authentication.
  • If set to 0, non-alphanumeric characters are not converted during authentication.

Default value is 1.

In support of RFC 2254, the following substitutions are made when set:

  • replace '(' with "\\28"
  • replace ')' with "\\29"
  • replace '*' with "\\2a"
  • replace '\' with "\\5c"

FlashReconnect

  • If set to 1, SBR Carrier attempts to reconnect to an LDAP database server when the LDAP database server goes down. When this setting is enabled, SBR Carrier immediately attempts to reconnect to the LDAP database server if a Bind or a Search operation fails and sends an Access-Reject if the connection attempt is unsuccessful.

    Note: If SBR Carrier has not successfully connected to the LDAP database server since startup, SBR Carrier directly rejects the request without performing any Bind or Search operation even if this parameter is set to 1.

  • If set to 0, SBR Carrier sends an Access-Reject before the reconnection is attempted.

This setting applies to all servers. To apply this setting for a particular server, configure the FlashReconnect parameter in the [Server/name] section.

Default value is 1.

LdapVersion

Specifies the version of LDAP protocol.

Default value is 3.

OnFound

 

Specifies the next request section when data is found. The value of this parameter is a string, name. The name specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same .aut file. If there is no next request section, the overall operation succeeds. This can be overridden using the $reject keyword, which causes the operation to fail when data is found.

OnNotFound

 

Specifies the next request section when data is not found. The value of this parameter is a string, name. The name specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same .aut file. If there is no next request section, the overall operation fails. This can be overridden using the $accept keyword, which causes the operation to succeed when data is not found.

Password

Specifies the password string, which can include variables, used to specify a Bind before any search within a request. If this parameter is not specified, the packet's password is used.

UTC

  • If set to 0, time values are displayed using the local time.
  • If set to 1, time values are displayed using UTC (GMT).

[Server] Section

The [Server] section lists the LDAP servers that may be used to perform authentication. You can specify more than one server in the [Server] section for load-balancing or backup. When more than one server is specified, Steel-Belted Radius Carrier authenticates against these databases in a round-robin fashion.

The syntax is:

[Server]ServerName=TargetNumberServerName=TargetNumber...

where ServerName is the name of a configuration file section that contains configuration information for that server, and TargetNumber is an activation target number, a number that controls when this server is activated for backup purposes. TargetNumber is optional and may be left blank. For example:

[Server]
s1 =
s2 =
[Server/s1]
.
. ;Connection details for server s1
.
[Server/s2]
.
. ;Connection details for server s2

A Steel-Belted Radius Carrier server maintains connectivity with its LDAP servers according to the following rules:

  • The priority of the server by order. The first entry in the [Server] section has the highest priority.
  • By activation target number. The rule for the activation target is that if the number of LDAP servers that Steel-Belted Radius Carrier is connected to is less than the activation target, Steel-Belted Radius Carrier connects to the server and includes it in the round-robin list. While the number of active servers is equal to or greater that the activation target, Steel-Belted Radius Carrier does not use that server in the round-robin list. An activation target of 0 indicates that, in the current configuration, this machine is never used.

[Server/name] Sections

Several sections of the LDAP configuration file work together to configure the connection between the Steel-Belted Radius Carrier server and the LDAP database server. The sections are [Server], [Server/name], and [Settings].

Each [Server/name] section of the LDAP configuration file contains configuration information about a single LDAP server. You must provide a [Server/name] section for each server named in the [Server] section. For example:

[Server]
s1=
s2=

[Server/s1]
Host = ldap_1
Port = 389
.
.
.
[Server/s2]
Host = 130.4.67.1
LastResort = 1
.
.
.

Table 165 lists the settings that may be present in a [Server/ name ] section:

Table 165: [Server/name] Syntax

Parameter

Function

Bind

For Bind, you must specify a Bind template in the [Settings] section of the LDAP configuration file.

The Bind template must follow conventional LDAP syntax. It may be as simple or as complex as LDAP syntax permits, with multiple attribute/value assertions in Boolean combination. It may also include replacement variables from the Variable Table.

Each replacement variable consists of the variable name enclosed in angle brackets (<>). Upon execution of the LDAP Bind request, the value of the variable replaces the variable name.

For example, a Bind template that uses the User-Name attribute from the RADIUS request might look like this:

uid=<User-Name>, ou=Special Users, o=bigco.com

BindName

For BindName, the BindName parameter specifies the distinguished name (DN) to be used in the Bind request that connects to the LDAP server. The [Server/name] section lets you specify a unique BindName for a specific server. Use the [Settings] section to specify a default BindName to use for all servers.

For Bind, omit all Bind, BindName and BindPassword parameters and use the Bind parameter in the [Settings] section.

See [Settings] Section.

BindPassword

For BindName, you must provide a BindPassword. The BindPassword specifies the password to be used in the Bind request that connects to the LDAP server. The [Server/name] section lets you specify a unique BindPassword for a specific server. Use the [Settings] section to specify a default BindPassword to use for all servers.

For Bind, omit the BindName and BindPassword parameters. Use the Bind parameter instead.

Certificates

Specifies the path of the certificate database for use with SSL. This path must not end in a filename.

ConnectTimeout

Specifies the number of seconds to wait when attempting to establish the connection to the database before timing out. This value is passed to the client database engine, which may or may not implement the feature.

FlashReconnect

  • If set to 1, SBR Carrier attempts to reconnect to an LDAP database server when the LDAP database server goes down. When this setting is enabled, SBR Carrier immediately attempts to reconnect to the LDAP database server if a Bind or a Search operation fails and sends an Access-Reject if the connection attempt is unsuccessful.

    Note: If SBR Carrier has not successfully connected to the LDAP database server since startup, SBR Carrier directly rejects the request without performing any Bind or Search operation even if this parameter is set to 1.

  • If set to 0, SBR Carrier sends an Access-Reject before the reconnection is attempted.

This setting applies to a particular server. To apply this setting for all servers, configure the FlashReconnect parameter in the [Settings] section.

Default value is 1.

Host

The hostname or IP address of the LDAP server.

Note: For SSL configurations, the host name field accepts only LDAP-style URIs. For example, ldaps://hostname:port.

LastResort

You may identify a last resort LDAP server by providing a LastResort parameter in one of these [Server/name] sections, and setting its value to 1. If an LDAP query against some other server results in no record found, the server tries the last resort server before accepting or rejecting the user.

You might use the LastResort parameter to identify your master accounts database. This enables Steel-Belted Radius Carrier to cover the case in which a user account is newly added but has not yet been propagated to all the LDAP databases.

LdapVersion

Specifies the version of LDAP protocol, if needed to override the default given in the [Settings] section.

MaxConcurrent

Specifies the maximum number of LDAP requests that may be executing at one time.

You can enter the value in the range from 1 through 1000. Default value is 1.

Note: A setting of MaxConcurrent = 1 is sufficient for all but the most demanding environments. Increase this value slowly and conservatively. For more information about executing overlapping LDAP statements, see the SBR Carrier Administration and Configuration Guide.

MaxWaitReconnect

Specifies the maximum number of seconds to wait after successive failures to reconnect after a failure of the database connection.

WaitReconnect specifies the time to wait after failure of the database connection. This value is doubled on each failed attempt to reconnect, up to a maximum of MaxWaitReconnect.

Password

Specifies the password string, which can include variables, used to specify a Bind before any search within a request. If this parameter is not specified, the packet's password is used.

Port

The TCP port of the LDAP server, or 0 to use the standard port.

Default value is 0.

Note: For SSL configurations, the default port setting is ignored and the LDAP-style URI for Host is applied. For example, ldaps://hostname:port.

QueryTimeout

Specifies the number of seconds to wait for the execution of an LDAP request to complete before timing out. This value is passed to the database engine, which may or may not implement the feature.

SSL

  • If set to 0, SSL is not used over the LDAP connection.
  • If set to 1, SSL is used over the LDAP connection.

Default value is 0.

WaitReconnect

Specifies the number of seconds to wait after a failure of the database connection before trying to connect again.

[Search/DoLdapSearch] Sections

Each [Search/name] section (Table 166) in the LDAP configuration file specifies the complete details of one LDAP Search request. You can use the same Search request on various databases, because the details of the database connection are specified separately.

For BindName, you must ensure that each [Search/name] section searches for a database entry that matches the incoming username and retrieves from it an attribute containing that user’s password. Steel-Belted Radius Carrier must compare this password to the one it received in the incoming AccessRequest packet.

A [Search/name] section may retrieve other LDAP attributes as well; however, if you are authenticating with BindName, the user’s password is a minimum requirement. Use the Attributes parameter to specify the list of items you want returned.

For example:

[Search/DoLDAPSearch]
Base = ou=Special Users, o=bigco.com
Scope = 1
Filter = uid=<User-Name>
Attributes = InterestingAttributes
Timeout = 20
%DN = dn

[Attributes/InterestingAttributes]
User-Secret
RADIUS-Profile
Inactivity-Timeout

[Response]
%Password = User-Secret
%Profile = RADIUS-Profile
Vendor-Specific-NAS-Attribute = Inactivity-Timeout

Table 166: [Search/name] Syntax

Parameter

Function

%DN

Specifies a variable into which the distinguished name that results from the Search is placed.

Attributes

Specifies the LDAP attributes relevant to Steel-Belted Radius Carrier, by referencing an [Attributes/name] section elsewhere in the same .aut file.

Base

Specifies the distinguished name (DN) of the entry that serves as the starting point for the search. This filter is a template for an LDAP distinguished name string. The filter follows conventional LDAP syntax and may be as simple or as complex as LDAP syntax permits. It may also include replacement variables from the Variable Table.

Each replacement variable consists of the variable name enclosed in angle brackets (<>). Upon execution of the LDAP Search request, the value of the variable replaces the variable name.

OnFound

Specifies the next request section when data is found. The value of this parameter is a string, name. The name specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same .aut file. If there is no next request section, the overall operation succeeds. This can be overridden using the $reject keyword, which causes the operation to fail when data is found.

OnNotFound

Specifies the next request section when data is not found. The value of this parameter is a string, name. The name specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same configuration file. If there is no next request section, the overall operation fails. This can be overridden using the $accept keyword, which causes the operation to succeed when data is not found.

Search

(Optional) Specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same configuration file. Steel-Belted Radius Carrier tries this Search request next, if the current Search yields no result. Each [Search/name] section may contain at most one Search parameter.

Filter

Specifies the filter to apply to the search. This filter is a template for an LDAP Search string. The filter follows conventional LDAP syntax and may be as simple or as complex as LDAP syntax permits, with multiple attribute/value assertions in Boolean combination. It may also include replacement variables from the Variable Table.

Each replacement variable consists of the variable name enclosed in angle brackets (<>). Upon execution of the LDAP Search request, the value of the variable replaces the variable name.

For example, a Search template that uses the User-Name and Service-Type attributes from the RADIUS request might look like this:

(&(uid = <User-Name>)(type = <Service-Type>))

Scope

Specifies the scope of the search; 0 (search the base), 1 (search all entries one level beneath the base), or 2 (search the base and all entries beneath the base at any level).

The Search parameter can be used in one [Search/ name ] section after another to create a serial chain of Search requests. Every Search in the chain is tried. If any Search fails to return data, the Access-Request is rejected.

An example of a two-part chained Search follows:

[Settings]
Search = DoLdapSearch

[Search/DoLdapSearch]
Base = …
Filter = …
Search = GetMoreLdapInfo

[Search/GetMoreLdapInfo]
Base = …
Scope = …
Filter = …

Search sequencing is flexible. You can proceed to a new search even if the current search returns no data by using the OnNotFound parameter. You can override search results using the $reject and $accept keywords. The following is an example of flexible searching:

[Search/DoSearch2]
Base = o=xyz.com
Scope = 2
Filter = uid=<User-Name>
Attributes = AttrList
Timeout = 20
%DN = dn
OnFound = DoSearch8
OnNotFound = DoSearch9

[Search/DoSearch8]
Base = o=xyz.com
Scope = 2
Filter = uid=<User-Name>
Attributes = AttrList
Timeout = 20
%DN = dn
OnFound = DoSearch9
OnNotFound = DoSearch9

[Search/DoSearch9]
Base = o=xyz.com
Scope = 2
Filter = uid=<User-Name>
Attributes = AttrList
Timeout = 20
%DN = dn
OnNotFound = $accept

Modified: 2017-09-27