Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rsanzante/ansible-nginx-server-block

This role configures a single site using server blocks (virtual hosts using Apache jargon).
https://github.com/rsanzante/ansible-nginx-server-block

ansible-role nginx server-block

Last synced: about 1 month ago
JSON representation

This role configures a single site using server blocks (virtual hosts using Apache jargon).

Host: GitHub
URL: https://github.com/rsanzante/ansible-nginx-server-block
Owner: rsanzante
Created: 2018-04-29T11:46:58.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2020-08-27T08:21:16.000Z (over 4 years ago)
Last Synced: 2023-09-25T20:51:53.216Z (over 1 year ago)
Topics: ansible-role, nginx, server-block
Language: Shell
Homepage:
Size: 84 KB
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# Ansible Role: Nginx Server Block
----------------------------------

This role configures a single site using server blocks (virtual hosts using
Apache jargon).

Work in progress, alpha quality, but usable. Only tested with Ansible 2.4, but
it might work with other Ansible releases.

It may work with other distros, just make sure you configure it properly, see
"Non Debian distros" section. In particular, it probably works with Alpine
Linux, but not tested yet.

A working Nginx should be configured, this role doesn't install it or configure
at the http block level.

**Features**

- Multiple listen configuration but allows simple common configuration.
- Multiple location configurations.
- Server restrictions and restrictions per location.
- Fine-grained configuration for site.
- SSL configuration (given cert and key files are available).
- HTTP2.
- Predefined location for certain features on site (block .ht*, block
source code files, block hidden directories, mask forbidden with 404, etc).

**Non Debian distros**

By default role is configured for Debian like distros that use
sites-available/sites-enabled directories. For other distros, like CentOS, you
have to set the following variables:

nsb_nginx_sites_available_path: conf.d
nsb_nginx_sites_enabled_path: conf.d
nsb_distro_allows_disabling_sites: no

The final configuration depends on your Nginx configuration.

If `nsb_distro_allows_disabling_sites` is yes, role deploys conf file in
`nsb_nginx_sites_available_path`, and then makes a symlink from
`nsb_nginx_sites_enabled_path` to conf file.

If `nsb_distro_allows_disabling_sites` is no, role deploys conf file in
`nsb_nginx_sites_enabled_path`, without making any symlink.

**Predefined locations**

This role provides some predefined locations that can be added to server block
locations. See ```nsb_locations```.

Keep in mind that those locations have certain match rules that can interfere
with other custom locations. First locations have higher priority. See
http://nginx.org/en/docs/http/ngx_http_core_module.html#location for more info.

