Liberty profile: server command options

The server command supports starting, stopping, creating, packaging, and dumping a Liberty profile 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]

where the value of action represents the operation that you can perform on a Liberty profile server. See available administration operations for the Liberty profile 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 Fix Pack 8501 or dump operation. This path can be either a relative path, which is relative to the installation root directory of the Liberty profile, or an absolute path. The default archive target is a compressed file with the server name, which will be 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.

Fix Pack 8550 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 profile server can be installed by using the java command; for more information, see Installing the Liberty profile by extracting an archive file. The .jar extension facility is not available on the z/OS® platform.

--clean
Cleans all persistent cached information 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. Fix Pack 8550 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 profile 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.
  • Fix Pack 8550 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, thereby minimizing 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 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).
Fix Pack 8550 --os=os_value,os_value,...
Fix Pack 8550 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 web site at the following URL: http://www.osgi.org/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 subsequently include it if you repeat the minify operation on the archive.

Server Process

The server process is created using the environment variables that are specified in the server.env file. The following JVM options are added by default:
  • Fix Pack 8550 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. You 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

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

Fix Pack 8551 By default. the server command sets the umask value to deny all permissions to "Other" users before running the action. However, you 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 the WLP_OUTPUT_DIR/serverName/logs/console.log file 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. For more information about the logging configuration, see Liberty profile: 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 indicates that an error occurred while performing the requested . Messages will be 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
Fix Pack 8501 server javadump myserver
Fix Pack 8501 server javadump myserver --include=heap,system

Icon that indicates the type of topic Reference topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-express-iseries&topic=rwlp_command_server
File name: rwlp_command_server.html