debops.apache default variables
Sections
- orphan
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__group_packages
List of custom APT packages installed on hosts in a specific group in Ansible inventory.
apache__group_packages: []
- apache__host_packages
List of custom APT packages installed on specific hosts in Ansible inventory.
apache__host_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_fqdn }}'
- apache__domain
The domain name of the host running Apache.
apache__domain: '{{ ansible_domain }}'
- 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.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: Not 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 and apache__https_enabled) 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 left 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 an 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 }}'