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 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 toTrue
.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
unlessitem.state
is set toabsent
. Whether the configuration snippet should be enabled or disabled in Apache server context.state
Optional, String. Defaults to
present
. Whether the module should bepresent
orabsent
in theconf-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. Ifraw
is specified, a special template will be used which simply writes the given content into the snippet. Refer to the Apache configuration sections documentation 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 thesites-available
directory.divert_filename
Optional, string. The default value is determined based on the values of
item.name
anditem.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 theitem.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 sameitem.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 bepresent
orabsent
.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 toFalse
.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 toFalse
.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.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.
include_optional
Optional, string or list of strings. The given files are included the appropriate virtual host context using the IncludeOptional directive.
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 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 toitem.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 toitem.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
IfTrue
, redirect connection from HTTP to the HTTPS version of the site. Set toFalse
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 inapache__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 toTrue
and HTTPS is enabled for this item, the HTTP Strict Transport Security header is set in the server's responses. If this is set toFalse
, 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 theContent-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 noitem.csp_report
is given, it also determines the first part of theContent-Security-Policy-Report-Only
header. Which headers are actually enabled is defined byitem.csp_enabled
anditem.csp_report_enabled
. Refer to the Content Security Policy Reference.csp_report
Optional, string. This allows to set a different/potentially experimental
Content-Security-Policy-Report-Only
header than defined byitem.csp
.csp_append
Optional, string. Defaults to:
apache__http_csp_append
. CSP directives to append to all policies (item.csp
anditem.csp_report
). This can be used to overwrite the defaultapache__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 toTrue
and HTTPS is enabled for this item, theContent-Security-Policy
header is set in server responses.csp_report_enabled
Optional, boolean. Defaults to
False
. If this is set toTrue
and HTTPS is enabled for this item, theContent-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 toapache__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”?.
http_referrer_policy
Optional, string. Value of the
Referrer-Policy
HTTP header field. Set to{{ omit }}
to not send the header field. Defaults toapache__http_referrer_policy
. Refer to 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 toapache__status_location
.
status_allow_localhost
Optional, boolean. Allow access to the Apache server status using the
Require local
directive. Defaults toapache__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 toapache__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 thesites-available
directory.divert_filename
Optional, string. The default value is determined based on the values of
item.name
anditem.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 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.