DEBOPS.NGINX(5)

NAME
debops.nginx - Manage nginx webserver using Ansible

SYNOPSIS

debops run service/nginx [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Nginx <https://nginx.org/> is a fast and light webserver with extensible configuration.

The debops.nginx role can be used to install and manage nginx configuration for multiple websites at the same time. The server is configured using inventory variables. This role can also be used as a dependency of another role to configure a webserver for that role using dependency variables.

GETTING STARTED

  Security defaults

Following Mozilla intermediate level recommendations <https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1d&guideline=5.6>, 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 <https://english.ncsc.nl/publications/publications/2019/juni/01/it-security-guidelines-for-transport-layer-security-tls> 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 <https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_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 <https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security> (see also: HSTS Cheat Sheet <https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Strict_Transport_Security_Cheat_Sheet.html>) 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.

AUTOMATED CERTIFICATE MANAGEMENT ENVIRONMENT (ACME)

ACME is an initiative designed by Internet Security Research Group for the Let's Encrypt <https://letsencrypt.org/> service. It can be used to provision trusted X.509 certificates in a fully automated way.

One of the challenges to prove control over a domain to an ACME CA server is called http-01 , which uses a well-known path on the client web server to serve files which can then be validated by the CA server. This should be sufficient to prove that a given domain is controlled by the entity that requests the certificate.

The debops.nginx Ansible role includes support for the http-01 challenge. They are enabled by default for all server configurations and can be used to prove control over specified domains using a ACME client.

  Ansible local facts

The following ACME related Ansible local facts are exposed by the role:

ansible_local.nginx.acme
ansible_local.nginx.acme_root
ansible_local.nginx.acme_server
ansible_local.nginx.acme_domain

  How ACME support works

By default, all servers that have enabled ACME support, will answer queries on URL:

http://<domain>/.well-known/acme-challenge/xxxxxxxxxxxxxxxx

These queries will be answered over HTTP. Files will be served from the particular server root directory, for example:

/srv/www/sites/<domain>/public/.well-known/acme-challenge/

If the challenge file is not found at the server location, nginx will switch the request to the "global" server root directory, by default:

/srv/www/sites/acme/public/.well-known/acme-challenge/

This directory can be configured in the debops.nginx default variables, and is not managed by the role itself. Other Ansible roles are expected to create it and secure it using UNIX permissions as necessary.

If the requested file is not found on the "global" server root directory, the ACME challenge will be redirected over the same protocol (HTTP or HTTPS) to a different host on configured domain, by default:

$scheme://acme.{{ nginx_acme_domain }}$request_uri?redirect=yes

The redirected host should provide a configured webserver to respond to the ACME challenges. A default server is provided in the debops.nginx configuration and can be enabled on a given host (see below). The additional parameter redirect=yes is used by the nginx server to detect and terminate redirect loops.

  Manual nginx configuration

The above steps are configured in a separate file on the webserver host:

/etc/nginx/snippets/acme-challenge.conf

To enable a given nginx server to respond to ACME challenges, all you need to do is to include that file in the server {} section, for example:

server {
        listen [::]:80
        server_name example.org;
        root /srv/www/sites/example.org/public;
        include snippets/acme-challenge.conf;
        location / {
                try_files $uri $uri/ /index.html =404;
        }
}

Above configuration should be sufficient to satisfy local or remote ACME challenges. Similar configuration can be done on HTTPS server to achieve the same results.

DEFAULT VARIABLE DETAILS

Some of debops.nginx default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  nginx__servers

  Common role options

name
    Required, string or list of strings. Domain names for the Nginx server_name option documentation <https://nginx.org/en/docs/http/server_names.html>.

    The first element is used to create the name of the nginx configuration file and must be a normal domain name, other elements can include wildcards and regexp matches.

    The list can also be empty (but needs to be defined) in which case the configuration it is included in will be named default.

filename
    Optional, string. Alternative name of the nginx configuration file under the /etc/nginx/sites-available/ directory. The suffix .conf will be added automatically. This can be used to distinguish different server configurations for the same item.name. For example separate configuration for HTTP and HTTPS.

hostname
    Optional. String or a list of hostnames or subdomain names without dots. If it's defined, the role will generate server { } blocks that support redirecting the short hostnames or subdomains in the *.local domain managed by Avahi/mDNS to their corresponding FQDNs. For example:

•   host/ -> host.example.com

•   host.local -> host.example.com

    The example.com domain will be based on the hostname_domain parameter, or if not specified on the first value of the name parameter. Users can use the short hostnames in browsers by appending / character after the short name. Specifying directories or arguments is also supported.

    This allows the nginx webserver to correctly handle short subdomains passed to it via DNS suffixes defined in /etc/resolv.conf, or subdomains reachable via Avahi *.local domain.

    If the hostname parameter is not specified, the role will automatically generate subdomains based on the value of the name parameter; only alphanumeric subdomains with optional dashes and underscores are supported in this mode. To tell the role to not autogenerate the redirection, set the hostname parameter to False.

hostname_domain
    Optional. Specify the base DNS domain to use for short hostnames and subdomains. You can use this to set the base domain in multi-subdomain environments. For example, setting it to example.com will result in redirects:

•   host/ -> host.example.com

•   sub.host/ -> sub.host.example.com

    Supporting more than one level of subdomains with DNS suffixes on the clients depends on the resolv.conf(5) <https://manpages.debian.org/resolv.conf(5)> configuration, the ndots parameter.

    If this parameter is not specified, the role will check the list in the nginx__hostname_domains for possible domain suffixes and use the first one found there that matches the current server subdomain.

enabled
    Optional, boolean. Defaults to True. Specifies if the configuration should be enabled by creating a symlink in /etc/nginx/sites-enabled/.

state
    Optional, string. Defaults to present. Whether the Nginx server should be present or absent.

when
    Deprecated, optional, boolean. Use state: 'present' instead.

delete
    Deprecated, optional, boolean. Use state: 'absent' instead.

by_role
    Optional, string. Name of a Ansible role in the format ROLE_OWNER.ROLE_NAME which is responsible for the server configuration.

type
    Optional. Specify name of the template to use to generate nginx server configuration. Templates can extend other templates.

webroot_create
    Optional, boolean. Whether the role will create a server's root directory. Overrides nginx_webroot_create.

owner
    Optional, string. Sets the owner of the server root. Overrides nginx_webroot_owner.

    If specified, nginx will configure the server root to /srv/www/<owner>/sites/<name[0]>/public/.

    If not specified, nginx will configure the server root to /srv/www/sites/<name[0]>/public/.

    If it is set and no group is specified, the group is set to owner.

group
    Optional, string. Explicitly sets the group of the server root. Overrides owner and nginx_webroot_group.

mode
    Optional, string. The permissions of the server root directory. Overrides nginx_webroot_mode.

  Common webserver options

index
    Optional, string or boolean (False). Space separated list of index filenames. The directive will be omitted if set to False.

root
    Optional, string. Absolute path to server root to use for this server configuration. Defaults to /srv/www/sites/<name[0]>/public/. See also owner parameter. The directive will be omitted if set to False.

public_dir_name
    Optional, string. Folder name witch will be concatenated to /srv/www/sites/<name[0]>/ Defaults to public.

root_suffix
    Optional, string. Used in scenario when the site root is in another subfoder. Example. The files are stored in /srv/www/sites/<name[0]>/public, but in nginx the root needs to be /srv/www/sites/<name[0]>/public/current/pub. Defaults to empty string.

try_files
    Optional, string. Defaults to nginx_default_try_files. Checks for the existence of files in order, and returns the first file that is found for location /. Refer to the Nginx try_files directive for details.

keepalive
    Optional, integer. Defaults to nginx_default_keepalive_timeout. Set custom KeepAlive timeout for this server, in seconds.

deny_hidden
    Optional, boolean. Defaults to True. If True deny access to all hidden files.

favicon
    Optional, boolean. Defaults to True. Ignore /favicon.ico requests in server logs to reduce noise if True.

listen
    Optional, list of strings/integers or boolean (False). Defaults to nginx_listen_port. List of ports, IP addresses or sockets this server configuration should listen on for HTTP connections.

listen_ssl
    Optional, list of strings/integers or boolean (False). Defaults to nginx_listen_ssl_port. List of ports, IP addresses or sockets this server configuration should listen on for HTTPS connections.

include_files_begin
    Optional, list of strings. List of files that will be included at the beginning of the server configuration using include.

include_files_end
    Optional, list of strings. List of files that will be included at the end of the server configuration using include.

toplevel_options
    Optional, String or YAML text block with top-level options (i.e. before any server blocks in the generated configuration) for this server configuration. Semicolons at the end of each line are required.

options
    Optional, String or YAML text block with options (included inside the relevant server block) for this server configuration. Semicolons at the end of each line are required.

  Redirects

redirect
    Optional, string. Redirect incoming requests on the HTTP port to the given URL. FIXME: Rename to redirect_http

redirect_ssl
    Optional, string. Redirect incoming requests on the HTTPS port to the given URL. FIXME: Rename to redirect_https

redirect_code
    Optional, string. Specify HTTP code used in the redirect response, by default 307 Temporary Redirect. FIXME: Rename to redirect_http_code

redirect_code_ssl
    Optional, string. Specify HTTP code used in the redirect response from HTTP to HTTPS, by default 301 Moved Permanently. FIXME: Rename to redirect_https_code

redirect_from
    Optional, list of strings or boolean. Create a separate Nginx server block documentation <https://nginx.org/en/docs/http/ngx_http_core_module.html#server> which will automatically redirect requests from specified list of server names (or all but the first name in the name list if redirect_from is set to True) to the first server name specified in the name list.

redirect_to
    Optional, string. Create separate Nginx server block documentation <https://nginx.org/en/docs/http/ngx_http_core_module.html#server> which redirects all requests on servers specified in the name list to the server specified in redirect_to. The specified server name will be used as the only name in subsequent HTTP and HTTPS configuration.

redirect_to_ssl
    Optional, boolean. Defaults to True If True, redirect connection from HTTP to the HTTPS version of the site. Set to False to allow to serve the website via HTTP and HTTPS and don't redirect HTTP to HTTPS. FIXME: Rename to redirect_to_https

  HTTPS and TLS

acme
    Optional, boolean. Defaults to nginx_acme. Enable or disable support for Automated Certificate Management Environment challenge queries for this server.

ssl Optional, boolean. Defaults to nginx_pki. Enable or disable HTTPS for this server configuration. FIXME: Rename to https_enabled

ssl_crt
    Optional, string. Absolute path to a custom X.509 certificate to use. If not supplied, a certificate managed by debops.pki will be used. FIXME: Rename to tls_cert

ssl_key
    Optional, string. Absolute path to custom private key to use. If not supplied pki_key will be used instead. FIXME: Rename to tls_key

ssl_ca
    Optional, string. Specifies the absolute path to the client CA certificate used to authenticate clients. If not specified, pki_ca will be used instead.

ssl_trusted
    Optional, string. Specifies the absolute path to the intermediate+root CA server certificates which will be used for OCSP stapling verification. If not specified, the value of pki_trusted will be used instead.

ssl_dhparam
    Optional, string. Absolute path to custom DHE parameters to use. If not supplied, nginx_ssl_dhparam will be used instead. FIXME: Rename to tls_dhparam_file

ssl_ciphers
    Optional, strings. Defaults to nginx_default_ssl_ciphers. Name of the list of preferred server ciphers defined in nginx_ssl_ciphers to use.

ssl_curve
    Optional, string. Defaults to nginx_default_ssl_curve. ECC curve enabled for this server.

ssl_verify_client
    Optional, boolean. Requests the client certificate and verifies it if the certificate is present.

ssl_client_certificate
    Optional, string. Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

ssl_crl
    Optional. Specifies a file with revoked certificates (CRL) in PEM format used to verify client certificates.

pki_realm
    Optional, string. Overwrites the default PKI realm used by nginx for this server configuration. See the debops.pki role for more information, as well as the /etc/pki/realms directory on remote hosts for a list of available realms.

pki_crt
    Optional, string. Path to custom X.509 certificate to use, relative to the currently enabled PKI realm.

pki_key
    Optional, string. Path to custom private key to use, relative to the currently enabled PKI realm.

pki_ca
    Optional, string. Path to custom client CA certificate to use for client authentication, relative the to currently enabled PKI realm.

pki_trusted
    Optional, string. Path to custom intermediate+root CA certificate to use for OCSP stapling verification, relative to currently enabled PKI realm.

ocsp
    Optional, boolean. Defaults to nginx_ocsp. Enable or disable OCSP stapling for a given server. FIXME: Rename to ocsp_stapling_enabled

ocsp_verify
    Optional, boolean. Defaults to nginx_ocsp_verify Enable or disable OCSP stapling verification for a given server. An intermediate+root CA certificate is required for this. FIXME: Rename to ocsp_stapling_verify

nginx_ocsp_resolvers
    Optional, string. List of DNS servers used to for resolving. Among other things used to resolve OCSP stapling but in general all dns queries (e.g. for proxy_path). If it's empty, nginx role will try to use the nameservers from /etc/resolv.conf. Currently only the first nameserver is used

hsts_enabled
    Optional, boolean. Defaults to True. If this is set to True and HTTPS is enabled for this item, the HTTP Strict Transport Security <https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security> header is set in the server's responses. If this is set to False, the header will not be set in the server's responses.

hsts_preload
    Optional, boolean. Defaults to nginx_hsts_preload. Add a "preload" parameter to the HSTS header which can be used with the https://hstspreload.appspot.com/ site to configure HSTS preloading for a given website.

  User authentication

auth_basic
    Optional, boolean. Enable HTTP Basic Authentication for this server.

auth_basic_realm
    Optional. String which will be displayed to the user in the HTTP Basic Auth dialog box. Defaults to nginx_default_auth_basic_realm.

auth_basic_name
    Optional, string. Required with auth_basic. Specifies the name of the htpasswd file used for this server authentication. htpasswd files are stored in /etc/nginx/private/ directory.

    You can use auth_basic_filename and specify the full path to the htpasswd file to use; file needs to be readable by nginx system user.

  Locations

location
    Optional. Dict of location sections to include in this server configuration, in YAML text block format (semicolons at end of each configuration line required). Each key defines a string used as "location" option, values are strings or text blocks to be included inside each location section. Examples:

     location:
       '/': 'try_files $uri $uri/ /index.html =404;'
       '~ ^/doc$': |
         alias /usr/share/doc;
         autoindex on;

location_allow
    Optional. Dict which adds "allow" entries to each location section defined above from a list. Each location needs to have a corresponding entry in location dict. If item.location_deny is not defined, 'deny all;' is added at the end. Examples:

     location_allow:
       '~ ^/doc$': [ '127.0.0.1', '::1' ]

location_deny
    Optional. Dict which adds "deny" entries to each location section defined above from a list. Each location needs to have corresponding entry in location dict. Examples:

     location_deny:
       '/': [ '192.168.0.1/24' ]
       '~ ^/doc$': [ 'all' ]

location_referers
    Optional. Dict with lists of valid referrers accepted for a given location, all other referrers will be blocked by nginx. Each location needs to have corresponding entry in location dict. Examples:

     location_referers:
       '/': [ '{{ ansible_fqdn }}', 'www.{{ ansible_fqdn }}', '*.{{ ansible_domain }}' ]

location_list
    Optional, list of dicts. This is an alternative syntax of location_* entries; instead of using text blocks directly, it uses dict keys and values to configure each location, which allows for greater control and nesting. List of known keys and their descriptions:

pattern
    Location string pattern, for example: / or ~ ^/doc$ or gitlab

pattern_prefix
    String prepended to the location pattern, for example: @ which will create the named location @gitlab

enabled
    Boolean value specifying if the location should be included in configuration, defaults to True.

referers
    List of allowed valid referer strings.

     referers: [ '{{ ansible_fqdn }}' ]

access_policy
    Optional, string. Specify a named "access policy" to use for this location. Refer to nginx_access_policy_allow_map and similar variables for more information.

satisfy
    Optional, string. Defaults to nginx_default_satisfy. Set the location behaviour to either accept any of allow, auth configuration restrictions, or require all of them to match. By default, any restriction by itself will match. Choices: any, all

allow
    Optional, string or list of strings. IP addresses or CIDR networks which can access the given location. Automatically adds deny: all at the end of the list.

auth_basic
    Optional, boolean. Enable HTTP Basic Authentication for this location.

auth_basic_realm
    Optional. String which will be displayed to the user in the HTTP Basic Auth dialog box. Defaults to nginx_default_auth_basic_realm.

auth_basic_name
    Optional, string. Required with auth_basic. Specifies the name of the htpasswd file used for this location authentication. htpasswd files are stored in /etc/nginx/private/ directory.

    You can use auth_basic_filename and specify the full path to the htpasswd file to use; file needs to be readable by nginx system user.

options
    String or YAML text block with options for this location block, semicolons at the end of each line are required.

locations
    Nested list of locations to create in this location section.

  HTTP security headers

content_type_options
    Optional, string. Defaults to nosniff, which indicates to browsers that MIME types advertised in the Content-Type headers should not be changed and be followed. This prevents MIME type sniffing and is the reason why site security testers usually expect this header to be set. Set this variable to {{ omit }} to exclude the header from all responses.

csp Optional, string. Defaults to: default-src https: ; (force all assets to be loaded over HTTPS). Sets the first part of the Content-Security-Policy header. The string MUST end with a semicolon but MUST NOT begin with one. Make sure that you only use single quotes and no double quotes in the string. If no item.csp_report is given, it also determines the first part of the Content-Security-Policy-Report-Only header. Which headers are actually enabled is defined by item.csp_enabled and item.csp_report_enabled. Refer to the Content Security Policy Reference <https://content-security-policy.com/>.

csp_report
    Optional, string. This allows to set a different/potentially experimental Content-Security-Policy-Report-Only header than defined by item.csp.

csp_append
    Optional, string. Defaults to: nginx__http_csp_append. CSP directives to append to all policies (item.csp and item.csp_report). This can be used to overwrite the default nginx__http_csp_append as needed. The string MUST end with a semicolon but MUST NOT begin with one.

csp_enabled
    Optional, boolean. Defaults to False. If set to True and HTTPS is enabled for this item, the Content-Security-Policy header is set in server responses.

csp_report_enabled
    Optional, boolean. Defaults to False. If this is set to True and HTTPS is enabled for this item, the Content-Security-Policy-Report-Only header is set in the server responses.

xss_protection
    Optional, string. Value of the X-XSS-Protection HTTP header field. Set to {{ omit }} to not send the header field. Defaults to nginx__http_xss_protection.

1   Browsers should enable there build in cross-site scripting protection.

mode=block
    In case a cross-site scripting attack is detected, block the page from rendering.

    Note that the this option might create a vulnerability in old versions of Internet Explorer <https://github.com/helmetjs/helmet#xss-filter-xssfilter>.

    For more details and discussion see What is the http-header “X-XSS-Protection”? <https://stackoverflow.com/questions/9090577/what-is-the-http-header-x-xss-protection>.

http_referrer_policy
    Optional, string. Value of the Referrer-Policy HTTP header field. Set to {{ omit }} to not send the header field. Defaults to nginx__http_referrer_policy. Refer to Referrer Policy <https://www.w3.org/TR/referrer-policy/> for more details. Note that this header is a draft as of 2016-10-11 but it is already supported by the majority of web browsers.

permitted_cross_domain_policies
    Optional, string. Value of the X-Permitted-Cross-Domain-Policies HTTP header field. Set to {{ omit }} to not send the header field. Defaults to nginx__http_permitted_cross_domain_policies.

    Should cross domain policies be permitted?

frame_options
    Optional, string. Value of the X-Frame-Options HTTP header field. Set to {{ omit }} to not send the header field. Defaults to SAMEORIGIN.

  Search engine optimization

robots_tag
    Optional, list of strings or string. Value of the X-Robots-Tag HTTP header field. Set to {{ omit }} to not send the header field. Defaults to nginx__http_robots_tag.

    This allows you to give search engine bots hints how they should handle the website. For example, when you don’t want that search engines don’t "index" your website, you can set this variable to none.

    NOTE: This header field is merely a hint for the search engine bot, nothing more and they might ignore it. For example, Google sets this straight in their first sentence in the documentation which says "This document details how the page-level indexing settings allow you to control how Google makes content available through search results." So you will need to prevent the search engine bots from crawling the site in the first place in case you want to prevent that.

    Refer to robots meta tag and X-Robots-Tag HTTP header specifications <https://developers.google.com/webmasters/control-crawl-index/docs/robots_meta_tag> for more details.

  Access control

access_policy
    Optional, string. Specify a named "access policy" to use for this server. Refer to nginx_access_policy_allow_map and similar variables for more information.

satisfy
    Optional, string. Defaults to nginx_default_satisfy. Set the server behaviour to either accept any of allow, auth configuration restrictions, or require all of them to match. By default, any restriction by itself will match. Choices: any, all

allow
    Optional, string or list of strings. IP addresses or CIDR networks which can access the given server. Automatically adds deny: all at the end of the list.

options
    Optional, string. Add custom options to this server configuration using a YAML text block (semicolons at the end of each line are required).

  Logging and monitoring

log_path
    Optional, string. Absolute path where log files should be stored. If not specified, logs will be saved to /var/log/nginx/ directory. You should take care of log rotation if you specify a custom log path. The specified path needs to exist before nginx is reloaded/restarted.

access_log
    Optional, string. Defaults to <``name[0]>_access. Name of the access log file. The suffix .log will be added automatically.

access_log_enabled
    Optional, boolean. Defaults to True. If access logging should be enabled.

error_log
    Optional, string. Defaults to <``name[0]>_error. Name of the error log file. The suffix .log will be added automatically.

error_log_enabled
    Optional, boolean. Defaults to True. If error logging should be enabled.

access_log_format
    Optional. Name of the access log format. Custom log formats can be defined using nginx__log_format variable.

status
    Optional, list of strings. Enable nginx server status page and allow access from the given list of IP addresses or CIDR ranges.

status_name
    Optional, string. Defaults to nginx_status_name. Set the name of the location which should be used for the nginx status page.

  Error pages

error_pages
    Optional. Dict of error codes in string format as keys and corresponding error pages to display. Example:

     error_pages:
       '403 404': '/400.html'
       '502':     '/500.html'

error_pages_list
    Optional. List of dictionaries, each one describing an error page. List of known keys and their descriptions:

code
    Required, String or list strings. Error codes to include in this configuration section.

uri Required. URI or location to redirect the request to.

location and location_options
    Optional. If specified, an additional location section will be added with contents of the location_options parameter. If only location_options is present, the uri parameter will be used as the location.

    Examples:

     error_pages_list:
       - code: [ '403', '404', '=500' ]
         uri: '/error.html'
         location: '= /error.html'
         location_options: |
           internal;

maintenance
    Optional, boolean. Defaults to True. Specifies if the maintenance HTML page configuration should be added to the server or not.

maintenance_file
    Optional. Path of the maintenance HTML page (by default maintenance.html) located in the website's document root directory. If the file is present, all requests will be redirected to the maintenance page with error "503 Service Unavailable".

  Welcome page

welcome
    Optional, boolean. Defaults to False. If True a welcome index.html page is generated in website root directory using a template.

welcome_force
    Optional, boolean. Ensure that the templated file is up-to-date if True. Set to False by default to ensure idempotent operation.

welcome_template
    Optional. Specify absolute path to a Jinja2 template which should be used to generate a welcome page.

welcome_domain
    Optional. Specify a DNS domain which should be used in the generated welcome page. By default, a domain is detected from name[0], or if it's not specified, ansible_domain variables.

welcome_css
    Optional. If specified and False, omit custom stylesheet in the generated index.html' file.

  User directories

userdir
    Optional, boolean. Enable UserDir support. Web pages on https://host/~<user>/ will be read from /srv/www/<user>/userdir/public directories.

userdir_regexp
    Optional, string. Specify location regexp pattern used by nginx to determine if a specified URL is an userdir URL.

userdir_alias
    Optional, string. Specify the absolute path to user directories used as an alias pattern which uses the parameters from location regexp to select the correct user and file to display.

userdir_index
    Optional, string. Specify space separated list of index files which will be used by nginx automatically to display a HTML page, if found in the current directory.

userdir_options
    Optional, string. Specify additional options added to the userdir location block.

  Type: php

Available when item.type is set to php for a server.

php_upstream
    Required, string. Name of nginx upstream to use.

    If undefined, .php files will be protected by =403.

index
    Optional, string. Space separated list of index filenames. Refer to Common webserver options for details.

    If undefined, add index.php at the end of list of index files.

php_limit_except or False
    Optional, string or list of strings or boolean (False). Whitelist of allowed HTTP request methods.

    If absent or False, limits are disabled.

    Refer to the Nginx limit_except directive documentation <https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_except> for details.

php_include
    Optional, string or boolean (False). File to include instead of fastcgi_params or fastcgi.conf, relative to /etc/nginx/.

    If set to False, nothing is included.

php_try_files
    Optional. A string or list with try_files option values which should be defined in the PHP location blocks. If not defined, the default is to use the $script_name and =404 values.

php_location_script_name
    Optional. This parameter allows modification of the location matching rule used for PHP scripts without additional parameters, by default:

    ~ ^(?!.+\.php/)(?<script_name>.+\.php)$

php_location_path_info
    Optional. This parameter allows modification of the location matching rule used for PHP scripts with additional parameters, by default:

    ~ ^(?<script_name>.+\.php)(?<path_info>/.*)$

php_options
    Optional, string. Additional options to append to php location.

php_status
    Optional, boolean. Enable php-fpm server status page.

php_status_name
    Optional, string. Defaults to php_status. Set the name of the location which should be used for php fpm status page

php_ping_name
    Optional, string. Defaults to php_ping. Set the name of the location which should be used for php fpm ping page

php_status_allow
    Optional, string or list of strings. Allow access the given IP addresses or CIDR ranges.

  Type: php5

Deprecated, use Type: php.

  Type: proxy

Available when item.type is set to proxy for a server.

proxy_pass
    Required, string. Set the upstream url for this proxy configuration. This can be omitted if either a location or a location_list is defined.

proxy_location
    Optional, string. Defaults to /. Set the location for the proxy, which is used in case not other location or location_list are defined.

proxy_headers
    Optional, string. Add custom headers to this proxy configuration using a YAML text block (semicolon at the end of each line is required).

proxy_options
    Optional, string. Add custom options to this proxy configuration using a YAML text block (semicolon at the end of each line is required).

  Type: rails

Available when item.type is set to rails for a server.

FIXME: Documentation missing.

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others