Configuration Parameters

In this section

Component Parameters

Data Source Sections

Adding sections for new data sources

The component uses configuration parameters specified in the [LookupD] section of the unified configuration file of Dr.Web for UNIX Mail Servers.

Component Parameters

The section contains the following parameters:

Parameter

Description

LogLevel

{logging level}

Logging level of the component.

If the parameter value is not specified, the DefaultLogLevel parameter value from the [Root] section is used.

Default value: Notice

Log

{log type}

Logging method of the component.

Default value: Auto

ExePath

{path to file}

Path to the component executable.

Default value: <opt_dir>/bin/drweb-lookupd.

For GNU/Linux: /opt/drweb.com/bin/drweb-lookupd.

For FreeBSD: /usr/local/libexec/drweb.com/bin/drweb-lookupd

RunAsUser

{UID | user name}

The name of the user as whom the component runs. The user name can be specified either as the user numerical UID or as the user login. If the user name consists of numbers (i.e. similar to numerical UID), it is specified with the “name:” prefix, for example: RunAsUser = name:123456.

When a user name is not specified, the component operation terminates with an error after the startup.

Default value: drweb

IdleTimeLimit

{time interval}

Maximum idle time for the component. When the specified period of time expires, the component shuts down.

Acceptable values: from 10 seconds (10s) to 30 days (30d) inclusive.
If the None value is set, the component will functionate eternally; the SIGTERM signal will not be sent if the components goes idle.

Default value: 10m

DebugLibldap

{logical}

Include debug messages of the libldap library in the log at the debug level (i.e. with LogLevel = DEBUG).

Default value: No

LdapCheckCertificate

{No | Allow | Try | Yes}

The mode of certificate verification for LDAP connections via SSL/TLS.

Allowed values:

No—do not request a server certificate;

Allow—request the server certificate. If the certificate is not provided, the session will continue normally. If the server certificate is provided but cannot be scanned (it is impossible to find the corresponding root certificate), the certificate will be ignored and the session will be running normally;

Try—request the server certificate. If the certificate is not provided, the session will continue normally. If the server certificate is provided but cannot be verified (it is impossible to find the corresponding root certificate), the session will be terminated;

Yes—request the server certificate. If the certificate is not provided or cannot be verified (it is impossible to find the corresponding root certificate), the session will be terminated.

For LDAP data sources this certificate verification mode influences the way the URL is processed when the ldaps:// scheme or the StartTLS extension is used; and for AD data sources it will influence connections to the server, if UseSSL=Yes has been specified in the corresponding section (see below).

Default value: Yes

LdapCertificatePath

{path to file}

Path to the SSL certificate used for secure connection to LDAP servers (Active Directory) via SSL/TLS.

Note that the certificate file and the private key file (which is specified by a parameter described below) must form a matching pair.

Default value: (not specified)

LdapKeyPath

{path to file}

Path to the private key used for secure connection to LDAP servers (Active Directory) via SSL/TLS.

Note that the certificate file and the private key file (which is specified by the mentioned parameter) must form a matching pair.

Default value: (not specified)

LdapCaPath

{path}

Path to the directory or file with a list of root certificates which are trusted for sharing data using the LDAP protocol via SSL/TLS.

Default value: <Path to the system list of trusted certificates.>. The path depends on your GNU/Linux distribution.

For Astra Linux, Debian, Linux Mint, SUSE Linux and Ubuntu this is usually the path /etc/ssl/certs/.

For CentOS and Fedora—the path /etc/pki/tls/certs/ca-bundle.crt.

For other distributions, the path can be defined by running the command openssl version -d.

If the command is unavailable or the OS distribution could not be identified, the value /etc/ssl/certs/ is used.

DbIdleTimeout

{time interval}

The time-out period at the end of which an established connection to a database (or a Redis storage) will be broken if it is idle.

Default value: 5m

MysqlDefaultConn

{URL}

The URI that defines default parameters for connecting to a MySQL database.

Allowed values:

tcp://[<user>[:<password>]@][<host>][:<port>][/<database name>][?<parameter>=<value>[&…]];

unix://[<user>[:<password>]@]<socket path>[:<database name>][?<parameter>=<value>[&…]].

Take notice of the URI requirements.

Default value: (not specified)

PqDefaultConn

{URL}

The URI that defines default parameters for connecting to a PostgreSQL database.

Allowed values:

tcp://[<user>[:<password>]@][<host>][:<port>][/<database name>][?<parameter>=<value>[&…]];

unix://[<user>[:<password>]@]<socket path>[:<database name>][?<parameter>=<value>[&…]].

Take notice of the URI requirements.

Default value: (not specified)

SqliteDefaultConn

{path to file}

