User’s guide

Welcome to the User’s Guide!

Introduction

The role install and configure Apache web server

The user of this role is expected to have read at least the following documents

Installation

The most convenient way how to install an Ansible role is to use Ansible Galaxy CLI ansible-galaxy. The utility comes with the standard Ansible packages and provide the user with simple interface to the Ansible Galaxy’s services. For example take a look at the current status of the role

$ ansible-galaxy info vbotka.apache

and install it

$ ansible-galaxy install vbotka.apache

Together with the role vbotka.apache two other roles will be installed.

See also

  • For details how to install specific versions from various sources see Installing content.
  • Take a look at other roles $ ansible-galaxy search --author=vbotka

Ansible playbook

Simple playbook to install and configure Apache at srv.example.com (2)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ cat apache.yml
- hosts: srv.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: yes
  become_user: root
  become_method: sudo
  roles:
    - vbotka.apache

Note

See also

Tags

The tags provide very useful tool to run selected tasks of the role. To see what tags are available list the tags of the role with command below

1
2
3
4
5
6
7
8
9
 $ ansible-playbook apache.yml --list-tags

 playbook: apache.yml

 play #1 (srv.example.conf): srv.example.com TAGS: []
   TASK TAGS: [always, apache-debug, apache-httpd, apache-httpd-alias,
   apache-httpd-confd, apache-httpd-confd-includes, apache-httpd-confd-vhosts,
   apache-httpd-dirs, apache-httpd-modules, apache-httpd-ssl, apache-httpd-vhosts,
   apache-packages, apache-service, apache-vars]

For example see the list of the variables and their values with the tag apache-debug

$ ansible-playbook apache.yml -t apache_debug -e 'apache_debug=true'

See what packages will be installed

$ ansible-playbook apache.yml -t apache_packages -e 'apache_debug=true' --check

Install packages only and exit the play. Enable the debug output

$ ansible-playbook apache.yml -t apache_packages -e 'apache_debug=true'

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

$ ansible-playbook apache.yml -e 'apache_debug=true'

Variables

In this guide we describe role defaults variables in the directory defaults and variables included from the directory vars.

  • 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 (4-9,12-13,64-65)
  • For Apache configuration (19-54,60) see Apache HTTP Server Documentation.
  • Other variables (70,73,76,79-80) will be explained in the next sections.

[defaults/main.yml]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
---
# defaults for vbotka.apache

apache_install: true
apache_enable: true
apache_debug: false
apache_ssl: false
apache_php: false
apache_backup_conf: false

apache_SSLEngine: "off"

# httpd.conf
apache_ServerName: "www.example.com"
apache_ServerAdmin: "admin@example.com"
apache_httpd_conf:
  - {regexp: "ServerName", line: "{{ apache_ServerName }}"}
  - {regexp: "ServerAdmin", line: "{{ apache_ServerAdmin }}"}

# SSL
apache_SSLListen: ""
apache_SSLCertificateFile: "/usr/local/etc/apache{{ apache_version }}/server.crt"
apache_SSLCertificateKeyFile: "/usr/local/etc/apache{{ apache_version }}/server.key"
apache_SSLProtocol: "all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1"
# apache_SSLCipherSuite: HIGH:!aNULL:!MD5
# apache_SSLCipherSuite: RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
apache_SSLCipherSuite: "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"
apache_SSLHonorCipherOrder: "on"
apache_SSLCompression: "off"
apache_SSLSessionTickets: "off"
# SSLOpenSSLConfCmd DHParameters "/usr/local/etc/ssl/dhparam.pem"
# SSLSessionCache shmcb:/var/run/ssl_scache(512000)
# Header always set X-Frame-Options DENY
# Header always set X-Frame-Options SAMEORIGIN
apache_httpd_conf_ssl:
  - "Include etc/apache{{ apache_version }}/extra/httpd-ssl.conf"
