aehostd -- Custom NSS/PAM demon

Intended Audience: System architects, developers and system administrators

  1. Introduction
    1. Specific features
    2. NSS maps
    3. Host password initialization
  2. Installation
    1. NSS/PAM modules
    2. ansible
  3. Command-line parameters
  4. Configuration
    1. Process
    2. Logging & monitoring
    3. Service socket
    4. LDAP connection
    5. NSS map
    6. sudo
    7. PAM


While you can integrate your Linux systems with any NSS/PAM service demon it is highly recommended to use aehostd, a custom NSS/PAM service implemented in Python 3.6+.

The following diagram illustrates the integration of aehostd into Linux login:

Æ-DIR integration of Linux with aehostd

Specific features

Additionally to what you expect by such a service this custom client is has specific functionality for use with Æ-DIR:

NSS maps

The following NSS maps are provided:

Besides normal group map this demon returns some virtual groups to the calling application:

Example use-cases for virtual role groups:

Initialization of host password

aehostd has a special feature which is very helpful for automated enrollment of hosts. It does not require administrative access to the machine before correct initialization and also does not require other agents besides aehostd to be installed on the host. Mainly it is based on a PAM authentication with host password.

Initializing host password in aehostd


Host gets installed with correctly configured short bind-DN based on the canonical hostname (FQDN) (usually in file /etc/aehostd.conf) but without a host password (usually in file /var/lib/aehostd/

Process steps:

  1. A responsible setup admin adds a new aeHost entry for the canonical hostname (FQDN) and sets a new random password for this entry
    or just sets a new random password for an existing aeHost entry.
  2. Setup admin connects via SSH to the host authenticating as special service account aehost-init with the new host password set before.
  3. pam_aedir receives the PAM authentication request from sshd.
  4. aehostd receives the PAM authentication request for the system user account aehost-init.
  5. The host password is validated by sending a simple bind request on behalf of the locally configured host bind DN.
  6. In case the host password is correct it is written to the aehostd password file (located by configuration option bindpwfile) in case the password stored therein is different.


NSS/PAM modules

The NSS and PAM front-end modules of Arthur de Jong's nss-pam-ldapd (aka nslcd) are used for querying the aehostd service via its Unix domain socket.

Pre-built binary packages

For some platforms there are ready-to-use binary packages available:

Compile from source

You can compile these modules with different compile-time parameters to prevent naming and package collisions with other standard OS packages. In the following example the modules are compiled with module name aedir and for using Unix domain socket /var/run/aehostd/aehostd.sock:

./configure \
  --with-module-name=aedir \
  --disable-nslcd --disable-pynslcd --disable-kerberos \
  --libdir=/lib64 \
  --with-pam-seclib-dir=/lib/security \
  --disable-utils \
  --with-nss-maps=passwd,group,hosts \
make install

In /etc/nsswitch.conf you add the following lines:

passwd: files aedir
group:  files aedir

OS-specific source packages:


Automated installation/configuration can be done with ansible role aehostd.

Command-line arguments

Some parameters can be set via command-line arguments:

-h, --help
Shows help message and exits.
Pathname of configuration file (default: /etc/aehostd.conf)
Pathname of file for storing process-ID (PID) (default: /var/run/aehostd/
-l LOG_LEVEL, --log-level LOG_LEVEL
Level of log details (Integer), see Python's standard logging module. This argument overrides configuration option loglevel.
-n, --no-fork
Not used anymore since 1.2.0. Running in foreground is now the default because systemd is used almost everywhere.
-c, --check
Check whether demon is running. (default: False)

Configuration file

The following options can be set in the ini-style configuration file /etc/aehostd.conf (for syntax see Python docs -- Supported INI File Structure ).


The following options specify general process parameters:

Not used anymore since 1.2.0.
Not used anymore since 1.2.0.

Logging & monitoring

The following options specify general process parameters:

Level of log details (Integer), see Python's standard logging module -- Logging Levels
Default: 20 (INFO)
Path name of syslog socket: Setting this to a string enforces using syslog, empty string results in default syslog socket /dev/log being used.
Default: None (sends log messages to stderr)
Interval (seconds) at which internal monitoring data is written to log. Setting this to zero or negative value disables monitor logging completely.
Default: -1.0 (disabled)

Service socket

The following options specify handling of the Unix domain socket on which aehostd listens for NSS and PAM requests:

Path name of service socket where aehostd listens for incoming PAM and NSS requests. This must match what PAM and NSS frontend modules expect.
Default: /var/run/aehostd/socket
Timeout (seconds) of service socket
Default: 10.0 seconds
Permissions (octal digits) set for service socket
Default: 0666 (world-readable and -writeable)

LDAP connection

Various LDAP connection parameters can be set and tuned.

At least one of uri_list or uri_pool must be specified, or both can be specified.

List of LDAP servers (LDAP URIs) to try first in exactly this order no matter what is configured in uri_pool.
Default: empty list
List of LDAP servers (LDAP URIs) to try after all LDAP URIs defined with uri_list failed. This list gets rotated based on hosts's canonical FQDN for client-side load-balancing.
Default: empty list
The bind-DN to use when binding as service to AE-DIR with simple bind. Preferably the short bind-DN of the aeHost entry should be used.
binddn =,ou=ae-dir
The password file to use for simple bind as identity given in binddn.
Default: /var/lib/aehostd/
Timeout (seconds) used for all LDAP connections/operations
Default: 6.0
LDAPObject cache TTL used for short-time LDAP search cache.
Default: 6.0
Pathname of file containing trusted root CA certificate(s).
Default: None, which means use system-wide trust store.
Pathname of file containing client certificate used for SASL/EXTERNAL bind
Pathname of file containing client private key used for SASL/EXTERNAL bind
Time span (seconds) after which aehostd forcibly reconnects. This is used to make sure that aehostd chooses a replica again to make sure load keeps fairly balanced over all available replicas.
Default: 1800 (30 min.)

NSS maps

Parameters related to NSS maps:

Names of passwd entries to ignore
Default: All user names found in local file /etc/passwd
IDs of passwd entries to ignore
Default: All UIDs found in local file /etc/passwd
Names of group entries to ignore
Default: All user names found in local file /etc/group
IDs of group entries to ignore
Default: All UIDs found in local file /etc/group
Refresh time (seconds) for NSS passwd and group maps
Default: 60.0 (1 min)
Minimum numeric UID to handle in passwd requests
Default: 0
Minimum numeric GID to handle in group requests
Default: 0
Maximum numeric UID to handle in passwd requests
Default: 65500
Maximum numeric GID to handle in group requests
Default: 65500
Refresh time (seconds) for hosts maps. Negative values disables hosts refresh.
Default: -1.0 (disabled)
Levels (int) to go up for deriving the hosts map search base.
Default: 2
Which member attribute in aeGroup entries to use
Default: memberUid
Name prefix used for virtual groups
Default: ae-vgrp-
Number offset (int) to be used for virtual groups
Default: 9000
Directory name where to store exported SSH authorized keys
Default: None (disabled)
passwd string of virtual user account used to authenticate as own aeHost object
Default: aehost-init:x:9042:9042:AE-DIR virtual host init account:/tmp:/usr/sbin/nologin
Template string for deriving GECOS field from e.g. user name
Default: AE-DIR user {username}
Template string to use to derive homeDirectory from username and/or POSIX-IDs instead of querying it via LDAP. Field names which can be used in template string:
  • username
  • uid (for numeric POSIX-UID)
  • gid (for numeric POSIX-GID)

homedir_tmpl = /home/{user}
homedir_tmpl = /run/user/{uid}
Login shell used if LDAP attribute loginShell is not available.
Default: /usr/sbin/nologin
Login shell always used not matter what's in LDAP attribute loginShell.


Parameters related to synchronisation of security policy file SUDOERS(5) converted from aeSudoRule entries:

Pathname of sudoers export file to be picked up by privileged helper. Setting this to an empty string disables the sudoers export.
Default: /var/lib/aehostd/ae-dir-sudoers-export
Directory name where privileged helper stores sudoers export file
Default: /etc/sudoers.d
Pathname of visudo executable used to check sudoers syntax.
Default: /usr/sbin/visudo
Pathname of cvtsudoers executable used to convert LDAP entries (LDIF) to sudoers syntax.
Default: /usr/bin/cvtsudoers


Parameters used by the PAM handler:

Cache TTL (seconds) of PAM authc results
Default: -1 (disabled)
LDAP filter template used for checking authorization of a user
Default: None (disabled)
Error message sent to user about password change disabled/denied
Default: None (no details)