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 }}'