XWiki supports multi-tenancy which means your instance can have several wikis. This page helps you understand how to configure XWiki to access the correct wiki. Check XWiki URL Format to better understand the current URL scheme.

XWiki supports 2 URL modes: Path-based and Domain based modes.

The documentation below is for XWiki 5.0 and beyond. For earlier versions, use this documentation

Path-based wiki access

This is the default mode if you haven't touched the XWiki configuration (xwiki.virtual.usepath property in the xwiki.cfg file).

The URL format for this mode is: http://host/xwiki/wiki/wikialias/view/Space/Page.

The important part of the URL is /wiki/wikialias. Specifically it means:

  • wiki: this is just a fixed value used by XWiki to identify the URL as a path-based URL. If you wish to set a value different than wiki you can configure it in xwiki.cfg with the property xwiki.virtual.usepath.servletpath.
    Don't forget to set the xwiki.authentication.logoutpage property accordingly. Change the wiki part in the property value for the right alias.
  • wikialias: this is used by XWiki to find the wiki descriptor (see below for more about wiki descriptors). The following algorithm is used:
    • First XWiki tries to find a page that contains a XWikiServerClass object with the server field having a value of wikialias. If it finds one then it computes the name of the wiki by extracting it from that page name. Indeed, pages containing wiki descriptors must be named with the format XWikiServer<wikiid>. For example if a page named XWikiServerTest exists and it contains a XWikiServerClass object with a server field value of somewiki then the URL http://host/xwiki/wiki/somewiki/... will target the test wiki (the value is lowercased from the page name when extracted).
    • If no wiki descriptor can be located then XWiki tries to find a page named XWikiServer<wikialias> and having a XWikiServerClass object in it. If it's found then the target wiki is wikialias.
    • If no such page is found then the behavior depends on the value of the configuration property named xwiki.virtual.failOnWikiDoesNotExist (located in your xwiki.cfg file). If the value is 0 (which is the default) then the wiki served is the main wiki. If the value is 1 then an error saying that the wiki doesn't exist is displayed.

Note that if no /wiki/wikialias path is found in the URL then XWiki continues to look for a wiki using the domain-based algorithm explained below.

Domain-based wiki access

This was the default mode prior to XWiki 3.3. After the release of XWiki 3.3 the path-based mode was configured to be the default since it's the easiest to use.

The URL format for this mode is: http://domain/xwiki/bin/view/Space/Page. The information about which wiki is targeted is part of the domain part of the URL.

The following algorithm is used by XWiki:

  • First it tries to find a page that contains a XWikiServerClass object with the server field having a value of domain. If it finds one then it computes the name of the wiki by extracting it from that page name. Indeed, pages containing wiki descriptors must be named with the format XWikiServer<wikiid>. For example if a page named XWikiServerTest exists and it contains a XWikiServerClass object with a server field value of somewiki then the URL http://somewiki/xwiki/bin/... will target the test wiki (the value is lowercased from the page name when extracted).
  • If no wiki descriptor can be located then XWiki performs some checks:
    • If the domain value is an IP (e.g. 127.0.0.1, 85.65.12.36, etc.) or has the value of localhost then XWiki considers you're targeting the main wiki
    • If not, then XWiki tries to split the domain name and takes the first part before the "." (dot) character. For example if you have a domain name of prefix.domain.com then it extracts prefix. It then performs some additional checks:
      • if the value of prefix is www and there's no wiki alias named www (i.e. there's no page with a XWikiServerClass object having a server field value of www) then XWiki considers you're targeting the main wiki.
      • If not, then XWiki tries to find a page named XWikiServer<prefix> and having a XWikiServerClass object in it. If it's found then the target wiki is prefix.
      • If no such page is found then the behavior depends on the value of the configuration property named xwiki.virtual.failOnWikiDoesNotExist (located in your xwiki.cfg file). If the value is 0 (which is the default) then the wiki served is the main wiki. If the value is 1 then an error saying that the wiki doesn't exist is displayed.
Note that in this mode you need to configure your DNS or modify your /etc/hosts file in your operating system (see Hosts file documentation on Wikipedia for details).
Tags:
Created by Vincent Massol on 2017/09/06
   

Get Connected