diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index d5b738fb60826a13e465966baa8383fe1b35a227..da0bd1af4f28f5efbc7411f39968e174cdc3289e 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -86,6 +86,9 @@ Debian 12 Bookworm. Some minor improvements and fixes. * Environment indicator can now be collapsed by clicking on the arrows on the left side. + * Added parameter ``http_header_overrides`` which can be used to + set/override request's HTTP headers before passing it on to the + PHP application. * ``mail_server`` role diff --git a/docs/rolereference.rst b/docs/rolereference.rst index a21b98b6edf52cb8bd66b46e88181ab4d9b111d6..61519d65b941d09cd98a71c1db53f524b579ad73 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -1661,6 +1661,31 @@ Parameters succession, until the first match, or until it runs out of matches, when a client requests an URI pointing to directory. +**http_header_overrides** (dict, optional, ``{}``) + HTTP headers to set/override on the incoming request before passing + it on to the PHP application. Keys are HTTP header names, values are + header values. + + .. note:: + Role takes care of prefixing the headers with ``HTTP_``, + converting them to upper-case, and replacing dashes with + underscores - simply pass in the official HTTP header name, no + extra precautions are required for PHP specifics. + + Double quotes in the value must be escaped with a backslash. Make + sure to take into account the YAML escaping as well. For example, to + set the value to ``this is quote - "``, YAML should look like one of + the following: + + - ``this is double quote - "`` + - ``'this is double quote - \"'`` + - ``"this is double quote - \\\"'`` + + To clear a header value, simply set its value to an empty + string. Nginx variables can be used as well, however keep in mind + that the dollar sign (``$``) *cannot* be used/escaped due to Nginx + configuration file syntax limitations. + **https_tls_certificate** (string, mandatory) X.509 certificate used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``. diff --git a/docs/usage.rst b/docs/usage.rst index d8825e8a866747b34ab20e2c0b07cdb936a7e3c4..df465c4fb60bba6f82edafa034793326fcb5ee17 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1417,6 +1417,10 @@ Before we start, here is a couple of useful pointers regarding the * If you ever need to set some additional PHP FPM settings, this can easily be done via the ``additional_fpm_config`` role parameter. This particular example does not set any, though. +* Incoming request headers can be set/overridden using the + ``http_header_overrides`` parameter. This can be useful for + manipulating headers in specifics ways, such as disabling + compression etc. on the application side. * Mails delivered to local admin/application users are forwarded to ``root`` account (configurable via ``website_mail_recipients`` role parameter. diff --git a/roles/php_website/defaults/main.yml b/roles/php_website/defaults/main.yml index e8bfbfb57e3d4ea6b5b799f607fc216a3fd5030f..1f8c5b4f17b2dbac5bc93cb8337622e7d0e55daf 100644 --- a/roles/php_website/defaults/main.yml +++ b/roles/php_website/defaults/main.yml @@ -10,6 +10,7 @@ rewrites: [] additional_fpm_config: {} website_mail_recipients: "root" environment_indicator: null +http_header_overrides: {} # Internal parameters. php_fpm_service_name_per_release: diff --git a/roles/php_website/molecule/default/playbook.yml b/roles/php_website/molecule/default/playbook.yml index 7d385bb9653a4c761bd565d107316ef2c2478b07..9e628e02fad63b87c15e014ca273952bce9081bd 100644 --- a/roles/php_website/molecule/default/playbook.yml +++ b/roles/php_website/molecule/default/playbook.yml @@ -39,6 +39,8 @@ php_rewrite_urls: - ^/rewrite1/(.*)$ /rewrite.myphp?url=$1 last - ^/rewrite2/(.*)$ /rewrite.myphp?url=$1 last + http_header_overrides: + Accept-Encoding: 'donotencode' rewrites: - '^/rewrite_to_index1/(.*) /myindex.php last' - '^/rewrite_to_index2/(.*) /myindex.php last' @@ -95,3 +97,4 @@ - info.myphp - 404.myphp - rewrite.myphp + - headers.myphp diff --git a/roles/php_website/molecule/default/tests/data/php/optional/headers.myphp b/roles/php_website/molecule/default/tests/data/php/optional/headers.myphp new file mode 100644 index 0000000000000000000000000000000000000000..1a3a6a178c2417fe0d8b271cdc023d78ed8e1fd0 --- /dev/null +++ b/roles/php_website/molecule/default/tests/data/php/optional/headers.myphp @@ -0,0 +1,7 @@ + $value) { + echo "$name: $value\n"; +} + +?> diff --git a/roles/php_website/molecule/default/tests/test_parameters_optional.py b/roles/php_website/molecule/default/tests/test_parameters_optional.py index f838838ac419a5a3e7be6d7a3154b39047faee09..9a992d7085d9f87ec3f113905b0afa34b7e51afb 100644 --- a/roles/php_website/molecule/default/tests/test_parameters_optional.py +++ b/roles/php_website/molecule/default/tests/test_parameters_optional.py @@ -270,3 +270,15 @@ def test_regular_rewrites(host): assert page.rc == 0 assert page.stdout == open("tests/data/php/optional/myindex.php").read().rstrip() + + +def test_http_header_overrides(host): + """ + Tests if headers are overridden by Nginx prior to hitting the PHP + application. + """ + + page = host.run('curl -H "Accept-Encoding: plain" https://parameters-optional.local/headers.myphp') + + assert page.rc == 0 + assert "Accept-Encoding: donotencode" in page.stdout.split("\n") diff --git a/roles/php_website/templates/nginx_site.j2 b/roles/php_website/templates/nginx_site.j2 index 84eaf22f5a33078f6107649875d3f70058606399..fb0d12b9e467448fb5b10633543bbed35d84a342 100644 --- a/roles/php_website/templates/nginx_site.j2 +++ b/roles/php_website/templates/nginx_site.j2 @@ -48,6 +48,11 @@ server { location ~ {{ php_file_regex }} { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/{{ fqdn }}.sock; + + {% for header, value in http_header_overrides | dictsort -%} + fastcgi_param {{ 'HTTP_' + header.replace('-', '_').upper() }} "{{ value }}"; + {% endfor -%} + } # Serve the files.