Commit 339859d5 authored by Maciej Delmanowski's avatar Maciej Delmanowski

[docs] Clean up 'debops.users' documentation

parent 42558b72
---
# .. vim: foldmarker=[[[,]]]:foldmethod=marker
# debops.users default variables [[[
# ==================================
# debops.users default variables
# ==============================
# .. contents:: Sections
# :local:
......@@ -10,24 +10,6 @@
# .. include:: ../../../includes/global.rst
# APT packages [[[
# ----------------
# .. envvar:: users__base_packages [[[
#
# List of base packages to install.
users__base_packages:
- '{{ [ "acl" ]
if (users__acl_enabled|bool)
else [] }}'
# ]]]
# .. envvar:: users__packages [[[
#
# List of custom packages to install.
users__packages: []
# ]]]
# ]]]
# Global defaults [[[
# -------------------
......@@ -71,6 +53,24 @@ users__default_system: '{{ (True
users__default_shell: ''
# ]]]
# ]]]
# APT packages [[[
# ----------------
# .. envvar:: users__base_packages [[[
#
# List of base packages to install.
users__base_packages:
- '{{ [ "acl" ]
if (users__acl_enabled|bool)
else [] }}'
# ]]]
# .. envvar:: users__packages [[[
#
# List of custom packages to install.
users__packages: []
# ]]]
# ]]]
# Lists of managed UNIX groups and accounts [[[
# ---------------------------------------------
......@@ -213,4 +213,3 @@ users__dotfiles_repo: '{{ ansible_local.yadm.dotfiles
else "" }}'
# ]]]
# ]]]
# ]]]
Copyright
=========
.. literalinclude:: ../../../../ansible/roles/debops.users/COPYRIGHT
......@@ -8,8 +8,9 @@ Getting started
Example inventory
-----------------
``debops.users`` is included by default in the :file:`common.yml` DebOps playbook;
you don't need to do anything to have it executed.
The ``debops.users`` Ansible role is included by default in the
:file:`common.yml` DebOps playbook; you don't need to do anything to have it
executed.
If you don’t want to let ``debops.users`` manage user accounts, you can disable
it with the following setting in your inventory:
......
......@@ -3,15 +3,22 @@
debops.users
============
The ``debops.users`` Ansible role can be used to manage local user accounts and
groups. The role allows for certain operations inside of the home directories,
like configuration of the mail forwarding, SSH public keys or automatic
deployment of user configuration files (dotfiles).
.. toctree::
:maxdepth: 2
introduction
getting-started
defaults
defaults-detailed
copyright
upgrade
Copyright
---------
.. literalinclude:: ../../../../ansible/roles/debops.users/COPYRIGHT
..
Local Variables:
......
Introduction
============
The ``debops.users`` Ansible role can be used to manage local user accounts and
groups. The role allows for certain operations inside of the home directories,
like configuration of the mail forwarding, SSH public keys or automatic
deployment of user configuration files (dotfiles).
Installation
~~~~~~~~~~~~
This role requires at least Ansible ``v2.0.0``. To install it, run:
.. code-block:: console
ansible-galaxy install debops.users
..
Local Variables:
mode: rst
ispell-local-dictionary: "american"
End:
#!/bin/bash
## Upgrade inventory variables for migration from debops.users v0.1.x to v0.2.x.
## The script is idempotent.
git ls-files -z "$(git rev-parse --show-toplevel)" | xargs --null -I '{}' find '{}' -type f -print0 \
| xargs --null sed --in-place --regexp-extended '
s/\<users__?default_dotfiles\>/users__dotfiles_enabled/g;
s/\<users__?default_dotfiles_key\>/users__dotfiles_name/g;
s/\<users__?default_shell\>/users__default_shell/g;
s/\<users__?dotfiles\>/users__dotfiles_default_map/g;
s/\<users__?list\>/users__accounts/g;
s/\<users__?group_list\>/users__group_accounts/g;
s/\<users__?host_list\>/users__host_accounts/g;
s/\<users__?root\>/users__root_accounts/g;
s/\<users__?admins\>/users__admin_accounts/g;
s/\<users__?default\>/users__default_accounts/g;
s/\<users__?groups\>/users__groups/g;
s/\<([^.]users)_([^_])/\1__\2/g;
'
.. _users__ref_upgrade_nodes:
Upgrade notes
=============
The upgrade notes only describe necessary changes that you might need to make
to your setup in order to use a new role release. Refer to the
changelog for more details about what has changed.
From v0.1.x to v0.2.x
---------------------
All role variables have been renamed from ``users_*`` to ``users__*`` to move
them to a separate namespace.
List of renamed user list variables:
+----------------------+-----------------------------------+
| Old variable name | New variable name |
+======================+===================================+
| ``users_list`` | :envvar:`users__accounts` |
+----------------------+-----------------------------------+
| ``users_group_list`` | :envvar:`users__group_accounts` |
+----------------------+-----------------------------------+
| ``users_host_list`` | :envvar:`users__host_accounts` |
+----------------------+-----------------------------------+
| ``users_admins`` | :envvar:`users__admin_accounts` |
+----------------------+-----------------------------------+
| ``users_default`` | :envvar:`users__default_accounts` |
+----------------------+-----------------------------------+
| ``users_groups`` | :envvar:`users__groups` |
+----------------------+-----------------------------------+
| | :envvar:`users__group_groups` |
+----------------------+-----------------------------------+
| | :envvar:`users__host_groups` |
+----------------------+-----------------------------------+
This script can come in handy to update the inventory variable names, assuming
that your inventory is stored in a :command:`git` repository:
.. literalinclude:: scripts/upgrade-from-v0.1.x-to-v0.2.x.sh
:language: shell
The script is bundled with this role under
:file:`docs/scripts/upgrade-from-v0.1.x-to-v0.2.x.sh` and can be invoked from
there.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment