How to use Configuration Templates

Introduction

If you are using OpenLiteSpeed, LiteSpeed Web ADC, or native LiteSpeed Web Server Enterprise without a control panel, you can take advantage of virtual host configuration templates.

Today we’ll show you how templates work, go over some benefits, and walk you through an example usage.

Benefits of Templating

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 of their configurations at once. Plus, configuring a new vhost can be as simple as connecting it to the template.

How Configuration Templates Work

Each template contains three things:

1. a configuration file
2. a list of mapped listeners, and
3. a list of member virtual hosts.

Creating a Template

To create a brand new template, navigate to WebAdmin Console > Configuration > Virtual Host Templates > Add. You will be asked to fill out basic information for this template. One of the fields will require the location of your template file. If you do not have a template file yet, that’s fine. You can make up a new file name and LiteSpeed will create it for you in $SERVER_ROOT/conf/templates/.

For the purposes of this blog post, let’s call your new template mytemplate.

Once you’ve added mytemplate, you don’t need to configure any more settings, though you will probably want to.

Most of the settings in a virtual host template are comparable to normal virtual host settings. The main difference is that you can use the $VH_NAME variable in template settings to stand in for the names of the virtual hosts that you will be applying the template to.

Applying a Template to a Virtual Host

A virtual host template does nothing until you assign it to some member virtual hosts.

Virtual host template settings are located in the WebAdmin Console under Configuration > Virtual Host Templates. That is where you can find a list of your existing templates.

To add virtual hosts to mytemplate, click mytemplate and navigate to Template > Member Virtual Hosts > Add. Each virtual host you add will be automatically configured with the mytemplate settings. The member virtual host’s name will be substituted anywhere that $VH_NAME appears in the template settings. And listener-to-virtual host mapping will be added automatically for all listeners in the template’s mapped listener list.

Making Changes to a Template

In the WebAdmin Console, navigate to Configuration > Virtual Host Templates, and click View/Edit next to mytemplate, (or whichever template you wish to edit).

When you update the settings in a virtual host template, all of the member virtual hosts will automatically take on the new settings.

You will need to perform a Graceful Restart to put your updates into effect.

Default Templates

Our server products may come with some default virtual host templates, which can be found in the $SERVER_ROOT/conf/templates/ directory.

LiteSpeed Web Server has three, for the three most common types of virtual hosts:

• centralConfigLog is good for basic virtual hosts that will use the same server root directories and share a common directory naming framework.
• PHP_SuEXEC contains a setup ideal for hosting external PHP applications running in suEXEC mode. PHP scripts for member virtual hosts will be executed as the owner of the virtual host’s document root.
• EasyRailsWithSuEXEC is just like the PHP_SuEXEC template, but for Ruby on Rails applications.

Example

Let’s set up a new template in the LiteSpeed WebAdmin Console.

1. Click Configuration > Listeners and delete the default port 80 listener.
2. Click Add. Set the following, and click Save:
   1. Listener name: http
   2. Port: 80
   3. Binding Not set
3. Repeat step 2 to create an https listener for port 443.
4. Configure an SSL certificate for the https listener.
5. Click the Virtual Host Templates tab and click Add. Set the following, and click Save:
   1. Template Name: mytemplate (or whatever name you would like to use)
   2. Template file: /usr/local/lsws/conf/templates/mytemplate.xml
   3. Mapped Listeners:http, https
6. Click View/Edit on mytemplate. Click the General tab, and click Edit. Set the following, and click Save:
   1. Default Virtual Host Root: /home/$VH_NAME/
   2. Config file: /usr/local/lsws/conf/vhosts/$VH_NAME.xml
   3. Document Root: /home/$VH_NAME/public_html
7. Click the Security tab. Set the following, and click Save:
   1. External App Set UID Mode: DocRoot UID
   2. suEXEC User: $VH_NAME
   3. suEXEC Group: $VH_NAME
8. Click the External App tab and choose the LiteApeed SAPI App type. Set the following, and click Save:
   1. Name: $VH_NAME_lsphp81 (we are using PHP v8.1 in this example, but you can use any version you like)
   2. Address: uds://tmp/lshttpd/$VH_NAME.sock
   3. Max Connections: 3
   4. Initial Request Timeout (secs): 60
   5. Retry Timeout (secs): 30
   6. Connection Keepalive Timeout: -1
   7. Command: /usr/local/lsws/lsphp81/bin/lsphp
   8. Run as user: $VH_NAME
   9. Run as group: $VH_NAME
9. Click the Script Handler tab and click Add. Set the following, and click Save:
   1. Suffixes: php
   2. Handler type: LiteSpeed SAPI
   3. Handler name: [VHost Level]: $VH_NAME_lsphp81
10. Click the Template tab and click Add. Set the following, and click Save:
    1. Virtual Host Name: site1 (or any name of your choice)
    2. Domain: site1.com
    3. Aliases: www.site1.com
11. Click the Add button again. Set the following, and click Save:
    1. Virtual Host Name: site2 (or any name of your choice)
    2. Domain: site2.com
    3. Aliases: www.site2.com
12. Repeat step 11 for every virtual host that you want to add with this template.
13. Click Graceful restart to apply your changes

Testing

Once the template is created and the site1 and site2 virtual hosts are added as members, you can (1) test that the sites exist, (2) check the file system to verify that their document roots are in the correct place, as defined by the template, and (3), verify that each site owns a running PHP processes, as defined by the template.

1. In a browser window, verify that you can successfully visit site1.com and site2.com.
2. Verify that document roots exist in /home/site1/public_html and /home/site2/public_html.
3. Run: ps -aux | grep lsphp. This command will show you any lsphp processes running, and you can verify that they are owned by site1:site1 and site2:site2.

Conclusion

You should now know why templates are useful, and you should be able to create one and assign virtual hosts as members.

If you’d like to learn more, you can see our wiki on the subject, or take a look at these instructions for creating a template to be used with LiteSpeed Web ADC and Kubernetes.