Liberty environment variables in server.env

The following environment variables can be configured in server.env file. The ${wlp.install.dir} configuration variable has an inferred location that is always set to the parent of the directory containing the launch script.

For more information, see: Server configuration overview.

    JVM_ARGS List of command-line options, such as system properties or -X parameters, passed to the JVM when the server starts. Any values that contain spaces must be enclosed in quotes. We can also specify JVM options in jvm.options files.
    WLP_USER_DIR Alternative location for ${wlp.user.dir}. Must be an absolute path. If specified, the runtime environment looks for shared resources and server definitions in the specified directory. ${server.config.dir} is equivalent to...

      ${wlp.user.dir}/servers/serverName

    If not specified, ${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 the logs directory can include console.log, messages.log, and any generated FFDC files. Generated files can include server diagnostic dumps created with the server diagnostic dump or server javadump command. 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 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_DEBUG_ADDRESS Alternative port when we 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, we run Liberty from the ws-server.jar executable JAR file, or the embedded Liberty server SPI, then use the same settings to enable debug mode for Liberty. Specify the path to the libraries in server.env.


Notes

  • The server management script searches for server.env files in two locations:

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

  • Because the purpose of WLP_USER_DIR is to specify where the remaining configuration is located, it can be specified only in...

      ${wlp.install.dir}/etc/server.env

  • Customize JVM options using jvm.options files.

    We 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

    We 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 the beginning to the end of this list 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.

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

  • Do not put property values in quotation marks.

  • Empty lines and lines that start with the number sign (#) are ignored.

  • All characters are literal except for the caret (^) in Windows when the caret is used to escape a variable expansion character like the exclamation point (!).

  • There should be no blank space surrounding the equal sign (=).

  • For information about using expansion variables on Windows or on Linux in version 22.0.0.1 and later, see Expansion variables on the Open Liberty website.


What to do next

If we start the Liberty server using the server script, all of the operating system environment variables from the current session are available. If we 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.