Virtual Host Templates

From OpenLiteSpeed Wiki

Revision as of 20:01, 1 August 2016 by Rholda (talk | contribs) (Instantiating a member virtual host)

When you host multiple websites on one server, you may find that many of them have similar configurations. With LiteSpeed's virtual host template feature, you can create many virtual hosts from one master template and edit all their configurations at once.


Virtual host template settings are located in the Virtual Host Templates tab in the WebAdmin console (one of the main tabs under configuration).

Making your own templates

To create a brand new template, go to WebAdmin console > Configuration > Virtual Host Templates > Add. You will be asked to fill out basic information for this template, including the location of your template file (required). If you do not have a template file yet, that is okay. OpenLiteSpeed will give you the option to create the template file if you stipulate a file that does not exist (located in $SERVER_ROOT/conf/templates/).

$VH_NAME variable

Most settings in a virtual host template are comparable to normal virtual host settings. There is, however, a special variable: $VH_NAME. $VH_NAME stands for the names of member virtual hosts you will add later. This allows you to create settings that are specific to each member virtual host. For example, the Default Virtual Host Root setting (under the General tab), requires use of the $VH_NAME variable. This is so that different member vhosts will have different roots depending on their name. (This is further pursued in the example below.)

Adding member virtual hosts

By itself, a template has no virtual hosts or websites. When you are ready to add virtual hosts with the template's settings, you must add member virtual hosts (WebAdmin console > Configuration > Virtual Host Templates > your template > Template > Member Virtual Hosts > Add). These member virtual hosts will have all the settings of your virtual host template.

When you add a member virtual host, OpenLiteSpeed will not automatically create a virtual host root for this site. You must manually create a directory in the correct location (stipulated in either the Default Virtual Host Root setting or Member Virtual Host Root setting).

Turn a member virtual host into a standalone virtual host

The Instantiate link (available on the table of member vhosts under the Template tab) changes a member virtual host into a regular virtual host. This cuts the connection between this vhost and the template. Further changes in the template will not affect this vhost and changes can be made to this virtual host without affecting other virtual hosts. Instantiating allows you to create vhosts with the basic settings of the template, but with customized settings above and beyond the template settings. You can view and edit your instantiated vhosts in the Virtual Hosts tab (WebAdmin console > Configuration > Virtual Hosts).

Default virtual host templates

By default, OpenLiteSpeed comes with three virtual host templates for three common types of virtual hosts:

  • centralConfigLog: This template is for basic virtual hosts that all use the same server root directories and share a regular system for naming their root directories, document roots, etc... This template is examined in detail in the Example section below.
  • PHP_SuEXEC: This template contains a PHP external application set up to run in suEXEC mode. (PHP scripts for these vhosts will be executed as the owner of the virtual host's document root.)
  • EasyRailsWithSuEXEC: This template is an easy way to set up Ruby on Rails applications. The template contains a context that causes scripts in the virtual host to be run with Ruby (and as the owner of the vhost's document root).

We have made other custom templates that you can import into OpenLiteSpeed. Importation instructions are included in each template's guide, though all you have to do is copy the template (an XML file) into /usr/local/lsws/conf/templates/ and then, in the WebAdmin console, add a template that is directed to the XML file.

Example: Creating a virtual host with a template

As an example we will be creating a member vhost named "test" in the centralConfigLog template.

Add the member virtual host

First, I go to the template centralConfigLog in WebAdmin console > Configuration > Virtual Host Template.

Error creating thumbnail: File missing

Looking at the General settings (the General tab) I can see places where the name I choose for my member vhost will come into play.

Error creating thumbnail: File missing

I start to add a new member virtual host by going to the Template tab and clicking Add on the Member Virtual Hosts table.

Error creating thumbnail: File missing

I name my virtual host "test". This will affect where files for this vhost should be put. Remembering the General settings (the Default Virtual Host Root setting is set to "$SERVER_ROOT/$VH_NAME"), this new vhost will now have its virtual host root at /usr/local/lsws/test. It's access log will be /usr/local/lsws/logs/test.access.log. I am OK with this, so I leave the Member Virtual Host Root setting blank.

I hit save.

Error creating thumbnail: File missing

Now I have a new virtual host. I graceful restart to apply these changes.

Error creating thumbnail: File missing

Add website content

We have a new virtual host named "test" with configs matching the virtual host template CentralConfigLog. This website, though, does not have any content. In order to create an actual website using this vhost, I must create a directory for the virtual host root:

mkdir /usr/local/lsws/test

I must then upload any content I want on the website into the vhost's document root: /usr/local/lsws/test.

Only when I have done that will I have a new website.