Use nginx role with custom nginx.conf support

inventories/z9/host_vars/esphome.yml

@@ -1,5 +1,5 @@
 esphome__version: "2023.3.2"
-nginx__configs:
+nginx__version_spec: ""
+nginx__configurations:
   - name: esphome
     content: "{{ lookup('ansible.builtin.file', 'configs/esphome/nginx/esphome.conf') }}"
-nginx__enable_https_redirect: true

inventories/z9/host_vars/light.yml

@@ -48,8 +48,8 @@ ola__configs:
   - name: ola-usbserial
     content: "{{ lookup('ansible.builtin.file', 'configs/light/ola/ola-usbserial.conf') }}"
 foobazdmx__art_net_host: localhost
-nginx__enable_https_redirect: false
-nginx__configs:
+nginx__version_spec: ""
+nginx__configurations:
   - name: light.ccchh.net
     content: "{{ lookup('ansible.builtin.file', 'configs/light/nginx/light.ccchh.net.conf') }}"
   - name: http_handler

inventories/z9/host_vars/public-reverse-proxy.yaml

@@ -1,4 +1,5 @@
-nginx__enable_https_redirect: false
-nginx__configs:
+nginx__version_spec: ""
+nginx__deploy_redirect_conf: false
+nginx__configurations:
   - name: acme_challenge
     content: "{{ lookup('ansible.builtin.file', 'configs/public-reverse-proxy/nginx/acme_challenge.conf') }}"

inventories/z9/host_vars/zigbee2mqtt.yml

@@ -10,7 +10,7 @@ zigbee2mqtt__network_key: !vault |
           30303031306635313764323434333465353465366633376432326563666264386431623335613636
           64643434666433363865
 zigbee2mqtt__config: "{{ lookup('ansible.builtin.template', 'configs/zigbee2mqtt/zigbee2mqtt/configuration.yaml.j2') }}"
-nginx__configs:
+nginx__version_spec: ""
+nginx__configurations:
   - name: zigbee2mqtt
     content: "{{ lookup('ansible.builtin.file', 'configs/zigbee2mqtt/nginx/zigbee2mqtt.conf') }}"
-nginx__enable_https_redirect: true

playbooks/roles/nginx/README.md

@@ -0,0 +1,55 @@
+# Role `nginx`
+
+Makes sure the `nginx` package is installed from the NGINX repos on the specified hosts.
+Also makes sure a desirable baseline of NGINX configs is deployed on the specified hosts.
+For the NGINX site configurations the config template below can be used.
+
+## Entry Points
+
+The entry points available for external use are:
+
+- `main`
+
+## Supported Distributions
+
+The following distributions are supported:
+
+- Debian 11
+
+## Required Arguments
+
+For the required arguments look at the [`argument_specs.yaml`](./meta/argument_specs.yaml).
+
+## Updates
+
+This role updates NGINX to the latest version covered by the provided version spec., if needed.
+
+## `hosts`
+
+The `hosts` for this role need to be the machines, for which you want to make sure the `nginx` package is installed from the NGINX repos and a desirable baseline of NGINX configs is deployed.
+
+## Config Template
+
+Here's a config template, which can be used for new NGINX site configs, which you can supply to this role using the `nginx__configurations` argument.
+Just replace the placeholder values with real ones and extend and edit it as needed.
+
+```
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+server {
+    listen 443 ssl http2;
+    #listen [::]:443 ssl http2;
+    server_name replace_me;
+
+    ssl_certificate /path/to/signed_cert_plus_intermediates;
+    ssl_certificate_key /path/to/private_key;
+    # verify chain of trust of OCSP response using Root CA and Intermediate certs
+    ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
+
+    # HSTS (ngx_http_headers_module is required) (63072000 seconds)
+    add_header Strict-Transport-Security "max-age=63072000" always;
+
+    # replace with the IP address of your resolver
+    resolver 127.0.0.1;
+}
+```

playbooks/roles/nginx/defaults/main.yaml

@@ -0,0 +1,5 @@
+nginx__deploy_redirect_conf: true
+nginx__deploy_tls_conf: true
+nginx__configurations: [ ]
+nginx__use_custom_nginx_conf: false
+nginx__custom_nginx_conf: ""

playbooks/roles/nginx/files/redirect.conf

@@ -0,0 +1,10 @@
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+server {
+    listen 80 default_server;
+    #listen [::]:80 default_server;
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}

playbooks/roles/nginx/files/tls.conf