Path to a default SQLite database file (specify the file:// scheme prefix).

Default value: (not specified)

RedisDefaultConn

{URL}

The URL that defines default parameters for connecting to a Redis database.

Allowed values:

tcp://[<password>@][<host>][:<port>][/<database index>];

unix://[<password>@]<socket path>[:<database index>].

Take notice of the URI requirements.

Default value: (not specified)

URI requirements for database connection

1.Only the tcp:// and unix:// scheme prefixes (for local UNIX sockets) are used. Database-specific prefixes (such as postgresql:// and mysql://) are not supported. Path to a SQLite database file is specified with the file:// scheme prefix.

2.If the <host> field is not specified in the URI or the localhost host is specified, the 127.0.0.1 host address is substituted. In this case by default the connection to MySQL and PostgreSQL databases is established using a local UNIX socket despite that a network connection is specified.

3.If URI fields (such as <user>, <password>, <database name>, and so on) or the connection parameter string contain special characters (space, column, and so on), use hex coding, for example:

space—"%20";

':' — "%3A";

'/' — "%2F";

'@' — "%40";

'%' — "%25".

4.For MySQL, the connection parameter string can only include the following parameters:

Parameter name

Convention in database documentation

Type

Description

init

MYSQL_INIT_COMMAND

String

An SQL command to be run after connecting to the database

compression

MYSQL_OPT_COMPRESS

Logical

Use data compression

connect-timeout

MYSQL_OPT_CONNECT_TIMEOUT

Integer

Time-out for disconnecting an unused connection in seconds

reconnect

MYSQL_OPT_RECONNECT

Logical

Allow or deny automatic reconnection

read-timeout

MYSQL_OPT_READ_TIMEOUT

Integer

Time-out for receiving packets from the server in seconds

write-timeout

MYSQL_OPT_WRITE_TIMEOUT

Integer

Time-out for sending packets to the server in seconds

charset

MYSQL_SET_CHARSET_NAME

String

Character encoding used for the default connection

plugin-dir

MYSQL_PLUGIN_DIR

String

Path to the server directory storing plug-ins

nonblock

MYSQL_OPT_NONBLOCK

Integer

Stack size for non-blocking I/O operations

ssl-key

MYSQL_OPT_SSL_KEY

String

Path to a private key (in the PEM format) used to establish a secure connection

ssl-cert

MYSQL_OPT_SSL_CERT

String

Path to a public key certificate (in the PEM format) used to establish a secure connection

ssl-ca

MYSQL_OPT_SSL_CA

String

Path to a file (in the PEM format) containing trusted CA certificates

ssl-capath

MYSQL_OPT_SSL_CAPATH

String

Path to a directory containing trusted CA certificates (in the PEM format)

ssl-cipher

MYSQL_OPT_SSL_CIPHER

String

List of supported encryption algorithms for a secure connection

ssl-crl

MYSQL_OPT_SSL_CRL

String

Path to a file (in the PEM format) containing revoked certificates

ssl-crlpath

MYSQL_OPT_SSL_CRLPATH

String

Path to a directory containing revoked certificates (in the PEM format)

ssl-fp

MARIADB_OPT_SSL_FP

String

the SHA1 hash of the valid server certificate

ssl-fp-list

MARIADB_OPT_SSL_FP_LIST

String

Path to a file containing SHA1 hashes of valid server certificates

tls-passphrase

MARIADB_OPT_TLS_PASSPHRASE

String

Password for a password-protected client private key

tls-version

MARIADB_OPT_TLS_VERSION

String

List of supported TLS versions

server-verify-cert

MYSQL_OPT_SSL_VERIFY_SERVER_CERT

Logical

Allow or deny verification of server certificates

server-public-key-path

MYSQL_SERVER_PUBLIC_KEY

String

Path to a file (in the PEM format) containing an RSA public key of the server

Read more on these parameters in the database documentation: https://mariadb.com/kb/en/mysql_optionsv/.

5.For the PostgreSQL database also refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS.

Data Source Sections

In addition to the general section [LookupD], the configuration file also contains sections that describe connections to data sources (one section for each connection). These sections are named using the following scheme: [LookupD.<type>.<name>], where:

<type>—connection type:

LDAP—for a directory service using LDAP;

AD—for a directory service using Active Directory;

AllMatch—for a text file in the AllMatch mode (full match);

Mask—for a text file in the Mask mode (mask matching);

Regex—for a text file in the Regex mode (matching a regular expression in the PCRE standard);

Cidr—for a text file in the Cidr mode (matching IP addresses and/or ranges);

Pq—for a PostgreSQL database;

Mysql—for a MySQL database;

Sqlite—for an SQLite database;

Redis—for a Redis database;

<name>—a unique identifier (tag) for the connection, by which the connection can be referred to from the rules.

For example: [LookupD.LDAP.auth1]. Connection-specific sections comprise a set of parameters depending on a source type. The number of sections is unlimited.

1.Parameters used in LDAP sections

Parameter

Description

Url

{string}

URL that defines the used LDAP server and extracted data. In accordance with RFC 4516, the URL is constructed on the basis of the following scheme:

<scheme>://<host>[:<port>]/<dn>[?<attrs>[?<scope>[?<filter>[?<extensions>]]]]

Where:

<scheme>—method of connection to the server (the following schemes are allowed: ldap, ldaps and ldapi);

<host>[:<port>]—LDAP server address at which the request is sent;

<dn>—distinguished name of an object, information about which is received;

<attrs>—names of record attributes, the values of which must be received in the request;

<scope>—search scope (base, one, sub);

<filter><filter>—filtering condition for the values of extracted attributes;

<extensions>—list of LDAP extensions used in the request.

Features

In the list of attributes <attrs>, it is possible to use special characters of choice '*', '+' and '1.1'.

The following automatically resolved placeholders can be used in the <dn> and <filter> parts of the URL:

$u is automatically replaced with user—the user name sent by a client component;

$d is automatically replaced with domain—the domain sent by the client component;

$D—a chain of <subdomain>.<domain> transformed into dc=<subdomain>,dc=<domain>;

$$—the '$' symbol.

If the <filter> condition requires using special characters (for example: '*', '(', ')', '\', the character with code 0) as usual ones, they should be formatted as \XX. Besides, special characters in the LDAP URL are encoded using %XX sequences. For example, when using the '/' character in a URL in the ldapi scheme as a part of the path to a local LDAP server socket, this character is encoded as %2f.

As allowed extensions in <extensions>, only StartTLS and 1.3.6.1.4.1.1466.20037 are supported, they use TLS (i.e. a protected connection with the LDAP server is established, even if the use of the ldaps protected scheme is not explicitly indicated). If the name of the used extension is preceded by the character '!', then the use of TLS is required, i.e. in case it is impossible to establish the secure connection, the request will not be handled. Otherwise, the request will be handled even if the secure connection is not established.

These extensions cannot be used with the protected ldaps scheme. For more information refer to RFC 4516 or man ldap_search_ext_s.

Examples:

"ldaps://ds.example.com:990/$D?givenName,sn,cn?sub?(uid=$u)"
"ldap://ldap.local/o=org,dc=nodomain?ipNetworkNumber?sub?(objectClass=ipNetwork)?!StartTLS"

Default value: (not specified)

BindDn

{string}

An object in the LDAP directory to which the user is bound to get authorization.

Example: "cn=admin,dc=nodomain".

Default value: (not specified)

BindPassword

{string}

The password for authentication on the LDAP server.

Default value: (not specified)

ChaseReferrals

{logical}

Follow or not to follow references to other LDAP servers, if the current LDAP server returns them in response to requests.

Default value: No

2.Parameters used in AD sections

Parameter

Description

Host

{string}

Domain name (FQDN) or IP address of a host running the server of the Active Directory service to be connected to.

Example: "win2012.win.local".

Default value: (not specified)

Port

{integer}

Port on the host which is listened to by the server of the Active Directory service.

Default value: 389

Dn

{string}

DN of an object in the Active Directory (similar to the dn part of an LDAP URL).

Example: "dc=win,dc=local".

Default value: (not specified)

User

{string}

Full identifier of a user on the server.

Example: "Administrator@WIN.LOCAL".

Default value: (not specified)

Password

{string}

The password for authentication on the Active Directory server.

Default value: (not specified)

ChaseReferrals

{logical}

Follow or not to follow references to other LDAP servers, if the current Active Directory server returns them in response to requests.

Default value: No

UseSSL

{logical}

Use SSL/TLS for connecting to an Active Directory server.

Default value: No

3.Parameters used in AllMatch, Mask, Regex, and Cidr sections

Parameter

Description

File

{path}

Path to a text file containing search strings.

Example: "/etc/file1".

Default value: (not specified)

 

Features

Strings from a file specified in the section of the AllMatch type are used in a case-insensitive search to find a full match.

Strings of a file specified in the section of the Mask type are treated as masks (wildcards). Masks can be considered a simplified version of regular expressions containing special characters besides standard ones. Comparing the strings with the masks is case-insensitive. Masks can contain the following special characters and expressions:

*—any character sequence;

?—any character;

[<character set>]—any character from the set (for example, [bac]);

[!<character set>]—any character that does not match any character from the set (for example, [!cab]);

[[:<class>:]]—any character from the provided POSIX character class (alnum, alpha, ascii, blank, cntrl, digit, graph, lower, print, punct, space, upper, xdigit).

A mask matching some substring must cover a search substring surrounded by “*” characters (e.g., *host*). If you need to specify one of special characters, you need to escape such character with the backslash: \[, \], \*, \?. If needed, the backslash can be escaped as well: \\. There is no need to escape any other characters, e.g. the \a\b\c\*\d\?\\ string will be converted to the abc*d?\ string. Examples of masks:

#Matches the “name” string exactly
name

#Matches three-character strings where
#the first character is “c”, the second is any, and the third is “t”
#For example: cat, cut, cct
c?t

#Matches strings user, users, us3rr, ussr1, and so on
#(the [:alpha:] character class matches any alphabetical
#character, the special character ? matches any character)
us[[:alpha:]34]r?

#Matches strings .con, file.col, 3...co!, and so on
#(before .co—any character sequence, after—
#any character except m and ?)
*.co[!m\?]

#Matches any string comprising the host part,
#for example: host, localhost, hostel, ghosts
*host*

Strings from a file specified in the section of the Regex type are interpreted as PCREs (Perl Compatible Regular Expressions). Matching strings with regular expressions is done case-insensitively. Examples of regular expressions:

#IPv4
(\d{1,3}.){3}\d{1,3}

#Email address in the .com domain
\w+@\w+\.com

Strings from a file specified in the section of the Cidr type are interpreted as IP addresses or IP address ranges. Both IPv4 and IPv6 formats for IP addresses as well as address ranges are allowed. A subnet mask can be specified in the bit (octet) format, as well as in the CIDR (Classless Inter-Domain Routing) notation, for example:

#IPv4
192.168.0.1
192.168.0.0/12
192.168.0.0/255.255.255.224

#IPv6
fe80::c7e8/32
fe80::c7e8/255.255.255.224

4.Parameters used in the Pq, Mysql and Sqlite sections

Parameter

Description

Conn

{string}

Database connection string.

Allowed values:

for the Mysql (MySQL) and Pq (PostgreSQL) sections:

tcp://[<user>[:<password>]@]<host>[:<port>][/<database name>][?<parameter>=<value>[&…]];

unix://[<user>[:<password>]@]<socket path>[:<database name>][?<parameter>=<value>[&…]];

Example: "tcp://user:pwd@localhost:1234/userdb", "unix://user:pwd@/tmp/pgsql.sock:userdb".

Note the URI requirements;

for the Sqlite (SQLite) section:

Path to a database file (specify the file:// scheme prefix).

Example: "file:///home/user/users.db".

Default value: defined by the corresponding *DefaultConn parameter value

Request

{string}

String of an SQL query (SELECT) to the database. Like with AD and LDAP sources, the following automatically permitted markers can be used in the query:

$u, $U are replaced with user—the user name sent by a client component;

$d, $D are replaced with domain—the domain sent by the client component;

$$ is replaced with '$' character.

Example: "SELECT username FROM users INNER JOIN domains ON users.domain = domains.id WHERE domains.name = $d AND users.name = $u".

Default value: (not specified)

Only the query of the SELECT type can be specified as an SQL query. After making substitutions, the query is passed to the database “as is”. If the query result contains more than one column, then all columns except the first one will be ignored.

5.Parameters used in Redis sections

Parameter

Description

Conn

{string}

Redis data storage connection string.

Allowed values:

tcp://[<password>@]<host>[:<port>][/<database index>];

unix://[<password>@]<socket path>[:<database index>];

Take notice of the URI requirements.

Example: "tcp://localhost:6379".

Default value: defined by the RedisDefaultConn parameter value

Request

{string}

Redis storage query string. The following automatically permitted markers can be used in the query:

$u, $U are replaced with user—the user name sent by a client component;

$d, $D are replaced with domain—the domain sent by the client component;

$$ is replaced with '$' character.

Example: "HVALS bad_users".

Default value: (not specified)

If the query result contains more than one column, then all columns except the first one will be ignored.

Adding sections for new data sources

To add a new section for a data source of some type with a <name> tag using the Dr.Web Ctl command-line management tool for Dr.Web for UNIX Mail Servers (run with the drweb-ctl command), it is sufficient to use the following command:

# drweb-ctl cfset LookupD.<type> -a <name>

Example:

# drweb-ctl cfset LookupD.AD -a WinAD1
# drweb-ctl cfset LookupD.AD.WinAD1.Host 192.168.0.20

The first command will add a section named [LookupD.AD.WinAD1] to the configuration file, and the second command will modify the value of the Host parameter within this section.

Alternatively, you can write the new section directly to the configuration file (for example, by adding it to the end of the file):

[LookupD.AD.WinAD1]
Host = 192.168.0.20

Both methods of configuring have an equal effect; however, editing the configuration file directly requires applying the changed settings by sending a request for restart to the drweb-configd module. To do that, run the following command:

# drweb-ctl reload