Administering Liberty on z/OS
On the z/OS® platform you can start, stop, or modify Liberty by using MVS™ operator commands.
Before you begin
- STARTED profiles for the server process, and the angel process
- SERVER profiles to allow access to authorized z/OS services
Each LPAR can have one default angel process. You can give an angel a name if the angel is started at V16.0.0.4 or later. That angel can become an additional angel process on that LPAR. For more information about angels and LPARs, see Named angel.
If a Liberty server instance connects to an angel that is running at an earlier service level, some features of the server might not be available. Whenever possible, keep all Liberty servers at the same product level and aligned with the corresponding angel version. Upgrade the Liberty server product levels and the angel version at the same time.
About this task
This topic describes how to start, modify, and stop Liberty by using the MVS console. You can also start and stop the server from a shell, or use a shell to start the server as a started task, see Starting and stopping a server from the command line.
#
or $
characters in the job
name. Liberty constructs a UNIX path with the job name in it. The #
and
$
characters can cause incorrectly formed UNIX
paths.wlp/templates/zos/procs
directory.
One template is for the server process, and the other is for the angel process:- bbgzsrv for Liberty.
- bbgzangl for the angel process that is required for controlling access to system authorized services on the z/OS platform.
The target of an operator STOP command is a job or a started task.
After the JCL procedure templates are customized, they must be placed into the system procedure library concatenation. The name of the procedure member becomes the argument to the START command.
Procedure
Example
The following example shows the procedure template for the server process (bbgzsrv). This PROC is in a data set in the z/OS proclib concatenation.
//BBGZSRV PROC PARMS='defaultServer'
//*------------------------------------------------------------------
//* INSTDIR - the path to the WebSphere Liberty install.
//* This path is used to find the product code and is
//* equivalent to the WLP_INSTALL_DIR environment variable
//* in the Unix shell.
//* USERDIR - the path to the WebSphere Liberty user area.
//* This path is used to store shared and server specific
//* configuration information and is equivalent to the
//* WLP_USER_DIR environment variable in the Unix shell.
//*------------------------------------------------------------------
// SET INSTDIR='/u/MSTONE1/wlp'
// SET USERDIR='/u/MSTONE1/wlp/usr'
//*------------------------------------------------------------------
//* Start the Liberty server
//*
//* WLPUDIR - PATH DD that points to Liberty's "user"
//* directory. If the DD is not allocated, the user
//* directory location defaults to the wlp/usr directory
//* in the install tree.
//* STDOUT - Destination for stdout (System.out)
//* STDERR - Destination for stderr (System.err)
//* MSGLOG - Destination for messages.log (optional)
//* STDENV - Initial Unix environment - read by the system. The
//* installation default and server specific server
//* environment files will be merged into this environment
//* before the JVM is launched.
//*------------------------------------------------------------------
//STEP1 EXEC PGM=BPXBATSL,REGION=0M,
// PARM='PGM &INSTDIR./lib/native/zos/s390x/bbgzsrv &PARMS'
//WLPUDIR DD PATH='&USERDIR.'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//*MSGLOG DD SYSOUT=*
//*STDENV DD PATH='/etc/system.env',PATHOPTS=(ORDONLY)
//*STDOUT DD PATH='&ROOT/std.out',
//* PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//* PATHMODE=SIRWXU
//*STDERR DD PATH='&ROOT/std.err',
//* PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//* PATHMODE=SIRWXU
- The launcher uses the STDENV DD as the initial environment, but this DD is optional. The initial environment to the process is defined in the PROC. It can point to any type of data set that Language Environment® supports, but the format must be compatible with what is expected. For example, Extended Binary Coded Decimal Interchange Code (EBCDIC), simple key=value with no expansion.
- A PATH DD that points to an existing directory (not a file) is allowed. If that DD is opened, the FILE stream that is returned is valid for fldata so the HFS path that is associated with the DD can be used. The PROC template defines a WLPUDIR PATH DD that represents the equivalent of WLP_USER_DIR.
- The WLP_USER_DIR is determined by the following logic:
- If the WLPUDIR DD is defined, the associated path is used as WLP_USER_DIR.
- If WLPUDIR is not defined but WLP_USER_DIR is set in the initial environment (from STDENV), it is used.
- If WLPUDIR is not defined and WLP_USER_DIR is not set in the initial environment, the default value of $WLP_INSTALL_DIR/usr is used.
- The environment is determined by the following logic:
- If you define the STDENV DD, then Language Environment reads the entry as the initial environment.
- If $WLP_INSTALL_DIR/etc/server.env exists and is readable, its key=value contents are read and set into the environment. The file can be in ASCII or EBCDIC. Comments start with a pound sign (#) and go to the end of the line. Values that contain blank space can be placed in double quotation marks. Any environment entries that are specified in this file overrides entries from the initial environment.
- If $WLP_USER_DIR/servers/{serverName}/server.env exists and is readable, its key=value contents are read and set into the environment. This file can also be in ASCII or EBCDIC and supports comments. Any entries that are specified here override entries from the initial environment and the etc/server.env.
- Regardless of the user specified environment, the following entries are explicitly set:
_BPXK_WLM_PROPAGATE=NO, JAVA_THREAD_MODEL=HEAVY
, andJAVA_PROPAGATE=NO
. If_EDC_PTHREAD_YIELD
is not set, it is set to -2.
- After the environment is set, the JAVA_HOME is determined by the following logic:
- If JAVA_HOME is set in the environment, its location is used as JAVA_HOME.
- If JAVA_HOME is not set in the environment but $WLP_INSTALL_DIR/../java64 exists, $WLP_INSTALL_DIR/../java64 is used as JAVA_HOME.
- If JAVA_HOME is not set in the environment and $WLP_INSTALL_DIR/../java64 does not exist, $WLP_INSTALL_DIR/../java is used as JAVA_HOME.
- After JAVA_HOME is determined, JVM command line options are determined by
the following logic:You can create multiple jvm.options files in the following locations. These files are merged in order from the beginning to the end of this list before server start and are used as the JVM options for the server.
- ${wlp.install.dir}/usr/shared/jvm.options
- ${server.config.dir}/configDropins/defaults/jvm.options
- ${server.config.dir}/jvm.options
- ${server.config.dir}/configDropins/overrides/jvm.options
In addition to the JVM command-line options that are merged from any jvm.options files, the following options might also be merged.- The
-Dfile.encoding=iso8859-1
option is set only if the-Dfile.encoding
property is not already set in any merged jvm.options file or theJVM_ARGS
environment variable. - The -javaagent:$WLP_INSTALL_DIR/lib/bootstrap-agent.jar option is set only
if the
WLP_SKIP_BOOTSTRAP_AGENT
environment variable is not set toTRUE
.
The server process always sets the
-Djava.class.path=$WLP_INSTALL_DIR/lib/ws-launcher.jar
option from the command line.To provide JVM command-line options when the
jvm.options
files are read-only, consider using theIBM_JAVA_OPTIONS
environment variable, which overrules command-line options and thus any options set in jvm.options files. - When you start a Liberty server with a
z/OS procedure, you can customize the umask that is used by
the server process. To customize the umask, define the WLP_SKIP_UMASK and the _BPX_BATCH_UMASK
environment variables in one of the following ways:
- Specify the WLP_SKIP_UMASK environment variable. You can specify this variable in the
server.env file, or, if you start the server with a z/OS procedure, you can specify the variable under the STDENDV DD entry. In the
z/OS procedure, specify the _BPX_BATCH_UMASK variable under
the STDENV DD entry. You cannot specify the _BPX_BATCH_UMASK variable in the
server.env file. The following example shows a sample umask value customization:
//STDENV DD * _BPX_BATCH_UMASK=XXXX WLP_SKIP_UMASK=TRUE /*
- Specify both
_BPX_BATCH_UMASK=XXXX
andWLP_SKIP_UMASK=TRUE
in an EBCDIC encoded z/OS UNIX file. Define the path under the STDENV DD entry in the z/OS procedure. The following example shows a sample umask value customization://STDENV DD PATH='u/path/to/env/ebcdic/file',PATHOPTS=ORDONLY
- Specify the WLP_SKIP_UMASK environment variable. You can specify this variable in the
server.env file, or, if you start the server with a z/OS procedure, you can specify the variable under the STDENDV DD entry. In the
z/OS procedure, specify the _BPX_BATCH_UMASK variable under
the STDENV DD entry. You cannot specify the _BPX_BATCH_UMASK variable in the
server.env file. The following example shows a sample umask value customization:
start bbgzsrv,parms='defaultServer'
//BBGZANGL PROC PARMS='',COLD=N,NAME=''
//*------------------------------------------------------------------
// SET ROOT='/u/MSTONE1/wlp'
//*------------------------------------------------------------------
//* Start the Liberty angel process
//*------------------------------------------------------------------
//STEP1 EXEC PGM=BPXBATA2,REGION=0M,TIME=NOLIMIT,
// PARM='PGM &ROOT./lib/native/zos/s390x/bbgzangl COLD=&COLD NAME=X
// &NAME &PARMS'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*