Steps

XWiki writes path-based URLs by default because that mode needs no name resolution at all, so switch a wiki farm to domain-based URLs only once every wiki is meant to have a hostname of its own.

Before you start, make sure of the following.

• Each wiki's hostname resolves to the server, through DNS or through the server's hosts file. Domain-based URLs cannot work without it, since the hostname is what carries the wiki.
• You can edit the files under WEB-INF/ and restart the instance.
• You are an administrator of the main wiki, which is where the wiki descriptors live.

1. Set the URL form to domain-based in WEB-INF/xwiki.properties:

   url.standard.multiwiki.isPathBased = false

2. Set it a second time in WEB-INF/xwiki.cfg:

   xwiki.virtual.usepath=0

   Both files are needed: the factory that builds links and the filter that rewrites form submissions read the xwiki.cfg key and nothing else, so changing only the first leaves part of the instance writing path-based URLs.

3. Restart XWiki, so that both files are read again.
4. Open the Wiki Index from the Applications panel and select the Edit action of the wiki you are giving a hostname to, which opens its descriptor:

   

5. Set that wiki's alias to its hostname. The alias listed under "Wiki properties" is the one XWiki writes into every link it generates for the wiki, and on a farm that has been running path-based it still holds the bare wiki id:

   

   Change it on the descriptor page itself, through "Edit" then "Objects": open XWikiServerClass 0 and set its Server field. The wiki's administration does not offer it.

   Warning

   Adding a hostname under "Create new alias" does not do this. An extra alias only makes the wiki reachable under that name, so a wiki left with a bare id keeps writing links that resolve nowhere:

   http://support/xwiki/bin/view/Main/

6. Add every further hostname the wiki has to answer on under "Create new alias":

   

7. Check that the wiki now lists every one of its hostnames under "View aliases", and open it at one of them:

   

   http://support.example.org/xwiki/bin/view/Main/WebHome

   The wiki creation wizard proposes a default alias of its own in domain-based mode, built from the wiki id and the suffix set in WEB-INF/xwiki.properties, so set it to the domain the farm's wikis live under:

   wiki.alias.suffix = example.org

FAQ

Do the path-based URLs stop working?

Treat them as retired. Wiki URL Resolution explains why they still resolve although nothing on the instance writes or rewrites them any more.

What happens to a wiki I forget to give an alias?

It often stays reachable and writes broken links anyway, which is what makes the omission easy to miss: a hostname whose first label matches a wiki id reaches that wiki with no alias at all, so the wiki opens and the switch looks finished, while its links still carry the alias on the descriptor. Follow a link on one of its pages rather than only typing the hostname.

Does the main wiki need a hostname too?

It has a descriptor and appears in the Wiki Index like any other wiki, so give it one the same way. Left without, it is still reached on localhost, on an IP address and on any host whose first label is www, which Wiki URL Resolution sets out.

Related

• Wiki URL Resolution
• Change the Wiki Path Segment