Java 17 Support

Java 17 was a breaking change for Java users as it now blocks illegal reflective access. Both Adobe and Lucee have been slow to address this. Lucee 5.3.10 mostly seems to run on Java 17, but only the public beta of ColdFusion 2023 (Fortuna) supports Java 17. You may want to start testing Java 17 out, so the CommandBox CLI and its servers seem to have basic support for running on Java 17 now. Note, you may need to add additional JVM args to any servers based on the specific Java libraries you use.

Library Updates

We've bumped library versions such as Redhat Undertow to stay current with recent CVE fixes.

Override package install paths

If you have a project and want all packages of a certain type to use a different-than-normal default install location, you can override each package type just for that project. Create an installPathConventions key in the containing package's box.json which is an object containing keys for each package type you wish to override package install paths for.

{
  "installPathConventions" : {
    "modules" : "../lib/modules",
    "mvc" : "../lib/framework",
    "testing" : "they-will-never-find-it-here-lol/"
  }
}

Read more: https://commandbox.ortusbooks.com/package-management/installing-packages/installation-path

ls --tree

You can get recursive file listings now in a tree view by using the --tree flag

ls --tree

Tree Print Helper

In task runners and custom commands, you can now tap into the same tree printer that the "package list" and "ls --tree" use to output your own ASCII trees.

print.tree(  [
	'Ortus Solutions' : [
		'Products' : [
			'Open Source' : {
				'ColdBox MVC' : {},
				'CommandBox CLI' : {},
				'ContentBox CMS' : {}
			},
			'Commercial' : {
				'ForgeBox Pro' : {},
				'CommandBox Pro' : {},
				'TimeBox BMP' : {}
			}
		],
		'Services' : {
			'Consulting' : {},
			'Training' : {},
			'Design' : {}
		}
	]
] )

which outputs

└─┬ Ortus Solutions
  ├─┬ Products
  │ ├─┬ Open Source
  │ │ ├── CommandBox CLI
  │ │ ├── ContentBox CMS
  │ │ └── ColdBox MVC
  │ └─┬ Commercial
  │   ├── ForgeBox Pro
  │   ├── TimeBox BMP
  │   └── CommandBox Pro
  └─┬ Services
    ├── Training
    ├── Design
    └── Consulting

Read More: https://commandbox.ortusbooks.com/task-runners/printing-tree

Column Print Helper

There is also a print helper method for task runners and custom commands as well as a CLI command you can use that accepts an array or list of simple values and prints them in a column format based on the widest value and the available terminal width.

ls --simple | printColumns

Read More: https://commandbox.ortusbooks.com/task-runners/task-output/printing-columns

unansi Command

This command will accepted piped text and strip any ANSI formatting from it. Especially useful if piping the text to a native OS binary which doesn't handle formatting well.

package list | unansi

clipboard Command

We've introduced a new command for piping text onto your native operating system's clipboard.

echo "Hello World!" | clipboard
Copied to clipboard!

Release Notes

Here's the full list of all the changes in CommandBox 5.9.0.

In this section you will find the release notes for the 5.x version of CommandBox.

• Version 5.9.1 - August 2023

• Version 5.9.0 - May 2023

• Version 5.8.0 - April 2023

• Version 5.7.0 - December 2022

• Version 5.6.0 - September 2022

• Version 5.5.2 - May 2022

• Version 5.5.1 - May 2022

• Version 5.4.2 - October 2021

• Version 5.4.1 - September 2021

• Version 5.4.0 - August 2021

• Version 5.3.0 - May 2021

• Version 5.2.1 - Dec 2020

• Version 5.2.0 - Nov 2020

• Version 5.1.1 - June 2020

• Version 5.1.0 - May 2020

• Version 5.0.0 - Mar 2020

Library Updates

We know this stuff may seem boring, but it's super important to ensure you stay safe and secure on the latest versions of our bundled libraries. We updated the following libs in this release:

• org.lucee:lucee 5.3.9.141 -> 5.3.9.160

• io.undertow:undertow-servlet 2.2.17.Final -> 2.2.19.Final

• io.undertow:undertow-websockets-jsr 2.2.17.Final -> 2.2.19.Final

• net.minidev:json-smart-mini 1.0.8 -> 1.3.2

• commons-cli:commons-cli 1.2 -> 1.5.0

• org.jooq:joox 1.2.0 -> 1.6.2

• org.apache.logging.log4j:log4j-slf4j-impl 2.17.1 -> 2.18.0

• org.apache.logging.log4j:log4j-core 2.17.1 -> 2.18.0

• org.jboss.logging:jboss-logging 3.4.1.Final -> 3.4.3.Final

Lots of Bug Fixes

Over half of the tickets in this release were bug fixes to keep the CLI running smoothly on all operating systems. You can check out the full list of ticket below to see the screws we tightened.

New Server Security System

CommandBox servers have an exciting new weapon in their arsenal, and that is a new system of security that allows you to protect certain parts of your site from the general public. This could be CF admins, private dashboards, or a subfolder of sensitive files.

You'll find a new section in the server.json called web.security where these settings live. You can leverage the power of our Server Rule predicates to match whatever requests you want to secure, based on folder, HTTP method, remote IP, HTTP headers and more.

