Overview

ColdFusion offers both Administrator interface to view and change server settings, and a car wizard to bundle settings from one instance and then deploy in another instance after logging into its admin.

CFSetup is a command line utility to manage ColdFusion settings. You can use CFSetup, among others, to:

  1. Configure (read/write) ColdFusion Settings in ColdFusion Administrator
  2. Export and import settings from/to different ColdFusion instances.*

* You can however use the CAR wizard to migrate the settings and the relevant files.

In CFSetup, settings are grouped into relevant categories. The categories are listed below:

  • Caching
  • Chart
  • Cloudconfiguration
  • Cloudcredential
  • Com
  • Customtag
  • Datasource
  • Debug
  • Document
  • Dotnet
  • Eventgatewayinstance
  • Eventgatewaysetting
  • Eventgatewaytype
  • Idpconfiguration
  • Jvm
  • Logging
  • Mail
  • Mapping
  • Metric
  • NoSQL
  • Pdfservice
  • Probe
  • Probeconfig
  • Rest
  • Runtime
  • Scheduletask
  • Security
  • Server
  • Solr
  • Spconfiguration
  • Watch
  • Webservice
  • Websocket

Since CFSetup interacts directly with the config files, you need not have ColdFusion server up and running.

Restart ColdFusion server after changing a setting to get the setting reflected in the Administrator.

Terminology

Term Description
Alias An alias is shortcut or a substitute for the path of a ColdFusion instance. For example, instanceOne for C:\ColdFusion2021\cfusion is the alias for the instance C:\ColdFusion2021\cfusion.
Setting key In CFSetup, all settings are assigned a unique key, which is called a setting key. Every setting belongs to a particular category.
Setting value Denotes the value of the setting key.
Service

There are categories where every setting key-setting value pair belongs to a specific service. 

For example, in the category datasource, the service name id datasource name. There could be multiple datasource names in the category with each datasource name having its own host, port, etc.

Get started with CFSetup

The CFSetup tool is located in /coldfusion/config/cfsetup.

Start CFSetup

The CFSetup tool is located in /coldfusion/config/cfsetup.

You can start CFSetup using one of the following three ways:

Terminal mode

To start CFSetup, execute cfsetup.bat/cfsetup.sh in the command line:

<CF_HOME>/config/cfsetup>cfsetup.bat

After you hit Enter, the CFSetup tool starts.

Note:

In a JEE setup, CFSetup is located in cfusion.war\WEB-INF\config\cfsetup.

Help command

The Help command retrieves help for any category. For example,

  1. List all commands using help.
  2. View the usage of a command for a category. For example,  help add datasource.

Enter help in the prompt and see the syntax for all commands in CFSetup.

List of commands
List of commands

Usage

Action

Command

See usage of any command

help <command>

Get information about setting key of any category

help <category>

Get information of any setting key of a category

help <category> <keyName>

Get help on adding an instance of any category

help add <category>

List attributes of a category help <category>

Alias

An alias is shortcut or a substiture for the path of a ColdFusion instance.

Create an alias

cfsetup>alias <alias_name> <ColdFusion_Home>

For example,

cfsetup>alias firstAlias C:\ColdFusion2021\cfusion

Delete an alias

cfsetup>alias -d  <alias_name>

For example,

cfsetup> alias -d firstAlias

Use an alias

You can use an alias in the following ways:

  1. Use the alias as suffix. For example, cfsetup>show chart firstAlias
  2. Select an alias. For example, cfsetup>select  <alias_name> 

After selecting alias, if you do not specify the the alias suffix in the command, it will be executed for the selected alias.

For example, cfsetup>show chart

You can select the alias that you'd created so that you need not specify the cfusion path in each command.

Usage

Command type Command
Register an alias cfsetup>alias <alias_name> <ColdFusion_Home>
Delete an alias cfsetup>alias <alias_name> -d
Select an alias cfsetup>select <alias_name>
Deselect an alias

