~sirn/ansible-freebsd-s6-nginx

Ansible role for installing and configuring Nginx on S6-enabled FreeBSD host
config: allow ssl backend
config: allow *_backends without *_name
meta: rename dependencies to collections

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~sirn/ansible-freebsd-s6-nginx
read/write
git@git.sr.ht:~sirn/ansible-freebsd-s6-nginx

You can also use your local clone with git send-email.

#ansible-freebsd-s6-nginx

builds.sr.ht status

Configure Nginx for FreeBSD host using S6.

Requires ansible-freebsd-s6 to be applied first.

#Variables

#nginx_access_log
nginx_access_log: /dev/stderr

Specify where to output the access log. Using /dev/stderr allow Nginx error logs to be managed by s6-log which supports automatic log rotation (and many more).

#nginx_accf_http
nginx_accf_http: true

Enable kernel-level HTTP buffering module accf_http support in Nginx for HTTP request. Setting this to true may improve performance when dealing with slow clients as kernel will buffer the request preventing the application from performing buffering by themselves.

#nginx_accf_http_load
nginx_accf_http_load: true

Load and enable accf_http kernel module. Set this variable to false in jails.

#nginx_accf_data
nginx_accf_data: true

Enable kernel-level HTTP buffering module accf_http support in Nginx for non-HTTP request (e.g. HTTPS). Setting this to true may improve performance when dealing with slow clients as kernel will buffer the request preventing the application from performing buffering by themselves.

#nginx_accf_data_load
nginx_accf_data_load: true

Load and enable accf_data kernel module. Set this variable to false in jails.

#nginx_client_body_buffer_size
nginx_client_body_buffer_size: 32k

Configure the buffer size for reading client request body. Request larger than this value will be written to a temporary file.

#nginx_client_max_body_size
nginx_client_max_body_size: 128m

Configure the maximum size of a request body (e.g. max upload file size)

#nginx_cloudflare
nginx_cloudflare: false

Set real IP from header for clients connecting from IP addresses published by Cloudflare at the following URLs:

The list will be automatically updated every 7 days.

#nginx_cloudflare_logger
nginx_cloudflare_logger: |
    #!/usr/local/bin/execlineb -P
    s6-log -b n10 s1000000 t !"gzip -nq9" /var/log/nginx-cloudflare/

Configure a Cloudflare logger. See also s6-log.

#nginx_drop_privileges_early
nginx_drop_privileges_early: false

Drop Nginx privileges before launching Nginx process. Setting this to true may improve security as privilege is dropped via a smaller program (s6-setuidgid) rather than by Nginx itself. Must be set to false if nginx_accf_http or nginx_accf_data are set to true.

#nginx_error_log
nginx_error_log: /dev/stderr

Specify where to output the error log. Using /dev/stderr allow Nginx error logs to be managed by s6-log which supports automatic log rotation (and many more).

#nginx_error_log_level
nginx_error_log_level: info

Configure an error log level for Nginx.

#nginx_gzip_types
nginx_gzip_types:
    - application/json
    - text/css
    - text/javascript

Configure mime types to be compressed with gzip. Responses with text/html are always compressed.

#nginx_keepalive_timeout
nginx_keepalive_timeout: 120

Configure the keep alive timeout.

#nginx_http_port
nginx_http_port: 80

Configure Nginx HTTP port.

#nginx_https_port
nginx_https_port: 443

Configure Nginx HTTPS port.

#nginx_logger
nginx_logger: |
    #!/usr/local/bin/execlineb -P
    s6-log -b n10 s1000000 t !"gzip -nq9" /var/log/nginx/

Configure a Nginx logger. See also s6-log.

#nginx_ipv4
nginx_ipv4: true

Listens Nginx on IPv4 address.

#nginx_ipv6
nginx_ipv6: false

Listens Nginx on IPv6 address.

#nginx_server_names_hash_bucket_size
nginx_server_names_hash_bucket_size: 64

Configure bucket size for the server names hash tables. This should be configured to the processor's cache line size. See also Nginx documentation. (64 is usually a safe choice for modern processors.)

#nginx_sites
nginx_sites:

See Configuring Sites in the section below.

#nginx_types_hash_max_size
nginx_types_hash_max_size: 2048

Configure maximum size for the server names hash tables. This should be multiplication of nginx_server_names_hash_bucket_size.

#nginx_worker_connections
nginx_worker_connections: 256

Maximum number of simultaneous connections that can be opened by a worker process. Total limit of connections will be nginx_worker_connections multiply by nginx_worker_processes.

#nginx_worker_processes
nginx_worker_processes: 2

