System Properties and Environment Variables

System Properties and Environment Variables

This documentation shows how to set and use Environment Variables or System Properties to configure specific Lucee Server settings.

1. Introduction

Lucee settings are usually configured manually within the Server Administrator for server-context or in Web Administrator for web-context.

While settings for web-context are also configurable through your web applications Application.cfc (see Application.cfc / <cfapplication>), specific server-context settings can be configured with Environment Variables or System Properties (since Lucee 5.3).

This gives administrators and developers power to tweak server settings from startup without having to configure in the server administrators web interface.

For example, pre-define the extensions to be installed, enable full null support or define charsets for your running Lucee server instance.

2. Naming Notation

On startup Lucee identifies specific Environment Variables or JVM System Properties and uses them for the server setting configuration.

While system environment variable names need to be notated as MACRO_CASE, system property names need to be in dot.notation.

See as an example of variable/property name notation for enabling full null support in the table below:

Use as Notation Example
Environment Variables LUCEE_FULL_NULL_SUPPORT=true (MACRO_CASE)
System Properties lucee.full.null.support=true (dot.notation)

3. Setting The Variables

There are many different ways to make Environment Variables or System Properties available to Lucee depending on how you're running the Lucee server instance.

3.1 How To Set Environment Variables

Find below a brief overview of available options about where and how to set your Environment Variables:

Where Variables availability How to configure
OS (globally) OS (system-wide) Environment variables are configured within your OS configuration. Please refer to the documentation of your OS
OS (user specific) OS (system-wide), but limited to user Environment variables are configured within the OS user's profile configuration. Please refer to the documentation of your OS
Servlet Engine Tomcat Limited to the running servlet instance Option I: Use Tomcats path-to-lucee-installation\tomcat\bin\setenv.bat (Windows) or path-to-lucee-installation\tomcat\bin\setenv.sh (Linux) as specified in Tomcats 9.0 Documentation (see 3.4)
Option II: Run Tomcat with the argument --Environment=key1=value1;key2=... as specified in Tomcat 9 parameters
CommandBox Limited to the running CommandBox instance Since CommandBox 4.5 Environment Variables can be set in a file named ".env". You can easily create the .env file by running the command dotenv set from your CommanBox CLI. For more information please see How to set it up CommandBox with .env files and CommandBox Environment Variables

In the following example we'll follow Tomcat's recommendation and set Environment Variables by using Tomcats setenv.bat/setenv.sh files.

For Windows: Create a batch file at path-to-lucee-installation\tomcat\bin\setenv.bat with the following content:

REM Keep all struct keys defined with "dot notation" in original case.
set "LUCEE_PRESERVE_CASE=true"

REM Enable full null support
set "LUCEE_FULL_NULL_SUPPORT=true"


REM Set Simple whitespace management
set "LUCEE_CFML_WRITER=white-space"

If you have installed Tomcat as service in Windows, the service wrapper launches Java directly without using script files.

In this case you can alternatively add the Environment Variables by running the following Tomcat service update command in a terminal window: path-to-lucee-installation\tomcat\bin\tomcat9.exe //US//NameOfYourTomcatService --Environment=key1=value1;key2=...

For Linux: Create a shell script at path-to-lucee-installation\tomcat\bin\setenv.sh with the following content:

# Keep all struct keys defined with "dot notation" in original case.
LUCEE_PRESERVE_CASE=true

Enable full null support


LUCEE_FULL_NULL_SUPPORT=true


Set Simple whitespace management


LUCEE_CFML_WRITER=white-space

Important: When creating batch/shell script files for Tomcat, please make sure their permissions are correctly set for the user running Tomcat to read and execute them.

3.2 How To Set System Properties

System Properties are specific to the JVM servlet container engine.

Just like Environment Variables they can be configured at different locations.

In this example we will focus on configuring System Properties when running Lucee with Tomcat or CommandBox.

Here is a brief overview.

Configuration for How to configure
Servlet Engine Tomcat Use Tomcats path-to-lucee-installation\tomcat\bin\setenv.bat or path-to-lucee-installation\tomcat\bin\setenv.sh and add the system property using CATALINA_OPTS. See Tomcats 9.0 Documentation (see 3.3)
CommandBox In CommandBox System Properties can be set like Environment Variables in the .env file.

