User:Bagwell59/sandbox

= IBM Liberty Profile z/OS = IBM announced WebSphere Application Server Version 8.5 on April 24th, 2012. One element of that announcement was a new application server model called the "Liberty Profile." The previous application server model for WebSphere Application Server remains and is provided along with the new Liberty Profile model. The two together comprise WebSphere Application Server Version 8.5. The following graphic illustrates this relationship with the supported platforms provided as well:



Most of the functions of the Liberty Profile are common to all platforms. Some are exclusive to z/OS.

Liberty Profile in General
Note -- information presented here applies to all platforms on which the Liberty Profile is supported, including z/OS.

The Liberty Profile is a functional subset of the full Java EE 6 model of traditional WebSphere Application Server. It provides a composable web container runtime with dynamic update capabilities:


 * Composable -- the configuration design allows for coding only those functions needed by the application. This contributes to less resource usage compared to the tradtional full-function Java EE runtime.
 * Dynamic -- changes to the configuration file are detected and incorporated into the running server without need of a restart.  Changes to applications are detected and incorporated without need of a server restart.

Applications developed and tested using the Liberty Profile server runtime will also run in the traditional WebSphere Application Server runtime. Liberty is a functional subset of the full Java EE traditional WebSphere Application Server model.

The Liberty Profile product files are found under the  directory where WebSphere Application Server Version 8.5 itself is installed. This is known as the install directory. User directories are where server configurations are maintained. User directories may exist within the install directory, or be placed at other locations. The  shell script (or BAT file on Windows) is used to create and operate the Liberty Profile servers:



The numbered blocks in the graphic correspond to the following notes:
 * 1) The install directory (generic reference:   ) is the Liberty Profile product files are installed.  This may be where WebSphere Application Server V8.5 is installed, or it may be where a packaged copy of the Liberty Profile has been located.  The   shell script is located in the   directory.
 * 2) The   shell script is used to create server configurations as well as operate servers.  Server configuration files are maintained in what is called the user directory.  Where it creates a server configuration is based on the value for the environment variable  .  By default the server configuration will be created within the   directory.  Otherwise, the server configuration will be created at the location specified by.
 * 3) By default the server will be created within the   under.
 * 4) The primary configuration file is  .  Each server is required to have a   file.  Configuration elements may be shared between servers, and subsitution variables are supported within  .  That permits a common copy of   to be shared across multiple servers.
 * 5) Multiple server instance configurations may be created in any given  .  The illustration shows 99, which is simply an arbitrary number meant to convey the idea of many servers.  The number of Liberty Profile servers one may configure and run is a function of the server resources.
 * 6) The   may be located at directories other than the  .  Multiple such   locations may be created.  This provides a means for mounting   as read-only with one or many   locations making use of a common  .

Liberty Profile user directory structure
For any given   the following directory structure and file structure applies. The numbered blocks correspond to the notes that follow:




 * 1) The user directory root, which may be within the install root or at another location.
 * 2) Liberty Profile provides a built-in variable that may be used to reference the user directory for the operating server.  This variable may be used in the configuration file  and the variable will be resolved at runtime.  The variable is as shown:.
 * 3) The   directory is not present by default but may be created manually as a location for shared assets for all servers under the  .
 * 4) Three sub-directories under   are shown, along with the corresponding variables that relate to the directory.  The   directory may be used to share application WAR files between servers; the   directory for configuration elements shared between servers using the   XML element within the   directory may be used for other resources such as LTPA keys.
 * 5) Each server under the   carries a unique name.  The   variable may be used within a server's   to refer to that server's configuration directory.
 * 6) Four configuration files are shown.  Only   is required.  The   file is the primary configuration file for the server.  The   file is optional and is used to provide environment entries applicable to the operating server.  The   file is option and is used to provide values that influence the initial bootstrap of the server.  The   file is optional and is used to provide options to the JVM that operates in the server instance.
 * 7) The   directory is a location where one may store application WAR files.  The application may be referenced using the server config directory variable.  For example:.
 * 8) The   directory is a monitored directory.  Application WAR files dropped into this directory are detected and automatically loaded.  The monitoring interval is configurable.
 * 9) The   and   directories are where the server writes its logs and maintains other work files.  By default these directories will be located within the server's configuration directory, but they may be configured to be written elsewhere.

Liberty Profile configuration files
One configuration file is required and the others are optional.

server.xml
The  file is required. By default, changes to this file are detected and dynamically applied.

The  file is the primary configuration file for a given Liberty Profile server instance. By default the  file is monitored by the Liberty Profile and will be updated dynamically if a change is detected. What follows is an example of a simple configuration:

In this example the  section shows one feature --. Other features are supported, such as JDBC, JPA, SSL and several z/OS-specific functions. A complete list is provided in the product Information Center under search string.

This configuration example illustrates the HTTP endpoints defined as  and   listening on.

A more complex example would be:

This example illustrates the use of JDBC Type 2 on z/OS connecting to DB2 z/OS with IBM Resource Recovery Services (RRS) acting as the global transaction synchpoint coordinator. The HTTP  value is set to , indicating the Liberty Profile server is to listen across all network adapters.

A complete list of the XML elements supported in the  file is provided in the product Information Center under search string.

Using variables
Variables may be used in the  to reference directory locations or specific values. The variables are resolved at runtime. For example, multiple servers may share the same application:



Another example would be to set the HTTP ports for a server in the  file with:

And then reference those values in the  file using the respective variables:

This would provide a way to configure multiple servers, each with unique HTTP ports, but sharing a common  file.

Using includes
The use of the  element within the   file permits sharing of configuration elements across servers. For example, the following graphic illustrates three servers sharing a portion of configuration XML by using the  and referencing the variable   to point to the location of the common XML to use:

Note that XML to be included in the  must itself begin with   and end with.

It is possible to reduce the  for each server down to a single   provided necessarily unique values (such as HTTP ports if all servers are on the same TCP stack) are properly resolved with variables as illustrated earlier.

server.env
The  file is optional. Changes to this file require a restart of the server to take effect.

The  file provides values to the shell environment for the server to use during runtime. For example, the variable  provides the pointer to a valid 64-bit SDK to use for the server. Another example is  which would point to an output directory for the server to use other than the default. Environment variables may also be supplied in the profile of the user identity under which the Liberty Profile server operates.

Entries in the  file are specified one per line file.

jvm.options
The  file is optional. Changes to this file require a restart of the server to take effect.

The  file provides options to the JVM that operates within the server. Entries are specified on per line in the file.

bootstrap.properties
The  file is optional. Changes to this file require a restart of the server to take effect.

This file provides values to the runtime that affect the initial startup of the server. Entries are provided one per line in the file.

Operating a Liberty Profile server
On z/OS a Liberty Profile server is operated as either a UNIX process or a z/OS started task. There is no difference in configuration or functional support between the two. Starting Liberty Profile servers on z/OS is a means of running Liberty within traditional z/OS operational mechanisms such as system automation routines as well as the z/OS  command.
 * UNIX shell process -- the  shell script is used to start and stop the server
 * z/OS started task -- supplied JCL is used to start a Liberty Profile server as a z/OS started task

Starting and stopping a Liberty Profile server in the UNIX shell
This is accomplished using the  shell script, which is found in the   directory under the  . By default Liberty will look within the   for a user directory with the server name specified on the  command. The shell environment variable  may be used to indicate a different location for the user directory.

For example, to start the server  and specify all cached artifacts be cleaned prior to start, the command syntax is:

To stop the server the command would be:

Another command on the  command is , which will return the status of the server name supplied.

Starting a Liberty Profile server as a z/OS started task
A sample JCL start procedure is supplied that may be customized to start Liberty Profile servers. The following graphic illustrates how the supplied sample JCL is structured and how it relates to the   and  . Numbered blocks correspond to notes that follow.




 * 1) The sample JCL to start a server is supplied as   under   of the  .
 * 2) The   statement is used to specify the  , including.
 * 3) The   statement is used to specify the   under which the server to be started is configured.
 * 4) The   and   default to  .  That may be changed to specify a file system location.
 * 5) The   command includes   to specify the server to be started

For this to work a valid SAF  profile must exist that maps the JCL start procedure   to a user identity under which the Liberty Profile server will operate.

Multiple servers may be started in this manner by supplying separate  values on each   command.

Optionally, specify  to differentiate different servers started with the same JCL start procedure.

