Administer Liberty on z/OS

On the z/OS platform we can start, stop, or modify Liberty using MVS operator commands.

Ensure that the following security profiles are set up as described in Enable z/OS authorized services on Liberty for z/OS.

  • 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. We 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. See Named angel.

If a Liberty server instance connects to an angel 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.

This topic describes how to start, modify, and stop Liberty using the MVS console. We can also start and stop the server from a shell, or use a shell to start the server as a started task, see Start and stop a server from the command line. CAUTION:Do not include # 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. A started task is JCL that is run immediately in response to an operator START command. Two JCL procedure templates (PROCs) are available in the 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 required for controlling access to system authorized services on the z/OS platform.

Administrators can copy the templates to a user location, and then customize them to start Liberty servers from the MVS console.

Note: Files in the /templates directories might be modified when product updates are applied. The examples section provides further information about the two PROC templates.

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.

  • To start a process, use the START command for the appropriate proc:

    • START bbgzsrv to start the bbgzsrv proc for the server process
    • START bbgzangl to start the bbgzangl proc for the angel process

  • To modify Liberty, use the MODIFY command.

    See the following topics:

  • To stop a process, use the STOP (p) command for the appropriate proc:

    • STOP bbgzsrv to stop the bbgzsrv proc
    • STOP bbgzangl to stop the bbgzangl proc

    Attention:

    Canceling the Angel process started task (What to do if the Angel process started task abends)

    A best practice is to NOT ever cancel the angel process. Server tasks and application tasks can be depend on the angel process running. However, there are rare cases in which to avoid a severe system shutdown, such as a re-IPL, we might find it necessary to cancel the angel process. If we ever need to cancel the angel started task or if the angel started task should abend, our WebSphere Application Server administrator should cancel the servers with applications dependent on the successful running of the angel started task. Leaving the server(s) and application(s) running can result in a server hang condition.


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

Notes:

  • 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 we 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 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 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, and JAVA_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: We 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.

    If none of these files are present, then the ${wlp.install.dir}/etc/jvm.options file is read. 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 the JVM_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 to TRUE.

    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 the IBM_JAVA_OPTIONS environment variable, which overrules command-line options and thus any options set in jvm.options files.

  • When we start a Liberty server with a z/OS procedure, we can customize the umask 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. We can specify this variable in the server.env file, or, if we start the server with a z/OS procedure, we 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. We 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 and WLP_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

The following example shows the command that you would use to start Liberty using the sample bbgzsrv proc for a configured "defaultServer": 

    start bbgzsrv,parms='defaultServer'

The following example shows the procedure template for the angel process (bbgzangl): 

    //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=*


Parent topic: Administer Liberty manually


Related information