@@ -0,0 +1,19 @@
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+
+
+ssl_session_timeout 1d;
+ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
+ssl_session_tickets off;
+
+# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
+ssl_dhparam /etc/nginx-mozilla-dhparam;
+
+# intermediate configuration
+ssl_protocols TLSv1.2 TLSv1.3;
+ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
+ssl_prefer_server_ciphers off;
+
+# OCSP stapling
+ssl_stapling on;
+ssl_stapling_verify on;

playbooks/roles/nginx/handlers/main.yaml

@@ -0,0 +1,10 @@
+- name: Restart `nginx.service`
+  ansible.builtin.systemd:
+    name: nginx.service
+    state: restarted
+  become: true
+
+- name: apt-get update
+  ansible.builtin.apt:
+    update_cache: true
+  become: true

playbooks/roles/nginx/handlers/main.yml

@@ -1,4 +0,0 @@
-- name: Reload nginx
-  ansible.builtin.systemd:
-    service: nginx
-    state: reloaded

playbooks/roles/nginx/meta/argument_specs.yaml

@@ -0,0 +1,64 @@
+argument_specs:
+  main:
+    options:
+      nginx__version_spec:
+        description: >-
+          The version specification to use for installing the `nginx` package. The
+          provided version specification will be used like the following: `nginx={{
+          nginx__version_spec }}*`. This makes it possible to e.g. specify
+          until a minor version (like `1.3.`) and then have patch versions be
+          installed automatically (like `1.3.1` and so on).
+        type: str
+        required: true
+      nginx__deploy_redirect_conf:
+        description: >-
+          Whether or not to deploy a `redirect.conf` to
+          `/etc/nginx/conf.d/redirect.conf`.
+        type: bool
+        required: false
+        default: true
+      nginx__deploy_tls_conf:
+        description: >-
+          Whether or not to deploy a `tls.conf` to `/etc/nginx/conf.d/tls.conf`.
+        type: bool
+        required: false
+        default: true
+      nginx__configurations:
+        description: A list of nginx configurations.
+        type: list
+        elements: dict
+        required: false
+        default: [ ]
+        options:
+          name:
+            description: >-
+              The name of the configuration file, where the configuration should
+              be deployed to. The file will be placed under `/etc/nginx/conf.d/`
+              and `.conf` will be appended to the given name. So in the end the
+              path will be like this: `/etc/nginx/conf.d/\{\{ name \}\}.conf`.
+              Note that the names `tls` and `redirect` aren't allowed.
+            type: str
+            required: true
+          content:
+            description: The content of the configuration.
+            type: str
+            required: true
+      nginx__use_custom_nginx_conf:
+        description: >-
+          Whether or not to use a custom `/etc/nginx/nginx.conf`. If set to
+          true, you must provide a custom `nginx.conf` via
+          `nginx__custom_nginx_conf`.
+        type: bool
+        required: false
+        default: false
+      nginx__custom_nginx_conf:
+        description: >-
+          The value for a `nginx.conf` to be placed at `/etc/nginx/nginx.conf`.
+          You must set `nginx__use_custom_nginx_conf` to true for this value to
+          be used.
+          You should probably make sure that your custom `nginx.conf` still
+          includes `/etc/nginx/conf.d/*.conf` so that the configuration provided
+          using `nginx__configurations` still work.
+        type: str
+        required: false
+        default: ""

playbooks/roles/nginx/meta/argument_specs.yml

@@ -1,20 +0,0 @@
----
-argument_specs:
-  main:
-    options:
-      nginx__enable_https_redirect:
-        description: Redirect HTTP traffic to HTTPS
-        type: bool
-        required: false
-      nginx__configs:
-        description: Configuration files to add to /etc/nginx/conf.d/
-        type: list
-        elements: dict
-        required: false
-        options:
-          name:
-            description: Name of the config file without file extension
-            type: str
-          content:
-            description: Content of the config file
-            type: str

playbooks/roles/nginx/meta/main.yaml

@@ -0,0 +1,8 @@
+---
+dependencies:
+  - role: distribution_check
+    vars:
+      distribution_check__supported_distributions:
+        - name: Debian
+          versions:
+            - "11"

playbooks/roles/nginx/meta/main.yml

@@ -1,16 +0,0 @@
-dependencies:
-  - role: distribution_check
-    vars:
-      distribution_check__supported_distributions:
-        - name: Debian
-          versions:
-            - "10"
-            - "11"
-  - role: add_apt_repository
-    vars:
-      add_apt_repository__https_repo: false
-      add_apt_repository__keyring_url: https://nginx.org/keys/nginx_signing.key
-      add_apt_repository__keyring_path: /usr/share/keyrings/nginx-archive-keyring.gpg
-      add_apt_repository__repo: deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg]
-         http://nginx.org/packages/{{ ansible_facts.distribution | lower }} {{ ansible_facts.lsb.codename }} nginx
-      add_apt_repository__filename: nginx.list