In Tomcat System Properties are passed to the JVM servlet engine Tomcat on startup by populating CATALINA_OPTS with the -D flag, e.g. -Dlucee.full.null.support=true (note that there is no space between the -D flag and the system property key/value).

With Tomcat it's recommended to set CATALINA_OPTS in the setenv.bat/setenv.sh file.

For Windows: Create a batch file at path-to-lucee-installation\tomcat\bin\setenv.bat with the following content:

REM Set System Properties with CATALINA_OPTS
set "CATALINA_OPTS=-Dlucee.full.null.support=true -Dlucee.cfml.writer=white-space -Dlucee.cfml.writer=white-space"

If you have installed Tomcat as service in Windows, the service wrapper launches Java directly without using script files.

In this case you can alternatively add the System Properties in the JAVA tab of Tomcats GUI service editor.

To launch Tomcat GUI service editor, open a terminal window and enter path-to-lucee-installation\tomcat\bin\tomcat9w.exe //ES//NameOfYourTomcatService.

For Linux: Create a shell script at path-to-lucee-installation\tomcat\bin\setenv.sh with the following content:

# Set System Properties with CATALINA_OPTS
CATALINA_OPTS=-Dlucee.full.null.support=true -Dlucee.cfml.writer=white-space -Dlucee.cfml.writer=white-space

Important: When creating batch/shell script files for Tomcat, please make sure their permissions are correctly set for the user running Tomcat to read and execute them.

If you are running Lucee with CommandBox, you can make use of System Properties by saving them to the .env file, just the same way it's done with Environment Variables.

For further information please see How to set it up CommandBox with .env files and CommandBox Environment Variables.

5. Verifying Variables/Properties Passed To Lucee

To make sure the Environment Variables/System Properties are properly being passed to Tomcat/Lucee, you can simply dump these variables from within your web application with cfml as follows:

<cfscript>
writeDump(server.system.environment);
writeDump(server.system.properties);
</cfscript>

6. Security Consideration

When using Environment Variables or System Properties you need to consider important security implications.

This is because the data stored in this sort of variables or files may be accessible by other users sharing the same OS or running servlet engine instance.

Storing sensitive information e.g. hashed passwords, access-tokens, user names, database names, etc on OS or files has to be considered very carefully.

Also, make sure not to publish these files with sensitive data as part of open source code in public repositories.

Environment Variables/System Properties Reference For Lucee Server Settings

Variable/Property Description
LUCEE_ADMIN_ENABLED
lucee.admin.enabled
 Enables/disables access to Lucee Server/Web Administrator. If set to false, Lucee will respond with a 404 http status error for Administrator pages.
Values: Boolean true | false
Default: true

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_EXTENSIONS_INSTALL
lucee.extensions.install

Enables/disables installation of Lucee's default extensions. When this value is changed, it will need a complete redeployment of "lucee-server" (simple restart won't suffice).

This directive is very useful in combination with the system variable LUCEE_EXTENSIONS.

Values: Boolean true | false
Default: true

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_EXTENSIONS
lucee.extensions

Comma separated list of extension GUIDs (Globally Unique Identifiers) to be downloaded and installed during the very first server start.

Setting GUID alone will install latest version.

If you want to dictate version, append ;version=xx.xx.xx.xx to the GUID.

You can find available extensions and their corresponding GUID (these are listed as IDs) in the Server Administrator or at Lucee Downloads.

Values: String

Example: Installing JFreeChart Extension Version 1.0.19.19: 

LUCEE_EXTENSIONS=D46B46A9-A0E3-44E1-D972A04AC3A8DC10;version=1.0.19.19

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_ENABLE_BUNDLE_DOWNLOAD
lucee.enable.bundle.download
 Enables bundle download. Setting it to false makes sure that only bundles shipped with Lucee.jar are installed.
Values: Boolean true | false
Default: true

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_TEMPLATE_CHARSET
lucee.template.charset
 Default charset used to read templates of *.cfm and *.cfc files
Values: String
Default: default OS charset

Lucee Server Administrator:
Settings » Charset » Template charset

Application.cfc: 

// as cfscript
<cfscript>
processingdirective pageEncoding="UTF-8";
</cfscript>
or 
<!--- as cftag --->
<cfprocessingdirective pageEncoding="UTF-8">
LUCEE_WEB_CHARSET
lucee.web.charset
 Default character set for output streams, form-, url-, and cgi scope variables and reading/writing the header.
Values: String
Default: UTF-8

Lucee Server Administrator:
Settings » Charset » Web charset

Application.cfc: 

// Application.cfc
this.charset.web="UTF-8";
LUCEE_RESOURCE_CHARSET
lucee.resource.charset
 Default character set for reading from/writing to various resources.
Values: String
Default: default OS charset

Lucee Server Administrator:
Settings » Charset » Resource charset

Application.cfc: 

// Application.cfc
this.charset.resource="UTF-8";
LUCEE_SCRIPT_PROTECT
lucee.script.protect
 The configuration of Script protect, secures the system from "cross-site scripting" various resources.
Values: String none | all | cgi , url , form , cookie
Default: all

Example: The following directive will set script protection for url and form scope: 

LUCEE_SCRIPT_PROTECT=url,form

Lucee Server Administrator:
Settings » Request » Script-Protect

Application.cfc: 

// as cfscript
<cfscript>
this.scriptProtect="none";
</cfscript>
LUCEE_QUEUE_ENABLE
lucee.queue.enable
 Enables the queue for requests.
Values: Boolean true | false
Default: false

Lucee Server Administrator:
Settings » Request » Concurrent Requests » Enable

Application.cfc: not available

LUCEE_QUEUE_MAX
lucee.queue.max
 The maximum concurrent requests that the engine allows to run at the same time, before the engine begins to queue the requests. This setting needs the queue to be enabled LUCEE_QUEUE_ENABLE=true.
Values: Numeric
Default: 100

Lucee Server Administrator:
Settings » Request » Concurrent Requests » Maximal

Application.cfc: not available

LUCEE_QUEUE_TIMEOUT
lucee.queue.timeout
 The time in milliseconds a request is held in the queue. If the time is reached the request is rejected with an exception. If you have set 0 milliseconds the request timeout is used instead. This setting needs the queue to be enabled LUCEE_QUEUE_ENABLE=true.
Values: Numeric
Default: 0

Lucee Server Administrator:
Settings » Request » Concurrent Requests » Timeout

Application.cfc: not available

LUCEE_CFML_WRITER
lucee.cfml.writer
 Defines whitespace management of the server.
  • regular: No whitespace management.
  • white-space: Simple whitespace management - every whitespace character that follows whitespace is removed.
  • white-space-pref: Smart whitespace management - every whitespace character that follows a whitespace is removed, but whitespace inside the tags: <code>, <pre> and <textarea> is kept
Values: String white-space-pref | regular | white-space
Default: regular

Example: The following directive will set whitespace management to simple: 

LUCEE_CFML_WRITER=white-space

Lucee Server Administrator:
Settings » Output » Whitespace management

Application.cfc: not available

LUCEE_SUPPRESS_WS_BEFORE_ARG
lucee.suppress.ws.before.arg

If set, Lucee suppresses whitespace defined between the <cffunction> starting tag and the last <cfargument> tag.

This setting is ignored when there is a different output between this tags as white space.

Values: Boolean true | false
Default: true

Lucee Server Administrator:
Settings » Language/Compiler » Suppress whitespace before cfargument

Application.cfc: not available

LUCEE_PRESERVE_CASE
lucee.preserve.case

Keep all struct keys defined with "dot notation" in original case.

If set to false, all dot.notated key-names will be converted to UPPERCASE.

Values: Boolean true | false
Default: false

Lucee Server Administrator:
Settings » Language/Compiler » Key case

Application.cfc: 

// as cfscript
<cfscript>
processingdirective preserveCase="true";
</cfscript>
or 
<!--- as cftag --->
<cfprocessingdirective preserveCase="true">
LUCEE_ALLOW_COMPRESSION
lucee.allow.compression
 Enables/disables compression (GZip) for the Lucee Response stream for text-based responses when supported by the client (Web Browser)
Values: Boolean true | false
Default: false

Lucee Server Administrator:
Settings » Output » Compression

Application.cfc: 

//Application.cfc
this.compression = false;
LUCEE_FULL_NULL_SUPPORT
lucee.full.null.support
 Enables/disables full null support, support for null, including "null" literal.
Values: Boolean true | false
Default: false

Lucee Server Administrator:
Settings » Language/Compiler » Null Support

Application.cfc: 

