Ansible collection: foundata.nginx

Quelltext

Veröffentlichungen (Releases)

Dokumentation

Probleme (Issues)

Lizenzierung

Primäre Lizenz: GPL-3.0-or-later

Sonstiges

Spenden: Buy us a coffee
Projektbetreuer: foundata
Status: Stabil

Die Ansible-Collection foundata.nginx stellt Ressourcen zur Verwaltung und Nutzung von NGINX, einem HTTP-Webserver, Reverse-Proxy, Cache und Load Balancer.

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.

Dieses Projekt nutzt eine andere Arbeitssprache als Deutsch. Der folgende Abschnitt wurde automatisch aus der README-Datei generiert und liegt daher nur in der Originalsprache vor.

Ansible role: `foundata.nginx.run`

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

Features

Main features:

Site management via sites-available/ and sites-enabled/ with optional cleanup of unmanaged files.
Dynamic module management: enable modules by name, the role installs packages and creates load_module configs automatically with cross-platform support.
Layered configuration merge: production-ready internal defaults (see __run_nginx_http_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 site configs:
- http/tls-baseline.conf – TLS/SSL hardening (see above).
- server/headers-security.conf – security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy).
- server/headers-hsts.conf – HTTP Strict Transport Security with configurable max-age, includeSubDomains, and preload.
- location/cache-static.conf – long-lived caching for static assets (Cache-Control: public, immutable).
- location/php-fpm.conf – FastCGI proxy for PHP-FPM (Unix socket or TCP).
Hardened catch-all default_server that returns HTTP 444 / rejects unknown TLS handshakes, preventing unintended content exposure for unknown hostnames.

Example playbooks, using this role

Installation with automatic upgrade:

---

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

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

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

---

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

    - name: "Trigger invocation of the foundata.nginx.run role"
      ansible.builtin.include_role:
        name: "foundata.nginx.run"
      vars:
        run_nginx_autoupgrade: true
        run_nginx_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_nginx_sites_config:
          - name: "example.com"
            enabled: true
            content: |
              server {
                  listen 80;
                  listen [::]:80;
                  server_name example.com;
                  return 301 https://$host$request_uri;
              }
              server {
                  listen 443 ssl;
                  listen [::]:443 ssl;
                  server_name example.com;

                  include snippets/http/tls-baseline.conf;
                  include snippets/server/headers-security.conf;
                  include snippets/server/headers-hsts.conf;

                  # Cert paths (all other TLS settings inherited from tls-baseline.conf)
                  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
                  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

                  root /var/www/example.com;
                  index index.html;

                  location / {
                      try_files $uri $uri/ =404;
                  }

                  location ~* \.(css|js|svg|png|jpg|gif|ico|woff2?)$ {
                      include snippets/location/cache-static.conf;
                  }
              }
        run_nginx_modules_enabled:
          - "http_headers_more_filter"

Installation with PHP-FPM (TCP backend) and a custom events config:

---

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

    - name: "Trigger invocation of the foundata.nginx.run role"
      ansible.builtin.include_role:
        name: "foundata.nginx.run"
      vars:
        run_nginx_snippet_settings:
          php-fpm:
            type: "tcp"
            tcp_host: "127.0.0.1"
            tcp_port: 9000
        run_nginx_events_config_block: |
          worker_connections 4096;
        run_nginx_sites_config:
          - name: "app.example.com"
            enabled: true
            content: |
              server {
                  listen 443 ssl;
                  listen [::]:443 ssl;
                  server_name app.example.com;

                  include snippets/http/tls-baseline.conf;
                  include snippets/server/headers-security.conf;

                  # Cert paths (all other TLS settings inherited from tls-baseline.conf)
                  ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
                  ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

                  root /var/www/app;
                  index index.php index.html;

                  location / {
                      try_files $uri $uri/ /index.php?$query_string;
                  }

                  location ~ \.php$ {
                      include snippets/location/php-fpm.conf;
                  }
              }

Uninstall:

---

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

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

On SELinux-enabled systems (RHEL, Fedora, AlmaLinux, CentOS Stream), NGINX 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 NGINX 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_nginx_setup: Manage basic resources, such as packages or service users.
run_nginx_config: Manage settings, such as adapting or creating configuration files.
run_nginx_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_nginx_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:

