DynamoDB User Manager (DDUM)

Manage Linux users from DynamoDB.

This module runs as a daemon that periodically scans a pair of DynamoDB tables for user and group information and updates the local password/shadow password files for users and groups. This is done so there are no network dependencies in the PAM chain -- the goal is to allow administrators to continue to log in even when the network is adversely affected.

When installed via setup.py using the defaults, a daemon script installed as /usr/local/bin/dynamodb-user-manager.

DDUM is conservative in what it does. It modifies and adds users to the system; it never deletes them. To disable a user account, set the AccountExpireDate to a date in the past. DDUM will update the shadow entry for this user, disabling their account. This also preserves audit history in a sane way; you will no longer have dangling user ids and the risk of reusing a user id is reduced.

Command line arguments

Usage: dynamodb-user-manager [options]

Options:

• -h | --help Show this usage information.

• -c filename | --config filename Read configuration from filename instead of /etc/dynamodb-user-manager.cfg.

• -f | --foreground Don't fork into the background (don't daemonize).

• -p filename | --pidfile filename Write the process pid to filename instead of /var/run/dynamodb-user-manager.pid.

Configuration

Configuring the daemon requires a JSON configuration file; by default, this is /etc/dynamodb-user-manager.cfg. You can override this with the --config flag to dynamodb-user-manager.

The configuration file is a JSON document in the form:

{
    "aws_access_key": "AKIDEXAMPLE",
    "aws_profile": "default",
    "aws_region": "us-east-1",
    "aws_secret_key": "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",
    "aws_session_token": "",
    "full_update_jitter": 600,
    "full_update_period": 3600,
    "group_table_name": "Groups",
    "user_table_name": "Users",
    "logging": {
        "version": 1,
        ...
    }
}

The valid configuration keys are:

• aws_access_key / aws_secret_key / aws_session_token / aws_profile (str) Static AWS credentials to use.

  If aws_access_key and aws_secret_key (and, optionally, aws_session_token) are specified, these are fed directly into Boto and will be used.

  Otherwise, if aws_profile is specified, this is fed into Boto, which reads the the credentials from ~/.aws/credentials (usually the root user).

  On EC2 instances, these parameters should not be used. Boto will fetch the credentials from the EC2 instance metadata.

• aws_region (str) The AWS region to use. If unspecified, this uses the first value found from: The environment variable AWS_REGION The environment variable AWS_DEFAULT_REGION If running on EC2, the EC2 instance metadata. "us-east-1"

• full_update_period / full_update_jitter (int) The time, in seconds, between polls of the DynamoDB tables. The wait period is always used, plus a random value from 0 to full_update_jitter is selected; this helps distribute the load on the DynamoDB tables when run across multiple instances.

  The default is 3600 seconds (1 hour) for full_update_period, and 600 seconds (10 minutes) for full_update_jitter.

• group_table_name (str) The name of the DynamoDB table to use to fetch for groups. This defaults to "Groups".

• user_table_name (str) The name of the DynamoDB table to use to fetch for users. This defaults to "Users".

• logging (dict) If present, this is passed to the Python configuration function logging.config.dictConfig.

Field restrictions

Linux does not have a well-defined set of rules for what can appear in various fields -- a lot depends on the internal implementation of various libraries.

DDUM imposes the following restrictions:

• User and group names: 1-256 ASCII characters. Valid characters are letters, digits, period, underscore, and hyphen; the hyphen cannot be the first character of the name. (See POSIX 3.437, portable filename character set, LOGIN_NAME_MAX.)
• GECOS (realname, office, phone, etc): 256 characters, since 512 characters is a commonly used buffer size for the entire passwd line. Colons, newlines, vertical tabs, formfeeds, and the NUL character are disallowed. This is interpreted as Unicode and written in UTF-8 locally, though most libraries handle this field as bytes with no well-defined encoding.

Users table

The users table has the following schema. (DynamoDB type codes: S = string; N = number; SS = string set)

Groups table

The groups table has the following schema. (DynamoDB type codes: S = string; N = number; SS = string set)