From 6362a56ad362c25bdcaa4fe16d6cae7662723737 Mon Sep 17 00:00:00 2001
From: L3D <l3d@c3woc.de>
Date: Wed, 14 Feb 2024 03:36:16 +0100
Subject: [PATCH] start with documentation

---
 roles/user/README.md | 68 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/roles/user/README.md b/roles/user/README.md
index 5aa3186..241f032 100644
--- a/roles/user/README.md
+++ b/roles/user/README.md
@@ -1,6 +1,72 @@
  Ansible Role Users
 ====================
 
-Ansible role to create and update users and groups
+Ansible role l3d.users.user to create Users with their group and their SSH Public Keys to their account.
+Optionally you can also create an ansible user and add specified ssh keys to his home and all keys of admin users.
+
+There are two variables to define users. The ``l3d_users__default_users`` is ment to put to your group_vars to define a default for your system. The ``l3d_users__local_users`` could be put in your host_vars to define host-specific user and admin roles.
+
+ Variables:
+-------------
+
++ The dictionary-variable for your group_vars to set your general users and admins is ``l3d_users__default_users``.
++ The dictionary-variable for your host_vars to set your host-specific users and admins is: ``l3d_users__local_users``.
+The Option of these directory-variables are the following.
+
+| option | values | description |
+| ------ | ------ | --- |
+| name   | string | The user you want to create |
+| state  | ``present`` | Create or delete user |
+| shell | ``/bin/bash`` | The Shell of the User |
+| create_home | ``true`` | create a user home *(needed to store ssh keys)* |
+| admin | ``false`` | enable it to give the user superpowers |
+| pubkeys | string or lookup | see examples |
+| exklusive_pubkeys | ``true`` | delete all undefined ssh keys |
+| password | password hash | See [official FAQ](https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module) |
+| remove | ``false`` | completly remove user if state is absent |
+
+
+| name | default value | description |
+| ---  | --- | --- |
+l3d_users_user__create_ansible: true
+l3d_users_user__ansible_user_state: 'present'
+l3d_users_user__set_ansible_ssh_keys: false
+l3d_users_user__ansible_ssh_keys: "{{ lookup('url', 'https://github.com/do1jlr.keys', split_lines=False) }}"
+
+
+# create users
+l3d_users__default_users: {}
+#  - name: 'alice'
+#    state: 'present'
+#    shell: '/bin/bash'
+#    create_home: true
+#    admin: true
+#    pubkeys: |
+#       ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPvvXN33GwkTF4ZOwPgF21Un4R2z9hWUuQt1qIfzQyhC
+#       ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAG65EdcM+JLv0gnzT9LcqVU47Pkw0SqiIg7XipXENi8
+#       ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJz7zEvUVgJJJsIgfG3izsqYcM22IaKz4jGVUbNRL2PX
+#    exklusive_pubkeys: true
+#    password: "$Password_hash"
+#  - name: 'bob'
+#    state: 'present'
+#    shell: '/bin/zsh'
+#    admin: false
+#    pubkeys: "{{ lookup('url', 'https://github.com/do1jlr.keys', split_lines=False) }}"
+#    exklusive_pubkeys: false
+
+l3d_users__local_users: {}
+#  - name: 'charlie'
+#    state: 'present'
+#    admin: false
+#    pubkeys: "{{ lookup('url', 'https://github.com/do1jlr.keys', split_lines=False) }}"
+
+# Create ansible mamagement user
+l3d_users_user__create_ansible: true
+l3d_users_user__ansible_user_state: 'present'
+l3d_users_user__set_ansible_ssh_keys: false
+l3d_users_user__ansible_ssh_keys: "{{ lookup('url', 'https://github.com/do1jlr.keys', split_lines=False) }}"
+# run simple versionscheck
+submodules_versioncheck: false
+
 
 work in progress...