onaio - nginx

Ansible role which installs and configures Nginx, from a package or from source (including a series of optional modules).

Requirements & Dependencies

Ansible

It has been tested on Ansible 1.5 and above, and depends on the following roles:

• ANXS.apt
• ANXS.build-essential
• ANXS.perl
• ANXS.monit (if you want monit protection)

Platforms

Currently it's been developed for, and tested on Ubuntu. It is assumed to work on other Debian distributions as well.

Variables

default (nginx.conf)

• nginx_install_method - "source" or "package"

• nginx_user - user Nginx will run as

• nginx_uid - the uid for this user

• nginx_group - Nginx group

• nginx_gid - the gid for this group

• nginx_dir - location of the Nginx configuration (conf, sites-available, sites-enabled, ...)

• nginx_install_only - when set to true nginx will not be (re)started

• nginx_www_dir - location of the www root for Nginx sites

• nginx_log_dir - location of the Nginx logs

• nginx_pid - location of the Nginx PID file

• nginx_worker_processes - sets the number of worker processes

• nginx_daemon_disable - whether the daemon should be disabled which can be set to yes or no

• nginx_worker_rlimit_nofile - used for config value of worker_rlimit_nofile. Can replace any "ulimit -n" command. The value depend on your usage (cache or not) but must always be superior than worker_connections. Set to null to ignore

• nginx_error_log_options - option flags for the error_log

• nginx_error_log_filename - filename for the error log

• nginx_worker_connections - sets the number of worker connections

• nginx_multi_accept - used for config value of events { multi_accept }. Try to accept() as many connections as possible. Can be set to yes or no

• nginx_charset - used to specify an explicit default charset (say, 'utf-8', 'off'…)

• nginx_disable_access_log - whether or not to disable the access log, yes or no

• nginx_access_log_options - option flags for the access_log

• nginx_server_tokens - whether to send the Nginx version number in error pages and Server header, on or off

• nginx_event - used for config value of events { use }. Set the event-model. By default nginx looks for the most suitable method for your OS.

• nginx_sendfile - directive to activate or deactivate the usage of sendfile(), on or off

• nginx_keepalive - option whether to use the timeout options (below). Only the value "on" will include them

• nginx_keepalive_timeout - assigns the timeout for keep-alive connections with the client

• nginx_client_body_timeout - sets the read timeout for the request body from client

• nginx_client_header_timeout - specifies how long to wait for the client to send a request header

• nginx_send_timeout - specifies the response timeout to the client; it does not apply to the entire transfer but, rather, only between two subsequent client-read operations

• nginx_buffers - option whether to use the buffer options (below). Only the value "on" will include them

• client_body_buffer_size - specifies the client request body buffer size

• client_header_buffer_size - sets the headerbuffer size for the request header from client

• client_max_body_size - specifies the maximum accepted body size of a client request, as indicated by the request header Content-Length. Set to 0 to disable

• large_client_header_buffers - assigns the maximum number and size of buffers for large headers to read from client request

• nginx_server_names_hash_bucket_size - assigns the size of basket in the hash-tables of the names of servers. This value by default depends on the size of the line of processor cache

• nginx_types_hash_max_size -

• nginx_types_hash_bucket_size -

• nginx_proxy_read_timeout - defines a timeout (between two successive read operations) for reading a response from the proxied server.

• nginx_enable_rate_limiting - enable rate limiting, yes or no

• nginx_rate_limiting_zone_name - sets the shared memory zone

• nginx_rate_limiting_backoff - sets the maximum burst size of requests

• nginx_rate_limit - sets the rate (e.g. 1r/s)

• nginx_access_logs - a list of access log formats, filenames and options

    nginx_access_logs:
      - name: "main"
        format: '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'
        options: null
        filename: "access.log"
  
    #This will generate access_log /var/log/nginx/access.log combined
    nginx_access_logs:
      - name: "combined"
        filename: "access.log"
  

• nginx_default_root - the directory to place the default site

• nginx_default_enable - whether or not to actually enable the defaul site

source

• nginx_source_version - the version of Nginx to install
• nginx_source_url - URL for the Nginx source (versioned). By default it will get it from nginx_source_version
• nginx_source_prefix - prefix for installing nginx from source (versioned)
• nginx_source_conf_path - location of the main config file (in nginx_dir by default)
• nginx_source_default_configure_flags - the default configure flags (before adding the modules). By default, this sets --prefix, --conf-path and --sbin-path
• nginx_source_modules_included - see below
• nginx_source_modules_excluded - a list of configure flags to exclude modules. Example: ["mail_pop3_module", "mail_imap_module", "mail_smtp_module"]

nginx_source_modules_included is a dictionary (k,v) where k is the module name, and v its accompanying configure flag. All the possible options are given below:

nginx_source_modules_included:
  http_stub_status_module: "--with-http_stub_status_module"
  http_ssl_module: "--with-http_ssl_module"
  http_gzip_static_module: "--with-http_gzip_static_module"
  upload_progress_module: "--add-module=/tmp/nginx-upload-progress-module-{{nginx_upload_progress_version}}"
  headers_more_module: "--add-module=/tmp/headers-more-nginx-module-{{nginx_headers_more_version}}"
  http_auth_request_module: "--add-module=/tmp/ngx_http_auth_request_module-{{nginx_auth_request_release}}"
  http_echo_module: "--add-module=/tmp/echo-nginx-module-{{nginx_echo_version}}"
  google_perftools_module: "--with-google_perftools_module"
  ipv6_module: "--with-ipv6"
  http_real_ip_module: "--with-http_realip_module"
  http_spdy_module: "--with-http_spdy_module"
  http_perl_module: "--with-http_perl_module"
  naxsi_module: "--add-module=/tmp/naxsi-{{nginx_naxsi_version}}/naxsi_src"
  ngx_pagespeed: "--add-module=/tmp/ngx_pagespeed-release-{{nginx_ngx_pagespeed_version}}-beta"
  http_geoip_module: "--with-http_geoip_module"

Sites

There is a possibility to configure a list of servers to be available (not yet enabled) as well. Just provide a list of dictionaries according to the following format:

nginx_sites:
  - server:
      name: foo
      listen: 8080
      server_name: localhost
      ssl:
        enabled: true
        cert: "cert_file"
        key: "key_file"
        src_dir: "files"
        conf: "foo-ssl.conf"
        access_log_format: "{{ nginx_access_logs.0.name }}"
      location1:
        name: "/"
        try_files: "$uri $uri/ /index.html"
        sendfile: "on"
  - server:
      name: bar
      listen: 8888
      server_name: webmail.localhost
      ssl:
        enabled: false
      location1:
        name: /
        try_files: "$uri $uri/ /index.html"
      location2:
        name: /images/
        try_files: "$uri $uri/ /index.html"
        proxy_set_header:
         - header1 valA
         - header2 valB
  - server:
      name: baz
      listen: 443
      server_name: example.com
      ssl:
        enabled: true
        remote_src: yes
        cert: "cert.pem"
        key: "privkey.pem"
        src_dir: "/etc/letsencrypt/live/example.com"
        conf: "example.com.conf"
        create_symlink: true
      location1:
        name: "/"
        try_files: "$uri $uri/ /index.html"
        sendfile: "on"

The final example shows how to set multiple directives.

You can prevent the role from adding a semi-colon and a carriage return after a value defined in nginx_sites by prepending two underscores (__) to the key:

nginx_sites:
  - server:
      name: foo
      listen: 8080
      __server_name: localhost

The site file for the site defined above will not have a semi-colon and carriage return added after the value for "server_name";

To enable or disable specific sites you can add prior used server_name attribute to the variables nginx_enabled_sites and nginx_disabled_sites.

nginx_enabled_sites:
  - localhost

nginx_disabled_sites:
  - webmail.localhost

Load Balancers

You can configure load balancers using the nginx_loadbalancers varialbe. This will configure load balancers (with config files stored in /etc/nginx/conf.d) that you can choose to proxy_pass to:

Here are two example load balancers:

