diff --git a/docs/rolereference.rst b/docs/rolereference.rst index d280c2d72b84bb802eebd718157c8c95322ab056..c39387179e3ff88f2b49ba0a06faaa69c4ee6475 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -5,8 +5,8 @@ Role Reference Preseed ------- -This role can be used for generating simple preseed files for Debian Wheezy -installations. +The ``preseed`` role can be used for generating simple preseed files for Debian +Wheezy installations. The generated preseed files allow simplified installation, with a single root partition. A number of common parameters can be provided. @@ -129,3 +129,97 @@ automatic and one with manual network configuration: mirror_directory: /debian root_password: testserver timezone: Europe/Stockholm + + +Common +------ + +The ``common`` role can be used for applying a common configuration and +hardening across all servers, no matter what services they provide. + +The role implements the following: + +* Sets-up umask for all logins to ``0027``. +* Installs sudo. +* Installs additional base packages, as configured. +* Creates additional operating system groups, as configured. +* Creates additional operating system users, as configured. +* Hardens the SSH server by disabling remote ``root`` logins and password-based + authentication. + + +Parameters +~~~~~~~~~~ + +**os_users** (list, optional) + A list of operating system users that should be set-up on a server. Each item + is a dictionary with the following options describing the user parameters: + + **name** (string, mandatory) + Name of the operating system user that should be created. User's default + group will have the same name as the user. + + **uid** (number, mandatory) + UID for the operating system user. User's default group will have a GID + identical to the user's UID. + + **additional_groups** (string, mandatory) + Comma-separated list of additional groups that a user should belong to. If + no additional groups should be appended to user's list of groups, set it to + empty string. + + **authorized_keys** (list, mandatory) + List of SSH public keys that should be deployed to user's authorized_keys + truststore. If no authorized keys should be deployed, set it to empty list + (``[]``). + + **password** (string, mandatory) + Encrypted password that should be set for the user. + +**os_groups** (list, optional) + A list of operating system groups that should be set-up on a server. Each item + is a dictionary with the following options describing the group parameters: + + **name** (string, mandatory) + Name of the operating system group that should be created. + + **gid** (number, mandatory) + GID for the operating system group. + +**common_packages** (list, optional) + List of additional operating system packages that should be installed on the + server. Each element of the list should be a simple string denoting the name + of the package. + + +Examples +~~~~~~~~ + +Here is an example configuration for setting-up some common users, groups, and +packages on all servers: + +.. code-block:: yaml + + --- + + os_users: + - name: admin + uid: 1000 + additional_groups: sudo + authorized_keys: + - "{{ lookup('file', '/home/admin/.ssh/id_rsa.pub') }}" + password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.' + - name: john + uid: 1001 + additional_groups: "" + authorized_keys: [] + password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.' + + os_groups: + - name: localusers + gid: 2500 + + common_packages: + - emacs23-nox + - screen + - debconf-utils