Variable	Type	Required	Default	Description (abstract)
`run_nginx_state`	`str`	No	`"present"`	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 …
`run_nginx_autoupgrade`	`bool`	No	`false`	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).
`run_nginx_service_state`	`str`	No	`"enabled"`	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 …
`run_nginx_main_config_block`	`str`	No	`""`	Additional NGINX configuration directives for the main (top-level) context of `nginx.conf`, placed outside of any block such as `events {}` or `http {}`. The value is inserted verbatim into the rendered configuration file. Only directives …
`run_nginx_events_config_block`	`str`	No	`""`	Additional NGINX configuration directives for the `events {}` block in the main configuration file (`nginx.conf`). The value is inserted verbatim inside the `events {}` block. Do not include the `events {` and `}` delimiters themselves - only …
`run_nginx_http_config_block`	`str`	No	`""`	Additional NGINX configuration directives for the `http {}` block in the main configuration file (`nginx.conf`). The value is inserted verbatim inside the `http {}` block. Do not include the `http {` and `}` delimiters themselves - only the …
`run_nginx_main_config_baseline_manage`	`bool`	No	`true`	Controls whether the role injects curated baseline directives into the main (top-level) context of the main configuration file (`nginx.conf`). When set to `true`, the role provides sane defaults for the main context (e.g., `worker_processes`, …
`run_nginx_events_config_baseline_manage`	`bool`	No	`true`	Controls whether the role injects curated baseline directives into the `events {}` block of the main configuration file (`nginx.conf`). When set to `true`, the role provides sane defaults for the events context (e.g., `worker_connections`). …
`run_nginx_http_config_baseline_manage`	`bool`	No	`true`	Controls whether the role injects curated baseline directives into the `http {}` block of the main configuration file (`nginx.conf`). When set to `true`, the role provides sane defaults for the HTTP context (e.g., `sendfile`, `tcp_nopush`, …
`run_nginx_sites_config`	`list`	No	`[]`	List of site definitions (sometimes called vHosts) to manage. Each entry describes a site as a dictionary holding its name, enablement state, and raw NGINX configuration content. For each entry, the role renders a config file at …
`run_nginx_sites_delete_unmanaged`	`bool`	No	`true`	Controls whether the role removes stale site files that are not declared in `run_nginx_sites_config`. When set to `true`, any `*.conf` file or symlink found in `/etc/nginx/sites-available/` or `/etc/nginx/sites-enabled/` whose name does not …
`run_nginx_sites_defaultserver_manage`	`bool`	No	`true`	Controls whether the role includes a hardened catch-all `server {}` block in the `http {}` section of the main configuration file (`nginx.conf`). When set to `true`, a default server is rendered that listens on ports 80 and 443 with …
`run_nginx_modules_enabled`	`list`	No	`[]`	List of dynamic NGINX module names to enable at runtime. Module names follow the canonical `.so` filename with the `ngx_` prefix and `_module` suffix stripped. The general pattern is `_` (e.g. `http_perl` from `ngx_http_perl_module.so`). See …
`run_nginx_modules_disable_unmanaged`	`bool`	No	`true`	Controls whether the role removes dynamic module symlinks that are not declared in `run_nginx_modules_enabled`. When set to `true`, any `*.conf` file or symlink found in `/etc/nginx/modules-enabled/` whose name does not match an entry in …
`run_nginx_snippets_manage`	`bool`	No	`true`	Controls whether the role ships and manages its curated NGINX config snippets (reusable, centrally maintained config blocks meant to be pulled into `server {}` / `location {}` blocks via `include snippets/.conf;`). When set to `true`, the role …
`run_nginx_snippet_settings`	`dict`	No	`{}`	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 …
`run_nginx_snippets_delete_unmanaged`	`bool`	No	`false`	Controls whether the role removes snippet files below `/etc/nginx/snippets/` that are not managed by this role. When set to `true`, any files in the snippet subdirectories (`http/`, `server/`, `location/`) that were not rendered by the role’s …