cfsetup>deselect <alias_name>

If you are already using an alias, then use the command:

cfsetup:alias_name>deselect

Show all aliases cfsetup>show alias
Create an alias
Create an alias

Alias as suffix

You can also specify an alias as suffix to accomplish a task. For example,

show <setting> <alias_name>

Display settings
Display settings

Manage ColdFusion settings

Show all settings

Show all settings of a category for an instance. Also use the show command to list all categories.

cfsetup>show category

Show settings of a category

Show all settings of a category of an instance. 

cfsetup>show <category_name> <alias>

For example,

show-category

Get settings of a category

Use this get command to get the value of a settting of any category for an instance. 

To retrieve a configuration setting, use the command:

cfsetup>get <category> <settingKey> <aliasName>

For example,

cfsetup:aliasOne>get runtime sessionStorage sessionStorageHost sessionStoragePort sessionStoragePassword sessionStorageTimeout aliasOne

Get configuration settings
Get configuration settings

Set settings of a category

To set a configuration of a category, use the command:

cfsetup>set category <settingKey=settingValue> <aliasName>

For example,

cfsetup:aliasOne>set watch extensions=xml interval=120 watchenabled=false aliasOne

Set configuration settings
Set configuration settings

Add an instance of a category

You can add instances of a category.

cfsetup>add <category> setting1=<value> setting2=<value>.....settingn=<value>

For example, to add values to the category pdfservice, enter the command. Replace the requiter values.

cfsetup>add pdfservice hostname=<host> isenabled=<true|false> ishttps= <true|false> islocal= <true|false> name=<host> port=<port> weight=<weight>

Delete an instance of a category

You can delete instances of a category.

cfsetup>delete <category> setting1 <value> setting2 <value>.....settingn <value>

For example, to add the Service Configuration name to the category spconfiguration, enter the command.

cfsetup>delete spconfiguration spName

Export a category to json file

Export a single category

To export settings of a category, use the command:

cfsetup>export <category> <json_file> <cf_home>|<alias>

For example,

cfsetup>export websocket ws.json

If the json already exists, you can replace the old file.

While exporting, you must also password protect the file. You will be asked to provide a passphrase.

Export all settings
Export all settings

Export multiple categories

Export multiple categories
Export multiple categories

Export all categories

Export all categories and their properties to a json file.

cfsetup>export all <json_file> <alias>|<cf_home>

For example,

cfsetup>export all all-cat.json

While exporting, you must also password protect the file. You will be asked to provide a passphrase.

Note: When migrating settings from one machine to another, install the tools first, like, OpenOffice, before exporting all settings of categories, for example, dotnet,solr, document, and so on. Export the settings first and then the tool will ingest the settings. Update the path as required.

Export all categories
Export all categories

Import a category from a json file

Note:

While performing import operations for the categories that include file paths, you may have to update the file paths in the exported json file. The file paths must be relative to the server on which you want to perform the import operation.

Import a single category

To import settings of a category from a json file, use the command:

cfsetup>import <category> <jsonfile> <cfhome>|<alias>

For example,

cfsetup>import websocket ws.json aliasOne

While importing, you must provide the passphrase, which you'd set earlier.

Import a single category
Import a single category

Import multiple categories

Import multiple categories
Import multiple categories

The backup files, during importing, are located in the server you'd performed the import command. The location is:

ColdFusion_Home/cfusion/lib/cfsetup_backup

Import all categories

Import all categories and their properties to a json file.

cfsetup>import all <json_file> <alias>|<cf_home>

For example,

cfsetup>import all all-cat.json

While importing, you must also specify the passphrase that you'd set earlier while exporting.

Docker

To import a setting into a ColdFusion Docker image, you can specify the exported json.

importCFSettings=all_doc.json  importCFSettingsPassphrase=testpassword

Where,

  • importCFSettings=<A JSON file containing the CF Settings to be imported . Must be present in the webroot, /app>   
  • importCFSettingsPassphrase=<Passphrase to import CF settings from an encrypted JSON file.>