nginx_loadbalancers:
  - upstream_name: "lb1"
    method: least_conn
    hosts:
      - "127.0.0.1:8080"
      - "10.0.0.1:8080"
  - upstream_name: "lb2"
    method: least_conn
    hosts:
      - "127.0.0.1:9000"
      - "10.0.0.1:9000"

This role will create the files /etc/nginx/conf.d/load-balancer-lb1.conf and /etc/nginx/conf.d/load-balancer-lb2.conf. You can then proxy-pass to the load balancers using the NGINX proxy_pass directive (e.g proxy-pass http://lb1;. Use the equivalent ansible variable to achieve this in the site configuration described above.

Monit ?

You can put Nginx under monit monitoring protection, by setting monit_protection: yes

Basic Authentication

This role can generate password files that you can use with NGINX basic authentication. Specify the password files you want to generate in the nginx_basic_auth_files variable.

nginx_basic_auth_files:
  - path: "/etc/nginx/.htpasswd"
    users:
      - username: "admin"
        password: "somepassword"
        state: "present"
      - username: "old-admin"
        password: "somepassword"
        state: "absent"

You can then use a generate password file in your site configuration using the auth_basic_user_file directive.

Modules

Monitoring

• nginx_enable_monitoring - Whether or not to enable nginx status page that is used for monitoring.
• nginx_status_endpoint - url endpoint for the nginx status page. default is "status" which will allw you to access the status page when you load http://127.0.0.1/status

gzip module

• 'nginx_gzip' - whether to use gzip, can be "on" or "off"
• 'nginx_gzip_http_version'
• 'nginx_gzip_comp_level'
• 'nginx_gzip_proxied'
• 'nginx_gzip_vary'
• 'nginx_gzip_buffers'
• 'nginx_gzip_min_length'
• 'nginx_gzip_types'
• 'nginx_gzip_disable'

http_stub_status module

• nginx_remote_ip_var
• nginx_authorized_ips

http_gzip_static module

• nginx_gzip_static - whether to use gzip_static, can be on or off

upload_progress module

• nginx_upload_progress_version - version of the upload_progress module
• nginx_upload_progress_javascript_output- sets output in javascript. The default is true for backwards compatibility
• nginx_upload_progress_zone_name - assigns one name which will be used to store the per-connection tracking information. The default is proxied
• nginx_upload_progress_zone_size - assigns the zone size in bytes. Default is 1m (1 megabyte)

headers_more module

• nginx_headers_more_version - version of the headers_more module

http_auth_request module

• nginx_auth_request_release - the release number of the http_auth_request module

http_echo module

• nginx_echo_version - version of the http_echo module

http_realip module

• nginx_realip_header - Sets the header to use for the RealIp Module; only accepts "X-Forwarded-For" or "X-Real-IP"
• nginx_realip_addresses - Sets the addresses to use for the http_realip configuration
• nginx_realip_real_ip_recursive - If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the request header field. Can be on "on" or "off". The default is "off"

SSL Certificate passphrase

If your SSL key file is encrypted, you can add ssl_passphrase: "yourpassphrase" to the ssl object in your site configuration. The role will add a passphrase in the file specified by nginx_ssl_passphrase_path (default is /etc/nginx/passphrases) which is where NGINX will look for a password that can decrypt the SSL key specified.

ssl:
  enabled:   true
  src_dir: "files"
  cert: "certfile.crt"
  key: "encrypted-keyfile.key"
  ssl_passphrase: "mypassphrase"

naxsi module

• nginx_naxsi_version - version of the naxsi module

geoip module

• nginx_geoip: 'on'
• nginx_geoip_country: "{{nginx_dir}}/geoip/GeoIP.dat"
• nginx_geoip_city: "{{nginx_dir}}/geoip/GeoLiteCity.dat"

Thanks

To the contributors:

• Jean-Denis Vauguet

Testing

We use Molecule to run this role's tests. Use the following command to setup molecule on your machine:

pip install ansible molecule docker-py

To run the tests, run:

molecule test

License

Licensed under the MIT License. See the LICENSE file for details.

Feedback, bug-reports, requests, ...

Are welcome!

Credits

Based on ANXS.nginx!