improve role, especially wrt. passwords

README.md

@@ -0,0 +1,73 @@
+<!--
+SPDX-FileCopyrightText: 2023 Max Mehl <https://mehl.mx>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Ansible role for creating user accounts
+
+This Ansible role allows for easy and painless adding of users on
+Linux/Unix/POSIX systems. No rocket science involved.
+
+## Why not `ansible.builtin.user`?
+
+* If you want to provide a password, it has to be hashed. This role takes care
+  of it.
+* If you just want to add a user to an additional group (e.g. `docker` or
+  `audio`), you must not forget to set `append: true`. This role makes it by
+  default.
+* Sets some useful defaults, e.g. generating an ed25519 SSH key
+* Setting an empty instead of a disabled password requires an extra parameter
+  `allow_no_password: true`
+
+## Requirements
+
+* `python3` with the `crypt` module (part of standard library)
+
+## Usage
+
+Check out [`defaults/main.yml`](defaults/main.yml) for all possible
+configuration options and their defaults.
+
+## Examples
+
+### Create a user
+
+```yaml
+- name: Create new user for service
+  include_role:
+    name: users
+  vars:
+    username: srvuser
+```
+
+A user without a password will have it set to `*`, so disabled. Useful for users
+who you will log into via sudo or SSH.
+
+### Create multiple users
+
+In your playbook:
+
+```yaml
+- name: Set up machines
+  remote_user: root
+  tasks:
+    - name: Setup users
+      include_role:
+        name: users
+      loop: "{{ users }}"
+      vars:
+        username: "{{ item.user }}"
+        password: "{{ item.pass | default('*') }}"
+        # feel free to add other variables here as well
+```
+
+and in your `host_vars` file:
+
+```yaml
+users:
+  - user: srvuser
+    pass: safepassword
+  # password will be disabled
+  - user: controller
+```