Customize the Liberty profile environment

Liberty profile environment variables can be configured in server.env. The ${wlp.install.dir} configuration variable is set to the parent of the directory containing the launch script.

• WLP_USER_DIR

  Alternative location for ${wlp.user.dir}. Must be absolute path. The runtime looks for shared resources and server definitions in the specified directory. ${server.config.dir} is equivalent to ${wlp.user.dir}/servers/serverName. If not set, ${wlp.user.dir} is set to ${wlp.install.dir}/usr.

• WLP_OUTPUT_DIR

  Alternative location for server generated output such as logs, the workarea directory, and generated files. Files in logs directory include console.log, messages.log, and FFDCfiles. Generated files can include server dumps created with the server dump or server javadump command. Must be absolute path. If set, ${server.output.dir} is set to the equivalent of WLP_OUTPUT_DIR/serverName. If not set, ${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_DEBUG_ADDRESS

  Alternative port when running 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 we run Liberty from the ws-server.jar executable JAR file, or the embedded Liberty server SPI, use the same settings to enable debug mode.

We can specify WLP_OUTPUT_DIR, WLP_USER_DIR, and WLP_DEBUG_ADDRESS environment variables in server.env files. We can also specify JVM options in jvm.options files. Both server.env and jvm.options files work only when we use the server management script. If we use the ws-server.jar executable JAR file to launch the server, these files are not supported.

• Specify environment variables using server.env files.

  We 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

  • 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.

  • Shell and variable expansion are not supported.

  • WLP_USER_DIR can be specified only in the...
    ${wlp.install.dir}/etc/server.env

    ...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...

  • ${wlp.install.dir}/etc/server.env
  • ${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.

  We can also specify these environment variables in the shell environment, but the server.env files take precedence over those variables.

• Customize JVM options using jvm.options files.

  We use jvm.options files at the runtime and server levels to specify server startup options, for example, -X arguments. Options are applied when the start, run, and debug actions are passed. Specify only one option per line. For example:

  #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
  
  # Alternate verbose garbage collection log on IBM JVMs only.
  -Xverbosegclog:verbosegc.log
  
  # Additional verbose garbage collection options on HotSpot JVMs only.
  -Xloggc:verbosegc.log
  -XX:+PrintGCDetails
  -XX:+PrintGCTimeStamps
  -XX:+PrintHeapAtGC

  The server management script searches for jvm.options in two locations:

  • ${wlp.install.dir}/etc/jvm.options
  • ${server.config.dir}/jvm.options

  If both files are present, the options in the server-level file are used.

  • 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.
  • Shell and variable expansion are not supported.

If you start the server using either the MBean or the Admin Center, the only available environment variables are those variables available to a remote command running on that system.

Parent topic: Administer the Liberty profile manually
Server configuration
Provide global libraries for all Java EE applications
Directory locations
server command options