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)

• reverse-proxy() - Creates a round robin reverse proxy to a list of URLs

• 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.

reverse-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; }

A chain of handlers can be configured for the true AND false evaluation of a single predicate using the “else” keyword.

regex('(.*).css') -> set(attribute='%{o,css}', value='true') else set(attribute='%{o,css}', value='false');

Predicates

A predicate is a condition that must be matched for the handler to kick in.

Common predicates:

• path() - match the incoming request path

• path-suffix() - match full file/folder names at the end of the path like file.cfm

• path-prefix() - match full file/folder names at the start of the path like /lucee/admin

• method() - Match the HTTP method

• regex() - Match a regular expression against any exchange attribute

• equals() / contains() - Do a text compare on any exchange attribute

• path-template() - match a path with placeholders like /foo/{bar} and the placeholders become variables for use in later predicates or handlers in the chain.

• Full list here: https://undertow.io/undertow-docs/undertow-docs-2.0.0/#textual-representation-of-predicates

A predicate is called by placing parentheses after the name and passing in the required arguments as specified in the docs for that predicate. Quoting values is only required if they have a space, comma or brace. The following are all equivalent:

method(GET)
method("GET")
method(value=GET)
method(value="GET")

Complex conditions can be constructed with more than one predicate using the keywords “and” or “or”.

path-prefix(/tests/) OR path-prefix(/workbench)

A predicate can be negated with the keyword “not”

not method(POST)

Exchange Attributes

Exchange attributes are an abstraction Undertow provides to reference any part of the HTTP request or response. There is a textual placeholder that can be used in predicates and handlers that will be expanded in-place.

Common Exchange Attributes:

• %{REMOTE_IP} - Remote IP address

• %{PROTOCOL} - Request protocol

• %{METHOD} - Request method

• %{REMOTE_USER} - Remote user that was authenticated

• %{RESPONSE_TIME} - Time taken to process the request, in ms

• %{c,cookie_name} - Any cookie value

• %{q,query_param_name} - Any query parameter

• %{i,request_header_name} - Any request header

• %{o,response_header_name} - Any response header

• ${anything-here} - Any value from the predicate context (such as regex capture groups or path-template placeholders)

• Full list here: https://undertow.io/undertow-docs/undertow-docs-2.0.0/#exchange-attributes-2

Use an exchange attribute like you would a variable as the parameter to a handler or predicate.

set(attribute='%{o,someHeader}', value=myValue)
not equals('%{REMOTE_IP}', 127.0.0.1) -> set-error(403)

These are all equivalent:

regex(pattern="/(MSIE 6\.0)", value="%{i,user-agent}" ) -> response-code( 404 )
regex(pattern="/(MSIE 6\.0)", value="%{i,USER-AGENT}" ) -> response-code( 404 )
regex(pattern="/(MSIE 6\.0)", value="%{i,UsEr-AgEnT}" ) -> response-code( 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

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.

The following JVM Args are supported when starting the embedded server.

heapSize

You can set the max heap size the server is allowed to have (-Xmx) by passing the heapSize parameter to the start command. This parameter defaults to megabytes but you can specify any valid suffix.

start heapSize=1024

In server.json

server set JVM.heapSize=1024
server set JVM.heapSize=2G
server show JVM.heapSize

minHeapSize

You can set the starting heap size for the server (-Xms) by passing the minHeapSize parameter to the start command. This parameter defaults to megabytes but you can specify any valid suffix.

start minHeapSize=1024

In server.json

server set JVM.minHeapSize=1024
server set JVM.minHeapSize=2G
server show JVM.minHeapSize

Ad Hoc JVM Args

You can specify ad-hoc JVM args for the server with the JVMArgs parameter.

start JVMArgs="-XX:MaxGCPauseMillis\=200"

In server.json

server set JVM.args="-XX:MaxGCPauseMillis\=200"
server show JVM.args

Ad Hoc Runwar Options

You can specify ad-hoc options for the underlying Runwar library using the RunwarArgs parameter.

start RunwarArgs="--sendfile-enable false"

In server.json

server set runwar.args="--sendfile-enable false"
server show runwar.args

CommandBox allows you to create web aliases for the web server that are similar to virtual directories. The alias path is relative to the web root, but can point to any folder on the hard drive. Aliases can be used for static or CFM files.

To configure aliases for your server, create an object under web called aliases. The keys are the web-accessible virtual paths and the corresponding values are the relative or absolute path to the folder the alias points to.

Here's what your server.json might look like.

Here's how to create aliases from the server set command:

info On Adobe ColdFusion servers, .cfm files will be run automatically from inside an aliases directory. On Railo and Lucee servers, you'll need to create a CF mapping that maps the alias name and path for .cfm files to work.

Once you start using the embedded server for your development projects, you may wish to enable URL rewriting. Rewrites are used by most popular frameworks to do things like add the index.cfm back into SES URLs.

You may be used to configuring URL rewrites in Apache or IIS, but rewrites are also possible in CommandBox's embedded server via a .

Default Rules

We've already added the required jars and created a default rewrite that will work out-of-the-box with the ColdBox MVC Platform. To enable rewrites, start your server with the --rewritesEnable flag.

Now URLs like

can now simply be

In server.json

info The default rewrite file can be found in ~\.CommandBox\cfml\system\config\urlrewrite.xml

Custom Rules

If you want to customize your rewrite rules, just create your own XML file and specify it when starting the server with the rewritesConfig parameter. Here we have a simple rewrite rule that redirects /foo to /index.cfm

customRewrites.xml

Then, fire up your server with its custom rewrite rules:

In server.json

You can place your custom rewrite rule wherever you like, and refer to it by using either a relative path or an absolute path. CommandBox will start looking relative to where the server.json file resides.

or

Apache mod_rewrite-style rules

If you're coming from Apache, Tuckey supports a large subset of the mod_rewrite style rules like what you would put in .htaccess. You can simply put your rules in a file named .htaccess and point the web.rewrites.config property to that file.

Note: The name of the file matters with mod_rewrite-style rules. It must be called .htaccess. With xml rewrites, the filename is not important, only the content.

Here are some simple rewrite rules:

Please see the docs here on what's supported:

SES URLs

Your servers come ready to accept SES-style URLs where any text after the file name will show up in the cgi.path_info. If rewrites are enabled, the index.cfm can be omitted.

SES URLs will also work in a sub directory, which used to only work on a "standard" Adobe CF Tomcat install. Please note, in order to hide the index.cfm in a subfolder, you'll need a custom rewrite rule.

Logging

The Tuckey Rewrite engine has debug and trace level logging that can help you troubleshoot why your rewrite rules aren't (or are) firing. To view these logs, simply start your server with the --debug or --trace flags. Trace shows more details than debug. These options work best when starting in --console mode so you can watch the server logs as you hit the site. Alternatively, you can follow the server's logs with the server log --follow command.

Additional Tuckey Settings

The Tuckey Rewrite library that CommandBox uses under the hood. It has some extra settings that CommandBox allows you to use.

Watch rewrite file for changes

To monitor your custom rewrite file for changes without needing to restart the server, use this setting.

Internal Tuckey status page

To enable the inbuilt Tuckey status page, use the following setting. Note, debug mode needs to be turned on for the Tuckey status page to work. Also, you'll need to customize your rewrite file if you use a path other than /tuckey-status.

The start command will scan your system and find a random port that is not currently in use to start the server on. This ensures that multiple embedded servers can run at the same time on the same host without collisions. Ensure any redirects in your applications take the port into account.

Any Port in the Storm

You may want to set a specific port to use-- even port 80 if nothing else is using it. Pass the HTTP port parameter to the start command like so:

It is also possible to save the default port in your server.json. Add a web.http.port property, or issue the following command:

Now every time you start your server, the same port will be used.

If the server won't start or is unreachable, make sure it's port is free with your operating system's netstat command. On Unix-based OS's:

HTTPS

You can start your server to listen for SSL connections too.

This will enable SSL without an approved SSL certificate. If you need an official certificate so you don't have to confirm your SSL connection you can add these entries

Although free certificates are available (e.g LetsEncrypt) this is not very convenient, because these certs are valid only for three months. Automatic renewal it is difficult if your dev site is not accessible from the web. For a few dollars a year (< 10) you can apply for a domain validated certificate from companies like Comodo, RapidSSL, Trustwave, Digicert, Geotrust and others or a reseller for these certs. For a domain validated certificate you need a valid domain which is under your control which means (depending on provider):

• mail is sent to domain owner

• or mail is sent to well-known administrative contact in the domain, e.g. (admin@, postmaster@, etc.)

• or you can publish a DNS TXT record

So, now you have a valid domain, you have to generate a SSL key and a SSL Certificate Signing Request. With the CSR you can apply for the certificate. Generating a key and CSR with openSSL

This will generate output and some questions, and will finally result in a key file named dev_mydomain_com.key and a certificate signing request (csr) named dev_mydomain_com.csr

You have to enter Country Name, State and City. Organization Name is preferably the same as the domain owner. Organizational Unit Name will not be checked, so enter something simple such as ICT Common Name is the hostname for your site, such as dev.mydomain.com You can skip Email Adress and optional company name. For development you don't need a challenge password, which means your key file is NOT protected. But don't give this key to others or protect it with a challenge password. If you protect your key you have to server set web.SSL.keyPass=MyChallengePassword Now you have a CSR, which you can submit at your SSL provider. They will send you a certificate file (*.csr), and probably one or more intermediate certificates. Create a new my.csr file and copy everything from your certificate file into it, and append the intermediate certificate(s). Now you have a valid my.csr certificate file and a key file. Place both files in a location accessible for your commandbox and enter the corresponding paths to web.SSL.certFile and web.SSL.keyFile

AJP

You can start your server to listen for AJP connections too.

A Gracious Host

Your application may rely on a specific host name other than the default of 127.0.0.1. You can set the host to anything you like, but you must add a host file entry that resolves your host name to an IP address assigned to your network adapter (usually 127.0.0.1)

If you have multiple IP addresses assigned to your PC, you can bind the server to a specific IP using the host parameter.

A server configuration can only have one host entry. If you require your server to be available on multiple IP addresses of the machine it runs on, you can set the host to 0.0.0.0. This will effectively bind the server to all network interfaces (including local).

Or save in server.json

Customize URL that opens for server

By default, CommandBox will open your browser with the host and port of the server. You can customize the exact URL that opens. This setting will be appended to the current host and port.

Or you can completely override the URL if your setting starts with http://.

By Default, your servers start using the same version of Java that the CommandBox CLI is using. For people needing to run Adobe ColdFusion 9, or who just want to do some testing on different JREs, you can point each of your servers at a custom JRE and CommandBox will use it when starting the server.

if you already have a JRE downloaded somewhere on your hard drive, you can manually point the server at it, or you can simply tell CommandBox which version of java you'd like, at it will automatically download that version of OpenJDK for your server to use (if it's not already downloaded)

Manual Java Config

Point CommandBox to an existing java install like so:

To set the default version of Java for all the servers you start on your machine, use the global config setting defaults.

Automatic Java Download

To let CommandBox take over and acquire Java for you, pass an installation endpoint ID to the start command

or set it in your server.json

or set a default for all servers

To review what possible IDs you can use to dial in your exact Java version, read the . You don't need to manually install Java-- CommandBox will do that for you. You just need to provide the ID so CommandBox knows what you want.

Java Namespace

To make it easier for you to manage the Java installations CommandBox makes for you, we have a namespace of commands you can use. The Java versions CommandBox installs automatically for your servers to use are stored in a folder under your CommandBox home. CommandBox manages this folder for you. You can change where the system Java installation go like so:

java search

Search the AdoptOpenJDk API for available versions of Java for you to use.

You can filter the version, jvm, os, CPU arch, type, and release. Most of those parameters default to match your local system. For instance, running this command on Windows will only return Windows versions. To open up the search, pass nothing to that filter.

java list

List the installed Java installations for you to start servers with. If you have set a global default Java version it will be marked in the list.

java setDefault

You may change the global default Java version for your servers with this command.

java install

You can pre-install a Java version so it's ready to go the next time you start a server with this command. This differs from the normal package install command in that it doesn't install to the current working directory, but into the core server JRE folder that CommandBox manages for you. Use the --setDefault flag to also set the newly installed Java version as the global default for all servers.

java uninstall

You can remove a java installation so it doesn't take up space on your hard drive. Use the FULL ID that shows in the java list command to uninstall.

Note, the download will still be in your artifacts cache. Also, if you start a server up again that asks for a Java installation you've uninstalled, CommandBox will simply re-install it again.

The built in REST implementation in Adobe ColdFusion and Lucee is usually something you either love or hate. If you love it, you can enable it and customize the paths so it doesn't collide with your app's routes. if you hate it, you can turn it off. The REST servlet will be disabled unless you include a setting like so:

server set app.restMappings=/rest/*,/api/*

Note that the above setting will take over any URLs starting with /rest or api and you cannot use those routes or folders in your code. This is why it's handy to be able to modify or remove these. On a typical server, this is done via the web.xml, but CommandBox will do it all for you with just the setting above.

And to test/debug your rules, start your server with the trace flag and tail the console output. Every hit in your browser will output several lines of debugging for each rule that is processed.

server start --trace --console 

With the custom rule above, you'd see something like this:

[DEBUG] requested: '/CFIDE/main/ide.cfm'
[TRACE] io.undertow.predicate: Path(s) [/CFIDE/main/ide.cfm] MATCH input [/CFIDE/main/ide.cfm] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}.
[TRACE] io.undertow.predicate: Predicate [path( '/CFIDE/main/ide.cfm' )] resolved to true. Next handler is [done] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}.
[TRACE] io.undertow.predicate: Predicate chain marked done. Next handler is [Runwar PathHandler] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}.
[WARN ] responded: Status Code 200 (/CFIDE/main/ide.cfm)

There are endless combinations of predicates and handlers you can apply to your apps. Here's an assortment of examples to get you going. Many of these are contrived, but are just mean to show the range of syntax and functionality.

Rewrite a URL:

path('/healthcheck') -> rewrite('/healthcheck.cfm')

Stop processing rules for a given request:

path(/healthcheck) -> done
path(/healthcheck) -> response-code(503)  // This rule is skipped

For all GET requests, set a response header called type with a value of get

method(GET) -> set(attribute='%{o,type}', value=get)

If the incoming path ends with .css it will rewrite the request to .xcss and set a response header called rewritten to true.

regex('(.*).css') -> { rewrite('${1}.xcss'); set(attribute='%{o,rewritten}', value=true) } 

Redirect all jpg requests to the same file name but with the png extension. The ${1} exchange attribute is used to reference the first regex group.

regex('(.*).jpg$') -> redirect('${1}.png')

Set a request header that you can access in your CFML app just like a normal HTTP header.

set(attribute='%{i,someHeader}', value=someValue)

Match certain SES-style URLs and store the place holders (referenced as exchange attributes) into HTTP request headers.

path-template('/product/{productid}') -> set(attribute='%{i,productid}', value='${productid}')

In this example, hitting the server with /restart skips the first rule, the second rule rewrites the request and then restarts back at the first rule which fires the second time through.

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

Block access to a URL unless coming from a specific IP.

path-prefix(/admin/) and not equals('%{REMOTE_IP}', 127.0.0.1) -> set-error( 404 )

For more control over IP address matches, use the ip-access-control() handler.

path-prefix(value="/admin/") -> ip-access-control[default-allow=false, acl={'127.0.0.* allow'}, failure-status=404]

Leading slash is NOT required. Both of these rules are the same:

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

It is not required to include .* at the end of a regex path unless you’ve set full-match=true

regex( "^/tests/" ) -> set-error( 404 ) 
regex( pattern='^/tests/.*", full-match=true ) -> set-error( 404 )

Perform a regex a case insensitive search like so:

regex(pattern="Googlebot", value="%{i,USER-AGENT}", case-sensitive=false ) -> set-error( 404 )

When attribute values are not quoted, all leading and trailing whitespace will be trimmed. The following are all the same:

path( "/foobar" )
path(/foobar)
path( /foobar )

But this example is different. The leading and trailing spaces will be preserved in the path string.

path( " /foobar " )

Basic MVC rewrite:

not regex( pattern='.*\.(bmp|gif|jpe?g|png|css|js|txt|xls|ico|swf|cfm|cfc|html|htm)$', case-sensitive=false ) -> rewrite('/index.cfm/%{RELATIVE_PATH}')

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(/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, sever rule 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 server.json

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

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

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

5. CommandBox built-in rules (web.blockCFAdmin, web.blockConfigPaths)

6. 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(/box.json) -> set-error(404)",
            "path-suffix(hidden.js) -> set-error(404)",
            "path-prefix(/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(/box.json) -> set-error(404)",
  "path-suffix(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(/box.json) -> set-error(404)
path-suffix(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

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

server set profile=production

Which create this property

{
  "profile": "production"
}

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

server start profile=production

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.directoryListing = false

• web.blockCFAdmin = external

• web.blockSensitivePaths = true

• web.blockFlashRemoting = true

Development profile

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

• web.directoryListing = true

• web.blockCFAdmin = false

• web.blockSensitivePaths = true

• web.blockFlashRemoting = true

None profile

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

• web.directoryListing = true

• 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.

{
  "profile": "production"
  "web": {
    "blockCFAdmin": false
  }
}

CommandBox bundles some custom predicates and handlers to make your life easier.

The predicate cf-admin() will returns true if the incoming URL is to the Lucee or ColdFusion admin:

cf-admin() -> set-error( 404 ); 

// Is the equivalent of 
regex(pattern='^/(CFIDE/administrator|CFIDE/adminapi|CFIDE/AIR|CFIDE/appdeployment|CFIDE/cfclient|CFIDE/classes|CFIDE/componentutils|CFIDE/debug|CFIDE/images|CFIDE/orm|CFIDE/portlets|CFIDE/scheduler|CFIDE/ServerManager|CFIDE/services|CFIDE/websocket|CFIDE/wizards|lucee/admin)/.*', case-sensitive=false) -> set-error(404) 

The handler block-external() blocks any request not from localhost with a 404 response code. You can pair this with any predicate you choose.

cf-admin() -> block-external() 

// Is the equivalent of 
cf-admin() -> ip-access-control( default-allow=false, failure-status=404, acl={ 127.*.*.* allow } ) 

The handler block-cf-admin() blocks any request to the Lucee or ColdFusion admin with a 404 response code.

block-cf-admin() 

// Is the equivalent of 
cf-admin() -> set-error( 404 ); 

Build Your Own

You can build your own predicates and handlers by compiling java classes that implement the io.undertow.predicate.PredicateBuilder or io.undertow.server.handlers.builder.HandlerBuilder interfaces. If the proper service metadata is present in your jar's META-INF folder, undertow will automatically find and register your builders via Java's service loader.

This isn't super difficult but involves a few moving parts. If you're interested in writing your own handlers and predicates to use in your server rules, reach out on the mailing list and we'll walk you through it.

You can see the custom handlers and predicates documented above in our Runwar source code here:

Custom handlers:

Custom Predicates:

If you have custom jar files that you want to be available to a server, we recommend you use the this.javaSettings functionality in your Application.cfc to load those jars. If that isn't an option for you, or you want to include libs for a JDBC drivers then we offer a feature for you to specify a list of directories for which CommandBox will load jars from. This prevents you from worrying about getting your jars inside the WEB-INF/lib which starts fresh anytime you forget a server.

To load in your jar files, the first method is to use the libDirs parameter to the server start command.

And the way to specify this in a portable manner in your `server.json` is like so:

Remember, paths to the start command are relative to your current working directory and paths in your server.json file are relative to the folder that the server.json file lives in. Absolute paths work the same everywhere.

Global Custom Libs

Have a bunch of servers and they ALL need the same jars, you can add your `libDirs` to the global server defaults config settings. Your global lib directories won't be overwritten by server-level config dirs, but instead appended to. Relative paths in your config settings are relative to the respective web root of the server. CommandBox will also ignore missing lib dirs to give you some flexibility in this.

You can customize the error page that CommandBox servers return. You can have a setting for each status code including a default error page to be used if no other setting applies.

Create an errorPages object inside the web object in your server.json where each key is the status code integer or the word default and the value is a relative (to the web root) path to be loaded for that status code.

This is what you server.json might look like:

You can set error pages via the server set command like this:

Accessing error variables

If your error page points to a CFM file, you can get access to the original path being accessed for 404s and the error that was thrown for 500s. To see all the request headers that are available, use the following snippet of code:

An example of getting the original missing path in a 404 would look like this:

The default welcome files are the usual index.cfm, index.htm, index.html, etc but you can override this with the welcomeFiles setting in your server.json by providing a comma-delimited list of files that you would like CommandBox to look for when a user hits a directory on a running server.

This setting is a complete override of the defaults, so you need to specify the full list.

Directory Browsing

By default, a CommandBox server will not show the contents of a directory that doesn't have an index file. You can enable directory browsing for a single server with

And you can enable it for all servers by default with

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.

CommandBox uses JBoss Undertow to power it's lightweight servlet containers. Undertow also powers JBoss Wildfly and has a lot of configurable options, not all of which have first-class CommandBox settings. These low-level settings come in two different categories:

• Undertow Options - Settings that apply to the servlet and web server aspects of Undertow

• XNIO Options - Part of the underlying XNIO library which powers all low-level I/O in undertow

Undertow Options

Undertow has its own set of options which can be found here:

To set an XNIO option that CommandBox doesn't already expose with a first-class setting, you can set them into your server.json like so:

You can also set global XNIO objects that will apply to all servers. Global options will be appended to server-level options.

XNIO Options

XNIO (which is a refined version of NIO (Non-blocking I/O) has its own set of options that apply to the low level network transport functions it provides. You can find the full set of XNIO options here:

To set an XNIO option that CommandBox doesn't already expose with a first-class setting, you can set them into your server.json like so:

You can also set global XNIO objects that will apply to all servers. Global options will be appended to server-level options.

The web server in CommandBox is capable of enabling GZIp compression to reduce the size of HTTP responses. To enable GZip compress on your CommandBox server, add a web.gzipEnable setting in your server.json file.

server set web.gzipEnable=true

By default GZip compression will be applied to any file over 1500 KB in size. This is because 1500 KB or smaller can fit inside a single network packet, so there's no real benifit in zipping small files and it just causes CPU overhead.

If you wish to customize the file size or any other aspect of when GZip compression is applied, you can specify a custom Undertow Predicate that, when true, will trigger GZip for the request.

server set web.gzipPredicate="request-larger-than(500)"

Since ANY valid Undertow predicate language can be used here you can combined predicates to control exactly when GZip compression is applied. This example would apply GZip compression to any CSS files over 500 KB that were not in the /admin folder.

server set web.gzipPredicate="not path-prefix( admin ) and regex( '(.*).css' ) and request-larger-than(500)"

For every server you start, there is a corresponding icon in your PC's system tray. In addition to the menu options you get out of the box, you can add in custom menu items. Menus are defined as nested arrays of structs, where each struct represents a single menu item. A menu item can be informational, have an action, or contain sub menus.

[
    {
        "label" : "My Custom Menu Item!",
        "disabled" : true
    }
]

You can customize the tray menus for a server via 3 different methods:

• The trayOptions array in a specific server's server.json file. These menu additions will be specific to that server.

• The server.defaults.trayOptions config setting. These menu additions will be added to every server you start

• A custom CommandBox Module with an interceptor listening to the onServerStart interception point that modifies the serverInfo.trayOptions array.

Each menu item struct can have the following keys. Only label is required.

• label - This text appears on the menu and is the unique name

• action - This controls what the menu item does when clicked. Possible options are:

  • openfilesystem - Opens a folder on the file system. Requires path to be set as well.

  • openbrowser - Opens a URL in your default browser. Requires url to be set as well.

  • stopserver - Stops the current server

  • run - Runs an arbitrary native command synchronously. Requires command to be set as well.

  • runAsync - Runs an arbitrary native command asynchronously Requires command to be set as well.

  • runTerminal - Runs an arbitrary native command in a new Terminal window. Requires command to be set as well.

• path - The file system path to use for the openfilesystem action.

• url - The HTTP URL to use for the openbrowser action

• image - A custom image file to use for the icon. Relative paths in the server.json will be relative to the JSON file Relative paths in the global config will be relative to the web root of the server.

  • command - The native command to run for the run, runAsync, or runTerminal actions.

• workingDirectory - The working directory to use for the run, runAsync or runTerminal actions.

• shell - Override the native shell to use on your OS. Defaults to your nativeShell config setting.

• items - An array that contains a struct of sub menus.

• disabled - Boolean that greys out menu item and disables any action. Use for informational items.

openfilesystem Example

[
    {
        "label" : "Open Downloads",
        "action" : "openfilesystem",
        "path" : "D:/downloads",
        "image" : "C:/pictures/folder.png"
    }
]

openbrowser Example

[
    {
        "label" : "Open Google",
        "action" : "openbrowser",
        "url" : "https://www.google.com",
        "image" : "C:/pictures/cat.png"
    }
]

stopserver Example

[
    {
        "label" : "Kill it!",
        "action" : "stopserver",
        "image" : "images/bomb.png"
    }
]

run Example

Commands executed by the run action will display their output in a popup window. The PID of the process is available if running on Java 9 or later. Also, there is a button to kill the process, but your mileage may vary. Only use this option to run command line apps that have console output you want to see.

[
    {
        "label" : "Does the Internet work?",
        "action" : "run",
        "command" : "ping google.com"
    }
]

runAsync Example

Commands executed by the runAsync action work like the run action except there is no windows to show you the output. This is what you want to use to fire off an app such as an IDE.

[
    {
        "label" : "Math is math!",
        "action" : "runAsync",
        "command" : "calc.exe"
    }
]

runTerminal Example

Commands executed by the runTerminal action work like the run action except a new terminal window is opened to run the command. The terminal windows stays open and you can continue to interact with it when the command finishes.

[
    {
        "label" : "Update dependencies",
        "action" : "runTerminal",
        "command" : "box update"
    }
]

You can customize how your command is run by setting the optional workingDirectory and shell properties. If not set, the working directory will be the web root of the server.

[
    {
        "label" : "Clear Temp Dir",
        "action" : "runAsync",
        "command" : "rm -rf",
        "workingDirectory" : "/var/tmp",
        "shell" : "/bin/zsh"
    }
]

Sub Menus

You can nest menus by supplying another array of structs in the items property of a menu. A menu cannot have an action and have sub menus.

[
    {
        "label" : "Top menu",
        "items" : [
            {
                "label" : "Sub 1"
            },
            {
                "label" : "Sub 2"
            },
            {
                "label" : "Sub 3"
            }
        ]
    }
]

Override Existing Menus

Menu items are layered "on top" of existing options whichs mean you can add new sub menu items to an existing top level menu. You can even override the action or image of a built-in menu. Menu items are registered in this order:

• Built-in menus

• Config setting server defaults

• server.json trayOptions

• onServerStart interceptor

This example server.json will add a new sub menu into the existing "Open..." top level menu.

{
    "trayOptions":[
        {
            "label":"Open...",
            "items":[
                {
                    "action":"runAsync",
                    "command":"calc.exe",
                    "label":"Calculator"
                }
            ]
        }
    ]
}

There is no way to remove existing menu items via your config settings or server.json. To do that, you'd need to directly manipulate the trayOptions array in an interceptor.

Here are some settings for performance tuning your servers

Max Requests

This setting limits how many requests will be passed through the Undertow listener to your app server. It defaults to 30. Please note that your web server connector and Adobe ColdFusion may also have their own max request setting.

Or as a global setting for all servers:

Baked-in Rules

CommandBox has a few baked in rules that you can apply ad-hoc or as part of a server profile.

• web.blockCFAdmin - Returns 404 error page for any Adobe CF or Lucee Server admin administrator paths

• web.blockSensitivePaths - Returns 404 error page for common config files such as box.json or .env

• web.blockFlashRemoting - Blocks all paths related to Flash and Flex remoting calls

Block CF Admin

This setting has three possible settings:

• true - Block ALL access to ColdFusion and Lucee admins

• false - Do not block anything

• external - Only block access not coming from localhost.

The exact rule activated when you set this property to true is:

The exact rule activated when you set this property to external is:

Block Sensitive Paths

This setting only allows true/false. This is a bit of a catch-all rule for any sort of paths that a user should never be able to make on production that could reveal information or access secret parts of your CF installation. When set to true, the following rules are activated:

When the profile is set to production, the following rule is also added which blocks the ColdFusion RDS access from CF Builder and access to TestBox runners:

If you need to legitimately access any of these paths, you'll need to turn off this setting and custom-add the rules that you want to keep. This setting is a convenience that adds several rules at once.

Block Flash Remoting

This setting only allows true/false. When set to true, the following rules are activated:

If you need to legitimately access any of these paths, you'll need to turn off this setting and custom-add the rules that you want to keep. This setting is a convenience that adds several rules at once.

Override just part of a baked-in rule

What if you want to go one step deeper? For instance, the blockSensitivePaths setting blocks a whole bunch of stuff all in one shot. An example might be wanting to open up JUST the RDS IDE integration for your developers, which funnels through the /CFIDE/main/ide.cfm path which you can see is blocked above.

The solution to this is quite simple and is all based on the ORDER in which your rules are processed. Built-in CommandBox rules are the last to process. This means that if you hijack the predicates with a custom rule FIRST, you can override the behavior of the built in rules. So, if we want to allow access to the /CFIDE/main/ide.cfm path, we just need to add a custom rule that matches that path and then aborts the predicate chain so no further rules fire.

Which gives you the following server.json

The done handler is what bypasses all subsequent rules for the request.