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 we can use with the server command and the equivalent executable JAR file ws-server.jar.

Syntax

The command syntax is as follows:

action

The value of action represents the operation we can perform on a Liberty server.

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 each server action command:

--archive=/path/to/servername.zip

Target file for the package or dump operation. This path can either relative to the Liberty home, 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.

--clean

Clean all persistent cached information that is related to the specified server instance, which includes OSGi resolver metadata and persistent OSGi bundle data. If we 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 that this option is not necessary for normal operation. IBM service might request we 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 we are developing a product extension, and we are either updating OSGi manifests or planning to clear persistent OSGi bundle data.

--include=package_option

Specify the files to package, where package_option can take one of the following values:

all	Package all the files in the Liberty installation directory. Applies only to the package operation. If the ${WLP_USER_DIR} and ${WLP_OUTPUT_DIR} are defined in the server.env file, the files under them are packaged.
usr	Package the files in the ${WLP_USER_DIR} directory. Only to the package operation.
minify	Package only those parts of the runtime environment, and files in the ${WLP_USER_DIR} directory, 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,...

Type of diagnostic information to be captured with the dump action. 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...
On HotSpot virtual machines, the resulting file is named...
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...
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...
On HotSpot virtual machines, the resulting file is named...
This value can also be applied to the dump operation.
Note that 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,...

Operating systems we 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.

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

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.

--target=pausable_component,pausable_component,...

Comma-delimited list of specific components that can be paused or resumed.

Server Process

The server process is created using environment variables specified in server.env. The following JVM options are added by default:

-javaagent:wlp/bin/tools/ws-javaagent.jar	Required for trace, monitoring, incremental publishing of applications, and other server capabilities.
-Xshareclasses	Enable the shared class cache on supported IBM J9 virtual machines. The cache directory is set to WLP_OUTPUT_DIR/.classCache.
-XX:MaxPermSize	increases the size of the permanent generation for HotSpot virtual machines before Java 8. We 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
-Djava.awt.headless=true	Avoids java.awt.HeadlessException on all platforms and focus stealing problems on macOS.

We can use the jvm.options file to override these default JVM options or add more JVM options. We 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 we set the WLP_SKIP_UMASK environment variable, the server uses the umask from the underlying process of the operation. On z/OS, we can specify the WLP_SKIP_UMASK property in one of the following ways:

Use the server.env file.
Alternatively, if we start the server with a z/OS procedure, we can specify the property with the STDENDV DD entry.

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

The server command creates a process ID (PID) file when we start the server and deletes the PID file when we 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, including server start, is output to the foreground console when we use the run and debug actions and is redirected to...

console.log

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.

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 diagnostic dump myserver --archive="c:\mybackup\myserver.zip" --include=thread
server javadump myserver
server javadump myserver --include=thread,system

Parent topic: Administer Liberty from the command line

Related tasks

Use Ant to automate tasks for Liberty