Ansible collection: foundata.apache_httpd

Die Ansible-Collection foundata.apache_httpd stellt Ressourcen zur Verwaltung und Nutzung des Apache HTTP sservers bereit, einem HTTP-Webserver, Reverse-Proxy und Load Balancer, bereit

Die folgenden Abschnitte listen die README.md-Dateien der wichtigsten enthaltenen Inhalte (z. B. Rollen) auf. Für einen umfassenderen Überblick empfiehlt sich ein Blick in die Quellcode-Repositories.

Ansible role: foundata.apache_httpd.run

The foundata.apache_httpd.run Ansible role (part of the foundata.apache_httpd Ansible collection). It provides automated installation, configuration management, and hardening of Apache HTTP Server across major Linux distributions.

Features

Main features:

• VirtualHost management via sites-available/ and sites-enabled/ (Debian-style symlink pattern enforced on all platforms, including Red Hat and SUSE) with optional cleanup of unmanaged files.
• MPM selection: choose between event, worker, and prefork via a single variable; the role handles the platform-specific mechanism (Debian: mods-enabled/ symlinks, Red Hat: conf.modules.d/00-mpm.conf, SUSE: APACHE_MPM sysconfig variable).
• Module management: enable modules by short name, the role installs packages and activates modules automatically with cross-platform support (Debian: symlinks, Red Hat: package-managed conf.modules.d/ files, SUSE: APACHE_MODULES sysconfig variable).
• Layered configuration merge: production-ready internal defaults (see __run_apache_httpd_main_directives_defaults for the complete list) and user settings are combined automatically. User-provided values always take precedence.
• Hardened TLS baseline following the Mozilla “Intermediate” TLS profile (Guideline v6.0):
  • Post-quantum key exchange (X25519MLKEM768) on platforms with OpenSSL >= 3.5, automatic fallback to classical curves on older platforms.
  • Ships RFC 7919 ffdhe3072 DH parameters; no manual openssl dhparam step needed.
  • OCSP stapling, session resumption, and ECDHE-only cipher suites out of the box.
• Reusable, curated config snippets for common tasks, ready to Include in your VirtualHost configs:
  • global/tls-baseline.conf – TLS/SSL hardening (see above).
  • vhost/headers-security.conf – security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy).
  • vhost/headers-hsts.conf – HTTP Strict Transport Security with configurable max-age, includeSubDomains, and preload.
  • directory/cache-static.conf – long-lived caching for static assets (Cache-Control: public, immutable).
  • directory/php-fpm.conf – FastCGI proxy for PHP-FPM via mod_proxy_fcgi (Unix socket or TCP).
• Hardened catch-all <VirtualHost> that denies all requests / rejects unknown TLS handshakes, preventing unintended content exposure for unknown hostnames.

Example playbooks, using this role

Installation with automatic upgrade:

---

- name: "Initialize the foundata.apache_httpd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.apache_httpd.run role"
      ansible.builtin.include_role:
        name: "foundata.apache_httpd.run"
      vars:
        run_apache_httpd_autoupgrade: true

Installation with a TLS-enabled site, security headers, HSTS, and custom snippet settings:

---

- name: "Initialize the foundata.apache_httpd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.apache_httpd.run role"
      ansible.builtin.include_role:
        name: "foundata.apache_httpd.run"
      vars:
        run_apache_httpd_autoupgrade: true
        run_apache_httpd_snippet_settings:
          hsts:
            max_age: 63072000 # 2 years
            include_subdomains: true
            preload: true
          tls-baseline:
            resolvers:
              - "127.0.0.1" # local resolver (e.g. unbound, systemd-resolved)
        run_apache_httpd_modules_enabled:
          - "ssl"
          - "headers"
          - "rewrite"
          - "http2"
        run_apache_httpd_vhosts_config:
          - name: "example.com"
            enabled: true
            content: |
              <VirtualHost *:80>
                  ServerName example.com
                  Redirect permanent / https://example.com/
              </VirtualHost>
              <VirtualHost *:443>
                  ServerName example.com
                  DocumentRoot /var/www/example.com

                  SSLEngine on
                  SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
                  SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

                  Include snippets/vhost/headers-security.conf
                  Include snippets/vhost/headers-hsts.conf

                  <Directory /var/www/example.com>
                      Require all granted
                      Include snippets/directory/cache-static.conf
                  </Directory>
              </VirtualHost>

Installation with PHP-FPM (TCP backend) and custom main config directives:

---

- name: "Initialize the foundata.apache_httpd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.apache_httpd.run role"
      ansible.builtin.include_role:
        name: "foundata.apache_httpd.run"
      vars:
        run_apache_httpd_snippet_settings:
          php-fpm:
            type: "tcp"
            tcp_host: "127.0.0.1"
            tcp_port: 9000
        run_apache_httpd_main_config_block: |
          Timeout 120
          MaxKeepAliveRequests 200
        run_apache_httpd_modules_enabled:
          - "ssl"
          - "headers"
          - "rewrite"
          - "proxy"
          - "proxy_fcgi"
        run_apache_httpd_vhosts_config:
          - name: "app.example.com"
            enabled: true
            content: |
              <VirtualHost *:443>
                  ServerName app.example.com

                  SSLEngine on
                  SSLCertificateFile /etc/letsencrypt/live/app.example.com/fullchain.pem
                  SSLCertificateKeyFile /etc/letsencrypt/live/app.example.com/privkey.pem

                  Include snippets/vhost/headers-security.conf

                  DocumentRoot /var/www/app
                  DirectoryIndex index.php index.html

                  <Directory /var/www/app>
                      Require all granted
                      Include snippets/directory/php-fpm.conf
                  </Directory>
              </VirtualHost>

Uninstall:

---

- name: "Initialize the foundata.apache_httpd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.apache_httpd.run role"
      ansible.builtin.include_role:
        name: "foundata.apache_httpd.run"
      vars:
        run_apache_httpd_state: "absent"

On SELinux-enabled systems (RHEL, Fedora, AlmaLinux, CentOS Stream), Apache may need additional permissions for network connections (e.g. reverse proxying to upstream backends). Add this to your playbook before including the role:

- name: "Allow Apache to make network connections (SELinux)"
  ansible.posix.seboolean:
    name: "httpd_can_network_connect"
    state: true
    persistent: true
  when:
    - ansible_facts['selinux']['status'] | default('disabled') == 'enabled'

Supported tags

It might be useful and faster to only call parts of the role by using tags:

• run_apache_httpd_setup: Manage basic resources, such as packages or service users.
• run_apache_httpd_config: Manage settings, such as adapting or creating configuration files.
• run_apache_httpd_service: Manage services and daemons, such as running states and service boot configurations.

There are also tags usually not meant to be called directly but listed for the sake of completeness** and edge cases:

• run_apache_httpd_always, always: Tasks needed by the role itself for internal role setup and the Ansible environment.

Role variables

The following variables can be configured for this role:

run_apache_httpd_state

⇑ Back to ToC ⇑

Determines whether the managed resources should be present or absent.

present ensures that required components, such as software packages, are installed and configured.

absent reverts changes as much as possible, such as removing packages, deleting created users, stopping services, restoring modified settings, …

• Type: str
• Required: No
• Default: "present"
• Choices: present, absent

run_apache_httpd_autoupgrade

⇑ Back to ToC ⇑

If set to true, all managed packages will be upgraded during each Ansible run (e.g., when the package provider detects a newer version than the currently installed one).

• Type: bool
• Required: No
• Default: false

run_apache_httpd_service_state

⇑ Back to ToC ⇑

Defines the status of the service(s).

enabled: Service is running and will start automatically at boot.

disabled: Service is stopped and will not start automatically at boot.

running Service is running but will not start automatically at boot. This can be used to start a service on the first Ansible run without enabling it for boot.

unmanaged: Service will not start at boot, and Ansible will not manage its running state. This is primarily useful when services are monitored and managed by systems other than Ansible.

The singular form (service) is used for simplicity. However, the defined status applies to all services if multiple are being managed by this role.

• Type: str
• Required: No
• Default: "enabled"
• Choices: enabled, disabled, running, unmanaged

run_apache_httpd_mpm

⇑ Back to ToC ⇑

Selects the Multi-Processing Module (MPM) that determines how Apache handles concurrent connections.

event: A hybrid multi-process/multi-threaded model with an event-driven connection handling loop. Best for modern workloads, especially with keep-alive connections. Default on Debian and Red Hat.

worker: A multi-process/multi-threaded model where each child process serves requests with multiple threads. Good for high-traffic sites that need concurrency without the overhead of one-process-per-connection.

prefork: A non-threaded, pre-forking model where each child process handles one connection at a time. Required when using non-thread-safe libraries such as mod_php. Default on SUSE.

On Debian-like platforms the role enables the corresponding mpm_* module. On Red Hat it adjusts conf.modules.d/00-mpm.conf. On SUSE it sets the APACHE_MPM sysconfig variable.

• Type: str
• Required: No
• Default: "event"
• Choices: event, worker, prefork

run_apache_httpd_vhosts_default_manage

⇑ Back to ToC ⇑

Controls whether the role includes a hardened catch-all <VirtualHost> in the main configuration file.

When set to true, a default VirtualHost is rendered that listens on ports 80 and 443 with a minimal, restrictive configuration. This acts as a security fallback preventing unintended content exposure when requests arrive for unknown hostnames or manipulated SNI values.

Set to false if you prefer to define your own catch-all VirtualHost via run_apache_httpd_vhosts_config.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_main_config_block

⇑ Back to ToC ⇑

Additional Apache HTTPD configuration directives for the global (server-wide) context of the main configuration file.

The value is inserted verbatim into the rendered configuration file. Only directives valid in the Apache server config context should be used here (e.g., Timeout, KeepAlive, LogLevel, ServerAdmin).

Unlike NGINX (which separates events {} and http {} blocks), Apache uses a single flat global context for all server-wide directives. This variable covers all of them.

For VirtualHost definitions, use run_apache_httpd_vhosts_config instead.

• Type: str
• Required: No
• Default: ""

run_apache_httpd_main_config_baseline_manage

⇑ Back to ToC ⇑

Controls whether the role injects curated baseline directives into the main configuration file.

When set to true, the role provides sane defaults for the global context (e.g., ServerTokens ProductOnly, ServerSignature Off, TraceEnable Off, Timeout, KeepAlive, log formats, Listen directives, MIME types, and baseline security settings). These baseline directives are merged from internal defaults and platform-specific overrides.

Custom directives supplied via run_apache_httpd_main_config_block are rendered alongside the baseline. If set to false, no baseline directives are injected and you will likely need to provide essential directives yourself via run_apache_httpd_main_config_block to get a working service.

When true, the baseline also includes Listen 80 and a conditional Listen 443 (active when the ssl module is enabled). If you need custom listen ports, provide them via run_apache_httpd_main_config_block and set this to false, or add additional Listen directives alongside the baseline.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_vhosts_config

⇑ Back to ToC ⇑

List of VirtualHost definitions (sometimes called vHosts or sites) to manage. Each entry describes a VirtualHost as a dictionary holding its name, enablement state, and raw Apache configuration content.

For each entry, the role renders a config file at sites-available/<name>.conf (or vhosts-available/<name>.conf on SUSE-like platforms). If enabled: true, a symlink is created in sites-enabled/ (or vhosts.d/ on SUSE) pointing to the file in the available directory. The enabled directory is included by the role’s managed main configuration via IncludeOptional, so only symlinked VirtualHosts become active.

Setting enabled: false keeps the available file in place but removes the symlink, making it easy to temporarily disable a VirtualHost without losing its configuration.

Stale files no longer listed here are removed when run_apache_httpd_vhosts_delete_unmanaged is true (the default).

On non-Debian platforms where these directories do not exist by default, the role creates them and adds the necessary IncludeOptional directive to the managed main configuration file.

Example:

run_apache_httpd_vhosts_config:
  - name: "example.com"
    enabled: true
    content: |
      <VirtualHost *:80>
          ServerName example.com
          Redirect permanent / https://example.com/
      </VirtualHost>
      <VirtualHost *:443>
          ServerName example.com
          DocumentRoot /var/www/example.com

          SSLEngine on
          SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
          SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

          Include snippets/vhost/headers-security.conf
          Include snippets/vhost/headers-hsts.conf

          <Directory /var/www/example.com>
              Require all granted
          </Directory>
      </VirtualHost>
  - name: "api_backend"
    enabled: true
    content: |
      <VirtualHost *:443>
          ServerName api.example.com
          [...]
      </VirtualHost>

• Type: list
• Required: No
• Default: []

run_apache_httpd_vhosts_config['name']

⇑ Back to ToC ⇑

Identifier used to build the config filename (<name>.conf) below the available and enabled directories. Must be unique within run_apache_httpd_vhosts_config.

Allowed characters: a-z, A-Z, 0-9, dot (.), underscore (_), and hyphen (-). Any other character causes the role to fail with a validation error.

• Type: str
• Required: No

run_apache_httpd_vhosts_config['enabled']

⇑ Back to ToC ⇑

Controls whether the VirtualHost is active.

When true, a symlink is created in the enabled directory pointing to the corresponding file in the available directory, so Apache includes it. When false, the symlink is removed while the file in the available directory is kept in place, allowing the VirtualHost to be disabled without losing its configuration.

• Type: bool
• Required: No
• Default: false

run_apache_httpd_vhosts_config['content']

⇑ Back to ToC ⇑

Raw Apache configuration for the VirtualHost, inserted verbatim into the rendered file. Typically contains one or more <VirtualHost> blocks, and optionally supporting directives.