apache_httpd_conf_ssl_extra:
  - {regexp: "ServerName ", line: "{{ apache_ServerName }}:443"}
  - {regexp: "ServerAdmin ", line: "{{ apache_ServerAdmin }}"}
  - {regexp: "SSLEngine ", line: "{{ apache_SSLEngine }}"}
  - {regexp: "SSLProtocol ", line: "{{ apache_SSLProtocol }}"}
  - {regexp: "SSLCipherSuite ", line: "{{ apache_SSLCipherSuite }}"}
  - {regexp: "SSLHonorCipherOrder ", line: "{{ apache_SSLHonorCipherOrder }}"}
  - {regexp: "SSLCompression ", line: "{{ apache_SSLCompression }}"}
  - {regexp: "SSLSessionTickets ", line: "{{ apache_SSLSessionTickets }}"}
  - {regexp: "SSLCertificateFile ", line: "{{ apache_SSLCertificateFile }}"}
  - {regexp: "SSLCertificateKeyFile ", line: "{{ apache_SSLCertificateKeyFile }}"}
apache_httpd_conf_ssl_extra_absent: []
apache_httpd_conf_ssl_listen:
  - "Listen 443"

# Modules
apache_httpd_conf_modules:
  - {module: "socache_shmcb_module", mod: "mod_socache_shmcb.so"}

# PHP
apache_php_version: "56"
apache_php_package: "www/mod_php{{ apache_php_version }}"

# vhosts
# Virtual hosts need apache_ssl. Port 80 is redirected permanently to
# 443 for vhosts.
apache_vhost: []

# dirs
apache_directory_blocks: []

# aliases
apache_alias: []

# conf.d
apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/vhosts"
apache_confd_dir_sections: "{{ role_path }}/vars/conf.d/sections"

# EOF
...

Warning

By default SSL is turned off apache_SSLEngine: "off" (9).

OS specific default variables

Here come the OS specific default variables. The configuration files in the directory vars/defaults will be included with_first_found (1). At least empty default.yml (6) shall be present.

1
2
3
4
5
6
7
8
 with_first_found:
 - files:
     - "{{ ansible_distribution }}-{{ ansible_distribution_release }}.yml"
     - "{{ ansible_distribution }}.yml"
     - "{{ ansible_os_family }}.yml"
     - "default.yml"
     - "defaults.yml"
   paths: "{{ al_os_vars_path }}/vars/defaults"

Note

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.

[vars/defaults/FreeBSD.yml]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
# FreeBSD defaults for vbotka.apache

freebsd_install_method: "packages"
# freebsd_install_method: "ports"
freebsd_use_packages: "yes"
freebsd_install_retries: 10
freebsd_install_delay: 5

apache_version: "24"
apache_package: "www/apache{{ apache_version }}"
apache_dir: "apache{{ apache_version }}"
apache_service: "apache{{ apache_version }}"
apache_conf_path: "/usr/local/etc/apache{{ apache_version }}"
apache_data_owner: "www"
apache_data_group: "wheel"
apache_data_mode: "0640"
apache_dir_mode: "0750"
apache_packages:
  - "{{ apache_package }}"

# EOF
...

OS specific custom variables

Here come the OS specific custom variables. The configuration files in the directory vars will be included with_first_found (1) and will override the default values of the variables. At least empty default.yml (6) shall be present here.

1
2
3
4
5
6
7
8
 with_first_found:
 - files:
     - "{{ ansible_distribution }}-{{ ansible_distribution_release }}.yml"
     - "{{ ansible_distribution }}.yml"
     - "{{ ansible_os_family }}.yml"
     - "default.yml"
     - "defaults.yml"
   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.
  • See al_include_os_vars_path.yml.

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).

1
2
3
4
5
apache_vhost:
  - ServerName: "mail.example.net"
    DocumentRoot: "/usr/local/www/roundcube/"
    SSLCertificateFile: "/usr/local/etc/letsencrypt/live/mail.example.net/fullchain.pem"
    SSLCertificateKeyFile: "/usr/local/etc/letsencrypt/live/mail.example.net/privkey.pem"

Notes

Note

See Also

See also

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
2
3
4
5
6
7
8
 apache_directory_blocks:
   - Directory: "/usr/local/www/roundcube"
     Includefile: "usr-local-www-roundcube.conf"
     Conf:
       - "Options Indexes FollowSymLinks"
       - "DirectoryIndex index.html"
       - "AllowOverride All"
       - "Require all granted"

Notes

Note

apache_alias

Synopsis

  • apache_alias is a list of aliases.

Example

1
2
3
4
 apache_alias:
   - "ScriptAlias /nagios/cgi-bin/ /usr/local/www/nagios/cgi-bin/"
   - "Alias /nagios/ /usr/local/www/nagios/"
   - "Alias /joomla /usr/local/www/joomla3/"

Notes

Note

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 the file will be included in {{ apache_conf_path }}/httpd.conf.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
 $ cat mail.example.net/apache.d/vhosts/mail.example.net.yml
 my_apache_vhost:
   content:
     - sections:
         - name: VirtualHost
           param: "*:80"
           content:
             - options:
                 - ServerName: mail.example.net
                 - DocumentRoot: /usr/local/www/roundcube/
                 - Redirect permanent /: https://mail.example.net/
     - sections:
         - name: VirtualHost
           param: "*:443"
           content:
             - options:
                 - ServerName: mail.example.net
                 - DocumentRoot: /usr/local/www/roundcube/
                 - SSLCertificateFile: /usr/local/etc/ssl/certs/mail.example.net.crt
                 - SSLCertificateKeyFile: /usr/local/etc/ssl/private/mail.example.net.key

Hints

Hint

  • The default value is
    apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/vhosts"
  • In projects it might be convenient to change the path. For example
    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).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
$ cat mail.example.net/apache.d/sections/usr-local-www-roundcube.yml
my_apache_dir:
  content:
    - sections:
        - name: Directory
          param: /usr/local/www/roundcube
          content:
            - options:
                - Options:
                    - Indexes
                    - FollowSymLinks
                - AllowOverride: All
                - Require:
                    - all
                    - granted

$ cat /usr/local/etc/apache24/Includes/usr-local-www-roundcube.conf
<Directory /usr/local/www/roundcube>
  Options Indexes FollowSymLinks
  AllowOverride All
  Require all granted
</Directory>

Hints

Hint

  • The default value is
    apache_confd_dir_vhosts: "{{ role_path }}/vars/conf.d/sections"
  • In projects it might be convenient to change the path. For example
    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

1
2
3
4
5
apache_httpd_conf:
  - {regexp: "ServerName", line: "{{ apache_ServerName }}"}
  - {regexp: "ServerAdmin", line: "{{ apache_ServerAdmin }}"}
  - {regexp: "ServerRoot", line: "/usr/local"}
  - {regexp: "MIMEMagicFile", line: "etc/apache24/magic"}

Notes

Note

* The default value is
apache_httpd_conf:
- {regexp: "ServerName", line: "{{ apache_ServerName }}"}
- {regexp: "ServerAdmin", line: "{{ apache_ServerAdmin }}"}
* The argument line must be quoted if it contains spaces
- {regexp: "ErrorDocument 500", line: "\"The server made a boo boo.\""}
* For details see Configure httpd.conf. [httpd.yml]

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

* The default value is
apache_httpd_conf_ssl:
- "Include etc/apache{{ apache_version }}/extra/httpd-ssl.conf
* For details see Configure ssl. [httpd-ssl.yml]

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

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

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

  • The default value is
    apache_httpd_conf_ssl_listen:
    - "Listen 443"
  • Overlapping Listen directives will result in a fatal error which
    will prevent the server from starting up.
  • For details see Configure ssl. [httpd-ssl.yml]

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 LoadModule
directive will be added to
httpd.conf.
If false directive will
be commented (disabled).

Example

1
2
3
4
apache_httpd_conf_modules:
  - {module: "socache_shmcb_module", mod: "mod_socache_shmcb.so"}
  - {module: "ssl_module", mod: "mod_ssl.so"}
  - {module: "php5_module", mod: "libphp5.so"}

Notes

Note