debops.apache default variables

Packages and installation

apache__base_packages

List of base packages to install.

apache__base_packages:
  - 'apache2'
  - '{{ "libapache2-mod-security2" if (apache__security_module_enabled|bool) else [] }}'
apache__packages

List of custom APT packages installed with Apache.

apache__packages: []
apache__dependent_packages

List of APT packages to install for other Ansible roles, for usage as a dependent role.

apache__dependent_packages: []
apache__deploy_state

What is the desired state which this role should achieve? Possible options:

present
Default. Ensure that Apache is installed and configured as requested.
absent

Ensure that Apache is uninstalled and it's configuration is removed. FIXME: You might need to run:

for file in /etc/apache2/sites-available/default-ssl.conf /etc/apache2/sites-available/000-default.conf /etc/apache2/conf-available/security.conf
do
    dpkg-divert --remove $file
done
rm /etc/apache2 -rf
apache__deploy_state: 'present'

Server configuration

apache__fqdn

The Fully Qualified Domain Name of the host running Apache.

apache__fqdn: '{{ ansible_local.core.fqdn
                  if (ansible_local|d() and ansible_local.core|d() and
                      ansible_local.core.fqdn|d())
                  else ansible_fqdn }}'
apache__domain

The domain name of the host running Apache.

apache__domain: '{{ ansible_local.core.domain
                    if (ansible_local|d() and ansible_local.core|d() and
                        ansible_local.core.domain|d())
                    else (ansible_domain if ansible_domain else ansible_hostname) }}'
apache__config_path

Base path where the Apache configuration is stored.

apache__config_path: '/etc/apache2'
apache__service_name

The name of the Apache service.

apache__service_name: 'apache2'
apache__user

The user under which Apache is running during normal operation.

apache__user: 'www-data'
apache__server_name

The ServerName to use for the default virtual host to prevent Apache from trying to determine it’s FQDN.

apache__server_name: '{{ apache__fqdn }}'
apache__server_admin

Default server admin contact information. Either a Email address or a URL (preferable on another webserver if this one fails). Refer to item.server_admin for how to overwrite this for a virtual host.

apache__server_admin: '{{ ansible_local.core.admin_public_email[0]
                          if (ansible_local|d() and ansible_local.core|d() and
                              ansible_local.core.admin_public_email|d())
                          else (apache__user + "@" + apache__fqdn) }}'
apache__server_tokens

Control what is included in the Server HTTP header field send back to clients. The default is to only reveal the product name Apache. Refer to the Apache ServerTokens directive documentation for details. Check the Apache security module section if you want more flexibility then what ServerTokens provides.

apache__server_tokens: 'ProductOnly'
apache__server_signature

Should Apache identify itself in error messages generated by Apache? This will not be done by default which also matches the upstream default as of Apache 2.4. Refer to the Apache ServerSignature directive documentation for details.

apache__server_signature: 'Off'
apache__trace_enabled

Should HTTP TRACE requests be allowed? Refer to the Apache TraceEnable directive documentation for details.

apache__trace_enabled: 'Off'
apache__http_listen

List of transport layer ports to listen on for HTTP connections. Note that changing this variable is currently not supported.

apache__http_listen: [ 80 ]
apache__https_listen

List of transport layer ports to listen on for HTTPS connections. Note that changing this variable is currently not supported.

apache__https_listen: [ 443 ]
apache__config_use_if_version

Should the Apache IfVersion directive be used to generate a generic form of the Apache configuration?

True

Default. Use the Apache IfVersion directive to generate a configuration which is intended to work with as many Apache versions as this role supports.

This has the advantage that if your Apache version does not already support all features which this role is able to configure then you can upgrade Apache independently of this role and the new features will be used in Apache as soon as a recent enough version of Apache starts up.

Note however that it is still recommended to rerun this role against your host after version upgrades because if certain features are enabled might not only depend on the Apache version. For example the version of the used cryptography library (OpenSSL) is also relevant and checked by this role at Ansible role execution time.

False

The configuration is specifically generated for the Apache version which is detected at Ansible role execution time.

This has the advantage that the generated configuration is potentially smaller and easier to read.

apache__config_use_if_version: True
apache__config_min_version

Specifies the minimum Apache version to support when apache__config_use_if_version is set to True. By default, this defaults to the current Apache major and minor version detected because major.minor version downgrades are considered uncommon and to avoid too much legacy directives. (You can still do such downgrades if the role supports the Apache version you are downgrading to but then you might need to rerun the role so that a suitable configuration can be generated.)

Supported special strings:

current_major_minor
Gets replaced by the currently detected major.minor version.
apache__config_min_version: 'current_major_minor'

Filesystem access

TODO Note: Note implemented yet. Default set of filesystem access permissions. Note that the main apache2.conf already contains a default set of restrictions which work in conjunction with the settings below.

Refer to Apache DirectoryMatch directive documentation for details.

apache__default_directory_match

Default DirectoryMatch directives maintained by this Ansible role.

apache__default_directory_match:
  '/.': 'Require all denied'
apache__directory_match

This variable is intended to be used in Ansible’s global inventory as needed.

apache__directory_match: {}
apache__group_directory_match

This variable is intended to be used in a host inventory group of Ansible (only one host group is supported).

apache__group_directory_match: {}
apache__host_directory_match

This variable is intended to be used in the inventory of hosts as needed.

apache__host_directory_match: {}
apache__combined_directory_match

The dictionaries which holds the actual Apache modules combined from the above variables.

apache__combined_directory_match: '{{ apache__default_directory_match
                                      | combine(apache__directory_match)
                                      | combine(apache__group_directory_match)
                                      | combine(apache__host_directory_match) }}'

Network configuration

apache__allow

List of IP addresses or CIDR subnets which should be allowed to connect to to Apache by the firewall. This variable is intended to be used in Ansible’s global inventory.

apache__allow: []
apache__group_allow

List of IP addresses or CIDR subnets which should be allowed to connect to to Apache by the firewall. This variable is intended to be used in a host inventory group of Ansible (only one host group is supported).

apache__group_allow: []
apache__host_allow

List of IP addresses or CIDR subnets which should be allowed to connect to to Apache by the firewall. This variable is intended to be used in the inventory of hosts.

apache__host_allow: []

Apache modules

The Apache module configuration is defined in multiple YAML dictionaries which are combined together. This allows the configuration of Apache modules on different inventory levels as needed.

See apache__modules for more details.

apache__modules

This variable is intended to be used in Ansible’s global inventory as needed.

apache__modules: {}
apache__group_modules

This variable is intended to be used in a host inventory group of Ansible (only one host group is supported).

apache__group_modules: {}
apache__host_modules

This variable is intended to be used in the inventory of hosts as needed.

apache__host_modules: {}
apache__role_modules

Apache modules managed by this Ansible role.

apache__role_modules:
  'headers': True
  'alias': True
  'ssl':
    enabled: '{{ True if (apache__https_listen) else False }}'
  'security2':
    enabled: '{{ apache__security_module_enabled|bool }}'
  'status':
    enabled: '{{ apache__status_enabled|bool }}'
    config: |
      <Location /server-status>
          # Revoke default permissions granted in `/etc/apache2/mods-available/status.conf`.
          Require all denied
      </Location>
  'socache_shmcb':
    enabled: '{{ True
                 if (apache__ocsp_stapling_enabled|bool
                     and "shmcb" in apache__ocsp_stapling_cache)
                 else omit }}'
  'authz_host':
    enabled: '{{ True
                 if (apache__status_enabled|bool
                     and apache__status_allow_localhost)
                 else omit }}'
  'rewrite':
    enabled: '{{ True
                 if (apache__register_mod_rewrite_used is defined and
                     apache__register_mod_rewrite_used.rc|d(1) == 0)
                 else omit }}'
apache__combined_modules

The dictionaries which holds the actual Apache modules combined from the above variables.

apache__combined_modules: '{{ apache__role_modules
                              | combine(apache__modules)
                              | combine(apache__group_modules)
                              | combine(apache__host_modules) }}'

Apache security module

apache__security_module_enabled

Enable the security2 module for Apache.

apache__security_module_enabled: False
apache__security_module_server_signature

Refer to the ModSecurity SecServerSignature directive documentation. This directive is not set if the special value omit is set.

apache__security_module_server_signature: '{{ omit }}'

Multi-processing module

Selection of the MPM to use is leaved to Debian package maintainer scripts which will select a suitable MPM. Note that some Apache modules can depend on certain MPMs being used which will be configured in the package maintainer scripts of those modules.

apache__mpm_max_connections_per_child

Number of requests a child process will handle before terminating. Refer to the Apache MaxConnectionsPerChild directive documentation for details.

apache__mpm_max_connections_per_child: '0'

