README.rst

=============
Usage
=============

Nginx is an open source reverse proxy server for HTTP, HTTPS,
SMTP, POP3, and IMAP protocols, as well as a load balancer,
HTTP cache, and a web server (origin server). The nginx project
started with a strong focus on high concurrency, high performance
and low memory usage.

Sample Pillars
==============

Gitlab server setup:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        bind:
          address: '0.0.0.0'
          ports:
          - 80
        site:
          gitlab_domain:
            enabled: true
            type: gitlab
            name: domain
            ssl:
              enabled: true
              key: |
                -----BEGIN RSA PRIVATE KEY-----
                ...
              cert: |
                xyz
              chain: |
                my_chain..
            host:
              name: gitlab.domain.com
              port: 80

Simple static HTTP site:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_static_site01:
            enabled: true
            type: nginx_static
            name: site01
            host:
              name: gitlab.domain.com
              port: 80

Simple load balancer:

.. code-block:: yaml

    nginx:
      server:
        upstream:
          horizon-upstream:
            backend1:
              address: 10.10.10.113
              port: 8078
              opts: weight=3
            backend2:
              address: 10.10.10.114
        site:
          nginx_proxy_openstack_web:
            enabled: true
            type: nginx_proxy
            name: openstack_web
            proxy:
              upstream_proxy_pass: http://horizon-upstream
            host:
              name: 192.168.0.1
              port: 31337

Static site with access policy:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_static_site01:
            enabled: true
            type: nginx_static
            name: site01
            access_policy:
              allow:
              - 192.168.1.1/24
              - 127.0.0.1
              deny:
              - 192.168.1.2
              - all
            host:
              name: gitlab.domain.com
              port: 80

Simple TCP/UDP proxy:

.. code-block:: yaml

    nginx:
      server:
        stream:
          rabbitmq:
            host:
              port: 5672
            backend:
              server1:
                address: 10.10.10.113
                port: 5672
                least_conn: true
                hash: "$remote_addr consistent"
          unbound:
            host:
              bind: 127.0.0.1
              port: 53
              protocol: udp
            backend:
              server1:
                address: 10.10.10.113
                port: 5353

Simple HTTP proxy:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_site01:
            enabled: true
            type: nginx_proxy
            name: site01
            proxy:
              host: local.domain.com
              port: 80
              protocol: http
            host:
              name: gitlab.domain.com
              port: 80

Simple HTTP proxy with multiple locations:

.. note:: If proxy part is defined and location is missing ``/``,
          the proxy part is used. If the ``/`` location is defined,
          it overrides the proxy part.

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_site01:
            enabled: true
            type: nginx_proxy
            name: site01
            proxy:
              host: local.domain.com
              port: 80
              protocol: http
            location:
              /internal/:
                host: 172.120.10.200
                port: 80
                protocol: http
              /doc/:
                host: 172.10.10.200
                port: 80
                protocol: http
            host:
              name: gitlab.domain.com
              port: 80

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_site01:
            enabled: true
            type: nginx_proxy
            name: site01
            location:
              /:
                host: 172.120.10.200
                port: 80
                protocol: http
              /doc/:
                host: 172.10.10.200
                port: 80
                protocol: http
            host:
              name: gitlab.domain.com
              port: 80

Simple Websocket proxy:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_site02:
            enabled: true
            type: nginx_proxy
            name: site02
            proxy:
              websocket: true
              host: local.domain.com
              port: 80
              protocol: http
            host:
              name: gitlab.domain.com
              port: 80

Content filtering proxy:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          nginx_proxy_site03:
            enabled: true
            type: nginx_proxy
            name: site03
            proxy:
              host: local.domain.com
              port: 80
              protocol: http
              filter:
                search: https://www.domain.com
                replace: http://10.10.10.10
            host:
              name: gitlab.domain.com
              port: 80

Proxy with access policy:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_site01:
            enabled: true
            type: nginx_proxy
            name: site01
            access_policy:
              allow:
              - 192.168.1.1/24
              - 127.0.0.1
              deny:
              - 192.168.1.2
              - all
            proxy:
              host: local.domain.com
              port: 80
              protocol: http
            host:
              name: gitlab.domain.com
              port: 80

Use nginx `ngx_http_map_module` that creates variables whose values depend on
values of other variables.

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        map:
          enabled: true
          items:
            mymap:
              enabled: true
              string: input_string
              variable: output_map_variable
              body:
                default:
                  value: '""'
                example.com:
                  value: '1'
                example.org:
                  value: '2'

