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
  3. Configuration
    1. General process parameters
    2. Socket parameters
    3. LDAP connection parameters
    4. NSS map parameters
    5. sudo parameters
    6. PAM parameters

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 2.x.

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.

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 build files:

ansible

Example ansible role: ansible/roles/ae-dir-hostd/ (sets ansible variable nsswitch_module to "aedir")

Configuration

The following options can be set in the configuration file /etc/aehostd.conf:

General process parameters

The following options specify general process parameters:

# the user name or ID aehostd should be run as
uid = aehostd
# the group name or ID aehostd should be run as
gid = aehostd

# Level of log details (Integer), see Python's standard logging module
# Default: 20 (INFO)
#loglevel = 20

# 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)
#logsocket =

# Interval (seconds) at which internal monitoring data is written to log.
# Setting this to zero or negative value disables monitor logging completely.
# The default is -1.0 (disabled).
#monitor = 60.0

Socket parameters

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

# Path name of service socket which must match what PAM and NSS modules expect
# Default: /var/run/aehostd/socket
#socketpath = /var/run/aehostd/socket

# timeout (seconds) of service socket
# Default: 10.0 seconds
#sockettimeout = 10.0

# permissions (octal digits) used for service socket
# Default: 0666 (world-readable and -writeable)
#socketperms = 0666

LDAP connection parameters

Various LDAP connection parameters can be set and tuned:

# At least one of uri_list or uri_pool must be specified.
# Both uri_list or uri_pool may 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.
uri_list = ldapi://

# 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.
uri_pool = ldaps://ae-dir-c1.example.com ldaps://ae-dir-c2.example.com ldaps://ae-dir-c3.example.com

# The bind-DN to use when binding as service to AE-DIR with simple bind.
# Preferrably the short bind-DN should be used.
binddn = host=srv1.example.com,ou=ae-dir

# The password file to use for simple bind as identity given in binddn.
# Default is: /var/lib/aehostd/aehostd.pw
#bindpwfile = /var/lib/aehostd/aehostd.pw

# Timeout (seconds) used for all LDAP connections/operations
# Default: 6.0
#timelimit = 6.0

# LDAPObject cache TTL used for short-time LDAP search cache.
# Default: 6.0
#cache_ttl = 6.0

# File containing trusted root CA certificate(s).
# Default: None, which means use system-wide trust store.
#tls_cacertfile = /etc/ssl/certs/cacerts.pem

# File containing client certificate used for SASL/EXTERNAL bind.
#tls_cert = /etc/aehostd.crt

# File containing private key used for SASL/EXTERNAL bind.
#tls_key = /etc/aehostd.key

# Time span (seconds) after which aehostd forcibly reconnects.
# Default: 1800 (30 min.)
#conn_ttl = 1800.0

NSS map parameters

Parameters related to NSS maps:

# Names of passwd entries to ignore
# Default: All user names found in local file /etc/passwd
#nss_ignore_users =
# IDs of passwd entries to ignore
# Default: All UIDs found in local file /etc/passwd
#nss_ignore_uids =
# Names of group entries to ignore
# Default: All user names found in local file /etc/group
#nss_ignore_groups =
# IDs of group entries to ignore
# Default: All UIDs found in local file /etc/group
#nss_ignore_gids =
# Refresh time (seconds) for NSS passwd and group maps
# Default: 60.0 (1 min)
#refresh_sleep = 60.0

# Minimum numeric UID to handle in passwd requests
# Default: 0
#nss_min_uid = 0
# Minimum numeric GID to handle in group requests
# Default: 0
#nss_min_gid = 0
# Maximum numeric UID to handle in passwd requests
# Default: 65500
#nss_max_uid = 65500
# Maximum numeric GID to handle in group requests
# Default: 65500
#nss_max_gid = 65500

# Refresh time (seconds) for hosts maps. Negative values disables hosts refresh.
# Default: -1.0 (disabled)
#netaddr_refresh = -1.0
# Levels (int) to go up for deriving the hosts map search base.
# Default: 2
#netaddr_level = 2

# Which member attribute in aeGroup entries to use
# Default: memberUid
#memberattr = memberUid

# Name prefix used for virtual groups
# Default:
#vgroup_name_prefix = ae-vgrp-

# Number offset (int) to be used for virtual groups
# Default: 9000
#vgroup_rgid_offset = 9000

# Directory name where to store exported SSH authorized keys
# Default: None (disabled)
#sshkeys_dir = /var/lib/aehostd/sshkeys

# 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
#aehost_vaccount = 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}
#gecos_tmpl = AE-DIR user {username}

# Template string for deriving home directory path name from e.g. user name
# Default: None (disabled)
#homedir_tmpl =

# Login shell to be used if attribute loginShell is not available
#loginshell_default = /usr/sbin/nologin

# Login shell always used not matter what's in attribute loginShell
# Default: None (disabled)
#loginshell_override =

sudo parameters

Parameters related to NSS maps:

# Path name of sudoers export file to be picked up by privileged helper
# Default: /var/lib/aehostd/ae-dir-sudoers-export
#sudoers_file = /var/lib/aehostd/ae-dir-sudoers-export

# Directory name where privileged helper stores sudoers export file
# Default: /etc/sudoers.d
#sudoers_includedir = /etc/sudoers.d
# pathname of visudo executable
# Default: /usr/sbin/visudo
#visudo_exec = /usr/sbin/visudo
# pathname of visudo cvtsudoers
# Default: /usr/bin/cvtsudoers
#cvtsudoers_exec = /usr/bin/cvtsudoers

PAM parameters

Parameters used by the PAM handler:

# LDAP filter template used for checking authorization of a user
# Default: None (disabled)
#pam_authz_search =

# Error message sent to user about password change disabled/denied
# Default: None (no details)
#pam_passmod_deny_msg =