Wiki source code of Apache Server Key Configurations
Last modified by Eleni Cojocariu on 2026/09/16 09:33
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | [[Apache HTTP Server>>https://httpd.apache.org/]] forwards requests to XWiki through its [[mod_proxy>>https://httpd.apache.org/docs/current/mod/mod_proxy.html]] module. The directives below are the ones a wiki needs; [[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]] and [[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]] assemble them into a complete ##VirtualHost##, and [[Configure HTTPS for the Apache HTTP Proxy Server>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.configure-https.WebHome]] adds the ##HTTPS## ones. | ||
| 2 | |||
| 3 | == Proxy Directives == | ||
| 4 | |||
| 5 | These go in the ##VirtualHost## block that serves the wiki, on port ##80## for a plain ##HTTP## configuration and on port ##443## for an ##HTTPS## one. | ||
| 6 | |||
| 7 | |=Directive|=What it does | ||
| 8 | |{{code language="none"}}<VirtualHost *:80>{{/code}}|Opens the block that handles every request arriving on port ##80##, on all network interfaces (##*##). | ||
| 9 | |##ServerName localhost##|The host name this block answers for. Set it to the wiki's public domain, for example {{code language="none"}}ServerName wiki.example.com{{/code}}. | ||
| 10 | |{{code language="none"}}ErrorLog ${APACHE_LOG_DIR}/xwiki-error.log{{/code}} and {{code language="none"}}CustomLog ${APACHE_LOG_DIR}/xwiki-access.log combined{{/code}}|Optional per-wiki log files, so that proxy problems can be told apart from the rest of the server's traffic. | ||
| 11 | |##RedirectMatch ^/$ /xwiki/##|Redirects the root URL to the wiki, so that {{code language="none"}}http://localhost{{/code}} reaches XWiki without ##/xwiki## being typed. See [[RedirectMatch>>https://httpd.apache.org/docs/current/mod/mod_alias.html#redirectmatch]]. | ||
| 12 | |{{code language="none"}}<Location /xwiki>{{/code}} with ##Require all granted##|Grants access to the proxied path. See [[Require>>https://httpd.apache.org/docs/current/mod/mod_authz_core.html#require]]. | ||
| 13 | |##AllowEncodedSlashes NoDecode##|Lets Apache forward URLs that contain an encoded slash (##%2F##) without decoding it, which XWiki page names can contain. The default is ##Off##, under which Apache answers ##404## for such URLs. See [[AllowEncodedSlashes>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]]. | ||
| 14 | |##AddDefaultCharset Off##|##Off## is the default, and nothing has to be added: XWiki names ##UTF-8## in the ##Content-Type## of its own responses, and Apache leaves a content type that already names a character set alone. The directive matters where a wider part of the configuration sets it, since ##On## stands for ##iso-8859-1## and is applied to every ##text/html## or ##text/plain## response that names none. Set it to ##utf-8## where it cannot be removed. See [[AddDefaultCharset>>https://httpd.apache.org/docs/current/mod/core.html#adddefaultcharset]] and [[Character Encoding>>doc:documentation.xs.admin.configuration.character-encoding.WebHome]]. | ||
| 15 | |{{code language="none"}}RequestHeader unset Forwarded{{/code}}, {{code language="none"}}RequestHeader unset X-Forwarded-Host{{/code}} and {{code language="none"}}RequestHeader unset X-Forwarded-Proto{{/code}}|Drops any forwarded header the client sent, before Apache appends its own. XWiki builds its URLs from the //first// value of these headers while Apache appends after the client's, so without the three lines a reader can make the wiki emit links for any host or scheme. Provided by [[mod_headers>>https://httpd.apache.org/docs/current/mod/mod_headers.html]]. See [[RequestHeader>>https://httpd.apache.org/docs/current/mod/mod_headers.html#requestheader]]. | ||
| 16 | |##ProxyRequests Off##|Disables the forward proxy, which a reverse proxy never uses and which would otherwise turn the server into an open proxy. See [[ProxyRequests>>https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxyrequests]]. | ||
| 17 | |##ProxyPreserveHost On##|Forwards the client's ##Host## header to XWiki, so that XWiki builds URLs for the public domain rather than for ##localhost##. See [[ProxyPreserveHost>>https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypreservehost]]. | ||
| 18 | |{{code language="none"}}ProxyPass /xwiki http://localhost:8080/xwiki nocanon upgrade=websocket{{/code}}|Forwards ##/xwiki## to the Servlet Container. ##nocanon## passes the path on raw, leaving characters such as ##;## and encoded slashes untouched; ##upgrade=websocket## tunnels the WebSocket connections that realtime editing uses, and needs Apache HTTP Server 2.4.47 or later. See [[ProxyPass>>https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass]]. | ||
| 19 | |{{code language="none"}}ProxyPassReverse /xwiki http://localhost:8080/xwiki{{/code}}|Rewrites the ##Location## header of the redirects XWiki returns, so that a redirect to {{code language="none"}}localhost:8080{{/code}} reaches the reader as one to the public URL. It takes no ##nocanon## option, and silently ignores any third keyword written there rather than reporting it. See [[ProxyPassReverse>>https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassreverse]]. | ||
| 20 | |||
| 21 | == HTTPS Directives == | ||
| 22 | |||
| 23 | These are added to the port ##443## block, on top of the proxy directives above. | ||
| 24 | |||
| 25 | |=Directive|=What it does | ||
| 26 | |{{code language="none"}}<VirtualHost *:443>{{/code}}|Opens the block that handles ##HTTPS## requests. It carries the same proxy directives as the port ##80## block, plus the ones below. | ||
| 27 | |##SSLEngine on##|Enables TLS for this block. Provided by [[mod_ssl>>https://httpd.apache.org/docs/current/mod/mod_ssl.html]]. | ||
| 28 | |##SSLCertificateFile /path/to/certificate##|The server certificate presented to browsers during the TLS handshake. See [[SSLCertificateFile>>https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatefile]]. | ||
| 29 | |##SSLCertificateKeyFile /path/to/privatekey##|The private key matching that certificate. See [[SSLCertificateKeyFile>>https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatekeyfile]]. | ||
| 30 | |##RequestHeader set X-Forwarded-Proto "https"##|Tells XWiki that the reader's request used ##HTTPS##, which Apache would otherwise hide by forwarding it over plain ##HTTP##. It goes after the three ##RequestHeader unset## lines above, so that the value the wiki reads is the proxy's own. Provided by [[mod_headers>>https://httpd.apache.org/docs/current/mod/mod_headers.html]]. | ||
| 31 | |||
| 32 | == Redirection Directives == | ||
| 33 | |||
| 34 | These go in the port ##80## block, whose body they replace once ##HTTPS## serves the wiki, so that a plain ##HTTP## request is redirected instead of proxied. | ||
| 35 | |||
| 36 | |=Directive|=What it does | ||
| 37 | |##AllowEncodedSlashes NoDecode##|Still required in a block that only redirects: without it Apache answers ##404## for a URL holding an encoded slash instead of redirecting it. | ||
| 38 | |##RewriteEngine On##|Enables the rewriting engine, without which no ##RewriteCond## or ##RewriteRule## is processed. Provided by [[mod_rewrite>>https://httpd.apache.org/docs/current/mod/mod_rewrite.html]]. | ||
| 39 | |{{code language="none"}}RewriteCond %{REQUEST_URI} !^/\.well-known{{/code}}|Exempts [[##/.well-known##>>https://en.wikipedia.org/wiki/Well-known_URI]], where an ACME client such as certbot answers the challenge that issues and renews the certificate, and which therefore has to stay reachable over plain ##HTTP##. | ||
| 40 | |{{code language="none"}}RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R=301,L,NE]{{/code}}|Redirects everything else to the ##HTTPS## address of the same URL. ##[R=301]## makes it a permanent external redirect, ##[L]## stops further rules being applied, and ##[NE]## keeps the redirect from encoding a second time the ##%2F## an XWiki page name can contain. See [[RewriteRule Flags>>https://httpd.apache.org/docs/current/rewrite/flags.html]]. |
