User’s guide 

Introduction 

The role will install and configure Apache web server

Ansible role: Apache
Supported systems: FreeBSD
Requirements:

The user is expected to have basic knowledge of Ansible

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

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 $ ansible-galaxy search --author=vbotka

Ansible playbook 

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

shell> 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

gather_facts: true (3) must be set to collect variables

needed to evaluate OS specific default variables and OS specific custom variables

[ansible_distribution, ansible_distribution_release, ansible_os_family]
See Variables

See also

For details see Connection Plugins (4-5)
and Understanding Privilege Escalation (6-8).

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 the below command

 shell> 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_samples,
   apache_service, apache_vars]

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

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

See what packages will be installed

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

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

shell> 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

shell> ansible-playbook apache.yml -e 'apache_debug=true'

See also

Playbook Debugger

Variables 

In this guide we describe the role default 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,14-15,69-70)
For Apache configuration (23-62,65) see Apache HTTP Server Documentation.
Other variables (75,78,81,84-85) will be explained in the next sections.

[defaults/main.yml]

---
# 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_servertokens: Prod
apache_httpd_conf:
  - {regexp: ServerName, line: "{{ apache_servername }}"}
  - {regexp: ServerAdmin, line: "{{ apache_serveradmin }}"}
  - {regexp: ServerTokens, line: "{{ apache_servertokens }}"}

# 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"
# Note: The regex value must be terminated by one space
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: '81'
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"

# samples
apache_samples: false
apache_samples_list:
  - httpd.conf
  - magic
  - mime.types
  - extra/httpd-autoindex.conf
  - extra/httpd-dav.conf
  - extra/httpd-default.conf
  - extra/httpd-info.conf
  - extra/httpd-languages.conf
  - extra/httpd-manual.conf
  - extra/httpd-mpm.conf
  - extra/httpd-multilang-errordoc.conf
  - extra/httpd-ssl.conf
  - extra/httpd-userdir.conf
  - extra/httpd-vhosts.conf
  - extra/proxy-html.conf

# rc.conf
apache_rcconf: []

# EOF
...

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.

 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

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.

[vars/defaults/FreeBSD.yml]

---
# FreeBSD defaults for vbotka.apache

freebsd_install_method: packages
# freebsd_install_method: ports
freebsd_use_packages: true
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 

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.

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

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

The default value is an empty list apache_vhost: []
For details see httpd-vhosts.yml. [httpd-vhosts.yml]

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

 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

The default value is an empty dictionary apache_directory_blocks: {}
For details see httpd-dirs.yml. [httpd-dirs.yml]

apache_alias 

Synopsis 

apache_alias is a list of aliases.

Example 

 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

The default value is an empty list apache_alias: []
For details see httpd-alias.yml. [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 the file will be included in {{ apache_conf_path }}/httpd.conf.

 $ 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

Notes 

Note

For details see httpd-confd-vhosts.yml. [httpd-confd-vhosts.yml]

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

$ 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>

Notes 

Note

For details see httpd-confd-includes.yml. [httpd-confd-includes.yml]

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 

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 httpd.yml. [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 httpd-ssl.yml. [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

See the default value in Default variables
For details see httpd-ssl.yml. [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 httpd-ssl.yml. [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

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 httpd-ssl.yml. [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 

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

The default value is

apache_httpd_conf_modules:

- {module: "socache_shmcb_module", mod: "mod_socache_shmcb.so"}
For details see httpd-modules.yml. [httpd-modules.yml]