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.