User’s guide
Introduction
The role will install and configure Apache web server
Ansible role: vbotka.apache
Supported systems: FreeBSD
Requirements:
The user is expected to have basic knowledge of Ansible
Installation
The most convenient way on how to install a Ansible role or collection is to use Ansible Galaxy CLI
ansible-galaxy
. The utility is installed by the standard Ansible package and provides the user with
simple interface to the Ansible Galaxy’s services. For example take a look at the current status of
the role
shell> ansible-galaxy role info vbotka.apache
and install it
shell> ansible-galaxy role install vbotka.apache
Together with the role vbotka.apache dependent role jtyr.config_encoder_filters will be installed (see meta/main.yml). This role provides the filter encode_apache used to encode YAML configuration data to the Apache format.
Install the library vbotka.ansible_lib, if necessary
shell> ansible-galaxy role install vbotka.ansible_lib
Install the collection community.general
shell> ansible-galaxy collection install community.general
See also
For details on how to install specific versions from various sources see Installing content.
Take a look at other roles
shell> ansible-galaxy search --author=vbotka
Ansible playbook
Simple playbook to install and configure Apache at srv.example.com (2)
1shell> cat apache.yml
2- hosts: srv.example.com
3 gather_facts: true
4 connection: ssh
5 remote_user: admin
6 become: yes
7 become_user: root
8 become_method: sudo
9 roles:
10 - vbotka.apache
Note
See Variables.
gather_facts: true
(3) must be set to collect variables needed to evaluateansible_distribution
,ansible_distribution_release
,ansible_os_family
See also
For details see Connection Plugins (4-5) and
Debug
To see additional debug information in the output enable debug output in the configuration
apache_debug: true
, or set the extra variable in the command
shell> ansible-playbook apache.yml -e 'apache_debug=true'
See also
Variables
In this section we describe default variables stored in the directory defaults
and variables
included from the directory vars
.
Precedence:
role defaults in the directory
{{ role_path }}/defaults
(precedence 2.)include OS specific vars from the directory
{{ role_path }}/vars
(precedence 18.)
Default variables
Most of the variables are self-explaining. For Apache configuration (23-58) see Apache HTTP Server Documentation. Other variables will be explained in the following sections.
1---
2# defaults for vbotka.apache
3
4apache_install: true
5apache_enable: true
6apache_debug: false
7apache_ssl: false
8apache_php: false
9apache_backup_conf: false
10
11apache_sslengine: "off"
12
13# httpd.conf
14apache_servername: www.example.com
15apache_serveradmin: admin@example.com
16apache_servertokens: Prod
17apache_httpd_conf:
18 - { regexp: ServerName, line: "{{ apache_servername }}" }
19 - { regexp: ServerAdmin, line: "{{ apache_serveradmin }}" }
20 - { regexp: ServerTokens, line: "{{ apache_servertokens }}" }
21
22# SSL
23apache_ssllisten: ""
24apache_sslcertificatefile: /usr/local/etc/apache{{ apache_version }}/server.crt
25apache_sslcertificatekeyfile: /usr/local/etc/apache{{ apache_version }}/server.key
26apache_sslprotocol: all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
27# apache_sslciphersuite: HIGH:!aNULL:!MD5
28# apache_sslciphersuite: RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
29apache_sslciphersuite:
30 ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
31apache_sslhonorcipherorder: "on"
32apache_sslcompression: "off"
33apache_sslsessiontickets: "off"
34# SSLOpenSSLConfCmd DHParameters '/usr/local/etc/ssl/dhparam.pem'
35# SSLSessionCache shmcb:/var/run/ssl_scache(512000)
36# Header always set X-Frame-Options DENY
37# Header always set X-Frame-Options SAMEORIGIN
38apache_httpd_conf_ssl:
39 - Include etc/apache{{ apache_version }}/extra/httpd-ssl.conf
40# Note: The regex value must be terminated by one space
41apache_httpd_conf_ssl_extra:
42 - { regexp: "ServerName ", line: "{{ apache_servername }}:443" }
43 - { regexp: "ServerAdmin ", line: "{{ apache_serveradmin }}" }
44 - { regexp: "SSLEngine ", line: "{{ apache_sslengine }}" }
45 - { regexp: "SSLProtocol ", line: "{{ apache_sslprotocol }}" }
46 - { regexp: "SSLCipherSuite ", line: "{{ apache_sslciphersuite }}" }
47 - { regexp: "SSLHonorCipherOrder ", line: "{{ apache_sslhonorcipherorder }}" }
48 - { regexp: "SSLCompression ", line: "{{ apache_sslcompression }}" }
49 - { regexp: "SSLSessionTickets ", line: "{{ apache_sslsessiontickets }}" }
50 - { regexp: "SSLCertificateFile ", line: "{{ apache_sslcertificatefile }}" }
51 - { regexp: "SSLCertificateKeyFile ", line: "{{ apache_sslcertificatekeyfile }}" }
52apache_httpd_conf_ssl_extra_absent: []
53apache_httpd_conf_ssl_listen:
54 - Listen 443
55
56# Modules
57apache_httpd_conf_modules:
58 - { module: socache_shmcb_module, mod: mod_socache_shmcb.so }
59
60# PHP
61apache_php_version: "81"
62apache_php_package: www/mod_php{{ apache_php_version }}
63
64# vhosts
65# Virtual hosts need apache_ssl. Port 80 is redirected permanently to
66# 443 for vhosts.
67apache_vhost: []
68# dirs
69apache_directory_blocks: []
70# aliases
71apache_alias: []
72# conf.d
73apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/vhosts"
74apache_confd_dir_sections: "{{ role_path }}/vars/conf.d/sections"
75
76# samples
77apache_samples: false
78apache_samples_list:
79 - httpd.conf
80 - magic
81 - mime.types
82 - extra/httpd-autoindex.conf
83 - extra/httpd-dav.conf
84 - extra/httpd-default.conf
85 - extra/httpd-info.conf
86 - extra/httpd-languages.conf
87 - extra/httpd-manual.conf
88 - extra/httpd-mpm.conf
89 - extra/httpd-multilang-errordoc.conf
90 - extra/httpd-ssl.conf
91 - extra/httpd-userdir.conf
92 - extra/httpd-vhosts.conf
93 - extra/proxy-html.conf
94
95# rc.conf
96apache_rcconf: []
Warning
By default, SSL is turned off apache_sslengine: "off"
(11).
OS specific default variables
The configuration files from the directory vars/defaults
will be included in the loop
with_first_found
(1). At least empty default.yml
(6) shall be present.
1 with_first_found:
2 - files:
3 - "{{ ansible_distribution }}-{{ ansible_distribution_release }}.yml"
4 - "{{ ansible_distribution }}.yml"
5 - "{{ ansible_os_family }}.yml"
6 - default.yml
7 - defaults.yml
8 paths: "{{ al_os_vars_path }}/vars/defaults"
Note
OS specific variables are included by the module
include_var
that has very high precedence (18 in the list of 22).See Ansible variable precedence: Where should I put a variable?
To override the default variables see OS specific custom variables.
FreeBSD default variables
By default, the binary packages will be installed (4). But, if custom builds are available switch to
ports
(5) and use freebsd_use_packages: "yes"
(6) to speedup the installation. Under
standard circumstances, there is no reason to change other parameters here.
1---
2# FreeBSD defaults for vbotka.apache
3
4freebsd_install_method: packages
5# freebsd_install_method: ports
6freebsd_use_packages: true
7freebsd_install_retries: 10
8freebsd_install_delay: 5
9
10apache_version: "24"
11apache_package: www/apache{{ apache_version }}
12apache_dir: apache{{ apache_version }}
13apache_service: apache{{ apache_version }}
14apache_conf_path: /usr/local/etc/apache{{ apache_version }}
15apache_data_owner: www
16apache_data_group: wheel
17apache_data_mode: "0640"
18apache_dir_mode: "0750"
19apache_packages:
20 - "{{ apache_package }}"
21
22# EOF
OS specific custom variables
The configuration files from the directory vars
will be included in the loop
with_first_found
(1) and will override the default values of the variables. At least empty
default.yml
(6) shall be present here.
1 with_first_found:
2 - files:
3 - "{{ ansible_distribution }}-{{ ansible_distribution_release }}.yml"
4 - "{{ ansible_distribution }}.yml"
5 - "{{ ansible_os_family }}.yml"
6 - default.yml
7 - defaults.yml
8 paths: "{{ al_os_vars_path }}/vars"
Note
OS specific variables from the directory
{{ al_os_vars_path }}/vars
override OS specific default variables from the directory{{ al_os_vars_path }}/vars/defaults
apache_vhost
Synopsis
apache_vhost
is a list of virtual hosts.
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
ServerName
|
string
required |
Fully qualified domain
name (FQDN)
|
DocumentRoot
|
string
required |
Path DocumentRoot
|
SSLCertificateFile
|
string
required |
Path to SSL Certificate
|
SSLCertificateKeyFile
|
string
required |
Path to SSL Private key
|
redirect
|
boolean
default: false |
Redirect permanent http
to https
|
create_document_root
|
boolean
default: false |
Create DocumentRoot
|
Example
The example below will configure virtual server mail.example.net
(2).
1apache_vhost:
2 - ServerName: "mail.example.net"
3 DocumentRoot: "/usr/local/www/roundcube/"
4 SSLCertificateFile: "/usr/local/etc/letsencrypt/live/mail.example.net/fullchain.pem"
5 SSLCertificateKeyFile: "/usr/local/etc/letsencrypt/live/mail.example.net/privkey.pem"
Notes
Note
The default value is an empty list
apache_vhost: []
For details see annotated source httpd-vhosts.yml
GitHub httpd-vhosts.yml
See Also
See also
It is also possible to configure virtual servers with
apache_confd_dir_vhosts
. See apache_confd_dir_vhosts.
apache_directory_blocks
Synopsis
apache_directory_blocks
is a list of directory blocks.
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
Directory
|
string
required |
DocumentRoot directory
|
Includefile
|
string
required |
Path to the includefile to be
created
|
Conf
|
list
|
Configuration of the directory
|
Example
Configuration file (3) will be created in the directory {{ apache_conf_path }}/Includes/
.
1 apache_directory_blocks:
2 - Directory: /usr/local/www/roundcube
3 Includefile: usr-local-www-roundcube.conf
4 Conf:
5 - Options Indexes FollowSymLinks
6 - DirectoryIndex index.html
7 - AllowOverride All
8 - Require all granted
Notes
Note
The default the value is an empty list
apache_directory_blocks: []
For details see annotated source httpd-dirs.yml
GitHub httpd-dirs.yml
See Also
See also
<TBD>
apache_alias
Synopsis
apache_alias
is a list of aliases.
Example
1 apache_alias:
2 - "ScriptAlias /nagios/cgi-bin/ /usr/local/www/nagios/cgi-bin/"
3 - "Alias /nagios/ /usr/local/www/nagios/"
4 - "Alias /joomla /usr/local/www/joomla3/"
Notes
Note
The default value is an empty list
apache_alias: []
For details see annotated source httpd-alias.yml
GitHub httpd-alias.yml
apache_confd_dir_vhosts
Synopsis
apache_confd_dir_vhosts
is path to directory with virtual hosts’ configuration files.
Parameters
The parameters and format of the files are described in the filter encode_apache.
Example
From the configuration file below the configuration file
{{ apache_conf_path }}/extra/mail.example.net.conf
will be created and included in {{ apache_conf_path }}/httpd.conf
1 shell> cat mail.example.net/apache.d/vhosts/mail.example.net.yml
2 my_apache_vhost:
3 content:
4 - sections:
5 - name: VirtualHost
6 param: "*:80"
7 content:
8 - options:
9 - ServerName: mail.example.net
10 - DocumentRoot: /usr/local/www/roundcube/
11 - Redirect permanent /: https://mail.example.net/
12 - sections:
13 - name: VirtualHost
14 param: "*:443"
15 content:
16 - options:
17 - ServerName: mail.example.net
18 - DocumentRoot: /usr/local/www/roundcube/
19 - SSLCertificateFile: /usr/local/etc/ssl/certs/mail.example.net.crt
20 - SSLCertificateKeyFile: /usr/local/etc/ssl/private/mail.example.net.key
Notes
Note
For details see annotated source httpd-confd-vhosts.yml
GitHub httpd-confd-vhosts.yml
Hints
Hint
apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/vhosts"
apache_confd_dir_vhosts: "{{ playbook_dir }}/apache.d/vhosts"
apache_confd_dir_sections
Synopsis
apache_confd_dir_sections
is path to directory with configuration files.
Parameters
The parameters and format of the files are described in the filter
encode_apache.
The content of the files will be encoded and stored in the files in the
directory {{ apache_conf_path }}/Includes/
.
Example
For example, from the configuration file below the configuration file
usr-local-www-roundcube.conf
will be created and stored in the
directory {{ apache_conf_path }}/Includes
(17).
1shell> cat mail.example.net/apache.d/sections/usr-local-www-roundcube.yml
2my_apache_dir:
3 content:
4 - sections:
5 - name: Directory
6 param: /usr/local/www/roundcube
7 content:
8 - options:
9 - Options:
10 - Indexes
11 - FollowSymLinks
12 - AllowOverride: All
13 - Require:
14 - all
15 - granted
16
17shell> cat /usr/local/etc/apache24/Includes/usr-local-www-roundcube.conf
18<Directory /usr/local/www/roundcube>
19 Options Indexes FollowSymLinks
20 AllowOverride All
21 Require all granted
22</Directory>
Notes
Note
For details see annotated source httpd-confd-includes.yml, or
GitHub httpd-confd-includes.yml
Hints
Hint
apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/sections"
apache_confd_dir_vhosts: "{{ playbook_dir }}/apache.d/sections"
apache_httpd_conf
Synopsis
apache_httpd_conf
is a list of lines in httpd.conf
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
regexp
|
string
required |
The pattern to replace if
found
|
line
|
string
required |
The line to insert/replace
into the file
|
Example
1apache_httpd_conf:
2 - { regexp: ServerName, line: "{{ apache_servername }}" }
3 - { regexp: ServerAdmin, line: "{{ apache_serveradmin }}" }
4 - { regexp: ServerRoot, line: /usr/local }
5 - { regexp: MIMEMagicFile, line: etc/apache24/magic }
Notes
Note
apache_httpd_conf:
- {regexp: ServerName, line: "{{ apache_servername }}"}
- {regexp: ServerAdmin, line: "{{ apache_serveradmin }}"}
- {regexp: ErrorDocument 500, line: "\"The server made a boo boo.\""}
apache_httpd_conf_ssl
Synopsis
apache_httpd_conf_ssl
is a list of lines that configure SSL in httpd.conf
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
line
|
string
required |
The line to insert
into the file
|
Notes
Note
apache_httpd_conf_ssl:
- "Include etc/apache{{ apache_version }}/extra/httpd-ssl.conf"
apache_httpd_conf_ssl_extra
Synopsis
apache_httpd_conf_ssl_extra
is a list of lines that configure SSL in extra/httpd-ssl.conf
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
regexp
|
string
required |
The pattern to replace if
found
|
line
|
string
required |
The line to insert/replace
into the file
|
Notes
Note
See the default value in Default variables
For details see annotated source httpd-ssl.yml, or
GitHub httpd-ssl.yml
apache_httpd_conf_ssl_extra_absent
Synopsis
apache_httpd_conf_ssl_extra_absent
is a list of lines that will be removed from extra/httpd-ssl.conf
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
regexp
|
string
required |
The pattern to be removed
|
Notes
Note
The default value is empty list
apache_httpd_conf_ssl_extra_absent: []
For details see annotated source httpd-ssl.yml, or
GitHub httpd-ssl.yml
apache_httpd_conf_ssl_listen
Synopsis
apache_httpd_conf_ssl_listen
is a list of addresses and ports that the server will bind to.
Notes
Note
apache_httpd_conf_ssl_listen:
- Listen 443
apache_httpd_conf_modules
Synopsis
apache_httpd_conf_modules
is a list of modules to be loaded.
Parameters
Parameter
|
Type
|
Comments
|
---|---|---|
module
|
string
required |
Name of the module
|
mod
|
string
required |
Object file or Library
|
present
|
boolean
default: true |
If
true LoadModuledirective will be added to
httpd.conf.
If
false directive willbe commented (disabled).
|
Example
1apache_httpd_conf_modules:
2 - { module: socache_shmcb_module, mod: mod_socache_shmcb.so }
3 - { module: ssl_module, mod: mod_ssl.so }
4 - { module: php5_module, mod: libphp5.so }
Notes
Note
apache_httpd_conf_modules:
- { module: socache_shmcb_module, mod: mod_socache_shmcb.so }