DEBOPS.APACHE(5)

NAME
debops.apache - Manage and configure the Apache HTTP Server

SYNOPSIS

debops run service/apache [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.apache role allows you to setup and manage the Apache HTTP Server <https://httpd.apache.org/> with version 2.4 and above.

GETTING STARTED

  Example inventory

To manage Apache on a given host or set of hosts, they need to be added to the [debops_service_apache] Ansible group in the inventory:

[debops_service_apache]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.apache role:

---
- name: Manage and configure the Apache HTTP Server
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_apache' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare apache environment
      ansible.builtin.import_role:
        name: 'apache'
        tasks_from: 'main_env'
      tags: [ 'role::apache', 'role::apache:env' ]
  roles:
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ apache__ferm__dependent_rules }}'
    - role: apache
      tags: [ 'role::apache', 'skip::apache' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::apache:env
    Environment role tag, should be used in the playbook to execute a special environment role contained in the main role. The environment role prepares the environment for other dependency roles to work correctly.

role::apache
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::apache:pkgs
    Tasks related to system package management like installing or removing packages.

role::apache:modules
    Tasks related to Apache modules.

role::apache:vhosts
    Tasks related to Apache virtual hosts.

ANSIBLE INTEGRATION AND ROLE DESIGN

  Design goals

•   Try not to modify/replace configuration files which are maintained by Debian. In particular the /etc/apache2/apache2.conf is not altered.

•   Most variables which directly correspond to a Apache directive are not masked or otherwise changed (for example using True, False for directives which expect on, off is not supported). Together with the direct reference to upstream documentation provided in the role documentation this is expected to provide more transparency to the user and allow the role to be future proof when changes occur upstream.

•   For directives where off or False might be a valid option, the special variable omit (use in Jinja: {{ omit }}) is intended to be used when the directive should be omitted (not written to the Apache configuration at all).

•   Apache is not restarted by the role because that would require to close established connections. Some configuration options require a restart to take effect. The documentation for those options should give a hint about it. You should test your settings with a test system and do a restart in production manually when required. Optionally, it should be possible to allow restarts using inventory variables.

  Alternative roles

Ansible Galaxy <https://galaxy.ansible.com/> has an impressive number of Ansible roles for Apache at your disposal. A few of them have been checked out before/while writing this role:

•   geerlingguy.apache <https://github.com/geerlingguy/ansible-role-apache>

•   jpnewman.apache <https://github.com/jpnewman/ansible-role-apache>

•   And peeked at a few more.

    However, none of the already existing roles where found to be a suitable start for Apache support in DebOps so this role has been designed and written from scratch. Unfortunately, that workflow is not uncommon considering the quality requirements and standards of DebOps.

DEFAULT VARIABLE DETAILS

Some of debops.apache default variables have more extensive configuration than simple strings or lists. Here you can find documentation and examples for them.

NOTE: This section of the documentation might not be fully up-to-date. If there is something missing you are encouraged to cross-check with debops.nginx docs and enhance the documentation.

  apache__modules

The Apache modules configuration is represented as YAML dictionaries. Each key of those dictionaries is a module name. The module names correspond to the file names under /etc/apache2/mods-available Refer to the Apache module index <https://httpd.apache.org/docs/2.4/mod/> for a full list of available modules upstream.

The role provides multiple variables which can be used on different inventory levels. The apache__combined_modules variable combines these YAML dictionaries together and determines the order in which module configuration "mask" the previous ones.

The dictionary value can be a simple boolean corresponding to the enabled option (as described below) or a dictionary by itself with the following supported options:

enabled
    Required, boolean. Defaults to True. Set to {{ omit }} not change the state of a module. Whether the module should be enabled or disabled in Apache.

force
    Optional, boolean. Defaults to False. Force disabling of default modules and override Debian warnings when set to True.

config
    Optional, string. Module configuration directives which will be saved in a role managed configuration file under conf-available and contained in a <IfModule> section which causes Apache to only enables this module configuration when the module is enabled.

ignore_configcheck
    Optional, boolean. Defaults to False. Ignore configuration checks about inconsistent module configuration. Especially for mpm_* modules.

  Examples

Ensure the ldap module is enabled for the given host:

apache__host_modules:
  ldap: True

  apache__snippets

Apache configuration snippets are represented as YAML dictionaries. Each key of those dictionaries corresponds to the filename prefix under conf-available. The .conf file extension is added by the role and must be omitted by the user. Note that Debian maintainers recommend in README.Debian of the apache2 package that filenames should be prefixed with local- to avoid name clashes with files installed by packages. This is not enforced by the role and should be done by the user of the role.

The role provides multiple variables which can be used on different inventory levels. The apache__combined_snippets variable combines these YAML dictionaries together and determine the order in which configuration "mask" the previous ones.

The dictionary value can be a simple boolean corresponding to the enabled option (as described below) or a dictionary by itself with the following supported options:

enabled
    Optional, boolean. Defaults to True unless item.state is set to absent. Whether the configuration snippet should be enabled or disabled in Apache server context.

state
    Optional, String. Defaults to present. Whether the module should be present or absent in the conf-available directory.

type
    Optional, string. Refer to the following subsections for the supported type.

  Type: raw

Available when item.type is set to raw or divert. This can be used to create a snippet based on the item.raw content.

raw Optional, string. Raw content to write into the snippet file. By default, the role will look under templates/etc/apache2/conf-available for a template matching the item key. If raw is specified, a special template will be used which simply writes the given content into the snippet. Refer to the Apache configuration sections documentation <https://httpd.apache.org/docs/2.4/sections.html> for details.

  Type: divert

Available when item.type is set to divert. This special type does not create a snippet file, instead it uses dpkg-divert to allow you to do a package management aware rename of a snippet.

Note that for this type no changes are done in the conf-enabled directory to avoid idempotency issues with a potential snippet with the same filename as the snippet which is diverted away.

divert_suffix
    Optional, string. Defaults to .dpkg-divert. Allows to change the suffix for the diverted file in the sites-available directory.

divert_filename
    Optional, string. The default value is determined based on the values of item.name and item.filename. Allows to change the divert filename.

divert
    Optional, string. Defaults to the file path determined for snippet in the conf-available directory. Allows to specify a full file path where to divert the file to. Note that the item.divert_suffix is still in affect when using this option.

  Type: dont-create

This special type assumes the snippet file is already present and does not try to create it. This can be used to enable or disable snippet files managed by system packages for example.

  Examples

Ensure the given Apache directives are configured in /etc/apache2/conf-available/example.conf and enabled in Apache server context:

apache__host_snippets:
  example:
    type: 'raw'
    raw: |
      # Your raw Apache directives.

Ensure the /etc/apache2/conf-available/owncloud.conf snippet shipped by ownCloud system packages is disabled so that debops.owncloud has full control over it and can enable ownCloud in specific vhost contexts.

owncloud__apache__dependent_snippets:
  owncloud:
    enabled: False
    type: 'dont-create'

  apache__vhosts

The Apache virtual hosts can be defined as lists of YAML dictionaries. This allows the configuration of Apache virtual hosts on different inventory levels as needed.

Note that one vhost item of this role usually results in two Apache virtual hosts, one for HTTP and one for HTTPS.

  Common role options

name
    Required, string or list of strings. Domain names to for this name-based virtual host.

    The first element is used to create the name of the sites configuration file and must be a normal domain name, other elements can include wildcards.

    The list can also be empty (but needs to be defined) in which case the configuration it is included in will be named default.

filename
    Optional, string. Alternative name of the sites configuration file under the /etc/apache2/sites-available/ directory. The suffix .conf will be added automatically. This can be used to distinguish different server configurations for the same item.name. For example separate configuration for HTTP and HTTPS.

enabled
    Optional, boolean. Defaults to True. Specifies if the configuration should be enabled by creating a symlink in /etc/apache2/sites-enabled/.

state
    Optional, string. Defaults to present. Whether the vhost should be present or absent.

by_role
    Optional, string. Name of a Ansible role in the format ROLE_OWNER.ROLE_NAME which is responsible for the server configuration.

comment
    Optional, string. Comment for the intended purpose of the virtual host.

type
    Optional, string. Specify name of the template to use to generate the virtual host configuration. Templates can extend other templates.

  Common webserver options

server_admin
    Optional, string. Defaults to apache__server_admin. Default server admin contact information. Either a Email address or a URL (preferable on another webserver if this one fails).

index
    Optional, string or boolean (False). Space separated list of index filenames. The directive will be omitted if set to False.

root
    Optional, string. Absolute path to server root to use for this server configuration. Defaults to /srv/www/<``name[0]>/public/. See also ``owner parameter. The directive will be omitted if set to False.

document_root
    Optional, string. Alias for item.root. item.root is also used by debops.nginx and might be preferred for that reason.

alias
    Optional, string. Alias to item.root configured using the Alias directive <https://httpd.apache.org/docs/2.4/mod/mod_alias.html#alias>.

alias_path
    Optional, string. Alternative path which should be aliased. If not specified, DocumentRoot will be used as the alias target.

root_directives
    Optional, string. Additional raw Apache directives to apply to item.root.

options
    Optional, string. Defaults to apache__vhost_options.

allow_override
    Optional, string. Defaults to apache__vhost_allow_override.

listen_http
    Optional, list of strings/integers. Defaults to a socket based on apache__http_listen matching all network addresses. List of ports, IP addresses or sockets this server configuration should listen on for HTTP connections.

listen_https
    Optional, list of strings/integers. Defaults to a socket based on apache__https_listen matching all network addresses. List of ports, IP addresses or sockets this server configuration should listen on for HTTPS connections.

include
    Optional, string or list of strings. The given files are included the appropriate virtual host context using the Include directive <https://httpd.apache.org/docs/2.4/mod/core.html#include>.

include_optional
    Optional, string or list of strings. The given files are included the appropriate virtual host context using the IncludeOptional directive <https://httpd.apache.org/docs/2.4/mod/core.html#includeoptional>.

raw_content
    Optional, string. Allows to specify raw Apache directives which are inlined in the appropriate virtual host context.

custom_log
    Optional, string. Specify absolute path to the access log file which should be used by this vhost. You also need to specify the access log format to use.

error_log
    Optional, string. Specify absolute path to the error log file which should be used by this vhost.

custom_log_condition
    Optional, string. Allows to specify condition which controls whether or not to log a particular request in access log. You can use it for example to skip logging health checks from your load balancer.

  Redirects

Refer to the Apache Redirect directive documentation <https://httpd.apache.org/docs/2.4/mod/mod_alias.html#redirect> for details.

redirect_http
    Optional, string. Redirect incoming requests on the HTTP port to the given URL.

redirect_http_code
    Optional, string/integer. Defaults to 307 (Temporary Redirect). Specify HTTP code used in the redirect response when redirecting to item.redirect_http.

redirect_https
    Optional, string. Redirect incoming requests on the HTTPS port to the given URL.

redirect_https_code
    Optional, string/integer. Defaults to 307 (Temporary Redirect). Specify HTTP code used in the redirect response when redirecting to item.redirect_https.

redirect_to_https_with_code
    Optional, string/integer. Defaults to 301 (Moved Permanently). Optional, string/integer. Specify HTTP code used in the redirect response from HTTP to HTTPS, by default 301 Moved Permanently.

redirect_to_https
    Optional, boolean. Defaults to apache__redirect_to_https If True, redirect connection from HTTP to the HTTPS version of the site. Set to False to allow to serve the website via HTTP and HTTPS and don't redirect HTTP to HTTPS.

  HTTPS and TLS

https_enabled
    Optional, boolean. Defaults to apache__https_enabled. Enable or disable HTTPS for this server configuration.

tls_crt
    Optional, string. Absolute path to a custom X.509 certificate to use. If not supplied, a certificate will managed by debops.pki will be used.

tls_key
    Optional, string. Absolute path to custom private key to use. If not supplied pki_key will be used instead.

tls_dhparam_file
    Optional, string. Absolute path to custom DHE parameters to use. If not supplied, apache__tls_dhparam_file will be used instead.

tls_cipher_suite_set_name
    Optional, strings. Defaults to apache__tls_cipher_suite_set_name. Set name of TLS cipher suites to use as defined in apache__tls_cipher_suite_sets.

pki_realm
    Optional, string. Overwrites the default PKI realm used by Apache for this vhost configuration. See the debops.pki role for more information, as well as the /etc/pki/realms directory on remote hosts for a list of available realms.

pki_crt
    Optional, string. Path to custom X.509 certificate to use, relative to the currently enabled PKI realm.

pki_key
    Optional, string. Path to custom private key to use, relative to the currently enabled PKI realm.

ocsp_stapling_enabled
    Optional, boolean. Defaults to apache__ocsp_stapling_enabled Enable or disable OCSP Stapling.

hsts_enabled
    Optional, boolean. Defaults to True. If this is set to True and HTTPS is enabled for this item, the HTTP Strict Transport Security <https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security> header is set in the server's responses. If this is set to False, the header will not be set in the server's responses.

hsts_preload
    Optional, boolean. Defaults to apache__hsts_preload. Add a "preload" parameter to the HSTS header which can be used with the https://hstspreload.appspot.com/ site to configure HSTS preloading for a given website.

  HTTP security headers

csp Optional, string. Defaults to: default-src https: ; (force all assets to be loaded over HTTPS). Sets the first part of the Content-Security-Policy header. The string MUST end with a semicolon but MUST NOT begin with one. Make sure that you only use single quotes and no double quotes in the string. If no item.csp_report is given, it also determines the first part of the Content-Security-Policy-Report-Only header. Which headers are actually enabled is defined by item.csp_enabled and item.csp_report_enabled. Refer to the Content Security Policy Reference <https://content-security-policy.com/>.

csp_report
    Optional, string. This allows to set a different/potentially experimental Content-Security-Policy-Report-Only header than defined by item.csp.

csp_append
    Optional, string. Defaults to: apache__http_csp_append. CSP directives to append to all policies (item.csp and item.csp_report). This can be used to overwrite the default apache__http_csp_append as needed. The string MUST end with a semicolon but MUST NOT begin with one.

csp_enabled
    Optional, boolean. Defaults to False. If set to True and HTTPS is enabled for this item, the Content-Security-Policy header is set in server responses.

csp_report_enabled
    Optional, boolean. Defaults to False. If this is set to True and HTTPS is enabled for this item, the Content-Security-Policy-Report-Only header is set in the server responses.

http_xss_protection
    Optional, string. Value of the X-XSS-Protection HTTP header field. Set to {{ omit }} to not send the header field. Defaults to apache__http_xss_protection.

1   Browsers should enable there build in cross-site scripting protection.

mode=block
    In case a cross-site scripting attack is detected, block the page from rendering.

    Note that the this option might create a vulnerability in old versions of Internet Explorer <https://github.com/helmetjs/helmet#xss-filter-xssfilter>.

    For more details and discussion see What is the http-header “X-XSS-Protection”? <https://stackoverflow.com/questions/9090577/what-is-the-http-header-x-xss-protection>.

http_referrer_policy
    Optional, string. Value of the Referrer-Policy HTTP header field. Set to {{ omit }} to not send the header field. Defaults to apache__http_referrer_policy. Refer to Referrer Policy <https://www.w3.org/TR/referrer-policy/> for more details. Note that this header is a draft as of 2016-10-11 but it is already supported by the majority of web browsers.

  Apache status

status_enabled
    Optional, boolean. Should the Apache server status be enabled? Defaults to apache__status_enabled.

status_location
    Optional, string. The Location or URL path by which the Apache server status should be accessible. Defaults to apache__status_location.

status_allow_localhost
    Optional, boolean. Allow access to the Apache server status using the Require local directive. Defaults to apache__status_allow_localhost.

status_directives
    Optional, string. Additional directives included into the Location sections for the Apache server status configuration. Can be used to customize access for example. Defaults to apache__status_directives.

  Type: raw

Available when item.type is set to raw. Don’t do all the fancy stuff that the normal templates can do for you and just use the provided Apache configuration and dump it into the file.

raw Optional, string. Raw content to write into the virtual host configuration file.

  Type: divert

Available when item.type is set to divert. This special type does not create a virtual host file, instead it uses dpkg-divert to allow you to do a package management aware rename of a file.

Note that for this type no changes are done in they sites-enabled directory to avoid idempotency issues with a potential configuration with the same filename as the configuration which is diverted away.

divert_suffix
    Optional, string. Defaults to .dpkg-divert. Allows to change the suffix for the diverted file in the sites-available directory.

divert_filename
    Optional, string. The default value is determined based on the values of item.name and item.filename. Allows to change the divert filename.

divert
    Optional, string. Defaults to the file path determined for the virtual host configuration. Allows to specify a full file path where to divert the file to. Note that the item.divert_suffix is still in affect when using this option.

  Examples

Create virtual hosts for www.example.org and example.org:

apache__host_vhosts:
  - name: [ 'www.example.org' ]
    root: '/srv/www/sites/www.example.org/public'
  - name: [ 'example.org' ]
    redirect_http: 'https://www.example.org'
    redirect_https: 'https://www.example.org'
    redirect_http_code: '301'
    redirect_https_code: '301'

The files under /srv/www/sites/www.example.org/public are served for requests against https://www.example.org. Requests against example.org are permanently redirected to the canonical www.example.org site. HTTPS is the default and legacy HTTP connection attempts are permanently redirected to HTTPS. HSTS <https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security> tells clients to only connect to the site using HTTPS from now on. Certificates managed by debops.pki are used according to the name of the virtual host which should match a PKI realm of debops.pki.

AUTHOR
Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others