LDAP Directory

Your organization's email accounts, alias addresses and distribution lists are often kept on a directory server (OpenLDAP or Zimbra's own LDAP). For DeepFilter to verify the recipient of inbound email against this directory and to show how many accounts and addresses each domain has, it must be able to connect to that directory.

The LDAP Directory tab defines this connection: it determines through which servers, with which security setting and with which identity the directory is reached, tests the connection, and shows the account, alias and distribution list inventory in the directory on a per-domain basis. The profiles defined here are used by the LDAP / Directory method of Recipient Verification on the Inbound Email → SMTP Flow screen (see Inbound Email); the profiles used by that method are synced at regular intervals.

The connection is not a single definition: each directory source is a directory profile. Unlike Zimbra SOAP profiles, a directory profile is not tied to a delivery server; it describes the directory itself. The server list inside a profile is ordered and provides redundancy (failover): if the first server does not answer, the next one is tried.

You reach the LDAP Directory screen through Management → Integration → LDAP Directory.

note

The Integration menu and this screen are visible only to users with the global administrator role; domain administrators do not see this section in the menu.

What Is on the Screen

The Directory profiles section lists the defined profiles in a table. If there is no profile yet, the message "No directory profile defined yet" and the Add profile button appear.

Column	What it shows
Profile	The name of the profile; if the profile is off, a Disabled badge next to it. Below it, the sync interval and lock threshold are written (for example "Every 15 minutes · lock threshold 20%"). If a test was run from the row in this session, its result (Success, Warning, Error) and time also appear here.
Directory type	OpenLDAP or Zimbra LDAP.
Servers	The server list (address:port), with the transport security and the base DN (or "root" if empty) below it. If the connection is unencrypted, Unencrypted appears; if certificate verification is off, a "Certificate verification off" warning appears.
Usage	If the profile is used in Recipient Verification, "Recipient verification" together with the names of the delivery servers and the number of domains covered; if it is not used, "Not in use".
Last sync	The sync status and time (see Sync and Lock); below it, the mailbox · alias · list counts of the applied list and the duration of the sync.
Actions	The Sync, Test, Edit and Delete buttons.

If a profile's last sync was locked or failed, a warning band opens below the row (see Sync and Lock).

A profile used in Recipient Verification cannot be deleted; first remove the profile link from the delivery server or domain on the Inbound Email → SMTP Flow screen.

Profile Settings

The fields in this section are edited in the Add directory profile / Edit directory profile window, opened with Add profile or with Edit on a row, and take effect with the window's Save button. The window consists of six sections: General, Servers, Connection security, Credentials, Sync and Advanced filters.

General

Profile name — The name shown in the list and in records (for example "Staff directory"). At most 100 characters; a second profile with the same name cannot be defined.

Profile enabled — Whether the profile is in use. (default: On)

If you change the value: A disabled profile is not queried, but its definition is kept; when you turn it back on, it returns with its settings. A disabled profile cannot be used in Recipient Verification.

Directory type — OpenLDAP or Zimbra LDAP. (default: OpenLDAP)

Why it exists: Directory schemas keep accounts and addresses in different attributes. The type selection fills the filter and attribute fields in the Advanced filters section with that schema's suggested values.

• OpenLDAP — Counts person entries that have a mail address as accounts; the distribution list filter comes empty, because the list schema is not standard in generic LDAP. If you know your organization's list schema, enter the filter yourself.
• Zimbra LDAP — Counts only active Zimbra accounts (excluding system resources); it also reads alias addresses, distribution lists and domain aliases.

Servers

The directory servers the profile connects to. Each row has a server address (name or IP) and a port. The servers are tried in order from top to bottom; the first one that answers is used. Add server adds a new row, and the arrow buttons (Move up / Move down) change the order. At most 8 servers can be defined; at least one server is required.

The server address cannot be a local address (loopback/link-local); enter the network address of the directory server.

Connection security

Transport security — STARTTLS, LDAPS or Unencrypted. (default: STARTTLS)

Why it exists: The bind password and the directory content travel over the network. STARTTLS uses port 389 and LDAPS uses port 636; the port field is updated according to the selection.

If you change the value: When Unencrypted is selected, a warning appears in the window: the bind password and the directory content travel over the network in the clear. Use this option only on a trusted internal network.

