Skip to Content

Published

Complete the NginX proxy subtree with its HTTPS and Windows pages, and fix the SSH tunneling page

Last modified by Eleni Cojocariu on 2026/08/18 11:56

Follow-up to Correct the NginX proxy pages and the Tomcat proxy-headers page, now merged, which left three scope questions to the reviewer. This change answers the first two of them: the NginX subtree stopped at plain HTTP on port 80, with no HTTPS page at all, and its single procedure carried the Windows variant of most steps, which is what made it read half again as long as its Apache counterpart. Six file changes, one of them a new page; nothing deleted, nothing renamed.

Everything below was verified against NginX 1.24.0 proxying a live XWiki 18.4.3, with the three blocks taken verbatim out of the proposed pages by the harness rather than retyped into it (nginxverify3.sh, which never touches a system NginX: it runs nginx -p on ports 8081 and 8444).

The subtree now mirrors the Apache one

The Apache subtree has a reference page, one procedure per operating system and an HTTPS procedure. The NginX subtree had a reference page and one procedure. It now has the same four pages:

  • Configure NginX Server as a Proxy on a Linux OS is the existing procedure with its Windows clauses taken out of steps 3 to 6 and out of two FAQ answers, and retitled after its Apache twin ("Set up NginX Proxy Server" said neither which server nor which system).
  • Configure NginX Server as a Proxy on a Windows OS is new, and mirrors configure-apache-server-windows: the archive, the single conf\nginx.conf, prefix-relative log paths, start nginx and nginx -s reload.
  • Configure HTTPS for the NginX HTTP Proxy Server is the configurations page rewritten, and mirrors configure-https.
  • The reference page gains the HTTPS Directives and Redirection Directives tables it was missing, so that every directive the two new blocks use is documented where the others are.

The HTTPS page was not usable as it stood

It was typed explanation and titled "More Configurations for the NginX HTTP Proxy Server", but it held one subject only, which is HTTPS; it is a howto now, titled after the Apache page it parallels. What it shipped could not be followed:

  • ssl on; was made obsolete in NginX 1.15.0 and removed in 1.25.1, so the block fails outright on any current NginX; on 1.24.0 it still starts, with a deprecation warning. The ssl parameter of listen is what replaces it, and the proposed block uses it.
  • Neither code block was closed, and neither server block was complete: the first ended on the line "...the rest of the configuration remains the same (Headers, WebSocket, Redirection of root to /xwiki)...", inside the code macro, and the second ended after its return line. A reader could not copy either one.
  • The redirect had no exception for /.well-known, so it redirected the challenge an ACME client answers to renew the certificate, which breaks automatic renewal. The Apache page was given that exception by the first change request; this one now has its NginX equivalent, and it is a location ^## because a plain prefix loses to any regular-expression location the block may also hold (measured: 403 against 200).
  • xwiki.home was given as xwiki.home=https://localhost/xwiki, which is wrong twice over, since the property takes the public base address without the /xwiki path. It reads xwiki.home=https://wiki.example.com/ now, as on the Apache page.
  • The 443 block repeated no proxy directive, so anything a reader assembled from it lost the forwarded headers, the WebSocket tunnel and the body-size limit that the port 80 block had been given. It carries all of them now, and X-Forwarded-Proto needs no second value: it is written $scheme, so it reports https by itself.

What the harness measured

  • Served through the proposed 443 block, the wiki reports https://wiki.example.com:8444/xwiki/bin/view/Main/ as its own absolute URL, scheme, host and port included.
  • The port 80 block answers 301, and an encoded slash survives the redirect: /xwiki/bin/view/Main/A%2FB is redirected to the same path, still encoded, because $request_uri is the request as it arrived. This is what the Apache rule needs its [NE] flag for.
  • The ACME challenge answers 200 over plain HTTP while everything else is redirected.
  • The redirect must use $host where the proxy headers must use $http_host, which is the exact opposite of the previous change request's first finding and the reason it is a FAQ answer rather than a silent choice: reached on port 8081, the $http_host form answers Location: https://wiki.example.com:8081/, which is an https address carrying the port of the plain HTTP listener.
  • A location declaring an add_header of its own inherits none of the outer ones, so the Strict-Transport-Security header a reader adds to the server block never reaches /xwiki. The FAQ answer says so.
  • Keeping the server block the Windows archive ships, next to the wiki's, leaves nginx -t answering "test is successful" with only a [warn] line, and the stock welcome page answering on every URL. That is why the Windows step says to replace it.

