Skip to content

Deploying LDAP Servers

The base container images authenticate users via LDAP against two servers named ldap1 and ldap2 (configured in SSSD at ldaps://ldap1:636 and ldaps://ldap2:636). This guide covers deploying those servers, keeping them updated, and integrating them with Proxmox.

Prerequisites

  • A running cluster with at least one site configured
  • The management software deployed and accessible
  • Two available container slots for ldap1 and ldap2

LDAP Gateway Image

The LDAP servers use ghcr.io/mieweb/ldap-gateway, a Node.js LDAP server that reads user and group data directly from the management database via SQL.

Environment Variables

Variable Value
DIRECTORY_BACKEND sql
LDAP_COMMON_NAME Hostname of the container (e.g. ldap1 or ldap2)
LDAP_BASE_DN Derived from the site's internal domain (e.g., example.com → dc=example,dc=com)
AUTH_BACKENDS sql or sql,notification (if push notifications are enabled)
NOTIFICATION_URL Push notification endpoint (only present if push notifications are enabled)
SQL_URI postgres://username:password@hostname:port/database/ssl=true — must point to the same database used by the manager
SQL_QUERY_ALL_USERS See rendered queries below
SQL_QUERY_ONE_USER See rendered queries below
SQL_QUERY_ALL_GROUPS See rendered queries below
SQL_QUERY_GROUPS_BY_MEMBER See rendered queries below
REQUIRE_AUTH_FOR_SEARCH false — allows unauthenticated LDAP searches
NODE_TLS_REJECT_UNAUTHORIZED 0

SQL Queries

The queries are generated by the manager using Sequelize's quoteIdentifier(). Rendered for PostgreSQL:

SQL_QUERY_ALL_USERS 

SELECT "uid" AS username, "uidNumber" AS uid_number, "gidNumber" AS gid_number,
       "givenName" AS first_name, "cn" AS full_name, "sn" AS last_name,
       "mail", "homeDirectory" AS home_directory, "userPassword" AS password
FROM "Users"

SQL_QUERY_ONE_USER 

SELECT "uid" AS username, "uidNumber" AS uid_number, "gidNumber" AS gid_number,
       "givenName" AS first_name, "cn" AS full_name, "sn" AS last_name,
       "mail", "homeDirectory" AS home_directory, "userPassword" AS password
FROM "Users"
WHERE "uid" = ?

SQL_QUERY_ALL_GROUPS 

SELECT g."cn" AS name, g."gidNumber" AS gid_number
FROM "Groups" g

SQL_QUERY_GROUPS_BY_MEMBER 

SELECT g."cn" AS name, g."gidNumber" AS gid_number
FROM "Groups" g
INNER JOIN "UserGroups" ug ON g."gidNumber" = ug."gidNumber"
INNER JOIN "Users" u ON ug."uidNumber" = u."uidNumber"
WHERE u."uid" = ?

Deploying ldap1 and ldap2

Create two LXC containers named exactly ldap1 and ldap2 using the ghcr.io/mieweb/ldap-gateway image. Both use identical configuration — the pair provides redundancy.

For each server:

  1. Create a container with hostname ldap1 (or ldap2) using the ghcr.io/mieweb/ldap-gateway image
  2. Set the environment variables from above
  3. Start the container

Both servers will register in DNSMasq automatically, making them resolvable by name from all containers in the site.

Rolling Updates

To update the LDAP servers without downtime, replace them one at a time:

  1. Delete ldap1 — all containers fail over to ldap2 via SSSD
  2. Recreate ldap1 with the latest ghcr.io/mieweb/ldap-gateway image and the same environment variables
  3. Verify ldap1 is running and responding on port 636
  4. Delete ldap2 — traffic shifts to the updated ldap1
  5. Recreate ldap2 with the latest image and same environment variables
  6. Verify ldap2 is running

SSSD on the base images is configured with both servers (ldaps://ldap1:636, ldaps://ldap2:636) and will automatically fail over when one is unavailable.

Proxmox LDAP Realm

Configure Proxmox to authenticate users against the same LDAP servers. This allows container ACLs to reference cluster users as username@ldap.

DNS Configuration

First, configure Proxmox to use the same DNS server as the containers (the DNSMasq instance managed by the management software). This ensures Proxmox can resolve ldap1 and ldap2 by name.

In the Proxmox web UI: Node → System → DNS → set the DNS server to the DNSMasq IP address.

Add the LDAP Realm

In the Proxmox web UI: Datacenter → Permissions → Realms → Add → LDAP Server.

Setting Value
Realm ldap
Base Domain Name Derived from internal domain (e.g., example.com → dc=example,dc=com)
User Attribute Name uid
Default ✅ (checked)
Server ldap1
Fallback Server ldap2
Port (leave default)
Mode LDAPS
Verify Certificate ❌ (unchecked)
Require TFA none

Under Sync Options:

Setting Value
Email Attribute mail
Scope Users and Groups

All other settings remain at defaults.

Sync Users

After adding the realm, sync it to import users and groups:

Datacenter → Permissions → Realms → select ldap → Sync.

The management software also triggers a sync automatically when creating containers (via syncLdapRealm('ldap')) to ensure new users are available for ACL assignment.