Setting System Properties and Environment Variables

Setting System Properties and Environment Variables

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

Refer to Environment Variables / System Properties for Lucee for the full list of available 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 allowe 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 Considerations

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.

See also