Configuration snippets

Apache configuration snippets can be defined in multiple YAML dictionaries which are combined together. This allows configuration of Apache on different inventory levels as needed.

See apache__snippets for more details.

apache__snippets

This variable is intended to be used in Ansible’s global inventory as needed.

apache__snippets: {}
apache__group_snippets

This variable is intended to be used in a host inventory group of Ansible (only one host group is supported).

apache__group_snippets: {}
apache__host_snippets

This variable is intended to be used in the inventory of hosts as needed.

apache__host_snippets: {}
apache__dependent_snippets

This variable is intended for other Ansible roles to be used when using debops.apache as role dependency.

apache__dependent_snippets: {}
apache__role_snippets

Apache snippets used internally by this role.

apache__role_snippets:
  'local-debops_apache': True

  'security':
    type: 'divert'
    raw: |
      # This file exists here to make Debian package scripts happy.
      # For the actual security directives enabled in server context refer to
      # the `local-debops_apache.conf` file.
      #
      # `postinst` of the `apache2` package normally tries to enable the
      # `security` snippet in server context without checking if it is actually
      # there. The package provided `security.conf` snippet has been diverted
      # to `package-security.conf` and is not enabled to allow `debops.apache`
      # to configure and change security related settings.
    divert_filename: 'package-security'
    divert_suffix: ''

  'local-debops_apache_security_module':
    state: '{{ apache__security_module_enabled|bool | ternary("present", "absent") }}'
apache__combined_snippets

The dictionaries which holds the actual Apache _snippets combined from the above variables.

apache__combined_snippets: '{{ apache__dependent_snippets
                               | combine(apache__role_snippets)
                               | combine(apache__snippets)
                               | combine(apache__group_snippets)
                               | combine(apache__host_snippets) }}'

HTTP security headers

Sensible default configuration of HTTP security headers. Note that a few security headers can not be reasonably set by default because they have to be fine-tuned for the website in question. Refer HTTP security headers for details.

apache__http_csp_append

CSP directives to append to all policies. This can be used to set the report-uri globally. The string MUST end with a semicolon but MUST NOT begin with one. Refer HTTP security headers for details.

apache__http_csp_append: ''
apache__http_frame_options

Default value for the X-Frame-Options header. Set to False to omit this header. Refer to the RFC 7034 for details.

apache__http_frame_options: 'SAMEORIGIN'
apache__http_xss_protection

Refer to item.http_xss_protection for details.

apache__http_xss_protection: '1; mode=block'
apache__http_referrer_policy

Refer to item.http_referrer_policy for details.

apache__http_referrer_policy: 'same-origin'
apache__http_content_type_options

FIXME

apache__http_content_type_options: 'nosniff'
apache__http_sec_headers_directive_options

What condition and action should be used for the Header directives generated from this section? Two popular options are always set and set. Note that if Header set is used in .htaccess for example while using always set for this variable then Apache will add the header a second time which you probably don’t want.

apache__http_sec_headers_directive_options: 'set'

Virtual hosts

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.

See apache__vhosts for more details.

apache__vhosts

This variable is intended to be used in Ansible’s global inventory as needed.

apache__vhosts: []
apache__default_vhost

Default virtual host which will receive all requests which don’t match other virtual hosts. Refer to the Apache virtual host matching documentation for details.

apache__default_vhost:
  name: '{{ apache__default_vhost_name }}'
  filename: '000-default'
  root: '/var/www/html'
apache__default_vhost_name

Default virtual host name. Ideally, this a FQDN for which a valid certificate is present so that Apache does not complain about a certificate subject mismatch.

apache__default_vhost_name: 'default.{{ apache__domain }}'
apache__group_vhosts

This variable is intended to be used in a host inventory group of Ansible (only one host group is supported).

apache__group_vhosts: []
apache__host_vhosts

This variable is intended to be used in the inventory of hosts as needed.

apache__host_vhosts: []
apache__role_vhosts

Used internally by this role. Order is important.

apache__role_vhosts:

  - name: '000-default'
    type: 'divert'
    divert_filename: 'package-default'
    divert_suffix: ''
    comment: |
      `postinst` of the `apache2` package normally tries to enable
      the `000-default` site without checking if it is actually there.
      Divert the package provided `000-default` site file away, we will not need it :)

  - name: 'default-ssl'
    type: 'divert'
    divert_filename: 'package-default-https'
    divert_suffix: ''
    comment: |
      Divert the package provided `default-ssl` site file away, we will not need it :)

  - '{{ apache__default_vhost }}'
  - '{{ apache__status_vhost }}'
