You can customize the Liberty
environment by using certain specific variables to support the placement of product binary files and
shared resources in read-only file systems.
About this task
The Liberty specific environment variables
in the following list can be configured in the server.env file to customize the
Liberty environment. The
${wlp.install.dir} configuration variable has an inferred location that is always
set to the parent of the directory that contains the launch script.
- WLP_USER_DIR
This environment variable can be used to specify an alternative
location for ${wlp.user.dir}. This variable must be an absolute path. If this
variable is specified, the runtime environment looks for shared resources and server definitions in
the specified directory. The ${server.config.dir} is equivalent to
${wlp.user.dir}/servers/serverName. If this environment
variable is not specified, ${wlp.user.dir} is set to
${wlp.install.dir}/usr.
- WLP_OUTPUT_DIR
This environment variable can be used to specify an
alternative location for server generated output such as logs, the workarea
directory, and generated files. Files in the logs directory can include
console.log, messages.log, and any generated FFDC files.
Generated files can include server dumps that are created with the server dump or
server javadump command. This variable must be an absolute path. If this
environment variable is specified, ${server.output.dir} is set to the equivalent of
WLP_OUTPUT_DIR/serverName. If this environment variable is not
specified, ${server.output.dir} is the same as
${server.config.dir}.
When the server command is used, the server process
uses the output directory as its current working directory.
- WLP_ZOS_PROCEDURE
This environment variable can be used to specify the name of an STC procedure to be used to start the server as a z/OS® started task rather than as a UNIX System Services background process. By default, the command port remains enabled to allow continued administration of the server from the server script. Optionally, the command port can be manually disabled restricting server administration to just the z/OS operator console, see Specifying Liberty bootstrap properties.
-
WLP_ZOS_JOBNAME
This environment variable can be used in addition to the
WLP_ZOS_PROCEDURE variable to specify a job name for the Liberty server that was started as a z/OS started task.
- WLP_DEBUG_ADDRESS
This environment variable can be used to specify an
alternative port when you run the server in debug mode. The default value is 7777. When Liberty is run in debug mode from the server
command, the following values are set JAVA_DEBUG="-Dwas.debug.mode=true
-Dcom.ibm.websphere.ras.inject.at.transform=true
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=${WLP_DEBUG_ADDRESS}". If
however, you run Liberty from the
ws-server.jar executable JAR file, or the embedded Liberty server SPI, then you must use the same
settings to enable debug mode for Liberty.
You can specify WLP_OUTPUT_DIR, WLP_USER_DIR, and
WLP_DEBUG_ADDRESS environment variables in server.env files.
You can also specify JVM options in jvm.options files. Both
server.env and jvm.options files work only when you use
the server management script. If you use the ws-server.jar executable JAR file to
launch your server, these files are not supported.
Procedure
- Specify environment variables by using server.env files.
You can use
server.env files at the installation and server levels to
specify environment variables such as
JAVA_HOME,
WLP_USER_DIR, and
WLP_OUTPUT_DIR. For example:
# Use a specific Java binary
JAVA_HOME=/opt/ibm/java-i386-60/jre
# JAVA_HOME=c:\Java
Note: - The server.env files support only key=value pairs.
- Empty lines and lines that start with the # character are ignored.
- There are no escape characters; all characters are literal, including back-slashes and leading
and trailing white space.
- There should be no white space surrounding the equals "=" sign.
- Shell and variable expansion are not supported.
- WLP_USER_DIR can be specified only in the
${wlp.install.dir}/etc/server.env file because the purpose of this variable is
to specify where the remaining configuration is located. After the remaining configuration is found
and merged, no further configuration in a different location is expected, or supported.
The server management script searches for server.env files in two locations:
${wlp.install.dir}/etc/server.env and
${server.config.dir}/server.env. If both files are present,
the contents of the two files are merged; values in the server-level file take precedence over
values in the runtime-level file.
You can also specify these environment variables in the shell environment, but the
server.env files take precedence over those variables.
- Customize JVM options by using jvm.options files.
You can use
jvm.options files at the runtime and server levels to specify
more server startup options, for example,
-X arguments. The options are applied
when the start, run, and debug actions are started through the server management script. Be sure to
specify only one option per line. For
example:
# Set the maximum heap size to 1024m.
-Xmx1024m
# Set a system property.
-Dcom.ibm.example.system.property=ExampleValue
# Enable verbose output for class loading.
-verbose:class
# Enable verbose garbage collection.
-verbose:gc
# Specify an alternate verbose garbage collection log on IBM Java Virtual Machines only.
-Xverbosegclog:verbosegc.log
# Specify additional verbose garbage collection options on HotSpot Java Virtual Machines only.
-Xloggc:verbosegc.log
-XX:+PrintGCDetails
-XX:+PrintGCTimeStamps
-XX:+PrintHeapAtGC
![[16.0.0.4 and later]](../ng_v16004plus.gif)
You can create multiple
jvm.options files in the following locations:
- ${wlp.install.dir}/usr/shared/jvm.options
- ${server.config.dir}/configDropins/defaults/jvm.options
- ${server.config.dir}/jvm.options
- ${server.config.dir}/configDropins/overrides/jvm.options
These files are merged in order from top to bottom before server start and are used as the JVM
options for the server. If none of these files are present, then
${wlp.install.dir}/etc/jvm.options is read.
Note: - Do not put property values in quotation marks.
- Empty lines and lines that start with the # character are ignored.
- There are no escape characters; all characters are literal, including back-slashes and leading
and trailing white space.
- There should be no white space surrounding the equals "=" sign.
- Shell and variable expansion are not supported.
What to do next
If you start the Liberty server by using
the server script, all of the operating system environment variables from the current session are
available. If you start the server by using either the MBean or the Admin Center, the only available environment variables are
those variables that are available to a remote command that is running on that system.