Gitiles
Code Review Sign In
gerrit.mcp.mirantis.com / salt-formulas / nginx / 6dfc424a1ba19a5e540b8cde07725d9c594e845f / . / README.rst
blob: 630b919db994b81a4dbcba056aa301059ae64e71 [file] [log] [blame]
=============
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
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/