//Application.cfc
this.nullsupport = true;
LUCEE_CASCADE_TO_RESULTSET
lucee.cascade.to.result
 Enables/disables search of available resultsets when variables have no scope defined, e.g. #myVar# instead of #variables.myVar# (CFML Standard)
Values: Boolean true | false
Default: true

Lucee Server Administrator:
Settings » Scope » Search resultset

Application.cfc: 

//Application.cfc
this.searchResults = true;
LUCEE_TYPE_CHECKING
lucee.type.checking
 Enables/disables type definitions checking with function arguments and return values
Values: Boolean true|false
Default: true

Lucee Server Administrator:
Settings » Performance/Caching » UDF Type Checking

Application.cfc: 

//Application.cfc
this.typeChecking = true;

LUCEE_STATUS_CODE
lucee.status.code
 Enables/disables sending 200 http status code in case of an exception. Set the value to false to always send 200 status response code
Values: Boolean true | false
Default: true

Lucee Server Administrator:
Settings » Error » Status code

Application.cfc: not available

LUCEE_S3_SECRETKEY
lucee.s3.secretkey

LUCEE_S3_ACCESSKEYID
lucee.s3.accesskeyid

Defines the default S3 virtual S3 bucket mapping credentials.

Use this to hide AWS S3 credentials from source code or Web Administrator.

That way you connect to your S3 bucket with a S3:///myAwsBucketname/someDirectory/ S3:///myAwsKey:myAwsSecretKey@/myAwsBucketname/someDirectory/. Please see S3

Values: String

Lucee Server Administrator: not available

Application.cfc: 

//Application.cfc
this.s3.accesskeyid = "myAWSaccessID";
this.s3.awssecretkey = "myAWSsecretKey";
LUCEE_UPLOAD_BLOCKLIST
lucee.upload.blocklist

Defines a comma separated list of file extensions that are not allowed to be uploaded.

By default Lucee will block a set of files that have potential risk. Use this setting to have more control over Lucees default settings.

Values: String
Default: asp,aspx,cfc,cfm,cfml,do,htm,html,jsp,jspx,php

Example: The following directive won't allow the upload of the following files: 

LUCEE_UPLOAD_BLOCKLIST=asp,aspx,cfc,cfm,cfml,do,htm,html,jsp,jspx,php

Lucee Server Administrator: not available

Application.cfc: 

//Application.cfc
this.blockedExtForFileUpload="asp,aspx,cfc,cfm,cfml,do,htm,html,jsp,jspx,php"

LUCEE_BASE_DIR
lucee.base.dir
Defines the base directory location for the server engine.
Values: String

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_SERVER_DIR
lucee.server.dir

Defines the directory location where Lucee should create the server context.

By default Lucee places its server context in the servlet engines directory.

Use this to move the server context outside the Lucee installation dir. This directive is the same as the init param lucee-server-directory of path-to-lucee-installation\tomcat\conf\web.xml

Values: String

Example: Moving web contexts to another location: 

set "LUCEE_SERVER_DIR="/var/another-location/server/"

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_WEB_DIR
lucee.web.dir
Defines the directory location where Lucee should create the web contexts.

By default Lucee places its web-context configuration and data files in a folder named WEB-INF under the webroot of each website.

Use this to move the web context outside of the websites webroot.

This directive is the same as the init param lucee-web-directory of path-to-lucee-installation\tomcat\conf\web.xml.

When using this directive you'll need to add Lucees label variable {web-context-label} to the path that will be used as the identifier hash or label for the created web contexts.

Values: String

Example: Moving web contexts to another location: 

set "LUCEE_WEB_DIR="/var/another-location/web/{web-context-label}/"

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_ENABLE_DIALECT
lucee.enable.dialect
Enables/disables the experimental Lucee dialect
Values: String
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_FELIX_LOG_LEVEL
lucee.felix.log.level
Sets log level for Felix
Values: String error | warning |info | debug
Default: error

Lucee Server Administrator: not available

Application.cfc:
not available

LUCEE_CONTROLLER_DISABLED
lucee.controller.disabled
Disables the controller. Default is false.

The Controller is an internal background process which runs maintenance tasks.

On Startup
  • Syncing NTP time
  • Clearing out temp files
  • Clearing out cache files
  • Clearing out expired scopes like sessions (in persistent storage)
