Traditional CommandBox servers have only a single web root and if you want to start up two separate sites, then you start two CommandBox servers which creates two separate Java processes. This may be cumbersome or even untenable if you have hundreds site separate sites you want to run as the overhead of the JVMs would require too much memory.

CommandBox can also use a popular standard called ModCFML which allows it to behave like an Adobe ColdFusion Tomcat-based installation, which you can set behind a web server and CF will pull the webroots dynamically from the web server, allowing any number of separate sites to all be run on a single JVM instance.

What is ModCFML?

ModCFML takes it's name from the convention of Apache modules, which are named mod_xyz and is really more of a standard implemented by several different libraries. The way ModCFML works, is the front-end web server (IIS, Apache, Nginx, etc) passes a few custom HTTP headers to the back end CF server on each request that tells the CF server where the web root lives for that site. Here's an overview of the related libraries:

• BonCode - Boncode is an AJP proxy for IIS which can be configured globally or on a per-site basis to proxy requests to a back-end CF server. Boncode automatically sends the ModCFML HTTP headers. Docs here.

• Apache mod_cfml module - This module can be installed into Apache HTTPd server to create an AJP reverse proxy. Docs here.

• Tomcat ModCFML Valve - This Tomcat valve creates contexts in Tomcat for the incoming ModCFML Headers. Since you're using CommandBox, you don't need this since CommandBox has support for the equivalent behavior built in!

• CommandBox - CommandBox will obey the standard ModCFML HTTP headers so long as ModCFML.enable is set to true for the server.

• Nginx or other web servers - Even though there is no native ModCFML module for Nginx, you can still use it by just setting the necessary HTTP headers manually! More on this below.

Set Up

This is the minimum needed to configure ModCFML for any front-end web server in CommandBox:

server set ModCFML.enable=true
server set ModCFML.sharedKey=my-secret
server set web.ajp.enable=true web.ajp.port=8009

That's it! The default web root for the server will be whatever folder you start the CommandBox sever in, but that default web root will only be used if a requests reaches CommandBox which doesn't contain the special ModCFML HTTP headers.

Next you'll need to install BonCode (if using IIS) or mod_cfml (if using Apache) and configure it with the same shared key for security. The web server doesn't need to be on the same server as CommandBox, but CommandBox's AJP port does need to be accessible to the web server and the port numbers need to match. 8009 is the default AJP port, but it's not a requirement.

Configuration

Here are some additional ModCFML settings you may want to tweak:

maxContexts

This limits the number of contexts which can be created to prevent a malicious client from causing a DOS from a huge number of contexts, which would eventually begin consuming memory. Default is 200.

requireSharedKey

Set this to false FOR DEVELOPMENT PURPOSES ONLY to not require the shared key header to be present. This may simplify your local setup, but do NOT enable this on any externally-accessible web server as a malicious client could send their own HTTP headers and serve content from anywhere on your server's hard drive! Default is true.

Unsupported Configuration

Here are some settings you may be familiar with in the Tomcat valve, that CommandBox does NOT use.

timeBetweenContexts

CommandBox does NOT have a corresponding setting for timeBetweenContexts **** since Undertow is VERY fast to add new contexts.

scanClassPaths

CommandBox does NOT have a corresponding setting for scanClassPaths **** because it re-uses the existing class loader and cloned Undertow deployment from the default context so no jars at all need to be scanned.

loggingEnabled

CommandBox does NOT have a corresponding setting for loggingEnabled. There is already logging as part of Runwar and the --debug flag when you start your server will automatically log additional bits.

responseCode

CommandBox does NOT have a corresponding setting for responseCode **** because it is capable of adding the new context entirely on the fly and using it immediately without needing to re-send the request.

What about Nginx, etc?

You can use any front end web server you like so long as you manually set the HTTP headers that ModCFML requires. Here they are:

• X-ModCFML-SharedKey - Needs to match the ModCFML.sharedKey in your server.json

• X-Tomcat-DocRoot - Needs to contain the absolute path to the web root for the current virtual host

• X-Webserver-Context - Optional. Will be used instead of hostname to group multiple hostnames into a single context

• X-VDirs - A string representing the aliases (virtual directories) of the web server for CommandBox to auto-create in the servlet in the format: /foo,C:\path\to\foo;/bar,C:\path\to\bar

• X-VDirs-SharedKey - Must also contain the same value as X-ModCFML-SharedKey or X-VDirs will be ignored. This is for security since the older mod_cfml Apache proxies don't override a missing X-VDir header, allowing malicious client to pass one. Only pass the X-VDirs-SharedKey header if your proxy is explicitly controlling the contents of the X-VDirs header.

For NGinx, setting the headers would look like this and would need configured for each site.

proxy_set_header X-Tomcat-DocRoot /path/to/site/www;
proxy_set_header X-ModCFML-SharedKey SHARED-KEY-HERE;

It is not required to use an AJP proxy. CommandBox's ModCFML support will process the incoming HTTP headers regardless of what protocol was used to proxy the requests to it.

Debugging

How do you confirm ModCFML is working or debug when it doesn't go right? CommandBox has automatic debug and trace level messages that will appear in the console when you start your server with the --debug or --trace flag that will tell you when a new context is deployed and what the web root is.

[WARN ] Runwar: X-Tomcat-DocRoot is null or empty.  Using default context for deploymentKey [127.0.0.1].
[INFO ] Runwar: Creating deployment [site1.com] in C:\www\site1
[DEBUG] Runwar: New servlet context created for [site1.com]
[INFO ] Runwar: Creating deployment [site2.com] in C:\www\site2
[DEBUG] Runwar: New servlet context created for [site2.com]
[INFO ] Runwar: Creating deployment [site3.com] in C:\www\site3
[DEBUG] Runwar: New servlet context created for [site3.com]

Adobe vs Lucee

CommandBox's ModCFML support will work for both Adobe and Lucee servers! Keep in mind however, that Lucee and Adobe work differently under the covers, even though it looks the same from the outside. When the server is Lucee, CommandBox's ModCFML support will create a new servlet context deployment for each web context. Each servlet context will have a context root of / and will share the same class loader as the default instance, so they will also share the same server context. Adobe only uses the default servlet context, but swaps out the resource manager per-request, just like Adobe's Tomcat-based installations work. If you don't know what all that means, don't worry.

Naked ModCFML

You maybe wondering if it's possible to make use of multiple web roots in CommandBox without having any web server at all. Well, we weren't going to let you in on this, but actually YES it is possible! All you need to do is configure some Server Rules to detect the host name and set the HTTP headers and CommandBox's ModCFML will be none the wiser. You can turn off the requirement of a shared key, but make sure you have a catch-all rule that rejects requests from unknown host names.

Here is the server.json for a simple setup. Note, we're using the commandbox-hostupdater module here to auto-create hosts file mappings for our domains. We're also pointing the webroots to site1.com, site2.com, and site3.com folders inside of the default web root, but these could really point anywhere you like.

{
    "ModCFML":{
        "enable":"true",
        "requireSharedKey":"false"
    },
    "web":{
        "hostAlias":[
            "site1.com",
            "site2.com",
            "site3.com",
            "fakedomain.com"
        ],
        "rules":[
            "equals( %{LOCAL_SERVER_NAME}, 'site1.com' ) -> set(attribute=%{i,X-Tomcat-DocRoot},value='${serverinfo.webroot}site1.com')",
            "equals( %{LOCAL_SERVER_NAME}, 'site2.com' ) -> set(attribute=%{i,X-Tomcat-DocRoot},value='${serverinfo.webroot}site2.com')",
            "equals( %{LOCAL_SERVER_NAME}, 'site3.com' ) -> set(attribute=%{i,X-Tomcat-DocRoot},value='${serverinfo.webroot}site3.com')",
            "not regex( value=%{LOCAL_SERVER_NAME}, pattern='^site[123]\\.com$', case-sensitive=false ) -> set-error(401)"
        ]
    }
}

If you want something SUPER quick and dirty for local development and you TRUST the people accessing the site, you could get really clever and just have a simple convention where the host name matches a a folder inside of your default web root. Any hostnames that didn't match a real folder would just use the default web root.

{
    "ModCFML":{
        "enable":"true",
        "requireSharedKey":"false"
    },
    "web":{
        "rules":[
            "set(attribute=%{i,X-Tomcat-DocRoot},value='${serverinfo.webroot}%{LOCAL_SERVER_NAME}')"
        ]
    }
}

HTTP bindings are much more robust in Multi-Site mode. In single-site mode, there is basically no such thing as host name bindings. All traffic coming into that CommandBox server is simply routed to the one and only server regardless of its host name or IP address.

As of version 6.0, a CommandBox server can now have

• Any number of HTTP bindings on any IP/port combination

• Any number of SSL bindings on any IP/port combination

• Any number of AJP bindings on any IP/port combination

And furthermore, a binding can be shared for all sites on the server, or could serve traffic to ONLY a single site depending on how you configure it. Think how IIS, Nginx or Apache work. You now have the same level of flexibility in CommandBox!

CommandBox 6 has introduced a new syntax for bindings (and is still backwards compatible with the old JSON syntax too) that allows you to specify hostnames alongside the bindings:

{
  "web":{
    "bindings":{
      "HTTP":{
  
      "listen":"80",
      // or...
      "listen":"*:80",
      // or...
      "listen":"0.0.0.0:80",
      // or...
      "listen":"10.10.0.123:80",
      
      // same as ""
      "host" : "*",
      // or...
      "host":"www.domain.com,www.something.com",
      // or...
      "host": [
        "www.domain.com",
        "www.something.com"
      ]  
  
    }
  }
}

Even though each site can use a different IP/port, a very common setup is to have a single port 80/443 binding at the server level shared by all sites, and then simply specify a hostname for each site. If you only need to specify a host name for a site, but don't need to declare a new binding (because you're inheriting a binding from the global level) then you can use the new hostAlias key at the site level which can be a list or array of hostnames to be layered on top of the global bindings for this site:

{
    "profile":"production",
    "directoryBrowsing":false,
    "hostAlias":"example.com,www.example.com",
    "GZipEnable":false
}

In Multisite mode, each site can have as many bindings as you want, where each binding has:

• An IP address (or all IPs, which is the equivalent to 0.0.0.0)

• A port

• Zero or more hostnames

  • Exact (full) match like www.foo.com

  • Starts-with match like *.foo.com or *bar.com

  • Ends-with match like www.foo.* or www.bar*

  • Regular expression match like ~www\.(bob|tom|bernard)Industries\.(com|net|org)

When a request comes into CommandBox in multi-site mode, the most specific binding will be found, and the traffic served to the matching site. The order of precedence of binding matching is as follows:

• Exact IP and hostname match

• Exact IP and hostname ends with match

• Exact IP and hostname starts with match

• Exact IP and hostname regex match

• Any IP and hostname exact match

• Any IP and hostname ends with match

• Any IP and hostname starts with match

• Any IP and hostname regex match

• Try Exact IP and any hostname

• Any IP and any hostname

• Default site

If you need help debugging how your bindings are being assembled at runtime, you can use this command:

server info --verbose

which will show you all the listeners (ports/IPs) that CommandBox is listening to at the OS level as well as all the bindings for each site that control what listeners will map to them:

  - site1: http://site1.com:80 --> C:\path\to\site1\
      Bindings:
        - 0.0.0.0:80:site1.com

  - site2: http://site2.com:80 --> C:\path\to\site2\
      Bindings:
        - 0.0.0.0:80:site2.com

  - site3: http://site3.com:80 --> C:\path\to\site3\
      Bindings:
        - 0.0.0.0:80:site3.com

  - default: http://127.0.0.1:80 --> C:\path\to\default\
      Bindings:
        - 0.0.0.0:80:*
        - Default Site

  Listeners:
    - HTTP
      - 0.0.0.0:80

If you do not specify any bindings at all, it will still pick a random port to bind to. It will also pick a SEPARATE random port for each site so you can access each site separately.

Each site can have a default open browser URL, but CommandBox will not automatically open a browser in Multi-Site mode. These URLs will be available in a sub menu of the tray icon, or can be used from the server open command like so:

server open siteName=site3

Default site

If no bindings were matched, then CommandBox will look for a default site configuration. Unlike IIS which has a default site created by scratch, or Apache which just takes the first site defined, CommandBox requires you to explicitly define a default site like Nginx. If no default site is defined, CommandBox has a built in "site not found" error page that will be shown. You can avoid or "turn off" this default page by setting a default site.

Configure any of your sites to be the default site by adding a default key set to true inside the site JSON. It doesn't matter whether the site is defined in the server.json in the sites object or in an external site JSON file.

{
  "webroot" : "www/default",
  "default" : true
}

The default behavior when you run server start is to start a server that points only to a single web root. There are two methods you can use to host more than one web root at a time in a single CommandBox server:

• ModCFML- this requires a web server sitting in front of CommandBox which sends special HTTP headers that instruct CommandBox what to use as the web root.

• Multi-Site mode- this is new in CommandBox 6.0 and it allows full configuration of multiple sites (web roots), rewrite, HTTP/SSL bindings, and settings inside of a single server.

In both cases, there is a single JVM process and a single CF Engine at play. So all sites will use the same CF engine and version. If you want to run different versions of CF, you'll need more than one server. You can use a reverse proxy in your server rules to still access all your sites via a single "front end" server instance.

The CommandBox built-in web server is now fully fledged with out-of-the-box support for multiple bindings, host header matching, multiple SSL certs/SNI, and full control over rewrites gzip compression, virtual directories (aliases) and secure profiles on a per-site basis. CommandBox is now truly the only tool you need to deploy your code! There's no need to have Apache, IIS, or Nginx in the mix any longer.

There is a repo on Github that contains working examples of all the features of Multi-Site. Feel free to skip straight there to learn by example.

https://github.com/Ortus-Solutions/commandbox-tests

Tuckey Rewrites

Please note that the legacy form of rewrites using Tuckey will NOT work by default in Multi-Site mode. There are two main reasons for this limitation:

• Tuckey is tied to the servlet and static files are now no longer served by the Default Servlet, but are returned to the browser without even touching the servlet.

• There is only one servlet servicing all sites, so you can't have different rewrites per site.

Not ready to leave Tuckey? You can force the new Undertow web server to not serve static files by setting servletPassPredicate=true, which will send ALL files to the servlet:

server set web.servletPassPredicate=true

Read more about the servlet pass predicate here.

However, the best approach is to simply switch over to using Server Rules. They do everything Tuckey does, AND each site can get its own separate set of server rules for maximum configurability.

Also note, when you set this flag:

server set web.rewrites.enable=true

as of CommandBox 6, a Tuckey XML rewrite file will no longer be employed. Instead Server Rules will be added that perform the same rewrites as the old Tuckey functionality. Tuckey will now ONLY be used if you specify a custom rewrite file.

In a traditional server setup, you are used to two separate pieces of software

• A web server like NGinx, Apache, or IIS which serves static files, performs URL rewrites, and proxies some requests off to a servlet

• A Servlet container like Tomcat or CommandBox receiving the proxied requests on another port (HTTP or AJP) and processing CF code

In CommandBox, now we have the ability to combine both of those bullets together into a single piece of software. No reverse proxy is needed, nor is a second port to proxy to.

In all cases with the legacy setup, there is always a check of some kind that decides which requests will get sent to the servlet. This is usually checking for URLs ending in .cfm or .cfc. Common implementations of this are:

• Adobe's CF connector

• The mod_cfml module for Apache

• BonCode for IIS

• A custom proxy directive in your web server.

As of CommandBox 6, we have the same setting and it can be set as web.servletPassPredicate which is simply an Undertow Predicate. By default, CommandBox uses the following predicate for the servletPassPredicate:

regex( '^/(.+?\\.cf[cm])(/.*)?$' )

So the URI /index.cfm will get sent to the servlet, but /test.txt would just get sent by the static file resource handler. You can customize this if necessary with any valid Undertow predicate. It can even be different on a per-site basis by setting it inside the sites object or .site.json file for a given site.

# Send ALL traffic to the servlet (the servlet's default handler will serve static files)
server set web.servletPassPredicate=true

# Only serve CF files out of the cgi folder
server set web.servletPassPredicate="regex( '^/cgi/(.+?\\.cf[cm])(/.*)?$' )"

# process CFM files or anything in the /REST/ directory
server set web.servletPassPredicate="regex( '^/(.+?\\.cf[cm])(/.*)?$' ) or path-prefix-nocase( /REST/ )"

Note, be careful as your servlet pass setting may send .cfm files to the static file handler. CommandBox has a failsafe in place to prevent the source code from being returned, but you should still use caution when configuring this.

There's no flag or setting for enabling multiple sites in a single server. All you have to do is

• define a sites object in server.json

• or a siteConfigFiles setting in server.json

inside your server.json and if one or more sites are found, CommandBox will automatically switch over to "Multi-Site" mode. It's easy to tell if a server has more than one site. When you start it, the console output will have a dedicated section in the output for each site. There is also additional information in the server info command about each site.

❯ start --dryRun
 √ | Starting Server
   | √ | Configuring site [site1]
   |   | √ | Setting site [site1] Profile to [production]
   | √ | Configuring site [site2]
   |   | √ | Setting site [site2] Profile to [production]
   | √ | Configuring site [site3]
   |   | √ | Setting site [site3] Profile to [production]

Let's explore the two methods of defining more sites.

Define a "sites" object in server.json

The sites object will have a key for each site you want to define where the name of the key is the name of each site and the value is another object containing the configuration of that site. Think of all of the setting which can be set in the web object of server.json. Each site object in the sites object can have all the same settings as the top-level web object so it will be very familiar.

{
    "name":"My server",
    "web":{
        // These settings apply to all sites
        "accessLogEnable":"true",
        "bindings":{
            "HTTP":{
                "listen":"80"
            }
        }
    },
    "sites":{
        "site1":{
            "hostAlias":"site1.com",
            "webroot":"/path/to/site1"
        },
        "site2":{
            "hostAlias":"site2.com",
            "webroot":"/path/to/site2",
            // Overrides the default above coming from "web"
            "accessLogEnable":"false",
        }
    }
}

The simple example server.json above, some defaults that apply to all sites are defined in the top-level web object. Then we have two sites, site1 and site2 defined with their own settings. Remember, each site object is just a copy of the web object above, so all the same settings are valid. You can use the server set command to configure these and rely on the tab completion to help prompt you with all valid options.

The ONLY required settings for each site are

• webroot

• or siteConfigFile which points to a JSON file on disk where a web root must be defined

{
    "sites":{
        "client-1":{
            "siteConfigFile":"/var/www/client1-site.json"
        },
        "client-2":{
            "siteConfigFile":"/var/www/client2-site.json”
        }
    }
}

If you want to access each site individually, you'll either want to specify a separate HTTP/SSL/AJP binding OR a custom hostname for each site. Otherwise, you'll have no way to access them!

You can also place a .site.json file inside of the web root, which will be found by convention and its contents will be added to the site object for that site. This is akin to configuring your sites in Apache, but having an .htaccess file in each web root to override settings.

System setting expansions will be processed in any .site.json files, and if a .env file exists in the web root as well, thoses env vars will be loaded, but JUST for that .site.json file's expansions.

Define a siteConfigFiles setting in server.json

If you have a lot of sites, or a lot of settings, the first option can become unwieldly since the server.json will have a lot of stuff in it. That is why we also allow you to specify a siteConfigFiles setting which contains a list or array of file globbing patterns or directories to look for JSON files in. Once all the JSON files have been found, they will be used to define sites. each JSON file will contain JUST the contents of the object you would have put in the sites object of server.json which has all the same options as a web object in server.json.

Valid examples could be:

{
    "name":"My server",
    "web":{
        // These settings apply to all sites
        "accessLogEnable":"true",
        "bindings":{
            "HTTP":{
                "listen":"80"
            }
        }
    },
    "siteConfigFiles" : "C:/absolute/path/to/configs/"
    // or...    
    "siteConfigFiles" : "../relative/path/to/configs/"
    // or...    
    "siteConfigFiles" : "../marketingSites/*-active.json,../internalSites/**/*-active.json"
    // or...    
    "siteConfigFiles" : [
        "../marketingSites/*-active.json",
        "../internalSites/**/*-active.json"
    ]
    // or...    
    "siteConfigFiles" : [
        "../sites/site1.json",
        "../sites/site2.json",
        "../sites/site3.json"
    ]
}

System setting expansions will be processed in any of the site JSON files located via your file globbing patterns. If the server.json has a sites object AND a siteConfigFiles setting, all sites will be combined together. Feel free to choose the approach that fits your needs!

As soon as CommandBox flips over to Multi-Site mode, the settings in the web object will become defaults that apply to all sites. This allows you to group global settings into the top-level web object and then override what you need for each site. Here is the full order of precedence for what settings will be applied:

• settings in a .site.json file inside a web root of a site

• settings in an external site JSON file pointed to by the siteConfigFiles setting in server.json

• site-specific object in the sites object of server.json

• settings in the web object of server.json

• server.default settings in CommandBox's global config settings

Settings global to a server

Since all sites for a given server do run inside the same JVM, there are some settings which cannot be customized on a per-site basis. They are as follows:

• JRE/JDK the server runs on

• JVM args, heap size

• CF Engine/version

• Console log

• Tuckey Rewrites (part of servlet)

• Environment Variables

• Tray icon (there is a single tray icon for the entire server)

Per-site settings

Everything normally set in the web block of your server.json can be configured separately for each site. These settings include:

• GZIp enabled and GZip predicate

• Access log

• Use proxy forwarded IP

• CommandBox Server Rules (Undertow Predicate Language)

  • SSL settings (HSTS, SSL Redirect)

  • Block CF Admin

  • Block flash remoting

  • Block sensitive paths

• Security

  • Basic auth

  • Client cert auth

  • Security predicate

• Custom error pages (404, 500, etc)

• Mime types

• Welcome files

• Allowed file extensions

• Directory browsing

• Aliases/Virtual dirs

• File cache settings

• Case sensitive paths

• Web root

• Server Profile (even though this is not inside the web object in your server.json, it can still be set in a sites block to override for that site.)

And remember, all of the settings in the section above can be defaulted for all sites in the web block at the top of your server.json and then overridden in the sites.siteName block or in a .site.json file.

Debugging settings

There is much-improved console output now coming from Runwar when the server starts up. Add --verbose or --debug to your server start command and you'll see site debug output at the top of the server start in the interactive job output:

   |   |--------------------------------------------------------------
   | √ | Configuring site [site1]
   |   |---------------------------------------
   |   | Site name - site1
   |   | Webroot - C:\path\to\site1\
   |   | Site config file - C:\path\to\server.json
   |   |---------------------------------------
   |   | √ | Setting site [site1] Profile to [development]
   |   |   |------------------------------------------------------------
   |   |   | Profile set from server bound to localhost
   |   |   | Block CF Admin disabled
   |   |   | Block Sensitive Paths enabled
   |   |   | Block Flash Remoting enabled
   |   |   | Allowed Extensions: [log]
   |   |   | Directory Browsing enabled
   |   |   | File Caching disabled
   |   |   |------------------------------------------------------------
   | √ | Configuring site [site2]
   |   |---------------------------------------
   |   | Site name - site2
   |   | Webroot - C:\path\to\site2\
   |   | Site config file - C:\path\to\server.json
   |   |---------------------------------------
   |   | √ | Setting site [site2] Profile to [development]
   |   |   |------------------------------------------------------------
   |   |   | Profile set from server bound to localhost
   |   |   | Block CF Admin enabled
   |   |   | Block Sensitive Paths enabled
   |   |   | Block Flash Remoting enabled
   |   |   | Allowed Extensions: [log2]
   |   |   | Directory Browsing enabled
   |   |   | File Caching disabled
   |   |   |------------------------------------------------------------
   | √ | Configuring site [site3]
   |   |---------------------------------------
   |   | Site name - site3
   |   | Webroot - C:\path\to\site3\
   |   | Site config file - C:\path\to\server.json
   |   |---------------------------------------
   |   | √ | Setting site [site3] Profile to [development]
   |   |   |------------------------------------------------------------
   |   |   | Profile set from server bound to localhost
   |   |   | Block CF Admin disabled
   |   |   | Block Sensitive Paths enabled
   |   |   | Block Flash Remoting enabled
   |   |   | Allowed Extensions: [log]
   |   |   | Directory Browsing disabled
   |   |   | File Caching disabled
   |   |   |------------------------------------------------------------
   | √ | Configuring site [default]
   |   |-----------------------------------------
   |   | Site name - default
   |   | Webroot - C:\path\to\default\
   |   | Site config file - C:\path\to\server.json
   |   |-----------------------------------------
   |   | √ | Setting site [default] Profile to [development]
   |   |   |--------------------------------------------------------------
   |   |   | Profile set from server bound to localhost
   |   |   | Block CF Admin disabled
   |   |   | Block Sensitive Paths enabled
   |   |   | Block Flash Remoting enabled
   |   |   | Allowed Extensions: [log]
   |   |   | Directory Browsing enabled
   |   |   | File Caching disabled
   |   |   |--------------------------------------------------------------

Furthermore, once the actual server process gets underway, with the --trace flag you'll see additional console output like so:

[INFO ] Runwar: ******************************************************************************
[INFO ] Runwar: Starting Runwar
[INFO ] Runwar:   - Runwar Version: 5.0.0-SNAPSHOT
[INFO ] Runwar:   - Java Version: 11.0.22+7 (Eclipse Adoptium)
[INFO ] Runwar:   - Java Home: C:\path\to\jre
[INFO ] Runwar: ******************************************************************************
[INFO ] Runwar: Listeners:
[INFO ] Runwar:   - Binding HTTP on 0.0.0.0:80
[DEBUG] Runwar:      Setting HTTP/2 enabled: true
[INFO ] Runwar: ******************************************************************************
[INFO ] Runwar: Configuring Servlet
[DEBUG] Runwar:   File cache is disabled
[DEBUG] Runwar:   Ignoring web.xml welcome file, so adding server options welcome files to deployment manager.
[INFO ] Runwar:   Found WEB-INF: 'C:\path\to\WEB-INF'
[DEBUG] Runwar:   Parsing 'C:\path\to\WEB-INF\web.xml'
[TRACE] Runwar:     Total No. of context-params: 0
[TRACE] Runwar:     Total No. of listeners: 0
[TRACE] Runwar:     Total No. of servlets: 2
[TRACE] Runwar:       servlet-name: CFMLServlet, servlet-class: lucee.loader.servlet.CFMLServlet
[TRACE] Runwar:       servlet-name: RESTServlet, servlet-class: lucee.loader.servlet.RestServlet
[TRACE] Runwar:       Mapping servlet-name: CFMLServlet, url-pattern: *.cfc
[TRACE] Runwar:       Mapping servlet-name: CFMLServlet, url-pattern: *.cfm
[TRACE] Runwar:       Mapping servlet-name: CFMLServlet, url-pattern: *.cfml
[TRACE] Runwar:     Total No. of welcome files: 4
[TRACE] Runwar:       welcome-file: index.cfm
[TRACE] Runwar:       welcome-file: index.lucee
[TRACE] Runwar:       welcome-file: index.html
[TRACE] Runwar:       welcome-file: index.htm
[INFO ] Runwar: ******************************************************************************
[INFO ] Runwar: Creating deployment [default]
[DEBUG] Runwar:   Initialized MappedResourceManager
[INFO ] Runwar:     Web Root: C:\path\to\default
[DEBUG] Runwar:     Aliases: {/js=C:\path\to\javascript}
[DEBUG] Runwar:   Adding Mime types
[TRACE] Runwar:   - log = 'text/plain'
[DEBUG] Runwar:   New servlet context created for [default]
[DEBUG] Runwar: ******************************************************************************
[INFO ] Runwar: Creating deployment [site3]
[DEBUG] Runwar:   Initialized MappedResourceManager
[INFO ] Runwar:     Web Root: C:\path\to\site3
[DEBUG] Runwar:     Aliases: {/js=C:\path\to\javascript, /js-brad=C:\path\to\site3\javascript}
[DEBUG] Runwar:   Adding Mime types
[TRACE] Runwar:   - log = 'text/plain'
[DEBUG] Runwar:   New servlet context created for [site3]
[DEBUG] Runwar: ******************************************************************************
[INFO ] Runwar: Creating deployment [site1]
[DEBUG] Runwar:   Initialized MappedResourceManager
[INFO ] Runwar:     Web Root: C:\path\to\site1
[DEBUG] Runwar:     Aliases: {/js=C:\path\to\javascript}
[DEBUG] Runwar:   Adding Mime types
[TRACE] Runwar:   - log = 'text/plain'
[DEBUG] Runwar:   New servlet context created for [site1]
[DEBUG] Runwar: ******************************************************************************
[INFO ] Runwar: Creating deployment [site2]
[DEBUG] Runwar:   Initialized MappedResourceManager
[INFO ] Runwar:     Web Root: C:\path\to\site2
[DEBUG] Runwar:     Aliases: {/js=C:\path\to\site2\javascript}
[DEBUG] Runwar:   Adding Mime types
[TRACE] Runwar:   - log2 = 'application/xml'
[TRACE] Runwar:   - log = 'text/plain'

One of the most useful features of CommandBox is the ability to start an ad-hoc server quickly and easily. Any folder on your hard drive can become the web root of a server. To start up the server, cd into a directory containing some CFML code, and run the start command. An available port will be chosen by default and in a few seconds, a browser window will open showing the default document (index.cfm).

CommandBox> cd C:\sites\test
CommandBox> start

To stop the embedded server, run the stop command from the same directory.

CommandBox> stop

OS Integration

You can start as many embedded server instances as you want. Each running server will add an icon in your system tray with the logo of your currently running engine. Click on it for options:

• Stop Server

• Open Browser

• Open Admin

• Open File System

Open Browser

When a server finishes starting, CommandBox will automatically open up the root of the site in your default browser. You can control the URL that is opened with

server set openBrowserURL=/admin/foo.cfm

You can change the browser used to open all sites or override just the browser for a single site:

# Global setting
config set preferredBrowser=Chrome
# Per-server setting
server set preferredBrowser=Chrome

Or you can disable this feature entirely

# Global setting
config set server.defaults.openBrowser=false
# Per-server setting
server set openBrowser=false

Disable the tray icon

If you don't want the tray integration, then you can turn it off in your server.json with this setting.

server set trayEnable=false

Or turn it off at a global level in your config settings.

config set server.defaults.trayEnable=false

Full Control

CommandBox's embedded server does not require any prior installations of any CFML engine to work. It does not use Apache, IIS, or Nginx. A very lightweight Java web server called Undertow is used and a context is programmatically deployed via a WAR file.

You should still have all the options you need to set up most local development servers quickly. The web-based administrator is available to you where you can edit any setting, add data sources, CF mappings, and mail servers. To see a list of all the parameters you can pass to the server start command, refer to the CommandBox API Docs or run server start help command directly from the CLI.

Environment Variables

Any ComandBox environment variables present in the shell will automatically be passed to the environment of the server process. This means, given an example like this:

set foo=bar
server start

The CFML code running that server process will be able to "see" the foo environment variable.

You can specify the CFML engine via the command line arguments:

This will start an Adobe ColdFusion 2018 server in your webroot. That's it!

By default, CommandBox uses the cfengine slug to search for the engine on ForgeBox. The format is slug@version where the version is optional. Ortus Solutions maintains the versions of the engines available on ForgeBox.

Supported engines are:

• Adobe ColdFusion 9 **

• Adobe ColdFusion 10

• Adobe ColdFusion 11

• Adobe ColdFusion 2016

• Adobe ColdFusion 2018

• Adobe ColdFusion 2021

• Adobe ColdFusion 2023

• Lucee 5

• Lucee 6 (beta)

• Railo 4.2

• Lucee 4.5

Here are some examples:

Engines are downloaded and stored in your CommandBox artifacts folder. You can view your engines and clear them using the standard artifacts commands:

Admin password

ColdFusion requires a username and password when CommandBox sets it up. When using the (default) development CommandBox profile, the default username and password for the Adobe ColdFusion servers used are:

• Username: admin

• Password: commandbox

Since Lucee 5.3.4.46, Lucee no longer prompts you to set the admin password the first time running the admin. When using the (default) development CommandBox profile, Lucee offers the option for you creating a password.txt file to set that initial password.

