roles/users/README.md

Ansible Galaxy

This role includes complete Galaxy metadata and can be published to Ansible Galaxy or used in collections.

User Configuration

Users are configured via YAML files in files/users/<username>/main.yml. User files to be deployed to home directories are placed in files/users/<username>/data/.

Directory Structure

files/users/<username>/
├── main.yml          # User configuration (metadata)
├── sudoers           # Optional sudo policy for /etc/sudoers.d/<username>
└── data/             # Files to copy to user's home directory
    ├── .ssh/
    ├── .zshrc
    └── other-files/

Path Resolution Logic

The role searches for user configurations in this priority order:

1. Inventory-specific per-host: {{ inventory_path }}/files/{{ inventory_hostname }}/users/{{ username }}/
2. Inventory-specific global: {{ inventory_path }}/files/users/{{ username }}/
3. Project per-host: files/{{ inventory_hostname }}/users/{{ username }}/
4. Project global: files/users/{{ username }}/

Once a user directory is found, the role:

• Loads metadata from {{ user_dir }}/main.yml
• Copies files from {{ user_dir }}/data/ to the user's home directory
• Deploys {{ user_dir }}/sudoers, if present, to /etc/sudoers.d/<username>

Sudoers File

Place a file named sudoers beside the user's main.yml, for example files/users/agent/sudoers. The role copies it without templating, owned by root:root with mode 0440, and validates it with /usr/sbin/visudo -cf %s before installation. The target must have sudo installed and its main sudoers configuration must include /etc/sudoers.d.

The file uses the selected user directory described above. If that directory has no sudoers file, the role leaves existing sudo policy untouched. Both remove and remove-all delete /etc/sudoers.d/<username> when removing the account.

User Metadata (main.yml)

Each user can have the following attributes:

---
user:
  uid: 1001                    # User ID (optional)
  shell: /usr/bin/zsh          # User shell (defaults to users_default_shell)
  comment: [email protected]     # GECOS comment
  default_groups:              # Default groups if none specified via --extra-vars
    - wheel
    - sudo
  linger: true                 # Enable systemd lingering (defaults to users_linger_enable)
  ohmyzsh: true                # Install Oh My Zsh (only for zsh users, defaults to users_ohmyzsh_install)
  ohmyzsh_theme: agnoster      # Oh My Zsh theme (defaults to users_ohmyzsh_theme)
  ohmyzsh_update: false        # Enable/disable Oh My Zsh auto-update (defaults to users_ohmyzsh_update)

Default supplementary groups that do not exist on the target system are skipped. Groups supplied explicitly via --extra-vars remain strict and must exist.

Multi-Location File Loading

The role supports organic overrides by checking multiple locations for user files, in order of priority:

1. {{ inventory_path }}/files/{{ inventory_hostname }}/users/ - Host-specific overrides
2. {{ inventory_path }}/files/users/ - Inventory-specific users
3. files/{{ inventory_hostname }}/users/ - Host-specific relative path
4. files/users/ - Global default users

This allows different inventory files to have their own user configurations while falling back to global defaults.

Usage

# Add users
ansible-playbook site.yml --tags=users --extra-vars "users=srw,eon user_action=add"

# Remove users
ansible-playbook site.yml --tags=users --extra-vars "users=srw user_action=remove"

# Remove users and their files
ansible-playbook site.yml --tags=users --extra-vars "users=srw user_action=remove-all"

Role Defaults

Default values can be overridden by modifying roles/users/defaults/main.yml:

users_default_shell: /bin/bash    # Default shell for users
users_home_mode: '0700'           # Home directory permissions
users_default_action: add         # Default action when not specified
users_home_prefix: /home          # Home directory prefix
users_linger_enable: false        # Default systemd lingering setting
users_ohmyzsh_install: true       # Default Oh My Zsh installation for zsh users
users_ohmyzsh_update: false       # Default Oh My Zsh auto-update setting
users_ohmyzsh_install_url: "https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh"  # Oh My Zsh installation script URL
# Upstream default is robbyrussell
users_ohmyzsh_theme: gentoo       # Default Oh My Zsh theme