ansible-role-nginx/README.md

Ansible NGINX Role
==================

[![Ansible Galaxy](https://img.shields.io/badge/galaxy-nginxinc.nginx-5bbdbf.svg)](https://galaxy.ansible.com/nginxinc/nginx)
[![Build Status](https://travis-ci.org/nginxinc/ansible-role-nginx.svg?branch=master)](https://travis-ci.org/nginxinc/ansible-role-nginx)

This role installs NGINX Open Source, NGINX Plus, the NGINX Amplify agent, the NGINX Controller agent, or NGINX Unit on your target host.

**Note:** This role is still in active development. There may be unidentified issues and the role variables may change as development continues.

Requirements
------------

**Ansible**

This role was developed and tested with [maintained](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status) versions of
Ansible. Backwards compatibility is not guaranteed.

**Ansible Galaxy**

Use `ansible-galaxy install nginxinc.nginx` to install the role on your system.

It supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline) and [NGINX Plus](https://www.nginx.com/products/technical-specs/):

**NGINX Open Source**

```yaml
Alpine:
  versions:
    - 3.8
    - 3.9
    - 3.10
CentOS:
  versions:
    - 6
    - 7.4+
    - 8
Debian:
  versions:
    - stretch
    - buster
FreeBSD:
  versions:
    - 11.2+
    - 12
RedHat:
  versions:
    - 6
    - 7.4+
    - 8
SUSE/SLES:
  versions:
    - 12
    - 15
Ubuntu:
  versions:
    - xenial
    - bionic
```

**NGINX Plus**

```yaml
Alpine:
  versions:
    - 3.8
    - 3.9
    - 3.10
Amazon Linux:
  versions:
    - 2018.03
Amazon Linux 2:
  versions:
    - LTS
CentOS:
  versions:
    - 6.5+
    - 7.4+
    - 8
Debian:
  versions:
    - stretch
    - buster
FreeBSD:
  versions:
    - 11.2+
    - 12
Oracle Linux:
  versions:
    - 6.5+
    - 7.4+
RedHat:
  versions:
    - 6.5+
    - 7.4+
    - 8
SUSE/SLES:
  versions:
    - 12
    - 15
Ubuntu:
  versions:
    - xenial
    - bionic
```

**NGINX Amplify Agent**

```yaml
Amazon Linux:
  versions:
    - 2017.09
CentOS:
  versions:
    - 6
    - 7
Debian:
  versions:
    - jessie
    - stretch
Ubuntu:
  versions:
    - trusty
    - xenial
    - bionic
RedHat:
  versions:
    - 6
    - 7
```

**NGINX Controller Agent**

```yaml
Amazon Linux:
  versions:
    - 2017.09
Amazon Linux 2:
  versions:
    - LTS
CentOS:
  versions:
    - 6
    - 7
Debian:
  versions:
    - jessie
    - stretch
Ubuntu:
  versions:
    - xenial
    - bionic
RedHat:
  versions:
    - 6
    - 7
```

**NGINX Unit**

```yaml
CentOS:
  versions:
    - 6
    - 7
RedHat:
  versions:
    - 6
    - 7
Debian:
  versions:
    - jessie
    - stretch
    - buster
Ubuntu:
  versions:
    - xenial
    - bionic
Amazon Linux:
  versions:
    - 2018.03
Amazon Linux 2:
  versions:
    - 2
FreeBSD:
  versions:
    - 10
    - 11
```

Role Variables
--------------

This role has multiple variables. The defaults for all these variables are the following:

```yaml
---
# Install NGINX.
# Default is true.
nginx_enable: true

# Start NGINX service.
# Default is true.
nginx_start: true

# Print NGINX configuration file to terminal after executing playbook.
nginx_debug_output: false

# Supported systems
nginx_linux_families: ['Alpine', 'Debian', 'RedHat', 'Suse']
nginx_bsd_systems: ['FreeBSD', 'NetBSD', 'OpenBSD', 'DragonFlyBSD', 'HardenedBSD']

# Specify which type of NGINX you want to install.
# Options are 'opensource' or 'plus'.
# Default is 'opensource'.
nginx_type: opensource
# Specify which version of NGINX you want to install.
# Default is empty.
# nginx_version: =19-1~bionic

# Specify repository origin for NGINX Open Source.
# Options are 'nginx_repository' or 'os_repository'.
# Only works if 'nginx_type' is set to 'opensource'.
# Default is nginx_repository.
nginx_install_from: nginx_repository

# Choose where to fetch the NGINX signing key from.
# Default is the official NGINX signing key host.
# nginx_signing_key: http://nginx.org/keys/nginx_signing.key

# Specify source repository for NGINX Open Source.
# Only works if 'install_from' is set to 'nginx_repository'.
# Defaults are the official NGINX repositories.
# nginx_repository: deb https://nginx.org/packages/mainline/debian/ stretch nginx

# Choose to install BSD packages or ports.
# Options are True for packages or False for ports.
# Default is True.
nginx_bsd_install_packages: true

# Choose to update BSD ports collection.
# Options are True for update or False for do not update.
# Default is True.
nginx_bsd_update_ports: true

# Choose to install packages built from BSD ports collection if
# available.
# Options are True for use packages or False for do not use packages.
# Default is True.
nginx_bsd_portinstall_use_packages: true

# Specify which branch of NGINX Open Source you want to install.
# Options are 'mainline' or 'stable'.
# Only works if 'install_from' is set to 'nginx_repository'.
# Default is mainline.
nginx_branch: mainline

# Location of your NGINX Plus license in your local machine.
# Default is the files folder within the NGINX Ansible role.
nginx_license:
  certificate: license/nginx-repo.crt
  key: license/nginx-repo.key

# Delete NGINX Plus license after installation for security purposes.
# Default is true.
nginx_delete_license: true

# Install NGINX JavaScript, Perl, ModSecurity WAF (NGINX Plus only), GeoIP, Image-Filter, RTMP Media Streaming, and/or XSLT modules.
# Default is false.
nginx_modules:
  njs: false
  perl: false
  waf: false
  geoip: false
  image_filter: false
  rtmp: false
  xslt: false

# Install NGINX Amplify.
# Use your NGINX Amplify API key.
# Requires access to either the NGINX stub status or the NGINX Plus REST API.
# Default is null.
nginx_amplify_enable: false
nginx_amplify_api_key: null

# Install NGINX Controller.
# Use your NGINX Controller API key and NGINX Controller API endpoint.
# Requires NGINX Plus and write access to the NGINX Plus REST API.
# Default is null.
nginx_controller_enable: false
nginx_controller_api_key: null
nginx_controller_api_endpoint: null

# Install NGINX Unit and NGINX Unit modules.
# Use a list of supported NGINX Unit modules.
# Default is false.
nginx_unit_enable: false
nginx_unit_modules: null

# Remove previously existing NGINX configuration files.
# Use a list of paths you wish to remove.
# Default is false.
nginx_cleanup_config: false
nginx_cleanup_config_path:
  - /etc/nginx/conf.d

# Enable uploading NGINX configuration files to your system.
# Default for uploading files is false.
# Default location of files is the files folder within the NGINX Ansible role.
# Upload the main NGINX configuration file.
nginx_main_upload_enable: false
nginx_main_upload_src: conf/nginx.conf
nginx_main_upload_dest: /etc/nginx/
# Upload HTTP NGINX configuration files.
nginx_http_upload_enable: false
nginx_http_upload_src: conf/http/*.conf
nginx_http_upload_dest: /etc/nginx/conf.d/
# Upload Stream NGINX configuration files.
nginx_stream_upload_enable: false
nginx_stream_upload_src: conf/stream/*.conf
nginx_stream_upload_dest: /etc/nginx/conf.d/
# Upload HTML files.
nginx_html_upload_enable: false
nginx_html_upload_src: www/*
nginx_html_upload_dest: /usr/share/nginx/html
# Upload SSL certificates and keys.
nginx_ssl_upload_enable: false
nginx_ssl_crt_upload_src: ssl/*.crt
nginx_ssl_crt_upload_dest: /etc/ssl/certs/
nginx_ssl_key_upload_src: ssl/*.key
nginx_ssl_key_upload_dest: /etc/ssl/private/

# Enable creating dynamic templated NGINX HTML demo websites.
nginx_html_demo_template_enable: false
nginx_html_demo_template:
  default:
    template_file: www/index.html.j2
    html_file_name: index.html
    html_file_location: /usr/share/nginx/html
    web_server_name: Default

# Enable creating dynamic templated NGINX configuration files.
# Defaults are the values found in a fresh NGINX installation.
nginx_main_template_enable: false
nginx_main_template:
  template_file: nginx.conf.j2
  conf_file_name: nginx.conf
  conf_file_location: /etc/nginx/
  user: nginx
  worker_processes: auto
  #worker_rlimit_nofile: 1024
  error_log:
    location: /var/log/nginx/error.log
    level: warn
  worker_connections: 1024
  http_enable: true
  http_settings:
    access_log_format:
      - name: main
        format: |-
          '$remote_addr - $remote_user [$time_local] "$request" '
          '$status $body_bytes_sent "$http_referer" '
          '"$http_user_agent" "$http_x_forwarded_for"'
    access_log_location:
      - name: main
        location: /var/log/nginx/access.log
    tcp_nopush: true
    tcp_nodelay: true
    keepalive_timeout: 65
    cache: false
    rate_limit: false
    keyval: false
    #server_tokens: "off"
  http_global_autoindex: false
  #http_custom_options: []
  stream_enable: false
  #stream_custom_options: []
  #auth_request_http: /auth
  #auth_request_set_http:
    #name: $auth_user
    #value: $upstream_http_x_user

# Enable creating dynamic templated NGINX HTTP configuration files.
# Defaults will not produce a valid configuration. Instead they are meant to showcase
# the options available for templating. Each key represents a new configuration file.
nginx_http_template_enable: false
nginx_http_template:
  default:
    template_file: http/default.conf.j2
    conf_file_name: default.conf
    conf_file_location: /etc/nginx/conf.d/
    servers:
      server1:
        listen:
          listen_localhost:
            ip: localhost # Wrap in square brackets for IPv6 addresses
            port: 8081
            opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:').
        server_name: localhost
        include_files: []
        error_page: /usr/share/nginx/html
        access_log:
          - name: main
            location: /var/log/nginx/access.log
        error_log:
          location: /var/log/nginx/error.log
          level: warn
        root: /usr/share/nginx/html
        https_redirect: false
        autoindex: false
        auth_basic: null
        auth_basic_user_file: null
        try_files: $uri $uri/index.html $uri.html =404
        #auth_request: /auth
        #auth_request_set:
          #name: $auth_user
          #value: $upstream_http_x_user
        client_max_body_size: 1m
        proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
        add_headers:
          strict_transport_security:
            name: Strict-Transport-Security
            value: max-age=15768000; includeSubDomains
            always: true
          #header_name:
            #name: Header-X
            #value: Value-X
            #always: false
        ssl:
          cert: /etc/ssl/certs/default.crt
          key: /etc/ssl/private/default.key
          dhparam: /etc/ssl/private/dh_param.pem
          protocols: TLSv1 TLSv1.1 TLSv1.2
          ciphers: HIGH:!aNULL:!MD5
          prefer_server_ciphers: true
          session_cache: none
          session_timeout: 5m
          disable_session_tickets: false
          trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt
          stapling: true
          stapling_verify: true
        #custom_options: []
        web_server:
          locations:
            default:
              location: /
              include_files: []
              proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
              add_headers:
                strict_transport_security:
                  name: Strict-Transport-Security
                  value: max-age=15768000; includeSubDomains
                  always: true
                #header_name:
                  #name: Header-X
                  #value: Value-X
                  #always: false
              html_file_location: /usr/share/nginx/html
              html_file_name: index.html
              autoindex: false
              auth_basic: null
              auth_basic_user_file: null
              try_files: $uri $uri/index.html $uri.html =404
              #auth_request: /auth
              #auth_request_set:
                #name: $auth_user
                #value: $upstream_http_x_user
              client_max_body_size: 1m
              #returns:
                #return302:
                  #code: 302
                  #url: https://sso.somehost.local/?url=https://$http_host$request_uri
              #custom_options: []
          http_demo_conf: false
        reverse_proxy:
          locations:
            backend:
              location: /
              include_files: []
              proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
              add_headers:
                strict_transport_security:
                  name: Strict-Transport-Security
                  value: max-age=15768000; includeSubDomains
                  always: true
                #header_name:
                  #name: Header-X
                  #value: Value-X
                  #always: false
              proxy_connect_timeout: null
              proxy_pass: http://backend
              #rewrites:
              # - /foo(.*) /$1 break
              #proxy_pass_request_body: off
              #allows:
              # - 192.168.1.0/24
              #denies:
              # - all
              proxy_set_header:
                header_host:
                  name: Host
                  value: $host
                header_x_real_ip:
                  name: X-Real-IP
                  value: $remote_addr
                header_x_forwarded_for:
                  name: X-Forwarded-For
                  value: $proxy_add_x_forwarded_for
                header_x_forwarded_proto:
                  name: X-Forwarded-Proto
                  value: $scheme
                #header_upgrade:
                  #name: Upgrade
                  #value: $http_upgrade
                #header_connection:
                  #name: Connection
                  #value: "Upgrade"
                #header_random:
                  #name: RandomName
                  #value: RandomValue
              #internal: false
              #proxy_store: off
              #proxy_store_acccess: user:rw
              proxy_read_timeout: null
              proxy_send_timeout: null
              proxy_ssl:
                cert: /etc/ssl/certs/proxy_default.crt
                key: /etc/ssl/private/proxy_default.key
                trusted_cert: /etc/ssl/certs/proxy_ca.crt
                protocols: TLSv1 TLSv1.1 TLSv1.2
                ciphers: HIGH:!aNULL:!MD5
                verify: false
                verify_depth: 1
                session_reuse: true
              proxy_cache: backend_proxy_cache
              proxy_cache_valid:
                - code: 200
                  time: 10m
                - code: 301
                  time: 1m
              proxy_temp_path:
                path: /var/cache/nginx/proxy/backend/temp
              proxy_cache_lock: false
              proxy_cache_min_uses: 3
              proxy_cache_revalidate: false
              proxy_cache_use_stale:
                - http_403
                - http_404
              proxy_ignore_headers:
                - Vary
                - Cache-Control
              proxy_cookie_path:
                path: /web/
                replacement: /
              proxy_buffering: false
              proxy_http_version: 1.0
              websocket: false
              auth_basic: null
              auth_basic_user_file: null
              try_files: $uri $uri/index.html $uri.html =404
              #auth_request: /auth
              #auth_request_set:
                #name: $auth_user
                #value: $upstream_http_x_user
              #returns:
                #return302:
                  #code: 302
                  #url: https://sso.somehost.local/?url=https://$http_host$request_uri
              #custom_options: []
          health_check_plus: false
        returns:
          return301:
            location: /
            code: 301
            value: http://$host$request_uri
    proxy_cache:
      proxy_cache_path:
        - path: /var/cache/nginx/proxy/backend
          keys_zone:
            name: backend_proxy_cache
            size: 10m
          levels: "1:2"
          max_size: 10g
          inactive: 60m
          use_temp_path: true
      proxy_temp_path:
        path: /var/cache/nginx/proxy/temp
      proxy_cache_valid:
        - code: 200
          time: 10m
        - code: 301
          time: 1m
      proxy_cache_lock: true
      proxy_cache_min_uses: 5
      proxy_cache_revalidate: true
      proxy_cache_use_stale:
        - error
        - timeout
      proxy_ignore_headers:
        - Expires
    upstreams:
      upstream1:
        name: backend
        lb_method: least_conn
        zone_name: backend_mem_zone
        zone_size: 64k
        sticky_cookie: false
        servers:
          server1:
            address: localhost
            port: 8081
            weight: 1
            health_check: max_fails=1 fail_timeout=10s
        #custom_options: []
      #custom_options: []

# Enable NGINX status data.
# Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus.
# Note - 'status' has been deprecated since NGINX Plus R13.
# Default is false.
nginx_status_enable: false
nginx_status_location: /etc/nginx/conf.d/stub_status.conf
nginx_status_port: 80

# Enable NGINX Plus REST API, write access to the REST API, and NGINX Plus dashboard.
# Requires NGINX Plus.
# Default is false.
nginx_rest_api_enable: false
nginx_rest_api_template_file: http/api.conf.j2
nginx_rest_api_file_location: /etc/nginx/conf.d/api.conf
nginx_rest_api_port: 80
nginx_rest_api_write: false
nginx_rest_api_dashboard: false

# Enable creating dynamic templated NGINX stream configuration files.
# Defaults will not produce a valid configuration. Instead they are meant to showcase
# the options available for templating. Each key represents a new configuration file.
nginx_stream_template_enable: false
nginx_stream_template:
  default:
    template_file: stream/default.conf.j2
    conf_file_name: default.conf
    conf_file_location: /etc/nginx/conf.d/stream/
    network_streams:
      default:
        listen_address: localhost
        listen_port: 80
        udp_enable: false
        include_files: []
        proxy_pass: backend
        proxy_timeout: 3s
        proxy_connect_timeout: 1s
        proxy_protocol: false
        proxy_ssl:
          cert: /etc/ssl/certs/proxy_default.crt
          key: /etc/ssl/private/proxy_default.key
          trusted_cert: /etc/ssl/certs/proxy_ca.crt
          protocols: TLSv1 TLSv1.1 TLSv1.2
          ciphers: HIGH:!aNULL:!MD5
          verify: false
          verify_depth: 1
          session_reuse: true
        health_check_plus: false
        #custom_options: []
    upstreams:
      upstream1:
        name: backend
        lb_method: least_conn
        zone_name: backend
        zone_size: 64k
        sticky_cookie: false
        servers:
          server1:
            address: localhost
            port: 8080
            weight: 1
            health_check: max_fails=1 fail_timeout=10s
        #custom_options: []
    #custom_options: []
```

Dependencies
------------

None

Example Playbook
----------------

This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX.

```yaml
---
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
```

This is a sample playbook file for deploying the Ansible Galaxy NGINX role to a dynamic inventory containing the `nginx` tag.

```yaml
---
- hosts: tag_nginx
  remote_user: root
  roles:
    - role: nginxinc.nginx
```

This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX as a simple web server.

```yaml
---
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
  vars:
    nginx_http_template_enable: true
    nginx_http_template:
      default:
        template_file: http/default.conf.j2
        conf_file_name: default.conf
        conf_file_location: /etc/nginx/conf.d/
        port: 80
        server_name: localhost
        error_page: /usr/share/nginx/html
        autoindex: false
        web_server:
          locations:
            default:
              location: /
              html_file_location: /usr/share/nginx/html
              html_file_name: index.html
              autoindex: false
          http_demo_conf: false
```

This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX as a reverse proxy.

```yaml
---
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
  vars:
    nginx_http_template_enable: true
    nginx_http_template:
      default:
        template_file: http/default.conf.j2
        conf_file_name: default.conf
        conf_file_location: /etc/nginx/conf.d/
        servers:
          server1:  
            listen:
              listen_localhost:
                #ip: 0.0.0.0
                port: 80
                opts:
                  - default_server
            server_name: localhost
            error_page: /usr/share/nginx/html
            autoindex: false
            reverse_proxy:
              locations:
                frontend:
                  location: /
                  proxy_pass: http://frontend_servers
                backend:
                  location: /backend
                  proxy_pass: http://backend_servers
        upstreams:
          upstream_1:
            name: frontend_servers
            lb_method: least_conn
            zone_name: frontend
            zone_size: 64k
            sticky_cookie: false
            servers:
              frontend_server_1:
                address: 0.0.0.0
                port: 8081
                weight: 1
                health_check: max_fails=3 fail_timeout=5s
          upstream_2:
            name: backend_servers
            lb_method: least_conn
            zone_name: backend
            zone_size: 64k
            sticky_cookie: false
            servers:
              backend_server_1:
                address: 0.0.0.0
                port: 8082
                weight: 1
                health_check: max_fails=3 fail_timeout=5s
      frontend:
        template_file: http/default.conf.j2
        conf_file_name: frontend_default.conf
        conf_file_location: /etc/nginx/conf.d/
        servers:
          server1:
            listen:
              listen_localhost:
                ip: 0.0.0.0
                port: 8081
                opts: []
            server_name: localhost
            error_page: /usr/share/nginx/html
            autoindex: false
            web_server:
              locations:
                frontend_site:
                  location: /
                  proxy_hide_headers:
                    - X-Powered-By
                  html_file_location: /usr/share/nginx/html
                  html_file_name: index.html
                  autoindex: false
              http_demo_conf: false
      backend:
        template_file: http/default.conf.j2
        conf_file_name: backend_default.conf
        conf_file_location: /etc/nginx/conf.d/
        servers:
          server1:
            listen:
              listen_localhost:
                ip: 0.0.0.0
                port: 8082
                opts: []
            server_name: localhost
            error_page: /usr/share/nginx/html
            autoindex: false
            web_server:
              locations:
                backend_site:
                  location: /
                  html_file_location: /usr/share/nginx/html
                  html_file_name: index.html
                  autoindex: false
              http_demo_conf: false
```


This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing NGINX Plus.

```yaml
---
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
  vars:
    nginx_type: plus
```

This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost to install NGINX Plus and the NGINX Controller agent.

```yaml
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
  vars:
    nginx_type: plus
    nginx_rest_api_enable: true
    nginx_rest_api_port: 80
    nginx_rest_api_write: true
    nginx_controller_enable: true
    nginx_controller_api_key: <API_KEY_HERE>
    nginx_controller_api_endpoint: https://<FQDN>/1.4
```

This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost to install NGINX Unit and the PHP/Perl NGINX Unit language modules.

```yaml
---
- hosts: localhost
  become: true
  roles:
    - role: nginxinc.nginx
  vars:
    nginx_enable: false
    nginx_unit_enable: true
    nginx_unit_modules:
      - unit-php
      - unit-perl
```

To run any of the above sample playbooks create a `setup-nginx.yml` file and paste the contents. Executing the Ansible Playbook is then as simple as executing `ansible-playbook setup-nginx.yml`.

Alternatively, you can also clone this repository instead of installing it from Ansible Galaxy. If you decide to do so, replace the role variable in the previous sample playbooks from `nginxinc.nginx` to `ansible-role-nginx`.

License
-------

[Apache License, Version 2.0](https://github.com/nginxinc/ansible-role-nginx/blob/master/LICENSE)

Author Information
------------------

[Alessandro Fael Garcia](https://github.com/alessfg)

[Grzegorz Dzien](https://github.com/gdzien)

&copy; [NGINX, Inc.](https://www.nginx.com/) 2018 - 2019