Snippets provided by this role can be pulled in with Include snippets/<context>/<name>.conf as needed.

• Type: str
• Required: No

run_apache_httpd_vhosts_delete_unmanaged

⇑ Back to ToC ⇑

Controls whether the role removes stale VirtualHost files that are not declared in run_apache_httpd_vhosts_config.

When set to true, any *.conf file or symlink found in the available and enabled directories whose name does not match an entry in run_apache_httpd_vhosts_config is deleted. This keeps the managed directories in sync with the declared list, treating run_apache_httpd_vhosts_config as the single source of truth.

When set to false, unknown files are left untouched. Use this if you manage additional VirtualHosts outside of this role and want to prevent accidental removal.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_modules_enabled

⇑ Back to ToC ⇑

List of Apache module short names to enable.

Module names correspond to what a2enmod accepts or the .so filename with the mod_ prefix and _module/.so suffix stripped (e.g. ssl from mod_ssl.so, proxy_fcgi from mod_proxy_fcgi.so).

Example:

run_apache_httpd_modules_enabled:
  - "ssl"
  - "headers"
  - "rewrite"
  - "proxy_fcgi"
  - "http2"
  - "brotli"

Only modules known to the platform-specific __run_apache_httpd_modules_map_resources mapping (see vars/main.yml and the platform overrides in vars/debian.yml, vars/redhat.yml, vars/suse.yml) are managed by this role. Modules not present in that mapping are silently skipped; if you need to enable such a module, add the necessary LoadModule configuration via your own tasks on top of this role.

For each listed and known module, the role installs required distribution packages automatically. On Debian, it creates symlinks from mods-available/ to mods-enabled/. On Red Hat, it ensures the package-provided config files in conf.modules.d/ are present. On SUSE, it adds the module to the APACHE_MODULES sysconfig variable.

• Type: list
• Required: No
• Default: []

run_apache_httpd_modules_disable_unmanaged

⇑ Back to ToC ⇑

Controls whether the role disables modules that are not declared in run_apache_httpd_modules_enabled.

When set to true, modules not listed in run_apache_httpd_modules_enabled are disabled. On Debian, symlinks in mods-enabled/ are removed. On SUSE, modules are removed from the APACHE_MODULES sysconfig variable. On Red Hat, package-provided config files in conf.modules.d/ are left in place (as they are managed by the package manager), but any role-created overrides are cleaned up.

When set to false, unknown modules are left untouched. Use this if you manage additional modules outside of this role and want to prevent accidental unavailability of modules loaded by default on your platform.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_snippets_manage

⇑ Back to ToC ⇑

Controls whether the role ships and manages its curated Apache config snippets (reusable, centrally maintained config blocks meant to be pulled into VirtualHost or Directory contexts via Include snippets/<name>.conf).

When set to true, the role ensures the snippet directories (snippets/global/, snippets/vhost/, snippets/directory/) exist and renders all snippet templates shipped with the role into them. Snippet content can be influenced via run_apache_httpd_snippet_settings.

When set to false, the role skips creating the snippet directories and does not render any snippet templates. Use this if you want to maintain your own snippet library entirely outside of this role. Cleanup of stale files is also gated by this variable: run_apache_httpd_snippets_delete_unmanaged only takes effect while snippets are managed.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_snippet_settings

⇑ Back to ToC ⇑

User-level overrides for the configuration snippets shipped by this role.

Each top-level key corresponds to a snippet name (e.g. hsts, php-fpm, tls-baseline). Values are dictionaries whose keys map to template variables used when rendering the snippet.

Settings provided here take highest priority, overriding both the internal defaults (see __run_apache_httpd_snippet_settings_defaults in vars/main.yml) and any platform-specific overrides. Only the keys you specify are overridden; all other settings keep their default values.

Example:

run_apache_httpd_snippet_settings:
  hsts:
    max_age: 63072000
    preload: true
  tls-baseline:
    resolvers:
      - "127.0.0.1"

• Type: dict
• Required: No
• Default: {}

run_apache_httpd_snippet_settings['hsts']

⇑ Back to ToC ⇑

Settings for the vhost/headers-hsts.conf snippet that renders the Strict-Transport-Security HTTP response header.

• Type: dict
• Required: No

run_apache_httpd_snippet_settings['hsts']['max_age']

⇑ Back to ToC ⇑

Duration in seconds that the browser should remember to only access the site via HTTPS. The default of 31536000 corresponds to one year, which is the minimum recommended by https://hstspreload.org/.

• Type: int
• Required: No
• Default: 31536000

run_apache_httpd_snippet_settings['hsts']['include_subdomains']