Liberty Profile use of z/OS platform functions
Liberty Profile for z/OS has several extensions designed to take advantage of specific z/OS platform functions. These extensions are:


 * SAF -- z/OS Security Access Facility (SAF) may be used for user authentication as well as a keystore/truststore for digital certificates.
 * WLM -- z/OS Workload Manager (WLM) may be used to classify work into separate WLM enclaves. This provides the ability to separate requests within a Liberty Profile server into separate WLM reporting classes for the purposes of resource usage analysis and reporting.
 * '''JDBC Type 2 with RRS --- JDBC Type 2 on z/OS makes use of a cross-memory connector into IBM DB2. When JDBC Type 2 is used then IBM Resource Recovery Services (RRS) is used to serve as the global transaction synchpoint coordinator being participants in the transaction.
 * MODIFY -- The z/OS  command may be used to initiate and process SVC and transaction dumps for a named server

server.xml sample for SAF
The following sample XML illustrates the elements needed to use SAF as a keystore and truststore for SSL:

Notes
 * Other XML is required, such as the  and , as well as any other configuration elements needed in support of the applications intended to be run
 * This implies the necessary SAF work has been completed to define a keyring for the user under which the Liberty Profile server will run, and that the necessary SSL server certificates and the CA certificate is present
 * The string  is literal.  Access to the keystore is controlled by SAF based on the userid of the operating server.  A password is not needed.  However, the literal string   is.

server.xml sample for WLM classification
The following sample XML illustrates the elements needed to classify work with a transaction class for use by WLM:

Notes
 * Other XML is required, such as the  and , as well as any other configuration elements needed in support of the applications intended to be run
 * This implies the necessary WLM work has been completed to define and activate the transaction classification mapping under the CB subsystem classification rules
 * In this example any URI that matches  will result in the transaction class   being passed into WLM.

server.xml sample for JDBC Type 2 with RRS
The following sample XML illustrates the elements needed to use JDBC Type 2 with RRS:

Notes
 * Other XML is required, such as the  and , as well as any other configuration elements needed in support of the applications intended to be run
 * This implies the necessary DB2 work has been completed to allow the userid under which the Liberty Server is operating to access the database tables used by the application
 * In this example  is the DB2 subsystem ID and   is the DB2 location name.
 * Access to JDBC Type 2 with RRS requires authorized access. That requires the presence of the Angel process, which provides the anchor point for access to z/OS platform authorized services for Liberty Profile on z/OS.

Liberty Profile z/OS Angel process
The Liberty Profile Angel process is exclusive to z/OS. It provides an anchor point for access to z/OS authorized services. It is not required for Liberty Profile function common to all platforms. It is required for JDBC T2 with RRS because that service has no unauthorized execution path. Other z/OS-only services (SAF, WLM, MODIFY) do not require the Angel process but benefit from it because access authority is granted once rather than per call.

The Angel process runs as a z/OS started task. There is no mechanism for running it as a UNIX shell process. It consumes no TCP ports. It starts and uses virtual no CPU thereafter. Its role is to provide an access point for authorized access to z/OS services. Access is permitted or denied based on the ID of the Liberty Profile server having  access to certain SAF   profiles.

If the Angel process is deemed necessary (based on criteria listed above), then only one copy is required per z/OS image regardless of the number of Liberty Profile servers that utilize the Angel process.

Configuring the Liberty Profile z/OS Angel process
The Angel process requires the use of a supplied JCL start procedure. That start procedure is supplied as  under   of the  .

The JCL has the following structure:

//BBGZANGL PROC PARMS='',COLD=N //*-- // SET ROOT='/usr/lpp/zWebSphere/V8R5/wlp/' //*-- //* Start the Liberty angel process //*-- //STEP1  EXEC PGM=BPXBATA2,REGION=0M, // PARM='PGM &ROOT./lib/native/zos/s390x/bbgzangl COLD=&COLD &PARMS' //STDOUT   DD SYSOUT=* //STDERR   DD SYSOUT=*

Where  points to the   for Liberty.

A SAF  profile must exist the Angel started task runs under a valid ID.

Operating the Liberty Profile z/OS Angel process
A simple MVS  command starts the Angel process:

The Angel process should be started prior to any Liberty Profile server requiring access to the Angel.

SAF profile access to the Liberty Profile z/OS Angel process
The following SAF  profiles provide incremental access to the Angel process based on the functional access sought. The userid under which the Liberty Profile server runs must have minimum  to the   profile.

Any Liberty Profile server ID seeking access to authorized services through the Angel process must have  to the following. This provides the essential access priviledges:

RDEF SERVER BBG.ANGEL UACC(NONE) RDEF SERVER BBG.AUTHMOD.BBGZSAFM UACC(NONE)

Liberty Profile server IDs seeking access to SAF services through the Angel process would be granted  to the following as well:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)

Liberty Profile server IDs seeking access to WLM services through the Angel process would be be granted  to the following as well:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSWLM UACC(NONE)

Liberty Profile server IDs seeking access to JDBC Type 2 with RRS services through the Angel process would be granted  to the following as well:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.TXRRS UACC(NONE)

Liberty Profile server IDs seeking access to MODIFY DUMP services through the Angel process would be granted  to the following as well:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE)