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

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)

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

See Variables.
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 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. The below command lists the available tags

 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_php,
   apache_httpd_ssl, apache_httpd_vhosts, apache_pkg,
   apache_samples, apache_sanity, apache_service, apache_vars]

For example, display the variables

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

Display what packages will be installed

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

Install packages and exit the play. Enable the debug output

shell> ansible-playbook apache.yml -t apache_pkg -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 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.)

See also

Ansible variable precedence. Where should I put a variable?

Default variables 

Most of the variables are self-explaining. For Apache configuration see Apache HTTP Server Documentation.

main.yml

[defaults/main/main.yml]

---
# defaults for vbotka.apache
apache_role_version: 2.8.2

apache_install: true
apache_enable: true
apache_debug: false
apache_backup_conf: false

# Sanity
apache_sanity: true

# 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 }}"}

# dirs
apache_directory_blocks: []

# modules
apache_httpd_conf_modules: []
# - {module: socache_shmcb_module, mod: mod_socache_shmcb.so}

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

# aliases
apache_alias: []

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

# rc.conf
apache_rcconf: []

# Use vbotka.freebsd.lib in collection vbotka.freebsd
apache_ansible_lib:
  vbotka.apache: vbotka.ansible_lib
  vbotka.freebsd.apache: vbotka.freebsd.lib

# EOF

ssl.yml

Configure SSL/TLS when enabled (3)

[defaults/main/ssl.yml]

---
# defaults for vbotka.apache
apache_ssl: false
apache_sslengine: "off"
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: "{{ apache_sslciphersuite_list | join(':') }}"
apache_sslciphersuite_list:
  - 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

# EOF

Warning

By default, SSL is turned off apache_sslengine: "off" (4).

php.yml

Install and configure PHP when enabled (3). Install and configure FastCGI Process Manager (FPM) when enabled (4).

[defaults/main/php.yml]

---
# defaults for vbotka.apache
apache_php: false
apache_php_fpm: false

apache_php_blocks:
  - includefile: php.conf
    state: present
    block: "{{ apache_php_include }}"
  - includefile: php-fpm.conf
    state: "{{ apache_php_fpm | ternary('present', 'absent') }}"
    block: "{{ apache_php_fpm_include }}"

apache_php_include: |
  <IfModule dir_module>
    DirectoryIndex index.html index.php
  </IfModule>
  <FilesMatch "^(?!info\.php).+\.php$">
    SetHandler application/x-httpd-php
  </FilesMatch>
  <FilesMatch "^.+\.phps$">
    SetHandler application/x-httpd-php-source
  </FilesMatch>

# See role vbotka.freebsd_php variables bsd_php_conf_www_listen_*
apache_php_fpm_listen_sock: "/var/run/php{{ apache_php_version }}-fpm.sock"
apache_php_fpm_include: |
  <FilesMatch "^info.php$">
      SetHandler proxy:unix:{{ apache_php_fpm_listen_sock }}|fcgi://localhost/
      # use the following line instead if you didn't set PHP-FPM to listen on a Unix socket
      # SetHandler proxy:fcgi://127.0.0.1:9000
  </FilesMatch>

# EOF

samples.yml

Copy samples when enabled (3)

[defaults/main/samples.yml]

---
# defaults for vbotka.apache
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

# EOF

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_php_version: "83"
apache_php_package: www/mod_php{{ apache_php_version }}

apache_packages: "{{ apache_php | ternary(apache_pkg + apache_pkg_php, apache_pkg) }}"
apache_pkg:
  - "{{ apache_package }}"
apache_pkg_php:
  - "{{ apache_php_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 annotated source httpd-vhosts.yml
GitHub tasks/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 the value is an empty list apache_directory_blocks: []
For details see annotated source httpd-dirs.yml
GitHub tasks/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 annotated source httpd-alias.yml
GitHub tasks/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

 shell> 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 annotated source httpd-confd-vhosts.yml
GitHub tasks/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"

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

shell> 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 annotated source httpd-confd-includes.yml, or
GitHub tasks/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"

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

* Because of the escaped quotes the argument line must be quoted

- {regexp: ErrorDocument 500, line: "\"The server made a boo boo.\""}

* For details see annotated source httpd.yml, or

* GitHub tasks/httpd.yml

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 annotated source httpd-ssl.yml, or

* GitHub tasks/httpd-ssl.yml

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

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

apache_httpd_conf_ssl_listen:

- Listen 443

* Overlapping Listen directives will result in a fatal error.

* For details see annotated source httpd-ssl.yml, or

* GitHub tasks/httpd-ssl.yml

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 annotated source httpd-modules.yml, or

* GitHub tasks/httpd-modules.yml