Usage

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:

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:

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

Simple load balancer:

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:

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:

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:

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.

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
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:

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:

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:

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.

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.

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.

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.

  1. Create geo instance that will match IP and set limit_action var. “0” - is unlimited, 1 - limited
  2. Create a global_geo_limiting_map that will map ip_limit_key to ip_limit_action
  3. Create global limit_req_zone called global_limit_zone that limits number of requests to 1r/s
  4. Apply global_limit_zone globally to all requests with 5 req burst.
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:

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.

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:

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:

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

Proxy buffering:

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

Let’s Encrypt:

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.

nginx:
  server:
    enabled: true
    site:
      mysite:
        ssl:
          enabled: true
          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.

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:

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:

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:

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):

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

or:

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):

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