playbooks/roles/nginx/tasks/main.yaml

@@ -0,0 +1,19 @@
+- name: make sure nginx configuration names are valid
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: make_sure_nginx_configuration_names_are_valid
+
+- name: make sure NGINX repos are setup
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/repo_setup
+
+- name: make sure NGINX is installed
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/nginx_install
+
+- name: make sure desirable NGINX configs are deployed
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/config_deploy

playbooks/roles/nginx/tasks/main.yml

@@ -1,45 +0,0 @@
----
-- name: Setup up repository pinning
-  ansible.builtin.template:
-    src: 99nginx.j2
-    dest: /etc/apt/preferences.d/99nginx
-    mode: "0644"
-- name: Install nginx
-  ansible.builtin.apt:
-    update_cache: true
-    name: nginx
-    state: present
-- name: Delete default.conf
-  ansible.builtin.file:
-    path: /etc/nginx/conf.d/default.conf
-    state: absent
-  when: nginx__configs
-- name: Create nginx redirect.conf
-  ansible.builtin.template:
-    src: redirect.conf.j2
-    dest: /etc/nginx/conf.d/redirect.conf
-    mode: "0644"
-  when: nginx__enable_https_redirect is defined and nginx__enable_https_redirect
-- name: Create nginx tls.conf
-  ansible.builtin.template:
-    src: tls.conf.j2
-    dest: /etc/nginx/conf.d/tls.conf
-    mode: "0644"
-- name: Download dhparam file
-  ansible.builtin.get_url:
-    url: https://ssl-config.mozilla.org/ffdhe2048.txt
-    dest: /etc/nginx/dhparam.pem
-    mode: "0644"
-- name: Add user specified configs
-  ansible.builtin.copy:
-    content: "{{ item.content }}"
-    dest: /etc/nginx/conf.d/{{ item.name }}.conf
-    mode: "0644"
-  loop: "{{ nginx__configs }}"
-  notify: Reload nginx
-- name: Enable and start systemd service
-  ansible.builtin.systemd:
-    name: nginx.service
-    daemon_reload: true
-    enabled: true
-    state: started

playbooks/roles/nginx/tasks/main/config_deploy.yaml

@@ -0,0 +1,130 @@
+- name: check, if a save of a previous `nginx.conf` is present
+  ansible.builtin.stat:
+    path: /etc/nginx/nginx.conf.ansiblesave
+  register: nginx__nginx_conf_ansiblesave_stat_result
+
+- name: handle the case, where a custom `nginx.conf` is to be used
+  when: nginx__use_custom_nginx_conf
+  block:
+    - name: when no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
+      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists == false
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/nginx.conf.ansiblesave
+        mode: 0644
+        owner: root
+        group: root
+        remote_src: true
+        src: /etc/nginx/nginx.conf
+      become: true
+
+    - name: deploy the custom `nginx.conf`
+      ansible.builtin.copy:
+        content: "{{ nginx__custom_nginx_conf }}"
+        dest: "/etc/nginx/nginx.conf"
+        mode: 0644
+        owner: root
+        group: root
+      become: true
+
+- name: handle the case, where no custom `nginx.conf` is to be used
+  when: not nginx__use_custom_nginx_conf
+  block:
+    - name: when a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
+      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/nginx.conf
+        mode: 0644
+        owner: root
+        group: root
+        remote_src: true
+        src: /etc/nginx/nginx.conf.ansiblesave
+      become: true
+
+    - name: delete the `nginx.conf.ansiblesave`, if it is present
+      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      ansible.builtin.file:
+        path: /etc/nginx/nginx.conf.ansiblesave
+        state: absent
+      become: true
+
+- name: make sure mozilla dhparam is deployed
+  ansible.builtin.get_url:
+    force: true
+    dest: /etc/nginx-mozilla-dhparam
+    mode: 0644
+    url: https://ssl-config.mozilla.org/ffdhe2048.txt
+  become: true
+  notify: Restart `nginx.service`
+
+- name: set `nginx__config_files_to_exist` fact initially to an empty list
+  ansible.builtin.set_fact:
+    nginx__config_files_to_exist: [ ]
+
+- name: handle the case, where tls.conf should be deployed
+  when: nginx__deploy_tls_conf
+  block:
+    - name: make sure tls.conf is deployed
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/conf.d/tls.conf
+        mode: 0644
+        owner: root
+        group: root
+        src: tls.conf
+      become: true
+      notify: Restart `nginx.service`
+
+    - name: add tls.conf to nginx__config_files_to_exist
+      ansible.builtin.set_fact:
+        nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'tls.conf' ] }}"  # noqa: jinja[spacing]
+
+- name: handle the case, where redirect.conf should be deployed
+  when: nginx__deploy_redirect_conf
+  block:
+    - name: make sure redirect.conf is deployed
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/conf.d/redirect.conf
+        mode: 0644
+        owner: root
+        group: root
+        src: redirect.conf
+      become: true
+      notify: Restart `nginx.service`
+
+    - name: add redirect.conf to nginx__config_files_to_exist
+      ansible.builtin.set_fact:
+        nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'redirect.conf' ] }}"  # noqa: jinja[spacing]
+
+- name: make sure all given configuration files are deployed
+  ansible.builtin.copy:
+    content: "{{ item.content }}"
+    dest: "/etc/nginx/conf.d/{{ item.name }}.conf"
+    mode: 0644
+    owner: root
+    group: root
+  become: true
+  loop: "{{ nginx__configurations }}"
+  notify: Restart `nginx.service`
+
+- name: add names plus suffix from `nginx__configurations` to `nginx__config_files_to_exist` fact
+  ansible.builtin.set_fact:
+    nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ item.name + '.conf' ] }}"  # noqa: jinja[spacing]
+  loop: "{{ nginx__configurations }}"
+
+- name: find configuration files to remove
+  ansible.builtin.find:
+    paths: /etc/nginx/conf.d/
+    recurse: false
+    excludes: "{{ nginx__config_files_to_exist }}"
+  register: nginx__config_files_to_remove
+
+- name: remove all configuration file, which should be removed
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: absent
+  become: true
+  loop: "{{ nginx__config_files_to_remove.files }}"
+  notify: Restart `nginx.service`

