.. _readme: 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 `_. If you are interested in writing or contributing to formulas, please pay attention to the `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 `Semantic Versioning `_. See `Formula Versioning Section `_ for more details. Contributing to this repo ------------------------- **Commit message formatting is significant!!** Please see `How to contribute `_ 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 `_ 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 :1 $ 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.