Verify server certificate — Whether the server's certificate is checked against the trusted root list. (default: Off) This switch cannot be used while the transport security is Unencrypted.

If you change the value: While verification is off, a warning appears in the window: an interposed server can hide its identity. If your directory server's certificate comes from a trusted authority or from your own root certificate, turn verification on; if you have your own root certificate, turn verification on and add the PEM.

Custom root certificate (PEM) — If you use an internal certificate authority, the PEM content of the root certificate (it starts with -----BEGIN CERTIFICATE-----). This field appears only while Verify server certificate is on and the transport security is encrypted (STARTTLS or LDAPS). When you turn verification off or switch to Unencrypted, unsaved changes in the field are discarded; the stored certificate is not touched.

If a certificate is stored, a "CA loaded: …" line and the Replace / Remove buttons appear in place of the field. If the field is left empty, the stored certificate is kept. When Remove is selected, the certificate is deleted at save time; if a bind password is stored, you are asked to enter it again. To remove a stored certificate, first turn verification on; only then does the field appear.

tip

If you define the server by IP address, the name in the certificate cannot be verified and the test reports this as a warning. Use the server's DNS name if possible.

Credentials

Bind DN — The DN of the account used to connect to the directory (for example uid=deepfilter,ou=people,dc=example,dc=com). If left empty, the directory is bound anonymously.

Bind password — The password of the bind DN. Left empty for an anonymous connection.

Why it exists: Once saved, the password is not shown on screen. If the field is left empty, the stored password is kept; Remove stored password deletes it at save time.

If you change the value: When the server list, the bind DN or the trust setting (certificate verification, transport security, root certificate) changes, the stored password is not used for the new target; you are asked to enter the password again before continuing.

Base DN — The node under which the search is performed (for example dc=example,dc=com).

If you change the value: If left empty, the search starts from the root of the directory. In Zimbra every domain is a separate tree at the root of the directory; to see all domains leave the field empty, and to count only one domain enter that domain's DN. In directories with more than one root (suffix), an empty Base DN scans each root separately.

Timeout (s) — The longest time to wait for an answer from the server; 3–120 seconds. (default: 10)

Sync

Profiles used in recipient verification are read regularly with these settings. Unlike the 30-second limit of the test screen, a sync can take up to 5 minutes. No scheduled sync is performed for a profile that is not used in Recipient Verification.

Sync interval — How often the directory is read; chosen from options between 5 minutes and 24 hours. (default: 15 min)

If you change the value: A new account created in the directory is accepted within this period at the latest. Shortening the interval makes new accounts recognized sooner, but queries reach the directory server more often.

Lock threshold (%) — The drop ratio that stops the new list from being applied; 0–90. (default: 20)

Why it exists: A wrong filter or a partial read on the directory side can make the address count drop suddenly. If such a list were applied, email to valid recipients would be rejected. If the address count drops by more than this ratio compared to the previous list, the new list is not applied and the last successful list is kept.

The section also lists the cases where the list is never applied, regardless of the threshold: when the directory cannot be reached or authentication fails, when the result comes back empty (a base DN or filter error), and when the result comes back partial (a time limit or a server limit). In these cases the last successful list stays in use and administrators are notified.

Advanced filters

This section comes filled with the directory type's suggested values; if your directory schema differs, change them here. The Restore preset values button returns the fields to the suggested values of the selected directory type.

Field	What it does
Account filter	The LDAP filter that selects mailbox objects; it starts with a parenthesis, e.g. (objectClass=person).
Primary address attribute	The attribute holding the account's primary email address. Required.
Alias attribute	The attribute holding additional addresses; leave it empty if the directory has no aliases.
Distribution list filter	The filter that selects distribution lists. If left empty, lists are not counted.
List address attribute	The attribute holding the list's address; required when the distribution list filter is filled.
List alias attribute	The attribute holding the list's additional addresses.

Include locked accounts — With the Zimbra LDAP type, an example filter that also covers locked (locked, lockout, maintenance) accounts and this button appear below the account filter. The button replaces the account filter with the example filter. If the account filter is not in a recognized form, the warning "The filter is not recognized; apply the example manually." appears.

