apache-formula/docs/modules/ROOT/pages/README.adoc

= 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:

[arabic]
. apache will use 1-500 for ordering
. apache will reserve 1 -100 as unused
. apache will reserve 101-150 for pre pkg install
. apache will reserve 151-200 for pkg install
. apache will reserve 201-250 for pkg configure
. apache will reserve 251-300 for downloads, git stuff, load data
. apache will reserve 301-400 for unknown purposes
. apache will reserve 401-450 for service restart-reloads
. apache WILL reserve 451-460 for service.running
. 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
----

=== `+apache.config.vhosts.clean+`

Remove non-declared virtual hosts, and deactivates the service.

=== `+apache.config.vhosts.cleanup+`

Remove non-declared virtual hosts, but keeps the service running.

== 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.