Use nginx `ngx_http_geo_module module` that creates variables with values
depending on the client IP address.

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        geo:
          enabled: true
          items:
            my_geo_map:
              enabled: true
              variable: output_get_variable
              body:
                default:
                  value: '""'
                cl1
                  name: 10.12.100.1/32
                  value: '1'
                cl2
                  name: 10.13.0.0/16
                  value:  2'

Use `ngx_http_limit_req_module` module that is used to limit the request
processing rate per a defined key, in particular, the processing rate of
requests coming from a single IP address. The limitation is done using
the `leaky bucket` method.
The `limit_req_module` might be configured globally or applied to specific
nginx site.

.. code-block:: yaml

    nginx:
      server:
        limit_req_module:
          limit_req_zone:
            global_limit_ip_zone:
              key: global_limit_ip_var
              size: 10m
              rate: '1r/s'
          limit_req_status: 503
          limit_req:
             global_limit_zone:
               burst: 5
               enabled: true

There is an example to to limit requests to all sites based on IP.
In the following example all clients are limited except of 10.12.100.1
with 1 req per second.

#. Create geo instance that will match IP and set `limit_action` var.
   "0" - is unlimited, 1 - limited

#. Create a `global_geo_limiting_map` that will map `ip_limit_key` to
   `ip_limit_action`

#. Create global `limit_req_zone` called `global_limit_zone` that limits
   number of requests to 1r/s

#. Apply `global_limit_zone` globally to all requests with 5 req burst.

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        geo:
          enabled: true
          items:
            global_geo_limiting:
              enabled: true
              variable: ip_limit_key
              body:
                default:
                  value: '1'
                unlimited_client1:
                  name: '10.12.100.1/32'
                  value: '0'
        map:
          enabled: true
          items:
            global_geo_limiting_map:
              enabled: true
              string: ip_limit_key
              variable: ip_limit_action
              body:
                limited:
                  name: 1
                  value: '$binary_remote_addr'
                unlimited:
                  name: 0
                  value: '""'
        limit_req_module:
          limit_req_zone:
            global_limit_zone:
              key: ip_limit_action
              size: 10m
              rate: '1r/s'
          limit_req_status: 503
          limit_req:
             global_limit_zone:
               burst: 5
               enabled: true

To apply request limiting to particular site only `limit_req` should be
applied on site level, for example:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_openstack_api_keystone:
            limit_req_module:
              limit_req:
                global_limit_zone:
                  burst: 5
                  enabled: true


Use `ngx_http_limit_conn_module` module that is used to set the shared memory
zone and the maximum allowed number of connections for a given key value.
The `limit_conn_module` might be configured globally or applied to specific
nginx site.

.. code-block:: yaml

    nginx:
      server:
        limit_conn_module:
          limit_conn_zone:
            global_limit_conn_zone:
              key: 'binary_remote_addr'
              size: 10m
          limit_conn_status: 503
          limit_conn:
             global_limit_conn_zone:
               connection: 50
               enabled: true


To apply connection limiting to particular site only `limit_conn` should be
applied on site level, for example:

.. code-block:: yaml

    nginx:
      server:
        site:
          nginx_proxy_openstack_web:
            limit_conn_module:
              limit_conn:
                global_limit_conn_zone:
                  connections: 25
                  enabled: true

Gitlab server with user for basic auth:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        user:
          username1:
            enabled: true
            password: magicunicorn
            htpasswd: htpasswd-site1
          username2:
            enabled: true
            password: magicunicorn

Proxy buffering:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        bind:
          address: '0.0.0.0'
          ports:
          - 80
        site:
          gitlab_proxy:
            enabled: true
            type: nginx_proxy
            proxy:
              request_buffer: false
              buffer:
                number: 8
                size: 16
            host:
              name: gitlab.domain.com
              port: 80

If we need to read large client request headers, we need to add new
parameter `large_client_header_buffers` with buffers number and size:
.. code-block:: yaml
    nginx:
      server:
        enabled: true
        bind:
          address: '0.0.0.0'
          ports:
          - 80
        site:
          gitlab_proxy:
            enabled: true
            type: nginx_proxy
            large_client_header_buffers: '4 8k'
            host:
              name: gitlab.domain.com
              port: 80

Let's Encrypt:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        bind:
          address: '0.0.0.0'
          ports:
          - 443
        site:
          gitlab_domain:
            enabled: true
            type: gitlab
            name: domain
            ssl:
              enabled: true
              engine: letsencrypt
            host:
              name: gitlab.domain.com
              port: 443

SSL using already deployed key and cert file.

.. note:: The cert file should already contain CA cert and
          complete chain.

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          mysite:
            ssl:
              enabled: true
              key_file: /etc/ssl/private/mykey.key
              cert_file: /etc/ssl/cert/mycert.crt

