server command options

server command options

Overview

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

Syntax

server action serverName [options]

See available administration operations for the Liberty profile from the command prompt.
If serverName is not specified, the action is performed against the default server instance, defaultServer.

Options

--archive="/path/to/install_root/serverName.jar"

Target file for the package or dump operation. Path can be relative to the installation root directory of the Liberty profile, or an absolute path. If archive file name is not specified, default archive created is...
/path/to/install_root/serverName.jar

Use quotation marks if the value contains spaces. We can use this option for both package and dump operations. We can use serverName.jar to install a Liberty profile server installed using the java command.

--clean

Clean all persistent cached information related to the specified server instance. Includes OSGi resolver metadata and OSGi bundle data. The server recomputes cached data at the next startup.
Not necessary for normal operation. Generally used by request from IBM service when determining required interim fix, or if there is a suspected problem with the cached data. Used also when developing extensions that either update OSGi manifests, or clear persistent OSGi bundle data.

--include=package_option

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

all If ${WLP_USER_DIR} and ${WLP_OUTPUT_DIR} are defined in server.env, package files under them.
usr Package files in ${WLP_USER_DIR}.
minify Package only those parts of the runtime environment required to run the server. Minimizes size of archive.

--include=diagnose_option,diagnose_option,...

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 Diagnose excessive memory consumption and memory leaks. 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

system Diagnose excessive memory consumption and memory leaks. Useful for finding defects in the virtual machine. Only supported on IBM J9 virtual machines. Resulting file is named...
core.date.time.processID.sequenceNumber.dmp

thread 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

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 will be reported indicating that the server does not support the dump type. This restriction only applies to HotSpot virtual machines; 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.
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 web site
This option applies only to the package operation, and can be used only with the --include=minify option. If you exclude an operating system, we cannot subsequently include it if you repeat the minify operation on the archive.

Server Process

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

The -javaagent:wlp/bin/tools/ws-javaagent.jar option is required for trace, monitoring, 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 prior to Java 8. We can set the WLP_SKIP_MAXPERMSIZE environment variable to true to avoid this default option, which will avoid warnings such as:
Java HotSpot(TM) Client VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0

We can use jvm.options to override these default JVM options or add additional JVM options.

By default. the server command sets the umask value to deny all permissions to "Other" users before running the action. We can set the WLP_SKIP_UMASK environment variable to true to avoid setting the umask value.
The current working directory of the server process is set to the server output directory.
The standard output and error from the server process is output to the foreground console when using the run and debug actions and is redirected to...
WLP_OUTPUT_DIR/serverName/logs/console.log

...by default when using 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. See Logging and Trace.

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 indicate an an error occurred. Messages will be printed and captured in log files with more information about the error.

Usage

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=heap,system

Parent topic: Administer the Liberty profile from the command prompt
Tasks:
Generate a server dump from the command prompt
Packaging a Liberty profile server from the command prompt
Create a Liberty profile server manually
Use Ant to automate tasks
Embedding the Liberty profile server in the applications
Customize the Liberty profile environment
Administer the Liberty profile from the command prompt

all	If ${WLP_USER_DIR} and ${WLP_OUTPUT_DIR} are defined in server.env, package files under them.
usr	Package files in ${WLP_USER_DIR}.
minify	Package only those parts of the runtime environment required to run the server. Minimizes size of archive.

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 indicate an an error occurred. Messages will be printed and captured in log files with more information about the error.