- block_hidden_dirs: Blocks any hidden file or directory (those that begins with
a period. If nsb_feature_blocked_to_404 is set to yes a 404 is returned instead of a
403.

- block_apache_ht_files: Ignores Apache's .ht* files. Used when
nsb_feature_ignore_ht_files is enabled. You can add it to nsb_locations if you
prefer to control where it's placed.
If nsb_feature_blocked_to_404 is set to yes a 404 is returned instead of a
403.

- no_favicon_logging: Do not log accesses to favicon.ico. Used when
nsb_feature_dont_log_favicon is enabled. You can add it to nsb_locations if you
prefer to control where it's placed.

- no_robots_txt_logging: Do not log accesses to robots.txt. Used when
nsb_feature_dont_log_robots_txt is enabled. You can add it to nsb_locations if you
prefer to control where it's placed.

- images_bypass_basic_auth: Sometimes is interesting to allow access only to image files. For example, development environments protectec by Basic Auth could benefit from this so external services like email readers can access images embedded in the email body. Not all images bypass the Baisc Auth,m only the typical web content formats: JPEG, WebP, PNG, GIF and SVG.

- block_sensitive_files: Block certain files that may contain confidential information. For example: .sql, .mysql, .php, .install, .module, .yml, .orig, .json, .lock, etc.

**Restriction**

A restriction block can be assigned to the server or to any location.

Restrictions covers:
- Basic auth setup (with an existing htpassw file).
- Allow/disallow clauses.
- Change satisfy default value to 'any'.

See https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/.

Restriction block properties:

- satisfy_any: yes

If yes, a `satisfy any;` clause is added.

- deny_allow_list: []

List of allow/deny clauses.

- basic_auth_off: no

Disables the basic auth for this block. Not valid for server context, only for
location contexts. Used when there's a basic auth defined at server context
and you want to disable in a certain location. If `basic_auth_enabled` is
`yes` an error is triggered.

- basic_auth_enabled: no

Enable basic auth.

- basic_auth_name: null

Basic auth name. Mandatory when basic auth is enabled.

- basic_auth_passwd_filepath: null

htpasswd file with valid users. Mandatory when basic auth is enabled.

Restriction block example:

restriction:
satisfy_any: yes
deny_allow_list:
- deny 192.168.1.2
- allow 192.168.1.1/24
- allow 127.0.0.1
- deny all
basic_auth_enabled: yes
basic_auth_name: 'Restricted area'
basic_auth_passwd_filepath: '/etc/htpasswd/file'

## Requirements
---------------

This role doesn't deal with Nginx installation or general configuration so Nginx
must be installed in the system prior to using this role.

You can try for example this role to install Nginx: https://galaxy.ansible.com/HanXHX/nginx/
Or this one: https://galaxy.ansible.com/jdauphant/nginx/

## Role Variables
-----------------

#### Mandatory variables
------------------------

- nsb_domains: List of domains for this server block. At least one domain must
be present. The first domain will be considered the main domain for this
server block. Redirected domains will point to this main domain. Also,
it's used for generated identifiers and names, like the main configuration
file.

#### Mandatory when SSL is enabled
----------------------------------

- nsb_ssl_certificate_file: Path to certificate file.

- nsb_ssl_certificate_key_file: Path to certificate key file.

#### Optional/fine configuration variables (along with default value)
---------------------------------------------------------------------

- nsb_docroot_path:

Path to docroot. If not set means that this server block probably will be
a redirection, proxy or something similar.

- nsb_locations: []

List of server locations. Each location can have two forms. One is the custom
locatins and they have the following properties:

- match: Location's match clause. Mandatory.
Ex: `/`, `/status`, `^~ /images/`, `~* \.(gif|jpg|jpeg)$`

- body: Location's body, code inside the `{` and `}`. Mandatory.

- restriction: Restriction block attached to this location. See
**Restriction** section. This property is optional.

The second form is when you want to add predefined location. In that case only
a ```predefined``` property is needed. The proprerty should have the
predefined location name.

- nsb_server_block_enabled: yes

Enables configured server block. If set to no, configuration is not loaded by
Nginx. This disables the server block.

- nsb_ipv4_interface: '*'

IPv4 interface to listen to for HTTP and HTTPS.

- nsb_ipv6_interface: '*'

IPv6 interface to listen to for HTTP and HTTPS.

- nsb_listen_port: 80

Nginx will listen to this port for incoming HTTP
connections.

- nsb_ssl_listen_port: 443

Nginx will listen to this port for incoming HTTPS
connections.

- nsb_additional_listen_configuration: []

Complex listen configuration can be added to this variable if needed. See
defaults/main.yml to get the details.

- nsb_use_access_log_file_for_site: yes

Whether to use an access log file for this site or not.

- nsb_use_error_log_file_for_site: yes

Whether to use an error log file for this site or not.

- nsb_log_dir_path: /var/log/nginx

Directory where to put the log files.

- nsb_log_format_access: combined

Log format used for access log.

- nsb_log_error_level: error

Log level for error log.

- nsb_restriction: none

Server context restriction block. See **Restriction** section.

- nsb_server_additional_conf: null

Additional server block configuration. Use multiline syntax if more than one
line is needed.

#### Variables to enable certain features using location blocks (along with default value)
------------------------------------------------------------------------------------------

- nsb_feature_allow_well_known_rfc_5785: yes

Allows access to files under .well-known as stated in RFC 5785. If https is
enforced this makes sure files under .well-known are still available under
http.

- nsb_feature_ignore_ht_files: yes

Block access to Apache's .ht* files. If yes, the predefined location
block_apache_ht_files is added on top of custom locations. If you enable this
setting you shouldn't use the block_apache_ht_files location directly (don't
use in the nsb_locations array).

- nsb_feature_dont_log_favicon: yes

Do not log accesses to favicon.ico file. If yes, the predefined location
nsb_feature_dont_log_favicon is added on top of custom locations. If you enable
this setting you shouldn't use the no_favicon_logging location directly (don't
use in the nsb_locations array).

- nsb_feature_dont_log_robots_txt: yes

Do not log accesses to robotgs.txt file. If yes, the predefined location
nsb_feature_dont_log_robots_txt is added on top of custom locations. If you enable
this setting you shouldn't use the no_favicon_logging location directly (don't
use in the nsb_locations array).