or

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          mysite:
            ssl:
              enabled: true
              engine: custom
              key_file: /etc/ssl/private/mykey.key
              cert_file: /etc/ssl/cert/mycert.crt

Advanced SSL configuration, more information about SSL option
may be found at http://nginx.org/en/docs/http/ngx_http_ssl_module.html

.. note:: Prior to nginx 1.11.0, only one type of ecdh curve
          can be applied in ``ssl_ecdh_curve directive``.

          if mode = ``secure`` or mode = ``normal`` and ``ciphers``
          or ``protocols`` are set, they should have type ``string``.
          If mode = ``manual``, their type should be ``dict``
          as shown below.

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          mysite:
            ssl:
              enabled: true
              mode: 'manual'
              key_file:  /srv/salt/pki/${_param:cluster_name}/${salt:minion:cert:proxy:common_name}.key
              cert_file: /srv/salt/pki/${_param:cluster_name}/${salt:minion:cert:proxy:common_name}.crt
              chain_file: /srv/salt/pki/${_param:cluster_name}/${salt:minion:cert:proxy:common_name}-with-chain.crt
              protocols:
                TLS1:
                  name: 'TLSv1'
                  enabled: True
                TLS1_1:
                  name: 'TLSv1.1'
                  enabled: True
                TLS1_2:
                  name: 'TLSv1.2'
                  enabled: False
              ciphers:
                ECDHE_RSA_AES256_GCM_SHA384:
                  name: 'ECDHE-RSA-AES256-GCM-SHA384'
                  enabled: True
                ECDHE_ECDSA_AES256_GCM_SHA384:
                  name: 'ECDHE-ECDSA-AES256-GCM-SHA384'
                  enabled: True
              buffer_size: '16k'
              crl:
                file: '/etc/ssl/crl.pem'
                enabled: False
              dhparam:
                enabled: True
                numbits: 2048
                use_dsaparam: True
              ecdh_curve:
                secp384r1:
                  name: 'secp384r1'
                  enabled: False
                secp521r1:
                  name: 'secp521r1'
                  enabled: True
              password_file:
                content: 'testcontent22'
                enabled: True
                file: '/etc/ssl/password.key'
              prefer_server_ciphers: 'on'
              ticket_key:
                enabled: True
                numbytes: 48
              resolver:
                address: '127.0.0.1'
                valid_seconds: '500'
                timeout_seconds: '60'
              session_tickets: 'on'
              stapling: 'off'
              stapling_file: '/path/to/stapling/file'
              stapling_responder: 'http://ocsp.example.com/'
              stapling_verify: 'on'
              verify_client: 'on'
              client_certificate:
                file: '/etc/ssl/client_cert.pem'
                enabled: False
              verify_depth: 1
              session_cache: 'shared:SSL:15m'
              session_timeout: '15m'
              strict_transport_security:
                max_age: 16000000
                include_subdomains: False
                always: true
                enabled: true

Setting custom proxy headers:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          custom_headers:
            type: nginx_proxy
            proxy_set_header:
              Host:
                enabled: true
                value: "$host:8774"
              X-Real-IP:
                enabled: true
                value: '$remote_addr'
              X-Forwarded-For:
                enabled: true
                value: '$proxy_add_x_forwarded_for'
              X-Forwarded-Proto:
                enabled: true
                value: '$scheme'
              X-Forwarded-Port:
                enabled: true
                value: '$server_port'

Define site catalog indexes:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          nginx_catalog:
            enabled: true
            type: nginx_static
            name: server
            indexes:
            - index.htm
            - index.html
            host:
              name: 127.0.0.1
              port: 80

Define site catalog autoindex:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          nginx_catalog:
            enabled: true
            type: nginx_static
            name: server
            autoindex: True
            host:
              name: 127.0.0.1
              port: 80

Nginx stats server (required by collectd nginx plugin) (DEPRECATED):

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          nginx_stats_server:
            enabled: true
            type: nginx_stats
            name: server
            host:
              name: 127.0.0.1
              port: 8888

or:

.. code-block:: yaml

    nginx:
      server:
        enabled: true
        site:
          nginx_stats_server:
            enabled: true
            root: disabled
            indexes: []
            stats: True
            type: nginx_static
            name: stat_server
            host:
              name: 127.0.0.1
              address: 127.0.0.1
              port: 8888

Nginx configured to wait for another service/s before
starting (currently only with systemd):

.. code-block:: yaml

    nginx:
      server:
        wait_for_service:
          - foo-bar.mount
        enabled: true
        site:
          ...

More Information
================

* http://wiki.nginx.org/Main
* https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility
* http://nginx.com/resources/admin-guide/reverse-proxy/
* https://mozilla.github.io/server-side-tls/ssl-config-generator/