Reverse Proxy and SSH Tunneling

Untouched by both earlier change requests, and carrying three defects:

  • Its first FAQ answer opened a group with ((( and closed it only at the end of the second, so the two answers rendered inside one box, the second reading as part of the first.
  • The two-hop path was described in prose on a page that is an Explanation of exactly that topology. It gets a PlantUML diagram (validated with plantuml -syntax and rendered to a PNG, since the change request preview cannot render the macro at all), plus the one command the page never gave.
  • The fact that decides the whole arrangement was missing: the port the tunnel opens on the remote server is bound to that server's loopback interface only ("By default, TCP listening sockets on the server will be bound to the loopback interface only", ssh(1)), which is why a reverse proxy is needed in front of it at all. A third FAQ answer says what keeps the tunnel up, which nothing did.
  • Its WIP banner is removed, as is the one on the HTTPS page.

Deliberately not in this change

  • Two renames, which are moves and cannot travel in a change request: set-nginx to configure-nginx-server-linux, and configurations to configure-https with a move up beside the two procedures, where the Apache page sits. Until then the HTTPS page is a child of the Linux one and the tree reads oddly, which is the cost of doing this as one reviewable change.
  • The page name of the new Windows page repeats the server name its parent already carries (nginx-key-configurations/configure-nginx-server-windows), against the page-name rule, exactly as the whole Apache subtree does. Symmetry between the two subtrees was preferred to fixing it on one page only; fixing both is a rename too.
  • Whether the two OS procedures should be howto rather than tutorial is still open from the first change request, and is left alone so that all four pages stay of one type.
  • A platform issue for the first-versus-last value of the X-Forwarded-* headers is filed separately: XWiki reads the first value while a proxy appends its own last, and there is no trusted-proxy count, which is why both subtrees can only tell administrators to overwrite those headers at the proxy.

All changes

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure NginX Server as a Proxy on a Linux OS
Parent
... ... @@ -1,0 +1,1 @@
1 +documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,47 @@
1 +NginX forwards requests to the XWiki [[Servlet Container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] on a Linux system, using the [[directives XWiki needs>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]]. This procedure serves the wiki over plain ##HTTP## on port ##80##; [[Configure HTTPS for the NginX HTTP Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]] adds ##HTTPS## on top of it. The commands are those of a Debian-based distribution.
2 +
3 +1. Make sure your wiki is running and reachable locally, for example at {{code language="none"}}http://localhost:8080/xwiki{{/code}}.
4 +1. [[Install NginX>>https://nginx.org/en/docs/install.html]].
5 +1. Create the file ##/etc/nginx/sites-available/xwiki## with the following content:(((
6 +{{code language="nginx"}}
7 +map $http_upgrade $connection_upgrade {
8 + default upgrade;
9 + "" "";
10 +}
11 +
12 +server {
13 + listen 80;
14 + server_name localhost;
15 +
16 + access_log /var/log/nginx/xwiki-access.log;
17 + error_log /var/log/nginx/xwiki-error.log;
18 +
19 + client_max_body_size 0;
20 +
21 + location = / {
22 + return 301 /xwiki/;
23 + }
24 +
25 + location /xwiki {
26 + proxy_pass http://localhost:8080;
27 +
28 + proxy_set_header Host $http_host;
29 + proxy_set_header X-Real-IP $remote_addr;
30 + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
31 + proxy_set_header X-Forwarded-Proto $scheme;
32 + proxy_set_header X-Forwarded-Host $http_host;
33 + proxy_set_header Forwarded "";
34 +
35 + proxy_http_version 1.1;
36 + proxy_set_header Upgrade $http_upgrade;
37 + proxy_set_header Connection $connection_upgrade;
38 +
39 + proxy_redirect off;
40 + }
41 +}
42 +{{/code}}
43 +)))
44 +1. Enable the site: {{code language="none"}}sudo ln -s /etc/nginx/sites-available/xwiki /etc/nginx/sites-enabled/{{/code}}.
45 +1. Check the configuration: {{code language="none"}}sudo nginx -t{{/code}}.
46 +1. Reload NginX: {{code language="none"}}sudo systemctl reload nginx{{/code}}.
47 +1. Open {{code language="none"}}http://localhost{{/code}} in a browser. NginX redirects to {{code language="none"}}http://localhost/xwiki/{{/code}} and the wiki loads through port ##80##, with no port number in the address.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Why does the configuration file have to be enabled separately? ==
2 +
3 +The ##nginx.conf## the Debian packages ship includes ##/etc/nginx/sites-enabled/##, and nothing else, so the symbolic link created above is what makes NginX read the file written in ##sites-available##. Keeping the two directories apart is what lets a site be disabled without deleting its configuration.
4 +
5 +== How do I serve the wiki on my own domain instead of localhost? ==
6 +
7 +Set ##server_name## to that domain, for example {{code language="none"}}server_name wiki.example.com;{{/code}}, and make sure the name resolves: a name that is not published in DNS has to be added to the ##hosts## file of every machine that uses it, for example {{code language="none"}}127.0.0.1 wiki.example.local{{/code}}.
8 +
9 +== Where does NginX write its logs? ==
10 +
11 +In the two files named by the block above, ##/var/log/nginx/xwiki-access.log## and ##/var/log/nginx/xwiki-error.log##. The access log is where to look first when the wiki answers through port ##8080## but not through the proxy, since it records the path NginX actually forwarded.
Related
... ... @@ -1,0 +1,4 @@
1 +* [[Configure NginX Server as a Proxy on a Windows OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.configure-nginx-server-windows.WebHome]].
2 +* [[Configure Apache HTTP Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.configure-apache-server-linux.WebHome]].
3 +* [[Configure Tomcat to Find Proxy Headers>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]].
4 +* [[NginX beginner's guide>>https://nginx.org/en/docs/beginners_guide.html]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +tutorial
DocApp.Code.DocumentationExtensionClass[0]

Creation of Configure NginX Server as a Proxy on a Windows OS

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure NginX Server as a Proxy on a Windows OS
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,47 @@
1 +NginX forwards requests to the XWiki [[Servlet Container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] on a Windows system, using the [[directives XWiki needs>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]]. Windows has no NginX package and no ##sites-available## directory, so the server is unpacked from an archive and everything is configured in the single ##conf\nginx.conf## file.
2 +
3 +1. Make sure your wiki is running and reachable locally, for example at {{code language="none"}}http://localhost:8080/xwiki{{/code}}.
4 +1. Download the Windows build of [[NginX>>https://nginx.org/en/download.html]].
5 +1. Extract the archive to ##C:\nginx##.
6 +1. Replace the ##server## block that ##C:\nginx\conf\nginx.conf## already holds with the following content, inside the ##http## section of that file:(((
7 +{{code language="nginx"}}
8 +map $http_upgrade $connection_upgrade {
9 + default upgrade;
10 + "" "";
11 +}
12 +
13 +server {
14 + listen 80;
15 + server_name localhost;
16 +
17 + access_log logs/xwiki-access.log;
18 + error_log logs/xwiki-error.log;
19 +
20 + client_max_body_size 0;
21 +
22 + location = / {
23 + return 301 /xwiki/;
24 + }
25 +
26 + location /xwiki {
27 + proxy_pass http://localhost:8080;
28 +
29 + proxy_set_header Host $http_host;
30 + proxy_set_header X-Real-IP $remote_addr;
31 + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
32 + proxy_set_header X-Forwarded-Proto $scheme;
33 + proxy_set_header X-Forwarded-Host $http_host;
34 + proxy_set_header Forwarded "";
35 +
36 + proxy_http_version 1.1;
37 + proxy_set_header Upgrade $http_upgrade;
38 + proxy_set_header Connection $connection_upgrade;
39 +
40 + proxy_redirect off;
41 + }
42 +}
43 +{{/code}}
44 +)))
45 +1. Open a Command Prompt, go to the installation directory with {{code language="none"}}cd C:\nginx{{/code}}, and check the configuration: {{code language="none"}}nginx -t{{/code}}.
46 +1. Start NginX: {{code language="none"}}start nginx{{/code}}. After any later change to ##nginx.conf##, use {{code language="none"}}nginx -s reload{{/code}} instead.
47 +1. Open {{code language="none"}}http://localhost{{/code}} in a browser. NginX redirects to {{code language="none"}}http://localhost/xwiki/{{/code}} and the wiki loads through port ##80##, with no port number in the address.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Why does the NginX welcome page answer instead of the wiki? ==
2 +
3 +The ##server## block the archive ships is still in ##nginx.conf##. Two blocks listening on port ##80## for the same ##server_name## only produce a warning, and NginX answers with the first of them.
4 +
5 +== Can NginX run as a Windows service? ==
6 +
7 +No. NginX on Windows runs as a console application, with no equivalent of the Apache {{code language="none"}}httpd.exe -k install{{/code}} command, and it is stopped with {{code language="none"}}nginx -s quit{{/code}}. Running it unattended needs a third-party service wrapper.
8 +
9 +== Is NginX on Windows suitable for a production wiki? ==
10 +
11 +Its own [[documentation>>https://nginx.org/en/docs/windows.html]] calls it a beta version: only one worker process does any work, and only the ##select()## and ##poll()## connection methods are available. Serve a production wiki from a Linux host, or with [[Apache HTTP Server on Windows>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]].
Related
... ... @@ -1,0 +1,5 @@
1 +* [[Configure NginX Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]].
2 +* [[Configure HTTPS for the NginX HTTP Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]].
3 +* [[Configure Apache HTTP Server as a Proxy on a Windows OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.configure-apache-server-windows.WebHome]].
4 +* [[Configure Tomcat to Find Proxy Headers>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]].
5 +* [[NginX for Windows>>https://nginx.org/en/docs/windows.html]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +tutorial
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure HTTPS for the NginX HTTP Proxy Server
Parent
... ... @@ -1,0 +1,1 @@
1 +documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,60 @@
1 +Once NginX forwards requests to XWiki on port ##80##, a second ##server## block on port ##443## serves the same wiki over ##HTTPS## and the port ##80## one redirects to it. This procedure continues [[Configure NginX Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]], and the directives it adds are described in [[NginX Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]].
2 +
3 +1. Obtain a TLS certificate and its private key for the wiki's domain.
4 +1. Add the ##HTTPS## block to ##/etc/nginx/sites-available/xwiki##, carrying every proxy directive of the port ##80## block:(((
5 +{{code language="nginx"}}
6 +server {
7 + listen 443 ssl;
8 + server_name wiki.example.com;
9 +
10 + ssl_certificate /etc/ssl/certs/wiki.example.com.crt;
11 + ssl_certificate_key /etc/ssl/private/wiki.example.com.key;
12 +
13 + access_log /var/log/nginx/xwiki-access.log;
14 + error_log /var/log/nginx/xwiki-error.log;
15 +
16 + client_max_body_size 0;
17 +
18 + location = / {
19 + return 301 /xwiki/;
20 + }
21 +
22 + location /xwiki {
23 + proxy_pass http://localhost:8080;
24 +
25 + proxy_set_header Host $http_host;
26 + proxy_set_header X-Real-IP $remote_addr;
27 + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
28 + proxy_set_header X-Forwarded-Proto $scheme;
29 + proxy_set_header X-Forwarded-Host $http_host;
30 + proxy_set_header Forwarded "";
31 +
32 + proxy_http_version 1.1;
33 + proxy_set_header Upgrade $http_upgrade;
34 + proxy_set_header Connection $connection_upgrade;
35 +
36 + proxy_redirect off;
37 + }
38 +}
39 +{{/code}}
40 +)))
41 +1. Replace the body of the port ##80## block in the same file with a redirect to ##HTTPS##:(((
42 +{{code language="nginx"}}
43 +server {
44 + listen 80;
45 + server_name wiki.example.com;
46 +
47 + location ^~ /.well-known/acme-challenge/ {
48 + root /var/www/html;
49 + }
50 +
51 + location / {
52 + return 301 https://$host$request_uri;
53 + }
54 +}
55 +{{/code}}
56 +)))
57 +1. Set ##xwiki.home## in the [[##xwiki.cfg## configuration file>>doc:documentation.xs.admin.configuration.WebHome]] to the public base address, scheme and trailing slash included and without the ##/xwiki## path: {{code language="none"}}xwiki.home=https://wiki.example.com/{{/code}}.
58 +1. Recommended: make the Servlet Container trust the forwarded headers as well, following [[Configure Tomcat to Find Proxy Headers>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]].
59 +1. Check the configuration and reload NginX: {{code language="none"}}sudo nginx -t{{/code}} then {{code language="none"}}sudo systemctl reload nginx{{/code}}.
60 +1. Open {{code language="none"}}https://wiki.example.com{{/code}} in a browser. The browser reports the connection as secure, the plain ##HTTP## address redirects to it, and the wiki's own links all use {{code language="none"}}https://{{/code}}.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,19 @@
1 +== Why does the redirect use $host when the proxy headers use $http_host? ==
2 +
3 +Because ##$host## carries no port and ##$http_host## does: in the redirect the port of the plain ##HTTP## listener would end up in an {{code language="none"}}https://{{/code}} address, while the proxy headers need the port so that the wiki builds its own URLs with it.
4 +
5 +== Why does the ACME location need the ^~ prefix? ==
6 +
7 +Without it a regular-expression ##location## elsewhere in the same ##server## block wins over the prefix, and the certificate challenge is redirected to ##HTTPS## instead of being answered, which breaks automatic renewal.
8 +
9 +== Do I have to configure the TLS protocols and ciphers? ==
10 +
11 +No. Since NginX 1.23.4 ##ssl_protocols## already defaults to ##TLSv1.2 TLSv1.3##, so a hardening snippet copied from an older guide usually only pins something weaker.
12 +
13 +== How do I make browsers use HTTPS without going through the redirect first? ==
14 +
15 +Add {{code language="none"}}add_header Strict-Transport-Security "max-age=63072000" always;{{/code}} to the port ##443## block, once every part of the wiki is served over ##HTTPS##, since a browser then refuses plain ##HTTP## for the whole ##max-age##. A ##location## that declares an ##add_header## of its own inherits none of the outer ones and needs the line repeated.
16 +
17 +== How do I do this on Windows? ==
18 +
19 +The two blocks are the same. Put them in ##conf\nginx.conf## in place of the port ##80## one, name the certificate and the key with Windows paths, and reload with {{code language="none"}}nginx -s reload{{/code}}.
Related
... ... @@ -1,0 +1,4 @@
1 +* [[Configure NginX Server as a Proxy on a Windows OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.configure-nginx-server-windows.WebHome]].
2 +* [[Configure Tomcat to Find Proxy Headers>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]].
3 +* [[NginX Configuring HTTPS servers>>https://nginx.org/en/docs/http/configuring_https_servers.html]].
4 +* [[Configuration>>doc:documentation.xs.admin.configuration.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Content
... ... @@ -1,4 +1,4 @@
1 -[[NginX>>https://nginx.org/]] forwards requests to XWiki with the ##proxy_pass## directive of its [[proxy module>>https://nginx.org/en/docs/http/ngx_http_proxy_module.html]]. The directives below are the ones a wiki needs, and [[Set up NginX Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]] assembles them into a complete ##server## block. The [[Apache Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]] page documents the equivalent Apache HTTP Server directives.
1 +[[NginX>>https://nginx.org/]] forwards requests to XWiki with the ##proxy_pass## directive of its [[proxy module>>https://nginx.org/en/docs/http/ngx_http_proxy_module.html]]. The directives below are the ones a wiki needs; [[Configure NginX Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]] and [[Configure NginX Server as a Proxy on a Windows OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.configure-nginx-server-windows.WebHome]] assemble them into a complete ##server## block, and [[Configure HTTPS for the NginX HTTP Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]] adds the ##HTTPS## ones. The [[Apache Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]] page documents the equivalent Apache HTTP Server directives.
2 2  
3 3  == Server Block Directives ==
4 4  
... ... @@ -27,3 +27,20 @@
27 27  |##proxy_http_version 1.1##|Uses ##HTTP/1.1## towards the container, which the WebSocket upgrade needs. See [[proxy_http_version>>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version]].
28 28  |{{code language="none"}}map $http_upgrade $connection_upgrade { default upgrade; "" ""; }{{/code}} with ##proxy_set_header Upgrade $http_upgrade## and ##proxy_set_header Connection $connection_upgrade##|Tunnels the WebSocket connections that realtime editing uses. The ##map## belongs at ##http## level, outside the ##server## block, and is what keeps ##Connection: upgrade## for the handshakes only: hard-coded, that header goes out on every request, including the ones upgrading nothing, and it rules out the connection reuse an ##upstream## block declaring ##keepalive## would otherwise bring. See [[map>>https://nginx.org/en/docs/http/ngx_http_map_module.html#map]].
29 29  |##proxy_redirect off##|Leaves the ##Location## header of the container's redirects alone, which is what is wanted here: ##Host## is forwarded unchanged, so XWiki already redirects to the public address. See [[proxy_redirect>>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect]].
30 +
31 +== HTTPS Directives ==
32 +
33 +These are added to the port ##443## block, on top of the proxy directives above.
34 +
35 +|=Directive|=What it does
36 +|{{code language="none"}}listen 443 ssl;{{/code}}|Opens the block that handles ##HTTPS## requests and turns TLS on for it. The block carries the same proxy directives as the port ##80## one, ##X-Forwarded-Proto## included: it is written ##$scheme##, so it reports ##https## here with nothing else to change. See [[listen>>https://nginx.org/en/docs/http/ngx_http_core_module.html#listen]].
37 +|##ssl_certificate /etc/ssl/certs/wiki.example.com.crt##|The certificate presented to browsers during the TLS handshake. NginX reads no separate chain file: an intermediate certificate goes in this same file, after the wiki's own. See [[ssl_certificate>>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate]].
38 +|##ssl_certificate_key /etc/ssl/private/wiki.example.com.key##|The private key matching that certificate. See [[ssl_certificate_key>>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key]].
39 +
40 +== Redirection Directives ==
41 +
42 +These make up the port ##80## block once ##HTTPS## serves the wiki: its body is replaced by them, so that a plain ##HTTP## request is redirected instead of proxied.
43 +
44 +|=Directive|=What it does
45 +|{{code language="none"}}location ^~ /.well-known/acme-challenge/ { root /var/www/html; }{{/code}}|Keeps the path an ACME client such as certbot answers the certificate challenge on reachable over plain ##HTTP##, so that automatic renewal keeps working. The ##^~## prefix is what makes NginX stop at this location instead of also trying the regular-expression ones the block may hold. See [[location>>https://nginx.org/en/docs/http/ngx_http_core_module.html#location]].
46 +|{{code language="none"}}return 301 https://$host$request_uri;{{/code}}|Redirects everything else to the ##HTTPS## address of the same URL. It is ##$host## here and not the ##$http_host## the proxy directives use, because ##$host## carries no port and the redirect must not put the port of the plain ##HTTP## listener into an {{code language="none"}}https://{{/code}} address. ##$request_uri## is the request as it arrived, so the ##%2F## an XWiki page name can contain crosses the redirect still encoded. See [[return>>https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return]].

Summary

Details

Page properties
Content
... ... @@ -25,5 +25,5 @@
25 25  Both Apache HTTP Server and NginX are used in front of XWiki; the choice usually follows whichever of them is already installed and administered.
26 26  
27 27  * [[Apache Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]]: the Apache directives a wiki needs, and the procedures that set them up on Linux, on Windows and for ##HTTPS##.
28 -* [[NginX Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]]: the equivalent NginX directives, and the procedure that sets them up.
29 -* [[Reverse Proxy and SSH Tunneling>>doc:documentation.xs.admin.installation.http-reverse-proxy.ssh-tunneling.WebHome]]: reaching a wiki that runs on a machine with no public address, through a remote server.
28 +* [[NginX Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]]: the equivalent NginX directives, and the procedures that set them up on Linux, on Windows and for ##HTTPS##.
29 +* [[Reverse Proxy and SSH Tunneling>>doc:documentation.xs.admin.installation.http-reverse-proxy.ssh-tunneling.WebHome]]: reaching a wiki that runs on a machine with no public address, through a remote server.

Summary

Details

Page properties
Content
... ... @@ -1,9 +1,33 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
1 +[[Proxying>>doc:documentation.xs.admin.installation.http-reverse-proxy.WebHome]] a wiki that runs on a machine with no public address takes a second hop: a reverse SSH tunnel to a server that has one. The tunnel is opened by the local machine, outwards, which is what makes the arrangement work behind a firewall that allows no incoming connection and without a fixed public IP address:
4 4  
5 -[[Proxying>>doc:documentation.xs.admin.installation.http-reverse-proxy.WebHome]] combined with SSH tunneling allows a remote server to forward incoming traffic to a service running on a local machine. This is useful when the local service is not directly accessible from the internet due to for example firewall restrictions, dynamic IP addresses. In this setup, a reverse SSH tunnel is created from the local machine to a remote server. The tunnel maps a port on the remote server (for example, ##8080##) to a port on the local machine where the application is running (for example, ##127.0.0.1:8080##). As a result, any request received by the remote server on the mapped port is securely forwarded through the SSH connection to the local service.
3 +{{code language="none"}}
4 +ssh -R 8080:127.0.0.1:8080 server
5 +{{/code}}
6 6  
7 -A reverse proxy such as [[Nginx>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]] can then be configured on the remote server to expose the service under a public domain (for example, {{code language="none"}}https://wiki.yourdomain.com{{/code}}). The proxy forwards incoming ##HTTP## requests to the locally tunneled port, making the locally running application accessible as if it were hosted on the remote server.
7 +{{plantuml}}
8 +@startuml
9 +!theme bluegray
10 +skinparam componentStyle rectangle
11 +left to right direction
8 8  
9 -This approach is commonly used for development, testing, and temporary deployments. It eliminates the need for the local machine to have a public IP address or direct inbound network access, while still allowing external users to access the service securely through the remote server.
13 +actor "Reader" as USER
14 +
15 +package "Remote server, public address" {
16 + component "**Reverse proxy**\nNginX serving wiki.example.com" as PROXY
17 + component "**Tunnel entrance**\n127.0.0.1:8080 on the remote server,\nbound to its loopback interface only" as ENTRY
18 +}
19 +
20 +package "Local machine, no public address" {
21 + component "**XWiki**\nServlet container on 127.0.0.1:8080" as XWIKI
22 +}
23 +
24 +USER --> PROXY : HTTPS, port 443
25 +PROXY --> ENTRY : proxy_pass to 127.0.0.1:8080
26 +ENTRY --> XWIKI : forwarded over the SSH connection
27 +XWIKI ..> ENTRY : ssh -R, opened outwards\nby the local machine
28 +@enduml
29 +{{/plantuml}}
30 +
31 +The port the tunnel opens on the remote server is bound to that server's loopback interface, not to its public one, so nothing reaches the wiki through it from outside. Publishing it is the reverse proxy's job, and the proxy is configured as it is on any other host, following [[Configure NginX Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]] with ##proxy_pass## naming the tunnelled port: to XWiki the request arrives from the proxy, exactly as it would if the wiki ran on the same machine.
32 +
33 +This is a development and temporary-deployment arrangement. Every request crosses an SSH connection that nothing restarts on its own, so a permanent wiki is better served from a host that carries it directly.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,16 +1,11 @@
1 -== How can I verify that the remote port is available? ==
1 +== How do I check that the remote port is free? ==
2 2  
3 -Before creating the reverse SSH tunnel, make sure that port ##8080## is not already in use on the remote server. Run the following command from your local machine:
3 +Run {{code language="none"}}ssh server curl -sS http://127.0.0.1:8080/{{/code}} before opening the tunnel: ##Connection refused## means the port is free, and any other answer means a service is already listening on it.
4 4  
5 -(((
6 -{{code language="none"}}ssh server wget -O - http://127.0.0.1:8080/{{/code}}. Expected result: ##Connection refused##.
5 +== What if another service is already using that port? ==
7 7  
8 -== What if another service is already listening on port ##8080## on the remote server? ==
7 +Stop that service, or open the tunnel on a free port instead, for example {{code language="none"}}ssh -R 9090:127.0.0.1:8080 server{{/code}}, and point ##proxy_pass## at {{code language="none"}}http://127.0.0.1:9090{{/code}}.
9 9  
10 -If the command returns a web page or another response instead, it means that another service is already listening on port 8080 on the remote server. In this case, either:
9 +== What keeps the tunnel up? ==
11 11  
12 -* stop the conflicting service, or
13 -* use another port for the SSH tunnel.
14 -
15 -For example: {{code language="none"}}ssh -R9090:127.0.0.1:8080 server{{/code}}. This exposes the local XWiki instance through port ##9090## on the remote server instead of ##8080##.
16 -)))
11 +Nothing on its own: the tunnel dies with the SSH session. Run it under a supervisor such as ##autossh## or a ##systemd## service, and set ##ServerAliveInterval## so that a connection lost silently is noticed and reopened.
Related
... ... @@ -1,0 +1,3 @@
1 +* [[Configure NginX Server as a Proxy on a Linux OS>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]].
2 +* [[Configure HTTPS for the NginX HTTP Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]].
3 +* [[OpenSSH ssh manual>>https://man.openbsd.org/ssh]].
Aug 18, 2026, 11:53:49 AM

Approved by Eleni Cojocariu

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected