nginx

This is an Ansible role for installing and managing nginx servers.

Requirements

This role installs nginx on Debian systems using APT, on Enterprise Linux systems using EPEL, or on SmartOS using pkgin. Other systems or installation methods are not supported.

Role Variables

All variables are optional.

General Configuration

• nginx_flavor (default: full): Specifies which nginx package to install. Choose based on your distribution. On RedHat-based distributions, you can use galaxy for "Galaxy nginx" or other values for EPEL nginx. For SmartOS installations, this value is not applicable. Generally, full is a safe default.
• nginx_servers: A list of server {} templates (virtual hosts).
• nginx_ssl_servers: Similar to nginx_servers, but only installed if SSL is configured.
• nginx_conf_http: Set options in the http {} section of nginx.conf. This is a dictionary where keys are nginx config options and values are their values.
• nginx_default_redirect_uri: Controls what URI the default virtual host should redirect to when using nginx from EPEL.
• nginx_enable_default_server (default: true): Enable or disable the default EPEL virtual host.
• nginx_supervisor: Run nginx under supervisor (requires additional supervisor settings).
• nginx_conf_dir (default: /etc/nginx): Directory for nginx configuration files.

SSL Configuration

The nginx_conf_ssl_certificate* variables control SSL usage. If not set, SSL won't be enabled.

• nginx_conf_ssl_certificate: Name of the SSL certificate file on the remote host.
• nginx_conf_ssl_certificate_key: Name of the SSL private key file on the remote host.
• nginx_conf_ssl_ciphers: List of ssl_ciphers for nginx.conf.
• nginx_conf_ssl_protocols: List of ssl_protocols for nginx.conf.

External SSL Configuration

• nginx_ssl_role (default: undefined): Role to run for setting up SSL. This is often needed after nginx is running but before SSL is used. It ensures that the SSL role runs at the correct time. See also nginx_ssl_servers.
• nginx_conf_ssl_certificate and nginx_conf_ssl_certificate_key: File names of the SSL certificate and private key.

Paths for these SSL certificate variables should be absolute.

Playbook SSL Configuration

If nginx_ssl_role is not set, you can use this role to copy your certificate and key from the playbook.

• nginx_ssl_conf_dir (default: <nginx_conf_dir>/ssl): Location to copy SSL certificates and files.
• nginx_ssl_src_dir (default: files/ssl): Source location of SSL certificates.
• sslkeys: Dictionary of private keys. Keys are filenames that match nginx_conf_ssl_certificate_key.
• nginx_conf_ssl_trusted_certificate: File name for trusted certificates used for OCSP stapling.

In this mode, the nginx_conf_ssl_certificate* variables should be relative paths, but they can also be absolute paths. If absolute, they will be searched in nginx_ssl_src_dir.

SELinux

When SELinux is enabled, some additional actions will take place:

• If certbot_well_known_root is set, it allows httpd_sys_content_t permissions on all subdirectories.
• nginx_selinux_allow_local_connections (default: false): Allows nginx to connect to localhost.

Dependencies

While not required, you can use geerlingguy.repo-epel to enable EPEL with Ansible.

Example Playbook

Here are a few examples based on how you get your certificates.

Local SSL Certificates

Install nginx with SSL certificates stored in the playbook:

- name: Install and configure nginx
  hosts: webservers
  vars:
    sslkeys:
      snakeoil_privatekey.pem: |
        -----BEGIN PRIVATE KEY-----
        MIIE...
        -----END PRIVATE KEY-----
    nginx_conf_ssl_certificate: snakeoil_cert.pem
    nginx_conf_ssl_certificate_key: snakeoil_privatekey.pem
    nginx_servers:
      - vhost1
      - vhost2
    nginx_conf_http:
      client_max_body_size: 1g
  roles:
    - galaxyproject.nginx

Let's Encrypt

Install nginx with SSL certificates from Let's Encrypt using Certbot:

- name: Install and configure nginx
  hosts: webservers
  vars:
    nginx_conf_ssl_certificate: /etc/ssl/certs/fullchain.pem
    nginx_conf_ssl_certificate_key: /etc/ssl/private/private.pem
    nginx_servers:
      - vhost1
      - vhost2
    nginx_ssl_servers:
      - vhost1_ssl
      - vhost2_ssl
    nginx_conf_http:
      client_max_body_size: 1g
    nginx_ssl_role: usegalaxy_eu.certbot
    certbot_auth_method: --webroot
    certbot_domains:
      - vhost1.example.org
      - vhost2.example.org
    certbot_admin_email: [email protected]
    certbot_agree_tos: --agree-tos
    certbot_well_known_root: /var/www/_well-known_root
    certbot_post_renewal: |
      systemctl restart nginx || true
  roles:
    - galaxyproject.nginx

Self-Signed Certificates

Install nginx and use a generated self-signed SSL certificate (great for testing):

- name: Install and configure nginx
  hosts: webservers
  vars:
    nginx_servers:
      - vhost1
      - vhost2
    nginx_ssl_servers:
      - vhost1_ssl
      - vhost2_ssl
    nginx_conf_http:
      client_max_body_size: 1g
    nginx_ssl_role: galaxyproject.self_signed_certs
    openssl_domains:
      - vhost1.example.org
      - vhost2.example.org
    nginx_conf_ssl_certificate_key: /etc/ssl/private/{{ openssl_domains[0] }}.pem
    nginx_conf_ssl_certificate: /etc/ssl/certs/{{ openssl_domains[0] }}.crt
  roles:
    - galaxyproject.nginx

License

Academic Free License ("AFL") v. 3.0

Author Information

• Nate Coraor
• Helena Rasche