See also options to [control the admin password via CFConfig(https://cfconfig.ortusbooks.com/using-the-cli/commandbox-server-interceptors/server-start#set-individual-settings)].

WAR Support

Additionally, CommandBox can start any WAR given to it using the WARPath argument.

If you run a regular start command inside of a folder that has a /WEB-INF/web.xml file, CommandBox will treat that folder as a WAR.

Custom Engines

The cfengine parameter can accept any valid CommandBox endpoint ID. That means it can be an HTTP URL, a Git repo, a local folder path to your company's network share, or a custom ForgeBox entry you've created. As long as that endpoint resolves to a package that contains these files, you're good:

1. box.json

2. Engine.[zip|war] (file name doesn't matter)

CommandBox will download the package, unzip it and use the WAR/zip file as the engine for your app.

Normally, the artifacts cache isn't used for non-ForgeBox packages, but CommandBox will only download the engine once per server and then assume the file hasn't changed. You will need to forget the server to trigger a new download.

Here's an example of starting up a web server using a direct download link to a package containing a WAR file:

server.json Configuration

You can set the cfengine and other related configuration options in your server.json to use them every time you start your app.

These commands would create the following server.json

Just a reminder that starting a server with any command line arguments will save the arguments to your server.json by default.

This command would add adobe@2023 to your server.json. If this is not what you want, you can append saveSettings=false or even --!saveSettings when you start your server and CommandBox will not save the arguments you specify to your server.json.

Remember to use Semantic Versions

One minor difference to keep in mind is Lucee server and Adobe ColdFusion use a typical versioning scheme for java projects which looks like this:

However, and use the (semver) which is slightly different. Basically the build ID is moved to the end after a plus (+) sign.

The important thing to remember is, when starting a server via CommandBox always use the second format shown above since that is how ForgeBox recognizes each release.

What versions exist?

Questions about what versions are available? No problem! Here are some ways you can find out:

• View the last few versions via the CLI with the command forgebox show lucee

• Start typing your cfengine and hit the <tab> key to invoke the tab-completion feature. This actually phones out to ForgeBox as you hit tab to get the current valid list of versions that match what you've typed so far

You can also follow the Lucee bleeding edge, which means every time you start your CommandBox server you'll get the very latest Lucee snapshot release. Please only use this for local development and not production!

Pinning Exact Version

It is a nice feature of CommandBox to have it automatically grab the latest version of your favorite CF engine every time it starts.

However, you may have good reason to NEVER want a new version automatically installed. In order to do this, you must specify a COMPLETE version number, including the build number, making sure to use the proper version format. This means you need a major, minor, patch, and build number.

Lucee Light builds on ForgeBox

We're now publishing CF Engines to ForgeBox based on the Lucee Light builds which allows you to start up a Lucee Light server. These are under a ForgeBox package named lucee-light and we've also backfilled all the same versions that exist for the normal lucee engine. Note, the three bullets points above apply to Lucee Light as well, Just replace lucee with lucee-light and you're good to go.

If you have questions about how to install extensions into a Lucee light server, please hit us up on Slack and we can show you several ways to manage that.

You may want to start up a local server that does not have a CF Engine such as Lucee or Adobe ColdFusion installed. You can do this as of CommandBox 5.1.0 by setting the cfengine parameter to none like so:

Or in your server.json like this

This server will support everything that you are used to including the server.json file, heap settings, ports, and virtual directories. The only difference is it will server everything as static files. (.cfm or .cfc files will not be processed)

This is what a typical ColdFusion deployment looks like. A separate web server sites in front, bound to ports 80 and 443 and proxies back to a Tomcat-based servlet:

CommandBox's Servlet configuration

For a CommandBox server, we replace the green box above with JBoss Undertow instead of Tomcat and we configure it on the fly with CommandBox. Here's a look under the covers at what the internal pieces of CommandBox look like for a single site server.

We have a set of HTTP/SSL/AJP listeners that feed through a single handler chain of configuration that funnel requests to the servlet deployment where the CF engine's libs are loaded. The default servlet serves static files via the singular resource manager configured to look in the web root.

CommandBox Multi-Site with Lucee

Here is what a Multi-Site server looks like under the covers for Lucee Server (which works differently than Adobe). This is mostly the same regardless of whether you're using ModCFML or the new Multi-Site features.

Here the listeners funnel to a handful of different initial handler chains, which represent the different configuration between sites. The Lucee jars are loaded once and the Lucee Servlet Context exists once. Each site has a separate servlet deployment where a separate Lucee Web Context lives, along with their own CFML Servlet, default servlet, and resource manager configured for their separate web root.

In Multi-Site mode, static files are NOT served by the default servlet, but instead by an Undertow resource handler in the initial handler chain. The web.servletPassPredicate controls what requests even reach the servlet. Static files are served without ever touching the servlet.

CommandBox Multi-Site with Adobe CF

Here is what a Multi-Site server looks like under the covers for Adobe ColdFusion (which works differently than Lucee). This is the mostly the same regardless of whether you're using ModCFML or the new Multi-site features.

Like the Lucee example above, the listeners pass requests off to one of several initial handler chains, which represent different per-site configurations. However, we only have a single servlet deployment in this case and a single default servlet. The resource manager delegates out to sub-resource managers based on the site being accessed to switch out the web root as necessary.

In Multi-Site mode, static files are NOT served by the default servlet, but instead by an Undertow resource handler in the initial handler chain. The web.servletPassPredicate controls what requests even reach the servlet. Static files are served without ever touching the servlet.

This has several Multi-Site examples in the folders starting with the words multi-site-. Here is an overview of a few of them.

Basic Multi-Site configured in server.json

Here is a basic server.json configuring several sites. Here we have some defaults configured in the web object for all sites, including a single HTTP binding to all IPs on port 80. There is a custom host alias configured on each site. There is a site called "default" which is set to the default site with default=true in the site object.

Custom Bindings

This example server contains custom HTTP and SSL bindings for each server. You'll probably never need anything this complex, but we support it all! The HTTP port 81 binding on all IPs, SSL binding on port 444, and AJP binding on port 8010 are shared by all sites. Each site then adds additional bindings specific to the site. Needless to say, there are multiple URLs that lead to each site.

Web root convention

This example server configures some defaults in the web object and then simply points to the web root of several sites where a .site.json file is waiting to further configure each site:

And here are the .site.json files from each of the web roots:

Per-site siteConfigFile

This example is similar to above, but instead of pointing to the web root of each site, it points to the site config file for each site, which is stored outside of the web roots:

In this example, the site1.json, site2.json, site3.json, and default.json files all live in the same directory as the server.json and would point to their respective webroots like so:

SiteConfigFiles globbing pattern

In this example, we have a single file globbing pattern that points to a directory of JSON files that define the sites:

In this example, we have a folder called sites-enabled in the same directory as the server.json with one or more JSON files. Here is an example:

Note the relative paths are always relative to this JSON file.

FusionReactor is a popular tool for monitoring performance and gathering metrics for ColdFusion and Java J2EE applications. You may wish to use FusionReactor with the servers you start up via CommandBox. We've created a CommandBox module that will add FusionReactor support to your CommandBox servers which you can view here on ForgeBox.

https://www.forgebox.io/view/commandbox-fusionreactor

Installation

The CommandBox FusionReactor module is a separate project that you can optionally install by typing this:

install commandbox-fusionreactor

That's it-- now every server you start with the start command will automatically have the JVM args added to it to load up FusionReactor.

Usage

There's nothing special you have to do in order for FusionReactor to load. A random port will be chosen for FusionReactor to use so you can have more than one server running at a time and each of them will have their own FusionReactor instance running. When you start a server, you should see some output similar to this:

******************************************
* CommandBox FusionReactor Module Loaded *
******************************************

FusionReactor will be available at the URL http://127.0.0.1:2871

To open FusionReactor in your browser, you can run the following command:

fr open

If you right click on the tray icon for this server, you'll see there is a new menu item at the bottom called Open Fusion Reactor that will do the same thing.

Licensing

FusionReactor is a commercial product and requires a license to use. If your company has a license for you to use on your PC, then you can register your CommandBox FusionReactor license with this command:

fr register "myLicenseKey"

If you don't have a license, you can sign up for a trial and purchase a license from the http://www.fusion-reactor.com/ website.

Hide License Key

By default, the license key will always be displayed on the home page after login. You can turn off the display of the key on a per-server basis or at a global level for all servers.

# Server specific
server set fusionreactor.hideLicenseKey=true
# global default
config set server.defaults.fusionreactor.hideLicenseKey=true

Custom Port

By default, the module always picks a random port to start FusionReactor on. You can also set your FusionReactor port on a per-server basis, or at a global level for all servers (if using the fancy host updater module which prevents port conflicts by binding each site to its own IP). The default behavior will still be to pick a random port if you don't specify one.

# Server specific port
server set fusionreactor.port=8088
# global default port
config set server.defaults.fusionreactor.port=8088

Custom Host

By default, the module will bind FR's port to the same host as your CommandBox web server. You can ask FR to bind to a separate host/IP on a per server basis, or a global basis.

# Server specific host
server set fusionreactor.host=0.0.0.0
# global default hsot
config set server.defaults.fusionreactor.host=0.0.0.0

Disable the module

You may want to turn the FusionReactor functionality on or off based on your testing or for specific sites. There is now an enable flag for just that. It can be set per server and for all servers as well.

server set fusionreactor.enable=false
config set server.defaults.fusionreactor.enable=false

Per-server License Key

You can set a license key per server if you wish like so:

server set fusionreactor.licenseKey=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Managing Versions

The module is regularly updated to use the latest version of FusionReactor. Note however that your license key may not be for the latest FR version. When the internal default version of FR is updated for a major release, the version of the actual FR module will also have a "major" version increment. This is so you can always run upgrade --system and you won't have to worry about suddenly getting a major FR upgrade one day that doesn't work with your license key.

If you want to upgrade your CommandBox FusionReactor module to a new major release, just re-run the installation command.

install commandbox-fusionreactor

Custom Version of FusionReactor

If you have an older FR license you want to use, you can specify the version of FR you'd like like so:

# Server specific version
server set fusionreactor.installID=fusionreactor@7.x
# global default version
config set server.defaults.fusionreactor.installID=fusionreactor@7.x

The installID setting can be any valid CommandBox endpoint installation ID, which means you can point to a custom HTTP URL, or ForgeBox slug, etc.

Debugger Libs

As of version 4.0 of this module, the debugger libs will be added automatically for you based on your OS. To disable the debugger libs use the following setting:

# Server specific version
server set fusionreactor.debugEnable=false
# global default version
config set server.defaults.fusionreactor.debugEnable=false

Provide External reactor.conf File

There are a handful of JVM args we can use to set things like license key or password, but there are many many settings inside of FusionReactor that have no corresponding method to externalize them. These are stored in a file called conf/reactor.conf inside of the FusionReactor home directory. If you want to script out settings such as

• E-mail servers

• Notification settings

• Profiler settings

• Request history settings

Then you can make a copy of a reactor.conf file that contains the settings you want the point this module at the file to be copied over when starting the server so FR will pick it up and use it. Just need in mind that this setting will override any manual setting changes you make in the FR web admin every time you start the server.

Start up a test server with the FR module installed

install commandbox-fusionreactor
server start

Navigate to the FR admin, login, and set your desired settings

fr open

Copy the populated reactor.conf file somewhere for later use

cp "`server info property=FRHomeDirectory`conf/reactor.conf" ./reactor.conf

Point your server.json to the new file. Remember, non-absolute paths are relative to the directory the server.json lives in.

server set fusionreactor.reactorconfFile=reactor.conf

Now, a fresh new server will have these settings.

server stop 
server forget --force
server start

Note: the reactor.conf file may contain passwords or other sensitive information. It is in a java properties file format, so feel free to edit it and remove items you don't want. Also, take care when committing it to a source repo or making it web accessible so you don't reveal information. There is currently no support for environment variable expansions in this file, but perhaps we'll add it if it's useful.

Additional JVM args

The CommandBox FusionReactor module has passthrough settings for every documented JVM arg. Here are the remaining ones we haven't covered. If you want to know what some of these do, read the official FR docs on them.

Here's the module setting, followed by the JVM arg it creates. Remember, you can use environment variables in your server.json to control these dynamically on a per-server basis!

• fusionreactor.password - fradminpassword

• fusionreactor.cloudGroup - fr.cloud.group

• fusionreactor.requestObfuscateParameters - fr.request.obfuscate.parameters

• fusionreactor.autoApplicationNaming - fr.application.auto_naming

• fusionreactor.defaultApplicationName - fr.application.name

• fusionreactor.EDSEnable - fr.ed.ds.enable (version added: 8.1.0)

• fusionreactor.EDSListen - fr.ed.ds.listen (version added: 8.1.0)

• fusionreactor.EDSPollTimeout - fr.ed.ds.polltimeout (version added: 8.1.0)

• fusionreactor.EDSMaxDataSize - fr.ed.ds.maxdatasize (version added: 8.2.2)

• fusionreactor.EDSTarget - fr.ed.ds.target (version added: 8.1.0)

• fusionreactor.EDSGroups - fr.ed.ds.groups (version added: 8.1.0)

• fusionreactor.ChatEnabled - fr.chat.enabled (version added: 8.7.2)

Deprecated since 8.0.x

• fusionreactor.RESTRegisterURL - frregisterwith

• fusionreactor.RESTShutdownAction - frshutdownaction

• fusionreactor.RESTRegisterHostname - frregisterhostname

• fusionreactor.RESTRegisterGroup - frregistergroup

• fusionreactor.licenseDeactivateOnShutdown - frlicenseservice.deactivateOnShutdown

• fusionreactor.licenseLeaseTimeout - frlicenseservice.leasetime.hint

External Server

By default, FusionReactor is only available on the FR port, and not the HTTP or HTTPS port. If you want to hit FusionReactor's web UI through your main web server on the standard HTTP port, then enable the external server setting. This completely bypasses the custom port and custom host discussed above.

This can provide a convenient method to make FR accessible, but remember to put appropriate lock-down rules on your external web server so FR is not publicly accessible. Also note if you have a web server such as Nginx only proxying traffic to .cfm URLs to CommandBox, you'll need to modify it to also proxy requests to /fusionreactor/ to CommandBox as well or this feature will not work and you'll just get an Nginx/etc 404 instead.

# Server specific version
server set fusionreactor.externalServerEnable=true
# global default version
config set server.defaults.fusionreactor.externalServerEnable=true

Sometimes you may wish to start a server on a computer that doesn't have access to the Internet. However, you may notice that running a command such as the following will throw an error trying to connect to ForgeBox:

start cfengine=lucee@5.x

That is because 5.x is a semver range and not a specific version. CommandBox must connect to ForgeBox to see what versions of the CF engine lucee can be found to use the latest one.

Be More Specific

If you know that a CF engine is already downloaded in your server's artifacts directory, start your server with a specific major, minor, patch, and build version to skip the ForgeBox check.

start cfengine=lucee@5.0.0+252

NOTE: If this fails, check the location of the folder structure below the artifacts folder for it's exact path. e.g. /artifacts/lucee/5.0.0+252/lucee.zip - The box command for this would be: start cfengine=lucee@5.0.0+252 This follows the pattern: /artifacts/[server-type]/[server-version]/[server-type].zip Useful if you've manually downloaded the file from forgebox and need to rename it.

Fail Safe

If CommandBox needs to connect to ForgeBox to resolve a version number and ForgeBox is unavailable, it will look in your local artifacts cache to try and find a cached version of that CF engine that satisfies your semver range. This means you may not get the latest version of that CF Engine, but at least your server will start up.

If a server isn't starting, the first thing to run is the server log command. It will show you the console log for that server. Note, this dumps the entire log file to the console, which may be very large. We recommend using the tail or --follow tricks below.

server log
server log serverName

Tailing and Following logs

If the log is very large, use the tail command to just see the last few lines of it.

server log | tail
server log | tail lines=100

To get a live stream of the console log from a running server, use the --follow flag and the command will continue streaming new lines to the console until you press Ctrl-C to stop.

server log --follow

You can also look at your server's access log (if enabled) and rewrite log (if enabled).

server log --follow -access
server log --follow --rewrite

Start server in console mode

You can use the --console flag to the server start command to start a server in the foreground. The console log will be live-streamed to the CLI and the log will continue streaming as long as the server is running. Press Ctrl-C to stop the server and stop streaming the log file.

server start --console

Debug Logging

You can get additional information about a server start with the --debug flag. When debug is set, the start command will not exit immediately, but wait for the server to come up and live stream the debugging information and server logs to the console while the server is coming up.

server start --debug
server start --debug --console

Maximum logging! (trace)

You may still really be having issues getting your server to start up correctly due to a setting not getting picked up, rewrites not working, or maybe a jar not loading. You can "drink from the firehose" so to speak by turning on trace level logging. This works best when starting the server via the console so you can watch the logging as it streams past.

server start --trace --console

Your CF engine (Lucee, Adobe, etc) or Java app may have application logs of its own and their locations will vary based on what you have running. In any case, they will most likely be located under the server home directory.

CF App server logs

You can find out where your server home is by running:

server info property=serverHomeDirectory

You can also get the full path to your servlet's "out" log with this command:

server info property=consolelogPath

This log file is the equivalent of your catalina.out file on a typical Lucee/Tomcat install or the equivalent of your coldfusion-out.log file on a typical ColdFusion install.

The Servlet's "out" log can be tailed with this command:

server log --follow
server log myServerName --follow

Your console "out" log will auto-rotate every 10MB to keep it from getting too big. Don't use the --debug or --trace flag on a production server or you'll get a lot of logging information! Without those flags, the "out" log doesn't log anything for each request. With debug enabled, you'll get basic information for each request that comes in as well as whether a rewrite rule fired, and with trace, you'll get a ton of information about every request as well as every local path resolution by the path resource manager.

Lucee Server's Log Files

There are many log files for Lucee. For the guide below, I'm assuming you haven't set a custom serverConfigDir or webConfigDir for your servers. If you have, adjust the paths for the server and web context to be whatever it is you've configured. Here are the three locations you'll find log file and is pretty much the same for Lucee 4 and Lucee 5.

1. Lucee's server context log files - The server context is located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF/lucee-server/context/logs/.

2. Lucee's web context log files - The web context is also located under the server home. Open that directory and then navigate to WEB-INF/lucee-web/logs/.

So, to give real examples-- a Lucee server I just looked at on my machine has the three folders of log files I just covered above in these locations:

C:/users/brad/.CommandBox/server/{hash}-cfconfig/lucee-4.5.5.006/logs/server.out.txt

C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/application.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/datasource.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/deploy.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/gateway.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/mapping.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/memory.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/orm.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/remoteclient.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/rest.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/scope.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/search.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/thread.log

C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/application.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/datasource.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/deploy.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/gateway.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/mapping.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/memory.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/orm.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/remoteclient.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/rest.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/scope.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/search.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/thread.log

Adobe ColdFusion's Log Files

Since Adobe doesn't have the separation of server and web contexts, it only has two log locations which are as follows on all versions.

1. ColdFusion server log files - The remaining log files are located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF\cfusion\logs/.

So, to give real examples-- a ColdFusion server I just looked at on my machine has the two folders of log files I just covered above in these locations:

C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/logs/server.out.txt

C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/application.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/audit.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/eventgateway.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/exception.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/monitor.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/scheduler.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/server.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/websocket.log

Access Log

CommandBox servers use a powerful Java-based web server which we've tested to have throughput just as good as Apache or IIS. You can enable "access" logs which output one line for each HTTP request (even for static assets like JS or image files) in the same "common" format that Apache web server uses.

server set web.accessLogEnable=true

View the location of this log or tail the log contents like so:

server info property=accessLogPath
server log --follow --access
server log myServername --follow --access

Your access log will be auto-rotated every day.

Rewrite Log

CommandBox servers use the java-based Tuckey rewrite engine for easy URL rewriting. There's a lot of good debugging information available to help figure out why your rewrites aren't working. You can enable a separate rewrite log to view this information. Keep in mind this can generate a lot of logging output.

server set web.rewrites.logEnable=true

View the location of this log or tail the log contents like so:

server info property=rewritesLogPath
server log --follow --rewrites
server log myServername --follow --rewrites

Your rewrites log will be auto-rotated every 10MB. The amount of information that appears in the rewrites log will be affected by the --debug and --trace flags when you start the server.

Request Dumping

There is a feature you can use to dump all the header details for an HTTP request and response in the form of an Undertow handler called dump-request(). Just include the following server rule in your server.json

{
  "web" : {
    "rules" : [
      "dump-request()"
    ]
  }
}

To fire only for certain requests, you can pair the handler with any predicate you wish:

{
  "web" : {
    "rules" : [
      "regex('(.*).cfm') -> dump-request()"
    ]
  }
}

Then start your server with the --console flag or tail the console with server log --follow and you'll see info like this for each request:

Request Dump:
----------------------------REQUEST---------------------------
               URI=/bar.cfm
 characterEncoding=null
     contentLength=-1
       contentType=null
            header=Accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
            header=Accept-Language=en-US,en;q=0.9,nb;q=0.8,da;q=0.7
            header=Accept-Encoding=gzip, deflate, br
            header=User-Agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.84 Safari/537.36
            header=Host=127.0.0.1:55599
            locale=[en_US, en, nb, da]
            method=GET
          protocol=HTTP/1.1
            scheme=http
              host=127.0.0.1:55599
        serverPort=55599
          isSecure=false
--------------------------RESPONSE--------------------------
     contentLength=3
       contentType=text/html;charset=UTF-8
            header=Connection=keep-alive
            header=Content-Type=text/html;charset=UTF-8
            header=Content-Length=3
            header=Date=Thu, 31 Mar 2022 22:55:19 GMT
            status=200

==============================================================

It's important to note that each server you start opens a new Java process on your host operating system. This allows each server to have it's own settings and configuration independent of any other server. Start as many as you need and simply stop them when you're done. Just keep in mind each server gets its own heap space so keep an eye on your available RAM.

Server Runs Independant of CLI

The embedded server instances are also a separate process from the actual CommandBox CLI process, which also runs on Java. This means you can open the interactive shell, start a few servers, then quit the shell, yet the servers will still continue to run. You can use the CLI to issue a stop command in the servers web root, or just right click on the tray icon.

There is currently no way to have servers start automatically when your computer boots, though there's nothing preventing you from setting up a local script to run the start commands for you.

WEB-INF

You may be used to having your server's WEB-INF folder living in your web root. The CommandBox embedded server still has a dedicated WEB-INF folder for each server you start, but it lives under the main CommandBox installation directory in your user folder. Changes you make to the WEB-INF such as adding jars or new tas will be persisted until you issue a server forget command.

CommandBox stores information about each of the servers you've ever started inside ~/.CommandBox/servers.json so it can remember settings from one run to the next.

List your server

You can see an overview of your servers and what state they're in with the server list command.

server list

site1 (starting)
  https://127.0.0.1:8081
  C:\site1

site1 (running)
  https://127.0.0.1:8082
  C:\site2

site3 (stopped)
  https://127.0.0.1:8083
  C:\site3

If you have many servers, you can provide parameters to help filter the results from server list

# All servers containing the word "foo"
server list foo

# Running servers
server list --running

To list only the servers that have been started in a given directory, use the --local flag.

server list --local

You can take a quick look at the what's been happening with the server log command or use the server status command to see more detailed information including the arguments used previously to start/stop the server.

Multiple Servers

Servers are uniquely identified by their full path, but they also have a short name which defaults to the immediate folder containing their web root. The stop, start, etc commands can be run in the web root for a server, or in any working directory as long as you reference the server's short name.

start site1
start site2
restart site3
stop site2
stop --all

Another handy shortcut is the server cd command that will change the current working directory of the interactive shell to the web root of a named server.

server cd site1
start
server cd site2
install myPackage
restart

Info Server name is the first parameter to all server commands and tab completion works too, making it as easy as possible for you.

Get Server Information

You can get information about a server using the server info command. Add the --JSON flag to get the data back in a JSON format. The property parameter will allow you to retrieve a single value for scripting mashups.

server info
server info --JSON
server info property=serverHomeDirectory
server info property=consoleLogPath

Forgetting Servers

If you want to wipe all configuration, logs, and WEB-INF files for a server, use the server forget command. This will also remove any administrator settings you may have saved including data sources, mail servers, and server mappings.

server forget

You can forget all your servers at once too if you want to start with a clean slate. This command will stop and forget all servers.

server stop --all --forget

Prune Old Servers

You can easily forget all servers which have not been started for a certain period of time with the server prune command. It accepts the number of days that need to have passed since a server was last started in order to prune it.

server prune days=30

# Skip the confirmation check
server prune --force

You can also get back just a JSON representation of servers matching the filter with the --json flag. The JSON will be in the same format as the server list --json command.

server prune 100 --json

CommandBox allows you full control over the servers you start. This includes the port and host, custom JVM args, URL rewriting, web aliases, custom error pages, and custom welcome files.

Ways to provide configuration

Configuration can be set at several different levels:

1. Passed as parameters to the server start command

2. Stored in a server.json file for that server

3. Global defaults in the server.defaults config setting

4. Internal defaults from the ServerService

Settings will be used in that order. Also, any parameters passed to the start command will automatically be saved to your server.json file unless you pass the --noSaveSettings flag.

File path handling

A lot of settings used to start a server involve file paths. Paths starting with a drive letter like C:/, a UNC network path like \\, or a leading slash like / are considered absolute paths and will not be expanded. Try to avoid absolute paths if you want to make your server config portable.

Paths that start with a file/folder name like foo/bar.jar or ../../lib/my.jar are relative and the root folder that they are relative to depends on where there are specified.

• If the path is passed as a parameter to the start command, the path is relative to the current working directory

• If the path is in the server.json file, it is relative to the folder containing the JSON file. (Remember the server.json doesn't have to be in the web root!)

• If the path is in a global server.defaults config setting, it is relative to the web root of the server.

CommandBox has profiles you can assign to a server when you start it to configure the default settings. This is to provide easy secure-by-default setups for your production servers, and to make it easier to switch between a development mode and production mode.

There are 3 currently supported profiles. Custom profiles will be added as a future feature.

• Production - Locked down for production hosting

• Development - Lax security for local development

• None - For backwards compat and custom setups. Doesn't apply any web server rules

Setting the profile

You can set the profile for your server in your server.json

Which create this property

Or you can specify it when starting the server like so:

Default Profile

If a profile is not set, these rules are used to choose the default value:

• If there is an env var called environment, it is used to set the default profile (same convention as ColdBox MVC)

• If the site is bound on localhost, default the profile to "development". Localhost is defined as any IP address starting with 127.

• If neither of the above are true, the default profile is "production". This makes CommandBox servers secure by default.

Production profile

When profile is set to "production", the following defaults are provided:

• web.directoryBrowsing = false

• web.blockCFAdmin = external

• web.blockSensitivePaths = true

• web.blockFlashRemoting = true

Development profile

When profile is set to "development", the following defaults are provided:

• web.directoryBrowsing= true

• web.blockCFAdmin = false

• web.blockSensitivePaths = true

• web.blockFlashRemoting = true

None profile

When profile is set to "none", the following defaults are provided:

• web.directoryBrowsing= false

• web.blockCFAdmin = false

• web.blockSensitivePaths = false

• web.blockFlashRemoting = false

Customizing your profile

The defaults above only apply if you do not have am explicit server.json or server.defaults config setting. If you have an explicit setting, it will override the profile's default. Therefore, if you set the profile toproduction but set web.blockCFAdmin to false, your CF administrator will be public, but the remaining production defaults will still be applied. This allows even the default profiles to be customizable.

It is common to protect pages on your site through your CF code that runs on every request. This does not protect static files like images, plus it can still expose extra surface area of your site for attack. CommandBox has a security system to block certain paths on your site at the web server level, so these requests never reach CF.

Authentication Mechanisms

There are currently two authentication mechanisms you can enable in CommandBox. Any combination of them can be used to secure the protected portions of your site. When CommandBox determines that the current page requires authentication, it will check each enabled auth mechanism until it finds one that can validate the user.

Basic Authentication

Basic Authentication is built on a simple username/password list and challenges the user to provide credentials in their browser.

Client Cert Authentication

Client Cert auth is common for internal government sites and involves the user installing a private certificate on their PC which the server asks the browser to send while negotiation the SSL connection. Client certs are a PKI cert, and often times are stored on a CAC which is a physical card issued to the user.

More to Come

There are more auth mechanisms we will add in the future including Digest Auth, Header Auth, and SSO. Contact us if you're wanting to sponsor any of these.

Auth Predicate

If you do not provide an auth predicate but you enable at least one auth mechanism, ALL PAGES on the entire site will be secured. This is quite secure, but often times you only want to protect a subfolder such as /CFIDE/administrator or /lucee/admin.

To limit the scope of what pages required authentication, you can specify an auth predicate, which follows the same syntax as .

We don't recommend using path() or path-prefix() as they are not case sensitive, which can lead to them being easily worked around if you are on Windows. Even regex() is case-sensitive by default. Only use a case sensitive predicate matcher if your file system and web server are set to be case sensitive! If your server is case sensitive, then the example above can be simplified to this:

The most common auth predicates match a subfolder, but you are not limited to this. Anything valid in a server rule predicate can be used here, including HTTP method, headers, remote IP, etc.

Client Cert Authentication is common for internal government sites and involves the user installing a private certificate on their PC which the server asks the browser to send while negotiation the SSL connection. Client certs are a PKI cert, and often times are stored on a CAC which is a physical card issued to the user.

It is a requirement that the user hit your site via SSL in order for their browser to send their client cert OR for you to opt into accepting upstream client cert HTTP headers from a proxy or web server that is negotiating your SSL connection. It is recommended you configure your server to either disable HTTP or automatically redirect all HTTP traffic to HTTPS, which can be enabled with the web.SSL.forceSSLRedirect setting.

Accepting Client Certs

Configuring your SSL connection to accept or require client certs is covered in the portion of the docs. It's important to note configuring your server to accept SSL client certs and using these certs to authenticate a user two different things. It's possible to accept (or even require) your client (browser) to send a client cert in your web.ssl.clientCert settings but not use the authentication mechanism to protect parts of your site automatically. Any time a browser has sent a client cert, you will be able to access those details from the CGI and request scopes to do your own custom authentication. It is also possible to use Client Cert authentication but not have.

Client Cert Renegotiation

If you have configured your SSL Client Cert settings to accept, but not require client certs, this will allow a user to visit your site and not be challenged to provide a cert until they hit a page that your authPredicate kicks in and requires authentication. Only then will the user's browser prompt them for a cert.

SSL Renegotiation, when enabled, will disable HTTP/2 AND TLSv1.3. Both of these are not compatible with SSL Renegotiation.

Trust Upstream Client Cert Headers

Even if CommandBox is not using SSL directly, but is sitting behind a proxy or web server that takes care of negotiating the client cert, you can still use client cert auth to protect pages on your site if you configure CommandBox to trust any SSL_CLIENT_CERT HTTP request header.

Only enable this setting if you TRUST your upstream proxy and you know it will overwrite any potentially-malicious SSL_CLIENT_CERT header from the client. SSL Certs received through this header will appear in the CGI and request scope and will be trusted the same as a client cert directly negotiated through CommandBox, but there will be NO trust chain verification. The header will be trusted blindly from your upstream server. This setting is off by default.

Enable Client Cert Authentication

You can enable the client cert auth mechanism like so:

Once enabled, all pages on your site will be secured if you have no authPredicate configured. Otherwise, only pages that match the predicate will be secured.

Validate Incoming Certs

By default, when you enable client cert auth, CommandBox simply checks that some client cert is present. Remember, your SSL settings require you to provide a Trust Store or a list of trusted root CAs and only client certs which are trusted by one of those CAs will be negotiated. This may be enough security for you right there if you are only allowing certs signed/trusted by a specific root cert. The client cert trust store requires you to explicitly provide every single CA you want trusted. It does NOT use your Operating system's trust store, nor does it use Java's trust store, nor does it use Lucee Servers.

If a request is authorized via a client cert, the Subject distinguished name of the client cert will be present in cgi.remote_user just like basic auth works.

Filter Subject Distinguished Name (SDN)

You can filter down a subset of client certs you want to be accepted for client cert auth by specifying a full or partial subject DN. This will not limit the certs which are negotiated and appear in the CGI scope. It will only limit the certs which are allowed to provide authentication for pages secured by the authPredicate. A Subject Distinguished Name (SDN) contains one or more parts known as Relative Distinguished Names, or RDNs. They follow an LDAP name RFC and look like this:

You may provide a single Subject DN ...

or an array of Subject DNs to filter on...

The RDNs can be in any order and you can supply a PARTIAL Subject DN. CommandBox will match all RDNs regardless of order or case sensitivity. You are not required to provide the full Subject DN, but all RDNs you provide MUST be present in the incoming cert or it will be rejected.

Filter Issuer Distinguished Name (IDN)

You can also filter down a subset of client certs you want to be accepted for client cert auth by specifying a full or partial Issuer DN. This will not limit the certs which are negotiated and appear in the CGI scope. It will only limit the certs which are allowed to provide authentication for pages secured by the authPredicate. An Issuer Distinguished Name (IDN) look and work the same as Subject DNs.

You may provide a single Issuer DN ...

or an array of Issuer DNs to filter on...

The RDNs can be in any order and you can supply a PARTIAL Issuer DN. CommandBox will match all RDNs regardless of order or case sensitivity. You are not required to provide the full Issuer DN, but all RDSs you provide MUST be present in the incoming cert or it will be rejected.

If you require more specific parsing of the cert pieces, then you’ll need to disable the built in security in CommandBox and write your own code that runs on every request and parses the CGI variables manually to decide if you accept the cert.

server.json Configuration

CommandBox's web server supports enabling Basic Auth on your sites.

That will create the following data in your server.json, which will be picked up the next time you start your server.

If there is no authPredicate set, basic auth with secure ALL PAGES on the site. Once you set an authPredicate, only the pages matching the predicate will require authentication.

The old setting location for Basic Auth (web.basicAuth) will STILL WORK until the next major version of CommandBox, but should be considered deprecated. If both the settings exist (Ex: web.basicAuth.enable and web.security.basicAuth.enable), the new location will be given precedence.

Server scripts work just like , but they only apply to server-related interceptor points, and they go in your server.json. If you have several servers in a folder with their own server-name.json files, the server scripts can be different per server.

The interception points which will fire a server script are:

• preServerStart

• onServerStart

• onServerInstall

• onServerInitialInstall

• onServerStop

• preServerForget

• postServerForget

Read more about when these interception points fire .

Configure server scripts like so in your server.json:

Ad-hoc server scripts

Just like package scripts, you can also create ad-hoc scripts for a given server. They are executed with the server run-script command. Define them as additional keys in the scripts block.

And run them like so:

Running multiple commands

You can run several commands into a single one using &&. You can also do this by specifying an array of strings instead of a string like so:

This can be much more readable for multiple commands. Note, this is functionality equivalent to using &&, which means any erroring command will stop execution.

CommandBox servers have a method of locking down secure URLs and or implementing any of the Undertow predicate and handlers via a nice text based language. Undertow supports a “predicate language” that allows a string to be parsed into a graph of predicates (conditions) and handlers (actions to take). Ex:

path-suffix-nocase(/box.json) -> set-error(404)

These rules can be used for any of the following:

• Security - Block paths, IPs, or users

• URL rewrites - Rewrite incoming URLs to something different

• Modifying HTTP requests on the fly - Set headers, cookies, or response codes

Much of this functionality overlaps with the existing Tuckey-based rewrites in CommandBox, but this functionality is built directly into Undertow, has a more streamlined syntax, and allows for easier ad-hoc rules to be layered into a server that allows for you to have custom rules layered on top of built in rules. It can be used to replace what Tuckey does, or added on top.

Create your Rules

Unlike custom Tuckey-based rewrites that must be placed in a single XML file, server rules can be provided ad-hoc in a variety of locations. They are combined and passed to the server in the order defined. This allows you to easily "layer" custom rules along with out-of-the-box lockdown profiles.

For maximum configuration options, the following mechanisms are supported for specifying the rules for a given server. Rules are processed in the order listed. i.e., a rule defined in your server.json is processed prior to a rule in your server.default config setting.

1. Ad-hoc rule array in sites object or .site.json for Multi-site server

2. Ad-hoc rule array in server.json

3. External rules files in the sites object of the server.json or .site.json for Multi-site server

4. External rules files in server.json in the order defined

5. Ad-hoc rule array in config setting server.defaults

6. External rules files in config setting server.defaults in the order defined

7. CommandBox built-in rules (web.blockCFAdmin, web.blockSensitivePaths)

8. Any module listening to server interceptions can inject their rules wherever they please in the array.

server.json Rules

You can specify ad-hoc rules in the web.rules property as an array of strings in your server.json as well as specify one or more external rule files in the web.rulesFile property as an array or list of file glob patterns.

{
    "web" : {
        "rules" : [
            "path-suffix-nocase(/box.json) -> set-error(404)",
            "path-suffix-nocase(hidden.js) -> set-error(404)",
            "path-prefix-nocase(/admin/) -> ip-access-control(192.168.0.* allow)",
            "path(/sitemap.xml) -> rewrite(/sitemap.cfm)",
        "disallowed-methods(trace)"
        ],
          "rulesFile" : "../secure-rules.json"
        // Or...
          "rulesFile" : ["../security.json","../rewrites.txt","../app-headers.json"]
        // Or...
          "rulesFile" : "../rules/*.json"
    }
}

External rule files with a .json suffix will be expected to be a valid JSON file containing an array of strings. Ex:

[
  "path-suffix-nocase(/box.json) -> set-error(404)",
  "path-suffix-nocase(hidden.js) -> set-error(404)"
]

External rule files with any extension OTHER than .json will be expected to be a raw text file with one rule per line. Emtpy lines are ignored and the rules are processed in the order defined.

path-suffix-nocase(/box.json) -> set-error(404)
path-suffix-nocase(hidden.js) -> set-error(404)

Rules specified directly in the server.json or in an external JSON file must be escaped for the JSON they are a part of. Using a plain text external file can help readability since no additional escaping is required for the rules.

config setting server.defaults Rules

Like all other config server defaults, they follow the same pattern as the server.json file.

config set server.defaults.web.ruleFile=/path/to/rules.json

Commenting Out Rules

You can comment out any rule (whether it's in JSON or a text file) by proceeding it with a pound sign (#).

# Here is a comment that will be ignored

# The following rule also won't be run
# path-suffix-nocase(hidden.js) -> set-error(404)

The Undertow-based web server built into CommandBox will only serve up static files if they are in a list of valid extensions. This is to prevent prying eyes from hitting files they shouldn't be able to access on your server.

The current list of valid extensions is:

3gp,3gpp,7z,ai,aif,aiff,asf,asx,atom,au,avi,bin,bmp,btm,cco,crt,css,csv,deb,der,dmg,
doc,docx,eot,eps,flv,font,gif,hqx,htc,htm,html,ico,img,ini,iso,jad,jng,jnlp,jpeg,jpg,
js,json,kar,kml,kmz,m3u8,m4a,m4v,map,mid,midi,mml,mng,mov,mp3,mp4,mpeg,mpeg4,mpg,msi,
msm,msp,ogg,otf,pdb,pdf,pem,pl,pm,png,ppt,pptx,prc,ps,psd,ra,rar,rpm,rss,rtf,run,sea,
shtml,sit,svg,svgz,swf,tar,tcl,tif,tiff,tk,ts,ttf,txt,wav,wbmp,webm,webp,wmf,wml,wmlc,
wmv,woff,woff2,xhtml,xls,xlsx,xml,xpi,xspf,zip,aifc,aac,apk,bak,bk,bz2,cdr,cmx,dat,
dtd,eml,fla,gz,gzip,ipa,ia,indd,hey,lz,maf,markdown,md,mkv,mp1,mp2,mpe,odt,ott,odg,
odf,ots,pps,pot,pmd,pub,raw,sdd,tsv,xcf,yml,yaml 

If you have a common static file you need to serve, you can add your own custom extensions to the list like so:

server set web.allowedExt=jar,exe,dll

If you've used mod_rewrite with Apache web server, you may be familiar with its Rewrite Map functionality, which allows you to create dynamic rewrites based on a text file of mappings. We have a similar feature built on Undertow's Server Rules that mimics Apache's feature.

Declare a Rewrite Map

There is a rewrite-map() handler which declares a named map file. It accepts an absolute path to the rewrite file, and case sensitivity flag.

{
  "web" : {
    "rules":[
      "rewrite-map( name=myMap, file='/path/to/myMap.txt' case-sensitive=false )"
    ]
  }
}

The file format matches that of Apache's rewrite map functionality.

• Lines starting with # are a comment

• empty lines are ignored

• First space-delimited token becomes the key

• All remaining tokens become the value

• Lines with a single token default the value to an empty string

Here is an example file:

#comment

brad wood
luis majano
jorge reyes bendeck
RACHEL                           WOOD
sdf sdf

Watch disk for changes

If the date modified on the rewrite map file changes on disk, the data will be automatically re-loaded into memory.

Using the Rewrite Map

There are two handler/predicates you can use to interact with the rewrite map. Make sure these are in your list of Server Rules AFTER the map definition.

Check if a key exists

There is a rewrite-map-exists() predicate which will tell you if a given key exists in the map (Apache doesn't have this)

rewrite-map-exists( map='myMap', key='%{RELATIVE_PATH}' )

You can pair this predicate to only use the rewrite map if there is a match.

Get the value for a key from the map

There is a new %{map:name-name:mapKey|defaultValue} exchange attribute which mostly follows Apache's syntax. The only limitation is nested exchange attributes must use [] instead of {} due to an Undertow parsing issue).

{
  "web" : {
    "rules":[
      "rewrite-map( name=myMap, file='/path/to/myMap.txt' case-sensitive=false )",
      "regex-nocase( '^/foo/(.*)$' ) -> rewrite( 'index.cfm?page=%{map:myMap:$[1]|99}' )"
    ]
  }
}

In the example above, we're using a regex predicate to extract the text after /foo/ in the URL and then we reference that capture group as $[1] which we pass in as the key to the map. If there is no key in the map for that value, we default to 99.

So, given our example rule map file above, the url

http://site1.com/foo/luis

would be rewritten to

http://site1.com/index.cfm?page=majano

CommandBox's server rules are based directly on the "Predicate Language" feature of JBoss Undertow. All of the official documentation for Undertow's predicate language applies to CommandBox. CommandBox doesn't limit the power of what Undertow provides at all. In fact, we give you some additional out-of-the box predicates and handlers you can use.

There are three concepts you need to understand and you'll be writing your own rules in no time.

• Handler - A wrapper around the request that takes some sort of action such as returning a status code or rewriting the request.

• Predicate - A conditional that evaluates to true or false. Used to Conditionally apply a handler

• Exchange Attribute - An abstracted way to refer to any piece of information about the request or response. Can include URL, query string, cookies, headers, or CGI variables.

Since the parsing of your rules is handled by Undertow, it is case sensitive in many areas and CommandBox cannot control this. The following must always be lower case:

• Predicate names

• Handler names

• Parameter names

• Keywords like and, or, else

The full undertow docs can be found here: https://undertow.io/undertow-docs/undertow-docs-2.0.0/

Handler

A handler will take action on the request. This can redirect the request, rewrite it, abort it, or modify attributes of the request such as setting an HTTP header or status code. If the predicate is omitted, the handler will always fire for all requests. Ex:

disallowed-methods(trace)

Common handlers:

• set() - Sets an exchange attribute (see below)

• rewrite() - Rewrite the request URL

• redirect() - Redirect to another URL

• header() - Sets an HTTP response header

• set-error() - Set HTTP response code and returns the corresponding error page

• ip-access-control() - Configure IP-based allow/deny rules (wildcards and IP ranges allowed)

• done - Skips remaining rules

• request-limit() - Limits concurrent requests

• restart - Restarts process back at start of predicate rule chain (combine with rewrite, etc)

• proxy() - Creates a proxy to a single host

• load-balanced-proxy() - Creates a round robin reverse proxy to a list of hosts

• allowed-methods() / disallowed-methods() - Enforces whitelist/blacklist of HTTP methods on current request

• Full list here: https://undertow.io/undertow-docs/undertow-docs-2.0.0/#built-in-handlers-2

A handler is called using the “name” from the docs and passing any required parameters. Params can be named or positional (if there is only one). Quoting values is only required if they have a space, comma or brace. The following are all equivalent:

set-error(404)
set-error("404")
set-error(response-code=404)
set-error(response-code="404")

Handler parameters that accept an array use the Java array literal syntax which is a comma-delimited list of values in curly braces.

load-balanced-proxy( { 'http://host.com', 'http://host2.com' } )

More than one handler can be run by wrapping them in curly braces and using semicolons between them

path(/restart) -> { rewrite(/foo/a/b); restart; }