Skip to content

Bug 1849943: Add Apache and Nginx reverse proxy instructions - #190

Open
topunix wants to merge 4 commits into
bugzilla:mainfrom
topunix:bug-1849943
Open

topunix wants to merge 4 commits into
bugzilla:mainfrom
topunix:bug-1849943

Conversation

@topunix

@topunix topunix commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Part 1 of Bug 1849943 (docs still based on BMO instead of Harmony).

What

  • installing/apache.rst: replaces the TODO stub with reverse proxy instructions. Covers enabling mod_proxy/mod_proxy_http/mod_headers, a virtual host example, Debian/Ubuntu and Fedora/Red Hat paths, and the X-Forwarded-Proto header for TLS termination.
  • installing/nginx.rst: new file. web_server.rst already listed nginx in its toctree but the page didn't exist, which caused a Sphinx build warning.

Both pages match the existing Caddy page: proxy to 127.0.0.1:3001, and run the app with MOJO_REVERSE_PROXY=1.

Notes

  • Port 3001 comes from bugzilla.pl (MOJO_LISTEN default). Both pages mention the PORT override.
  • The Apache page uses a site/conf.d file and never touches the main httpd.conf.
  • The Nginx page calls out client_max_body_size. Nginx defaults to 1 MB, which would silently block larger attachment uploads.

Testing

Built locally with the pinned versions in docs/requirements.txt (full rebuild, sphinx-build -E). Both pages render. The nginx toctree warning is gone. Remaining warnings are pre-existing: the extension glob patterns (staged by makedocs.pl, not by plain sphinx-build) and two in integrating/auth-delegation.rst, which the next PR fixes.

Still to come on 1849943

A separate PR removing BMO-specific references across the docs (BMO test server links, example hostnames, dead mozilla.org links) and the remaining mod_perl instructions in the platform install pages.

Comment thread docs/en/rst/installing/apache.rst Resolved
Comment thread docs/en/rst/installing/nginx.rst Resolved
justdave
justdave previously approved these changes Oct 12, 2026

@mrenvoize mrenvoize left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes; the docs should not steer people into an insecure setup.

  1. bugzilla.pl:17 defaults MOJO_LISTEN to all interfaces, and the docs add MOJO_REVERSE_PROXY=1 without telling the reader to bind to loopback. Mojo then trusts the last X-Forwarded-For value (Transaction.pm:36-43), and remote_ip feeds API-key IP checks, cookie IP binding, rate limits and BlockIP. Direct access to the backend port would allow spoofing (inferred from reading, not tested). Please bind to 127.0.0.1 in the examples and say why.
  2. Links are built from urlbase, not X-Forwarded-Proto, so apache.rst:52-54 is misleading. Also Hostage.pm:57-68 returns 500 unless urlbase/inbound_proxies are set; neither is mentioned.
  3. The :443 vhost snippet is incomplete (no SSL directives, no ProxyPass).
  4. multiple-bugzilla.rst (in #191) has the same bind-address issue.

…inbound_proxies

Address review feedback on the reverse proxy docs.

Start the backend with MOJO_LISTEN on 127.0.0.1 in the Apache, Nginx
and Caddy pages instead of PORT, which listens on all interfaces. With
MOJO_REVERSE_PROXY=1 the app trusts forwarding headers from whatever
connects to it, so the backend port must not be reachable from other
hosts.

Correct the X-Forwarded-Proto wording: it tells Bugzilla a request
arrived over HTTPS, while most links come from urlbase. Complete the
Apache 443 virtual host with SSL directives and ProxyPass, and add a
port 80 redirect.

Add a "Settings for a proxied Bugzilla" section to the web server page
covering urlbase, inbound_proxies, and the 500 "Reverse Proxy is
Misconfigured" response, and point the stale inbound_proxies entry in
parameters.rst at it.
@topunix

topunix commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

Thanks Martin. Addressed in c2b65a8:

  1. Backend bind: the Apache, Nginx and Caddy pages now start the backend with MOJO_LISTEN=http://127.0.0.1:3001 instead of PORT, and say why. bugzilla.pl listens on all interfaces by default and with a bare PORT, and with MOJO_REVERSE_PROXY=1 the app trusts forwarding headers from whatever connects to it.

2a. X-Forwarded-Proto: reworded in apache.rst and the matching sentence in nginx.rst. The header tells Bugzilla the request arrived over HTTPS; most links come from urlbase.

2b. urlbase and inbound_proxies: added a "Settings for a proxied Bugzilla" section to web_server.rst, linked from all three proxy pages. Reading Hostage.pm, the 500 fires when urlbase is https, inbound_proxies is set, and the request is not seen as HTTPS. With inbound_proxies empty the check is skipped, so the section documents both cases. Both settings live in localconfig now, so I also replaced the stale inbound_proxies entry in parameters.rst with a pointer to the new section.

  1. The :443 vhost is now complete (ServerName, SSL directives, ProxyPreserveHost, ProxyPass, ProxyPassReverse), and I added a port 80 redirect, since proxying plain HTTP with an https urlbase hits the 500 above.

  2. multiple-bugzillas.rst: fixed in Bug 1849943: Remove BMO references and mod_perl/CGI install instructions #191 (b6a23be), since that PR owns the file.

Noticed while checking the code, not changed here: the remote_ip() POD in Bugzilla/Util.pm, setup/strings.txt.pl and the 3.x release notes template still describe inbound_proxies as controlling X-Forwarded-For trust, and essential-post-install-config.rst and moving.rst still call urlbase an admin parameter. I left those out to keep this PR to the proxy pages.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

4 participants