{
  "web" : {
    "security" : {
      "realm" : "My Realm",
      "authPredicate" : "path-prefix( /lucee/admin/ ) and not equals('%{REMOTE_IP}', 127.0.0.1)"
    }
  }
}

That authPredicate would require authorization for any pages in the Lucee admin unless you were on localhost. NOTE: path-prefix is case sensitive, so on Windows you'd want to use a regex() based check such as regex( pattern='^/lucee/admin/.*', case-sensitive=false )

When a request is marked as requiring authentication, you can enable one or more auth mechanisms to challenge the user as discussed below.

Read more on Server Security Here.

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/security

Basic Auth Security

CommandBox has supported basic auth for a while, but it was a simple all-or-nothing implementation. Basic auth has been revamped and rolled into the new security system. If no authPredicate is defined, it will still apply to the whole site. But when an authPredicate is declared in your server.json, it will only kick in for those pages.

We've also moved the basic auth settings in server.json to here:

{
    "web":{
        "security" : {
            "realm" : "My Realm",
            "authPredicate" : "regex( pattern='^/lucee/admin/.*', case-sensitive=false )"
            "basicAuth":{
                "users":{
                    "brad":"pass",
                    "luis":"pass2"
                },
                "enable":"true"
            }
        }
    }
}

Don't worry, the old location still works too for now. We won't remove support for it until the next major release of CommandBox. If both the settings exist (Ex: web.basicAuth.enable and web.security.basicAuth.enable), the new location will be given precedence.

Read more on Basic Auth Security Here.

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/security/basic-authentication

Client Cert Security

Adding support for client SSL certs was one of our largest undertakings and is a very exciting new feature for government shops who use PKI based authentication, often times in the form of DoD CAC (cards) which are physical cards containing a private PKI cert that identifies the user. This feature was one of the last reasons to need IIS or Apache in your mix, but now CommandBox can do it all!

Client certs have two part-- first is the ability of the web server to prompt the user's browser to ask for a client cert to send. This requires configuring a trust store or a list of trusted CA certs to accept. When the user sends a cert, it automatically makes a number of CGI and request variables available to your CF code. You can configure your SSL connection to accept or require client certs like so:

{
  "web" : {
    "ssl" : {
      "enable" : true,
      "clientCert" : {
	"mode" : "Requested",
	"CACertFiles" : "rootCA.cer,anotherRootCA.cer",
	// OR...
	"CACertFiles" : [
          "rootCA.cer",
          "anotherRootCA.cer"
	],
        // OR...
	"CATrustStoreFile' : "cacerts",
	"CATrustStorePass' : "changeit"
      }
    }
  }
}

Some of the CGI variables which are automatically created when a client cert is present are

• CGI.SSL_CLIENT_CERT - PEM-encoded cert (base 64 string)

• CGI.CERT_SUBJECT - The Subject distinguished name of the client cert (CN=foo, O=bar, OU=baz)

• CGI.CERT_SERIALNUMBER - The serial number of the cert in the format 91-7e-5f-a5-b2-20-a1-8b-4c-d0-40-3b-1c-a1-a8-58

• CGI.CERT_ISSUER - The Issuer distinguished name of the client cert (CN=foo, O=bar, OU=baz)

• CGI.SSL_CLIENT_VERIFY - Matches Apache HTTP. Values will be "SUCCESS" or "NONE"

