Configuring the Virtualization Server

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

{{AVMWarning}}
AVM

Table of Contents

• 1 Overview


• 2 Method 1:  Using ip.alfrescodemo.net


• 3 Method 2:  Configuring wildcard DNS on your own nameserver
  
  
  
  • 3.1 A word of caution
  
  


• 4 FAQ

Overview

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

1. Cookies
   Issues:
   
   • 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
   Issues:
   
   • 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
   Issues:
   
   • 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:

 http://virtual-hostname.www--sandbox.virtualization-domain:port/request-path 

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 ip.alfrescodemo.net  (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 ip.alfrescodemo.net

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

 $VIRTUAL_TOMCAT_HOME

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

 192.168.1.5

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

 AAA-BBB-CCC-DDD.ip.alfrescodemo.net

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

 AAA.BBB.CCC.DDD

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

 alice.mysite.www--sandbox.192-168-1-5.ip.alfrescodemo.net

the IP address returned will be:

 192.168.1.5

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

 127-0-0-1.ip.alfrescodemo.net

This returns the IP address:

 127.0.0.1

This special IP address always refers to your local machine (hence its name:  'localhost').  Therefore, if you use the default virtualization domain '127-0-0-1.ip.alfrescodemo.net', 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 127.0.0.1).  In order to make the Alfresco webapp generate URLs that address the Virtualization Server's network-accessible address (e.g.: 192.168.1.5), edit the file:

 $VIRTUAL_TOMCAT_HOME/conf/alfresco-virtserver.properties

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

 alfresco.virtserver.domain=127-0-0-1.ip.alfrescodemo.net

For example:

 alfresco.virtserver.domain=192-168-1-5.ip.alfrescodemo.net

IMPORTANT:

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

 THIS IS VALID:      alfresco.virtserver.domain=192-168-1-5.ip.alfrescodemo.net
 THIS IS MALFORMED:  alfresco.virtserver.domain=192.168.1.5.ip.alfrescodemo.net

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:

 http://<hostname>.www--sandbox.192-168-1-5.ip.alfrescodemo.net

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

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

 ping alice.mysite.www--sandbox.192-168-1-5.ip.alfrescodemo.net
 ping       mysite.www--sandbox.19

Method 2:  Configuring wildcard DNS on your own nameserver

While ip.alfrescodemo.net 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, djbdns,  Microsoft DNS, or some other DNS solution in place, and want to keep everything centralized in it.
  
• You are not dependent from Alfresco's alfrescodemo.net 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:

 localdomain.lan 

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

 192.168.1.5  

Suppose your wildcard DNS names were contained within:

 ip.localdomain.lan

In this case, edit:

 $VIRTUAL_TOMCAT_HOME/conf/alfresco-virtserver.properties

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

 alfresco.virtserver.domain=ip.localdomain.lan

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 ip.alfrescodemo.net 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 http://www.google.com/search?hl=en&safe=off&q=Microsoft+DN... http://www.google.com/search?hl=en&safe=off&q=BIND+bugs&bt....  Be careful.

FAQ

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