Non-interactive mode

Using the non-interactive mode, you can perform all configuration-related functions without entering the CFSetup environment explicitly.

To use the non-interactive mode, go to the location /ColdFusion/config/cfsetup, and start a command or terminal mode.

Then run any command using the syntax below:

/ColdFusion/config/setup>cfsetup.bat <command>

For example, to display chart settings in an alias,

CFSetup in a non-interactive mode
CFSetup in a non-interactive mode

To modify a setting, use the command, as shown below:

CFSetup in a non-interactive mode
CFSetup in a non-interactive mode

To view the modified settings, use the command below:

CFSetup in a non-interactive mode
CFSetup in a non-interactive mode

Script mode

In addition to the non-interactive mode, you can define a sequence of commands in a batch file. With this approach, you can set up your automation pipeline, and manage configuration settings in a more structured manner.

For example, create a batch file, mycommands.bat, that contains the following commands:

@echo off

call cfsetup.bat show chart C:\cf09Sep\ColdFusion\cfusion

call cfsetup.bat set chart maximumCachedImages=40 C:\cf09Sep\ColdFusion\cfusion

call cfsetup.bat get chart maximumCachedImages C:\cf09Sep\ColdFusion\cfusion

Then, on the console, run the command as shown below:

Run CFSetup as script
Run CFSetup as script

Change password

For changing the password for admin/rds/jetty, enter the following command:

set security admin=testpassword jetty=testpassword rds=testpassword cfusion

The password will be effective once you restart the server.

CFSetup in standalone mode

showYou can use CFSetup in the standalone mode as well, which works in the same way as CFSetup in the modes explained above. Download cfsetup-standalone.zip and unzip its contents.

The ColdFusion server need not be up and running.

Note: On non-Windows platforms, in cfstart.sh file,  you must specify the runtime user manually.

The runtime user must always be the same as the ColdFusion runtime user.

Note:

The cfsetup folder and its sub-folders need to have the same file permissions as the runtime user.

Examples

Add configuration settings

Here are a few examples.

Category Command
Webservice add webservice name=ws authtype=<authtype> url=<url_wsdl>
EventGatewayType add eventgatewaytype type=<type> class=<class> description=<description> startTimeout=<timeOut> killOnTimeout=<true|false>
EventGatewayInstance
add eventgatewayinstance configurationpath=<path> cfcpath=<cfc_path> type=<type> gatewayid=<id> mode=<mode>
Solr add solr language name=<name> suffix=<suffix>
REST add rest mapping=<mapping> isdefault=<false|true> host=<host> rootpath=<rootpath>
PDFService
add pdfservice hostname=<host> isenabled=<true|false> ishttps= <true|false> islocal= <true|false> name=<host> port=<port> weight=<weight>
JVM add jvm jvmargs="--add-opens=java.base/java.nio=ALL-UNNAMED"
Cloud credentials add cloudcredential vendorName=AWS|AZURE accessKeyId=SomeAccessKeyId secretAccessKey=SomeSecretKey region=SomeRegion alias=myAliasForCloudCredential
Cloud configuration
  • add cloudconfiguration serviceName=DYNAMODB alias=configAlias maxConnections=50 connectionMaxIdleTime=10s socketTimeout=10s connectionTimeout=10s connectionTimeToLive=10s connectionAcquisitionTimeout=10s numRetries=5 apiCallAttemptTimeout=2s
  • add cloudcredential vendorName=AWS accessKeyId=SomeAccessKeyId secretAccessKey=SomeSecretKey region=ap-south-1 alias=cloudcred1
