ansible-role-unix-users/README.md

volker-raschek.unix-users

The ansible role volker-raschek.unix-users create and manage users on Linux based distributions. For example for Arch Linux, Fedora and Ubuntu. Furthermore, the role can also be used to create groups, ~/.forward, ~/.netrc and to manage the ~/.ssh directory.

Requirements

The role requires ansible-core 2.11 or newer. A home directory can optionally be created as btrfs subvolume, which relies on the btrfs_subvolume module of the collection community.general.

ansible-galaxy collection install -r requirements.yml

The role manages users, groups and their home directories, so it has to be executed with become: true.

Tests

The role is tested with Molecule. The scenario starts one docker container per supported distribution family, applies the role, asserts that a second run reports no change and finally verifies the created users and groups, the permissions and the content of the managed files and that a user declared as absent is gone again. A btrfs home is not covered, because a container has no btrfs filesystem to create a subvolume on.

The ssh key pair the scenario feeds into the role is generated during molecule create and removed again during molecule destroy, so no private key is kept in the repository.

Molecule ships only its default driver, therefore docker is required besides molecule itself. The collections are declared in molecule/default/collections.yml and installed by molecule.

pip install molecule docker

The complete sequence creates the containers, tests them and removes them afterwards.

molecule test

While working on the role the containers are better kept alive.

# create the containers and apply the role
molecule converge

# run the assertions of molecule/default/verify.yml against the running containers
molecule verify

# open a shell in one of the containers
molecule login --host unix-users-debian

# remove the containers
molecule destroy

Examples

User and group

The following example create the user toor and group toor. Booth with a specific id.

unix_groups:
  toor:
    gid: "1001"
    state: present

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    shell: /bin/bash
    password: toor
    group: toor

Btrfs home dir

Optionally, the home directory of a user can also be created as dedicated btrfs subvolume. This make it possible to create snapshots of the home directory, for example via btrbk.

Warning

Removing a user with state: absent also deletes the btrfs subvolume of the home directory. Snapshots taken from that subvolume are not removed and keep the data available.

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    btrfs: true
    shell: /bin/bash
    password: toor
    group: toor

.netrc

The ansible role supports the creation and management of the .netrc file in a user's home directory. The .netrc file for the user toor is created below. This contains entries for GitHub.

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    netrc:
    - machine: github.com
      login: octocat
      password: pat_12345
    - machine: api.github.com
      login: octocat
      password: pat_12345
    shell: /bin/bash
    password: toor
    group: toor

.ssh

The SSH client directory ~/.ssh can also be managed via the Ansible role. This supports the creation and management of ~/.ssh/config, ~/.ssh/authorized_keys as well as the maintenance of private and public SSH keys.

The following example create two entries in ~/.ssh/authorized_keys. One normal SSH access for claire. If bob establish a SSH connection the command /usr/local/bin/upload-file.sh will be executed and exited. Furthermore, environment variables can be espcilitly defined, to consume it during execution of the command.

Important

To allow consuming environment variables must be set PermitUserEnvironment yes in /etc/ssh/sshd_config.

The private key toor@toor-pc.ed25519.key must be stored in ssh/private_keys. The public key will be automatically extracted from the private key.

The public keys claire@claire-pc.pub as well as bob@bob-pc.pub must be stored in ssh/authorized_keys.

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    ssh:
      config:
      - Host: "*"
        StrictHostKeyChecking: "no"
        UserKnownHostFile: /dev/null
      authorized_keys:
      - filename: claire@claire-pc.pub
      - command: /usr/local/bin/upload-file.sh
        envs:
        - key: SSH_KEY_NAME
          value: bob@bob-pc
        filename: bob@bob-pc.pub
      private_keys:
      - toor@toor-pc.ed25519.key
    shell: /bin/bash
    password: toor
    group: toor

.forward

If on the system is postfix installed, postfix will respect the ~/.forward file. This allows to forward local emails to external email addresses. The following example create the ~/.forward file for toor to forward emails to toor@company.example.local.

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    email: toor@company.example.local
    shell: /bin/bash
    password: toor
    group: toor

shell_rc files

The role also supports the creation of bashrc drop-in files. These are created in ~/.bashrc.d and included by ~/.bashrc via source.

Program-related configurations can be made via a drop-in file. For example, the configuration of the bash history via the environment variables HISTCONTROL or HISTFILE. In addition to environment variables, aliases and complete functions can also be defined.

unix_users:
  toor:
    state: present
    name: Toor
    uid: "1000"
    home: /home/toor
    email: toor@company.example.local
    shell: /bin/bash
    shell_rc_files:
    - file: "/home/toor/.bashrc.d/10-docker.bashrc" # absolute or relative path to home dir
      aliases:
      - key: "dcd"
        value: "docker-compose down"
      envs:
      - export: true
        key: "PATH"
        value: "/home/toor/workspace/docker-compose/bin:${PATH}" # Add local compiled docker-compose into $PATH
      functions:
      - name: "foo"
        value: |
          if ! which docker 1> /dev/null; then
            echo "ERROR: docker not found" 1>&2
            exit 1
          fi
    password: toor
    group: toor

Further ansible roles

This ansible role is used in combination with other ansible roles of volker-raschek. You can search for the other ansible roles via the following command.

$ ansible-galaxy role search --author "volker-raschek"

Found roles matching your search:

 Name                      Description
 ----                      -----------
 volker-raschek.bind9      Role to install and configure bind9 on different distributions
 volker-raschek.dhcpd      Role to install and configure dhcpd on different distributions
 volker-raschek.renovate   Role to configure renovate as container image
 ...