{"id":21430737,"url":"https://github.com/rsanzante/ansible-nginx-server-block","last_synced_at":"2026-04-18T06:35:08.622Z","repository":{"id":196502451,"uuid":"131489988","full_name":"rsanzante/ansible-nginx-server-block","owner":"rsanzante","description":"This role configures a single site using server blocks (virtual hosts using Apache jargon).","archived":false,"fork":false,"pushed_at":"2020-08-27T08:21:16.000Z","size":86,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-16T22:13:10.975Z","etag":null,"topics":["ansible-role","nginx","server-block"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rsanzante.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-04-29T11:46:58.000Z","updated_at":"2022-10-13T16:40:03.000Z","dependencies_parsed_at":"2023-09-26T00:48:40.448Z","dependency_job_id":null,"html_url":"https://github.com/rsanzante/ansible-nginx-server-block","commit_stats":null,"previous_names":["rsanzante/ansible-nginx-server-block"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rsanzante/ansible-nginx-server-block","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsanzante%2Fansible-nginx-server-block","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsanzante%2Fansible-nginx-server-block/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsanzante%2Fansible-nginx-server-block/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsanzante%2Fansible-nginx-server-block/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rsanzante","download_url":"https://codeload.github.com/rsanzante/ansible-nginx-server-block/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsanzante%2Fansible-nginx-server-block/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31959881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible-role","nginx","server-block"],"created_at":"2024-11-22T22:28:33.893Z","updated_at":"2026-04-18T06:35:08.602Z","avatar_url":"https://github.com/rsanzante.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Role: Nginx Server Block\n----------------------------------\n\nThis role configures a single site using server blocks (virtual hosts using\nApache jargon).\n\nWork in progress, alpha quality, but usable. Only tested with Ansible 2.4, but\nit might work with other Ansible releases.\n\nIt may work with other distros, just make sure you configure it properly, see\n\"Non Debian distros\" section. In particular, it probably works with Alpine\nLinux, but not tested yet.\n\nA working Nginx should be configured, this role doesn't install it or configure\nat the http block level.\n\n**Features**\n\n  - Multiple listen configuration but allows simple common configuration.\n  - Multiple location configurations.\n  - Server restrictions and restrictions per location.\n  - Fine-grained configuration for site.\n  - SSL configuration (given cert and key files are available).\n  - HTTP2.\n  - Predefined location for certain features on site (block .ht*, block\n    source code files, block hidden directories, mask forbidden with 404, etc).\n\n\n**Non Debian distros**\n\nBy default role is configured for Debian like distros that use\nsites-available/sites-enabled directories. For other distros, like CentOS, you\nhave to set the following variables:\n\n    nsb_nginx_sites_available_path: conf.d\n    nsb_nginx_sites_enabled_path: conf.d\n    nsb_distro_allows_disabling_sites: no\n\nThe final configuration depends on your Nginx configuration.\n\nIf `nsb_distro_allows_disabling_sites` is yes, role deploys conf file in\n`nsb_nginx_sites_available_path`, and then makes a symlink from\n`nsb_nginx_sites_enabled_path` to conf file.\n\nIf `nsb_distro_allows_disabling_sites` is no, role deploys conf file in\n`nsb_nginx_sites_enabled_path`, without making any symlink.\n\n\n**Predefined locations**\n\nThis role provides some predefined locations that can be added to server block\nlocations. See ```nsb_locations```.\n\nKeep in mind that those locations have certain match rules that can interfere\nwith other custom locations. First locations have higher priority. See\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#location for more info.\n\n- block_hidden_dirs: Blocks any hidden file or directory (those that begins with\n a period. If nsb_feature_blocked_to_404 is set to yes a 404 is returned instead of a\n  403.\n\n- block_apache_ht_files: Ignores Apache's .ht* files. Used when\n  nsb_feature_ignore_ht_files is enabled. You can add it to nsb_locations if you\n  prefer to control where it's placed.\n  If nsb_feature_blocked_to_404 is set to yes a 404 is returned instead of a\n  403.\n\n- no_favicon_logging: Do not log accesses to favicon.ico. Used when\n  nsb_feature_dont_log_favicon is enabled. You can add it to nsb_locations if you\n  prefer to control where it's placed.\n\n\n- no_robots_txt_logging: Do not log accesses to robots.txt. Used when\n  nsb_feature_dont_log_robots_txt is enabled. You can add it to nsb_locations if you\n  prefer to control where it's placed.\n\n- 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.\n\n- block_sensitive_files: Block certain files that may contain confidential information. For example: .sql, .mysql, .php, .install, .module, .yml, .orig, .json, .lock, etc.\n\n**Restriction**\n\nA restriction block can be assigned to the server or to any location.\n\nRestrictions covers:\n  - Basic auth setup (with an existing htpassw file).\n  - Allow/disallow clauses.\n  - Change satisfy default value to 'any'.\n\nSee https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/.\n\nRestriction block properties:\n\n- satisfy_any: yes\n\n  If yes, a `satisfy any;` clause is added.\n\n- deny_allow_list: []\n\n  List of allow/deny clauses.\n\n- basic_auth_off: no\n\n  Disables the basic auth for this block. Not valid for server context, only for\n  location contexts. Used when there's a basic auth defined at server context\n  and you want to disable in a certain location. If `basic_auth_enabled` is\n  `yes` an error is triggered.\n\n- basic_auth_enabled: no\n\n  Enable basic auth.\n\n- basic_auth_name: null\n\n  Basic auth name. Mandatory when basic auth is enabled.\n\n- basic_auth_passwd_filepath: null\n\n  htpasswd file with valid users. Mandatory when basic auth is enabled.\n\nRestriction block example:\n\n    restriction:\n      satisfy_any: yes\n      deny_allow_list:\n        - deny 192.168.1.2\n        - allow 192.168.1.1/24\n        - allow 127.0.0.1\n        - deny all\n      basic_auth_enabled: yes\n      basic_auth_name: 'Restricted area'\n      basic_auth_passwd_filepath: '/etc/htpasswd/file'\n\n\n\n\n\n## Requirements\n---------------\n\nThis role doesn't deal with Nginx installation or general configuration so Nginx\nmust be installed in the system prior to using this role.\n\nYou can try for example this role to install Nginx: https://galaxy.ansible.com/HanXHX/nginx/\nOr this one: https://galaxy.ansible.com/jdauphant/nginx/\n\n\n## Role Variables\n-----------------\n\n#### Mandatory variables\n------------------------\n\n- nsb_domains: List of domains for this server block. At least one domain must\n  be present. The first domain will be considered the main domain for this\n  server block. Redirected domains will point to this main domain. Also,\n  it's used for generated identifiers and names, like the main configuration\n  file.\n\n#### Mandatory when SSL is enabled\n----------------------------------\n\n- nsb_ssl_certificate_file: Path to certificate file.\n\n- nsb_ssl_certificate_key_file: Path to certificate key file.\n\n\n#### Optional/fine configuration variables (along with default value)\n---------------------------------------------------------------------\n\n- nsb_docroot_path:\n\n  Path to docroot. If not set means that this server block probably will be\n  a redirection, proxy or something similar.\n\n- nsb_locations: []\n\n  List of server locations. Each location can have two forms. One is the custom\n  locatins and they have the following properties:\n\n  - match: Location's  match clause. Mandatory.\n    Ex: `/`, `/status`, `^~ /images/`, `~* \\.(gif|jpg|jpeg)$`\n\n  - body: Location's body, code inside the `{` and `}`. Mandatory.\n\n  - restriction: Restriction block attached to this location. See\n  **Restriction** section. This property is optional.\n\n  The second form is when you want to add predefined location. In that case only\n  a ```predefined``` property is needed. The proprerty should have the\n  predefined location name.\n\n- nsb_server_block_enabled: yes\n\n  Enables configured server block. If set to no, configuration is not loaded by\n  Nginx. This disables the server block.\n\n- nsb_ipv4_interface: '*'\n\n  IPv4 interface to listen to for HTTP and HTTPS.\n\n- nsb_ipv6_interface: '*'\n\n  IPv6 interface to listen to for HTTP and HTTPS.\n\n- nsb_listen_port: 80\n\n  Nginx will listen to this port for incoming HTTP\n  connections.\n\n- nsb_ssl_listen_port: 443\n\n  Nginx will listen to this port for incoming HTTPS\n  connections.\n\n- nsb_additional_listen_configuration: []\n\n  Complex listen configuration can be added to this variable if needed. See\n  defaults/main.yml to get the details.\n\n- nsb_use_access_log_file_for_site: yes\n\n  Whether to use an access log file for this site or not.\n\n- nsb_use_error_log_file_for_site: yes\n\n  Whether to use an error log file for this site or not.\n\n- nsb_log_dir_path: /var/log/nginx\n\n  Directory where to put the log files.\n\n- nsb_log_format_access: combined\n\n  Log format used for access log.\n\n- nsb_log_error_level: error\n\n  Log level for error log.\n\n- nsb_restriction: none\n\n  Server context restriction block. See **Restriction** section.\n\n- nsb_server_additional_conf: null\n\n  Additional server block configuration. Use multiline syntax if more than one\n  line is needed.\n\n\n#### Variables to enable certain features using location blocks (along with default value)\n------------------------------------------------------------------------------------------\n\n- nsb_feature_allow_well_known_rfc_5785: yes\n\n  Allows access to files under .well-known as stated in RFC 5785. If https is\n  enforced this makes sure files under .well-known are still available under\n  http.\n\n- nsb_feature_ignore_ht_files: yes\n\n  Block access to Apache's .ht* files. If yes, the predefined location\n  block_apache_ht_files is added on top of custom locations. If you enable this\n  setting you shouldn't use the block_apache_ht_files location directly (don't\n  use in the nsb_locations array).\n\n- nsb_feature_dont_log_favicon: yes\n\n  Do not log accesses to favicon.ico file. If yes, the predefined location\n  nsb_feature_dont_log_favicon is added on top of custom locations. If you enable\n  this setting you shouldn't use the no_favicon_logging location directly (don't\n  use in the nsb_locations array).\n\n- nsb_feature_dont_log_robots_txt: yes\n\n  Do not log accesses to robotgs.txt file. If yes, the predefined location\n  nsb_feature_dont_log_robots_txt is added on top of custom locations. If you enable\n  this setting you shouldn't use the no_favicon_logging location directly (don't\n  use in the nsb_locations array).\n\n- nsb_feature_blocked_to_404: yes\n\n  Instead of return a 403 on blocked URLs return a 404. Only valid for\n  block_apache_ht_files and block_hidden_dirs predefined locations.\n\n\n#### More optional/fine configuration variables (along with default value)\n--------------------------------------------------------------------------\n\n- nsb_ipv4_interface: '*'\n\n  Interface for IPv4 connections. If '*' all interfaces are used. If None no\n  IPv4 interface is used.\n\n- nsb_ipv6_interface: '*'\n\n  Interface for IPv6 connections. If '*' all interfaces are used. If None no\n  IPv6 interface is used.\n\n- nsb_conf_file_owner: root\n\n  User to own configuration files.\n\n- nsb_conf_file_group: www-data\n\n  Configuration files assigned group.\n\n#### Other variables\n--------------------\n\nOptional Nginx configuration variables. Those variables DO NOT configure Nginx\nbut report the Nginx configuration to this role.\n\n- nsb_nginx_conf_dir: /etc/nginx\n- nsb_nginx_sites_available_path: sites-available\n- nsb_nginx_sites_enabled_path: sites-enabled\n- nsb_distro_allows_disabling_sites: yes\n\n\nDependencies\n------------\n\nNo direct dependencies but as said above Nginx must be installed.\n\n\nExample Playbook\n----------------\n\n\nSimplest block server with just one simple location.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example.com\n          nsb_docroot_path: \"/var/vhosts/example.com\"\n          nsb_https_enabled: no\n          nsb_locations:\n            - match: \"/\"\n              body: |\n                index  index.html index.htm;\n\n\nBlock server with more options, SSL and restriction applied.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example.com\n            - www.example.com\n          nsb_docroot_path: \"/var/vhosts/example.com\"\n          nsb_https_enabled: yes\n          nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem\n          nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem\n          nsb_restriction:\n            satisfy_any: yes\n            deny_allow_list:\n              - deny 192.168.10.2\n              - allow 192.168.10.1/24\n              - allow 127.0.0.1\n              - deny all\n            basic_auth_enabled: yes\n            basic_auth_name: 'Restricted area'\n            basic_auth_passwd_filepath: '/etc/htpasswd/example.com/htpasswd'\n          nsb_locations:\n            - match: \"/\"\n              body: |\n                root   /var/www/html;\n                index  index.html index.htm;\n\n\nBlock server with a simple redirection to another domain.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example-old.com\n          nsb_server_additional_conf: \"return 301 https://example-new.com$request_uri;\"\n          nsb_force_https: no\n\n\nBlock server that acts as a proxy cache. Note that web_backend proxy must be\ndefined in the Nginx config elsewhere.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example.com\n            - www.example.com\n          nsb_docroot_path: \"/var/vhosts/example.com\"\n          nsb_https_enabled: yes\n          nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem\n          nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem\n          nsb_server_additional_conf: |\n            # Enable proxy cache.\n            proxy_cache general_cache;\n\n            # Add header to report cache misses and hits.\n            add_header X-Proxy-Cache $upstream_cache_status;\n          nsb_locations:\n            - match: \"/\"\n              body: \"try_files $uri @proxy;\"\n            - match: \"@proxy\"\n              body: |\n                limit_req zone=flood_protection burst=50 nodelay;\n                proxy_pass http://web_backend;\n                proxy_set_header  Host $host;\n                proxy_set_header  X-Real-IP $remote_addr;\n                proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;\n                proxy_set_header  X-Forwarded-By    $server_addr:$server_port;\n                proxy_set_header  X-Local-Proxy     $scheme;\n                proxy_set_header  X-Forwarded-Proto $scheme;\n\n                proxy_pass_header Set-Cookie;\n                proxy_pass_header Cookie;\n                proxy_pass_header X-Accel-Expires;\n                proxy_pass_header X-Accel-Redirect;\n                proxy_pass_header X-This-Proto;\n\n\n\nBlock server with predefined locations and RFC 5785 option enabled.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example.com\n          nsb_docroot_path: \"/var/vhosts/example.com\"\n          nsb_https_enabled: yes\n          nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem\n          nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem\n          nsb_feature_allow_well_known_rfc_5785: yes\n          nsb_locations:\n            - predefined: no_favicon_logging\n            - predefined: no_robots_txt_logging\n            - match: \"/\"\n              body: |\n                index  index.html index.htm;\n\n\n\nSame as previous example but using variables that enable configuration features\n(in this case not logging accesses to robots.txt and favicon.ico.\n\n    - hosts: servers\n      roles:\n        - role: metadrop.nginx_server_block\n          nsb_domains:\n            - example.com\n          nsb_docroot_path: \"/var/vhosts/example.com\"\n          nsb_https_enabled: yes\n          nsb_ssl_certificate_file: /var/ssl/certs/example.com/fullchain.pem\n          nsb_ssl_certificate_key_file: /var/ssl/certs/example.com/privatekey.pem\n          nsb_feature_allow_well_known_rfc_5785: yes\n        nsb_feature_dont_log_robots_txt: yes\n        nsb_feature_dont_log_favicon: yes\n          nsb_locations:\n            - match: \"/\"\n              body: |\n                index  index.html index.htm;\n\n\n\n\nLicense\n-------\n\nGPL 3.0\n\nAuthor Information\n------------------\n\nRicardo Sanz ricardo@metadrop.net\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsanzante%2Fansible-nginx-server-block","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frsanzante%2Fansible-nginx-server-block","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsanzante%2Fansible-nginx-server-block/lists"}