Configuring the Virtualization Server

Showing results for 
Search instead for 
Did you mean: 

Configuring the Virtualization Server

0 0 2,675

Obsolete Pages{{Obsolete}}

The official documentation is at:



Most systems use one of the following methods to provide a 'virtual view' of a website:

  1. Cookies
    • All windows share the same set of cookies, so you can't have multiple views active at the same time.
    • It's easy to clear a cookie cache accidentally
    • There's no easy way to send a URL plus its associated cookie to another person (e.g.: via email).
  2. Request path mangling
    • Complicated by the need to use proxies
    • Security/DoS issues in need to cache POST bodies to handle redirects
    • Requires custom plugins to handle internal subrequests (e.g.: server side includes).
  3. Extra QUERY_STRING arguments
    • Integrates badly with 3rd party applications
    • Requires taking special action to create 'bookmarkable' virtual link
    • Namespace pollution of application-level POST/GET arguments.

Instead, Alfresco makes each 'virtual view' correspond to a 'virtual website' within its own virtual host.
This approach has several advantages:

  • Side-by-side comparisons of different virtual views can be done within the same browser instance
  • The browser's built-in bookmarking mechanism works (no need for javascript 'URL constructors')
  • Virtualized hyperlinks to be sent via email
  • The virtual view is plainly visible in the URL itself

The general format of an Alfresco virtual hyperlink is:


In order for this to work, virtualization-domain and all its subdomains must resolve in DNS to the IP address of the Virtualization Server.  This is sometimes known as a 'wildcard DNS' address mapping.   There are two ways to achieve this:

  1. Use the appropriate subdomain of  (see instructions below)
  2. Configure a nameserver, and set up a wildcard domain pointing at your Virtualization Server machine's IP address.

While the second method will let you use your Virtualization Server even when disconnected from the Internet, many people will find the first method easier.

Method 1:  Using

Let's denote the directory you've installed the virtualization server in as


Further, let's suppose the IP address of the machine hosting the virtualization server is:

Alfresco has set up a nameserver at that's able to resolve any domain name of the form:

(or any of its subdomains) as the IP address:


For example, if your browser asks for the virtual host name:

the IP address returned will be:

Thus, provides 'wildcard dns' for all valid IPV4 address.  By default, the Virtualization Server is configured to use the virtualization domain:

This returns the IP address:

This special IP address always refers to your local machine (hence its name:  'localhost').  Therefore, if you use the default virtualization domain '', you'll only be able to do in-context preview on the same machine that hosts the Virtualization Server.  To enable everybody on a LAN to use in-context preview, you'll need to use a network-accessible IP address (i.e.: not  In order to make the Alfresco webapp generate URLs that address the Virtualization Server's network-accessible address (e.g.:, edit the file:


Within this file, change the following property so it it contains the hyphen-encode IP address you desire:

For example:


When specifying alfresco.virtserver.domain that uses, be sure IP address you want to have a DNS wildcard domain for is hyphen-encoded.  If it isn't, will assume you've misconfigured your system, and will fall back to returning for all DNS name lookups within your malformed virtualization domain.  For example:


Once you restart the Tomcat instance that runs the Alfresco webapp, if you click on the 'eyeball' icon near WCM assets, you'll see URLs of the form:


These links will resolve to your Virtualization Server on; they are network-accessible, virtualized, bookmarkable hyperlinks!

To see this in isolation, try issuing any of the following commands:

ping       mysite.www--sandbox.19

Method 2:  Configuring wildcard DNS on your own nameserver

While makes it trivial to set up virtualization for a single machine or a LAN, using your own nameserver to provide wildcard DNS has some advantages:

  • A local nameserver lets you virtualize content on a machine or LAN with no access to the Internet (e.g.: a demo laptop)
  • The first DNS lookup of a name is somewhat faster when served locally (IP address answers have a 1 day TTL)
  • You may already have BIND, djbdnsMicrosoft DNS, or some other DNS solution in place, and want to keep everything centralized in it.
  • You are not dependent from Alfresco's uptime

A detailed description of how to set up a DNS server (and then how to create a wildcard NS record within it) is beyond the scope of this document.  However, suppose your LAN's domain name were:


Further, suppose you had a wildcard DNS record that resolved to some IP address such as:  

Suppose your wildcard DNS names were contained within:


In this case, edit:


and modify the value of the alfresco.virtserver.domain property so it looks like this:


The 'hosts' file cannot be used to create a wildcard DNS domain on Windows or Unix.  To create a DNS wildcard that's usable when you're not connected to the Internet, you must install, configure, and maintain a real nameserver.  Thus, it's a tradeoff:  using for wildcard DNS is easy, fast, free, and requires no ongoing support effort; local nameserver require expertise and support, but may offer features you actually need (e.g.: the ability to run on a disconnected laptop).

The choice is yours.

A word of caution

Setting up DNS properly requires a fair amount of specialized expertise, and a great deal of attention to seemingly minor details.  If you make a mistake, your network's security may be compromised in several ways: cache poisoning, network snooping, viruses, denial of service attacks, etc.  Even when set up correctly, most DNS servers require at least some 'care and feeding', and some ongoing attention to security bulletins;  while djbdns quite good in this regard, the most common servers (Microsoft DNS and BIND) are notoriously buggy  Be careful.


If you're looking for detailed information, see the Virtualization Server FAQ.