Server command options

The server command supports starting, stopping, creating, packaging, and dumping a Liberty server. This topic describes all available options and exit codes that you can use with the server command and the equivalent executable JAR file ws-server.jar.

Syntax

The command syntax is as follows:

server action serverName [options]

The value of action represents the operation that you can perform on a Liberty server. See available administration operations for Liberty from the command prompt.

Note: If a server is not specified on the command line, the action is performed against the default server instance, defaultServer, if it exists.

Options

The following options are available for the server command:
--archive=path_to_the_target_archive_file

Specifies a target file for the package or dump operation. This path can be either a relative path, which is relative to the installation root directory of Liberty, or an absolute path. The default archive target is a compressed file with the server name, which is stored in the installation root directory. Use quotation marks if the value contains spaces. You can use this option for both package and dump operations.

For IBM i platformsDistributed: [AIX MacOS Linux Windows]If you specify a .jar extension for your archive file name, the server command creates a new self-extracting archive file from which the Liberty server can be installed by using the java command. For more information, see Installing Liberty by extracting a Java archive file in the product documentation. The .jar extension facility is not available on the z/OS® platform.

--clean
Cleans all persistent cached information that is related to the specified server instance, which includes OSGi resolver metadata and persistent OSGi bundle data. If you use this option, the server will be required to recompute any cached data at the next startup, which might take more time than a restart that can reuse cached data.
Note: This option is not necessary for normal operation. IBM® service might request that you use this option when providing an interim fix, or if there is a suspected problem with the cached data. This option might also be necessary if you are developing a product extension, and you are either updating OSGi manifests or planning to clear persistent OSGi bundle data.
--include=package_option
Specifies the files that you want to package, where package_option can take one of the following values:
  • all specifies to package all the files in the Liberty installation directory. If the ${WLP_USER_DIR} and ${WLP_OUTPUT_DIR} are defined in the server.env file, the files under them are packaged. This value applies only to the package operation.
  • usr specifies to package the files in the ${WLP_USER_DIR} directory. This value applies only to the package operation.
  • minify specifies to package only those parts of the runtime environment, and files in the ${WLP_USER_DIR} directory, that are required to run the server, which minimizes the size of the resulting archive. This value applies only to the package operation.
--include=diagnose_option,diagnose_option,...
Specifies the type of diagnostic information to be captured. The value of --include is a comma-delimited list, which can contain any of the following values:
  • heap is used to help diagnose the excessive memory consumption and memory leaks, which shows live objects in the memory and references between them. On IBM J9 virtual machines, the resulting file is named heapdump.date.time.processID.sequenceNumber.phd. On HotSpot virtual machines, the resulting file is named java.date.time.processID.sequenceNumber.hprof. This value applies to both the dump and javadump operations.
  • system is also used to help diagnose the excessive memory consumption and memory leaks, but they are also useful for finding defects in the virtual machine. These dumps are only supported on IBM J9 virtual machines. The resulting file is named core.date.time.processID.sequenceNumber.dmp. This value applies to both the dump and javadump operations.
  • thread is used to help diagnose hung threads, deadlocks, and can sometimes be used for diagnose excessive CPU issues. These dumps are always created with the server javadump command. On IBM J9 virtual machines, the resulting file is named javacore.date.time.processID.sequenceNumber.txt. On HotSpot virtual machines, the resulting file is named javadump.date.time.processID.sequenceNumber.txt. This value can also be applied to the dump operation.
    Note: The thread dump type is supported only when the server is running on the Java™ SDK. If the server is started with a JRE, an error is reported indicating that the server does not support the dump type. This restriction applies to HotSpot virtual machines only; the thread Java dump type is supported on any IBM JVM (JRE or SDK).
--os=os_value,os_value,...
Specifies the operating systems that you want the packaged server to support. Supply a comma-separated list. The default value is any, indicating that the server is to be deployable to any operating system supported by the source.

To specify that an operating system is not to be supported, prefix it with a minus sign (-). For a list of operating system values, refer to the OSGi Alliance website at the following URL: https://www.osgi.org/developer/specifications/reference/#os.