⇑ Back to ToC ⇑

Whether to extend the HSTS policy to all subdomains of the current domain. Required for HSTS preload list submission.

• Type: bool
• Required: No
• Default: true

run_apache_httpd_snippet_settings['hsts']['preload']

⇑ Back to ToC ⇑

Whether to add the preload directive, signalling to browser vendors that the domain should be included in the HSTS Preload List (hardcoded into browsers). This is practically irreversible; removal takes months.

• Type: bool
• Required: No
• Default: false

run_apache_httpd_snippet_settings['php-fpm']

⇑ Back to ToC ⇑

Settings for the directory/php-fpm.conf snippet that configures FastCGI proxying to a PHP-FPM backend. The snippet renders a <FilesMatch> block with the appropriate SetHandler directive for proxy:fcgi:// or proxy:unix:.

• Type: dict
• Required: No

run_apache_httpd_snippet_settings['php-fpm']['type']

⇑ Back to ToC ⇑

Connection method to the PHP-FPM backend. socket connects via a Unix domain socket (lower overhead, same-host only). tcp connects via TCP (allows remote backends).

• Type: str
• Required: No
• Default: "socket"
• Choices: socket, tcp

run_apache_httpd_snippet_settings['php-fpm']['socket']

⇑ Back to ToC ⇑

Absolute path to the PHP-FPM Unix socket. Only used when type is set to socket.

• Type: str
• Required: No
• Default: "/run/php/php-fpm.sock"

run_apache_httpd_snippet_settings['php-fpm']['tcp_host']

⇑ Back to ToC ⇑

Hostname or IP address of the PHP-FPM backend. Only used when type is set to tcp.

• Type: str
• Required: No
• Default: "127.0.0.1"

run_apache_httpd_snippet_settings['php-fpm']['tcp_port']

⇑ Back to ToC ⇑

TCP port of the PHP-FPM backend. Only used when type is set to tcp.

• Type: int
• Required: No
• Default: 9000

run_apache_httpd_snippet_settings['tls-baseline']

⇑ Back to ToC ⇑

Settings for the global/tls-baseline.conf snippet that provides TLS hardening following the Mozilla “Intermediate” profile.

• Type: dict
• Required: No

run_apache_httpd_snippet_settings['tls-baseline']['dhparam_path']

⇑ Back to ToC ⇑

Absolute path where the DH parameters file is deployed. The role ships RFC 7919 ffdhe3072 parameters and deploys them to this path automatically. Platform-specific vars files override this to match each distribution’s conventional TLS directory (e.g. /etc/pki/tls/certs/ on Red Hat).

• Type: str
• Required: No
• Default: "/etc/ssl/certs/dhparam_ffdhe3072.pem"

run_apache_httpd_snippet_settings['tls-baseline']['ecdh_curves']

⇑ Back to ToC ⇑

Colon-separated list of elliptic curves for ECDHE key exchange, passed to the SSLOpenSSLConfCmd Curves directive. The default includes the post-quantum hybrid X25519MLKEM768 (requires OpenSSL >= 3.5); platforms with older OpenSSL automatically fall back to a classical-only list via version-specific vars files.

• Type: str
• Required: No
• Default: "X25519MLKEM768:X25519:prime256v1:secp384r1"

run_apache_httpd_snippet_settings['tls-baseline']['resolvers']

⇑ Back to ToC ⇑

List of DNS resolver IP addresses used for OCSP stapling lookups. Using a local resolver (e.g. unbound, systemd-resolved at 127.0.0.1) is recommended for privacy and latency.

• Type: list
• Required: No
• List Elements: str

run_apache_httpd_snippet_settings['tls-baseline']['resolver_timeout']

⇑ Back to ToC ⇑

Timeout for DNS resolver queries used by OCSP stapling.

• Type: str
• Required: No
• Default: "3s"

run_apache_httpd_snippets_delete_unmanaged

⇑ Back to ToC ⇑

Controls whether the role removes snippet files below the snippet directories that are not managed by this role.

When set to true, any files in the snippet subdirectories (global/, vhost/, directory/) that were not rendered by the role’s snippet templates are deleted. This keeps the snippet directories clean and prevents stale or conflicting snippets.

When set to false, unknown files are left untouched. Use this if you maintain additional custom snippets outside of this role.

Only takes effect when run_apache_httpd_snippets_manage is true.

• Type: bool
• Required: No
• Default: false

Dependencies

See dependencies in meta/main.yml.

Compatibility

See min_ansible_version in meta/main.yml and __run_apache_httpd_supported_platforms in vars/main.yml.

External requirements

There are no special requirements not covered by Ansible itself.