Every Minute
  • Automatically deploying updates / extensions Deploying Lucee
  • Clearing out unused DB connections
  • Clearing out expired scopes like sessions
  • Clearing out pagePools
  • Checking mappings
  • Clearing out mail server connections
  • Clearing out locks
  • Picking up changed configuration files
Every Hour
  • Syncing NTP time
  • Clearing out temp files
  • Clearing out cache files
Values: Boolean true | false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_CONTROLLER_INTERVALL
lucee.controller.intervall

Number of milliseconds between controller calls.

Set to 0 to disable controller. Useful for benchmark testing.

Values: Numeric

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_LISTENER_TYPE
lucee.listener.type
 Sets how requests are handled and which templates are invoked by default.
  • None: When a request is called no other initialization template will be invoked by Lucee.
  • classic: Classic handling (CFML < 7). Lucee looks for the file Application.cfm and a corresponding file OnRequestEnd.cfm
  • modern: Modern handling. Lucee only looks for the file Application.cfc
  • mixed: Mixed handling. Lucee looks for a file Application.cfm / OnRequestEnd.cfm as well as for the file Application.cfc
Values: String none | classic | modern | mixed
Default: mixed

Lucee Server Administrator:
Settings » Request » Application listener » Type

Application.cfc: not available

LUCEE_LISTENER_MODE
lucee.listener.mode

Defines where Lucee looks for the files Application.cfc / Application.cfm.

Note: In case of having LUCEE_LISTENER_TYPE set to none the setting for LUCEE_LISTENER_MODE is ignored.

  • curr2root: Looks for the file Application.cfc / Application.cfm from the current up to the webroot directory.
  • currOrRoot: Looks for the file Application.cfc / Application.cfm in the current directory and in the webroot directory.
  • root: Looks for the file Application.cfc / Application.cfm only in the webroot .
  • curr: Looks for the file Application.cfc / Application.cfm only in the current template directory.
Values: String curr2root | currOrRoot | root | curr
Default: curr2root

Lucee Server Administrator:
Settings » Request » Application listener » Mode

Application.cfc: not available

LUCEE_QOQ_HSQLDB_DISABLE
lucee.qoq.hsqldb.disable
 Throw exception if native QoQ logic fails, otherwise Lucee falls back to using HSQLDB (which is needed for joins etc), Default is false.
http://wwvv.codersrevolution.com/blog/improving-lucees-query-of-query-support
Values: Boolean true | false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_QOQ_HSQLDB_DEBUG
lucee.qoq.hsqldb.debug

Log message to WEB context's datasource log any time a QoQ "falls back" to HyperSQL.

This could include just bad SQL syntax. Default is false.

Values: Boolean true|false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_MAPPING_FIRST
lucee.mapping.first

Changes Lucee default behaviour of using existing physical paths over virtually mapped paths with the same mapped name (conflicting situation).

Set this value to true to change Lucees default behaviour and force Lucee to use mappings as first priority and silently ignore conflicting physical paths.

Example: 
// Assumption:
// "D:/myimages/abc" is a physical valid location

// Defined mappings
mappings[ '/' ] = 'D:/';
mappings[ '/myimages' ] = 'D:/images';

// Default Lucee:
// the following writeDump outputs "D:/myimages/abc"
writeDump( expandPath( '/myimages/abc' );

// If LUCEE_MAPPING_FIRST=true:
// the following writeDump outputs "D:/images/abc"
writeDump( expandPath( '/myimages/abc' );

Values: Boolean true|false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_LOG_REFLECTION
lucee.log.reflection

Enables logging on reflection calls.

Values: Boolean true|false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_ENABLE_WARMUP
lucee.enable.warmup

Enables warming up a Lucee instance.

When enabled, Lucee will startup, deploy itself, creating the required directories, deploying any configured extensions and then exiting.

It enables a faster startup for the deployment of Docker images, Kubernetes clusters and blue/green environments for example.

Values: Boolean true|false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

LUCEE_USE_LUCEE_SSL_TRUSTSTORE
lucee.use.lucee.SSL.TrustStore

Enables the certificate authority truststore in Lucee location, instead by the JVM default truststore location.

Previous to Lucee 6.0 Lucee served its own SSL truststore. From 6.0 the truststore is set by the JVM default truststore location.

Enabling this setting will tell Lucee to use its own truststore, behaving as prior to Lucee 6.0.

Values: Boolean true|false
Default: false

Lucee Server Administrator: not available

Application.cfc: not available

See also