This option applies only to the package operation, and can be used only with the --include=minify option. If you exclude an operating system, you cannot later include it if you repeat the minify operation on the archive.

--target=pausable_component,pausable_component,...
Specifies a comma-delimited list of specific components that can be paused. If you specify the target option, only the components that are listed are paused or resumed. For a list of example target values, see Pausing and Resuming a Liberty server from the command line.

Server Process

The server process is created by using the environment variables that are specified in the server.env file. The following JVM options are added by default:
  • The -javaagent:wlp/bin/tools/ws-javaagent.jar option is required for trace, monitoring, incremental publishing of applications, and other server capabilities.
  • The -Xshareclasses and related options enable the shared class cache on supported IBM J9 virtual machines. The cache directory is set to WLP_OUTPUT_DIR/.classCache.
  • The -XX:MaxPermSize option increases the size of the permanent generation for HotSpot virtual machines before Java 8. You can set the WLP_SKIP_MAXPERMSIZE environment variable to true to avoid this default option, which avoids warnings such as: 
    Java HotSpot(TM) Client VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0
  • The -Djava.awt.headless=true option avoids java.awt.HeadlessException on all platforms and focus stealing problems on macOS.

You can use the jvm.options file to override these default JVM options or add more JVM options. For more information about the server.env and jvm.options file, see Customizing the Liberty environment.

For UNIX platformsFor IBM i platformsBy default, the server command sets the umask value to deny all permissions to Other users before the command runs the action. You can set the WLP_SKIP_UMASK environment variable to true in the server.env file to prevent the server command from modifying the umask. If you set the WLP_SKIP_UMASK environment variable, the server uses the umask from the underlying process of the operation. On z/OS, you can specify the WLP_SKIP_UMASK property in one of the following ways:
  • Use the server.env file.
  • Alternatively, if you start the server with a z/OS procedure, you can specify the property with the STDENDV DD entry.

The current working directory of the server process is set to the server output directory.

For UNIX platformsFor IBM i platformsThe server command creates a process ID (PID) file when you start the server and deletes the PID file when you stop the server. By default, the PID file is set to WLP_OUTPUT_DIR/.pid/serverName.pid. The absolute path of the PID file can be changed by setting the PID_FILE environment variable, or the absolute path of the PID directory can be changed by setting the PID_DIR environment variable.

The standard output and error from the server process is output to the foreground console when you use the run and debug actions and is redirected to the WLP_OUTPUT_DIR/serverName/logs/console.log file by default when you use the start action. The log name can be changed by setting the LOG_FILE environment variable, and the log directory can be changed by setting the LOG_DIR environment variable. For more information about the logging configuration, see Logging and trace.

The stop action prevents new application requests from entering the server, which allows existing requests some time to complete. After that time, the remaining server components are stopped and the server process exits. Application requests that do not complete in the allowed time fail, but their exact behavior depends on their activity when the server components stopped.

Exit codes

The following exit codes are available for the server command and the equivalent executable JAR file ws-server.jar:
0
OK. 0 indicates successful completion of the requested operation. For server status, 0 indicates that the server is running.
1
For server status, 1 indicates that the server is not running. For other operations, it indicates invocation of a redundant operation. For example, starting a started server or stopping a stopped server. This code might also be returned by JVM if invalid Java options are used.
2
The server does not exist.
3
An unsupported action was called on a running server. For example, the server is running when the package action is called.
4
An unsupported action was called on a stopped server. For example, the server is not running when the dump action is called.
5
Unknown server status. For example, the workarea directory is missing, or the Attach API fails to work.
>=20
Return codes greater than or equal to 20 indicates that an error occurred while performing the request. Messages are printed and captured in log files with more information about the error.

Usage

The following examples demonstrate the correct syntax:

server run
server start myserver --clean
server package myserver --archive="archivefile.zip" --include=all
server dump myserver --archive="c:\mybackup\myserver.zip" --include=thread
server javadump myserver
server javadump myserver --include=thread,system