SAML SP
  • add spconfiguration name=spName description="sp description" entityid=abc acsbinding="HTTP POST" acsurl=http://localhost:8500/acsurl.cfm
  • add spconfiguration name=spName_all description="sp description3" entityid=abc3 acsbinding="HTTP POST" acsurl=http://localhost:8500/acsurl.cfm generated=false logoutresponsesigned=true signkeystorealias=signing signkeystorepassword=<password> signkeystorepath=C:\ColdFusion\cfusion\lib\saml\key.p12 signmetadata=false signrequests=true slobinding="HTTP POST" slourl=http://localhost:8500/slobinding.cfm wantassertionssigned=true
SAML IDP
  • add idpconfiguration name=idpName description="desc" metadataurl="https://dev-980666.okta.com/app/exk2tr0cdmKwWOEGe357/sso/saml/metadata"
  • add idpconfiguration name=idp_all description="desc" entityid="http://entity-id-url/" ssourl="https://sso-url/sso/saml" slourl="https://slo-url/slo/saml" ssobinding="http-post" slobinding="http-post" signRequests=true encryptRequests=true signcertificate="abcd" encryptcertificate="abcd"
  • add idpconfiguration name=idp_all_1 description="desc" entityid="http://entity-id-url/" ssourl="https://sso-url/sso/saml" slourl="https://slo-url/slo/saml" ssobinding="http-redirect" slobinding="http-redirect" signRequests=true encryptRequests=true signcertificate="abcd" encryptcertificate="abcd"
  • add idpconfiguration name=idp1 description="desc" metadataFilePath="C:/metadata.xml" cfusion
  • add idpconfiguration name=idp2 description="desc" metadataRaw="MIIDpDCCAoygAwIBAgIGAW3ZMbcZMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG" cfusion
NoSQL datasource
  • add nosql name=testset mongoport=27017 mongoHost=host driverName=MONGODB maxStalenessSeconds=2000 MAXWAITQUEUETIMEOUT=2000 MAXWAITQUEUESIZE=10 MAXPOOLSIZE=20 MAXCONNECTIONLIFETIME=2000 HEARTBEATFREQUENCY=10  MAXCONNECTIONIDLETIME=2000 MINHEARTBEATFREQUENCY=2 CONNECTTIMEOUT=2000 READPREFERENCE=PRIMARY SSL=YES  REPLICASET=replica READCONCERN=majority 
  • add datasource name=mysql1 driver=MySQL5 host=database-2.cncsotwo7vlg.us-east-2.rds.amazonaws.com port=3306 database=Regression_dbo username=admin password=Pa$$w0rd
Probe add probe url="http://localhost/hellocf.cfm" start_time="08:00:00 AM" interval=3000 name="probe1"

Set a configuration setting

Here are a few exmples.

Category Command
Webservice set webservice ws ntlmdomain=<ntlmdomain> password=<password> proxyport=80 proxyusername=<proxyusername> workstation=<workstationname> url=http://host:port/basic.cfc?wsdl proxyserver=<proxyserver> proxypassword=<proxypassword> timeout=0.0 username=<username> authtype=ntlm
EventGatewayType
set eventgatewaytype CFML type=<type> class= <description>  description=<description> startTimeout=<timeOut> killOnTimeout= <true|false>
EventGatewaySetting
set eventgatewaysetting jigid=<jigid> maxqueuesize=<queue_size> threadPoolsize=1.0 enableeventgatewayservice=false
EventGatewayInstance
  • set eventgatewayinstance test configurationpath= <path_configuration>
  • set eventgatewayinstance test cfcpath= <path_cfc>
Solr set solr solrwebapp=<app> port=<port> host=<localhost> solrbuffersize=<buffer_size> solrhome=<SOLR_home> multicore httpsenabled=<true|false> username=<admin> password=<admin>
REST set rest <app_path> isdefault=<false|true> host=<localhost> rootpath= <rootpath>
Document
  • set document local docpath=<path_document>
  • set document remote dochost=<host>
  • set document remote docport=<port>
PDFService set pdfservice hostname= <host> isenabled=<true|false> ishttps= <true|false> islocal= <true|false> name=<host> port=<port> weight=<weight>
Websocket
  • set websocket websocketport=8584
  • set websocket websocket_clustered=<true|false>
