docs: explain trouble with underscores in headers

docs/source/deploy.rst

@@ -246,20 +246,24 @@ to the newly created unix socket:
     After=network.target
 
     [Service]
+    # gunicorn can let systemd know when it is ready
     Type=notify
+    NotifyAccess=main
     # the specific user that our service will run as
     User=someuser
     Group=someuser
-    # another option for an even more restricted service is
-    # DynamicUser=yes
-    # see http://0pointer.net/blog/dynamic-users-with-systemd.html
+    # this user can be transiently created by systemd
+    # DynamicUser=true
     RuntimeDirectory=gunicorn
-    WorkingDirectory=/home/someuser/applicationroot
-    ExecStart=/usr/bin/gunicorn applicationname.wsgi
+    WorkingDirectory=~
+    # using the @ prefix, you can set venv path via argv[0]
+    ExecStart=@/usr/bin/python3 ${HOME}/bin/python3 -m gunicorn --chdir appdir applicationname.wsgi
     ExecReload=/bin/kill -s HUP $MAINPID
     KillMode=mixed
     TimeoutStopSec=5
     PrivateTmp=true
+    # if your app does not need administrative capabilities, let systemd know
+    # ProtectSystem=strict
 
     [Install]
     WantedBy=multi-user.target
@@ -272,11 +276,12 @@ to the newly created unix socket:
     [Socket]
     ListenStream=/run/gunicorn.sock
     # Our service won't need permissions for the socket, since it
-    # inherits the file descriptor by socket activation
-    # only the nginx daemon will need access to the socket
+    # inherits the file descriptor by socket activation.
+    # Only the nginx daemon will need access to the socket:
     SocketUser=www-data
-    # Optionally restrict the socket permissions even more.
-    # SocketMode=600
+    SocketGroup=www-data
+    # Once the user/group is correct, restrict the permissions:
+    SocketMode=0660
 
     [Install]
     WantedBy=sockets.target

docs/source/faq.rst

@@ -11,7 +11,9 @@ How do I set SCRIPT_NAME?
 -------------------------
 
 By default ``SCRIPT_NAME`` is an empty string. The value could be set by
-setting ``SCRIPT_NAME`` in the environment or as an HTTP header.
+setting ``SCRIPT_NAME`` in the environment or as an HTTP header. Note that
+this headers contains and underscore, so it is only accepted from trusted
+forwarders listed in the ``forwarded-allow-ips`` setting.
 
 
 Server Stuff

docs/source/news.rst

@@ -2,6 +2,16 @@
 Changelog
 =========
 
+22.0.1 - 2TBDTBDTBD
+===================
+
+- the SCRIPT_NAME header when received from allowed forwarders is no longer restricted for containing an underscore
+
+*** NOTE ***
+
+- This mitigates a regression that appeared first in the 22.0.0 release
+- Review your ``forwarded-allow-ips`` setting if you are still not seeing the SCRIPT_NAME transmitted
+
 22.0.0 - 2024-04-17
 ===================
 

gunicorn/config.py

@@ -2352,6 +2352,7 @@ def validate_header_map_behaviour(val):
     else:
         raise ValueError("Invalid header map behaviour: %s" % val)
 
+
 class ForwarderHeaders(Setting):
     name = "forwarder_headers"
     section = "Server Mechanics"