Number of worker processes. This should be set to the number of CPUs available, or set to auto to let Nginx automatically determine the number of CPUs.

#Configuring Sites

This Ansible playbook allows Nginx sites to be configured in YAML format. It has built-in support for most of the common Nginx configurations, for example:

nginx_sites:
    - secure: false
      default: true
      domain:
          - example.com
      locations:
          - path: /
            redirect_match: "^/(.*)$"
            redirect_target: "https://example.com/$1"

    - secure: true
      default: true
      dehydrated_cert: example.com
      root: /var/www
      domains:
          - example.com
      locations:
          - path: "~ \\.php$"
            fastcgi_connect_timeout: 3s
            fastcgi_backends:
                - 127.0.0.1:4123
          - path: "/foo"
            proxy_name: foo
            proxy_connect_timeout: 3s
            proxy_backends:
                - 127.0.0.1:8080 weight=5
                - 127.0.0.1:8081
#secure
secure: false

Configure whether to listen on HTTPS port. Note either cert and cert_key or dehydrated_cert must be configured.

#config
config: |
    # nginx config here

A free form configuration to be declared before location { } block.

#cert
cert: /path/to/cert.pem

Path to SSL certificate for this site.

#cert_key
cert_key: /path/to/cert.key

Path to SSL certificate key for this site.

#dehydrated_cert
dehydrated_cert: example.com

Automatically configure certificate and certificate key for Dehydrated-provisioned certificates, usually located at /usr/local/etc/dehydrated/certs. For use in conjunction with ansible-freebsd-s6-dehydrated.

#default
default: true

Indicate whether the site is a default_server, e.g. the site user will visit when vhosts are not found.

#domain
domain:
    - example.com

Domain names for this site.

#root
root: /var/www

Document root for the site.

#locations
locations:
    - path: "~ \\.php$"
      fastcgi_connect_timeout: 3s
      fastcgi_backends:
          - 127.0.0.1:4123
    - path: "/foo"
      proxy_name: foo
      proxy_connect_timeout: 3s
      proxy_backends:
          - 127.0.0.1:8080 weight=5
          - 127.0.0.1:8081

Declare a location block in Nginx configuration.

  • path declare a path to match, e.g. path in location <path> { ... } block. Can uses the following operators:
    • no operator will be treated as a prefix match (e.g. / matches all paths, /foo matches /foo, /foo/bar, etc.)
    • = path an exact match (e.g. / matches only /, /foo matches /foo but not /foo/bar, etc.)
    • ~ path a case sensitive regular expression match
    • ~* path a case insensitive regular expression match
    • ^~ path a negate regular expression match
#Redirection
locations:
    - path: /
      redirect_match: "^/(.*)$"
      redirect_target: "https://example.com/$1"

A simple redirect from redirect_match to redirect_target.

  • redirect_match matches the path, can be regular expression
  • redirect_target rewrite the path, can use $1 to substitute matching group
#Proxy
locations:
    - path: "/foo"
      proxy_name: foo
      proxy_connect_timeout: 3s
      proxy_backends:
          - 127.0.0.1:8080 weight=5
          - 127.0.0.1:8081
    - path: "/bar"
      proxy_name: bar

A proxy to backend. If proxy_name is presented, proxy_backends is required to be declared only once, otherwise proxy_backends is required. In the example above, /bar will reuse the backend configuration of /foo.

  • proxy_name a name of a backend to be declared in Nginx's upstream block
  • proxy_secure configure whether backend is SSL backend
  • proxy_backends list of backend servers; see also Nginx configuration
  • proxy_connection_upgrade enables HTTP upgrade for a location, required for WebSocket
  • proxy_read_timeout defines a timeout for reading a response from backend servers
  • proxy_connect_timeout defines a timeout for connecting to backend servers
#FastCGI
locations:
    - path: "~ \\.php$"
      fastcgi_name: php
      fastcgi_read_timeout: 3s
      fastcgi_connect_timeout: 3s
      fastcgi_backends:
          - 127.0.0.1:4123
          - unix:/var/run/php.sock
    - path: "~ \\.phps$"
      fastcgi_name: php

A connection to FastCGI process. If fastcgi_name is present, fastcgi_backends is required to be declared only once, otherwise fastcgi_backends is required. In the example above, .phps will reuse the backend configuration of .php.

  • fastcgi_name a name of a backend to be declared in Nginx's upstream block
  • fastcgi_backends list of backend servers; see also Nginx configuration
  • fastcgi_read_timeout defines a timeout for reading a response from backend
  • fastcgi_connect_timeout defines a timeout for connecting to backend
#Free-Form
locations:
    - path: /
      config: |
          # nginx config here

A free form configuration to be put inside location { } block.