4449474a3d
This patch clarifies some of the installation and usage docs for newcomers to the role. Closes-Bug: 1702571 Change-Id: I1a935b37d9b9248ca53e8f252dd2407c15347935
101 lines
3.1 KiB
ReStructuredText
101 lines
3.1 KiB
ReStructuredText
Getting started
|
|
===============
|
|
|
|
The ansible-hardening role can be used along with the `OpenStack-Ansible`_
|
|
project or as a standalone role that can be used along with other Ansible
|
|
playbooks. This documentation assumes that the reader has completed the steps
|
|
within the
|
|
`Ansible installation guide <http://docs.ansible.com/ansible/intro_installation.html>`_.
|
|
|
|
.. _OpenStack-Ansible: https://git.openstack.org/cgit/openstack/openstack-ansible/
|
|
|
|
.. contents::
|
|
:local:
|
|
:backlinks: none
|
|
|
|
Installing the ansible-hardening role
|
|
-------------------------------------
|
|
|
|
The recommended installation methods for the ansible-hardening role are
|
|
``ansible-galaxy`` (recommended) or ``git``.
|
|
|
|
Using ``ansible-galaxy``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The easiest installation method is to use the ``ansible-galaxy`` command that
|
|
is provided with your Ansible installation:
|
|
|
|
.. code-block:: console
|
|
|
|
ansible-galaxy install git+https://github.com/openstack/ansible-hardening
|
|
|
|
The ``ansible-galaxy`` command will install the role into
|
|
``/etc/ansible/roles/ansible-hardening`` and this makes it easy to use with
|
|
Ansible playbooks.
|
|
|
|
Using ``git``
|
|
~~~~~~~~~~~~~
|
|
|
|
Start by cloning the role into a directory of your choice:
|
|
|
|
.. code-block:: console
|
|
|
|
mkdir -p ~/.ansible/roles/
|
|
git clone https://github.com/openstack/ansible-hardening ~/.ansible/roles/ansible-hardening
|
|
|
|
Ansible looks for roles in ``~/.ansible/roles`` by default.
|
|
|
|
If the role is cloned into a different directory, that directory must be
|
|
provided with the ``roles_path`` option in ``ansible.cfg``. The following is
|
|
an example of a ``ansible.cfg`` file that uses a custom path for roles:
|
|
|
|
.. code-block:: ini
|
|
|
|
[DEFAULTS]
|
|
roles_path = /etc/ansible/roles:/home/myuser/custom/roles
|
|
|
|
With this configuration, Ansible looks for roles in ``/etc/ansible/roles`` and
|
|
``~/custom/roles``.
|
|
|
|
Usage
|
|
-----
|
|
|
|
The ansible-hardening role works well with existing playbooks. The following
|
|
is an example of a basic playbook that uses the ansible-hardening role:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
|
|
- name: Harden all systems
|
|
hosts: all
|
|
become: yes
|
|
vars:
|
|
security_enable_firewalld: no
|
|
security_rhel7_initialize_aide: no
|
|
security_ntp_servers:
|
|
- 1.example.com
|
|
- 2.example.com
|
|
roles:
|
|
- ansible-hardening
|
|
|
|
The variables provided in the ``vars`` section can enable, disable, or alter
|
|
configuration for various tasks in the ansible-hardening role. For more details
|
|
on the available variables, refer to the :ref:`hardening-domains_label`
|
|
section.
|
|
|
|
.. note::
|
|
|
|
The role must be run as the root user or as a user with ``sudo`` access.
|
|
The example above uses the ``become`` option, which causes Ansible to use
|
|
sudo before running tasks. If the role is running as root, this option can
|
|
be changed to ``user: root``.
|
|
|
|
.. warning::
|
|
|
|
It is strongly recommended to run the role in check mode (often called a
|
|
`dry run`) first before making any modifications. This gives the deployer
|
|
the opportunity to review all of the proposed changes before applying the
|
|
role to the system. Use the ``--check`` parameter with ``ansible-playbook``
|
|
to use check mode.
|