- nsb_feature_blocked_to_404: yes

Instead of return a 403 on blocked URLs return a 404. Only valid for
block_apache_ht_files and block_hidden_dirs predefined locations.

#### More optional/fine configuration variables (along with default value)
--------------------------------------------------------------------------

- nsb_ipv4_interface: '*'

Interface for IPv4 connections. If '*' all interfaces are used. If None no
IPv4 interface is used.

- nsb_ipv6_interface: '*'

Interface for IPv6 connections. If '*' all interfaces are used. If None no
IPv6 interface is used.

- nsb_conf_file_owner: root

User to own configuration files.

- nsb_conf_file_group: www-data

Configuration files assigned group.

#### Other variables
--------------------

Optional Nginx configuration variables. Those variables DO NOT configure Nginx
but report the Nginx configuration to this role.

- nsb_nginx_conf_dir: /etc/nginx
- nsb_nginx_sites_available_path: sites-available
- nsb_nginx_sites_enabled_path: sites-enabled
- nsb_distro_allows_disabling_sites: yes

Dependencies
------------

No direct dependencies but as said above Nginx must be installed.

Example Playbook
----------------

Simplest block server with just one simple location.

- hosts: servers
roles:
- role: metadrop.nginx_server_block
nsb_domains:
- example.com
nsb_docroot_path: "/var/vhosts/example.com"
nsb_https_enabled: no
nsb_locations:
- match: "/"
body: |
index index.html index.htm;

Block server with more options, SSL and restriction applied.

- hosts: servers
roles:
- role: metadrop.nginx_server_block
nsb_domains:
- example.com
- www.example.com
nsb_docroot_path: "/var/vhosts/example.com"
nsb_https_enabled: yes
nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem
nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem
nsb_restriction:
satisfy_any: yes
deny_allow_list:
- deny 192.168.10.2
- allow 192.168.10.1/24
- allow 127.0.0.1
- deny all
basic_auth_enabled: yes
basic_auth_name: 'Restricted area'
basic_auth_passwd_filepath: '/etc/htpasswd/example.com/htpasswd'
nsb_locations:
- match: "/"
body: |
root /var/www/html;
index index.html index.htm;

Block server with a simple redirection to another domain.

- hosts: servers
roles:
- role: metadrop.nginx_server_block
nsb_domains:
- example-old.com
nsb_server_additional_conf: "return 301 https://example-new.com$request_uri;"
nsb_force_https: no

Block server that acts as a proxy cache. Note that web_backend proxy must be
defined in the Nginx config elsewhere.

# Add header to report cache misses and hits.
add_header X-Proxy-Cache $upstream_cache_status;
nsb_locations:
- match: "/"
body: "try_files $uri @proxy;"
- match: "@proxy"
body: |
limit_req zone=flood_protection burst=50 nodelay;
proxy_pass http://web_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-By $server_addr:$server_port;
proxy_set_header X-Local-Proxy $scheme;
proxy_set_header X-Forwarded-Proto $scheme;

proxy_pass_header Set-Cookie;
proxy_pass_header Cookie;
proxy_pass_header X-Accel-Expires;
proxy_pass_header X-Accel-Redirect;
proxy_pass_header X-This-Proto;

Block server with predefined locations and RFC 5785 option enabled.

- hosts: servers
roles:
- role: metadrop.nginx_server_block
nsb_domains:
- example.com
nsb_docroot_path: "/var/vhosts/example.com"
nsb_https_enabled: yes
nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem
nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem
nsb_feature_allow_well_known_rfc_5785: yes
nsb_locations:
- predefined: no_favicon_logging
- predefined: no_robots_txt_logging
- match: "/"
body: |
index index.html index.htm;

Same as previous example but using variables that enable configuration features
(in this case not logging accesses to robots.txt and favicon.ico.

- hosts: servers
roles:
- role: metadrop.nginx_server_block
nsb_domains:
- example.com
nsb_docroot_path: "/var/vhosts/example.com"
nsb_https_enabled: yes
nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem
nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem
nsb_feature_allow_well_known_rfc_5785: yes
nsb_feature_dont_log_robots_txt: yes
nsb_feature_dont_log_favicon: yes
nsb_locations:
- match: "/"
body: |
index index.html index.htm;

License
-------

GPL 3.0

Author Information
------------------

Ricardo Sanz [email protected]