diff --git a/doc/source/domains.rst b/doc/source/domains.rst index dd6db06e..0a05c331 100644 --- a/doc/source/domains.rst +++ b/doc/source/domains.rst @@ -1,3 +1,5 @@ +.. _hardening-domains-label: + Hardening Domains ================= diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 6d5f109f..204d64e8 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -1,9 +1,11 @@ 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. +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 `_. .. _OpenStack-Ansible: https://git.openstack.org/cgit/openstack/openstack-ansible/ @@ -11,58 +13,88 @@ with other Ansible playbooks. :local: :backlinks: none -Prepare your system -------------------- +Installing the ansible-hardening role +------------------------------------- -Start by installing ansible and then install the role itself using -``ansible-galaxy``: +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 - pip install ansible - ansible-galaxy install git+https://git.openstack.org/openstack/ansible-hardening + ansible-galaxy install git+https://github.com/openstack/ansible-hardening -The role will be installed into -``/etc/ansible/roles/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. -Initial configuration ---------------------- +Using ``git`` +~~~~~~~~~~~~~ -The role's default configuration is suitable for most Linux hosts. Deployers -should review the :ref:`special_notes` section to learn more about how to -provide custom configuration for the Ansible tasks in the role. +Start by cloning the role into a directory of your choice: -Using as a standalone role --------------------------- +.. code-block:: console -Adding the ansible-hardening role to existing playbooks is -straightforward. Here is an example of an existing role for deploying web -servers with the security hardening role added: + 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: Deploy web servers - hosts: webservers - become: yes - roles: - - common - - webserver - - ansible-hardening + - 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 -Using with OpenStack-Ansible ----------------------------- +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. -The ansible-hardening role is automatically enabled and applied in the -Newton release of OpenStack-Ansible. Set the following Ansible variable to -enable the role in the Mitaka release of OpenStack-Ansible: +.. note:: -.. code-block:: yaml + 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``. - apply_security_hardening: true +.. warning:: -For more information, refer to the OpenStack-Ansible documentation on -`configuring security hardening`_. - -.. _configuring security hardening: http://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/app-advanced-config-security.html#security-hardening + 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.