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.

server set openBrowserURL=/bar.cfm

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

server set openBrowserURL=http://127.0.0.1:59715/test.cfm

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:

 start port=8080

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

server set web.http.port=8080
server show web.http.port

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:

 $> netstat -pan | grep 80

HTTPS

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

start SSLEnable=true SSLPort=443

server set web.SSL.enable=true
server set web.SSL.port=8080
server show web.SSL.enable
server show web.SSL.port

Setting SSL Enabled protocols

You can customize what SSL protocols your HTTPS listener will respond to with the following XNIO option. Supply a comma-delimited list of valid protocols.

server set runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2

HTTP/2

HTTP/2 is a newer standard of HTTP supported by all modern browsers. HTTP/2 is enabled by default any time you are using an HTTP/HTTPS listener, however all major browsers will only allow the server to negotiate HTTP/2 over an HTTPS connection. HTTP/2 runs over the same port and only changes the exchange between the server and browser. You can disable HTTP/2 support like so:

server set web.http2.enable=false

If you want to confirm whether your browser is using HTTP/2, you can open your debugging tools and look at the network requests. You may need to add the "protocol" column in the UI. HTTP/2 will usually show up as something like "h2" in the protocol column.

AJP

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

start AJPEnable=true AJPPort=8009

server set web.AJP.enable=true
server set web.AJP.port=8009
server show web.AJP.enable
server show web.AJP.port

AJP Secret

CommandBox's AJP listener (provided by Undertow) is already protected against the Ghostcat vulnerability. However, if you would like to set utp an AJP secret as well to ensure all requests coming into the AJP listener are from a trusted source, you can do by setting the web.ajp.secret property.

server set web.AJP.secret=mySecret

For this to work, you must also configure your AJP proxy in your web server to send the same secret! For requests received to the AJP listener which do not contain the secret, a 403 status code will be returned. You can customize the output of the 403 page via the Error Pages settings.

The AJP secret is implemented via a Server Rule. Feel free to add your own server rule instead of this setting if you want to customize how it works.

equals(%p, 8009) and not equals(%{r,secret}, 'mySecret') -> set-error(403)

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)

 start host=mycoolsite.local

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

 start host=192.168.10.15 port=80

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

 start host=0.0.0.0 port=80

Or save in server.json

server set web.host=mycoolsite.local
server show web.host

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.

server set web.host=mySite.localhost

Turning on SSL in your web server will 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

server set web.SSL.certFile=/path/to/dev_mydomain_ext.crt
server set web.SSL.keyFile=/path/to/dev_mydomain_ext.key
server set web.SSL.keyPass=myPass

The cert file and private key can be a PEM encoded file, or a DER-format binary file.

You can also use a PFX file (PKCS #8) by specifying it in the web.ssl.certFile setting and then put the password for the PFX file in the web.ssl.keyPass setting. You won't use the web.ssl.keyFile setting for a PFX since the private key is contained in the main file.

Generating a Server Cert

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

openssl req -utf8 -nodes -sha256 -newkey rsa:2048 -keyout dev_mydomain_com.key -out dev_mydomain_com.csr

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 are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:NL
State or Province Name (full name) [Some-State]:YourState
Locality Name (eg, city) []:YourCity
Organization Name (eg, company) [Internet Widgits Pty Ltd]:YourCompany
Organizational Unit Name (eg, section) []:IT
Common Name (e.g. server FQDN or YOUR name) []:dev.mydomain.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

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 host name for your site, such as dev.mydomain.com You can skip Email Address 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

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

{
    "web" : {
        "bindings" : {
            // A single binding
            "HTTP" : {},
            // or an array of objects for multiple bindings
            "HTTP" : [],
            
            // A single binding
            "SSL" : {},
            // or an array of objects for multiple bindings
            "SSL" : [],
            
            // A single binding
            "AJP" : {},
            // or an array of objects for multiple bindings
            "AJP" : []
        }
    }
}

Creating a binding

Every binding has

• IP address (can be * or 0.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:

server set web.bindings.HTTP.listen=8080

{
    "web" : {
        "bindings" : {
            "HTTP" : {
                "listen" : "8080"
            }
        }
    }
}

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:

server set web.bindings.HTTP.listen=10.10.0.123:8080

{
    "web" : {
        "bindings" : {
            "HTTP" : {
                "listen" : "10.10.0.123:8080"
            }
        }
    }
}

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.

server set web.bindings.HTTP.IP=10.10.0.123
server set web.bindings.HTTP.port=8080

{
    "web" : {
        "bindings" : {
            "HTTP" : {
                "IP" : "10.10.0.123",
                "port" : "8080"
            }
        }
    }
}

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

{
    "web" : {
        "bindings" : {
            "HTTP" : {
                "listen" : "10.10.0.123:8080",
                "host" : "site.com,site2.net"
                // Or...
                "host" : [
                    "site.com",
                    "site2.net"
                ]
            }
        }
    }
}

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.

{
    "web" : {
        "bindings" : {
            "HTTP" : [
                {
                    "listen" : "10.10.0.123:8080",
                    "host" : "internal-site.com"
                },
                {
                    "listen" : "*:80",
                    "host" : "site.com"
                }
            ]
        }
    }
}

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.

server set web.bindings.ajp.listen=*:8009
server set web.bindings.ajp.secret=my-secret-value

{
    "web" : {
        "bindings" : {
            "AJP" : {
                "listen" : "*:8009",
                "secret" : "my-secret-value"
            }
        }
    }
}

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.

server set web.bindings.SSL.HTTP2Enable=true

{
    "web" : {
        "bindings" : {
            "SSL" : {
                "listen" : "0.0.0.0:443",
                "HTTP2Enable" : true
            }
        }
    }
}

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 file

• keyFile - THe Private key (not used for PFX)

• keyPass - The key pass or PFX pass. Blank if not used

{
    "web" : {
        "bindings" : {
            "SSL" : {
                "listen" : "0.0.0.0:443",
                "certFile" : "../certs/mycert.pem",
                "keyFile" : "../certs/mykey.pem",
                "keyPass" : "my-pass"
            }
        }
    }
}

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.

{
    "web" : {
        "bindings" : {
            "SSL" : {
                "listen" : "0.0.0.0:443",
                "host" : "site1.com,site2.com,site3.com"
                "certs" : [
                    {
                        "certFile" : "../certs/site1Cert.pem",
                        "keyFile" : "../certs/site1Key.pem"
                    },
                    {
                        "certFile" : "../certs/site12Cert.pem",
                        "keyFile" : "../certs/site2Key.pem"
                    },
                    {
                        "certFile" : "../certs/site3Cert.pem",
                        "keyFile" : "../certs/site3Key.pem"
                    }
                ]
            }
        }
    }
}

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

{
  "web" : {
    "bindings" : {
      "ssl" : {
        "listen" : "0.0.0.0:443",
        "clientCert" : {
  	"mode" : "Requested",
  	"CACertFiles" : "rootCA.cer,anotherRootCA.cer",
  	"CATrustStoreFile' : "/path/to/cacerts",
  	"CATrustStorePass' : "changeit"
        }
      }
    }
  }
}

For more information on how to configure and use client certs, check out our guide here.