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

Introduction

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

Prerequisites:

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/aehostd.pw).

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.

Installation

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 \
  --with-nslcd-socket=/var/run/aehostd/aehostd.sock
make
make install

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

passwd: files aedir
group:  files aedir

OS-specific source packages:

ansible

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.
-f CFG_FILENAME, --config CFG_FILENAME
Pathname of configuration file (default: /etc/aehostd.conf)
-p PIDFILE, --pid PIDFILE
Pathname of file for storing process-ID (PID) (default: /var/run/aehostd/aehostd.pid)
-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 ).

Process

The following options specify general process parameters:

uid
Not used anymore since 1.2.0.
gid
Not used anymore since 1.2.0.

Logging & monitoring

The following options specify general process parameters:

loglevel
Level of log details (Integer), see Python's standard logging module -- Logging Levels
Default: 20 (INFO)
logsocket
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)
monitor
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:

socketpath
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
sockettimeout
Timeout (seconds) of service socket
Default: 10.0 seconds
socketperms
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.

uri_list
List of LDAP servers (LDAP URIs) to try first in exactly this order no matter what is configured in uri_pool.
Default: empty list
uri_pool
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
binddn
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.
Example:
binddn = host=server1.example.com,ou=ae-dir
bindpwfile
The password file to use for simple bind as identity given in binddn.
Default: /var/lib/aehostd/aehostd.pw
timelimit
Timeout (seconds) used for all LDAP connections/operations
Default: 6.0
cache_ttl
LDAPObject cache TTL used for short-time LDAP search cache.
Default: 6.0
tls_cacertfile
Pathname of file containing trusted root CA certificate(s).
Default: None, which means use system-wide trust store.
tls_cert
Pathname of file containing client certificate used for SASL/EXTERNAL bind
tls_key
Pathname of file containing client private key used for SASL/EXTERNAL bind
conn_ttl
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:

nss_ignore_users
Names of passwd entries to ignore
Default: All user names found in local file /etc/passwd
nss_ignore_uids
IDs of passwd entries to ignore
Default: All UIDs found in local file /etc/passwd
nss_ignore_groups
Names of group entries to ignore
Default: All user names found in local file /etc/group
nss_ignore_gids
IDs of group entries to ignore
Default: All UIDs found in local file /etc/group
refresh_sleep
Refresh time (seconds) for NSS passwd and group maps
Default: 60.0 (1 min)
nss_min_uid
Minimum numeric UID to handle in passwd requests
Default: 0
nss_min_gid
Minimum numeric GID to handle in group requests
Default: 0
nss_max_uid
Maximum numeric UID to handle in passwd requests
Default: 65500
nss_max_gid
Maximum numeric GID to handle in group requests
Default: 65500
netaddr_refresh
Refresh time (seconds) for hosts maps. Negative values disables hosts refresh.
Default: -1.0 (disabled)
netaddr_level
Levels (int) to go up for deriving the hosts map search base.
Default: 2
memberattr
Which member attribute in aeGroup entries to use
Default: memberUid
vgroup_name_prefix
Name prefix used for virtual groups
Default: ae-vgrp-
vgroup_rgid_offset
Number offset (int) to be used for virtual groups
Default: 9000
sshkeys_dir
Directory name where to store exported SSH authorized keys
Default: None (disabled)
aehost_vaccount
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
gecos_tmpl
Template string for deriving GECOS field from e.g. user name
Default: AE-DIR user {username}
homedir_tmpl
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)

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

sudo

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

sudoers_file
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
sudoers_includedir
Directory name where privileged helper stores sudoers export file
Default: /etc/sudoers.d
visudo_exec
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

PAM

Parameters used by the PAM handler:

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