408 lines
11 KiB
ReStructuredText
408 lines
11 KiB
ReStructuredText
apache
|
|
======
|
|
|
|
|img_travis| |img_sr|
|
|
|
|
.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/apache-formula.svg?branch=master
|
|
:alt: Travis CI Build Status
|
|
:scale: 100%
|
|
:target: https://travis-ci.com/saltstack-formulas/apache-formula
|
|
.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
|
:alt: Semantic Release
|
|
:scale: 100%
|
|
:target: https://github.com/semantic-release/semantic-release
|
|
|
|
Formulas to set up and configure the Apache HTTP server on GNU/Linux, FreeBSD, and Windows OS.
|
|
|
|
.. contents:: **Table of Contents**
|
|
|
|
General notes
|
|
-------------
|
|
|
|
See the full `SaltStack Formulas installation and usage instructions
|
|
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
|
|
|
|
If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
|
|
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
|
|
|
|
If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
|
|
which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
|
|
|
|
See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
|
|
|
|
Contributing to this repo
|
|
-------------------------
|
|
|
|
**Commit message formatting is significant!!**
|
|
|
|
Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
|
|
|
|
Available states
|
|
----------------
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
``apache``
|
|
^^^^^^^^^^
|
|
|
|
Installs the Apache package and starts the service.
|
|
|
|
``apache.config``
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Metastate to apply all apache configuration
|
|
|
|
|
|
``apache.config.file``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures apache based on os_family
|
|
|
|
``apache.config.flags``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures apache flags on SuSE
|
|
|
|
``apache.config.certificates``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Deploy SSL certificates from pillars
|
|
|
|
``apache.config.modules``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Metastate to Enable and disable Apache modules.
|
|
|
|
``apache.config.modules.mod_mpm``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures the apache mpm modules on Debian ``mpm_prefork``, ``mpm_worker`` or ``mpm_event`` (Debian Only)
|
|
|
|
``apache.config.modules.mod_rewrite``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enabled the Apache module mod_rewrite (Debian and FreeBSD only)
|
|
|
|
``apache.config.modules.mod_proxy``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module mod_proxy. (Debian and FreeBSD only)
|
|
|
|
``apache.config.modules.mod_proxy_http``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module mod_proxy_http and requires the Apache module mod_proxy to be enabled. (Debian Only)
|
|
|
|
``apache.config.modules.mod_proxy_fcgi``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module mod_proxy_fcgi and requires the Apache module mod_proxy to be enabled. (Debian Only)
|
|
|
|
``apache.config.modules.mod_wsgi``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs the mod_wsgi package and enables the Apache module.
|
|
|
|
``apache.config.modules.mod_actions``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module mod_actions. (Debian Only)
|
|
|
|
``apache.config.modules.mod_headers``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module mod_headers. (Debian Only)
|
|
|
|
``apache.config.modules.mod_pagespeed``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and Enables the mod_pagespeed module. (Debian and RedHat Only)
|
|
|
|
``apache.config.modules.mod_perl2``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_perl2 module (Debian and FreeBSD only)
|
|
|
|
``apache.config.modules.mod_geoip``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_geoIP (RedHat only)
|
|
|
|
``apache.config.modules.mod_php5``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_php5 module
|
|
|
|
``apache.config.modules.mod_cgi``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables mod_cgi. (FreeBSD only)
|
|
|
|
``apache.config.modules.mod_fcgid``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_fcgid module (Debian only)
|
|
|
|
``apache.config.modules.mod_fastcgi``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_fastcgi module
|
|
|
|
``apache.config.modules.mod_dav_svn``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_dav_svn module (Debian only)
|
|
|
|
``apache.config.modules.mod_security``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs an enables the `Apache mod_security2 WAF <http://modsecurity.org/>`_
|
|
using data from Pillar. (Debian and RedHat Only)
|
|
|
|
Allows you to install the basic Core Rules (CRS) and some basic configuration for mod_security2
|
|
|
|
``apache.config.modules.mod_security.rules``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This state can create symlinks based on basic Core Rules package. (Debian only)
|
|
Or it can distribute a mod_security rule file and place it /etc/modsecurity/
|
|
|
|
``apache.config.modules.mod_socache_shmcb``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables mod_socache_shmcb. (FreeBSD only)
|
|
|
|
``apache.config.modules.mod_ssl``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables the mod_ssl module (Debian, RedHat and FreeBSD only)
|
|
|
|
``apache.config.modules.mod_suexec``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables mod_suexec. (FreeBSD only)
|
|
|
|
``apache.config.modules.mod_vhost_alias``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables the Apache module vhost_alias (Debian Only)
|
|
|
|
``apache.config.modules.mod_remoteip``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Enables and configures the Apache module mod_remoteip using data from Pillar. (Debian Only)
|
|
|
|
``apache.config.modules.mod_xsendfile``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and enables mod_xsendfile module. (Debian Only)
|
|
|
|
``apache.config.own_default_vhost``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Replace default vhost with own version. By default, it's 503 code. (Debian Only)
|
|
|
|
``apache.config.no_default_vhost``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Remove the default vhost. (Debian Only)
|
|
|
|
``apache.config.vhosts.standard``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures Apache name-based virtual hosts and creates virtual host directories using data from Pillar.
|
|
|
|
Example Pillar:
|
|
|
|
.. code:: yaml
|
|
|
|
apache:
|
|
sites:
|
|
example.com: # must be unique; used as an ID declaration in Salt; also passed to the template context as {{ id }}
|
|
template_file: salt://apache/vhosts/standard.tmpl
|
|
|
|
When using the provided templates, one can use a space separated list
|
|
of interfaces to bind to. For example, to bind both IPv4 and IPv6:
|
|
|
|
.. code:: yaml
|
|
|
|
apache:
|
|
sites:
|
|
example.com:
|
|
interface: '1.2.3.4 [2001:abc:def:100::3]'
|
|
|
|
``apache.config.manage_security``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures Apache's security.conf options by reassinging them using data from Pillar.
|
|
|
|
``apache.config.modules.mod_status``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Configures Apache's server_status handler for localhost
|
|
|
|
``apache.config.debian_full``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs and configures Apache on Debian and Ubuntu systems.
|
|
|
|
``apache.config.clean``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Metastate to cleanup all apache configuration.
|
|
|
|
|
|
``apache.clean``
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Stops the Apache service and uninstalls the package.
|
|
|
|
These states are ordered using the ``order`` declaration. Different stages
|
|
are divided into the following number ranges:
|
|
|
|
1) apache will use 1-500 for ordering
|
|
2) apache will reserve 1 -100 as unused
|
|
3) apache will reserve 101-150 for pre pkg install
|
|
4) apache will reserve 151-200 for pkg install
|
|
5) apache will reserve 201-250 for pkg configure
|
|
6) apache will reserve 251-300 for downloads, git stuff, load data
|
|
7) apache will reserve 301-400 for unknown purposes
|
|
8) apache will reserve 401-450 for service restart-reloads
|
|
9) apache WILL reserve 451-460 for service.running
|
|
10) apache will reserve 461-500 for cmd requiring operational services
|
|
|
|
Example Pillar:
|
|
|
|
.. code:: yaml
|
|
|
|
apache:
|
|
register-site:
|
|
# any name as an array index, and you can duplicate this section
|
|
{{UNIQUE}}:
|
|
name: 'my name'
|
|
path: 'salt://path/to/sites-available/conf/file'
|
|
state: 'enabled'
|
|
|
|
sites:
|
|
# Force SSL: Redirect from 80 to 443
|
|
example.com:
|
|
port: 80
|
|
template_file: salt://apache/vhosts/redirect.tmpl
|
|
RedirectSource: 'permanent /'
|
|
# Trailing slash is important
|
|
RedirectTarget: 'https://example.com/'
|
|
example.com_ssl:
|
|
port: 443
|
|
ServerName: example.com
|
|
SSLCertificateFile: /path/to/ssl.crt
|
|
SSLCertificateKeyFile: /path/to/ssl.key
|
|
SSLCertificateChainFile: /path/to/ssl.ca.crt
|
|
|
|
Testing
|
|
-------
|
|
|
|
Linux testing is done with ``kitchen-salt``.
|
|
|
|
Requirements
|
|
^^^^^^^^^^^^
|
|
|
|
* Ruby
|
|
* Docker
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gem install bundler
|
|
$ bundle install
|
|
$ bin/kitchen test [platform]
|
|
|
|
Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
|
|
e.g. ``debian-9-2019-2-py3``.
|
|
|
|
``bin/kitchen converge``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Creates the docker instance and runs the ``apache`` main states, ready for testing.
|
|
|
|
``bin/kitchen verify``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs the ``inspec`` tests on the actual instance.
|
|
|
|
``bin/kitchen destroy``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Removes the docker instance.
|
|
|
|
``bin/kitchen test``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
|
|
|
|
``bin/kitchen login``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Gives you SSH access to the instance for manual testing.
|
|
|
|
Testing with Vagrant
|
|
--------------------
|
|
|
|
Windows/FreeBSD/OpenBSD testing is done with ``kitchen-salt``.
|
|
|
|
Requirements
|
|
^^^^^^^^^^^^
|
|
|
|
* Ruby
|
|
* Virtualbox
|
|
* Vagrant
|
|
|
|
Setup
|
|
^^^^^
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gem install bundler
|
|
$ bundle install --with=vagrant
|
|
$ bin/kitchen test [platform]
|
|
|
|
Where ``[platform]`` is the platform name defined in ``kitchen.vagrant.yml``,
|
|
e.g. ``windows-81-latest-py3``.
|
|
|
|
Note
|
|
^^^^
|
|
|
|
When testing using Vagrant you must set the environment variable ``KITCHEN_LOCAL_YAML`` to ``kitchen.vagrant.yml``. For example:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ KITCHEN_LOCAL_YAML=kitchen.vagrant.yml bin/kitchen test # Alternatively,
|
|
$ export KITCHEN_LOCAL_YAML=kitchen.vagrant.yml
|
|
$ bin/kitchen test
|
|
|
|
Then run the following commands as needed.
|
|
|
|
``bin/kitchen converge``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Creates the Vagrant instance and runs the ``apache`` main states, ready for testing.
|
|
|
|
``bin/kitchen verify``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs the ``inspec`` tests on the actual instance.
|
|
|
|
``bin/kitchen destroy``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Removes the Vagrant instance.
|
|
|
|
``bin/kitchen test``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
|
|
|
|
``bin/kitchen login``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Gives you RDP/SSH access to the instance for manual testing.
|