JVM set jvm maxheapsize=1024m minheapsize=512m
Caching

Redis

  • set caching rediscachestoragehost=10.192.217.233 rediscachestorageport=6383 rediscachestoragepassword=xxxxx sessionStorageCluster=false serverCacheType=REDIS redis.eternal=true redis.maxelementsinmemory=3999 redis.timetoidleseconds=5000 redis.timetoliveseconds=3000

Memcached

  • set caching serverCacheType=Memcached MemcachedServer=server1,server2 memcached.eternal=true memcached.maxelementsinmemory=3999 memcached.timetoidleseconds=5000 memcached.timetoliveseconds=3000

JCS

  • set caching serverCacheType=JCS jcs.eternal=true jcs.maxelementsinmemory=3999 jcs.timetoidleseconds=5000 jcs.timetoliveseconds=3000

Other settings

  • set caching templateCacheSize=516 trustedCacheEnabled=true inRequestTemplateCacheEnabled=false componentCacheEnabled=false saveClassFiles=false cacheWebServerPath=true enableInternalQueryCache=true
Runtime
  • set runtime timeoutrequests=true timeoutrequesttimelimit=60 isperappsettingsenabled=true enablehttpstatus=TRUE cfctypecheckenabled=true disableservicefactory=false preservecaseforserialize=false securejsonprefix=""//"" securejson=false maxoutputbuffersize=1024 enableinmemoryfilesystem=true inmemoryfilesystemlimit=100 inmemoryfilesystemapplimit=20 allowextraattributesinattrcoll=true dumpunnamedappscope=false allowappvarincontext=false cfaasgeneratedfilesexpirytime=30 servercfc=Server enableservercfc=false enablenullsupport=false usejavaasregexengine=false compileextforinclude=""*"" blockedextforfileupload=""AS,ASP,ASPX,BIN,DMG,CFC,CFM,CFML,CFR,CFSWF,EXE,HBXML,JSP,JSPX,JWS,MXML,PHP,SWC,SWS"" applicationcfcsearchlimit=""DEFAULT ORDER"" corepoolsize=25 maxpoolsize=50 keepalivetime=2000 postparameterslimit=100 postsizelimit=20 throttle-threshold=4 total-throttle-memory=200 allowrestdiscovery=false servermobilecontext=cfmobile cfusion
Cloud credentials
  • set cloudcredential myAliasForCloudCredential accessKeyId=newAccessKeyId
  • set cloudcredential myAliasForCloudCredential secretAccessKey=newSecretAccessKey
  • set cloudcredential myAliasForCloudCredential region=SomeRegion
Cloud configuration
  • set cloudconfiguration configAlias maxconnections=40
  • set cloudconfiguration configAlias maxconnections=40 numRetries=6
SAML SP
  • set spconfiguration spName description="sp description1"
  • set spconfiguration spName description="sp description3" entityid=abc3 acsbinding="HTTP POST" acsurl=http://localhost:8500/acsurl.cfm generated=false logoutresponsesigned=true signkeystorealias=signing signkeystorepassword=<password> signkeystorepath=C:\ColdFusion\cfusion\lib\saml\key.p12 signmetadata=false signrequests=true slobinding="HTTP POST" slourl=http://localhost:8500/slobinding.cfm wantassertionssigned=true
SAML IDP

set idpconfiguration idpName metadataurl="https://metadata-url/sso/saml"

NoSQL Datasource set nosql testcfsetup mongoPort=27001
Probe set probe <probename> enabled=0 file="checkbak.log" overwrite=false

Get a configuration setting

Here are a few settings.

Category Command
Webservice
  • get webservice test ntlmdomain
  • get webservice test password
  • get webservice test proxyport
EventGatewayType
  • get eventgatewaytype CFML type
  • get eventgatewaytype CFML class
EventGatewayInstance
  • get eventgatewayinstance test configurationpath
  • get eventgatewayinstance test cfcpath

