Bindings
You can configure the IP, Port, and hostnames for your servers in the bindings
object, which is new in CommandBox 6.0. Whereas the legacy syntax defaults to binding to localhost
, bindings will default to all IPs or 0.0.0.0
which is more consistent without mainstream web servers work.
The bindings
object goes inside your web
object in server.json
and for Multi-Site servers, you can also specify bindings
in each site as well.
Types of Bindings
There are 3 types of bindings, some of which have additional information that is specific to them
HTTP
SSL
HTTP/2 support
Server certs
Client certs
AJP
AJP secret
Each type of binding is represented by an object of that name inside the bindings
object. Everything is optional, so only specify what you need
Creating a binding
Every binding has
IP address (can be
*
or0.0.0.0
which means All IPs)Port
zero or more hostnames (An empty string or
*
will match all hostnames)
Note, hostnames are only really used for Multi-Site servers. If you only have a single site defined, all traffic will be served by that site regardless of the hostname of the incoming request.
Just the port
The default key to use is called listen
. You can specify JUST a port, which will default to all IPs and all hostnames:
Listen to IP:port
We can also specify the IP address as an IP or a *
or 0.0.0.0
before the port delimited by a colon:
Specify IP and Port separately
As an alternative to the listen
key, you can specify IP
and port
keys. This can be handy if you plan to override just part of a binding via env vars.
This syntax is mutually exclusive with the listen
key.
Host names
Add in as many hostnames as you need as a comma-delimited list or an array
Multiple bindings of the same type
More than one HTTP binding would look like this, where the same object is used, but inside of an array.
AJP Secret
AJP
bindings work the same as the HTTP
binding examples above, but can have the addition of a secret
key. All AJP connections to this port will need to come bearing the required secret.
HTTP/2 Support
Technically, HTTP/2 can be enabled on either HTTP
or SSL
bindings, but most browsers will only negotiate HTTP/2 over SSL
.
HTTP/2 is enabled by default. The legacy web.http2enable
flag is still obeyed and will be applied to any bindings in that block unless otherwise overridden.
SSL Server Certs
To configure a single SSL Server cert, you can specify the following keys inside the binding:
certFile
- A PEM-encoded DER cert or a PFX filekeyFile
- THe Private key (not used for PFX)keyPass
- The key pass or PFX pass. Blank if not used
SSL SNI Support
To configure multiple SSL certs on the same binding, use a certs
array of objects containing the same keys above for each cert you want to specify.
CommandBox will automatically use SNI (Server name Indication) to choose the correct cert to use when negotiating the SSL handshake based on the hostnames in each cert's
Subject Common Name (CN)
SAN (subject alternative names)
CommandBox will also handle SNI for wildcard certs as well.
SSL Client Certs
If using Client Cert authentication, you can also specify client certs for each SSL binding in an object called clientCert
. This object can have the following child keys:
mode
CACertFiles
CATrustStoreFile
CATrustStorePass
SSLRenegotiationEnable
For more information on how to configure and use client certs, check out our guide here.
Last updated