apache
------
https://travis-ci.com/saltstack-formulas/apache-formula[image:https://travis-ci.com/saltstack-formulas/apache-formula.svg?branch=master[Travis CI Build Status]]
https://github.com/semantic-release/semantic-release[image:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg[Semantic Release]]
Formulas to set up and configure the Apache HTTP server on GNU/Linux,
FreeBSD, and Windows OS.
General notes
~~~~~~~~~~~~~
See the full
https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html[SaltStack
Formulas installation and usage instructions].
If you are interested in writing or contributing to formulas, please pay
attention to the
https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas[Writing
Formula Section].
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 http://semver.org/[Semantic
Versioning].
See
https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning[Formula
Versioning Section] for more details.
Contributing to this repo
~~~~~~~~~~~~~~~~~~~~~~~~~
*Commit message formatting is significant!!*
Please see
xref:main::CONTRIBUTING.adoc[How
to contribute] for more details.
Available states
~~~~~~~~~~~~~~~~
`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 http://modsecurity.org/[Apache mod_security2
WAF] 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:
[source,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:
[source,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:
[source,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
[source,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
^^^^^
[source,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:
[source,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.
