File diff bf96a77e88ab → 4b964a31bd96
docs/rolereference.rst
Show inline comments
 
@@ -259,52 +259,52 @@ The role implements the following:
 
* Installs ``ferm`` (for iptables management), configuring a basic firewall
 
  which allows ICMP echo requests (PING), incoming connection on TCP port 22
 
  (SSH), and also introduces rate-limitting for incoming ICMP echo request
 
  pacakges and (new) TCP connections. The rate-limitting is based on the source
 
  IP address, using the ``iptables hashlimit`` module.
 

	
 

	
 
Role dependencies
 
~~~~~~~~~~~~~~~~~
 

	
 
Depends on the following roles:
 

	
 
* **backup_client**
 

	
 

	
 
Backups
 
~~~~~~~
 

	
 
If the backup for this role has been enabled, the following paths are backed-up:
 

	
 
**/var/log**
 
  Log files from the system.
 

	
 
**/home**
 
  Home directory for regular users.
 
  Home directory for regular users (this can be changed via role parameters).
 

	
 
**/root**
 
  Root user's home directory.
 
  Root user's home directory (this can be changed via role parameters).
 

	
 
**/etc/shadow**
 
  Operating system user passwords.
 

	
 
**/var/mail**
 
  Local user's mails.
 

	
 
**/var/spool/cron**
 
  Local user's cronjobs.
 

	
 

	
 
Parameters
 
~~~~~~~~~~
 

	
 
**apt_proxy** (string, optional, ``None``)
 
  URI of a caching proxy that should be used when retrieving the packages via
 
  apt.
 

	
 
**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
 
@@ -325,48 +325,52 @@ Parameters
 
  **password** (string, optional, ``!`` - no password)
 
    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, optional, ``whatever OS picks``)
 
    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.
 

	
 
**ca_certificates** (list, optional, ``{}``)
 
  Dictionary containing the CA certificates to deploy. Keys are base filenames
 
  (**without extension**) to be used when placing a certificate file in
 
  directory ``/usr/local/share/ca-certificates/``, while values are
 
  corresponding content to be placed in the file.
 

	
 
**extra_backup_patterns** (list, optional, ``[ "/home", "/root" ]]``)
 
  List of additional globbing patterns defining additional files or directories
 
  that should be backed-up.
 

	
 
**incoming_connection_limit** (string, optional, ``3/second``)
 
  Rate at which the incoming ICMP echo-request packages and new TCP connections
 
  will be accepted at. The value should be specified in the same format as value
 
  for the ``iptables hashlimit`` option ``--hashlimit-upto``.
 

	
 
**incoming_connection_limit_burst** (string, optional, ``9``)
 
  Initial burst of packages that should be accepted when the client with
 
  distinct source IP address connects to the server for the first time (usually
 
  higher than ``incoming_connection_limit``), even if it would go above the
 
  specified connection limit.
 

	
 
**prompt_colour** (string, optional, ``none``)
 
  Colour for showing the Bash prompt. Supported values are:
 

	
 
  ``black``, ``red``, ``green``, ``brown``, ``blue``, ``purple``, ``cyan``,
 
  ``light_gray``, ``dark_gray``, ``light_red``, ``light_green``, ``yellow``,
 
  ``light_blue``, ``light_purple``, ``light_cyan``, ``white``, ``none``.
 

	
 
  You should probably *not* use the ``black`` colour. Setting affects Bash
 
  shells *only*. Setting the value to ``none`` uses default terminal colour.
 

	
 
**prompt_id** (string, optional, ``NONE``)
 
  Optional identifier appended to regular Bash prompt, useful for visually
 
  identifying distinct environments. For example, if set to ``test``, resulting