Domain aliases (Zimbra) — In Zimbra a domain can be an alias of another domain; the accounts of the alias domain do not exist in the directory as separate addresses. The fields in this subsection (Domain filter, Domain name attribute, Domain type attribute, Alias target attribute, Domain id attribute, Alias type value) make it possible to derive the alias domain's addresses from the target domain. They come prefilled with the Zimbra LDAP type; if left empty, domain aliases are not resolved.

Adding a Profile

Prerequisites

• Network access must be open from the DeepFilter server to the directory server's LDAP port (usually 389 for STARTTLS, 636 for LDAPS).
• You must have the bind DN and password of an account authorized to read the directory (not needed if the directory allows anonymous reads).
• If an internal certificate authority is used, the PEM content of the root certificate must be at hand.

Steps

1. Open Management → Integration → LDAP Directory.
2. In the Directory profiles section, click the Add profile button.
3. Enter a Profile name and select a Directory type; the advanced filters are filled according to the type.
4. In the Servers section, enter the address and port of the directory server; if there is a backup server, add it to the order with Add server.
5. Select the Transport security. If certificate verification is wanted, turn on the Verify server certificate switch; if an internal authority is used, paste the root certificate into the Custom root certificate (PEM) field.
6. Fill in the Bind DN, Bind password and Base DN fields.
7. In the Directory Test section at the bottom of the window, test the details without saving them using the Test connection button (see Testing a Profile).
8. Click the Save button.

Verification — how to know it worked

• The notification "Directory profile created." appears and the profile is listed as a new row. If Profile enabled was left on, no Disabled badge appears next to the name in the Profile column (the table has no separate status column; only disabled profiles are marked with a badge).
• Because the new profile has not been synced yet, the Last sync column shows Never synced, and because it is not used in Recipient Verification, the Usage column shows "Not in use".

Testing a Profile

The Directory Test checks the profile details without changing anything in the directory; it only reads. A new or edited profile is tested without saving from the Directory Test section at the bottom of the window, and a saved profile with the Test button on its row.

The test reports five steps in order — Connection, TLS, Authentication, Base DN and Inventory — and each step is a prerequisite of the one after it. The overall result is one of three values: Directory reads correctly, Directory reads partially (there is a warning) or Directory is unreachable. The duration of the test and the server connected to are shown next to the result.

Prerequisites

• The form must not contain format errors (server address, filters and attributes); otherwise the test button stays disabled.
• If you changed the server list, the bind DN or the trust setting, enter the bind password again.

Steps

1. Open Management → Integration → LDAP Directory.
2. For a saved profile, click the Test button on its row; for a new or edited profile, click the Test connection button at the bottom of the window.
3. Read the step results from top to bottom; the first red step is the source of the problem. For steps that report an error or a warning, open Technical detail to see the detail returned by the server.

Verification — how to know it worked

• The overall result is Directory reads correctly and the counters in the Inventory section are filled. The result of a test run from the row is also written below the profile name.
• While certificate verification is off, the TLS step gives the warning "Certificate verification is off — identity is not checked"; this shows that the connection works but the server's identity is not checked.

tip

Test results belong to the values at that moment. If you change something in the form, the note "Results belong to earlier values" appears above the results; run the test again before saving.

Inventory counting takes at most 30 seconds. If the time runs out, or if the directory server limits the number of results it returns, the test ends with a warning and states that the counts are partial. At most two connection tests can run at the same time.

Reading the Inventory

At the end of a successful test, three counters and a domain table appear:

Counter	What it counts
Mailbox	The mailboxes matching the account filter.
Alias entry	The additional addresses defined on accounts. It is a count of addresses, not mailboxes; values identical to the primary address are not counted again.
Distribution list	The lists matching the distribution list filter. Not counted if the filter is empty.

Domains that are Zimbra domain aliases are shown in the table with a "→ target domain" note next to their name; their addresses are derived from the target domain. The number of domains that are domain aliases is written next to the heading.

The Domain breakdown table shows the Mailbox, Alias and List counts for each domain, along with the Defined in DeepFilter column. This column tells you whether the domain in the directory is defined as a domain in DeepFilter; you can see the difference between the directory and the domain list in DeepFilter here.

Sync and Lock

Every profile used in Recipient Verification is read in full from the directory at its own Sync interval. The addresses read are checked and, if there is no problem, applied as the local recipient list. The recipient of inbound email is accepted or rejected against this list; no query goes to the directory while email is being processed.

The statuses in the Last sync column:

Status	What it means
Applied	The last sync succeeded; the new list is in use.
Syncing	A sync is in progress; the directory is being read.
Locked	The new result was not applied (zero addresses, a partial result or a drop above the lock threshold); the last successful list is in use.
Failed	The directory could not be reached, authentication failed or the query could not be completed; the last successful list is in use.
Never synced	The profile has not been synced yet.

When the status is Locked or Failed, a band opens below the row. The band states the reason (for example "Sync lock: the address count dropped by …% (before → after)"), says which list stays in use and states that administrators have been notified. The Details button shows the address count, breakdown and duration of the pending result and of the applied list, whether the result is partial, and the raw explanation from the server.

Apply anyway — Deliberately applies the locked pending result; the recipient list is regenerated. It is used when a bulk deletion really happened in the directory (for example when the accounts of departing staff were closed). The confirmation window shows the number of addresses that will be applied.

caution

Before using Apply anyway, check the address count of the pending result with Details. If the drop comes not from a real change in the directory but from a wrong filter or a partial read, applying the list causes email to valid recipients to be rejected.

Sync — Syncs the profile immediately without waiting. If a sync is already running for the same profile, a new one is not started.

When a sync cannot be applied, an LDAP Sync Not Applied notification goes to the administrators; when the sync is applied successfully again, a recovery notification arrives (see Notifications).

Things to Watch Out For

• The directory is a separate system under your management. When the bind account's password, its read permission or the server certificate changes on the directory side, the connection breaks without anything changing in DeepFilter. After maintenance on the directory side, run the test of the relevant profile again.
• Limit the bind account to read-only access. DeepFilter does not write to the directory; do not give the bind account any permission other than read.
• An unencrypted connection and disabled certificate verification lower protection. Use these settings only on a trusted internal network and only temporarily.

Troubleshooting

The test says "Connection refused" or "The server does not answer". The server address or port may be wrong, or network access from the DeepFilter server to the directory server is closed. Verify the address, the port and the transport security selection (STARTTLS 389, LDAPS 636); on a slow directory, raise the Timeout value.

The test says "The server address cannot be resolved". The server name you entered cannot be resolved in DNS. Verify the name, review the server's name resolution settings (Management → System → DNS) or temporarily enter the IP address.

The test says "The server does not support STARTTLS". The directory server does not offer STARTTLS. If the server supports LDAPS, set Transport security to LDAPS; if it does not, enable TLS on the directory server.

The test says "The TLS certificate cannot be verified". The directory server presents a self-signed certificate or one signed by an internal authority. Add the PEM content of the root certificate to the Custom root certificate (PEM) field and keep verification on.

The test says "Bind DN or password is wrong". Make sure the bind DN is a full DN and the password is current. If the password was changed on the directory side, enter the new password and save.

The test says "Base DN not found" or "The account may not read this node". The Base DN does not exist in the directory, or the bind account cannot read that node. Verify the Base DN or give the bind account read permission.

The test says "The directory does not allow searching from the root". The Base DN was left empty and the directory does not allow searching from the root. Enter the search base in the Base DN field.

The inventory shows zero or fewer than expected. The account filter or the primary address attribute may not match your directory schema. Check that the Directory type is selected correctly and, if necessary, correct the values in the Advanced filters section to match your schema. With the Zimbra LDAP type only active accounts are counted. If the Base DN points to a single domain, only that domain is counted.

The warning "The server address cannot be local (loopback/link-local)" appears. localhost or a local address was entered as the server address. Enter the network address of the directory server.

The warning "At most two connection tests can run at the same time" appears. Other tests are running; wait a moment and try again.

The last sync shows "Locked". The new result dropped by more than the lock threshold compared to the previous one, or came back empty or partial. Read the reason with Details. If the drop is a real change in the directory, apply it with Apply anyway; if not, correct the account filter and the base DN and use Sync. For partial results, review the directory server's result limit.

The last sync shows "Failed". The directory could not be reached or authentication failed. Use the profile's Test button to see which step it gets stuck on, and fix it.

The profile cannot be deleted: "The profile is used by a delivery server or a domain". The profile is used in Recipient Verification. On the Inbound Email → SMTP Flow screen, remove this profile from the Directory profiles selection of the relevant delivery server or from the domain's profile setting, then repeat the deletion.