Wiki URL Resolution
Reference
Every request that reaches a wiki farm names the wiki it is for, in the path of the URL or in the host name. This page states which wiki XWiki serves for a given URL, and the properties that decide the form XWiki writes.
The Two URL Forms
A path-based URL carries the wiki in a path segment:
http://myfarm.example.org/xwiki/wiki/mywiki/view/Space/PageA domain-based URL carries it in the host name:
http://mywiki.example.org/xwiki/bin/view/Space/PageThe segment that follows the context path tells the two apart: wiki means the wiki is the segment after it, bin means the wiki is the host name. A URL with no wiki segment is therefore read as a domain-based one. Everything after the wiki follows the standard URL format, which the farm does not change.
Configuration Properties
All four are read from WEB-INF/xwiki.properties. The WEB-INF/xwiki.cfg twins are the older names for the same settings, and they are still read, so the two files have to agree.
| Property | Default | xwiki.cfg twin | Sets |
|---|---|---|---|
| url.standard.multiwiki.isPathBased | true | xwiki.virtual.usepath, 1 | Which of the two forms XWiki writes |
| url.standard.multiwiki.wikiPathPrefix | wiki | xwiki.virtual.usepath.servletpath | The segment that marks a path-based URL |
| url.standard.multiwiki.notFoundBehavior | redirect_to_main_wiki | xwiki.virtual.failOnWikiDoesNotExist, 0 | What is served when no wiki matches |
| url.standard.entityPathPrefix | bin | xwiki.defaultservletpath, bin/ | The segment a domain-based URL carries where a path-based one carries the wiki |
Which Form XWiki Writes
Setting isPathBased alone is not enough. The URL module falls back to the xwiki.cfg value only when the property is absent, but the factory that builds links and the filter that rewrites form submissions read xwiki.virtual.usepath alone, so a disagreement leaves part of the instance writing the other form. Switch to Domain-Based URLs sets both.
The Wiki Path Segment
Renaming wikiPathPrefix also moves where the servlet container has to route the segment, so follow Change the Wiki Path Segment rather than editing the property alone.
Wiki Descriptors
A wiki descriptor is a page of the main wiki, in the XWiki space, holding an XWiki.XWikiServerClass object. Its page name is XWikiServer followed by the wiki id, and the id XWiki reads back from that name is the suffix in lower case. The object's server field holds an alias that a URL may use, and a descriptor page may hold several such objects, each one adding another alias for the same wiki.
The first of those objects is not interchangeable with the others: its server field is the wiki's default alias, the one XWiki writes into the URLs it generates for that wiki, in either form. The rest are read when resolving a URL and never when writing one.
The id and the alias are independent, which is what makes the rules below readable: the page XWiki.XWikiServerTest whose server field is somewiki describes the wiki whose id is test, and the path-based URL that reaches it is /xwiki/wiki/somewiki/view/Space/Page.
Resolution Order
XWiki resolves the wiki before it looks at anything else in the request, and the resolved id is always lower-cased:
When the Wiki Does Not Exist
notFoundBehavior decides that last branch. redirect_to_main_wiki serves the main wiki instead; display_error lets the request reach a wiki that has no descriptor, and XWiki answers 404 with the wikidoesnotexist template. Its twin takes 0 for the first and 1 for the second.
Creating a page named XWiki.WikiDoesNotExist in the main wiki replaces the standard error message with that page's content.
FAQ
Why is a subwiki served as the main wiki instead of an error?
Because no descriptor matched the alias the URL carries, so the not-found behaviour above took over. Set it to display_error while you work out which alias is really being read.
Can a path-based and a domain-based URL both reach the same wiki?
They both resolve, since the form is read from the URL itself. The links XWiki writes and the form submissions it rewrites follow the configured mode, though, so run one mode rather than relying on the other form staying usable.
Is a wiki id case-sensitive in a URL?
No. The resolved id is lower-cased, so /xwiki/wiki/MyWiki/ and /xwiki/wiki/mywiki/ reach the same wiki.