The second part of client certs is the ability to use that client cert information as an authentication mechanism to enforce your authPredicate automatically. (When CommandBox's security system is unable to authorize a user, it stops the request before it ever even reaches CF!)

When authorizing based on client certs, you can have 4 levels of checks:

• Any user with a cert is allowed. (Remember, the client cert must always be trusted by one of your configured trusted CA certs)

• Subject Distinguished Name (DN) matches one or more complete or partial DNs you specify

• Issuer Distinguished Name (DN) matches one or more complete or partial DNs you specify

• Or disable the web.security.clientCert.enabled setting and allow all requests to reach CF where you can write your own checks.

CommandBox also supports SSL Renegotiation which allows you to not force the client cert right away until the user gets to a page on the site that kicks in the authPredicate and then their browser will prompt them then. This is a popular configuration since the user can hit your login page first and then be prompted for their cert once they login.

The configuration for all this looks like this:

{
  "web" : {
    "security" : {
      "realm" : "My Realm",
      "authPredicate" : "path-prefix( /admin )"
      "clientCert" : {
        "enable" : true,
        "SSLRenegotiationEnable":true,
        "subjectDNs" : "O=Ortus, OU=Marketing",
        "issuerDNs" : [
          "O=Verisign",
          "CN=Bob, O=Walmart",
          "CN=GeoTrust TLS RSA CA G1, O=DigiCert Inc, OU=www.digicert.com"
        ]
      }
    }
  }
}

Read more on Client Cert Auth security Here.

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/security/client-cert-authentication

Task Runner loadModules()

As Task Runners become more popular and people combine them with more modules to perform their operations, you run into the need to load a list of modules all at the same time which may have interdependencies. There is now a new loadModules() method available to Task Runners which accepts an array of module paths. Each module is first registered, and then each module is activated.

loadModules(
    directoryList( path=resolvePath( 'modules/' ), type='dir' )
);

Read more here:

https://commandbox.ortusbooks.com/task-runners/loading-ad-hoc-modules#loading-multiple-modules

Release notes

Bundled System Modules

To be more useful, CommandBox now bundles the following system modules

• commandbox-cfconfig

• commandbox-dotenv

• commandbox-update-check

They will be automatically installed (or updated) when you start the CLI for the first time. You can still update or uninstall them, just like any system module. Note: If you have any of these modules currently linked into the CommandBox core, any uncommitted changes will be overwritten when you upgrade box. Please unlink the repos first before upgrading.

The CommandBox Update Check modules can be disabled if you don't like it via

config set modules.commandbox-update-check.enable=false

It will also automatically obey the offlineMode Config Setting.

Custom MIME Types

CommandBox will automatically set the content type in the HTTP response for common static file types. If you come across a file extension that doesn't have the correct type, you can set it like so in your server.json:

server set web.mimeTypes.log=text/plain

Which creates the following

{                            
    "web":{                             
        "mimeTypes":{                  
            "log":"text/plain"      
        }
    }
} 

In the above example, hitting a file such as foo.log would come back with a text/plain content type header.

This setting will override any <mime-mapping> tag in your web.xml file.

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/mime-types

Config and Module Sync

If you are authenticated to ForgeBox in the CLI, you can synchronize your config settings to and from your ForgeBox account. This is a great way to get up and running on a new PC or keep multiple CommandBox installs in sync. In addition to synchronizing your Config Settings, this feature will also track your installed system modules, such as CFConfig, etc.

config sync push

This command will push your local settings and modules up to your ForgeBox account.

config sync push

By default, the settings are "merged" so new local settings will be added to ForgeBox, but nothing will be removed. To remove config that only exists on ForgeBox, you can use the --overwrite flag to force a full sync.

config sync pull

This command will pull your settings and modules from your ForgeBox account and set/install them locally.

config sync pull

By default, the settings are "merged" so missing settings will be added locally, and missing system modules will be installed, but nothing will be removed. To remove config and modules that only exist locally, you can use the --overwrite flag to force a full sync. This will remove local config settings and uninstall local system modules which were not on ForgeBox.

config sync diff

This command will not change anything, but gives you a full report of all settings which are different between your local CommandBox CLI and ForgeBox. It will show you "Remote Only," "Local Only," and "Changed" settings and modules. Use this to see what you're about to change before pushing or pulling.

config sync diff

Read More: https://commandbox.ortusbooks.com/config-settings/setting-sync

onServerInitialInstall interceptor

This is the same as onServerInstall, but it only runs the VERY FIRST time a CF engine is installed. This is helpful if you want to install Lucee extensions or ACF modules and only need to do it the first time. This interceptor is easier than using onServerInstall and inspecting the installDetails.initialInstall flag.

Case Sensitivity of Web Server

This has been an experimental feature of CommandBox servers for a while, but we've finalized the feature and added a proper setting to enable it in server.json. By default, the web server in CommandBox will follow the case sensitivity of the underlying file system. So, when on Windows /FiLe.TxT will still load an actual file called /file.txt. But on Linux, the case in the browser would need to match that of the file system. CommandBox allows you to force case sensitivity to be ON or OFF for a server, overriding the server's file system.

Forcing Case sensitivity

To force CommandBox's web server to be case sensitive, even on operating systems like Windows, use the following setting. There is a nominal performance benefit in doing this, and it can allow a Windows CommandBox server to mimic a Linux server for testing.

server set web.caseSensitivePaths=true

Forcing Case Insensitivity

To force CommandBox's web server to be case insensitive, even on operating systems like Linux, use the following setting. There is a nominal performance overhead in doing this, and it can allow a Linux CommandBox server to mimic a Windows IIS server. In this mode, CommandBox will use an internal cache of file system lookups to improve performance. If there are two files of the same name using different case, then you will get whatever file is found first.

server set web.caseSensitivePaths=false

Read More: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/case-sensitivity-of-web-server

Support for PFX cert files

If using CommandBox's SSL, you can now use a PFX file (PKCS #8 format) which contains the public and private key in one file.

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/ssl-certs

Case Insensitive Server Rule Predicates

Most of the Server Rule predicates are case-sensitive, which poses a problem when using them for security on Windows since they will only match one specific spelling of a folder or file. We have added "-nocase" versions of several popular predicates which perform case-insensitive checks.

• regex-nocase()

• path-suffix-nocase()

• path-prefix-nocase()

• path-nocase()

• equals-nocase()

• contains-nocase()

Server Rule Reverse Proxy handler supports SSL

Undertow's reverse-proxy() handler would not connect to a back-end server using SSL. We've given up on RedHat fixing this any time soon, and added a new load-balanced-proxy() handler which works with SSL.

load-balanced-proxy({'https://reports1.mydomain.com','https://reports2.mydomain.com'})

REPL Improvements

Due to long-standing bugs in the Lucee evaluate() function that seem like they'll never get fixed, we've finally put a workaround in the REPL, which captures the return value of member functions chained to literals and expressions using closures. Ex:

CFSCRIPT-REPL: "test".len()
4
CFSCRIPT-REPL: [1,2,3].each( (i)=>echo(i) )
123

Per-Server Preferred Browser Setting

There is already a Config Setting for the preferred browser when opening up sites. You can now customize this on a per-server basis with this server.json setting

server set preferredBrowser=firefox
server open

New Server Console Log Layouts

You can now control the Log4j appender layout for CommandBox servers, which includes formats such as JSON, which allows your server logs to be automatically imported into Elastic Search

server set runwar.console.appenderLayout=JSONTemplateLayout

Read More: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/console-log-layout

New forgebox version-debug command

There is a helpful command called forgebox version-debug which will show you what version of a package will be installed without actually installing it. It can also be useful to test a semver range and see what packages it matches.

Read More: https://commandbox.ortusbooks.com/package-management/installing-packages/debug-installation

Release Notes

Bug

COMMANDBOX-1537 Experimental feature force insensitive web server has stopped working in some cases

COMMANDBOX-1541 Hide Felix error messages in console on startup

COMMANDBOX-1542 Custom tray options calling box with space in path fail

COMMANDBOX-1550 Add load-balanced-proxy() handler to replace Undertow's broken reverse-proxy() because they refuse to fix it

COMMANDBOX-1551 Capture return value from some REPL expressions because Lucee refuses to fix evaluate()'s parser

COMMANDBOX-1552 Two instance of CLI cause class loading issues from OSGI bundles

COMMANDBOX-1559 server start port check doesn't take web.http.enable into accout

New Feature

COMMANDBOX-1434 CommandBox settings sync feature

COMMANDBOX-1539 Add onServerInitialInstall package/server script

COMMANDBOX-1540 Add `.webp` as a default mime type for CommandBox to support this new image format

COMMANDBOX-1543 Formalize setting for case sensitivity of web server

COMMANDBOX-1549 Add "nocase" versions of regex(), path-suffix(), path-prefix(), equals(), contains(), and path() predicates

COMMANDBOX-1555 Improve forgebox whoami command

COMMANDBOX-1556 Allow CommandBox to customize console appender Layout

COMMANDBOX-1562 New "forgebox version-debug" command

COMMANDBOX-1566 Bundle super helpful modules in box core

COMMANDBOX-1567 onConfigSettingSave and onEndpointLogin interception announcements

Improvement

COMMANDBOX-1034 Ability to pass file name to "more" command

COMMANDBOX-1345 Add a method in server.json to add MIME type mappings to Undertow

COMMANDBOX-1393 Improve message when starting second server with single server mode enabled

COMMANDBOX-1538 system setting serverinfo namespace use interceptdata if running inside of server script

COMMANDBOX-1544 Allow `web.webroot` to be changed in single server mode

COMMANDBOX-1545 Authentication failures don't send custom error pages

COMMANDBOX-1547 Add directory param to coldbox watch-reinit command

COMMANDBOX-1548 Support PKCS #8 format private keys

COMMANDBOX-1554 Allow preferredBrowser to be set on a per-server basis

COMMANDBOX-1557 Add file and directory completion to the ID param of the install command

COMMANDBOX-1558 Add installExtension() for commands and task runners to install Lucee extensions on the fly to the CLI

COMMANDBOX-1560 Update Lucee to 5.3.10.120 in CLI core

COMMANDBOX-1561 Improve upgrade command

COMMANDBOX-1564 Load libdirs in system classloader

COMMANDBOX-1565 Check for default branch of "main" in Git endpoint

Task

COMMANDBOX-1357 Try removing JAX API classes from runwar

COMMANDBOX-1546 Update to Undertow 2.2.22-Final

COMMANDBOX-1553 Update bundled JRE to jdk-11.0.18+10

COMMANDBOX-1563 Remove stopgap for COMMANDBOX-1459

Release notes

Bug

Server shutdowns aren't always done cleanly

Don't prompt on already-running server when terminal isn't interactive

Globber copyTo() command mishandles *nix leading slash

preServerStart can no longer affect server.json env var replacements

Servers can no longer override rest mappings

Corruption in interactive job output

Can't set XNIO socket settings or Sequence types

Command chaining has a code path where "job" variable is not defined

cfpm breaks in single server mode

Improvement

Allow Undertow's resource manager file system watcher to be disabled

Customize Undertow's enabled SSL protocols

Task

Update to Lucee 5.3.9.141 stable

Check Out The New Stuff

The notable updates include:

• Updated version of JBoss Undertow, which contains security fixes

• Updated version of Lucee to 5.3.10 which also contains library security updates

• New "artifacts prune" command to remove older artifacts that haven't been used recently

• Improved "upgrade" command which can also update new jars (you'll be able to use this in the NEXT update!)

• Support for PFX cert file for server SSL

And here are the full release notes:

New Feature

update coldbox resources to support api resources

artifacts prune command

Bug

Use user.home instead of user.dir to test case sensitivity

Cursor position get's off-track when using a multiselect with content that exceeds the terminal size

Improvement

Task

There are a lot of new features in CommandBox 6. Here's an overview of the biggest ones. Check out the release notes for the full list.

Multi-Site Servers

This one is huge. It's the hallmark feature of CommandBox 6 and allows you to easily run as many web sites (with different web roots) in a single CommandBox server. This finally gives you the same behavior you get with Adobe ColdFusion and IIS or Lucee/Tomcat and Apache with mod_cfml. CommandBox has had built-in ModCFML support for a while, but it still needed a web server in front to work fully. CommandBox Multi-Site gives you a fully powered web server that allows you to define as many separate web sites as you like, each with COMPLETE configuration control, all inside a single server process.

• Rewrites

• web aliases

• security profile

• HTTP/SSL/AJP bindings

• SSL Certs

• welcome files

• MIME types

• GZIP settings

• Basically everything can currently configure under the "web" object of your server.json can be set on a per-site basis!

CommandBox is now truly a One-Stop-Shop for running your apps from development to production. You don't need Apache, Nginx, IIS, or Tomcat!

Enhanced Server Bindings

Going hand-in-hand with our Multi-Site features, is the ability to bind to more than one HTTP port, more than one SSL port and more than one AJP port. You can configure proper host name matching on any binding, and even have multiple SSL certs. This new feature is available not only for Multi-Site but also for single site servers. The new server bindings come with a new JSON syntax in the server.json (we still support the old one too)

SSL SNI Support

Going hand-in-hand with our enhanced server bindings, is the ability not only to be able to specify multiple SSL certs per site, but also multiple SSL certs per SSL binding. CommandBox automatically enables SNI (Server Name Indication) which will choose the proper cert based on the incoming host name. With support for PEM files, DER formats, and PFX formats, this really opens up a lot of capabilities.

Rewrite Maps

We added a popular feature from Apache's mod_rewrite called rewrite maps. This allows you to create a simple text file of values you can reference in your rewrite rules to map incoming URL values to another value.

Publish command directly uploads to S3

This is a nice little productivity enhancement. When you run the publish command, the CLI will now directly upload your zip file to S3 instead of sending it to ForgeBox first. This improves the speed and efficiency of your deployments.

Add a proxy server rule alias

This is a simple one. If you want to create a simple reverse proxy to a single back-end server, we've created an alias for the existing load-balanced-proxy() handler called just proxy which accepts a single host with less verbosity.

Specify Package and Server scripts as an array

You're already familiar with specifying package scripts and server scripts in your box.josn and server.json as a string containing one or more commands. Instead of using && for multiple commands, 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.

ColdBox, TestBox and ContentBox commands are now modules

CommandBox still bundles helpful scaffolding commands for your favorite MVC framework Testing framework, and CMS, but these commands are no longer part of the core CommandBox source code. We've given them new life as independent modules. They are installed by default, but they now have their own lifecycle and can get releases at any time. You can view and update them with the rest of your system modules.

Adobe CF Script Alias

CommandBox adds a /cf_scripts/scripts alias for you any time you start an Adobe CF server. This alias points to the same folders in the root of the Adobe WAR. If you set a custom scripts src path in the CF administrator then you'll want to ensure CommandBox uses the expected alias. There is now a setting called web.adobeScriptsAlias which allows you to control the public, web-accessible path to the scripts folder that CommandBox creates for you. And better yet, if you're using CFConfig, will automatically update the Adobe script source setting to match and vice versa.

CommandBox Pro Config settings auto-sync

As a perk of CommandBox pro, once you log into the CLI with your ForgeBox Pro account, your config settings will now automatically sync to and from ForgeBox. This is a great way to keep multiple CLI instances across computers up to date.

Release Notes

Here are the full release notes for CommandBox 6.0.0

Bug

New Feature

Improvement

Task

This is a very small release with two changes.

• Update to Lucee 5.4.3.2

• Update bundled JRE to 11.0.20+8

Note Lucee 5.4.3.2 contains critical security patches which are outlined here:

The new Lucee version affects the core CLI runtime as well as the default server you get when running "server start" with no cfengine specified. Possible compatibility issues related to the major bump in Lucee version:

• This Lucee version does not include Hibernate, so the Ortus Hibernate extension is installed. We will stop doing this in 6.0

• This Lucee version has strict XML parsing settings on by default which may affect any servers you start which parse XML containing DTDs.

If you do run into XML errors, this code may help you in your Application.cfc, which allows DTDs, but still disallows XML external entities (XEE).

Release notes

Task

• Update bundled JRE to 11.0.20+8

• Update to Lucee 5.4.3.2

• There is a fix for a regression introduced in 5.4.0 where updating the version of a CF engine doesn't work without forgetting the server first.

• There is also an important security improvement to CommandBox servers. Thanks to Abram Adams for reporting this to Ortus so we could address it.

Release notes

Note, the details of the security improvement have been tracked privately.

Bug

Java path shows up twice in "server info --verbose"

Updating server in-place keeps old web.xml path

recipe with multiple "install" instructions fails

Improvement

Add additional interceptData to server interceptors

Update to WireBox 6.5.2

Immediately activate modules after installation

Improve multiselect DSL

Story

Add JSON and Properties output for info command

web.xml Overrides

When you start an Adobe or Lucee CF Engine, the WAR CommandBox uses has a stock web.xml baked into it. Sometimes you may want to add custom servlets, servlet mappings, etc into your server. You can override the stock web.xml in part or in total with a file of your own which you specify in the server.json like so:

More info here:

Funky Parameters

In addition to quoting parameter values, parameter names can also be quoted. This is useful when setting keys into settings or JSON files that have spaces, hyphens or special characters. Each of these examples are now supported:

More info here:

Library updates

Lucee Server has been updated to 5.3.8.201 and JBoss Undertow has been updated to 2.2.10.Final. The Lucee update, as usual, applies to the CLI as well as the default server you get when you run server start.

Smarter Jar Endpoint

When you install a Jar via HTTP URL and the version number is baked into the URL, the jar endpoint now makes more assumptions about what the version of the package is that allows it to optimize the update checks and eliminate unnecessary downloads.

More info here:

ask and confirm commands

Here are some fun commands for user interactivity in the shell. You can use these as part of a recipe or a nice "one-liner".

ask

The ask command is similar to the ask() method in Task Runners. It requires an interactive terminal and will ask the user a question and return their answer. It is meant to be changed with other commands.

or with default values

or with masked input

Or fun stuff like this

confirm

The confirm command will ask the user a yes/no question and return a passing or failing exit code from the command based on the answer.

Remember the && operator will only execute the second command if the first command returns an exit code of 0.

More info here:

server prune command

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.

More info here:

Release Notes

Here are the full release notes for CommandBox 5.4.0

Bug

Improvement

New Feature

Task

Override Config Settings via Env Vars

Every Config Setting can be overridden by convention by creating environment variables in the shell where you run box. This is ideal for CI builds where you want to easily set ForgeBox API keys, or tweak settings for your build.

More Info:

Override Server Settings via Env Vars

Every server setting can be overridden by convention by creating environment variables in the shell where you run box. This is ideal for CI builds where you want to easily set ports, or tweak settings for your build.

HTTP/2 Support

CommandBox now has out-of-the-box support for the HTTP/2 protocol. It is always enabled by default and browsers will use it when you're serving over HTTPS.

JMES JSON filtering / jq Command

We've added a new jq command which behaves roughly like the bash counterpart. You can pipe in JSON, or read the JSON from a file and apply a JSON query against it which can be used to filter, massage, rewrite, map, or filter the JSON into a new JSON object.

We've also added the ability to specify powerful jq filters to the "package show", "server show", and "config show" commands directly. Just prefix your filter with the text "jq:" like so:

AJP Secret Support

For this to work, you must also configure your AJP proxy in your web server to send the same secret!

AsyncManager Available to Task Runners and Commands

We've updated the version of WireBox inside the CLI and now have access to the AsyncManager for sweet threading and scheduled task support.

CommandBox is using an AsyncManager scheduled task thread now to redraw interactive jobs and progress bars. Look out for some new eye candy hiding in your server starts and package installs!

New Table Printer

The print helper in commands and Task Runners has a new toy that will print ASCII representations of tabular data thanks to a pull request from Eric Peterson. You can see it in the output of the outdated command.

And you can use it in your Task Runners like so:

ColdBox Scaffolding for REST Handlers

When scaffolding ColdBox handlers, we have support for ColdBox 6.x REST Handlers now.

Experimental Server Features

You can enable extra Resource Manager Logging when troubleshooting file system issues:

You can force case sensitivity on a Windows server:

You can force case Insensitivity on a Linux server:

You can enable a cache of file system lookups of servlet paths. This is only for production and will eliminate repeated file system hits by your CF engine, such as checking for an Application.cfc file on every request, or testing where the servlet context root is. Standard Adobe ColdFusion installations have a similar cache of "real" paths from the servlet context that is tied to a setting in the administrator called "Cache Webserver paths" but that setting is not available and does not work on CommandBox servers for some reason. This setting would apply to any CF engine.

HTTPS Redirect/HSTS

When using a CommandBox web server in production, you may wish to force your users to visit your site over HTTPS for security (and for HTTP/2 to work). However, it is desirable to still have your web server listening on HTTP so a user just typing your address in his browser can still connect to HTTP and then redirect. CommandBox can be configured to redirect all HTTP traffic over to HTTPS with the following setting.

If you want to go one step further, you can add a Strict-Transport-Security header to your site. This instructs the browser to automatically use HTTPS every time the user visits your site again.

Force Colored Output in your Builds

CommandBox won't use ANSI color formatting when running inside of a non-interactive terminal. However, build servers such as Gitlab or Jenkins (via a plugin) support ANSI color sequences. You can force CommandBox to use colored text output with this new setting:

Loose Semantic Version Parsing

One of the common hangups for people dealing with Lucee Server and Adobe ColdFusion CF Engines versions, is that CommandBox follows the npm-flavor of the semantic version spec and expects

instead of

So we've loosened our sem ver library to treat the 4th number as a build ID if there is no plus sign in the version (instead of just discarding the 4th digit as the spec requires)

Support for "localhost subdomains"

Most modern browsers allow you to make up any subdomain you want before localhost such as mySite.localhost and will simply resolve them to localhost (127.0.0.1) even without a hosts file entry. CommandBox now supports using these domains and will bind your server's ports to localhost even without using the commandbox-hostupdater module.

Relative CommandBox home

You can customize where CommandBox lives by placing a commandbox.properties file next to the box binary. We have better support for relative paths now so you can have portable CommandBox installations such as a thumb drive.

Halt Server If Port In Use (Breaking Change)

The only known breaking change in this release is if you try to start two servers on the same HTTP port. Previously, CommandBox would just ignore the port on the second server and choose a random port. Due to the confusion that can cause, CommandBox will now throw an error. If you want to override an explicit port locally, set the port to an empty string or a 0 and CommandBox will choose a random port for you. For example, if you are using the commandbox-dotenv module, you can put this line in your project's .env file to override the port in your server.json

Relative Web Alias Behavior (regression)

If you have a server with the server.json outside of the web root and at least one relative web alias, the alias will not work on the first start of the server. The workaround is to change the web aliases to be relative to the folder that the server.json lives in.

Incompatibility with old DotEnv module

Some users receive the following error when starting CommandBox after updating:

If you see this, it means you have an older version of the commandbox-dotenv module installed that is not compatible with the new version of WireBox inside CommandBox. To fix, delete this folder out of your CommandBox home:

Now the CLI will start and you can install the latest version of dotenv.

Release notes

Here is the list of all tickets included in the 5.3.0 release.

Bug

Improvement

New Feature

This release was primarily to address a regression in 5.1.0 affecting Mac OS users who tried to start Lucee servers. If you see an error similar to this on a Lucee server and you're running a Mac and CommandBox 5.1.0, then this release will fix it for you.

If you are upgrading from CommandBox 5.1.0, there are only a handful of tickets which are listed below. If you are updating from an earlier version of CommandBox, please check out our and release blogs.

Release notes

Bug

• [] - Overzealous gitignore matching of parent directories when zipping up for ForgeBox storage

• [] - Enabling SSL results in some CFHTTP requests to fail.

• [] - writedump failing in Lucee

• [] - File globbing matching partial file names

Improvement

• [] - Allow for verbose startup without debug logging of requests

Updated bundled Java libraries

• JLine - 3.19.0

• jGit - 5.11.0.202103091610-r

• Launch4j - 3.14

• JANSI - 2.3.2

Recursive jar scanning libDirs

When you configure libDirs for a server, CommandBox used to only load jar files found in the root. Now it will include sub directories which gives you more flexibility around how to install your jars.

New printTable Command

In the previous release, we introduced a new helper for printing ASCII Art tables in your custom commands and task runners. We've taken this a step further and wrapped the table printer utiilty in a new command so you can use it from the CLI directly. We've also expanded its functionality to accept ANY data in as JSON and it will marshall it into a query for you. This means it can be a query, an array of structs, an array or arrays, and more. You can now get quick and easy visualization of any data right from the CLI or in builds.

New sql command for on-the-fly manipulation of data

As if the previous command isn't cool enough, we've also added a new "sql" command which will also accept any sort of data as JSON, marshall it into a query object and allow you to alias, filter, order, and limit the rows on the fly using CFML's query of queries!

The sql command works very nicely with the new tablePrinter command, and truly makes JSON a first class citizen of the CommandBox CLI.

Small change to print.table() helper

We've made a small adjustment to the print.table() helper that was introduced in CommandBox 5.3.1 as follows. The old method signature is

And the new method signature is:

The parameters to the new printTable command matches the NEW method signature of the print.table() helper as well.

Format XML in REPL

When working with XML in the REPL, formatting is now applied when the XML is printed out to the console, making it easier to read (same as JSON)

Release Notes

Bug

Improvement

New Feature

In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

• - Feb 2024 -

• - Mar 2020 - August 2023

• - Jun 2018 - Sept 2019

• - Feb 2016 - Nov 2017

• - June 2015 - Nov 2015

• - Feb 2015

ModCFML Support

ModCFML is a popular standard for running a CF server behind IIS or Apache web server and allowing your virtual hosts configured in the web servers to control the web root of the CF server so you can run more than one site on a single CF instance. CommandBox has historically only had a single web root per server, but now you can use a single CommandBox instance to power as many Adobe CF or Lucee Server sites as you like. CommandBox's ModCFML just needs to be enabled and can work with BonCode, mod_cfml or Nginx.

server.json

Read more here:

Log4j 1.x is gone!

CommandBox's core is now 100% free of 1.x versions of the Log4j library. Note, if you start an older Lucee server or any Adobe ColdFusion server, they may still have Log4j 1.x bundled with them.

Library updates

Many of the java libraries have been updated

• JRE-bundled version ships with Java 11.0.15+10

• Undertow updated to 2.2.17.Final

• Lucee updated to 5.3.9.133

• JGit updated to 5.13.0.202109080827-r

• JLine updated to 3.21.0

• Runwar updated to 4.7.4

• Log4j updated to 2.17.1

Set Java System Props directly in server.json

Does what it says. Looks like this:

server.json

JVM Args can be an array

JVM args and Runwar args can now be set an array of strings which prevents you from needing to escape or quote anything.

Old way (still works)

New way

Request Dumper

There is now a handy little handler you can put in your server rules to view a console dump of all the header data related to your request and response.

server.json

OpenJDK Downloads

assertFalse command

Opposite of assertTrue. Returns a passing (0) or failing (1) exit code whether falsy parameter passed. Truthy values are "yes", "true" and positive integers. All other values are considered falsy

assertNotEqual command

Opposite of assertEqual. Returns a passing (0) or failing (1) exit code whether both parameters DO NOT match. Comparison is case insensitive.

Better command chaining

You can have more than two chained commands, and the command chain will keep executing so long as the next part is compatible with the previous exit code. Ex:

cfpm improvements

• We now set the JAVA_HOME for the cfpm command if it doesn't exist

• An Adobe server no longer needs to be the default server for that web root

• If cfpm is run as part of a package or server script, it will default to the using the server currently doing something

box.exe finds Java better on Windows

Previous versions of Launch4j only used the Windows registry to find the installed version of java. The following environment variables are now also checked in this order to attempt to find a JRE to use.

• JAVA_HOME

• JRE_HOME

• JDK_HOME

• PATH

head Command

Does the same basic thing as the tail command, but it reads from the top of the file or input.

X-Forwarded-For support disabled by default

For better security, CommandBox servers will not automatically obey X-Forwarded-For HTTP headers unless you enable it.

Only enable this setting if your CommandBox server is behind a trusted proxy which always sets this header. Otherwise, a malicious client could spoof a trusted IP an bypass IP access control.

Relaxed semantic version parsing

Both of these commands will now do the same thing. The second one used to error with version not found.

XML Love

XML formatting is now a first-class citizen of the print helper and the REPL. You can pass a parsed XML doc and they will be formatted upon display.

Mac Tray Icon Disabled

Due to lack of Java 9+ support in the Java library that creates tray icons, we've disabled the tray icon by default on MacOS. If you want to brave the possibility of it not working or spilling errors in the console, you can re-enable it like so:

Hopefully when the library gets updated, we'll be able to re-enable the tray icon by default.

Release Notes

Here is the complete list of all tickets closed in this release

Release Notes

Bug

Some installs unnecessarily write to the box.json

ConfigService::settingExists() fails in race conditions due to non-varscoped variables in JSONService

Improvement

Support excludePaths in watcher DSL and watch command

Ensure Adobe wars have a seeds.properties file

Add tab complete for "env clear" command

Ignore empty startScript on server start

Java 14 support

Java 14 is now supported in CommandBox 5.1.0. In order to support Java 14, we had to stop using Pack200 which means the binary sizes have grown a little. The good news is CommandBox will start up a little faster on its first run since there's less to unpack now.

Start pure HTML Server

You can start up a lightweight server that only serves static files now with CommandBox.

New CommandBox Light and CommandBox Thin Binaries

In pursuit of the smallest possible Docker images, we have CommandBox light which is built on Lucee Light. We also have a box "thin" binary you can swap out with the full self-extracting binary when using CommandBox in custom docker images. Check out Pete Freitag's to see both of these in use in a super tiny 78 Meg docker image. More docs here:

Force working directory when starting

If you're using box in an integration where you want it to start up in a specific working directory, there is a new bootstrap CLI arg for that.

Server tray menu item custom commands

You've always been able to specify custom menu items in your server.json or global config settings, but we've kicked it up a notch. Not only can you contribute to existing sub menus now, you can execute arbitrary native commands synchronously or async.

Release Notes

Here's the full list of tickets closed down in the 5.1.0 release.

Bug

New Feature

Task

Improvement

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

• Upgraded jboss-logging from 3.2.1.Final to 3.4.1.Final

• Upgraded jboss-logging-annotations from 2.1.0 to 2.2.1.Final

• Upgraded JCabi Log from 0.18 to 0.18.1

• Upgraded Apache HttpClient from 4.2.6 to 4.5.12

• Upgraded Apache httpmime from 4.2.6 to 4.5.12

• Removed unused JOpt Simple 5.0-beta-1

• Removed unused Gson 1.2.3

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:

Server Rules

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)

• Custom 3rd party CommandBox modules that contribute rules on-the-fly (time to get creative!)

Here's some examples of what can be in your server.json

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

• pre- Before a specific target

• post- After a specific target

• around - Wraps execution of a specific target

• onComplete - Fires regardless of exit status

• onSuccess - Fires when task runs without failing exit code or exception

• onFail - Fires if exit code is failing after the action is done (always fires along with onError, but does not receive an exception object). Use this to respond generally to failures of the job.

• onError - fires only if an unhandled exception is thrown and receives exception object. Use this to respond to errors in the task. Does not fire for interrupted exceptions

• onCancel - Fires when the task is interrupted with Ctrl-C

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:

• server.json properties

• box.json properties

• arbitrary JSON file properties

• Config settings (like the config show command)

• Server info properties (like the server info property=name command)

• Other properties in the same JSON file

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:

• firefox

• chrome

• opera

• edge (Windows and Mac only)

• ie (Windows only)

• safari (Mac only)

• konqueror (Linux only)

• epiphany (Linux only)

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:

Miscellaneous

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.

Release Notes

Here's the full list of tickets in the 5.2.0-RC.1 release.

Bug

New Feature

Task

Improvement

Sub-task