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
    2. Socket
    3. LDAP
    4. NSS maps
    5. 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 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

The following options specify general process parameters:

# the user id nslcd should be run as
uid = aehostd
# the group id nslcd should be run as
gid = aehostd
# logging level
loglevel = 20

Socket

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

# full path name of service socket
socketpath = /var/run/nslcd/socket
# timeout of service socket
sockettimeout = 10.0
# permissions used for service socket
socketperms = '0666'

LDAP

Various LDAP connection parameters can be set and tuned:

# The location at which the LDAP server(s) should be reachable.
uri = ldaps://ae-dir-c1.example.com ldaps://ae-dir-c2.example.com ldaps://ae-dir-c3.example.com
# preferred short bind-DN form (relocatable)
binddn = host=host1.example.com,ou=ae-dir
# pathname of file containing password for the above binddn
bindpwfile = /etc/aehostd.pw
# CA certificate for checking TLS server cert of LDAP server(s)
tls_cacertfile = /etc/ssl/certs/cacerts.pem
# Client certificate and its private key to use with SASL/EXTERNAL bind
tls_cert = None
tls_key = None
# time limit (secs) for all LDAP operations
timelimit = 3.0
# how long to use an existing LDAP connection (secs)
conn_ttl = 1800.0
# LDAPObject cache TTL (secs)
cache_ttl = 6.0

NSS maps

Parameters related to NSS maps:

# passwd entries to ignore (default: all users in local /etc/passwd)
nss_ignore_users =
nss_ignore_uids =
# group entries to ignore (default: all users in local /etc/passwd)
nss_ignore_groups =
nss_ignore_gids =
# POSIX-ID and name validation
nss_min_uid = 0
nss_min_gid = 0
nss_max_uid = 65500
nss_max_gid = 65500
# regex for constraining valid user and group names (default: POSIX standard)
validnames =
# virtual groups
vgroup_name_prefix = ae-vgrp-
vgroup_rgid_offset = 9000
# user account used to authenticate as own aeHost object
# formatted like entry in /etc/passwd
aehost_vaccount = aehost-init:x:9042:9042:AE-DIR virtual host init account:/tmp:/bin/true
# Template string for deriving gecos field from user's name
gecos_tmpl = AE-DIR user {username}
# Template string for deriving homeDirectory value from user's name
homedir_tmpl = /home/{username}

PAM

Parameters related to PAM:

# filter template string to be used when processing PAM authorization requests
pam_authz_search = (&(uid={username})(|(pwdChangedTime=*)(userCertificate=*)(sshPublicKey=*)))
# Text to output when rejecting change password requests
pam_passmod_deny_msg = None