playbooks/roles/nginx/tasks/main/nginx_install.yaml

@@ -0,0 +1,13 @@
+- name: make sure the `nginx` package is installed
+  ansible.builtin.apt:
+    name: nginx={{ nginx__version_spec }}*
+    state: present
+    allow_change_held_packages: true
+    update_cache: true
+  become: true
+
+- name: apt-mark hold `nginx`
+  ansible.builtin.dpkg_selections:
+    name: nginx
+    selection: hold
+  become: true

playbooks/roles/nginx/tasks/main/repo_setup.yaml

@@ -0,0 +1,30 @@
+- name: make sure `gnupg` package is installed
+  ansible.builtin.apt:
+    name: gnupg
+    state: present
+    update_cache: true
+  become: true
+
+- name: make sure NGINX signing key is added
+  ansible.builtin.apt_key:
+    url: https://nginx.org/keys/nginx_signing.key
+    state: present
+  become: true
+  notify: apt-get update
+
+- name: make sure NGINX APT repository is added
+  ansible.builtin.apt_repository:
+    repo: deb https://nginx.org/packages/debian/ bullseye nginx
+    state: present
+  become: true
+  notify: apt-get update
+
+- name: make sure NGINX APT source repository is added
+  ansible.builtin.apt_repository:
+    repo: deb-src https://nginx.org/packages/debian/ bullseye nginx
+    state: present
+  become: true
+  notify: apt-get update
+
+- name: Flush handlers to make sure "apt-get update" handler runs, if needed
+  ansible.builtin.meta: flush_handlers

playbooks/roles/nginx/tasks/make_sure_nginx_configuration_names_are_valid.yaml

@@ -0,0 +1,6 @@
+- name: make sure nginx configuration names are valid
+  ansible.builtin.fail:
+    msg: "You used the following name: `{{ item.name }}`. Please make sure to not use the following names: `tls`, `redirect`."
+  when: item.name == "tls"
+        or item.name == "redirect"
+  loop: "{{ nginx__configurations }}"

playbooks/roles/nginx/templates/99nginx.j2

@@ -1,4 +0,0 @@
-Package: *
-Pin: origin nginx.org
-Pin: release o=nginx
-Pin-Priority: 900

playbooks/roles/nginx/templates/redirect.conf.j2

@@ -1,9 +0,0 @@
-server {
-    listen 80 default_server;
-    listen [::]:80 default_server;
-    server_name _;
-
-    location / {
-        return 301 https://$host$request_uri;
-    }
-}

playbooks/roles/nginx/templates/tls.conf.j2

@@ -1,9 +0,0 @@
-ssl_protocols TLSv1.2 TLSv1.3;
-ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
-ssl_prefer_server_ciphers off;
-ssl_dhparam /etc/nginx/dhparam.pem;
-ssl_session_timeout 1d;
-ssl_session_cache shared:MozSSL:10m;
-ssl_session_tickets off;
-ssl_stapling on;
-ssl_stapling_verify on;