Getting started

Security defaults

Following Mozilla intermediate level recommendations, this role configures nginx with only TLSv1.2 and TLSv1.3 enabled. All modern browsers are supported with the default cipher suite. If you need support for older clients, see nginx_default_ssl_ciphers and nginx_default_tls_protocols. To follow modern level recommendation, enable only TLSv1.3 in nginx_default_tls_protocols. Note that there is still limited client support for TLSv1.3.

Only one curve (ECC) is enabled by default: secp256r1. While the NCSC-NL TLS Guidelines recommend three other curves, these are not supported by openssl (in Debian Buster, as checked on 2020-08-06).

If TLSv1.3 is the only protocol in use, clients are allowed to choose ciphers, because they know best if they have support for hardware-accelerated AES. If TLSv1.2 or lower is used, server ciphers are preferred, because those protocols allow downgrade attacks.

No dhparam is set if the only protocol is TLSv1.3, because that protocol uses Ephemeral Diffie-Hellman key exchange, which employs one-time keys for the current network session. Omitting the option is purely cosmetic, resulting in a cleaner configuration file.

If HTTP Strict Transport Security (see also: HSTS Cheat Sheet) is enabled, the default age is 2 years.

Example inventory

To manage Nginx on a given host or set of hosts, they need to be added to the [debops_service_nginx] Ansible group in the inventory:

[debops_service_nginx]
hostname

Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.nginx role:

---

- name: Manage nginx webserver
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_nginx' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::nginx' ]
      keyring__dependent_apt_keys:
        - '{{ nginx__keyring__dependent_apt_keys }}'

    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ nginx__apt_preferences__dependent_list }}'

    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'

    - role: python
      tags: [ 'role::python', 'skip::python' ]
      python__dependent_packages3:
        - '{{ nginx__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ nginx__python__dependent_packages2 }}'

    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::nginx

Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

type::dependency

This tag specifies which tasks are defined in role dependencies. You can use this to omit them using --skip-tags parameter.

depend-of::nginx

Execute all debops.nginx role dependencies in its context.

depend::secret:nginx

Run debops.secret dependent role in debops.nginx context.

depend::apt_preferences:nginx

Run debops.apt_preferences dependent role in debops.nginx context.

depend::ferm:nginx

Run debops.ferm dependent role in debops.nginx context.

role::nginx:servers

Configure nginx servers configuration as configured by the nginx_servers variable.