geerlingguy.ansible-role-nginx

If the standard variables do not expose a specific Nginx option, you can override the templates used to generate the nginx.conf or virtual host files.

1. Set nginx_conf_template or nginx_vhost_template to the path of your custom template.
2. Use Jinja2 template inheritance ({% extends ... %}) to extend the existing role templates and override specific blocks (e.g., {% block http_gzip %}).

You can also set a custom template on a per-vhost basis within the nginx_vhosts list.

# Global override
nginx_conf_template: "{{ playbook_dir }}/templates/nginx.conf.j2"

# Per-vhost override
nginx_vhosts:
  - server_name: "site1.example.com"
    template: "{{ playbook_dir }}/templates/site1.example.com.vhost.j2"

{# Example child template extending the role template #}
{% extends 'roles/geerlingguy.nginx/templates/nginx.conf.j2' %}

{% block http_gzip %}
    gzip on;
    gzip_proxied any;
    # ... other gzip settings
{% endblock %}

The nginx_vhosts variable is a list of dictionaries used to define Nginx server blocks. Each entry creates a separate configuration file named after the server_name.

Important Considerations:

• Filename Collisions: If you have multiple vhosts with the same domain (e.g., one for port 80 and one for port 443), you must manually set the filename key to prevent one from overriding the other.
• Indentation for extra_parameters: When using a multi-line block for extra_parameters, use a 2-space indent for the first line, and indent subsequent lines relative to that first line. This ensures the generated Nginx config is correctly indented with 4 spaces.
• Customization: If you require extensive customization beyond the provided keys, it is recommended to set nginx_vhosts: [] and manage your own .conf files manually.

nginx_vhosts:
  - listen: "443 ssl http2"
    server_name: "example.com"
    server_name_redirect: "www.example.com"
    root: "/var/www/example.com"
    index: "index.php index.html index.htm"
    error_page: ""
    access_log: ""
    error_log: ""
    state: "present"
    template: "{{ nginx_vhost_template }}"
    filename: "example.com.conf"
    extra_parameters: |
      location ~ \.php$ {
          fastcgi_split_path_info ^(.+\.php)(/.+)$;
          fastcgi_pass unix:/var/run/php5-fpm.sock;
          fastcgi_index index.php;
          fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
          include fastcgi_params;
      }
      ssl_certificate     /etc/ssl/certs/ssl-cert-snakeoil.pem;
      ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
      ssl_protocols       TLSv1.1 TLSv1.2;
      ssl_ciphers         HIGH:!aNULL:!MD5;

  - listen: "80"
    server_name: "example.com www.example.com"
    return: "301 https://example.com$request_uri"
    filename: "example.com.80.conf"

The following variables are available for configuring the Nginx role. Refer to defaults/main.yml for default values.

# Connection & Performance
nginx_listen_ipv6: true
nginx_user: "nginx"
nginx_worker_processes: "{{ ansible_processor_vcpus|default(ansible_processor_count) }}"
nginx_worker_connections: "1024"
nginx_multi_accept: "off"
nginx_keepalive_timeout: "65"
nginx_keepalive_requests: "100"

# Logging
nginx_error_log: "/var/log/nginx/error.log warn"
nginx_access_log: "/var/log/nginx/access.log main buffer=16k flush=2m"
nginx_log_format: "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $http_x_forwarded_for"

# Optimization & TCP
nginx_sendfile: "on"
nginx_tcp_nopush: "on"
nginx_tcp_nodelay: "on"
nginx_client_max_body_size: "64m"
nginx_server_names_hash_bucket_size: "64"

# Security & Headers
nginx_server_tokens: "on"

# Proxy & Cache
nginx_proxy_cache_path: ""

# Global Configuration Injection
nginx_extra_http_options: ""
nginx_extra_conf_options: ""

# Distribution Specifics
nginx_default_release: "" # Debian/Ubuntu only
nginx_ppa_use: false       # Ubuntu only
nginx_ppa_version: stable   # Ubuntu only
nginx_yum_repo_enabled: true # RedHat/CentOS only
nginx_zypper_repo_enabled: true # Suse only

# Service Management
nginx_service_state: started
nginx_service_enabled: yes

# Virtual Host Management
nginx_vhosts: []
nginx_remove_default_vhost: false
nginx_upstreams: []