There are a number of pretty exciting new features and a pile of bug fixes. And as usual, input from the community via Pull Requests. Huge thanks to Pete Freitag, Kai Koenig, Matthew Clemente, Bobby Hartsfield, Scott Steinbeck, Daniel Mejia, and Miguel Mathus! Here's an overview of the new stuff in 5.2.0
Library Updates
We know library updates are boring, but they are important and we want you to know we take them seriously. Keeping up-to-date ensure you have the latest fixes and security updates from all the third-party libs we bundle in CommandBox.
Here's an overview of what we updated in CommandBox 5.2.0.
Upgraded Runwar from 4.1.2 to 4.3.8
Upgraded JBoss Undertow from 2.0.27.Final to 2.2.0
Upgraded UrlRewritesFilter to Ortus fork 5.0.1 with custom fixes
The Undertow bump is a minor update, but a pretty big deal. Ortus sent three pull requests to the core Undertow project fixing bugs and adding predicate logging. All of our pulls were accepted and merged into the core Undertow project and released in the 2.2 release.
Read more about library updates here:
Server Security Profiles
This is a feature that we expect to grow in the future. We've started it out simple, yet powerful but left a lot of room to build on it. The two main goals here are
Make CommandBox secure-by-default so a server shoved in production comes nice and locked down
Makes it very easy for you to toggle off all the security stuff for development
CommandBox now 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
In production mode, CommandBox will block access to your CF admin to all external traffic, will block all common config files such as box.json or .env and will block, the "TRACK" and "TRACE" HTTP verbs
You can set the profile for your server in your server.json
Or you can specify it when starting the server like so:
If a profile is not set, CommandBox looks for an environment variable called "environment" or it checks to see if the site is bound on localhost to try and guess the correct profile for you.
We've also added some new flags in your server.json to fully customize how your profile behaves.
Read more about Server Profiles here:
This is huge-- probably the biggest chunk of work, and it's actually what makes the server profiles above even possible! It's always been possible to perform basic lock downs with a custom rewrite file, but we've exposed an amazing built-in functionality of Undertow called the Predicate language. It allows you to create ad-hoc rules that apply to your server to provide 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
An example of a server rule using Undertow's predicate language to block access to any box.json files looks like this:
One of the best things about these rules, is they don't have to be in a single monolithic XML file. Instead they can come from
An array of ad-hoc definitions in your server.json file or config server defaults
one or more external JSON or text file specified in your server.json or config server defaults
Built in CommandBox server profiles (see above)
Here's some examples of what can be in your server.json
There are TON of built in predicates and handlers your rules can use. We've documented some of them :
CommandBox also registers some custom rules in Undertow you can use for your CF apps:
There are lots of new docs on this. Read more about Server Rules here:
Task Runner Lifecyle events
The more we use Task Runners for builds, scheduled tasks, and utilities, we've seen the need to have lifecyle events in the same manner as the preHandler and postHandler sort of stuff in ColdBox MVC. Now if a task runner has methods of this name, they will be executed automatically.
preTask - Before any target in the task
postTask - After any target in the task
aroundTask - Wraps execution of any target in the task
The lifecycle methods are very powerful and can be controlled via whitelist and blacklists to control what targets they execute for. "Around" events are very easy to use thanks to the use of closure. There's a lot more details in the docs.
Read more about Task Runner Lifecyle events here:
System Setting ${} Namespaces
The default namespace when using the $ {foo} system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.
It is also possible to leverage built-in namespaces to allow expansions that reference:
arbitrary JSON file properties
This gives you a lot more power now to be able to create dynamic configuration in your JSON files and even from the command line. Here are some examples:
And one of the coolest things is this implementation is driven by a new onSystemSettingExpansion interception point and completely extendable! That means you can write a module that powers something hypothetical like this:
Read more about System Setting namespaces here:
GZip Compression Control
CommandBox has had the ability to enable/disable GZip compression in Undertow for a while. Now you can fully control when it activates based on the type or size of file, etc. This feature utilizes the same Undertow predicate language that we introduced above.
Read more about GZip Compression Control here:
Generic Watch Command
This is a fun one. There are some specific commands that make use of the Watcher library in CommandBox such as testbox watch and coldbox watch-reinit. However, there is also now a generic watch command that will run any arbitrary command of your choosing when a path matching your file globbing pattern is added/updated/deleted. Use this to build custom watchers on-the-fly without needing to touch any CFML code to write a Task Runner.
That command will echo out "config files updated!" every time a JSON file gets changed in the current directory. Here's a more complex one:
That one will list every new file that's added in this directory and all sub directories.
Read more about the generic watch command here:
Control Default Browser
There are a handful of features in CommandBox that will open URLs for you in your default browser. We've had requests to allow the browser in use to be customized, so we've reworked all of that logic, consolidating it in some places and now you can control what browser CommandBox uses. To change the default browser for all URL opening functions use this:
Supported browsers are:
And you can even dial in a browser on demand for the browse and server open commands.
Read more about setting the default browser here:
Here are some honorable mentions.
.htaccess rewrite flags
The CommandBox Tuckey rewrites allow an .htaccess file that uses the mod_rewrite style syntax of rewrites. Previously, use of flags such as these didn't work:L
Server restart from tray icon
We've added a "restart" option to the tray icon that does exactly what you think it does.
Trick for "cd"ing up directories
There's a new trick supported in CommandBox's shell that we've borrowed that allows you to change directories and go "up" more than one directory with less typing:
Pipe into standard input of native binaries
You can now pipe the output of a previous command in CommandBox directly to a native binary like so:
In this case, clip is a Windows binary that will read the standard input and place that text on the clipboard.
Breaking Changes
We work hard to make every CommandBox upgrade backwards compatible. There's a couple things that you may notice different in this release. They're both done to put security first and can be modified to get your original behavior back.
Since the CF Administrator is now blocked for traffic not coming from localhost when in production mode, you may need to explicitly open up the CF admin to make it accessible again if you needed it open to the public on a production server. Even with the profile set to production, you can activate just the CF admin like so:
The web server built into CommandBox will now only serve static files if their extension is found in a whitelist of acceptable files. 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:
If you have a common static file you need to serve, you can add your own custom extensions to the list like so:
And if you think we've missed an obvious one that deserves to be added to the default list, please let us know.
Here's the full list of tickets in the 5.2.0-RC.1 release.
[] - Tuckey UrlRewrite DTD version issues
[] - when installing a package which doesn't exist, commandbox claims forgebox is unreachable
[] - Remove mail-4.1.1.jar from runwar's lib dir
[] - Restart server via tray icon
[] - Stop expanding /WEB-INF paths in servlet init params
[] - Allow configuring default browser to use when opening a URL
[] - review all the runwar dependencies and check for outdated ones
[] - Block TRACE HTTP Verb by default
[] - Implement web server rules in Undertow
[] - Add an option to console log output without ANSI codes
[] - Load predicates in Runwar
[] - Pass Predicates as part of Server Start in CommandBox
[] - Add default server rules/predicates in CommandBox for default lockdown