February 2015

Gavin Pickin

Adding Goodies to Server.xml to make life easier with Lucee

CFML Server, Lucee, Server Admin

As I mentioned in my last post, where we started installing and setting up Lucee, a lot of the setup here is repeated (for the most part) from the Multi Engine Environment blog posts, and presentation I did at last years CF.Objective() which is now known at Dev.Objective(). We looked at installing Lucee, and changing the HTTP Port, AJP Port, and the Shutdown port already, now, lets dive deeper into the Server.xml file, and make it easier to manage going forward.

Depending on your system, server.xml for your installation is not easily accessible, you usually have to sudo open it, and if you want to script setup into it, its just difficult. One of the first steps I do with an Engine like this, is use an Include for additional sites / hosts, similarly to how you do it in Apache. Apache has its own method Include you can use, but server.xml is standard xml, so we can use those tools.

At the top of your server.xml, found in {{ServerDir}}/conf/ you will see the following opening XML Tag… right about the License comments.

<?xml version='1.0' encoding='utf-8'?>

What we are going to do, is declare an xml variable here, known as entity, and point it to an xml file. This will load the xml from that file, and store it in the entity, and we can use that variable/entity elsewhere in the file. So lets add a few lines right below that first line.

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE server-xml [
  <!ENTITY vhosts-config SYSTEM "file:///www/_servers/conf/inc_lucee_hosts.xml">

SO here, you can see our variable / entity is called “vhosts-config” and we’re loading inc_lucee_hosts.xml from a file location. I keep all of my conf files in a general location… so apache virtual confs, apache inc files for engine connectors, files for Adobe ColdFusion, but you can organize it how you see fit. I just make sure its somewhere I can easily edit and save, and I can make accessible for automation if i want. I built a simple editing tool, for outputting conf files from a database, but the UI is in limbo, if I finish it, I will release it.

PLEASE NOTE: There are three forward slashes, file:// is the resource location prefix, then the path is /www/_servers/conf so if you combine them, its file:///www/

The inc_lucee_hosts.xml file looks like this.
<Host name="" appBase="webapps">
     <Context path="" docBase="/www/JustMockIt"></Context>
<Host name="" appBase="webapps">
     <Context path="" docBase="/www/ITB2014-Meet-The-Family"></Context>

This is just simple Host configs that go further down the server.xml file. Anytime you want to add a new Site, you can just add the config here. Usually I place my includes at the bottom of the Engine container… so essentially, 3-4 lines from the bottom. The bottom of my Lucee server.xml file fresh from install looks like this.

    <Engine name="Catalina" defaultHost="localhost">
      <!--For clustering, please take a look at documentation at:
          /docs/cluster-howto.html  (simple how to)
          /docs/config/cluster.html (reference documentation) -->
      <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>
      <!-- Use the LockOutRealm to prevent attempts to guess user passwords
           via a brute-force attack -->
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <!-- This Realm uses the UserDatabase configured in the global JNDI
             resources under the key "UserDatabase".  Any edits
             that are performed against this UserDatabase are immediately
             available for use by the Realm.  -->
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <!-- SingleSignOn valve, share authentication between web applications
             Documentation at: /docs/config/valve.html -->
        <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
        <!-- Access log processes all example.
             Documentation at: /docs/config/valve.html
             Note: The pattern used is equivalent to using pattern="common" -->
        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />

As you can see, there is one HOST container defined, it is the localhost, with appBase set to web apps, and includes some comments, and a valve. Instead of editing this file every time we want to add a new Host, we want to edit the inc_lucee_hosts.xml file, and have that variable / entity definition we created at the top of the file allow us to include those hosts automatically.
So below the </Host> we want to make a little space, and add output the contents of that variable / entity, i.e. the file.

Now, whenever you start your Lucee server, the Host containers will be inserted into your Server.xml without needing to touch it again.

by Tim Brown
02/02/2015 08:36:45 PM

Does this still require a Tomcat Restart? Is there a graceful restart/refresh option when additional vhosts are added?

by Gavin
02/03/2015 08:45:06 AM

I know there are some ways that you can setup Tomcat to watch for changes, and reload them, I have to test and see if this will work or not, I would say probably not, since it is outside the original XML file.

I am going to do more experimentation with this, and I will post a follow up. I intend to write up the Tomcat watch as well, although Mark Drew wrote about it just recently, which coincided with the Lucee release. I'll follow up when I know more. Thanks for reading.

by Andy K
02/22/2015 05:38:34 PM

I don't think this ability is enabled by default anymore in Tomcat 8 (or even later versions of Tomcat 7) There is a xmlBlockExternal setting that now defaults to "true" ... not sure where to set back to false to allow entity includes again though?

Blog Search