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.
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 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.
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.
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.
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).
--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 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:
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.
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
server javadump myserver
server javadump myserver --include=heap,system