Solr

  • get solr solrwebapp
  • get solr port
REST
  • get rest <app_path> mapping
  • get rest <app_path> isdefault
Document
  • get document local docpath
  • get document remote dochost
  • get document remote docport
PDFService
  • get pdfservice localhost hostname
  • get pdfservice localhost isenabled
  • get pdfservice localhost ishttps
Websocket

get websocket websocket_clustered

Runtime
  • get runtime timeoutrequests timeoutrequesttimelimit isperappsettingsenabled  enablehttpstatus  cfctypecheckenabled disableservicefactory preservecaseforserialize securejsonprefix securejson maxoutputbuffersize enableinmemoryfilesystem inmemoryfilesystemlimit inmemoryfilesystemapplimit allowextraattributesinattrcoll dumpunnamedappscope allowappvarincontext cfaasgeneratedfilesexpirytime ormsearchindexdirectory cfformscriptsrc googlemapkey servercfc enableservercfc enablenullsupport usejavaasregexengine compileextforinclude blockedextforfileupload applicationcfcsearchlimit corepoolsize maxpoolsize keepalivetime missing_template site_wide postparameterslimit postsizelimit throttle-threshold total-throttle-memory allowrestdiscovery mobilekey servermobilecontext cfusion
Cloud credentials
  • get cloudcredential myAliasForCloudCredential vendorName
  • get cloudcredential myAliasForCloudCredential accessKeyId
  • get cloudcredential myAliasForCloudCredential secretAccessKey
  • get cloudcredential myAliasForCloudCredential region
  • get cloudcredential myAliasForCloudCredential alias
Cloud configuration
  • get cloudconfiguration configAlias serviceName
  • get cloudconfiguration configAlias serviceName maxconnections
  • get cloudconfiguration configAlias maxconnections

Note: You must specify the timeout values suffixed with the appropriate unit when configuring a cloud configuration.

SAML SP
  • get spconfiguration spName name
  • get spconfiguration spName name description
  • SAML IDP
  • get idpconfiguration idpName name
  • get idpconfiguration idpName name metadataurl
NoSQL Datasource
  • get nosql test2
  • get nosql test2 mongoHost

Delete an instance of a category

Here are a few examples.

To specify values separated by space, pass the value inside quotes.

Category Command
Webservice delete webservice test
EventGatewayType
delete eventgatewaytype CFML
EventGatewayInstance

delete eventgatewayinstance test

Solr delete solr language test
REST delete rest <app_path>
JVM delete jvm "--add-opens=java.base/java.nio=ALL-UNNAMED"
Cloud credentials

delete cloudcredential myAliasForCloudCredential

Cloud configuration

delete cloudconfiguration configAlias

SAML SP

delete spconfiguration spName

SAML IDP

delete idpconfiguration idpName

NoSQL Datasource delete nosql mongo2

Display a configuration setting

Category Command
Webservice
  • show webservice
  • show webservice test
EventGatewayType
  • show eventgatewaytype
  • show eventgatewaytype CFML
EventGatewayInstance
  • show eventgatewayinstance
  • show eventgatewayinstance test
EventGatewaySetting
show eventgatewaysetting
Solr show solr
REST
  • show rest
  • show rest <app_path>
PDFService
  • show pdfservice cfusion
  • show pdfservice localhost cfusion
Document show document
Websocket show websocket
Caching show caching
Cloud credentials
  • show cloudcredential
  • show cloudcredential myAliasForCloudCredential
Cloud configuration
  • show cloudconfiguration
  • show cloudconfiguration configAlias
SAML SP
  • show spconfiguration
  • show spconfiguration spName
SAML IDP
  • show idpconfiguration
  • show idpconfiguration idpName
NoSQL datasource
  • show nosql
  • show nosql mongo2
Probe
  • show probe
  • show probe <probename>

Limitations

In this version of CFSetup, you cannot add these cloud configuration settings- apiCallTimeout, retry conditions, and Proxy settings.