apache__dependent_vhosts

This variable is intended for other Ansible roles to be used when using debops.apache as role dependency.

apache__dependent_vhosts: []
apache__combined_vhosts

The list which holds the actual Apache virtual hosts combined from the above variables.

apache__combined_vhosts: '{{ apache__vhosts +
                             apache__group_vhosts +
                             apache__host_vhosts +
                             apache__role_vhosts +
                             apache__dependent_vhosts }}'
apache__vhost_type

The default template type to use for virtual hosts. See apache__vhosts for more details.

apache__vhost_type: 'default'
apache__vhost_allow_override

The default AllowOverride to use for virtual hosts. Refer to the Apache AllowOverride directive documentation for details.

apache__vhost_allow_override: 'None'
apache__vhost_options

The default Options to use for virtual hosts. Refer to the Apache Options directive documentation for details.

apache__vhost_options: [ '+FollowSymLinks' ]

Logging

apache__log_level

The default log level to use. Refer to the Apache LogLevel directive documentation for details.

apache__log_level: 'warn'
apache__access_log_format

Default log format as defined in /etc/apache2/apache2.conf. Refer to the Apache LogFormat directive documentation for details.

apache__access_log_format: 'combined'

Apache Status

Refer to the Apache mod_status documentation for details.

apache__status_enabled

Should the Apache server status be enabled by loading the required modules?

apache__status_enabled: False
apache__status_vhost_enabled

Should the Apache server status page be accessible using a independent virtual host bound to localhost?

apache__status_vhost_enabled: '{{ apache__status_enabled }}'
apache__status_for_vhost_enabled

Should the Apache server status page be enabled in all virtual hosts?

Note that even when this option evaluates to False, the hardcoded /server-status URL path is not fully neutralized. That is because the Apache SetHandler directive is set by the Apache Debian package in server config context. All access granted by package defaults is of course revoked by this Ansible role, again in server config context. But this means that for any virtual host, a request against /server-status (regardless of the value of apache__status_location) will be answered with a 403 Forbidden. If that causes a problem, the role could be changed to not enable the default module configuration and load the module directly from server config context. Or maybe someone has a workaround which does not involve changing the package module defaults.

Refer to item.status_enabled for how to overwrite this for a virtual host.

apache__status_for_vhost_enabled: False
apache__status_location

The Location or URL path by which the Apache server status should be accessible. Refer to item.status_location for how to overwrite this for a virtual host.

apache__status_location: '/server-status'
apache__status_allow_localhost

Allow access to the Apache server status using the Require local directive (refer to the Apache host Require directive documentation). Refer to item.status_allow_localhost for how to overwrite this for a virtual host.

apache__status_allow_localhost: False
apache__status_directives

Additional directives included into the Location sections for the Apache server status configuration. Can be used to customize access for example. Refer to item.status_directives for how to overwrite this for a virtual host.

apache__status_directives: ''
apache__status_extended_enabled

This option tracks additional data per worker about the currently executing request and creates a utilization summary. Refer to the Apache ExtendedStatus directive documentation for details. Note that this setting cannot be changed during a graceful restart. You will need to restart Apache yourself for a change to take effect!

apache__status_extended_enabled: '{{ apache__status_enabled|bool }}'
apache__status_vhost_name

Virtual host name for providing the Apache server status.

apache__status_vhost_name:
  - 'localhost'
apache__status_vhost

Optional virtual host for providing the Apache server status.

apache__status_vhost:
  name: '{{ apache__status_vhost_name }}'
  filename: 'debops.apache-status'
  status_enabled: True
  status_allow_localhost: True
  listen_http: [ 'localhost:80' ]
  https_enabled: False
  enabled: '{{ apache__status_vhost_enabled|bool }}'

Configuration for other Ansible roles

apache__ferm__dependent_rules

Configuration for debops.ferm Ansible role.

apache__ferm__dependent_rules:

  - type: 'accept'
    dport: '{{ apache__http_listen | union(apache__https_listen) }}'
    saddr: '{{ apache__allow + apache__group_allow + apache__host_allow }}'
    accept_any: True
    weight: '40'
    by_role: 'debops.apache'
    name: 'http_https'
    multiport: True
    rule_state: '{{ apache__deploy_state }}'