> For the complete documentation index, see [llms.txt](https://docs.weka.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.weka.io/additional-protocols/smb-support/smb-external-ldap-posix-resolution.md). # SMB external LDAP POSIX resolution Resolve SMB POSIX user and group attributes from an external LDAP directory. ## Overview Configure WEKA SMB-W to resolve POSIX user and group attributes (`uidNumber`, `gidNumber`) from an external LDAP directory instead of from the joined Active Directory. This supports environments where an identity bridge such as Delinea Server Suite (formerly Centrify), or a standalone OpenLDAP-compatible directory, holds the POSIX attributes that AD does not. By default, SMB-W maps SMB users to POSIX identities through the joined Active Directory, using the ID mapping backend selected with `--idmap-backend` (`rid`, `rfc2307`, and so on). When POSIX attributes are not present in AD, this mapping cannot succeed and SMB access fails. Switching the cluster to NSS POSIX-resolution mode changes where those attributes come from: 1. The SMB-W server is configured with `userdb_idmap = nss`, so it delegates every POSIX lookup to the operating system's Name Service Switch instead of querying AD. 2. Inside the SMB-W container, NSS is wired to SSSD (`passwd: compat sss`, `group: compat sss`) through `libnss_sss`. 3. SSSD queries the configured external LDAP directories and returns the UID/GID to the SMB-W server. Authentication and authorization are unchanged. Users still authenticate against Active Directory, and only POSIX attribute resolution moves to LDAP. ### POSIX resolution modes Select a mode that determines where SMB-W resolves POSIX UID and GID attributes. * `ad`: Default. Resolves POSIX UID and GID attributes through the joined Active Directory. Uses the ID mapping backend set with `--idmap-backend`. * `nss`: Resolves POSIX UID and GID attributes through NSS and SSSD against configured external LDAP domains. `--idmap-backend` does not apply and cannot be combined with this mode. ### Configuration storage and application LDAP domain definitions are held in the WEKA cluster configuration. Each SMB-W container generates `sssd.conf` from that configuration into the SMB-W config filesystem (`.smbw/sssd/sssd.conf`), writes it into the container, and restarts SSSD to apply the change. As a result: * The configuration survives container restarts, server reboots, and WEKA upgrades. * Bind passwords are never stored in cleartext in `sssd.conf`. WEKA keeps them in a separate per-domain credential file and injects them in obfuscated form when SSSD starts. SSSD runs only when it is needed. If no LDAP domain is configured, no `sssd.conf` is generated, the SSSD starter exits without starting the daemon, and clusters in `ad` mode are unaffected. When NSS mode is active and an `sssd.conf` exists, SMB-W startup waits up to 60 seconds for the SSSD NSS socket before serving, so the first lookups do not race an unready daemon. The wait is skipped in `ad` mode. ### Domain names and name qualification In NSS mode, the SMB-W server passes fully qualified names (`DOMAIN\user`) to NSS, and SSSD is configured with `use_fully_qualified_names`. The SSSD domain label is therefore not arbitrary: it must match the domain name that clients present, which is the AD domain name. Any other label prevents SSSD from routing the lookup to the right LDAP source. Domain labels may contain letters, digits, `.`, `_`, and `-`. They must be unique, and uniqueness is enforced case-insensitively. ### Users without POSIX attributes Users that have no `uidNumber`/`gidNumber` in the configured LDAP directories are not assigned an identity automatically. Their lookups fail and access is denied. NSS mode has no fallback to an auto-generated UID range. ## Configure external LDAP POSIX resolution Define one or more LDAP domains, switch the cluster to NSS mode, and verify that lookups resolve. ### Before you begin * Verify that the cluster is an SMB-W cluster. This feature does not apply to the legacy SMB cluster type. * Obtain cluster admin credentials. * Collect the LDAP URI, search base, bind DN, and bind password. For encrypted connections, also obtain the CA certificate PEM file of the issuing CA. * Confirm that the LDAP directory exposes POSIX attributes under the search base you intend to use. ### Add an LDAP domain ```bash weka smb ldap-domain add \ --ldap-uri ldap://ldap.example.com:389 \ --ldap-search-base "DC=example,DC=com" \ --ldap-bind-dn "CN=svc_weka,OU=Users,DC=example,DC=com" \ --ldap-bind-password \ --ldap-schema rfc2307bis \ --start-tls \ --ca-cert /path/to/ca.pem \ --validate-before-commit ```
ParameterDescription
<domain>SSSD domain label. Must be unique and must match the domain name clients present. Letters, digits, ., _, - only.
--ldap-uriLDAP server URI, for example ldap://host:389 or ldaps://host:636. Mandatory. One URI per domain.
--ldap-search-baseLDAP search base for POSIX lookups, for example DC=example,DC=com. Mandatory.
--ldap-bind-dnService account DN used for an authenticated bind. Omit for an anonymous bind.
--ldap-bind-passwordPassword for the bind DN. If omitted, the CLI prompts for it without echoing. Set both the bind DN and the password (authenticated bind), or leave both empty (anonymous bind).
--ldap-schemaLDAP schema used for POSIX attribute resolution, for example rfc2307 or rfc2307bis. Default: rfc2307bis.
--case-sensitiveMake POSIX name lookups case-sensitive. Default: omitted, which means case-insensitive. Keep the default when AD and the LDAP directory differ in username case.
--start-tlsSecure the LDAP connection with StartTLS (sets SSSD ldap_id_use_start_tls).
--ca-certPath to the CA certificate PEM file used to verify the LDAP server certificate. When supplied, SSSD is configured with ldap_tls_reqcert = demand. Maximum size 16 KiB.
--validate-before-commitProbe the LDAP server (bind plus a POSIX attribute lookup) before writing the configuration. The domain is not added if the probe fails.
{% hint style="info" %} Passwords are passed through to LDAP verbatim, including shell metacharacters. To avoid quoting problems with complex passwords, omit `--ldap-bind-password` and enter the password at the prompt. {% endhint %} ### Switch the cluster to NSS mode Adding a domain does not by itself change how POSIX attributes are resolved. Switch the cluster mode once at least one domain is configured: ```bash weka smb cluster update --posix-resolution-mode nss ``` {% hint style="warning" %} Flipping the POSIX resolution mode bounces the SMB-W cluster, because the SMB-W server must restart to pick up the new `userdb_idmap` setting. SMB clients lose their sessions during the restart. Perform the change in a maintenance window. {% endhint %} The mode switch is rejected if no LDAP domain is configured, and `--posix-resolution-mode nss` cannot be combined with `--idmap-backend`. Create a new cluster directly in NSS mode with a single LDAP domain: ```bash weka smb cluster create ... \ --posix-resolution-mode nss \ --ldap-domain example.com \ --ldap-uri ldap://ldap.example.com:389 \ --ldap-search-base "DC=example,DC=com" \ --ldap-bind-dn "CN=svc_weka,OU=Users,DC=example,DC=com" \ --prompt-ldap-bind-password ``` Cluster creation accepts one LDAP domain and does not accept TLS parameters. Add StartTLS, a CA certificate, or further domains afterwards with `weka smb ldap-domain add` and `weka smb ldap-domain update`. ### Verify the configuration 1. Check the cluster-level SSSD health. ```bash weka smb cluster ``` The output includes `SSSD Health`, and `SSSD Last Error` when health is `failed`. For the meaning of each value, see Monitor SSSD health. 2. Test an individual domain end to end. ```bash weka smb ldap-domain test ``` The command performs a bind and a `uidNumber` lookup against the stored parameters and changes nothing: ``` bind: OK posix attributes (uidNumber): found ``` ### View configured LDAP domains ```bash weka smb ldap-domain show # list all domains weka smb ldap-domain show # show one domain ``` The table reports the domain label, LDAP URI, search base, bind DN, whether an authenticated bind is configured (`Auth Bind`), and a live per-domain connectivity `Status`. {% hint style="info" %} Bind passwords are never returned by the CLI or the API, in any output format. There is no option to reveal a stored password. {% endhint %} ### Update an LDAP domain Only the parameters you supply are changed. Everything else is left as is. ```bash weka smb ldap-domain update \ [--ldap-uri ] \ [--ldap-search-base ] \ [--ldap-bind-dn ] \ [--ldap-bind-password ] \ [--ldap-schema ] \ [--case-sensitive true|false] \ [--start-tls true|false] \ [--ca-cert ] \ [--validate-before-commit] ``` Passing an empty `--ldap-schema` resets the domain to the `rfc2307bis` default. With `--validate-before-commit`, WEKA probes the merged configuration and applies the update only if the probe succeeds. ### Rotate the bind password ```bash weka smb ldap-domain rotate-password [] ``` If `` is omitted, the CLI prompts for it without echoing it. The stored credential is replaced, the per-domain obfuscated credential file is regenerated, and SSSD is reloaded. The old password is not written to any log. ### Rotate or replace a CA certificate ```bash weka smb ldap-domain update --ca-cert /path/to/new-ca.pem ``` The new PEM replaces the stored certificate for that domain and SSSD is reloaded. ### Remove an LDAP domain ```bash weka smb ldap-domain remove ``` This stops POSIX resolution from that domain. When the last domain is removed, the generated `sssd.conf` and all per-domain credential and certificate files are deleted, and SSSD stops. {% hint style="warning" %} Removing the last LDAP domain while the cluster is still in `nss` mode leaves SMB-W with no POSIX source. LDAP users resolve to `nobody` and access fails. Switch back to `ad` mode, or add a replacement domain. {% endhint %} ### Return to AD-based resolution ```bash weka smb cluster update --posix-resolution-mode ad --idmap-backend ``` The cluster bounces, the SMB-W server returns to AD-based ID mapping, and any configured LDAP domains are retained but no longer consulted. ## Secure the LDAP connection Two independent controls apply. Use both in regulated environments: * `--start-tls` upgrades a plain `ldap://` connection on port 389 to TLS. * `--ca-cert` supplies the CA that must have issued the LDAP server certificate. When it is set, SSSD requires a verifiable server certificate (`ldap_tls_reqcert = demand`). {% hint style="warning" %} Neither control is applied implicitly. A domain added without `--start-tls` and without `--ca-cert` binds in cleartext, and an `ldaps://` URI without `--ca-cert` is not validated against a cluster-wide trust store. Always pass both when the directory holds credentials or is reached over an untrusted network. {% endhint %} ## Monitor and troubleshoot ### Monitor SSSD health `weka smb cluster` reports one of the following values:
SSSD HealthMeaning
not-configuredThe cluster is not in nss mode, or no LDAP domain is configured. SSSD is intentionally not running.
runningSSSD is running and its NSS responder socket is ready on all SMB-W servers.
failedSSSD is not running, or its NSS socket is not ready, on at least one SMB-W server. SSSD Last Error carries the most recent error text.
### Log files Inside the SMB-W container, under the host-backed `/data/log/` directory:
FileContents
sssd_starter.logStarter activity: config filesystem wait, start/skip/restart decisions, credential-obfuscation errors.
sssd.logSSSD daemon output.
sssd_redacted.confSnapshot of the active sssd.conf with bind tokens stripped, for diagnostics.
The generated `sssd.conf` is marked `#DO NOT EDIT (managed by Weka)` and is overwritten whenever the cluster configuration changes. Edit the configuration through the CLI only. ### Troubleshoot common failures
Lookups return nobody/nogroup for LDAP users **Cause:** The cluster is in `ad` mode, no LDAP domain is configured, or the SSSD domain label does not match the domain name clients present. **Resolution:** 1. Confirm the POSIX resolution mode and the SSSD health. ```bash weka smb cluster ``` 2. List the configured domains and compare each label with the AD domain name clients send. ```bash weka smb ldap-domain show ``` 3. Correct the mismatch. Switch the cluster to `nss` mode, add the missing domain, or remove the mislabeled domain and add it again with the correct label. A label cannot be renamed in place.
weka smb ldap-domain test reports bind: FAILED **Cause:** The bind DN or password is wrong, or the TLS handshake fails because the server certificate of a StartTLS or `ldaps://` connection cannot be verified with the supplied CA. **Resolution:** 1. Verify the bind DN. ```bash weka smb ldap-domain show ``` 2. Set the password again if it may be stale. ```bash weka smb ldap-domain rotate-password ``` Omit `--new-password` so the CLI prompts for it, which avoids shell quoting problems with complex passwords. 3. Supply the correct CA certificate when the connection uses StartTLS or `ldaps://`. ```bash weka smb ldap-domain update --ca-cert /path/to/ca.pem --validate-before-commit ```
weka smb ldap-domain test reports posix attributes (uidNumber): NOT found **Cause:** The bind succeeds, but the search base or the schema is wrong, or the user has no POSIX attributes in the directory. **Resolution:** 1. Confirm that the user carries `uidNumber` and `gidNumber` in the directory. Users without POSIX attributes are denied access, and NSS mode has no automatic UID assignment. 2. Widen or correct the search base so it covers the container that holds the POSIX entries. ```bash weka smb ldap-domain update --ldap-search-base "DC=example,DC=com" --validate-before-commit ``` 3. Switch the schema if the directory publishes group membership in the other format. ```bash weka smb ldap-domain update --ldap-schema rfc2307 --validate-before-commit ```
SSSD Health: failed immediately after an SMB-W container restart **Cause:** SSSD is still waiting for the SMB-W config filesystem to mount, which takes up to about 3 minutes, or it is restarting to pick up a configuration change. **Resolution:** 1. Wait about 3 minutes and check the health again. ```bash weka smb cluster ``` 2. Review `sssd_starter.log` and `sssd.log` under `/data/log/` in the SMB-W container if the health stays `failed`.
## System specifications | Item | Value | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Maximum LDAP domains per SMB-W cluster | 64 | | LDAP domains accepted at cluster creation | 1 | | LDAP URIs per domain | 1. There is no multi-server failover within a single domain. Define separate domains for separate directories. | | Maximum CA certificate size | 16 KiB | | Maximum LDAP URI length | 256 characters | | Maximum search base length | 128 characters | | Maximum bind DN length | 256 characters | | Maximum domain label length | 64 characters | | SMB-W startup wait for the SSSD NSS socket (NSS mode only) | 60 seconds, non-fatal | | Bind authentication | Anonymous and simple authenticated binds only. Kerberos/GSSAPI bind is not supported. | | Raw `sssd.conf` upload | Not supported. The generated configuration cannot be replaced or extended with arbitrary SSSD options. | | Configuration interface | CLI only. The feature is not exposed in the WEKA GUI. | | Automatic UID assignment | Not supported. Users without POSIX attributes in LDAP are denied access. | | SSSD cache tuning | Not exposed. SSSD's built-in caching applies with WEKA-selected timeouts. | | NFS LDAP configuration | Independent. NFS-W has its own `weka nfs ldap` commands with a different configuration model. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.weka.io/additional-protocols/smb-support/smb-external-ldap-posix-resolution.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.