u s in g i b m z/o s p r o vi s i o nin g t o o lki t€¦ · chapter 1. what is z/os provisioning...

Using IBM z/OS provisioning toolkitVersion 1 Release 1

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 115.

This edition applies to the IBM z/OS Provisioning Toolkit, Version 1 Release 0 (product number 5655-CI1) and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this book . . . . . . . . . . . v

Chapter 1. What is z/OS ProvisioningToolkit? . . . . . . . . . . . . . . . 1How does z/OS Provisioning Toolkit work? . . . . 3What documentation is available for z/OSProvisioning Toolkit? . . . . . . . . . . . 4

Chapter 2. z/OS Provisioning Toolkitchange history . . . . . . . . . . . . 7

Chapter 3. Getting started with z/OSProvisioning Toolkit . . . . . . . . . 13Introduction to getting started with z/OSProvisioning Toolkit . . . . . . . . . . . 13Getting started with CICS by using z/OSMFworkflows . . . . . . . . . . . . . . . 14Getting started with CICS by using IBM CloudProvisioning and Management for z/OS. . . . . 17Getting started with other middleware . . . . . 21

Chapter 4. Security planning for z/OSProvisioning Toolkit . . . . . . . . . 23

Chapter 5. Prerequisites for using z/OSProvisioning Toolkit . . . . . . . . . 27

Chapter 6. Installing z/OS ProvisioningToolkit . . . . . . . . . . . . . . . 31

Chapter 7. Upgrading z/OSProvisioning Toolkit . . . . . . . . . 33

Chapter 8. Configuring z/OSProvisioning Toolkit . . . . . . . . . 35

Chapter 9. z/OS Provisioning Toolkitsupplied templates . . . . . . . . . 37

Chapter 10. Adding an IBM CloudProvisioning and Management for z/OStemplate for use with z/OSProvisioning Toolkit . . . . . . . . . 39

Chapter 11. z/OS Provisioning Toolkitimages. . . . . . . . . . . . . . . 41

Chapter 12. Building an image withz/OS Provisioning Toolkit. . . . . . . 43

Chapter 13. Running a z/OSProvisioning Toolkit image . . . . . . 45Link scenarios supported by z/OS ProvisioningToolkit . . . . . . . . . . . . . . . . 47

© Copyright IBM Corp. 2017 iii

Chapter 14. Managing z/OSProvisioning Toolkit images . . . . . 49

Chapter 15. Managing containerscreated by z/OS Provisioning Toolkit . . 51

Chapter 16. Using z/OS ProvisioningToolkit with z/OSMF compositetemplates . . . . . . . . . . . . . 55

Chapter 17. Automating provisioningwith z/OS Provisioning Toolkit . . . . 59

Chapter 18. The zospt command syntax 61

Chapter 19. Samples provided withz/OS Provisioning Toolkit. . . . . . . 65

Chapter 20. Troubleshooting z/OSProvisioning Toolkit . . . . . . . . . 69

Chapter 21. Provisioning CICS withz/OS Provisioning Toolkit. . . . . . . 75Configuration prerequisites for using z/OSProvisioning Toolkit with CICS . . . . . . . . 75Overview of supported CICS types . . . . . . 76Adding a CICS template by using IBM CloudProvisioning and Management for z/OS. . . . . 77Including a CICS bundle in your image . . . . . 80Security requirements for provisioning CICS withz/OS Provisioning Toolkit . . . . . . . . . 82

Modifying the CICS workflows to support dynamicsecurity. . . . . . . . . . . . . . . . 83Configuration properties for CICS images . . . . 84Modifying the set of CICS configuration propertiesthat can be overridden. . . . . . . . . . . 95Troubleshooting CICS provisioning with z/OSProvisioning Toolkit . . . . . . . . . . . 96

Chapter 22. Provisioning z/OS ConnectEnterprise Edition with z/OSProvisioning Toolkit . . . . . . . . . 99Configuration prerequisites for using z/OSProvisioning Toolkit with z/OS Connect EnterpriseEdition . . . . . . . . . . . . . . . . 99Adding a z/OS Connect Enterprise Editiontemplate by using IBM Cloud Provisioning andManagement for z/OS . . . . . . . . . . 100Security requirements for provisioning instances ofz/OS Connect EE with z/OS Provisioning Toolkit . 103Modifying the z/OS Connect Enterprise Editionworkflows to support dynamic security . . . . 104Configuration properties for z/OS ConnectEnterprise Edition images . . . . . . . . . 106

Chapter 23. Registering existingsubsystems in z/OSMF . . . . . . . 111CICS registration information . . . . . . . . 112DB2 registration information . . . . . . . . 113IBM MQ registration information . . . . . . . 113

Notices . . . . . . . . . . . . . . 115

iv Using IBM z/OS provisioning toolkit

About this book

This PDF is the product documentation for IBM® z/OS® Provisioning Toolkit. Thesame documentation is provided in IBM Knowledge Center.

Date of this PDF

This PDF was created on April 27th 2018.

© Copyright IBM Corp. 2017 v

vi Using IBM z/OS provisioning toolkit

Chapter 1. What is z/OS Provisioning Toolkit?

z/OS PT is a command line utility for the rapid provisioning of developmentruntime environments. System programmers can set up the environments that canbe provisioned in this way, authorize access to individuals or teams, and setprovisioning controls and limits. By using a command line interface, applicationdevelopers can quickly and independently provision and deprovision z/OSdevelopment environments, without needing mainframe administration skills orauthority.

DevOps tools and processes allow development and operations teams tocollaborate on reducing time to delivery. Automation is critical to an efficientdevelopment process. z/OS Provisioning Toolkit helps to automate thedevelopment process by providing application developers with immediate accessto the environments that they need, while the operations team retains overallcommand and control of the provisioning process.

z/OS Provisioning Toolkit has three main elements:1. Command line utility. z/OS PT provides commands to allow an application

developer to build an application image, run that image, and provision (and,later, deprovision) the underlying middleware environment. For some of theincluded commands, see the following list:v zospt build Build an application image.v zospt run Run an application image and automatically provision and start

the associated z/OS middleware.v zospt ps List environments that are provisioned.v zospt rm Deprovision an environment.

2. Scripts called zosptfiles and associated images. zosptfiles define theenvironments that can be provisioned. z/OS PT provides sample scripts andimages to make it quicker to set up the foundation of commonly usedenvironments, for example CICS® or IBM z/OS Connect Enterprise Edition.

3. z/OSMF workflows. The toolkit uses two features of z/OS to enforce controlover provisioned environments. You can define workflows in z/OSMF that canprovision runtime environments. You can manage and control these workflowsby using IBM Cloud Provisioning and Management for z/OS. The workflowscan be customized to local naming standards and operating procedures. z/OSPT drives these workflows.v For a list of workflows that are supplied by z/OS PT, see Chapter 9, “z/OS

Provisioning Toolkit supplied templates,” on page 37.v For an overview of provisioning and management of z/OS middleware and

how z/OSMF fits into the solution, see IBM Cloud Provisioning andManagement for z/OS: An Introduction.

To go a little deeper into the architecture and components, see “How does z/OSProvisioning Toolkit work?” on page 3.

Build, run, manage

Systems programmers can define software templates in z/OSMF. These templatesspecify the z/OSMF workflows, and definitions to be used by the workflows, toprovision middleware systems. The workflows can be configured to support local

© Copyright IBM Corp. 2017 1

http://www.redbooks.ibm.com/abstracts/redp5416.html

http://www.redbooks.ibm.com/abstracts/redp5416.html

naming standards and operating procedures. Appropriate provisioning controlsand limits can be set by using IBM Cloud Provisioning and Management for z/OS,including how many environments can be provisioned through z/OS PT.Individual application developer user IDs, or a group of user IDs, can be grantedaccess to run these templates, within defined controls and limits.

After the operations team configures the z/OSMF templates, applicationdevelopers can use the z/OS PT command line utility to issue simple command toprovision z/OS environments, for example, a CICS region or an instance of z/OSConnect Enterprise Edition. Application developers can share a single installationof z/OS PT, including images.

z/OS PT provisioning support

z/OS PT supports provisioning of a range of environments, by providing examplescripts and images and z/OSMF workflows. The flexible nature of a z/OSMFworkflow means that more tools and third-party products that are needed by theenvironments can be automatically configured and provisioned at the same time.

Images are included with the product for provisioning the following environments:v CICS Transaction Server, with embedded IBM z/OS Connect Enterprise Editionv CICS Transaction Server, with a Liberty JVM serverv A standard CICS TS environment for traditional COBOL 3270 developmentv z/OS Connect Enterprise Edition V2.0 stand-alone serverv z/OS Connect Enterprise Edition V3.0 stand-alone server

Try z/OS PT for yourself

Download z/OS PT without charge from IBM z/OS Provisioning Toolkit productpage.

z/OS PT provides a getting started scenario that enables CICS systemprogrammers to quickly evaluate the CICS workflows that are provided forprovisioning and deprovisioning a CICS region before they try z/OS PT withCloud Provisioning. For more information, see “Getting started with CICS by usingz/OSMF workflows” on page 14.

2 Using IBM z/OS provisioning toolkit

https://developer.ibm.com/mainframe/products/zospt/


How does z/OS Provisioning Toolkit work?z/OS PT interacts with z/OSMF to provision containers that are ready for use byusing images. z/OS PT has many artifacts and components, and these componentsare used in a certain sequence.

The components of z/OS PT

z/OSMFIBM z/OS Management Facility, with the IBM Cloud Provisioning andManagement for z/OS capability and z/OSMF workflows, are the toolsthat z/OS PT uses to provision containers.

WorkflowA workflow in z/OSMF is an XML document that is made up of one ormore steps, each one typically making a REST API call, or running JCL.The z/OSMF workflows can be customized to local naming standards andoperating procedures by editing a *.properties file.

*.properties fileThis text file sets values for the variables that are used by the z/OSMFworkflow, for example, the configuration options that you want to set in aprovisioned CICS region.

TemplateThe template is an artifact in z/OSMF. The template describes how toprovision a middleware instance that uses a z/OSMF workflow, anddescribes any definitions to be associated with that workflow. z/OS PTprovides templates for provisioning IBM middleware, such as CICS andIBM MQ.

Figure 1. Introducing the z/OS Provisioning Toolkit

Chapter 1. What is z/OS PT? 3

zosptfileThis text file tells z/OS PT what to put in an image when the zosptcommand is used.

Image An image is a preconfigured environment. Think of images as blueprintsthat can be rapidly provisioned to create runtime environments. An imageis a binary object that encapsulates a set of files and configuration, asdefined by the zosptfile. Each image is associated with a z/OSMFtemplate. The set of files and configuration in the image is used, with theassociated z/OSMF template, to provision one or more containers with thesame capabilities. An image can also have a dependency on another image- a base image - that has an association with a z/OSMF template, withoutneeding a separate association. For more information about the value ofimages, see Chapter 11, “z/OS Provisioning Toolkit images,” on page 41.

ContainerThe result of provisioning with z/OS PT is a container, with all thecapabilities of an associated image. The container encapsulates anapplication and its dependencies, making an environment that is ready foryou to work in.

The z/OSMF documentation refers generally to software provisioned froma template as an "instance".

The flow of z/OS PT

z/OS PT provides a getting started scenario that enables CICS systemprogrammers to quickly evaluate the CICS workflows that are provided forprovisioning and deprovisioning a CICS region before they try z/OS PT withCloud Provisioning. For more information, see “Getting started with CICS by usingz/OSMF workflows” on page 14.

For a full, dynamic scenario, a system programmer defines a template in z/OSMF,associates it with a workflow and specifies (in a *.properties file) any values to beused for variables in the workflow.

In z/OS, application developers use the zospt build command to build an image.They specify a configuration file that is called a zosptfile to associate the imagewith a z/OSMF template and provide any additional configuration. Then, they usethe zospt run command to create a container from the image. They each can workin a container, and manage its lifecycle with z/OS PT commands to start, stop, anddeprovision.

What to do next?

To start to explore z/OS PT, go to Chapter 6, “Installing z/OS ProvisioningToolkit,” on page 31. To understand more about how z/OSMF works, see thez/OSMF documentation.

What documentation is available for z/OS Provisioning Toolkit?z/OS PT provides product documentation (in IBM Knowledge Center and as PDF),and other sources of information. Command help is provided in z/OS PT itselfand a readme file is included in the z/OS PT download package. You can also findarticles and examples in Developer Centers and tips in dW Answers.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.izua300/IZUHPINFO_OverviewMain.htm

Product documentation in IBM Knowledge Center and PDF

If you are reading this document in PDF, you can find z/OS PT documentation inIBM Knowledge Center at z/OS Provisioning Toolkit in IBM Knowledge Center.This documentation is updated with every release of z/OS PT, and mightoccasionally be updated between releases to address issues.

z/OSMF documentation is also available in IBM Knowledge Center.

If you are reading this document in IBM Knowledge Center, you can find a PDFfile of documentation for download alongside the z/OS PT package. This PDFcontains the same documentation that you find in IBM Knowledge Center, in adifferent format.

Readme file and command help

z/OS PT contains command help. To access all the command help, type zospt--help. For help about a specific command, type zospt command --help.

A readme file is provided in the download package with initial instructions andlinks to the documentation that you need to work with z/OS PT.

Other sources of information

Developer Centers contain articles and examples to extend the documentationabout z/OS PT:v IBM z/OS Provisioning Toolkit product page gives you links to the latest news

and to download z/OS PT.v Mainframe Developer Center includes news about z/OS PT as part of the range

of IBM products that support DevOps.v CICS Developer Center covers the role of z/OS PT in provisioning and

managing CICS environments.v z/OS Connect EE Developer Center includes information about provisioning

z/OS Connect EE instances by using z/OS PT.v dW Answers is an open forum for questions and answers about IBM products.

Questions about z/OS PT are tagged with zospt.

Tell the z/OS PT team what you think

The z/OS PT team welcome your comments on the z/OS PT productdocumentation. The documentation is refreshed regularly in response to feedback,so get in touch through the "Contact us" option in IBM Knowledge Center, or inMainframe Developer Center.

Conventions used in this documentation

The following conventions are used to document z/OS PT syntax:

Notation Explanation

zospt A command. Square brackets indicate an optional parameter, for example:[-option]

variable Variables appear in lowercase. They represent names or values that yousupply.

Chapter 1. What is z/OS PT? 5

https://www.ibm.com/support/knowledgecenter/SSXH44E_1.0.0/zospt/welcome.html



https://developer.ibm.com/mainframe/

https://developer.ibm.com/cics/

https://developer.ibm.com/mainframe/products/zosconnect/

https://developer.ibm.com/answers

https://developer.ibm.com/mainframe/

Accessibility

Documentation that is provided with z/OS PT is accessible. Information about theaccessibility features of IBM® Knowledge Center can be found in the IBMKnowledge Center Release Notes. In addition to the accessibility of the onlineframework, the content of the z/OS PT documentation itself is adapted to beaccessible; all images that convey additional information have alternative text.


http://www.ibm.com/support/knowledgecenter/about/releasenotes.html

http://www.ibm.com/support/knowledgecenter/about/releasenotes.html

Chapter 2. z/OS Provisioning Toolkit change history

Use this information to discover the functions and properties that are added oraltered, in each version, release, or modification of IBM z/OS Provisioning Toolkit.

Table 1. Function and properties updates

Version number Function and properties updates

27 April 2018

v1.1.1 Function

v New samples and workflows to provision CICS with minimalprerequisites to get started with provisioning. For moreinformation about getting started, see Chapter 3, “Getting startedwith z/OS Provisioning Toolkit,” on page 13.

v Support for starting and stopping the Composite_Parent containerusing the zospt start and zospt stop commands. Starting orstopping the Composite_Parent container starts or stops theComposite_Child containers in the correct order.

26 January 2018


Table 1. Function and properties updates (continued)


v1.1 Function

v Update to DFH_CICS_TYPE to support values CMAS and WUI (inaddition to current supported values of MAS, SMSS andUnmanaged). For more information about supported CICS types,see “Overview of supported CICS types” on page 76.

v Addition of the --quiet option on the zospt run command toallow the provision and deprovision of containers to beautomated. For more information about the --quiet option, seeChapter 17, “Automating provisioning with z/OS ProvisioningToolkit,” on page 59.

v Support to build, run, and manage containers that areprovisioned from composite templates that are created inz/OSMF 2.2 onward. For more information about compositetemplates, see Chapter 16, “Using z/OS Provisioning Toolkit withz/OSMF composite templates,” on page 55.

v Support for starting and stopping multiple containers by usingthe zospt start and zospt stop commands.

v Support for specifying the containerName of a provisionedcontainer on the zospt run command.

v Support for allowing a subset of configuration properties that areset in the template to be overridden in the z/OS PT image. Formore information about overriding CICS properties, see“Modifying the set of CICS configuration properties that can beoverridden” on page 95.

New and updated configuration properties for CICS

v DFH_ZOS_PROCLIB now specifies the complete data set name of aprocedure library (PROCLIB). The workflow no longer appends.PROCLIB to the end of this value.

v DFH_ZOS_STCJOBS now specifies the complete data set name of adata set into which started task JCL jobs can be created. Theworkflow no longer appends .STCJOBS to the end of this value.

v DFH_DELETE_LOGSTREAM_TIMEOUT customizes the amount of timethe workflow waits to detect successful deletion of the CICS logstreams.

Removed configuration properties for CICS

v DFH_CONSOLE_SEARCH_SPACES is no longer required and is ignoredif a value is provided.

10 October 2017




v1.0.3 Function

v Link a provisioned CICS image to:

– A registered DB2® container.

– A registered IBM MQ container.

– Both a registered DB2 container and a registered IBM MQcontainer.

v Link a provisioned z/OS Connect EE image to a provisioned orregistered CICS container.

v For more information about supported link scenarios, see “Linkscenarios supported by z/OS Provisioning Toolkit” on page 47.

v Register existing subsystems in z/OSMF (for more information,see Chapter 23, “Registering existing subsystems in z/OSMF,” onpage 111.

v Provision a CICS region from an image that includes a CICSbundle (for more information, see “Including a CICS bundle inyour image” on page 80.

v Provision a CICS region with a JVM that is configured for remotedebug.

v Support for filtering the list of containers in command zospt ps.

v Support for removing images by using the zospt rmi command.

v Support for removing multiple containers by using the zospt rmcommand.

v Define a job in an STCJOBS data set for the started task of theprovisioned CICS region.

v Define a job in an STCJOBS data set for the started task of theprovisioned instance of z/OS Connect EE.

v Enhanced validation of the user ID that is specified for theDFH_ADMIN_CONSOLE property to determine whether theconsole API can be used to detect unsolicited messages.


v DFH_JVM_DEBUG

v DFH_ZFS_GROUP

v DFH_ZOS_STCJOBS

v DFH_STC_JOB_CARD

v DFH_REGION_LOGSTREAM_HLQ

v DFH_ZFS_DATACLASS

New and updated configuration properties for z/OS Connect EE

v ZCON_ZOS_STCJOBS

v ZCON_STC_JOB_CARD

17 July 2017

Chapter 2. z/OS PT change history 9



v1.0.2 Function

v Provision a CICS region with a shared CSD by using suppliedworkflows. For more information about using a shared CSD, see“Shared CSD guidance” on page 94.

v CICS samples updated to support CICS Transaction Server forz/OS, V5.4.

v Support for provisioning z/OS Connect Enterprise Edition V3.0by using supplied workflows.

v Provision a CICS region with an IPIC port (for example to enablea stand-alone instance of z/OS Connect EE V3.0 to connect to aprovisioned CICS region by using the new CICS serviceprovider).

v Provision z/OS software subsystems and services on any LPARin a Parallel Sysplex®

v The z/OS PT documentation PDF is now available directly fromthis IBM Knowledge Center, see z/OS Provisioning Toolkit PDF.

New configuration properties for IBM z/OS Provisioning Toolkit

v New zospt_pw environment variable can be set to enable z/OS PTto be used in a script without prompting for a password.

v New logging.properties file for configuring z/OS PT log sizeand count that contains the following properties:

– java.util.logging.FileHandler.limit

– java.util.logging.FileHandler.count

For more information about these properties, see Chapter 8,“Configuring z/OS Provisioning Toolkit,” on page 35.


v DFH_REGION_CSD_TYPE

v DFH_REGION_SHARED_CSD_NAME

v DFH_REGION_CSD is renamed DFH_REGION_CSD_INPUT

v DFH_REGION_IPIC

v TEMP_DIR

v VALIDATE_PARAMETERS

New configuration properties for z/OS Connect EE

v TEMP_DIR

v VALIDATE_PARAMETERS

11 April 2017




v1.0.1 Function

v Provision stand-alone z/OS Connect EE servers by usingsupplied workflows.

v Provision Liberty servers. For more information, and for sampleworkflows, see ..

v Enhanced inspect command to get information on provisionedcontainers. For more information about the inspect commandsyntax, see Chapter 18, “The zospt command syntax,” on page 61.

v Truststore support for connecting to z/OSMF from the commandline utility.

New configuration properties for IBM z/OS Provisioning Toolkit

v Added to the zosmf.properties file:

– truststore

– truststore_password

For more information about these properties, see Chapter 8,“Configuring z/OS Provisioning Toolkit,” on page 35.

New configuration properties for CICS

v DFH_CONSOLE_SEARCH_SPACES

v DFH_START_TIMEOUT

v DFH_STOP_TIMEOUT

10 January 2017

v1.0.0 Function

v z/OS PT is a simple command line utility for the rapidprovisioning of z/OS development environments. Use z/OS PTto build an image, run an image to create a container, and thenmanage that container by using simple commands.

v These commands are the currently supported z/OS PTcommands:

– zospt build

– zospt run

– zospt rm

– zospt inspect

– zospt images

– zospt ps

v Provision a CICS region by using supplied workflows.

v Provision an IBM MQ queue manager (workflows are includedwith IBM MQ V9.0.1 for z/OS).

v Examples for different CICS applications, including provisioningembedded z/OS Connect EE, Liberty, and Web services.

Chapter 2. z/OS PT change history 11

https://github.com/WASdev/sample.zos.provision.wlp

Chapter 3. Getting started with z/OS Provisioning Toolkit

z/OS PT provides different ways to get started, depending on the kind ofmiddleware that is used. Use this topic as a guide to find out what information,and samples are provided with z/OS PT.

Introduction to getting started with z/OS Provisioning ToolkitUse this topic to see what is provided by z/OS PT to help you get started withdifferent kinds of middleware.

Getting started with CICS

This diagram shows the progression between the different CICS scenarios that areavailable. This is a way for a system programmer to assess the technology, beforemaking z/OS PT available to application developers for self-service provisioning.

z/OS PT provides a simple getting started scenario that enables CICS systemprogrammers to quickly evaluate the CICS workflows that are provided forprovisioning and deprovisioning a CICS region before trying z/OS PT with CloudProvisioning. By using the “Getting started with CICS by using z/OSMFworkflows” on page 14 scenario, you run a workflow to provision a CICScontainer. The CICS container is not registered with the Cloud Provisioningsoftware services catalog as Cloud Provisioning isn't enabled.

A CICS system programmer can then progress to “Getting started with CICS byusing IBM Cloud Provisioning and Management for z/OS” on page 17, that usesCloud Provisioning, but with a pre-defined CICS region APPLID. This scenariouses the same CICS configuration as the previous scenario, which allows the

Figure 2. Progression between CICS scenarios


system programmer to try Cloud Provisioning. The CICS container is registeredwith the Cloud Provisioning software services catalog as Cloud Provisioning isenabled.

z/OS PT provides a set of sample templates, that can be used with the full,dynamic, Cloud Provisioning CICS scenario, as described in “Adding a CICStemplate by using IBM Cloud Provisioning and Management for z/OS” on page77. This scenario allows an application developer to provision CICS containers in aself-service way, without requiring any z/OS specific administration skills. Theprovisioning process runs under one or more automation user IDs, and APPLIDsand ports are dynamically allocated when required.

Getting started with z/OS Connect EE

z/OS PT provides a set of sample templates, that can be used with the full,dynamic, Cloud Provisioning z/OS Connect EE scenario, as described in “Addinga z/OS Connect Enterprise Edition template by using IBM Cloud Provisioning andManagement for z/OS” on page 100. This scenario allows an application developerto provision instances of z/OS Connect EE in a self-service way, without requiringany z/OS specific administration skills. The provisioning process runs under oneor more automation user IDs, and ports are dynamically allocated when required.

Getting started with other middleware

z/OS PT supports templates for provisioning the following products:v IBM MQ V9.0 (the IBM MQ V9.0 template is supplied with IBM MQ V9.0). For

more information, see Using IBM z/OSMF to automate IBM MQ.v WebSphere® Liberty (to download the WebSphere Liberty template, follow this

link WebSphere Liberty workflow in GitHub.

For more information about how to load these templates into z/OSMF, seeChapter 10, “Adding an IBM Cloud Provisioning and Management for z/OStemplate for use with z/OS Provisioning Toolkit,” on page 39.

Getting started with CICS by using z/OSMF workflowsThis scenario takes a system programmer through the steps that are involved inprovisioning a simple, single CICS container, by using z/OS PT to run thez/OSMF workflows. Use these instructions to quickly provision a container beforeyou try z/OS PT with IBM Cloud Provisioning and Management for z/OS. Thisscenario helps you to get familiar with the artifacts you need to provision acontainer, the z/OS PT command line, and the provisioning lifecycle.

Before you begin

Before you provision a container by using z/OSMF workflows, do the followingthings.v Ensure that z/OSMF is installed.v Ensure that the system programmer user ID has the appropriate authority to run

workflows, by granting it the following access:– READ access to the ZMFAPLA class SAF-

prefixZOSMF.WORKFLOW.WORKFLOWS.– READ access to EJBROLE SAF-prefixIzuManagementFacilityWorkflow.izuUsers

For more information, see Security configuration requirements for z/OSMF.


https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.con.doc/q019925_.html


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.izua300/izuconfig_SecurityStructuresForZosmf.htm#DefaultSecuritySetupForZosmf__SecuritySetupRequirementsForCoreFun

v Ensure that:– The system programmer user ID has authority to start a CICS region as a

started task.– The system programmer user ID has sufficient authority in a test environment

to:- Allocate data sets.- Create and delete log streams.- Add a procedure into a PROCLIB.- Issue console commands.

v Install z/OS PT by following the instructions here: Chapter 6, “Installing z/OSProvisioning Toolkit,” on page 31.

About this task

This task walks a system programmer through provisioning a simple, single CICScontainer by using the z/OSMF workflows. Every step in this task runs under thesystem programmer's user ID. A JES job is submitted for every step, and thesystem programmer can see the output from the JES jobs, and the source JCL.Being able to view the source and the output helps the system programmer tobecome familiar with how the workflow provisioning process works.

Procedure1. Connect z/OS PT to z/OSMF.v Edit the z/OS PT zosmf.properties UTF-8 file. Find the file in the

/zospt/config directory. Update the following properties to use the z/OSMFworkflows:

portThe HTTPS port that z/OSMF listens on.

hostnameIf you are running z/OS PT on the same LPAR that the z/OSMF serveris running on, set hostname=localhost . To use a host name of localhost,configure z/OSMF to listen for requests on localhost by specifyingHOSTNAME(*) in the IZUPRMxx parmlib member that contains configurationvalues for your z/OSMF server. Otherwise, specify the host name.

systemNicknameSpecify this property to set the nickname of the system on which theprovisioning workflows are to run. If your user ID has authority to seethem, the zospt ps -a command reports available system nicknames.

v Check that z/OS PT connects to z/OSMF by issuing the command:zospt ps -az/OS PT reports back basic information about the z/OSMF server.2018-04-21 17:03:01 IBM z/OS Provisioning Toolkit V1.1.12018-04-21 17:03:05 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2018-04-21 17:03:06 z/OS level is V2R3.2018-04-21 17:03:06 z/OS Management Facility level is V2R3.2018-04-21 17:03:06 z/OSMF system nicknames are MV01, MV02, MV03, MV04, MV05, MV06, MV07, MV08, MV09.2018-04-21 17:03:06 Getting started workflows will run on the system with nickname MV01.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPE

2. Customize the CICS region to provision by editing the z/OS PTcics.properties file and modifying the properties to meet your namingstandards. Find the file in the zospt/templates/cics_getting_started directory.The cics.properties file contains a list of CICS properties that are needed forthis scenario, and information about each property that needs to be set. This list

Chapter 3. Getting started with z/OS PT 15

of properties is a subset of the full list of CICS properties. For more informationabout configuring the cics.properties file, see “Configuration properties forCICS images” on page 84.

3. Run the cics_getting_started_workflow image by issuing command:zospt run cics_getting_started_workflowIf the provision is successful, you see the following output:2018-04-23 16:02:35 IBM z/OS Provisioning Toolkit V1.1.12018-04-23 16:02:35 Running image cics_getting_started_workflow.2018-04-23 16:02:35 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2018-04-23 16:02:37 Creating container USERTEST with id nzmay83vng8o4k9vkklaaxk8z4onwpdy on system MV01.2018-04-23 16:02:43 Validating allowed properties for CICS getting started workflows - Complete...2018-04-23 16:03:57 Starting the CICS region - Complete.2018-04-23 16:03:58 DFH_REGION_APPLID : USERTEST2018-04-23 16:03:58 DFH_CICS_TYPE : Unmanaged2018-04-23 16:03:58 Created container USERTEST with id nzmay83vng8o4k9vkklaaxk8z4onwpdy on system MV01.2018-04-23 16:03:58 Container USERTEST has been started.

You can also run command:zospt psto view your provisioned container, and to see it has a container type ofWorkflow:2018-04-26 11:41:21 IBM z/OS Provisioning Toolkit V1.1.12018-04-26 11:41:24 Connecting to z/OSMF on host localhost port 32000.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPEUSERTEST cics_getting_started_workflow user01 2018-04-26T11:34:56 provisioned N/A MV01 Workflow

If the provision fails, the output contains the following diagnosis information,most importantly, the job information:...2018-04-23 16:38:56 ERROR: The request failed to complete.2018-04-23 16:38:56 IZUWF0150E: The job that was submitted in step "Validating access to CICS data sets" failed during automation processing. Return code: "CC 0004" .2018-04-23 16:38:56 Workflow Name : provision_USERTEST_15235439188252018-04-23 16:38:56 Job Information : JOBNAME: IZUWFJB, JOBID: JOB25101, CC 00042018-04-23 16:38:56 Current Step Title : Validating access to CICS data sets...

If the run fails, as the workflow steps submit JES jobs under the systemprogrammer's user ID, the system programmer can use the information that isreturned in the failure to examine the job output and find the problem.a. View the JES job to diagnose the error. Find the job and view the output for

the failing job step. The system programmer can also view the source JCLfor any of the jobs, as the jobs all run under the system programmer's userID. Use this information to diagnose and fix the error.

b. Deprovision the failed container. Use commandzospt rm -f containerName(where containerName is USERTEST in this example). The output shows asuccessful deprovision.2018-04-23 17:00:22 IBM z/OS Provisioning Toolkit V1.1.12018-04-23 17:00:22 Performing deprovision on container USERTEST.2018-04-23 17:00:28 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2018-04-23 17:00:35 Container USERTEST has been deleted.2018-04-23 17:00:35 Deletion of environment completed successfully.2018-04-23 17:00:35 Removal of all containers completed successfully.

c. Rerun the zospt run command. Issue z/OS PT command zospt runcics_getting_started_workflow.


Results

You successfully connected z/OS PT to z/OSMF, customized the CICS region, andused the z/OS PT command line interface to provision and deprovision a CICScontainer.

What to do next

Before you move on to trying a scenario that uses Cloud Provisioning, you can tryadding further customization to the cics.properties file. To do so, follow thesesteps:1. Try out the other zospt commands. For more information about the other zospt

commands, see Chapter 18, “The zospt command syntax,” on page 61.2. Deprovision your CICS container by using command zospt rm -f

containerName (where containerName is USERTEST in this example).3. Change some properties in the cics.properties file to configure your CICS

region, for example, setting SIT parameters or DFHRPL concatenation. Formore information, see “Optional CICS properties” on page 90.

4. Reissue the zospt run command.

When you are ready, you can move on to “Getting started with CICS by using IBMCloud Provisioning and Management for z/OS,” which uses the same workflowsand configuration, but introduces Cloud Provisioning. Before you start thisscenario, you must deprovision your CICS container by using command:zospt rm -f containerName (where containerName is USERTEST in this example).

Getting started with CICS by using IBM Cloud Provisioning andManagement for z/OS

This scenario takes a system programmer through the steps that are involved inprovisioning a simple, single CICS container, by using z/OS PT and IBM CloudProvisioning and Management for z/OS. This scenario uses the same set ofworkflows and properties as in the 'Getting started with CICS by using z/OSMFworkflows' topic. The only thing that is different in this scenario is the introductionof Cloud Provisioning. This scenario is a way for system programmers to becomefamiliar with Cloud Provisioning before they use the capability to enableself-service for application developers. For more information about the capabilitiesof Cloud Provisioining, see the topic titled 'What is z/OS PT?'.

Before you begin

Before you provision a container by using Cloud Provisioning, do the followingthings.v Follow the steps in “Getting started with CICS by using z/OSMF workflows” on

page 14 to customize the properties for the workflows, and to configureconnectivity from z/OS PT to z/OSMF.

v Ensure that IBM Cloud Provisioning and Management for z/OS is installed andconfigured. For more information, see Preparing to use Cloud Provisioning.

v Request access from your z/OSMF system administrator to a domain to whichyour template can be added. This scenario uses the default domain that iscreated during the Cloud Provisioning installation process. For moreinformation, see Chapter 4, “Security planning for z/OS Provisioning Toolkit,”on page 23.


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua300/izuconfig_CloudProvSecuritySetup.htm

v Ensure that the system programmer's user ID is a domain administrator inz/OSMF.

v Ensure that you deprovisioned the CICS container that is used in “Gettingstarted with CICS by using z/OSMF workflows” on page 14, as you need theAPPLID for this scenario.

About this task

In this task, you add a Cloud Provisioning template in z/OSMF from which aCICS region can be provisioned. The provisioning process runs under the systemprogrammer's user ID.

Procedure1. Add the Cloud Provisioning template into z/OSMF. From a web browser,

connect to the z/OSMF Web Interface.a. Click Cloud Provisioning, then Software Services, then Templates. Click

Add Template > Standard.

b. In the resulting dialog box, complete Template Source file to point z/OSMFat the manifest file for the CICS getting started template:zospt/templates/cics_getting_started/cics.mf. z/OSMF must be able toread from this directory tree. Click Load. The fields for Workflow file,Actions file, and Workflow variables input file are populatedautomatically.

c. Name your template as cics_getting_started.

Note: By naming your template cics_getting_started you can use thistemplate with the provided sample z/OS PT image.


d. Click OK.

The template is loaded into z/OSMF in Draft state.2. Associate the template with a tenant in the domain to determine the set of

users that is able to run the template:a. Select the cics_getting_started template. From the Actions menu, select

Associate Tenant.


b. Select the tenant that your z/OSMF administrator specifies.c. Click OK.d. In the Add Template and Resource Pool for Tenant view, specify the

following properties and values:

Property Setting

Software servicesinstance name prefix

Specify a general name prefix, for example, “CGS” (for CICS getting started).

Maximum number ofsoftware servicesinstances

Specify 1 (one). The properties file for this template contains the CICS APPLID, so youcan have one CICS region active at a time. (When you run a fuller configuration asdescribed in “Adding a CICS template by using IBM Cloud Provisioning andManagement for z/OS” on page 77, this option controls the maximum number of regionsthat are allowed).

Maximum number ofsoftware servicesinstances for a user

Specify 1 (one). The properties file for this template contains the CICS APPLID, so youcan have one CICS region active per user at a time. (When you run a fuller configurationas described in “Adding a CICS template by using IBM Cloud Provisioning andManagement for z/OS” on page 77, this option controls the maximum number of regionsthat are allowed per person).

Specify customized JOBstatement JCL

Select this option. If you need to, you can customize the JOB statement. The jobstatement is applied to all JES jobs submitted as part of the provisioning process.

e. Click OK.


The template is now ready for use with z/OS PT.3. If you are not using the default domain and tenant, you must set the following

environment variables to set up the environment for z/OS PT:v export zospt_domain=domain_name

v export zospt_tenant=tenant_name

4. The template is in draft mode, which means only the creator can run thetemplate. Running the template in draft mode is a way of testing the templatebefore you publish it and allow other users to run it. Run the template in draftmode by issuing commandzospt run cics_getting_started_cloud --draft.2018-04-24 15:08:16 IBM z/OS Provisioning Toolkit V1.1.12018-04-24 15:08:16 Running image cics_getting_started_cloud.2018-04-24 15:08:16 The z/OSMF template used is cics_getting_started.2018-04-24 15:08:16 The z/OSMF domain is default.2018-04-24 15:08:16 The z/OSMF tenant is default.2018-04-24 15:08:16 Connecting to z/OSMF on host localhost port 32000.2018-04-24 15:08:17 The z/OSMF template cics_getting_started was created by USER01 at 2018-04-24T14:05:34.539Z. The template type is standard. It was last modified by USER01 at 2018-04-24T14:05:34.539Z.2018-04-24 15:08:19 Creating container CICS_CGS00 with id 4fcfd7f6-f377-458a-922e-61ae3365ccf5 on system MV01.2018-04-24 15:08:24 Validating allowed properties for CICS getting started workflows - Complete....2018-04-24 15:09:39 Starting the CICS region - Complete.2018-04-24 15:09:40 DFH_CICS_TYPE : Unmanaged2018-04-24 15:09:40 DFH_REGION_APPLID : IYK2ZLVR2018-04-24 15:09:41 Created container CICS_CGS00 with id 4fcfd7f6-f377-458a-922e-61ae3365ccf5 on system MV01.

You can also run command:zospt psto view your provisioned container:2018-04-26 13:57:29 IBM z/OS Provisioning Toolkit V1.1.12018-04-26 13:57:29 Connecting to z/OSMF on host localhost port 32000.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPEUSERTEST cics_getting_started_cloud user01 2018-04-26T12:56:03 provisioned cics_getting_started MV01 Standard

Results

You successfully added a Cloud Provisioning template into z/OSMF, associated thecics_getting_started template with a tenant in the domain, and ran the template.

What to do next1. Deprovision your CICS container by using command zospt rm -f

containerName.2. Build your z/OS PT knowledge by moving on to the next section of the

documentation, Chapter 4, “Security planning for z/OS Provisioning Toolkit,”on page 23, and continuing through the following sections.

3. When you are ready, move on to trying a full, dynamic scenario “Adding aCICS template by using IBM Cloud Provisioning and Management for z/OS”on page 77, which uses the provided sample template cics_54.

Getting started with other middlewareYou can provision other types of middleware by using z/OS PT. Some templatesare provided with z/OS PT, and others with IBM products.

z/OS PT templates for other middleware

z/OS PT provides templates for z/OS Connect EE.


v For more information about templates for z/OS Connect EE, see Chapter 19,“Samples provided with z/OS Provisioning Toolkit,” on page 65.

v For more information about how to load z/OS Connect EE templates inz/OSMF, see “Adding a z/OS Connect Enterprise Edition template by usingIBM Cloud Provisioning and Management for z/OS” on page 100.

Available templates for other middleware

z/OS PT supports templates for provisioning the following products:v IBM MQ V9.0 (the IBM MQ V9.0 template is supplied with IBM MQ V9.0). For

more information, see Using IBM z/OSMF to automate IBM MQ.v WebSphere Liberty (to download the WebSphere Liberty template, follow this

link WebSphere Liberty workflow in GitHub.

For more information about how to load these templates into z/OSMF, seeChapter 10, “Adding an IBM Cloud Provisioning and Management for z/OStemplate for use with z/OS Provisioning Toolkit,” on page 39.




Chapter 4. Security planning for z/OS Provisioning Toolkit

The security model for z/OS PT provides complete control over the provisioningprocess to ensure that only authorized users can provision environments.

Roles and authorities for setting up z/OSMF and IBM CloudProvisioning and Management for z/OS

z/OSMF has a security model with a number of roles that can perform differenttasks to enable Cloud Provisioning.

Table 2. z/OSMF Security roles

Role Function

Network administrator Defines the systems, TCP/IP stack, and pools of resources forCloud Provisioning. These pools include ports, APPLIDs, and IPaddresses. These pools are used by tenants and must be in placebefore a template can be run.

Security administrator Configures the security for all the IDs that are needed to completethe setup and running of Cloud Provisioning.

Landlord Defines the domain, domain administrators, and the systemresources for the domain.

Domain administrator Defines tenants, and associates templates with the tenants. Addsconsumers to the tenants.

Provisioning approver Has the authority to approve the IDs that are used in theworkflows to provision environments.

Consumer Has the authority to run templates in a tenant to provisionenvironments. Consumers do not usually need a high level ofauthority because the templates use provisioning IDs with theauthority to create an environment from scratch.

To work with z/OS PT, you need the following things:v Domain administrator authority to upload templates.v Consumer authority in z/OSMF to run templates.v All provisioning IDs and approval IDs specified in the templates to be

authorized by the provisioning approver.


Authority to run the z/OS PT command line interface

The command line interface is available on UNIX System Services and every userwho wants to use the toolkit needs permissions to access the z/OS PT installationdirectory. The permissions are described in Chapter 6, “Installing z/OSProvisioning Toolkit,” on page 31.

Certain commands use REST API calls to communicate with z/OSMF; for example,running an image or listing all the containers. Each user is prompted to enter auser ID and password to authenticate with z/OSMF before the command is run inz/OSMF.

Authority to create an environment

In the template properties file (for example ../zospt/templates/template_name/template_type.properties), you can set specific user IDs to have authority foreach workflow. This approach helps to retain control over which ID is used toperform steps in the workflow, for example, to mount zFS directories or create datasets.

In particular, Cloud Provisioning introduces a console services API that enablesworkflows to issue MVS™™ console commands. The API is used by workflowsduring the provisioning and deprovisioning process, as well as when starting andstopping containers. Create or identify a user ID that can be used by theworkflows to submit console API requests. Specify this userid in the templateproperties file and ensure that it has the appropriate security configuration asdescribed in the property.

When the workflow is uploaded to z/OSMF as part of a template, whoever isnamed as the approver for each step, must give their approval through thez/OSMF Web User Interface. A template cannot be published and run until all thesteps are approved.

Using this approach, developers can provision environments with a low-levelauthority because other IDs perform the steps in the workflow to provision an

Figure 3. Roles and authorities for setting up z/OSMF and Cloud Provisioning


environment. All owners of user IDs used in a workflow have visibility of how theIDs are being used and approve their usage.

Authority to create and run workflows

System programmers that want to upload templates require extra authority inz/OSMF. Becoming a Domain administrator provides this level of authority.System programmers require permissions to do the following tasks:v Upload templates.v Associate templates with tenants.v Refresh templates.v Delete templates.v Run workflows in all appropriate tenants.v View all template instances that are running.

Application developers require only Consumer authority to run workflows in atenant and query the environments that they provision. Typically, you can add agroup of user IDs to a tenant, for example a development team and supportingoperations team. All users in that tenant can run the associated workflows withinthe designated limits.

Configuring a truststore

The connection between z/OS PT and z/OSMF is made over HTTPS. z/OS PT canbe configured to use a truststore, enabling it to verify the identity of the z/OSMFserver before a secure connection is established. For more information, seeChapter 8, “Configuring z/OS Provisioning Toolkit,” on page 35.

Other permissions

Depending on the environment, some workflows might require you to configureextra security or permissions before they can be run by toolkit users:v For CICS permissions, see “Security requirements for provisioning CICS with

z/OS Provisioning Toolkit” on page 82.v For z/OS Connect EE permissions, see “Security requirements for provisioning

instances of z/OS Connect EE with z/OS Provisioning Toolkit” on page 103.

Workflows can also include security configuration, so you can comply with yourcompany standards around securing development environments.

Chapter 4. Security planning for z/OS PT 25

Chapter 5. Prerequisites for using z/OS Provisioning Toolkit

Before you use z/OS PT, you need to ensure that your system has the correctconfiguration. For z/OS PT prerequisites, and any subsystem-specific requirements,use the links that are provided here.

Prerequisites for getting started with CICS by using z/OSMFworkflows

Before you provision a container by using z/OSMF workflows, do the followingthings.v Ensure that z/OSMF is installed.v Ensure that the system programmer user ID has the appropriate authority to run

workflows, by granting it the following access:– READ access to the ZMFAPLA class SAF-

prefixZOSMF.WORKFLOW.WORKFLOWS.– READ access to EJBROLE SAF-prefixIzuManagementFacilityWorkflow.izuUsers

For more information, see Security configuration requirements for z/OSMF.v Ensure that:

– The system programmer user ID has authority to start a CICS region as astarted task.

– The system programmer user ID has sufficient authority in a test environmentto:- Allocate data sets.- Create and delete log streams.- Add a procedure into a PROCLIB.- Issue console commands.

v Install z/OS PT by following the instructions here: Chapter 6, “Installing z/OSProvisioning Toolkit,” on page 31.

For more information about the getting started scenario, see “Getting started withCICS by using z/OSMF workflows” on page 14.

Prerequisites for getting started with CICS by using IBM CloudProvisioning and Management for z/OS

Before you provision a container by using Cloud Provisioning, do the followingthings.v Follow the steps in “Getting started with CICS by using z/OSMF workflows” on

page 14 to customize the properties for the workflows, and to configureconnectivity from z/OS PT to z/OSMF.

v Ensure that IBM Cloud Provisioning and Management for z/OS is installed andconfigured. For more information, see Preparing to use Cloud Provisioning.

v Request access from your z/OSMF system administrator to a domain to whichyour template can be added. This scenario uses the default domain that iscreated during the Cloud Provisioning installation process. For moreinformation, see Chapter 4, “Security planning for z/OS Provisioning Toolkit,”on page 23.


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.izua300/izuconfig_SecurityStructuresForZosmf.htm#DefaultSecuritySetupForZosmf__SecuritySetupRequirementsForCoreFun

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua300/izuconfig_CloudProvSecuritySetup.htm

v Ensure that the system programmer's user ID is a domain administrator inz/OSMF.

v Ensure that you deprovisioned the CICS container that is used in “Gettingstarted with CICS by using z/OSMF workflows” on page 14, as you need theAPPLID for this scenario.

For more information about the getting started scenario, see “Getting started withCICS by using IBM Cloud Provisioning and Management for z/OS” on page 17.

Prerequisites for dynamically provisioning a CICS container

Before you dynamically provision a CICS container:

See the requirements in Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” on page39. In addition, you need:v A range of APPLIDs in a resource pool. (These APPLIDs can then be

dynamically allocated when you run z/OS PT).v A set of user IDs (agreed with your security administrator) that have sufficient

authority to provision a CICS environment. See “Security requirements forprovisioning CICS with z/OS Provisioning Toolkit” on page 82 for details.

v A range of ports in a resource pool. Ports can then be allocated to theprovisioned CICS regions.

For more information about the scenario, see “Adding a CICS template by usingIBM Cloud Provisioning and Management for z/OS” on page 77. For more CICSrequirements, see “Configuration prerequisites for using z/OS Provisioning Toolkitwith CICS” on page 75.

Prerequisites for dynamically provisioning an instance of z/OSConnect EE

Before you dynamically provision an instance of z/OS Connect EE:

See the requirements in Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” on page39. In addition, you need:v A range of ports in a resource pool. (These ports can then be dynamically

allocated when you run z/OS PT).v A set of user IDs (agreed with your security administrator) that has sufficient

authority to provision an instance of z/OS Connect EE. See “Securityrequirements for provisioning instances of z/OS Connect EE with z/OSProvisioning Toolkit” on page 103 for details.

For more information about the scenario, see “Adding a z/OS Connect EnterpriseEdition template by using IBM Cloud Provisioning and Management for z/OS” onpage 100. For more z/OS Connect EE requirements, see “Configurationprerequisites for using z/OS Provisioning Toolkit with z/OS Connect EnterpriseEdition” on page 99.

Prerequisites for provisioning other middleware

Before you add a Cloud Provisioning template, do the following things:


1. z/OSMF must have the IBM Cloud Provisioning and Management for z/OScapabilities installed.

2. A z/OSMF administrator (Landlord) must define a tenant with which thetemplate can be associated, and the domain to which that tenant belongs.z/OSMF comes with a default domain and default tenant.

3. A z/OSMF administrator (Landlord) must give you domain administratorauthority to enable you to add templates into the domain. If you are not able touse the default (supplied) domain, ensure that your user ID is added as adomain administrator to a domain that you can use.

4. You must ensure that you have user IDs with the correct level of authority tocomplete the workflow steps. You must have a user ID that can use thez/OSMF console API commands to issue MVS commands.

5. With the addition of APAR PI77388, z/OSMF can provision environmentsacross different systems within a sysplex. When you are using this capability,you must ensure that data set high-level qualifiers and zFS directories that areused during provisioning are available on all the systems to which you want toprovision environments. For more information about configuring z/OSMF forprovisioning across different systems, see z/OSMF documentation.

Configuration requirements

z/OS PT requires z/OS Management Facility (z/OSMF) and its IBM CloudProvisioning and Management for z/OS capability. For detailed systemrequirements and PTF prerequisites, refer to the z/OS Provisioning ToolkitSoftware Compatibility Report.

Chapter 5. Prerequisites for using z/OS PT 29


http://ibm.biz/BdiUbD


Chapter 6. Installing z/OS Provisioning Toolkit

z/OS PT is packaged as a compressed file and can be downloaded without charge.Install z/OS PT, ready for subsequent configuration.

Before you begin

Before you can install z/OS PT, ensure that you meet the system requirements thatare listed here Prerequisites for using z/OS Provisioning Toolkit.

Procedure1. Find z/OS PT for download on IBM z/OS Provisioning Toolkit product page.2. Extract the .zip file.3. Transfer the .pax file in binary format to the system where you want to run

z/OS PT.4. Issue the following command to extract the .pax file:

pax -rf zospt_v#######.pax

The zospt installation directory is created.5. Ensure that the user ID under which z/OSMF runs (the default user ID is

IZUSVR), has both read and execute permissions for all directories andsubdirectories in the zospt path. To change the permissions, issue thiscommand:chmod -R 755 zospt_install_dir

6. Ensure all user IDs under which you run zospt have the necessary permissions:v Read and run permissions for all directories in the zospt path.v Read, write, and run permissions for the images and logs directories in the

zospt path.7. Add zospt to the PATH. For quick access to the toolkit, issue the command:

export PATH=$PATH:<zospt directory>/bin

(where <zospt directory> is the full path of the z/OS PT installation directory).To persist the PATH declaration between sessions, add this command to your.profile file on z/OS UNIX System Services. For more information, seeCustomizing your .profile in the z/OS documentation.

8. Enter this command from the zospt directory:zospt --help

If the installation is successful, the command help prints to the command line.

Results

You successfully installed z/OS PT.

What to do next

You can now:v Return to “Getting started with CICS by using z/OSMF workflows” on page 14

and complete the scenario.



http://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.bpxa400/cupro.htm

v Prepare z/OSMF and z/OS PT to work together, by following the instructions inChapter 8, “Configuring z/OS Provisioning Toolkit,” on page 35.


Chapter 7. Upgrading z/OS Provisioning Toolkit

Find out more about the actions that you need to take to upgrade from one versionof z/OS Provisioning Toolkit to another.

Before you begin

Check the prerequisites of the new version of z/OS PT and any of the subsystemsthat you use with z/OS PT. Find information about prerequisites here Prerequisitesfor using z/OS Provisioning Toolkit.

Procedure1. Install the latest version of z/OS PT to a unique directory location to ensure

that you do not overwrite any template properties files, or other customizationsyou made to your environment, including modifying the dynamic securityscripts, and any custom images you built. Follow the installation instructionshere Chapter 6, “Installing z/OS Provisioning Toolkit,” on page 31. Return tothis upgrading procedure when you complete the installation instructions.

2. Examine any XML files, properties files, or REXX files that you modified foryour previous version of z/OS PT. These changes might need to be merged orcopied into the new installation directory. In particular, if you modified files inthe extensions directory for either the CICS or z/OS Connect EE workflows,you might need to copy those changes to the new installation directory, ormerge those changes with updated versions of those files in the newinstallation directory.

3. Refer to the Chapter 2, “z/OS Provisioning Toolkit change history,” on page 7for details on any new or updated properties that might need to be included inyour properties files to use the new templates.

4. Deprovision any systems that are provisioned from product-specific z/OSMFtemplates in Draft approved state before you refresh the templates to the newversion.

5. Refresh or load a new version of any product-specific templates from yourprevious version of z/OS PT. For more information about how to load az/OSMF template for use with z/OS PT, see Chapter 10, “Adding an IBMCloud Provisioning and Management for z/OS template for use with z/OSProvisioning Toolkit,” on page 39.

6. Change the PATH to point to the new version of z/OS PT.7. Rebuild any custom images with the new version of z/OS PT. For more

information about building images, see Chapter 12, “Building an image withz/OS Provisioning Toolkit,” on page 43. Reflect any changes that are made tothe sample zosptfiles in any zosptfiles you have that are based from thesamples.

What to do next

The new version of z/OS PT is ready to use. For more information aboutupgrading if you are using z/OS PT to provision CICS regions, see “Configurationprerequisites for using z/OS Provisioning Toolkit with CICS” on page 75.


Chapter 8. Configuring z/OS Provisioning Toolkit

To connect z/OS PT to z/OSMF, you must configure z/OS PT with basicconnectivity information for the z/OSMF server.

Procedure1. Edit the z/OS PT zosmf.properties UTF-8 file. Find the file in the

/zospt/config directory. The zosmf.properties file contains properties that areused to connect to z/OSMF:

hostnameThe host name, or IP address, of the system where z/OSMF is installed.The default is localhost.

portThe HTTPS port that z/OSMF listens on.

truststore = YES|NOUsing a truststore enables z/OS PT to check that it trusts the certificate ofthe z/OSMF server to which it attempts to connect.v The default of truststore=NO, means that when z/OS PT attempts to

connect to z/OSMF, z/OS PT always trusts the certificate that ispresented by the z/OSMF server during the SSL handshake.

v Specifying truststore=YES, means that z/OS PT checks that thecertificate (or a certificate authority that signed the z/OSMF server'scertificate) is present in its truststore. If the certificate is invalid, or is nottrusted, no connection is made.

Note: z/OS PT does not verify that the host name of the z/OSMF servermatches the host name that is identified in the z/OSMF server'scertificate.

A pre-configured truststore can be provided to z/OS PT. The truststoremust be of type JKS (Java™ keystore) and must be provided at thefollowing location: zospt/config/zosmf.jks. If no pre-configured truststoreis available, z/OS PT will ask the user whether to trust the z/OSMFserver's certificate and will create a truststore for future use. The user mustreview the certificate's details and determine whether it is acceptable forz/OS PT to trust the z/OSMF server. If the user agrees, the certificate thatidentifies the root certificate authority that signed the z/OSMF serverscertificate (or the z/OSMF servers certificate if it is self-signed) is added tothe truststore.

truststore_passwordSpecifies the password that is used to access the truststore.

systemNicknameSpecifies the nickname of the system. The nickname is only used when youprovision a container by using z/OSMF Workflows, as described in“Getting started with CICS by using z/OSMF workflows” on page 14, andis ignored byIBM Cloud Provisioning and Management for z/OS. You canask your system programmer for this information, or if your user ID is inthe security group for the z/OSMF users (IZUUSER, by default), you cansee a list of system nicknames by running z/OS PT command zospt ps -a.


2. Check that z/OS PT connects to z/OSMF. Issue zospt ps --all. z/OS PTprompts for a password and then reports back basic information about thez/OSMF server.

3. Optional: Set z/OS PT environment variables to further refine the connection toz/OSMF. The following environment variables can be set in the .profile in z/OSUNIX System Services, or as part of a shell script that runs z/OS PT:

zospt_domainSpecifies the z/OSMF domain with which to connect to run a template. Ifnot specified, the default domain is assumed.

zospt_tenantSpecifies the z/OSMF tenant with which to connect to run a template. Ifnot specified, the default domain is assumed.

zospt_pwSpecifies the password of the user that runs z/OS PT. If this environmentvariable is not set, the password is prompted for when z/OS PT is run andneeds to connect to z/OSMF.

4. Optional: Edit the z/OS PT logging.properties UTF-8 file. Find the file in the/zospt/config directory. The logging.properties file controls the size andnumber of log files that are created by z/OS PT. It is only necessary to changethese parameters if the default logging configuration is unsuitable. Thelogging.properties file contains properties that control the z/OS PT log sizeand count:

java.util.logging.FileHandler.limitSpecifies an approximate maximum amount to write (in bytes) to any onefile. The valid range is 0 - 2147483647 bytes. If it is set to zero, the numberof bytes that can be written has no limit. The default is 1000000 bytes.

java.util.logging.FileHandler.countSpecifies the number of log files to cycle through per user. The valid rangeis 0 - 2147483647 bytes. The default is 20. The logs are in the /logsdirectory. The most recent log file is named log_<userid running zospt>.0.

What to do next

Load a template into z/OSMF ready for use by the zospt commands, by followingthe instructions in Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” on page39.


Chapter 9. z/OS Provisioning Toolkit supplied templates

Templates are loaded into z/OSMF to enable the provisioning of runtimeenvironments. Each template consists of a set of workflows that are run toprovision an environment, or to perform an action on a provisioned environment,for example, starting, stopping, or deprovisioning. Templates are managed in theIBM Cloud Provisioning and Management for z/OS component of z/OSMF, andcan be run by z/OS PT. z/OS PT includes templates for provisioning CICS andz/OS Connect Enterprise Edition.

z/OS PT supplied templates and workflows

z/OS PT supplies and maintains the templates and workflows to provision anddeprovision the following products:v CICS Transaction Server unmanaged regionv CICS system-managed single server (SMSS)v CICSPlex® SM managed application system (MAS)v CICSPlex SM Web User Interface (WUI)v CICSPlex SM address space (CMAS)v z/OS Connect Enterprise Edition V2 or V3 server

The templates and workflows can be customized for specific customerenvironments by setting properties in a properties file. Before you use a z/OS PTsupplied template, review the list of customization properties:v For CICS, see “Configuration properties for CICS images” on page 84.v For z/OS Connect EE, see “Configuration properties for z/OS Connect

Enterprise Edition images” on page 106.

If you cannot find the customization that you need, make a request by using thefollowing link Request a feature.

How to use the supplied templates

Consider the following things when you use the z/OS PT supplied templates:v The supplied templates and workflows are written and maintained to provide

reliable provisioning and deprovisioning of a subsystem. It is important toalways run the deprovision action on a provisioned subsystem, regardless ofwhether the provision succeeded or failed. Deprovisioning provisionedsubsystems ensures that the artifacts that are created during provision of thesubsystem are deleted during deprovision, and that the LPAR is ready forfurther provisions to be run.

v By using the supplied templates and workflows without any modification, it iseasier to upgrade to later versions as they become available. If you have anyworkflow modification suggestions or requests, make a request by using thefollowing link Request a feature.

Other templates supported by z/OS PT

z/OS PT supports templates for provisioning the following products:


https://www.ibm.com/developerworks/rfe/?PROD_ID=1638

https://www.ibm.com/developerworks/rfe/?PROD_ID=1638

v IBM MQ V9.0 (the IBM MQ V9.0 template is supplied with IBM MQ V9.0). Formore information, see Using IBM z/OSMF to automate IBM MQ.

v WebSphere Liberty (to download the WebSphere Liberty template, follow thislink WebSphere Liberty workflow in GitHub.




Chapter 10. Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS ProvisioningToolkit

The foundation of provisioning with z/OS PT is a z/OSMF template. The templatepulls in the z/OSMF workflows and associated actions and variables that defineboth the environment to be provisioned, and how you want to provision it. Youload the template into z/OSMF by using the z/OSMF Web User Interface. Afteryou load a template, you can use z/OS PT to build an image based on thattemplate.

Before you begin

Before you add a Cloud Provisioning template, do the following things:1. z/OSMF must have the IBM Cloud Provisioning and Management for z/OS

capabilities installed.2. A z/OSMF administrator (Landlord) must define a tenant with which the

template can be associated, and the domain to which that tenant belongs.z/OSMF comes with a default domain and default tenant.

3. A z/OSMF administrator (Landlord) must give you domain administratorauthority to enable you to add templates into the domain. If you are not able touse the default (supplied) domain, ensure that your user ID is added as adomain administrator to a domain that you can use.

4. You must ensure that you have user IDs with the correct level of authority tocomplete the workflow steps. You must have a user ID that can use thez/OSMF console API commands to issue MVS commands.

5. With the addition of APAR PI77388, z/OSMF can provision environmentsacross different systems within a sysplex. When you are using this capability,you must ensure that data set high-level qualifiers and zFS directories that areused during provisioning are available on all the systems to which you want toprovision environments. For more information about configuring z/OSMF forprovisioning across different systems, see z/OSMF documentation.

About this task

For a reminder of how templates work with z/OS PT, see Chapter 1, “What isz/OS Provisioning Toolkit?,” on page 1.

A summary of the work of preparing z/OSMF with templates for use with z/OSPT follows. For more information about how to complete each step, see z/OSMFdocumentation.

For a walk-through of the process that uses either a CICS or z/OS Connect EEtemplate, see the following links:v Using a CICS template as an example, see “Adding a CICS template by using

IBM Cloud Provisioning and Management for z/OS” on page 77.v Using a z/OS Connect EE template as an example, see “Adding a z/OS Connect

Enterprise Edition template by using IBM Cloud Provisioning and Managementfor z/OS” on page 100.





Procedure1. Prepare a template for use with z/OSMF. Use the properties file to customize

the workflow to create an environment that meets your company standards.2. Log on to the z/OSMF Web User Interface and add the template. Go to Cloud

Provisioning > Software Services and select the Templates tab. Select AddTemplate to add the template.

3. Ensure that all owners of the user IDs in the workflow approve the template.4. Associate the template with a tenant. When you do the association, you can set

limits for how many times the container can be provisioned and how manyeach user is allowed to provision. The association automatically creates aresource pool for the template and the network administrator is notified.

5. Make sure that the necessary network resources are allocated to the resourcepool for the template. This step must be completed by a network administrator.

6. After the template is approved and the network resources are allocated, test thetemplate before you publish it to users in the tenant. You can test the templateby building an image that references the template name and running the zosptrun command with the --draft option. If you are not using the default domainand tenant, you must update your .profile in z/OS UNIX System Services toadd the following environment variables:zospt_domain=zospt_domain_namezospt_tenant=zospt_tenant_name

For more information about building an image to run a template, seeChapter 12, “Building an image with z/OS Provisioning Toolkit,” on page 43.

7. After your testing is complete, use the z/OSMF Web User Interface to publishthe template for everyone in the tenant to use.

What to do next

Switch to z/OS PT to build images from the template that you loaded. SeeChapter 12, “Building an image with z/OS Provisioning Toolkit,” on page 43 fordetails.


Chapter 11. z/OS Provisioning Toolkit images

A z/OS PT image contains the configuration, application code, and environmentvariables for z/OS PT to rapidly provision a preconfigured environment that istailored to a specific user's requirements. An image names a template that is usedby z/OS PT to provision the middleware that is specified in the template. z/OS PTprovides a set of sample CICS and z/OS Connect EE images.

An overview of z/OS PT images

A z/OS PT image is a set of files and configuration that is built from a zosptfile,then used by z/OS PT to provision one or more containers with the samecapability. A z/OS PT image extends the configuration of a system that is definedby a template that you load into z/OSMF. The template contains a base set ofconfiguration that can be overridden in the images.

The value of using a z/OS PT image

z/OS PT enables users to build images to configure a middleware instance that isprovisioned from a z/OSMF template. The following are some of the benefits ofusing z/OS PT images:v Images enable a single z/OSMF template to be used to provision systems with

different configurations.v An image can contain zFS artifacts that are deployed to the file system and used

by the provisioned subsystem.v Images are reusable and can be run multiple times to achieve specific subsystem

configurations.v Images are easy to build and do not require reapproval of the template.v An application developer can build images on top of an image that is supplied

by the system programmer.

The subset of CICS properties that can be overridden in an image can becustomized. For more information, see “Modifying the set of CICS configurationproperties that can be overridden” on page 95.

z/OS PT supplied images

z/OS PT provides sample images in directory zospt/images, which are built fromthe corresponding sample zosptfile from directory zospt/samples. For moreinformation about the sample images that are provided with z/OS PT, see“Samples images and the source artifacts that are used to build them” on page 65.


Chapter 12. Building an image with z/OS Provisioning Toolkit

After templates are set up in z/OSMF, you use the zospt build command to buildan image. This image is a set of files and configuration that are used with anassociated z/OSMF template to provision one or more containers with the samecapability. You need to set up the script file that is called zosptfile, then run thezospt build command to build the image.

About this task

A z/OS PT image is created by using the zospt build command. Images can becreated from scratch, or by basing an image on an existing one. In this way, youcan create stacks of images that together build different containers. For a reminderof how images work with z/OS PT, see Chapter 1, “What is z/OS ProvisioningToolkit?,” on page 1.

The build command takes the contents of a zosptfile and uses that to determinewhat gets put into an image. A zosptfile is a text document in UTF-8 encodingthat defines the instruction set that is used to assemble an image. Valid instructionsare shown in the following table:

Instruction Description

FROM imageName Defines the image on which this image is based. If you specify FROM scratch, this image isthe base image. It is not based on another image. Scratch is a reserved, base image that isthe starting point for building environments. Scratch cannot be directly built or run.Note: If you create an image by building on an existing image, the environmentvariables in the original image persist.

ENVZOSMF_TEMPLATE=templatename

Associate this image with a z/OSMF template.

ENV key=value Define an environment variable for this image. Some templates, such as CICS, allowenvironment variables to be specified to further customize the configuration of aprovisioned environment.

You can customize some of the properties of a provisioned environment by addingenvironment variable definitions to the zosptfile for the image, which can overridevalues that are specified in the properties file of the template that is named in the image.For more information about which properties can be added to the zosptfile for animage, see the Configuration properties file for the product you are provisioning.

Environment variables that are defined in a zosptfile for image_1 can also be referencedby other instructions in the same zosptfile, or by zosptfile instructions of other imagesbuilt FROM image_1, by referencing the environment variable as ${key}. For example, youmight define an environment variable to represent the directory into which certain filesare to be copied, and the environment variable might then be used in COPY instructions inthe zosptfile to ensure that the files are copied into the correct directory. To show thatan environment variable is only referenced by other instructions in the zosptfile, prefixthe environment variable name with IMAGE_.

The sample images that are provided with z/OS PT give examples of environmentvariables. For more information about sample images, see Chapter 19, “Samples providedwith z/OS Provisioning Toolkit,” on page 65.

COPY fromFile toFile Copy a file or directory into this image. The file must be in the same directory as thezosptfile, or one of its subdirectories.


For examples of zosptfile, see Chapter 19, “Samples provided with z/OSProvisioning Toolkit,” on page 65.

Procedure1. Edit the zosptfile:

a. Define the image on which this image is based:v To build this image from nothing, specify FROM scratch.v To build this image from an existing one, specify FROM imageName.

To see available images, use the zospt images command to print a list of theimages that are available to provision and the zospt inspect command tosee more details about a specified image.

b. Specify the template name that you want to call in z/OSMF when theimage is run (if the image is a base image).

c. Optional: Set environment variables.d. Optional: Copy files or directories into this image.

2. Run the zospt build command to build the image.zospt build -t imageName path

This command builds an image that is called imageName by using the zosptfilefound in the directory that is specified by path, and adds it to the local imagesdirectory.This command operates on local resources, and runs without connecting toz/OSMF.For a complete syntax description, and for information about how to remove animage, see Chapter 18, “The zospt command syntax,” on page 61.If you successfully set all of the properties, the following console output showsthe success message that is issued by zospt build:Successfully built /u/user/zospt/samples/cics_53_liberty/zosptfile into

image cics_53_liberty.

What to do next

The image is ready to use for provisioning with the zospt run command, asdescribed in Chapter 13, “Running a z/OS Provisioning Toolkit image,” on page45.


Chapter 13. Running a z/OS Provisioning Toolkit image

Use the zospt run command to provision a container from an image. z/OS PTuses the z/OSMF REST API to run the appropriate template and provision acontainer that uses the information in the image and any dependent images. In justa few minutes, a running environment is available for development. You can alsouse the link option on the zospt run command to provision a new container with alink to an existing container.

Running an image

Ensure that z/OS PT is configured and can correctly identify the z/OSMF domainthat contains the template to be run and the z/OSMF tenant that your user ID isassigned to. For a reminder of how to configure z/OS PT, see Chapter 10, “Addingan IBM Cloud Provisioning and Management for z/OS template for use with z/OSProvisioning Toolkit,” on page 39.

Run the zospt run command to create a container.zospt run imageName

This command creates a container from the image called imageName.

If you are testing a template that is in the Draft approved state, specify the --draftoption on the zospt run command. See the following example:zospt run imageName --draft

The --draft option is useful when you want to validate that the z/OSMF templateis correctly configured before you publish it for wider use.

For a complete syntax description, see Chapter 18, “The zospt command syntax,”on page 61.

For command zospt run cics_54, the console output returns progress on each stepin the workflow as the container is provisioned, including displaying some publicproperties, which is shown in the following example:2018-04-05 15:04:51 IBM z/OS Provisioning Toolkit V1.1.02018-04-05 15:04:51 Running image cics_54.2018-04-05 15:04:51 The z/OSMF template used is cics_54.2018-04-05 15:04:51 The z/OSMF domain is default.2018-04-05 15:04:51 The z/OSMF tenant is default.2018-04-05 15:04:51 Connecting to z/OSMF on host system01.ibm.com port 27820.2018-04-05 15:05:10 The z/OSMF template cics_54 was created by USER01 at 2018-01-05T07:40:34.394Z.

It was last modified by USER01 at 2018-01-06T07:41:11.761Z.2018-04-05 15:05:29 Creating container CICS_CICPJ00G with id cf91dd2f-9848-4672-af91-5aea7f80a02e on system MV01.2018-04-05 15:05:34 Getting dynamic applid - Complete.2018-04-05 15:05:36 Validating access to CICS data sets - Complete.2018-04-05 15:05:41 Validating access to zFS directories - Complete.2018-04-05 15:05:43 Allocating CMCI port - Complete.2018-04-05 15:05:45 Allocating http port - Complete.2018-04-05 15:05:47 Allocating https port - Complete.2018-04-05 15:05:52 Creating CICS security configuration - Complete.2018-04-05 15:06:14 Creating the zFS directory for the CICS region - Complete.2018-04-05 15:06:45 Creating CICS region data sets - Complete.2018-04-05 15:06:48 Formatting CICS region data sets - Complete.2018-04-05 15:06:52 Creating CICS log stream model - Complete.2018-04-05 15:07:23 Creating CICS CSD definitions - Complete.2018-04-05 15:07:28 Adding the image into the provisioned file system - Complete.2018-04-05 15:07:34 Creating the CICS Region JCL - Complete.2018-04-05 15:07:35 DFH_REGION_CMCIPORT : 320012018-04-05 15:07:35 DFH_REGION_HTTP : 284652018-04-05 15:07:35 DFH_REGION_APPLID : CICPJ00G2018-04-05 15:07:35 DFH_CICS_TYPE : SMSS2018-04-05 15:07:35 DFH_JVM_DEBUG : NO2018-04-05 15:07:35 DFH_REGION_ZFS_DIRECTORY : /u/cicprov/mount/CICPJ00G


2018-04-05 15:07:35 DFH_REGION_HTTPS : 284712018-04-05 15:07:37 Created container CICS_CICPJ00G with id cf91dd2f-9848-4672-af91-5aea7f80a02e on system MV01.2018-04-05 15:07:38 Performing start on container CICS_CICPJ00G.2018-04-05 15:07:42 Checking zFS is mounted - Complete.2018-04-05 15:07:53 Starting the CICS Region - Complete.2018-04-05 15:07:54 Started container CICS_CICPJ00G.

If the properties are all correct, the output from the zospt run command ends witha message that says the container is started. Your provisioned container is ready touse. The output also contains the details of how to access the container to use it fordevelopment and testing. If you have any problems when you provision acontainer, see Chapter 20, “Troubleshooting z/OS Provisioning Toolkit,” on page69.

Using the --name option

Use the --name option on the zospt run command to assign a meaningful name toa container, instead of having an automatically assigned container name:zospt run imageName --name containerName

This command provisions a container with name containerName (wherecontainerName must be unique). The maximum name length is 32 characters. Theacceptable characters are A-Z a-z 0-9 _ -.

Using the --link option

Use the link option on the zospt run command to provision a new container witha link to an existing container:zospt run imageName --link containerName|containerId:<alias>

This command creates a new container from the image that is called imageNameand connects it to an existing container (identified by either containerName orcontainerId), which can be given an alias. Existing subsystems must already beprovisioned by using z/OSMF or z/OS PT or registered as containers in z/OSMFso that they can be linked to by other containers.

You can specify the --link option multiple times in a single command, forexample:zospt run cics_54_liberty --link REG-DB2_TDB201:db2 --link REG-MQ_TMQ00:mq

For more information about registering existing subsystems in z/OSMF, seeChapter 23, “Registering existing subsystems in z/OSMF,” on page 111. For moreinformation about supported link scenarios, see “Link scenarios supported byz/OS Provisioning Toolkit” on page 47.

For command zospt run cics_54_test --link REG-DB2_DB200, the console outputreturns progress on each step in the workflow as the container is provisioned andreports back properties about the provisioned container, for example, its portnumbers, which is shown in the following example:2018-10-03 11:58:55 IBM z/OS Provisioning Toolkit V1.1.02018-10-03 11:58:55 Running image cics_54_test.2018-10-03 11:58:55 The z/OSMF template used is cics_54.2018-10-03 11:58:55 The z/OSMF domain is default.2018-10-03 11:58:55 The z/OSMF tenant is default.2018-10-03 11:58:55 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2018-10-03 11:58:56 The z/OSMF template cics_54 was created by USER01 at 2018-01-04T14:32:52.199Z.

It was last modified by USER01 at 2018-01-05T13:11:54.307Z.2018-10-03 11:59:02 Creating container CICS_CICPD002 with id 4743267a-5321-4420-86bb-a7e8040a1674 on system MV01.2018-10-03 11:59:12 Getting DB2 object id - Complete.2018-10-03 11:59:12 Getting necessary DB2 data - Complete.2018-10-03 11:59:12 Getting dynamic applid - Complete.2018-10-03 11:59:12 Validating access to CICS data sets - Complete.2018-10-03 11:59:20 Validating access to zFS directories - Complete.


2018-10-03 11:59:20 Validating console commands can be issued - Complete.2018-10-03 11:59:23 Hardening state indicating template validation steps passed. - Complete.2018-10-03 11:59:26 Allocating CMCI port - Complete.2018-10-03 11:59:29 Allocating HTTP port - Complete.2018-10-03 11:59:32 Allocating HTTPS port - Complete.2018-10-03 11:59:39 Obtaining hostname for the lpar - Complete.2018-10-03 11:59:45 Creating the zFS directory for the CICS region - Complete.2018-10-03 11:59:51 Creating CICS region data sets - Complete.2018-10-03 11:59:54 Formatting CICS region data sets - Complete.2018-10-03 11:59:57 Creating CICS log stream model - Complete.2018-10-03 12:00:01 Adding the image into the provisioned file system - Complete.2018-10-03 12:00:07 Set directory permissions - Complete.2018-10-03 12:00:36 Creating CICS CSD definitions - Complete.2018-10-03 12:00:39 Hardening state indicating successful CSD update - Complete.2018-10-03 12:00:45 Creating the CICS Region JCL - Complete.2018-10-03 12:00:48 Removing temporary files from zFS - Complete.2018-10-03 12:00:49 DFH_REGION_CMCIPORT : 320012018-10-03 12:00:49 DFH_REGION_HTTP : 260202018-10-03 12:00:49 DFH_REGION_APPLID : CICPD0022018-10-03 12:00:49 DFH_CICS_TYPE : SMSS2018-10-03 12:00:49 DFH_CICSGRP : DEFAULT2018-10-03 12:00:49 DFH_REGION_IPIC : NO2018-10-03 12:00:49 DFH_JVM_DEBUG : NO2018-10-03 12:00:49 DFH_REGION_ZFS_DIRECTORY : /u/user01/mount/CICPD0022018-10-03 12:00:49 DFH_REGION_HOSTNAME : SYSTEM01.IBM.COM2018-10-03 12:00:49 DB2_REGISTRY_NAME : REG-DB2_TDB2002018-10-03 12:00:49 DFH_REGION_HTTPS : 260222018-10-03 12:00:49 Created container CICS_CICPD002 with id 4743267a-5321-4420-86bb-a7e8040a1674 on system MV01.2018-10-03 12:00:51 Performing start on container CICS_CICPD002.2018-10-03 12:00:54 Checking zFS is mounted - Complete.2018-10-03 12:01:01 Starting the CICS Region - Complete.2018-10-03 12:01:02 Started container CICS_CICPD002.

If the properties are all correct, the output from the zospt run command ends witha message that says the container is started. Your provisioned container is ready touse. The output also contains the details of the name of the registry subsystem thatis specified in the link option. A DB2, IBM MQ, or IPIC connection definition isinstalled on the provisioned system (depending on the subsystem type of thelinking container) but no checks are made to ensure that the connection is acquiredor successful. If you have any problems when you provision a container, seeChapter 20, “Troubleshooting z/OS Provisioning Toolkit,” on page 69.

Using the --quiet option

The --quiet option is provided to make it easier to automate provisioning whenyou are using z/OS PT. By specifying the --quiet option, only the container nameis written to STDOUT during the zospt run command. The container name canthen be stored for use in further z/OS PT commands. For more information aboutusing z/OS PT in automation, see Chapter 17, “Automating provisioning withz/OS Provisioning Toolkit,” on page 59.zospt run imageName --quiet

This command runs an image in quiet mode.

Exploring further

Your provisioned container is ready to use. By using z/OS PT commands, you caninspect, stop, restart, and deprovision your container. For more information, seeChapter 15, “Managing containers created by z/OS Provisioning Toolkit,” on page51. For a complete syntax description, see Chapter 18, “The zospt commandsyntax,” on page 61.

Link scenarios supported by z/OS Provisioning ToolkitA range of link scenarios that define and install a connection to another subsystemare supported by z/OS PT. Use the link option on the zospt run command to trythese scenarios.

Chapter 13. Running a z/OS PT image 47

Linking containers

For more information about the zospt run --link command itself, see “--linkcontainerName:alias | containerId:alias” on page 63.

For more information about how to run the zospt run --link command, and forsome example output from the command, see “Using the --link option” on page46.

Linking a provisioned CICS image to a registered DB2 containerv A DB2 connection is defined and installed in the provisioned CICS container.v If the provisioned CICS container includes a Liberty JVM server, a JDBC type 2

connection is established.

Linking a provisioned CICS image to a registered IBM MQcontainerv An IBM MQ connection is defined and installed in the provisioned CICS

container.

Linking a provisioned CICS image to a registered DB2 container,and a registered IBM MQ containerv A DB2 connection and an IBM MQ connection are defined and installed in the

provisioned CICS container.v If the provisioned CICS container includes a Liberty JVM server, a JDBC type 2

connection is established.

Linking a provisioned instance of z/OS Connect EE to aprovisioned or registered CICS containerv The template that is used for provisioning the CICS container must specify the

property DFH_REGION_IPIC==YES so that CICS is listening on an IPIC portand the provisioned z/OS Connect EE container can determine the IPIC port towhich it needs to connect.

v An IPIC Connection is defined and installed in the provisioned z/OS ConnectEE container (by using the CICS Service Provider).

v If you specify an alias on the link command, the alias name (for example,myCICS) must match the value of the connectionRef specified in z/OS ConnectEE for building a service archive:<zosconnect_cicsIpicConnection id="myCICS"host="SYSTEM01.HURSLEY.IBM.COM"port="${instance-ZCON_CICS_IPIC_PORT}" />


Chapter 14. Managing z/OS Provisioning Toolkit images

After you build an image with the zospt build command, you can manage themusing other z/OS PT commands. You can see which images there are, or run orremove an image.

List images

Use the zospt images command to list all images:2017-12-21 13:26:58 IBM z/OS Provisioning Toolkit V1.1.0IMAGE NAME CREATED SIZEcics_52 2017-09-20T11:09:00 10240Bcics_53 2017-09-20T11:09:00 10240Bcics_54 2017-09-20T11:09:00 10240Bzosconnect_v2r0 2017-09-20T11:09:00 10240Bzosconnect_v3r0 2017-09-20T11:09:00 10240B

Inspect images

Use the zospt inspect command to see more details about the image you built:zospt inspect imageName

The following text is some example output from the zospt inspect command:2017-12-17 13:59:23 IBM z/OS Provisioning Toolkit V1.1.0{

"name": "cics_53","created": "Thu Aug 17 12:48:18 BST 2017","size": "10240B","FROM": "scratch","ENV": {"ZOSMF_TEMPLATE": "cics_53"}

}

For more information about what the property names size, FROM, and ENV mean,see Chapter 12, “Building an image with z/OS Provisioning Toolkit,” on page 43.

Remove images

When one or more images are no longer needed, use the zospt rmi command toremove them. This example command shows how to remove two images:zospt rmi imageName1 imageName2

The following output is returned:2017-09-12 13:29:04 IBM z/OS Provisioning Toolkit V1.1.02017-09-12 13:29:04 Deleted image imageName1.2017-09-12 13:29:04 Deleted image imageName2.

Exploring furtherv For a complete syntax description and any conditions of use, see Chapter 18,

“The zospt command syntax,” on page 61.v For more information about managing containers that are created by z/OS PT,

see Chapter 15, “Managing containers created by z/OS Provisioning Toolkit,” onpage 51.


Chapter 15. Managing containers created by z/OSProvisioning Toolkit

After you provision containers with the zospt run command, you can managethem using other z/OS PT commands. You can see which containers are running,start and stop them, and deprovision them when they are no longer needed.

List running containers

Use the zospt ps command to list running containers:zospt ps

This command returns the container name, the image name, the owner, the datethe container was created, the current state, the template that was used to createthe container, the system the container was created on, and the container type ofany running containers that you are authorized to view. This command also showsyou all running registered containers, with the container name prefixed with REG.All registered containers can be viewed by any user.2018-01-11 14:24:35 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPECICS_CICPD000 cics_54 user01 2017-10-03T10:54:31 provisioned cics_54 MV01 StandardZOSCONNECT_ZCON008 testApi user01 2018-01-04T02:27:34 provisioned zosconnect_v3r0 MV02 StandardCICS_CICPD000 cics_54_liberty user02 2018-01-15T10:54:31 provisioned cics_54 MV01 StandardREG-DB2_DB2000 N/A user02 2018-01-17T15:01:55 provisioned db2_registration MV01 Standard

List all containers

To list all containers, enter the following command:zospt ps -a

This command returns the container name, the image name, the owner, the datethe container was created, the current state, the template that was used to createthe container, the system the container was created on, and the container ID of anyrunning containers that you are authorized to view. It also returns the versions ofz/OSMF and z/OS of the running LPAR. This command also shows you allregistered containers, with the container name prefixed with REG. All registeredcontainers can be viewed by any user.2017-10-02 16:07:40 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2017-10-02 16:07:40 z/OS level is V2R2.2017-10-02 16:07:40 z/OS Management Facility level is V2R2.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPECICS_CICPD000 cics_54 user01 2017-10-03T10:54:31 provisioned cics_54 MV01 StandardZOSCONNECT_ZCON008 testApi user01 2018-01-04T02:27:34 provisioned zosconnect_v3r0 MV02 StandardCICS_CICPD000 cics_54_liberty user02 2018-01-15T10:54:31 provisioned cics_54 MV01 StandardREG-DB2_DB2000 N/A user02 2018-01-17T15:01:55 provisioned db2_registration MV01 StandardCICS_CICPD00C cics_54_app user02 2018-01-22T11:43:34 being-deprovisioned cics_54 MV01 StandardREG-MQ_CICPJ00A N/A user03 2018-01-22T15:35:03 deprovisioned mq_registration MV01 Standard

Filter the list of containers

To filter the results of zospt ps or zospt ps -a by OWNER, STATE, or SYSTEM, you canadd -f or --filter to the command. You can specify the -f option multiple timesin a single command. For example, to filter the results by OWNER and STATE, enterthe following command:zospt ps -f owner=user02 -f state=provisioned

This command gives the following output:2017-10-04 15:54:12 Connecting to z/OSMF on host system01.com port 32000.NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPECICS_CICPD000 cics_54_liberty user02 2018-01-15T10:54:31 provisioned cics_54 MV01 StandardREG-DB2_DB2000 N/A user02 2018-01-17T15:01:55 provisioned db2_registration MV01 Standard


For a complete syntax description and any conditions of use, see Chapter 18, “Thezospt command syntax,” on page 61.

Inspect containers

Use the zospt inspect command to see more details about the container youcreated, including the status of the container, and to see a list of any linked-tocontainers:zospt inspect containerName | containerID

The following text is some example output from the command zospt inspectCICS_CICPJ00Z:{

"container-name": "CICS_CICPJ00Z","container-id": "5209fa00-fadc-4d1e-aa37-e2c4b7160f30","instance-name": "CICS_CICPJ00Z","template": "cics_54","image_name": "cics_54","created-time": "2018-01-20T12:31:14.425Z","type": "CICS","system": "MV01","sysplex": "PLEX01","owner": "user123","state": "provisioned","tenant-name": "default","domain-name": "default","public_properties": {

"DFH_CICS_TYPE": "SMSS","DFH_REGION_APPLID": "CICPJ00Z","DFH_REGION_CMCIPORT": "32001","DFH_REGION_HOSTNAME": "HOST","DFH_REGION_HTTP": "28499","DFH_REGION_ZFS_DIRECTORY": "/u/zospt/mount/CICPJ00Z","INSTANCE_STATUS": "active"

},"connected-containers": [{"container-name": "DB2_DB2J001"}]

}

You can also use the zospt inspect command to see more details about aregistered container that is created by any user:{

"container-name": "REG-DB2_CICPJ000","container-id": "89b5481b-acbb-4a6c-9ffd-a3139e0b504f","instance-name": "REG-DB2_CICPJ000","template": "db2_registration","image_name": "N/A","created-time": "2018-01-02T15:01:55.034Z","type": "REG-DB2","system": "MV01","sysplex": "PLEX01","owner": "user234","state": "provisioned","tenant-name": "default","domain-name": "default","public_properties": {

"DSN_HLQ": "SYS2.DB2.V11","DSN_SSID": "DJ29","DSN_ZFS_HLQ": "/db2/db2v11"

},"connected-containers": []

}


The INSTANCE_STATUS property that is returned shows the current status of thecontainer. If the container was stopped in any way, the INSTANCE_STATUS shows asinactive.

The connected-containers property that is returned shows the container orcontainers that the inspected container is linked to.


Start and stop containers

Containers are started in the running state when you provision them. You can usethe zospt stop to stop one or more running containers and a zospt startcommand to restart one or more containers. You can identify a target containerwith either the containerName or containerID. You might use the followingcommands to stop and start multiple containers by interchangeably using theirname or ID:zospt stop CICS_CICPP003 05dc7424-3178-4e98-a179-1d7f95b749a2

...zospt start d5975552-711d-437e-ba86-63d97108523e CICS_CICPD001


Remove and deprovision containers

When one or more containers are no longer needed, use the zospt rm command toremove them. This process deletes the data sets and zFS directories that areassociated with the environment. This example command shows how to removetwo containers:zospt rm containerName1 containerName2

If one or more of the containers are running, the zospt rm command fails. In thiscase, you can either stop the running container or containers, or use the --forceoption on the command to deprovision the environment. The --force option mustalso be used if the container you want to remove is a registered container.

You can identify the target container with either containerName or containerID.


Exploring further

Now that you are working with z/OS PT, stay in touch through the IBMdeveloperCenters. There, you can find scenarios and examples of z/OS PT inaction:v CICS Developer Center for scenarios that involve CICS.v z/OS Connect EE Developer Center for scenarios that involve z/OS Connect EE.

Chapter 15. Managing containers created by z/OS PT 53


https://developer.ibm.com/mainframe/products/zosconnect/

Chapter 16. Using z/OS Provisioning Toolkit with z/OSMFcomposite templates

You can use a z/OSMF composite template to provision and deprovision multiplerelated containers by using a single z/OS PT command. The connection betweenthe containers is defined in z/OSMF when you create the composite template.Containers that need to be provisioned and deprovisioned together can bemanaged in z/OSMF, instead of by running multiple zospt run commands and byusing the --link option to connect them together.

About composite templates

Composite templates are available to use with z/OSMF 2.2 and above. Acomposite template is constructed by using z/OSMF to define which set oftemplates make up the composite template, the order in which the templates areprovisioned, and how they are connected together. A composite template can benamed in a z/OS PT image and the zospt run command can be used to provisionthe composite template. Try the templates that make up the composite templateindividually before you use them in a composite template.

For more information about composite templates, see z/OSMF Compositetemplates.

Using composite templates

Provisioning a connected set of containers can be achieved by using compositetemplates, or by provisioning separate containers, and connecting them togetherusing multiple z/OS PT commands. Composite templates might be suitable foryou if you need to provision multiple containers that must be provisioned anddeprovisioned together, or if you prefer to define and manage the connected set ofcontainers in z/OSMF, and present a single composite template that can beprovisioned and deprovisioned by users.

If you are using z/OSMF 2.1, or do not have the IBM Cloud Provisioning andManagement for z/OS 1.2 APARs applied, or if you want to build a z/OS PTimage that contains files that need to be copied to the zFS file system for use by aprovisioned container, consider issuing multiple z/OS PT commands to provision aconnected set of linked containers, each of which uses a different z/OS PT image.For more information about how to link containers together, see “Using the --linkoption” on page 46. For more information about link scenarios that are supported,see “Link scenarios supported by z/OS Provisioning Toolkit” on page 47.

Creating a composite template

You can create a composite template by using z/OSMF, in a similar way to astandard (non-composite) template.v For more information about how to create a composite template, see z/OSMF

Add a template.v For more information about how to create a standard template in preparation for

using z/OS PT, see Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” onpage 39.


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpSoftwareConfigComposites.html

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpSoftwareConfigComposites.html

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpAddTemplate.html#izuSChpAddTemplate

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpAddTemplate.html#izuSChpAddTemplate

Building an image that names a composite template

You build an image that names a composite template in a similar way to buildingan image that names a standard (non-composite) template, by adding instructionsto the zosptfile, then by using the zospt build command. The following exampleshows how you specify the composite template name in the zosptfile to build animage that names a composite template:

ENV ZOSMF_TEMPLATE=<composite_template_name>

Environment variables can be specified in the image and targeted at individualtemplates in the composite template, by prefixing the environment variable namewith the individual template name. For example, if your composite templateprovisions a CICS region that uses template cics_54 and a z/OS Connect EEinstance, that uses template zosconnect_v3r0, and you need the CICS region to beprovisioned with a Liberty JVM server, you can set the following environmentvariable in the image.ENV cics_54.DFH_REGION_JVMSERVER=Liberty

Setting the environment variable in this way ensures that theDFH_REGION_JVMSERVER variable is passed into the cics_54 template when theCICS region is provisioned.

You cannot COPY files or directories into an image for a composite template. Youcan specify only the template name and environment variables.

For more information about building an image by using z/OS PT, see Chapter 12,“Building an image with z/OS Provisioning Toolkit,” on page 43.

Running an image that names a composite template

You can run an image that names a composite template in the same way that youcan run an image that names a standard (non-composite) template, by using thezospt run command. The --name and --quiet options are supported on zospt runcommands for an image that names a composite template. Differences in theoutput that is generated from the zospt run command are shown in the followingexample output:/u/user/cics_demo:>zospt run test2018-01-11 07:51:46 IBM z/OS Provisioning Toolkit V1.1.02018-01-11 07:51:46 Running image test.2018-01-11 07:51:46 The z/OSMF template used is cics_zcee.2018-01-11 07:51:46 The z/OSMF domain is default.2018-01-11 07:51:46 The z/OSMF tenant is default.2018-01-11 07:51:46 Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.2018-01-11 07:51:47 The z/OSMF template cics_zcee was created by USER01 at 2017-11-08T07:49:19.567Z.

The template type is composite. It was last modified by USER01 at 2017-11-08T07:49:19.567Z.2018-01-11 07:51:47 The z/OSMF composite child template cics_user_test was created by USER01 at 2017-10-30T08:15:31.829Z.

Its position in the provisioning sequence is 1. It was last modified by USER01 at 2017-11-08T07:20:47.386Z.2018-01-11 07:51:47 The z/OSMF composite child template zosconnect_nosec_user was created by USER01 at 2017-08-08T09:06:20.822Z.

Its position in the provisioning sequence is 2. It was last modified by USER01 at 2017-11-08T07:20:28.208Z.2018-01-11 07:51:56 Creating composite container CZ_CZ00 with id cecaacb2-fcf0-4c6f-b7d1-8e246e82d76e on system MV01....2018-01-11 07:54:54 Created container ZOSCONNECT_CICPD00K with id 6fcdb76d-e9e1-4fc7-abfd-4e15c80cf48f on system MV01.2018-01-11 07:54:54 Created composite container CZ_CZ00 with id cecaacb2-fcf0-4c6f-b7d1-8e246e82d76e on system MV01.

For more information about running an image by using z/OS PT, see Chapter 13,“Running a z/OS Provisioning Toolkit image,” on page 45.


Managing containers created from a composite template

You can manage containers that are created from a composite template in the sameway that you manage containers that are created from a Standard (non-composite)template:v List running containers (by using the zospt ps command). The output of the

command indicates whether a container is a Composite_Parent, aComposite_Child, or a Standard container, as in the following zospt pscommand output:NAME IMAGE OWNER CREATED STATE TEMPLATE SYSTEM CONTAINER TYPECZ_CZ00 test user01 2018-01-11T07:51:47 provisioned cics_zcee MV01 Composite_ParentCICS_CICPD00I N/A user01 2018-01-11T07:51:47 provisioned cics_zcee:cics_user_test MV01 Composite_ChildZOSCONNECT_CICPD00K N/A user01 2018-01-11T07:51:47 provisioned cics_zcee:zosconnect_nosec_user MV01 Composite_Child

v Inspect containers (by using the zospt inspect command). This command isupdated to include information about the relationship between the container andits parent or child containers, as in the following command output:/u/user:>zospt inspect ZOSCONNECT_CICPD00K{

"container-name": "ZOSCONNECT_CICPD00K","container-id": "6fcdb76d-e9e1-4fc7-abfd-4e15c80cf48f","instance-name": "ZOSCONNECT_CICPD00K","template": "zosconnect_nosec_user","image_name": "N/A","created-time": "2018-01-11T07:51:47","type": "ZOSCONNECT","system": "MV01","owner": "user01","state": "provisioned","public_properties": {

"INSTANCE_STATUS": "inactive","ZCON_HTTP_PORT": "28665","ZCON_INSTALL_DIR": "/usr/lpp/IBM/zosconnect/v3r0","ZCON_RECOMMENDATION": "Export the environment variable WLP_USER_DIR=/u/user/mount/CICPD00K before you issue zosconnect commands against the server","ZCON_SERVER_DIRECTORY": "/u/user/mount/CICPD00K/servers/CICPD00K"

},"connected-containers": [{"container-name": "CICS_CICPD00I"}],"composite-parent": "CZ_CZ00","provisioning-sequence": "2"

}

v Start and stop containers (by using the zospt start and zospt stop commands).You can issue zospt start and zospt stop commands against Composite_Parentcontainers or Composite_Child containers. When you issue the zospt start orzospt stop commands against a Composite_Parent container, all containers arestarted or stopped in the right sequence.

v Remove and deprovision containers (by using the zospt rm command). If youissue the zospt rm command against a Composite_Parent container, it will checkthat all of the Composite_Child containers are stopped, and if so will attempt adeprovision. The zospt rm command fails if any child containers are still active.The zospt rm command is not supported for Composite_Child containers.

v Remove and deprovision containers (by using the zospt rm -f command). Youcan issue the zospt rm -f command against Composite_Parent containers. Whenyou issue the zospt rm -f command against a Composite_Parent container, allComposite_Child containers that are owned by the Composite_Parent containerare deprovisioned. The zospt rm -f command is not supported forComposite_Child containers.

For more information about managing containers that are created by z/OS PT fromstandard templates, see Chapter 15, “Managing containers created by z/OSProvisioning Toolkit,” on page 51.

Exploring further

Stay in touch and look out for more information at CICS Developer Center. Formore information about composite and standard templates, see z/OSMF CloudProvisioning Software Services.

Chapter 16. Using z/OS PT with z/OSMF composite templates 57


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpSoftwareConfigOverview.html

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zosmfcore.softwareconfig.help.doc/izuSChpSoftwareConfigOverview.html

Chapter 17. Automating provisioning with z/OS ProvisioningToolkit

To allow the provision and deprovision of containers to be automated, z/OS PTcan be configured so that no input from the user is needed at run time. You canspecify options on the zospt run command to make it easier to retrieve the nameof the provisioned containers for use in further automation steps.

Configuring z/OS PT for use in automation

Configure the following z/OS PT environment variables:v Set the zospt_pw environment variable to the password of the user ID that runs

the automation. The user ID that runs the automation must have the appropriateauthority in z/OSMF to perform the z/OS PT commands.

v If z/OS PT is configured to use a truststore, the truststore must already containthe certificate authorities that are needed to trust the z/OSMF server.

For more information about setting the zospt_pw and truststore environmentvariables, see Chapter 8, “Configuring z/OS Provisioning Toolkit,” on page 35. Formore information about the maximum length, and for a list of acceptablecharacters to use for the container name, see the zospt run command inChapter 18, “The zospt command syntax,” on page 61.

Obtaining the container name from a zospt run command

By default, the zospt run command reports the progress of the provisioningprocess by writing messages to STDOUT, which can make it difficult to capture thecontainer name that is dynamically allocated to the provisioned container. To makeit easier to obtain the container name, specify the --quiet option on the zospt runcommand:/u/cicsusr:>zospt run cics_54 --quietCICS_CICPJ001

If the command is successful, only the container name is written to STDOUT. If thecommand fails, error information is written to STDERR.

Example script to retrieve the z/OS PT container name

In the following example, the script provisions a container and uses a variable thatis called mycontainer to obtain the container name. In the following example, if theprovision successfully completes with a return code zero, the script then inspectsthe provisioned container by using the obtained name:#!/bin/shmycontainer=$(zospt run myimage --quiet)if [ $? -eq 0 ]then

zospt inspect $mycontainerfi

Specifying the container name on a zospt run command

In the following example, instead of receiving a dynamic container name from azospt run command, you can specify the container name to be used:


zospt run imageName --name containerName

If the automated script provisions multiple containers, the automation needs a wayto generate a unique container name for each container that gets provisioned:

Example script that sets the z/OS PT container name

In the following example, the script provisions a container that is named mycicsand then inspects the container:#!/bin/shzospt run myimage --name mycicszospt inspect mycics

Logging

z/OS PT commands emit informational messages to STDOUT and error messagesto STDERR.

z/OS PT return codes

z/OS PT commands return the following exit codes:v 0 = Success.v 12 = An error occurred. If the error occurs during a zospt run command, the

container is created and must be removed. If the error occurs on othercommands, it can be possible to retry those commands. The container must beremoved when it is no longer needed.

v 16 = An error occurred during a zospt run command before the container wascreated. The container does not need to be removed.

v 20 = An internal error occurred. For more information, see the z/OS PT logs andSTDERR.


Chapter 18. The zospt command syntax

This reference shows the options that you can set on the zospt commands that areused by the z/OS Provisioning Toolkit.

SyntaxUsage: zospt [OPTIONS] COMMAND [arg...]

Options:--version : Displays the command line version.-h (--help) : Displays the command line help.

Commands:build PATH [-h (--help)] -t (--tag) <imageName> Build an imageimages [-h (--help)] List all imagesinspect <imageName> | <containerName> | <containerId> Inspect an image or a container

[-h (--help)]rm <containerName> | <containerId> ... [-f (--force)] Remove one or more containers

[-h (--help)]rmi <imageName> ... [-h (--help)] Remove one or more imagesrun <imageName> [--draft] Run an image in a new container

[--link <containerName> | <containerId>:<alias>][--name <containerName>] [-q (--quiet)] [-h (--help)]

start <containerName> | <containerId> ... [-h (--help)] Start one or more containersstop <containerName> | <containerId> ... [-h (--help)] Stop one or more containersps [-a (--all)] [-f (--filter) <filter>] [-h (--help)] List containers

Run ’zospt COMMAND --help’ for more information on a command.

Description

Run zospt command --help to show the syntax of the command. If a commandfails, use the error messages in the console output, and Chapter 20,“Troubleshooting z/OS Provisioning Toolkit,” on page 69 to resolve any issues.

buildBuilds an image that is used by the zospt run command to provisioncontainers. The following are the build parameters:

PATHThe path to the directory that contains the zosptfile to be used in thisbuild. This parameter is mandatory.

-t (--tag)The name of the image that this command builds. You cannot use thefollowing reserved characters: : (colon), @ (at-sign), / (forward slash) or \(backslash). This parameter is mandatory.

imageNameThe name of the image to use as input to this build. This parameter ismandatory.

When you run zospt build, z/OS PT operates on local resources, and runswithout connecting to z/OSMF.

imagesPrints to the command line a list of the images that are available to run, withtheir name, size, and date created. This command has no additionalparameters.

When you run zospt images, z/OS PT operates on local resources, and runswithout connecting to z/OSMF.


inspectReturns details, in JSON format, about a specified image or container, see thefollowing example:{

"name": "imageName","created": "Thu Dec 01 15:10:28 GMT 2016","size": "10240B","FROM": "cics_53","ENV": {

"ZOSMF_TEMPLATE": "cics_53","DFH_REGION_JVMSERVER": "Liberty","LIBERTY_DIR": "workdir/DFHWLP/wlp/usr/servers/defaultServer"

}}

The following are the inspect parameters:

imageNameThe name of the image to be inspected. This parameter is mandatory.When you run the zospt inspect imageName command, z/OS PT operateson local resources, and runs without connecting to z/OSMF.

containerName|containerIdThe name or ID of the container to be inspected. This parameter ismandatory. When you run the zospt inspect containerName or zosptinspect containerId commands, z/OS PT operates on remote resourcesand connects to z/OSMF.

ps Lists the provisioned containers and containers for which provisioning failed.The following are the ps parameters:

-a (--all)Lists all of the containers in any of the following states: being provisioned,provisioned, provisioning failed, being deprovisioned, deprovisioned, anddeprovisioning failed. This parameter is optional.

-f (--filter)Filters the returned containers based on the owner or state of the container,or the system on which the container is running:zospt ps -f filter_by=value

Where filter_by is OWNER, STATE, or SYSTEM, and value is the parameter thatyou want to filter by. For multiple filters, specify -f before each filter, forexample:zospt ps -f owner=user02 -f state=provisioned

When you run zospt ps, you are prompted to enter your password on theconsole to authorize the connection to z/OSMF.

rm Removes (or deprovisions) one or more containers that were provisionedthrough the zospt run command. The following are the rm parameters:

containerName|containerIdThe name or ID of the container that was returned as a result of zospt run.Only one of these parameters is needed. Specify multiple containers thatare separated by a space to remove more than one container at a time.

-f (--force)This parameter is relevant only to CICS. If this optional parameter isspecified, the CICS region is shut down.


When you run zospt rm, you are prompted to enter your password on theconsole to authorize the connection to z/OSMF. After authorization, z/OS PTuses z/OSMF workflows to remove or deprovision the specified container orcontainers. The command line returns the progress of the workflows while itruns in z/OSMF. Multiple jobs run as part of each command, so they mighttake several minutes to complete.

rmiRemoves one or more images. imageName is the only rmi parameter:

imageNameThe name of the image to use as input. Specify multiple images that areseparated by a space to remove more than one image at a time. Thisparameter is mandatory.

runRuns an image that was built by using the zospt build command to create anew container. The following are the run parameters:

imageNameThe name of the image to run. This parameter is mandatory.

--draft

Run the z/OSMF template in "Draft approved" state. This parameter isoptional. Without this parameter, the z/OSMF template must be in"Published" state.

--link containerName:alias | containerId:alias

Provisions a container with a connection to one or more other containers.Specify the containerName|containerID of the container to link to. Eachcontainer can be given an optional alias, which can be used to identify theconnection in the provisioned container.

You can specify the --link option multiple times in a single command.

--name containerNameThe name of the container to run. This name must be unique, and meansthat you can assign a meaningful name to a container, instead of having anautomatically assigned container name. The maximum name length is 32characters. The acceptable characters are A-Z a-z 0-9 _ -. This parameteris optional.

-q (--quiet)No informational messages are written to the console during the run. Theonly output that is written to stdout is the name of the provisionedcontainer. If an error occurs, the error information is written to stderr.

When you run zospt run, you are prompted to enter your password on theconsole to authorize the connection to z/OSMF. After authorization, z/OS PTuses z/OSMF workflows to run the specified image. The command line returnsthe progress of the workflows while it runs in z/OSMF. Multiple jobs run aspart of each command, so they might take several minutes to complete.

startStarts one or more containers that were created by the zospt run command.The following are the start parameters:

containerName|containerIdThe name or ID of the container that was returned as a result of zospt run.

Chapter 18. The zospt command syntax 63

Only one of these parameters is needed. Specify multiple containers thatare separated by a space to start more than one container at a time.

When you run zospt start, you are prompted to enter your password on theconsole to authorize the connection to z/OSMF. After authorization, z/OS PTuses z/OSMF workflows to start the specified container. The command linereturns the progress of the workflows while it runs in z/OSMF. Multiple jobsrun as part of each command, so they might take several minutes to complete.

stopStops one or more containers that were created by the zospt run command.The following are the stop parameters:

containerName|containerIdThe name or ID of the container that was returned as a result of zospt run.Only one of these parameters is needed. Specify multiple containers thatare separated by a space to stop more than one container at a time.

When you run zospt stop, you are prompted to enter your password on theconsole to authorize the connection to z/OSMF. After authorization, z/OS PTuses z/OSMF workflows to stop the specified container. The command linereturns the progress of the workflows while it runs in z/OSMF. Multiple jobsrun as part of each command, so they might take several minutes to complete.


Chapter 19. Samples provided with z/OS Provisioning Toolkit

To give you a foundation for configuring templates and building images, z/OS PTprovides examples of the configuration for commonly used environments, such asCICS Transaction Server for z/OS. The download package of z/OS PT providessample templates and images, and the corresponding artifacts that are used byz/OS PT to build these images.

Samples templates

Templates are configured by a properties file and added into z/OSMF to enablethe provisioning of systems based on the templates. Example templates forprovisioning CICS regions and instances of z/OS Connect EE are provided in thezospt/templates directory. Each example contains a properties file, which needs tobe customized for your environment. To create a new template, copy the entiretemplate directory to another directory within the zospt/templates directory andthen update the properties file for the new template.

Table 3. Sample CICS templates provided with z/OS PT

Sample template name Details

cics_getting_started A z/OSMF template that is configured with a minimal set of properties toenable the provisioning of a simple, single CICS Transaction Server forz/OS V5.4 region. For a walkthrough that uses the cics_getting_startedtemplate, see “Getting started with CICS by using z/OSMF workflows” onpage 14.

cics_52 A z/OSMF template that is configured to provision a CICS TransactionServer for z/OS V5.2.



cmas_54 A z/OSMF template that is configured to provision a CICSPlex SM(CMAS) region.

wui_54 A z/OSMF template that is configured to provision a Web User Interface(WUI) region.

zosconnect_v2r0 A z/OSMF template that is configured to provision z/OS ConnectEnterprise Edition V2.0.

zosconnect_v3r0 A z/OSMF template that is configured to provision z/OS ConnectEnterprise Edition V3.0.

Samples images and the source artifacts that are used to buildthem

Configuration files (zosptfiles) are used to describe the contents of an image.Building a zosptfile creates a binary image that can then be used to provisionapplications and systems. Sample zosptfiles are provided in the zospt/samplesdirectory. Some of these samples are built into images that are provided with z/OSPT in the zospt/images directory. The images in directory zospt/images can belisted by using the zospt images command. If you plan to use a provided image,look at its zosptfile in directory zospt/samples to see how suitable it is for youruse.


Table 4. Sample zosptfiles provided with z/OS PT in directory zospt/samples

Sample name Details

cics_getting_started_workflow A zosptfile for building an image to test the “Getting started with CICSby using z/OSMF workflows” on page 14 scenario, by provisioning thecics_getting_started z/OSMF template (which is configured with aminimal set of properties to enable provisioning of a CICS TransactionServer for z/OS V5.4 region).

cics_getting_started_cloud A zosptfile for building an image to test the “Getting started with CICSby using IBM Cloud Provisioning and Management for z/OS” on page 17scenario, by provisioning the cics_getting_started z/OSMF template(which is configured with a minimal set of properties to enableprovisioning of a CICS Transaction Server for z/OS V5.4 region).

cics_52 A zosptfile that identifies the name of a z/OSMF template (cics_52) todrive for provisioning a region that is running CICS Transaction Server forz/OS V5.2.



cics_54_json A zosptfile that defines an Axis2 JVM server and associated serviceprovider pipeline based on CICS Transaction Server for z/OS V5.4. Theenvironment variable IMAGE_WSDIR is defined, which can be used tocopy WSBind files into the WSBind pickup directory for the serviceprovider pipeline.

cics_54_json_microservice A zosptfile that shows how to build an image that contains a JSONmicroservice that uses an Axis2 JVM server and associated serviceprovider pipeline based on CICS Transaction Server for z/OS V5.4. Thesample uses the environment variable IMAGE_WSDIR to copy WSBindfiles into the WSBind pickup directory for the service provider pipeline.The environment variable is defined in the cics_54_json image that thissample extends.

cics_54_liberty A zosptfile that defines a CICS Transaction Server for z/OS V5.4 regionwith an embedded Liberty JVM server. The environment variableIMAGE_LIBERTY_DIR is defined, which can be used to copyconfiguration files for the Liberty JVM server into the right directory.

cics_54_soap A zosptfile that defines a service provider pipeline that is configured forSOAP web services based on CICS Transaction Server for z/OS V5.4. Theenvironment variable IMAGE_WSDIR is defined, which can be used tocopy WSBind files into the WSBind pickup directory for the serviceprovider pipeline.

cics_54_soap_microservice A zosptfile that shows how to build an image that contains a SOAPmicroservice that uses a service provider pipeline that is configured forSOAP web services based on CICS Transaction Server for z/OS V5.4. Thesample uses the environment variable IMAGE_WSDIR to copy WSBindfiles into the WSBind pickup directory for the service provider pipeline.The environment variable is defined in the cics_54_soap image that thissample extends.


Table 4. Sample zosptfiles provided with z/OS PT in directory zospt/samples (continued)

Sample name Details

cics_54_zosconnect_v3r0 A zosptfile that defines a CICS Transaction Server for z/OS V5.4 regionwith embedded z/OS Connect EE V3. The sample sets the environmentvariable DFH_ZOSCONNECT_USERID to provide a default user IDforz/OS Connect EE tasks, which run in CICS. This environment variablereplaces any value that is specified for the DFH_ZOSCONNECT_USERIDproperty in the z/OSMF template that provisions the underlying CICSregion. The sample defines two further environment variables,IMAGE_APIS and IMAGE_SERVICES, which can be used to copy z/OSConnect EE API archive files (AAR files) and service archive files (SARfiles) to the appropriate directories so that they are installed when thez/OS Connect EE instance is started.

cics_54_zosconnect_v3r0_services A zosptfile that shows how to build an image that contains z/OSConnect V3 service archive files (SAR files) that are deployed into a CICSTransaction Server for z/OS V5.4 region with embedded z/OS Connect EEV3. The sample uses the environment variable IMAGE_SERVICES to copySAR files into the appropriate directory so that they are installed when thez/OS Connect EE instance is started. The environment variable is definedin the cics_54_zosconnect_v3r0 image that this sample extends.

cics_54_zosconnect_v3r0_api A zosptfile that shows how to build an image that contains z/OSConnect V3 API archive files (AAR files) that are deployed into a CICSTransaction Server for z/OS V5.4 region with embedded z/OS Connect EEV3. The sample uses the environment variable IMAGE_APIS to copy AARfiles into the appropriate directory so that they are installed when thez/OS Connect EE instance is started. The environment variable is definedin the cics_54_zosconnect_v3r0 image that this sample extends.

cmas_54 A zosptfile that identifies the name of a z/OSMF template (cmas_54) todrive for provisioning a CICSPlex SM (CMAS) region.

wui_54 A zosptfile that identifies the name of a z/OSMF template (wui_54) todrive for provisioning a Web User Interface (WUI) region.

zosconnect_v2r0 A zosptfile that identifies the name of a z/OSMF template(zosconnect_v2r0) to drive for provisioning z/OS Connect EE V2. Thesample defines an environment variable IMAGE_APIS, which can be usedto copy z/OS Connect EE API archive files (AAR files) to the appropriatedirectory so that they are installed when the z/OS Connect EE instance isstarted.

zosconnect_v3r0 A zosptfile that identifies the name of a z/OSMF template(zosconnect_v3r0) to drive for provisioning z/OS Connect EE V3. Thesample defines two environment variables, IMAGE_APIS andIMAGE_SERVICES, which can be used to copy z/OS Connect EE APIarchive files (AAR files) and service archive files (SAR files) to theappropriate directories so that they are installed when the z/OS ConnectEE instance is started.

Table 5. Sample images provided with z/OS PT in directory zospt/images

Sample image name Details

cics_getting_started_workflow An example image for testing out the “Getting started with CICS by usingz/OSMF workflows” on page 14 scenario, by provisioning thecics_getting_started z/OSMF template through z/OS PT.

cics_getting_started_cloud An example image for testing out the “Getting started with CICS by usingIBM Cloud Provisioning and Management for z/OS” on page 17 scenario,by provisioning the cics_getting_started z/OSMF template through z/OSPT.

Chapter 19. Samples provided with z/OS PT 67

Table 5. Sample images provided with z/OS PT in directory zospt/images (continued)

Sample image name Details

cics_52 Defines the z/OSMF template (cics_52) to drive for provisioning a regionthat is running CICS Transaction Server for z/OS V5.2.



cics_54_json Uses the configuration from the cics_54 image and extends it with anAxis2 JVM server and associated service provider pipeline. Theenvironment variable IMAGE_WSDIR is defined in the image, which canbe used in images that are built from the cics_54_json image, to copyWSBind files into the WSBind pickup directory for the service providerpipeline.

cics_54_liberty Uses the configuration from the cics_54 image and extends it with anembedded Liberty JVM server. The environment variableIMAGE_LIBERTY_DIR is defined in the image, which can be used inimages that are built from the cics_54_liberty image, to copy configurationfiles for the Liberty JVM server into the right directory.

cics_54_soap Inherits the configuration from the cics_54 image and extends it with aservice provider pipeline that is configured for SOAP web services. Theenvironment variable IMAGE_WSDIR is defined in the image, which canbe used in images that are built from the cics_54_soap image, to copyWSBind files into the WSBind pickup directory for the service providerpipeline.

cics_54_zosconnect_v3r0 Inherits the configuration from the cics_54_liberty image and extends it byconfiguring the embedded Liberty JVM server to run z/OS Connect EE.The image includes the environment variableDFH_ZOSCONNECT_USERID, which provides a default user ID for z/OSConnect EE tasks that run in CICS. This environment variable replaces anyvalue that is specified for the DFH_ZOSCONNECT_USERID property inthe z/OSMF template (cics_54) that provisions the underlying CICSregion. The image includes two further environment variables,IMAGE_APIS and IMAGE_SERVICES, which can be used in images thatare built from the cics_54_zosconnect_v3r0 image, to copy z/OS ConnectEE API archive files (AAR files) and service archive files (SAR files) to theappropriate directories so that they are installed when the z/OS ConnectEE instance is started.

cmas_54 Defines the z/OSMF template (cmas_54) to drive for provisioning aCICSPlex SM (CMAS) region.

wui_54 Defines the z/OSMF template (wui_54) to drive for provisioning a WebUser Interface (WUI) region.

zosconnect_v2r0 Defines the z/OSMF template (zosconnect_v2r0) to drive for provisioningz/OS Connect EE. The image defines the environment variableIMAGE_APIS, which can be used in images that are built from thezosconnect_v2r0 image, to copy z/OS Connect EE API archive files (AARfiles) to the appropriate directory so that they are installed when the z/OSConnect EE instance is started.

zosconnect_v3r0 Defines the z/OSMF template (zosconnect_v3r0) to drive for provisioningz/OS Connect EE. The image defines two environment variables,IMAGE_APIS and IMAGE_SERVICES, which can be used in images thatare built from the zosconnect_v3r0 image, to copy z/OS Connect EE APIarchive files (AAR files) and service archive files (SAR files) to theappropriate directories so that they are installed when the z/OS ConnectEE instance is started.


Chapter 20. Troubleshooting z/OS Provisioning Toolkit

Use these resources to find diagnostic information for z/OS PT with IBM CloudProvisioning and Management for z/OS, and a link to dW Answers for answers tospecific issues. If you cannot resolve a problem and need to contact IBM, see thefollowing topic for how to get the information that is needed by IBM Support (alsoknown as “MustGather” information).

Diagnosing errors during getting started

The information contained here helps you to diagnose an error if you are usingCloud Provisioning. For information about how to diagnose an error if you areusing z/OSMF workflows, see “Getting started with CICS by using z/OSMFworkflows” on page 14.

Finding diagnostic information

Look in the following places to find information about the execution of z/OS PT:v The console after you enter a zospt command. The console output indicates the

result of the command.v z/OS PT logs. The logs are in the /logs directory in the z/OS PT installation

location and contain more debugging information, such as the exchangesbetween z/OS PT and z/OSMF. The most recent log file is named log_<useridrunning zospt>.0.

v The z/OSMF Web Interface. z/OSMF maintains workflow information for failedworkflows and this information is the primary source for identifying why aworkflow failed. Messages in the interface indicate the processing status.z/OSMF can surface messages that originate from elsewhere, such as z/OS itselfor one of its components. You can tell a z/OSMF message because it alwaysstarts with “IZU”.

v JES job output of jobs that are submitted by z/OSMF as part of a workflow.

An example of how to debug a problem

In this example, a deliberate error was put into the cics.properties file that isused to provision a CICS region. The template that contains the error was thenloaded into z/OSMF, approved and associated with a tenant so that it was in a'Draft approved' state and was ready to be run. A z/OS PT image, cics_debug, wasbuilt that named the z/OSMF template to use for provisioning.

To try out this example, set the property DFH_LE_HLQ to an invalid value in thecics.properties file and load the template into z/OSMF.

The following steps help diagnose the cause of the error.1. Run the cics_debug image in draft mode by running z/OS PT command zospt

run cics_debug --draft.The output from this command shows the deliberate error and gives moreinformation, including the container name (which is shown in bold in the codeoutput):ERROR: The request failed to complete.IZUWF0150E: The job that was submitted in step "Validating access to CICS data sets" failed duringautomation processing. Return code: "CC 0008" .Instance Name : CICS_USR01


Workflow Name : CICS_USR01provision1515683080153Current Step : validateCICSVariablesCurrent Step Title : Validating access to CICS data setsCurrent Step Description : This step runs a JES job to validate as many as possible of the templateproperties that are related to datasets. The job runs under the user ID specified by the DFH_ADMIN_TSOproperty and includes checks for the existence of datasets required during provision, the authority toaccess the datasets required during provision, and that there are not already datasets for theprovisioned region. If this step fails, see the JES job output to understand which properties or securitypermissions need correcting. The source JCL for the JES job contains comments for each step in the job,which describe what the step is checking and how to resolve any problems that are identified. If you areviewing this description from within the workflows view in the z/OSMF UI, then you can view the JES jobby clicking on the Status tab for the workflow step.DFH_CICS_TYPE : UnmanagedDFH_REGION_APPLID : CICPJZZ0Created container CICS_USR01 with id cfdd0d7a-7993-456e-ba18-a033c2f2567d on system MV29 in a failedstate. Use ’zospt rm --force CICS_USR01’ to remove it.Failed to run image cics_debug.

2. Use the container name (CICS_USR01) in z/OSMF to find the failed provisionrequest. Log in to z/OSMF. Go to Cloud Provisioning > Software Services andselect the Instances tab. Find the failed container instance by pasting its nameinto the Find field.

3. Click the instance name (the name of the failed container, CICS_USR01) toshow more information. Click the link to the workflow that was submitted torun the provision (shown in the following image).

4. The workflow steps show what the workflow was doing, and how far it got,before it failed. As in the following image, look for the first Failed step, whichmight be one of the parent steps in the list of workflow steps, or a substep ofan In Progress step.


To see the substeps that belong to a step, click the plus symbol next to a steptitle. Not all steps have substeps.

5. In this example, the Failed step is the Validating access to CICS data sets step.Click the step name for more information. Click the Status tab to see whathappened when the step ran.

6. In this example, the Validating access to CICS data sets step ran some JCL. Notall steps submit JCL, some create REST requests to other components ofz/OSMF.

Note: For any steps that do submit JCL, the job output can be seen on the JESspool as an alternative to debugging using z/OSMF.

7. The JCL output in the following figure shows that a Language Environment®

data set was not found.

Chapter 20. Troubleshooting z/OS PT 71

In this example, the marked text shows that the high-level qualifier (HLQ) forLanguage Environment data sets is incorrect. The fix would be to look in thecics.properties file and replace the HLQ for Language Environment data setswith the correct value.

8. The template needs to be refreshed to pick up the changed cics.properties,which can be done by following the instructions here “Adding a CICS templateby using IBM Cloud Provisioning and Management for z/OS” on page 77.

9. The failed provision attempt counts towards any limits set in z/OSMF on thenumber of instances a user can provision. Therefore, containers that failed toprovision must be deprovisioned. In this example, the container isdeprovisioned and removed by issuing z/OS PT command zospt rm -fCICS_USR01.This command generates some output, with the final message, in this example,Deleted container CICS_USR01.

Resolving problems that are found when CICS regions areprovisioned by z/OS PT

For help resolving problems that are found when CICS regions are provisioned byz/OS PT, see “Troubleshooting CICS provisioning with z/OS Provisioning Toolkit”on page 96.

Getting help with specific questions on dW Answers

dW Answers is an open forum for questions and answers about IBM products. Allquestions about z/OS PT are tagged with zospt. Some questions also have moretags, such as cics if they relate specifically to CICS with z/OS PT. Go to dWAnswers and click “Ask a question” to submit a new question.

Contacting IBM Support

If you cannot resolve the problem yourself using the diagnostic information that isprovided or suggestions in dW Answers, contact IBM. The IBM Software Support





http://www.ibm.com/support/customercare/sas/f/handbook/home.html

Handbook gives information about how to contact and work with IBM Support.The following pieces of information are helpful to IBM Support:v The console output from a failed request.v The logs that are written by z/OS PT.v The zosmf.properties file. It can be found in the /config directory in the z/OS

PT installation location.

Depending upon the type of error, IBM Support might ask for more information,such as:v z/OSMF configuration settingsv z/OSMF workflow outputv The template that you usedv Template propertiesv The z/OS PT image that you used.v z/OS PT image contents.v The logs that are written by the system that is being provisioned.

Chapter 20. Troubleshooting z/OS PT 73

http://www.ibm.com/support/customercare/sas/f/handbook/home.html

Chapter 21. Provisioning CICS with z/OS Provisioning Toolkit

With z/OS PT, you can rapidly provision regions of CICS Transaction Server forz/OS. Images for provisioning commonly used CICS environments, such as CICSTS with embedded z/OS Connect Enterprise Edition, CICS TS with a Liberty JVMserver, or standard CICS TS for traditional COBOL development, are provided.

Configuration prerequisites for using z/OS Provisioning Toolkit withCICS

In addition to the requirements for z/OS PT, some system configuration is neededto enable z/OS PT to provision CICS regions.

System requirements

For any specific system requirements to be able to provision CICS regions by usingz/OS PT, see the z/OS Provisioning Toolkit Software Compatibility Report.


Ensure that a data class that is compatible with creating zFS directories exists. Thefollowing table shows an example of a valid data class configuration:

Override Space No

Volume Count 15

Data set Name Type EXTENDED

If Extended PREFERRED

Extended Addressability Yes

Record Access Bias User

Space Constraint Relief No

Reuse No

Initial Load Recovery

RLS CF Cache Value All

RLS Above the 2-GB Bar No

Extent ConstraintRemoval

No

CA Reclaim Yes

Log Replicate No

System DeterminedBlocksize

No

Message suppression

Ensure that message suppression is switched off for the following messages:v DFHSI1517: Control is being given to CICS.v EYUNL0099I: LRT initialization complete.v EYUXL0010I: CMAS initialization complete .



v DFHKE1799: TERMINATION OF CICS IS COMPLETE.v IXG661I: SETLOGR FORCE DELETE PROCESSED SUCCESSFULLY FOR

LOGSTREAM=resourcename.

These messages are used by the CICS workflow and must be available to be sentto an extended MCS console that the workflow uses to determine whether CICS isstarted or stopped, and whether a CICS region's log streams have been successfullydeleted. For more information about suppressing messages, see Suppressingmessages in z/OS.

User ID authorization

User IDs that run the different steps of the provisioning process must have thecorrect security authorizations. For more information, see “Security requirementsfor provisioning CICS with z/OS Provisioning Toolkit” on page 82.

Overview of supported CICS typesThe workflows that are provided with z/OS PT for provisioning CICS regions, canbe customized by using configuration properties. To simplify the process ofcustomizing the CICS regions for particular roles, you can set a property thatdescribes the type of CICS region you want to provision. To set the CICS type,specify the DFH_CICS_TYPE property when you configure the template.

For more information about other configuration properties, see “Configurationproperties for CICS images” on page 84.

CMAS

The template is used to provision CICSPlex SM address spaces (CMASs). Eachprovision from the template creates a CMAS, and defines a CICSplex in the datarepository of the CMAS. The name of the CICSplex can be provided, or can begenerated as part of the provisioning process. After you provision a CMAS, it isthen possible to use z/OS PT to provision one or more WUI or MAS regions to thedefined CICSplex. If you specify DFH_CICS_TYPE=CMAS, extra properties can be set tocustomize the CMAS configuration, as described in “CICSPlex SM properties” onpage 91. It is not possible to add a provisioned CMAS to an existing CICSplex orcreate a CMAS to CMAS link from one CMAS to another by using z/OS PT.

MAS

The template is used to provision MAS regions. A MAS region is managed byCICSPlex SM and belongs to a CICSplex. Each provision creates a MAS region andconnects it into a CICSplex. The name of the CICSplex to connect the MAS into isspecified as part of the template configuration, as described in “CICSPlex SMproperties” on page 91. The MAS can either connect to a CICSplex defined in aCMAS that is provisioned by z/OS PT, or can be connected to an existingCICSplex that was defined outside of z/OS PT.

SMSS

The template is used to provision CICS regions that do not participate in aCICSplex, but that can be managed through CICS Explorer®. To enable CICSExplorer to be connected to a provisioned CICS region, a CMCI port is allocated tothe CICS region and the necessary CICS resources that are required to enable the


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.ieag300/mcsupp.htm


CMCI port are defined in the CSD of the region and are installed during the startof the CICS region.

Unmanaged

The template is used to provision CICS regions that do not participate in aCICSplex and cannot be managed through CICS Explorer. No ports are allocated tothe CICS region unless they are specified as required through other configurationproperties on the template.

WUI

The template is used to provision Web User Interface (WUI) regions. A WUI regionenables a CICSplex to be managed through CICS Explorer or through a Web UserInterface provided by the region. Each WUI region is managed by CICSPlex SMand participates in a CICSplex. The name of the CICSplex to connect the WUI intois specified as part of the template configuration, as described in “CICSPlex SMproperties” on page 91. A Web User Interface (WUI) region must be connected to aCMAS region of the same CICS version. The WUI can either connect to a CICSplexdefined in a CMAS that is provisioned by z/OS PT, or can be connected to anexisting CICSplex that was defined outside of z/OS PT.

To enable CICS Explorer to be connected to a provisioned WUI region, a CMCIport is allocated to the WUI region, and the CICS resources that are required toenable the CMCI port are defined in the CSD of the region. The CICS resources arethen installed during the start of the region. A second port is allocated to the WUIregion to enable the WUI to be provided for managing the CICSplex.

Adding a CICS template by using IBM Cloud Provisioning andManagement for z/OS

This scenario walks you through the steps that are involved in adding a CICSCloud Provisioning template into z/OSMF and testing that it works. Unlike thesimple Cloud Provisioning scenario, “Getting started with CICS by using CloudProvisioning”, this scenario uses a richer set of z/OSMF capabilities. Instead ofrunning under only one user ID, this scenario sets up the template to use thez/OSMF ability to run workflows under a set of authorized provisioning user IDs.z/OSMF can dynamically allocate APPLIDs and ports from resource pools, and itcan dynamically add and remove security profiles to set up security forprovisioned environments like CICS.

Before you begin

See the requirements in Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” on page39. In addition, you need:v A range of APPLIDs in a resource pool. (These APPLIDs can then be

dynamically allocated when you run z/OS PT).v A set of user IDs (agreed with your security administrator) that have sufficient

authority to provision a CICS environment. See “Security requirements forprovisioning CICS with z/OS Provisioning Toolkit” on page 82 for details.

v A range of ports in a resource pool. Ports can then be allocated to theprovisioned CICS regions.

Chapter 21. Provisioning CICS with z/OS PT 77

The simple Cloud Provisioning scenario, as described in “Getting started withCICS by using IBM Cloud Provisioning and Management for z/OS” on page 17,familiarizes you with the basic steps that are involved in adding and verifying atemplate and the interfaces used. Running through that scenario is a goodintroduction to the steps that you need to do here.

About this task

This scenario provisions a CICS TS V5.4 region from a template called cics_54.You go through the following steps:1. Copying a template if you want to have more than one variant of it.2. Configuring the properties that z/OSMF uses to process the template.3. Adding the Cloud Provisioning template into z/OSMF.4. Associating the template with a domain and tenant.5. Configuring the network resource pool.6. Approving the template for use.7. Running z/OS PT to provision CICS.

Procedure1. Optional: Duplicate the directory for more than one variant of the template.

For example, the /cics_54 directory under /templates. Give the new directorya different name but keep it in the /templates directory.

2. Configure the cics.properties file that z/OSMF uses to process the template:v z/OS PT includes sample cics.properties files for provisioning CICS TS

V5.2, CICS TS V5.3, and CICS TS V5.4 (zospt/templates/cics_5n/cics.properties). The files are in code page ISO-8859-1.

v Add any additional or alternative properties, refer to “Configurationproperties for CICS images” on page 84.

v Make sure that you include properties for the set of user IDs that hassufficient authority to provision a CICS environment.

v Do not set DFH_REGION_APPLID because this property prevents z/OS PTfrom accessing the pool of APPLID resources.

3. Load the template into z/OSMF through the z/OSMF Web Interface. (To seethis step with the inclusion of screen captures, see “Getting started with CICSby using IBM Cloud Provisioning and Management for z/OS” on page 17).a. Set the Template Source file as the path to the manifest file for the

template. For example, zospt/templates/cics_54/cics.mf. z/OSMF musthave sufficient authority to this directory tree.

b. Name your template. For example, cics_54

Note: The template name is important. It must match the name that isused in an image that is built with zospt.

The template is loaded into z/OSMF.4. Associate the template with a tenant in the domain in the z/OSMF Web

Interface. (To see this step with the inclusion of screen captures, see “Gettingstarted with CICS by using IBM Cloud Provisioning and Management forz/OS” on page 17). Select and specify the following properties and values:


Property Setting


Check the Use SNA APPLID check box (which automatically selects the Create networkresource pool check box).Note: To use z/OS PT, do not check the Create workload management pool check box.

Maximum number ofsoftware servicesinstances.

Specify the maximum number of software services instances that can be allocated.


Specify the maximum number of software services instances that can be allocated by anindividual user.

System selection forprovisioning

Choose the system in the sysplex into which you want to provision the CICS regions.The default is to provision into the same system that is running z/OSMF. For moreinformation about configuring z/OSMF for provisioning across different systems, seez/OSMF documentation.Note: To use z/OS PT, do not choose the option Prompt user for system.

5. Configure the network resource pool by using z/OSMF. Details about theinterface are given here because this step is not completed in the scenario“Getting started with CICS by using IBM Cloud Provisioning andManagement for z/OS” on page 17.a. Select Manage z/OS Cloud Configuration in the Configuration Assistant,

and click Proceed.b. Select Cloud Domain and click Proceed.c. Select the pool for your template in the Network Resource Pools table (it

is named domainname.tenantname.templatename).d. Select Modify from the Actions drop-down. In the Attributes tab, select Is

complete. Select the pool of ports that was previously agreed with yournetwork administrator for use in this template in the Port Allocation tab.Select the range of APPLIDs that was previously agreed with yournetwork administrator in the SNA Application Name Range.

e. Click Save. Your network resource pool is configured. For moreinformation, see z/OSMF documentation.

6. Ensure that your template is approved by your security administrator, andthat you have access to the pools of ports and APPLIDs. The template is nowready for testing with the zospt utility.

7. Set up the environment for z/OS PT. Set the following environment variables:v export zospt_domain=domain_name


8. Run z/OS PT to provision a CICS image that is using your template. Issue thecommand zospt run templatename --draft For example, zospt run cics_54--draft. The –-draft option is needed to run the template in “Draftapproved” state.If the properties are all correct, you see output of the steps of the zospt runcommand, ending with the following success message:Created container CICS_CICPJ00T with id 9a2b363a-8454-4c65-88e2-c6d1e19d1ae2

9. If an error is reported, see Chapter 20, “Troubleshooting z/OS ProvisioningToolkit,” on page 69 for where to find help. If an error results in a change tothe properties for the workflow, adjust the properties, refresh the template andretry:a. Update the properties file. For example, zospt/templates/cics_54/

cics.properties.




b. Refresh the template from the z/OSMF Web Interface. (To see this stepwith the inclusion of screen captures, see “Getting started with CICS byusing IBM Cloud Provisioning and Management for z/OS” on page 17).

c. Reapprove the template for use.d. Retry the zospt run, as described in step 8 on page 79. Issue the command

zospt rm --force containerName to remove the container that failed toprovision correctly.

10. Optional: Publish the template for everyone in the tenant to use. Remove the–-draft option after the template is published.

What to do next

Use z/OS PT to build images from the template that you loaded. See Chapter 12,“Building an image with z/OS Provisioning Toolkit,” on page 43 for details.

Including a CICS bundle in your imageBy using z/OS PT, you can include a CICS bundle, or a JVM server resource (orboth) in your image. CICS bundles can contain policies, OSGi, or Liberty Javaapplication code and resource definitions, including LIBRARYs for localapplications. The inclusion of a CICS bundle means that you are able to provisiona CICS region with a specific configuration, or with specific applications alreadyavailable.

CICS bundles

A CICS bundle is a directory that contains artifacts and a manifest that describesthe bundle and its dependencies. CICS bundles provide a way of grouping andmanaging related resources. CICS bundles also provide versioning for themanagement of resource updates, and can declare dependencies on other resourcesoutside the bundle. Application developers can use CICS bundles for applicationpackaging and deployment, business events, and services. System programmerscan use CICS bundles for policies. For more information about defining CICSbundles, see Defining CICS bundles.

How to include a CICS bundle in your image

You can include a CICS bundle in your image by updating the zosptfile toinclude COPY statements that list the CICS bundles to be added. All of the CICSbundle artifacts must be copied to the image source directory, which must containa zosptfile so that you can build the new image by using the zospt buildcommand. For more information about how to build an image with z/OS PT, seeChapter 12, “Building an image with z/OS Provisioning Toolkit,” on page 43.

CICS bundle installation

All CICS bundles that are installed are named as DFH$Bn, where n is a number inthe range 0 - 999.

JVM server creation

You can either define the type of JVM server you want in the zosptfile by usingthe DFH_REGION_JVMSERVER environment property, or you can define a JVMSERVERresource in the bundle. For more information about the possible values of


https://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/configuring/resources/defining_app_resources.html

DFH_REGION_JVMSERVER in the zosptfile, see “JVM configuration options” on page87.

Include a CICS bundle to provision a CICS region with a Libertyapplication1. Create your Liberty application (for example, a CICS TSQ sample).2. Create a CICS bundle to include the Liberty application you created.3. Export the CICS bundle into a UNIX System Services directory.4. Create a zosptfile in the same directory as the exported CICS bundle (for

example, directory bundleLiberty). Update the zosptfile to include COPYstatements that list the CICS bundles to be added. This example shows howyour zosptfile might look:FROM scratchENV ZOSMF_TEMPLATE=cics_54ENV DFH_REGION_JVMSERVER=Liberty

COPY com.ibm.server.examples.wlp.tsq.bundle bundles/com.ibm.server.examples.wlp.tsq.bundle

5. Build the zosptfile into an image called (in this example) myTSQSampleApp,by using command:zospt build -t myTSQSampleApp bundleLiberty

6. Run the image to create a container by using command:zospt run myTSQSampleApp

If the properties are all correct, the CICS region is provisioned with aconfigured JVM server named DFHWLP, a CICS bundle resource installed, andthe running TSQ sample in the JVM server.


Security requirements for provisioning CICS with z/OS ProvisioningToolkit

The user IDs that are used by z/OSMF to provision regions with z/OS PT requirecertain permissions to run steps of the provisioning process.

User ID Permissions Used for

DFH_ADMIN_TSO v READ DFH_CICS_HLQ.*

v READ DFH_CPSM_HLQ.*

v READ DFH_LE_HLQ.*

v READ.

v DFH_CICS_LICENSE_DATASET.

v ALTER (create/delete/read/write/update) DFH_REGION_HLQ.*.

v Authority to run TSO LISTCATcommand.

v ALTER DFH_LOG_HLQ.* (if specified).

v Authority to define log streams.

v UPDATE DFH_ZOS_PROCLIB (adddelete member).

v READ DFH_ZOS_PROCLIBname.STCJOBS (if you are using STCjobs).

v Authority to define MAS to the CMASby using EYU9XDBT.

v Authority to delete a MAS from theCMAS by using EYU9XDBT.

v Validating that CICS data sets exist.

v Creating CICS region data sets.

v Creating CICS log stream model.

v Creating CICS CSD definitions.

v Creating the CICS region JCL.

v Deleting standard CICS data sets.

v Creating the MAS definition.

v Deleting the MAS definition.

DFH_ADMIN_ZFS v r_x on DFH_CICS_USSHOME.

v r_x on DFH_JAVA_HOME.

v rwx DFH_ZFS_MOUNTPOINT.

v r__ image location.

v r_x on DFH_CICS_USSCONFIG.

v ALTER (create/delete/read/write/update) DFH_REGION_HLQ.*.

v Authority to run TSO MOUNTcommand.

v Authority to run TSO UNMOUNTcommand.

v Validating that zFS directories exist.

v Defining zFS.

v Creating JVM profile.

v Creating Liberty server.xml.

v Adding image into zFS file system.

v Checking zFS is mounted.

v Deleting zFS.

DFH_ADMIN_SECURITY v Permission to run the Rexx scripts fordynamic security and the commandsthat are issued by these Rexx scripts. Bydefault, the scripts immediately exit withreturn code zero and do not modify anysecurity profiles. This default behaviorallows for predefined security profiles tobe used. The scripts can be modified toissue commands to dynamically create,update, and delete the security profilesthat are needed for the provisioned CICSregion. For more information, see“Modifying the CICS workflows tosupport dynamic security” on page 83.

v Setting up CICS security.

v Deleting CICS security configuration.



DFH_ADMIN_CONSOLE v Authority to use console API (new userID XXXXXXCN where XXXXXX are thefirst six characters of the provisioninguser ID.

v Authority to issue console STARTcommand.

v Authority to issue modify commands forCEMT P SHUT and CEMT P SHUTIMM.

v Authority to issue cancel commands.

v Authority to issue force commands.

v Authority to delete log streams.

v Authority to issue display commands (todisplay if a CICS region is active, and todisplay details of the console that isused during provisioning to validate it isset up correctly to receive unsolicitedmessages).

v Starting the CICS region.

v Stopping the CICS region.

v Deleting CICS log stream model.

Modifying the CICS workflows to support dynamic securityThe CICS template provides workflows to provision and deprovision a CICSregion. A step in the workflows runs a Rexx script, in which security profiles canbe dynamically added, modified, and deleted (which enables the provision anddeprovision of a CICS region, and dynamically configures the security profiles forthat CICS region). The security workflow steps that are always run as part ofprovision and deprovision do not make any dynamic security changes.

Before you begin

Note:

Check the return code from each security command for an appropriate response indefineSecurity.rexx. If the Rexx script exits with a nonzero return code,provisioning of the CICS region fails.

Edit deleteSecurity.rexx to undo any changes that are made indefineSecurity.rexx.

A failure in provisioning a CICS region might occur before, during or after anydynamic security configuration is made. As deleteSecurity.rexx is always calledduring deprovision, edit deleteSecurity.rexx to delete security profiles that donot exist, or that were retried.

Procedure1. Locate these Rexx extensions for dynamic security: zospt/workflows/cics/

extensions/defineSecurity.rexx (this script is run during provision of a CICSregion) and zospt/workflows/cics/extensions/deleteSecurity.rexx (this scriptis run during deprovision of a CICS region).

2. Locate the line at the start of each Rexx script that issues exit 0. Make surethat any required security calls are made before this command.


3. Customize the scripts for your environment by using the sample Rexx scriptsas a guide.

Configuration properties for CICS imagesYou can configure a number of properties to customize the way that CICS isprovisioned through z/OS PT. Some properties are set when you configure atemplate. Other properties are used to configure an image. Properties for atemplate are specified in a cics.properties ISO8859-1 file, ready to load intoz/OSMF. Properties for an image are specified in a zosptfile, ready for use by thez/OS PT commands that build, run, and manage provisioned systems.

Type of CICS region

Property Description

DFH_CICS_TYPE To set your CICS region type, use one of the available options in the following list:

v CMAS - A single CICSPlex SM address space (CMAS) is provisioned, and aCICSplex is defined to the data repository of the CMAS. If you specify CMAS,you need to set extra properties, as described in “CICSPlex SM properties” onpage 91.

v MAS - A MAS region is managed by CICSPlex SM and participates in a CICSplex.If you specify MAS, you need to set extra properties, as described in “CICSPlexSM properties” on page 91.

v SMSS - An SMSS region is a stand-alone region that can be managed throughCMCI. Although it has CICSPlex SM libraries, it does not require a CMAS orparticipate in a CICSplex.

v Unmanaged - An unmanaged region is a stand-alone region that cannot bemanaged through CMCI.

v WUI - A Web User Interface (WUI) region must be connected to a CMAS region ofthe same version. If you specify WUI, you need to set extra properties, asdescribed in “CICSPlex SM properties” on page 91.

High-level qualifiers for your installation

Property Description Where set

DFH_CICS_HLQ High-level qualifier (HLQ) of the CICS installation location.DFH_CICS_HLQ is used to define the STEPLIB and DFHRPLconcatenations for provisioned CICS regions. If the CICSregion needs to access modules in the MVS link pack area(LPA), specify the SIT parameter LPA=YES in the compiledSIT named by the DFH_REGION_SIT property, or in theDFH_REGION_SITPARMS property itself.

Template

DFH_CPSM_HLQ High-level qualifier (HLQ) of the CICSPlex SM installationlocation

Template

DFH_LE_HLQ High-level qualifier (HLQ) of the Language Environment. Template

User IDs for the configuration

For more information about the steps for which each user ID is used, see “Securityrequirements for provisioning CICS with z/OS Provisioning Toolkit” on page 82.



DFH_ADMIN_TSO TSO user ID that is used for steps that require a greaterlevel of authority: For example, creating data sets.

Template

DFH_ADMIN_CONSOLE User ID that is used to issue MVS console commands byusing the z/OS console services API.

When z/OS console services are used, an MVS console iscreated and used to submit console commands. The MVSconsole name is the first six characters of theDFH_ADMIN_CONSOLE user ID followed by the letters'CN'. Ensure that system messages are routed to the consoleto allow the start and stop of the CICS region to bedetected.

For more information about the authorizations that arerequired by the DFH_ADMIN_CONSOLE user ID, see z/OSconsole services.

Also ensure that messages DFHSI1517, EYUNL0099I,EYUXL0010I, DFHKE1799, and IXG661I are not suppressedby the Message Processing Facility (MPF) as these messagesare used to detect when different types of CICS regions startand stop, and when a CICS region's log streams aresuccessfully deleted.

If multiple z/OSMF servers are installed on different LPARsin a sysplex, the generated MVS console name (the first sixcharacters of the DFH_ADMIN_CONSOLE user ID) must beunique on each LPAR.

Template

DFH_ADMIN_ZFS User ID that has z/FS authority to mount and unmountz/FS file systems.

Template

DFH_ADMIN_SECURITY User ID that has authorization to make dynamic securityprofiles changes within the Security Manager.

By default, no dynamic security updates are made, as theRexx scripts that are run immediately exit with return codezero. This default behavior allows for predefined securityprofiles to be used. The Rexx scripts can be modified toissue commands to dynamically create, update, and deletethe security profiles that are needed for the provisionedCICS region. For more information, see “Modifying theCICS workflows to support dynamic security” on page 83.

Template

DFH_APPROVER_TSO Approval user ID for TSO. Template

DFH_APPROVER_CONSOLE Approval user ID for DFH_ADMIN_CONSOLE user ID tobe used.

Template

DFH_APPROVER_SECURITY Approval user ID for dynamic security configuration. Template

DFH_APPROVER_ZFS Approval user ID for ZFS. Template

CICS region configuration


DFH_REGION_HLQ High-level qualifier (HLQ) for all CICS region data sets Template


http://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.izua700/IZUHPINFO_API_RESTCONSOLE.html



DFH_STC_ID The user ID with which CICS starts.

CICS runs as a started task and the job name matches theAPPLID of the CICS region. A SAF security profile mustexist that ensures the started task runs under theDFH_STC_ID user ID. This profile can either be predefined,or it can be created dynamically as part of the provisioningprocess. For more information, see “Modifying the CICSworkflows to support dynamic security” on page 83.

The provisioned CICS region creates log streams under theDFH_STC_ID user ID.

Template

DFH_REGION_LOGSTREAM_HLQ A high-level qualifier for the CICS log-stream names. Up to8 characters can be specified. This property is optional. Ifnot specified, the user ID of the running CICS region isused, which is specified by the DFH_STC_ID property.

Template

DFH_LOG_HLQ Used as the high-level qualifier for log-stream data setnames. This property is optional.

Template

DFH_REGION_CICSSVC The CICS SVC number that is installed on the MVS LPAR. Template

DFH_REGION_DFLTUSER User ID used as the default ID for the CICS region. Template

DFH_REGION_VTAMNODE Name of the VTAM® node to activate when the CICS regionstarts up.

Template

DFH_REGION_REGION JCL region size for the CICS JCL, in the format nnnnM (forexample, 400® M).

Template

DFH_REGION_MEMLIMIT JCL MEMLIMIT size for the CICS JCL, in the format mmG (forexample, 16G).

Template

DFH_CICS_LICENSE_DATASET Location of the CICS license data set. Template

z/OS configuration options


DFH_ZOS_PROCLIB Names the PROCLIB data set into which the workflow cancreate a procedure for the CICS region. The CICS regionruns as a started task. If you specify a PROCLIB that is aPDSE, it enables concurrent addition of new procedures tothe PROCLIB. If a PDS is used and multiple concurrentupdates to the PROCLIB are attempted, z/OS abends themwith a 213-30 abend code, to avoid data corruption.

Template

DFH_ZOS_STCJOBS Names the data set into which the workflow can create thesource JCL that defines the job level characteristics of thestarted task for the provisioned CICS region. Only usedwhen DFH_STC_JOB_CARD is also specified. Specify adata set of type PDSE to enables concurrent addition ofnew STCJOBS to the data set. If a data set of type PDS isused and multiple concurrent updates to the data set areattempted, z/OS produces a 213-30 abend code, to avoiddata corruption.

Template

DFH_STC_JOB_CARD Specifies the job card to use to define the job levelcharacteristics of the started task for the provisioned CICSregion. When specified, DFH_ZOS_STCJOBS must also beused to indicate the data set for STCJOBS.

Template

DFH_ZOS_VSAM_UNIT UNIT value that is used in creation of data sets, forexample: SYSDA, 3390

Template



DFH_ZOS_VSAM_VOLUME VOLUME value that is used in the creation of data sets.For example, SYSDA. If the value is specified as SMS(Storage Management Subsystem), the VOLUME parameteris omitted from the VSAM creation.

Template

zFS configuration options


DFH_ZFS_DATACLASS DATACLASS (a list of data set allocation attributes andtheir values) defined on z/OS that is used to create thezFS data sets. For more information about setup details,see “Configuration prerequisites for using z/OSProvisioning Toolkit with CICS” on page 75. Fornon-SMS-managed systems, either remove theDFH_ZFS_DATACLASS property, or do not give theproperty a value. Instead, you can specify a value forDFH_ZOS_VSAM_VOLUME and this value is used.

Template

DFH_ZFS_GROUP Specifies the name of a SAF group, which is granted read,write and execute authority to the CICS region zFSdirectory and contents.

Template

DFH_ZFS_MOUNTPOINT zFS directory that is used to mount the zFS directories fora CICS region.

Template

DFH_CICS_USSHOME Location of the CICS USSHOME installation Template

DFH_CICS_USSCONFIG Specifies the directory in which z/OS UNIX configurationfiles for the CICS region are stored. The USSCONFIG SITparameter for each provisioned CICS region is set to thisdirectory. An SSL cipher suite specification file that iscalled strongciphers.xml must exist in the zFSsubdirectory <DFH_CICS_USSCONFIG>/security/ciphers.Sample cipher suite files are provided in the<DFH_CICS_USSHOME>/security/ciphers directory. For moreinformation about cipher suite files, see CICS TransactionServer for z/OS, V5.4.

Template

DFH_ZCEE_INSTALL_DIR The runtime directory within the installation directory ofz/OS Connect EE (only relevant when you areprovisioning images for CICS and z/OS Connect EE). Forexample, /usr/lpp/IBM/zosconnect/v3r0/runtime

Template

JVM configuration options


DFH_JAVA_HOME Location of the Java installation Template

DFH_REGION_JVMSERVER The type of JVM server for z/OS PT to provision. See thefollowing permitted values:

v Liberty - provisions a Liberty JVM server namedDFHWLP.

v OSGi - provisions an OSGi JVM server namedDFHOSGI.

v Axis2 - provisions an Axis2 JVM server namedDFHJVMAX.

v None - does not provision a JVM server.

Template or image.If set on the image,this value overridesthe value set in thetemplate by thecics.propertiesfile.


https://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/home/welcome.html



DFH_JVM_DEBUG Dynamically allocate a port for the remote debugging of aJVM server. If DFH_REGION_JVMSERVER is set toLiberty, OSGi, or Axis2, the JVM server is configured touse the allocated port. See the following permitted values:

v YES

v NO

If not set, no JVM debug port is allocated.

Template

DFH_ZOSCONNECT_USERID The default user ID for z/OS Connect EE. Template or image.If set on the image,this value overridesthe value set in thetemplate by thecics.propertiesfile.

Networking variables


DFH_REGION_HTTP Dynamically allocate an HTTP port during provision. Seethe following permitted values:

v YES

v NO

If not set, no HTTP port is allocated.

Template

DFH_REGION_HTTPS Dynamically allocate an HTTPS port during provision.See the following permitted values:

v YES

v NO

If not set, no HTTPS port is allocated.

Template

DFH_REGION_IPIC Dynamically allocate an IPIC port during provision. Seethe following permitted values:

v YES

v NO

When set to YES, a TCPIPSERVICE is configured for theCICS region to listen for inbound IPIC requests. Thedefault autoinstall program for IPCONN resources(DFHISAIP) is enabled so that outbound IPCONNconnections can be automatically created when aninbound request is received. When set to NO, or not set,no IPIC port is allocated.

If the property DFH_REGION_SEC=NO is specified, theIPIC port is unsecured. If the propertyDFH_REGION_SEC=YES is specified, the IPIC port issecured by using SSL with client authentication. Thedefault autoinstall program DFHISAIP creates IPCONNresources that specify SSL(NO) as one of their parameters,meaning that outbound IPIC connections are not securedby SSL.

Template


Security options


DFH_REGION_KEYRING Name of a key ring. Used for SSL or TLS connections toCICS. You must specify this property only when:

v DFH_REGION_SEC is set to YES, andDFH_CICS_TYPE is set to SMSS, meaning that a secureCMCI port is created.

v DFH_REGION_JVMSERVER is set to None, OSGI orAxis2, and DFH_REGION_HTTPS is set to YES,meaning that an HTTPS port is created.

If no value is specified and the property is needed, theAPPLID of the CICS region is used. The key ring can bedynamically created as part of the provisioning process.For more information, see “Modifying the CICSworkflows to support dynamic security” on page 83.

Template

DFH_REGION_SEC Specify whether security is enabled for the CICS region.Note: If the value is specified as NO, all other securityoptions are ignored.

Template

DFH_REGION_SECPRFX Specify whether to use SECPREFX. If no value isspecified, the APPLID of the CICS region is used.

Permitted values are <blank> | NO | YES | prefix.

Template

DFH_REGION_XAPPC Specify whether RACF® session security can be used withAPPC connections. Permitted values are NO | YES.

Template

DFH_REGION_XCMD Specify whether CICS command security is enabled.Permitted values are NO | YES | classname.

Template

DFH_REGION_XDB2 Specify whether DB2ENTRY security checking is enabled.Permitted values are NO | classname.

Template

DFH_REGION_XDCT Specify whether transient data queue security is enabled.Permitted values are NO | YES | classname.

Template

DFH_REGION_XFCT Specify whether file security is enabled. Permitted valuesare NO | YES | classname.

Template

DFH_REGION_XHFS Specify whether zFS file security is enabled. Permittedvalues are NO | YES.

Template

DFH_REGION_XJCT Specify whether journal security is enabled. Permittedvalues are NO | YES | classname.

Template

DFH_REGION_XPCT Specify whether started transaction security is enabled.Permitted values are NO | YES | classname.

Template

DFH_REGION_XPPT Specify whether program security is enabled. Permittedvalues are NO | YES | classname.

Template

DFH_REGION_XPSB Specify whether program specification block security isenabled. Permitted values are NO | YES | classname.

Template

DFH_REGION_XPTKT Specify whether PassTicket security is enabled. XPTKT isa new security option that requires a CICS APAR to beapplied. Permitted values are NO | YES.

Template

DFH_REGION_XRES Specify whether CICS resource security is enabled.Permitted values are NO | YES | classname.

Template

DFH_REGION_XTRAN Specify whether transaction attach security is enabled.Permitted values are NO | YES | classname.

Template

DFH_REGION_XTST Specify whether temporary storage queue security isenabled. Permitted values are NO | YES | classname.

Template



DFH_REGION_XUSER Specify whether surrogate user checking is enabled.Permitted values are NO | YES.

Template

Registration properties

For a list of properties to register a CICS workflow, see Table 6 on page 112.

Optional CICS properties

The following optional properties are used to insert SIT parameters and data setsinto the provisioned region.


DFH_REGION_STEPLIB Comma-separated list of variables to append to thestandard CICS and Language Environment STEPLIBdata sets.

Template

DFH_REGION_STEPLIB_TOP Comma-separated list of variables to add before thestandard CICS and Language Environment STEPLIBdata sets.

Template

DFH_REGION_RPL Comma-separated list of variables to append to thestandard CICS and Language Environment DFHRPLdata sets.

Template

DFH_REGION_RPL_TOP Comma-separated list of variables to add before thestandard CICS and Language Environment DFHRPLdata sets.

Template

DFH_REGION_CSD_TYPE Specify whether a new CSD needs to be created for eachCICS region, or whether an existing CSD can be shared.For more information about sharing a CSD, see “SharedCSD guidance” on page 94. The default is to create anew CSD, which is then deleted when the CICS region isdeprovisioned.

The provisioning process adds region-specific resourcesto the CSD. During deprovision those resources getremoved from the CSD if it is shared. When a CSD isshared, the CSD must be accessed in a way that allowsthe successful provision and deprovision of other CICSregions.

Permitted values are NEW | SHAREDREADONLY |SHAREDRLS. Use SHAREDREADONLY to provisionCICS regions that access a non-RLS CSD in read onlymode. Provision and deprovision fail if region-specificresources cannot be added or removed due to the CSDbeing in use. Use SHAREDRLS to provision CICSregions that need to access the CSD in update mode.

CSD-specific CICS system initialization parameters areautomatically set based on the value of this property andcannot be overridden. For more information about CICSsystem initialization parameters, see “Specifying moreCICS system initialization parameters” on page 92.

Template



DFH_REGION_CSD_NAME Specify the name of an existing CSD to be shared by theprovisioned CICS regions. This option is only applicablewhen DFH_REGION_CSD_TYPE=SHAREDREADONLY| SHAREDRLS.

Template

DFH_REGION_CSD_INPUT Comma-separated list of variables that allow data sets tobe inserted into the CSD upgrade job, for example:DFH_REGION_CSD_INPUT=CICPROV.CSD(EQACSD13).This option is only applicable whenDFH_REGION_CSD_TYPE=NEW.

Template

DFH_REGION_SIT The two-character name of the compiled SIT. Template

DFH_REGION_SITPARMS A provisioned CICS region is automatically configuredwith a set of system initialization (SIT) parameters.DFH_REGION_SITPARMS enables more SIT parametersto be specified for further customization of the region.The parameters must be comma-separated, for example:DFH_REGION_SITPARMS=DEBUGTOOL=YES,AUXTR=ON

For more information about which SIT properties areauto-configured and how, see “Specifying more CICSsystem initialization parameters” on page 92.

Template

DFH_REGION_DD_LIST Comma-separated list of DD cards to add to the CICSregion JCL. Commas can be included in the DD card byprefixing them with two backslashes "\\". Do notinclude "//" at the beginning of the line.

Template

DFH_CICS_LLQ CICS installation data set low-level qualifier, for exampleCICSLLQ is returned:

CTS530.CICS700.SDFHAUTH.CICSLLQCTS530.CICS700.SDFHLOAD.CICSLLQCTS530.CICS700.SDFJAUTH.CICSLLQ

Template

DFH_CPSM_LLQ CICSPlex SM installation data set low-level qualifier, forexample CPSMLLQ is returned:

CTS530.CPSM530.SEYUAUTH.CPSMLLQCTS530.CPSM530.SEYULOAD.CPSMLLQ

Template

CICSPlex SM properties

The following optional properties are used to configure CICS regions thatparticipate in a CICSplex.

Property Description DFH_CICS_TYPE Where set

DFH_CICSPLEX_DEF Use this property to set the name of aCICSplex to be created during provision of aCMAS. If no value is specified, the CICSplexname is dynamically generated as part of theprovisioning process.

CMAS Template orimage

DFH_CICSPLEX The name of the CICSplex the MAS or WUI isassociated with.

MAS or WUI Template

DFH_CMAS_APPLID The VTAM APPLID of the CMAS the MAS orWUI is attached to. This property is optional.

MAS or WUI Template


Property Description DFH_CICS_TYPE Where set

CMAS_REGISTRY_NAME This property can be set when you provision aWUI or a MAS region. The provisioningworkflow looks for the CMAS in the z/OSMFregistry to get the information needed for theworkflow to connect to the CMAS. Thisproperty is optional and can be specified as analternative to DFH_CICSPLEX and optionalproperties DFH_CMAS_APPLID andDFH_CMAS_SYSID.

MAS or WUI Template

DFH_CMAS_SYSID The SYSID of the CMAS the MAS or WUI isattached to. This property is optional.

MAS or WUI Template

DFH_CICSGRP The CICS system group the MAS or WUI isattached to. The CICS system group mustalready be defined in the CICSplex. Thisproperty is optional.

MAS or WUI Template

DFH_REGION_EYUPARMS Define EYUPARM settings for this region in acomma-separated list. This property is optional.

CMAS or MASor WUI

Template

DFH_REGION_WUIPARMS Define WUI server initialization parameters ina comma-separated list. This property isoptional.

WUI Template

Provisioning process customizations


DFH_START_TIMEOUT The amount of time to wait for the CICS region to startbefore it reports an error. The valid range is 30 - 600 seconds.The default is 30 seconds.

Template

DFH_STOP_TIMEOUT The amount of time to wait for the CICS region to stopbefore it attempts a more forceful stop. The stop order isCEMT P SHUT, CEMT P SHUT IMMEDIATE, CANCEL. Thevalid range is 10 - 600 seconds. The default is 30 seconds.

Template

TEMP_DIR The name of a temporary directory into which theDFH_ADMIN_ZFS user ID can create, update, and deletefiles. The default directory is /tmp. When you areprovisioning CICS regions across systems within a sysplex,the temporary directory must be accessible from the systemthat is running z/OSMF and the system on which theenvironment is being provisioned.

Template

VALIDATE_PARAMETERS During the provision of a CICS region, several steps are runto validate the configured templates properties. When thetemplate is correctly configured, you can choose not to runthese steps, which shorten the time that it takes to provisioneach region. Permitted values are YES | NO. The default isYES.

Template

DFH_DELETE_LOGSTREAM_TIMEOUTThe amount of time the workflow waits to detect successfuldeletion of the CICS region's log streams during deprovision.The valid range is 10 - 600 seconds. The default is 30seconds.

Template

Specifying more CICS system initialization parameters

CICS regions are provisioned with system initialization (SIT) parameters that areautomatically configured to support the properties that are defined in the template.


Use the DFH_REGION_SITPARMS property for further customization of SITparameters for CICS regions. Any SIT parameter can be specified by usingDFH_REGION_SITPARMS, but any conflicting SIT parameters are overridden bythe automatically configured SIT parameters (conflicts are commented out in thegenerated started task procedure for the CICS region). The following table lists SITparameters that are automatically configured and whether they can be overridden.SIT parameters not in the table can all be specified on theDFH_REGION_SITPARMS property.

SIT parameter How it is configured Can be overridden

APPLID Set to the dynamically obtained APPLID for the CICSregion.

No

CICSSVC Set to the value of the DFH_REGION_CICSSVC property. No

CPSMCONN Set to LMAS if the value of DFH_CICS_TYPE=MAS. No

CSDACC Set to READONLY or READWRITE depending on theDFH_REGION_CSD_TYPE property.

No

CSDRLS Set to YES if DFH_REGION_CSD_TYPE=SHAREDRLS,otherwise set to NO.

No

DFLTUSER Set to the value of the DFH_REGION_DFLTUSER property. No

GMTEXT Set to a string that includes the dynamic APPLID of theprovisioned region and the type of region that is beingprovisioned.

Yes

GMTRAN Set to CESN if DFH_REGION_SEC=YES Yes

GRPLIST Set to DFHLIST and a list that contains the specific resourcedefinitions for the provisioned CICS region.

Yes, but the providedGRPLIST must includethe CICS groups typicallyin DFHLIST and mustspecify a maximum ofthree entries (the fourthentry is used during theprovisioning process toadd specific resourcedefinitions for theprovisioned CICS region).

IRCSTRT Set to YES. Yes

ISC Set to YES. Yes

JVMPROFILEDIR Set to a dynamically provisioned zFS directory for the CICSregion.

No

KEYRING Set to the value of the DFH_REGION_KEYRING property,or the dynamically provisioned APPLID of the CICS region,if DFH_REGION_KEYRING is not specified. Set whenDFH_REGION_SEC=YES.

No

RLS Set to YES only if DFH_REGION_CSD_TYPE=SHAREDRLS. Only whenDFH_REGION_CSD_TYPEis not SHAREDRLS.

SEC Set to the value of the DFH_REGION_SEC property. No

SECPRFX Set to the value of the DFH_REGION_SECPRFX property,or the dynamically provisioned APPLID of the CICS regionif the DFH_REGION_SECPRFX property is not set.

No

SIT Set to the value of the DFH_REGION_SIT property. No

START Set to AUTO. Yes


SIT parameter How it is configured Can be overridden

SYSIDNT Set to a dynamic system ID based on the dynamic APPLIDfor the CICS region.

No

TCPIP Always set to YES to enable the CICS region to openTCPIPSERVICES for web or IPIC traffic.

No

TRANISO Set to YES. Yes

USSHOME Set to the value of the DFH_CICS_USSHOME property. No

USSCONFIG Set to the value of the DFH_CICS_USSCONFIG property. No

XAPPC Set to the value of the DFH_REGION_XAPPC property. No

XCMD Set to the value of the DFH_REGION_XCMD property. No

XDB2 Set to the value of the DFH_REGION_XDB2 property. No

XDCT Set to the value of the DFH_REGION_XDCT property. No

XFCT Set to the value of the DFH_REGION_XFCT property. No

XHFS Set to the value of the DFH_REGION_XHFS property. No

XJCT Set to the value of the DFH_REGION_XJCT property. No

XPCT Set to the value of the DFH_REGION_XPCT property. No

XPPT Set to the value of the DFH_REGION_XPPT property. No

XPSB Set to the value of the DFH_REGION_XPSB property. No

XPTKT Set to the value of the DFH_REGION_XPTKT property. No

XRES Set to the value of the DFH_REGION_XRES property. No

XTRAN Set to the value of the DFH_REGION_XTRAN property. No

XTST Set to the value of the DFH_REGION_XTST property. No

XUSER Set to the value of the DFH_REGION_XUSER property. No

Shared CSD guidance

By default when a CICS region is provisioned, a new CSD is defined for that CICSregion. When the CICS region is deprovisioned, the CSD is deleted, which ensuresthat each CICS region has a unique CSD and any changes that are made to thatCSD do not affect other CICS regions.

By changing the value of the DFH_REGION_CSD_TYPE parameter, it is possible toprovision CICS regions that share an existing CSD. Using a shared CSD ensuresthat updates to the CSD are available to all CICS regions that share the CSD. If aCSD is shared, it must not be held open by a CICS region. A CSD remaining opencan cause provision and deprovision failures.

The shared CSD can be used for regions that are provisioned and deprovisioned byusing z/OSMF to avoid situations where a CSD held open in a CICS region cancause provisioning and deprovisioning failures. One approach is to clone anexisting CSD and then use that clone as the shared CSD for provisioning.

Accessing the CSD by using RLS provides the highest level of sharing. If the CICSregions you provision need to update the CSD, specifyDFH_REGION_CSD_TYPE=SHAREDRLS. For more information aboutconsiderations for creating a CSD, see CICS Transaction Server for z/OS, V5.4.



If the CICS regions you provision do not need to update the CSD, then a non-RLSCSD can be shared. The CICS regions open the CSD in read only mode, whichavoids problems with the CSD being locked when DFHCSDUP jobs are run duringthe provision and deprovision workflows. This option is specified by the propertyDFH_REGION_CSD_TYPE=SHAREDREADONLY.

If you need to make updates to a non-RLS shared CSD, ensure that the updates donot cause provisioning and deprovisioning failures. DFHCSDUP jobs that aresubmitted by the provisioning workflows include an extra DD statement thatopens a data set exclusively. This data set is used as a serialization mechanism toensure that the DFHCSDUP jobs do not cause each other to fail due to the CSDbeing in use when multiple provisions or deprovisions are running at the sametime. You can specify the same DD card in your own DFHCSDUP jobs to serializeyour updates with updates that are made during the provisioning anddeprovisioning processes. The DD card is//CSDLOCK DD DSN=<DFH_REGION_HLQ>.CSDLOCK,// DISP=(MOD,CATLG),// UNIT=<DFH_ZOS_VSAM_UNIT>,SPACE=(1,1)

where the values of DFH_REGION_HLQ and DFH_ZOS_VSAM_UNIT areproperties that are described in tables “CICS region configuration ” on page 85 and“z/OS configuration options” on page 86.

Modifying the set of CICS configuration properties that can beoverridden

The CICS template provides workflows to provision and deprovision a CICSregion. A set of properties determine the configuration of the provisioned CICSregion. These properties are set before the template is added to z/OSMF and canbe changed only by refreshing the template in z/OSMF, or creating a new versionof the template. To enable different configurations of provisioned CICS regions thatuse the same template in z/OSMF, you can override the values of a subset of theproperties that are set in the template. The override can be done by specifying theproperties in a z/OS PT image. The subset of properties that can be overridden inan image can be customized for your environment.

Before you begin

Consider the amount of flexibility you would like in customizing the CICS regionsthat are provisioned from each z/OSMF template. Templates added into z/OSMFhave an approval process, where users across the organization can approve theautomation steps that are taken during the provisioning process. The values set forthe template properties affect these automation steps (for example, you can specifythe high-level qualifier for data sets that are created during the provisioning ofeach CICS region).

Properties that affect the provisioning process, for example, data set high-levelqualifiers, would need to be reviewed as part of the template approval process, sothese properties cannot be overridden in a z/OS PT image.

Properties that change the configuration of the CICS region, for example, its SITparameters, and DFHRPL concatenation, might be appropriate to be overridden ina z/OS PT image so that the same template can be used to provision CICS regionswith different configurations. Other examples of properties that can be overriddenin the z/OS PT images include properties that allow provisioned MAS or WUIregions to connect into different CICSplexes or CICS groups.


Overriding properties in this way can minimize the number of templates that needto be maintained and approved in z/OSMF. To ensure that only users with thecorrect permissions can build images, you can restrict the permissions of theimages directory in z/OS PT.

Procedure1. Locate the image_properties.xml file: zospt/workflows/cics/extensions/

image_properties.xml. This file describes which template properties areallowed to be overridden in a z/OS PT image.

2. To determine whether the set of template properties that can be overridden isappropriate, review the descriptions of the properties in theimage_properties.xml file.

3. To add more properties that can be overridden, uncomment or add extraatCreate XML elements to the file. To limit the set of properties that can beoverridden, comment out or delete the appropriate atCreate XML elementsfrom the file. For example, to override the CMAS_REGISTRY_NAME,uncomment, or add the following line to image_properties.xml:<atCreate name="CMAS_REGISTRY_NAME" required="false" prompt="false"/>.The full set of CICS properties is described in “Configuration properties forCICS images” on page 84, but check image_properties.xml for the propertiesthat can be overridden.

Troubleshooting CICS provisioning with z/OS Provisioning ToolkitUse this information to help diagnose common problems that are found whenCICS regions are provisioned by z/OS PT.

Diagnosing the error in step Checking the rest status from thestart command in zospt run command output

When you use the zospt run command to provision a CICS container from animage, workflow step Checking the rest status from the start command can failwith a return code of 8. If this step fails, it is because the previous step failed todetect a console message indicating that CICS has successfully completed itsstartup processing. The message being detected varies depending on the type ofCICS region being provisioned.v When DFH_CICS_TYPE equals Unmanaged or SMSS, the message number is

DFHSI1517.v When DFH_CICS_TYPE equals MAS or WUI, the message number is

EYUNL0099I.v When DFH_CICS_TYPE equals CMAS, the message number is EYUXL0010I

Check the CICS job log to find out whether the appropriate console message wasissued. If it was not, the reason should be apparent in the job log. If the consolemessage was successfully issued, but not detected, refer to the “Configurationproperties for CICS images” on page 84 description of theDFH_ADMIN_CONSOLE property, to ensure that the userid being used forconsole commands has been configured correctly to be able to find unsolicitedmessages from an extended MCS console, and that message suppression is notsuppressing the console message that is being searched for. It is also possible toadjust the amount of time that the workflow waits to detect the console messageafter issuing the command to start the CICS region. Refer to the description of theDFH_START_TIMEOUT property to understand the default wait time. If the


console message was not issued within that time period, consider increasing thevalue of the property.

Diagnosing other z/OS PT problems

For more information about troubleshooting z/OS PT, see Chapter 20,“Troubleshooting z/OS Provisioning Toolkit,” on page 69.


Chapter 22. Provisioning z/OS Connect Enterprise Editionwith z/OS Provisioning Toolkit

With z/OS PT, you can provision a stand-alone instance of an IBM z/OS ConnectEnterprise Edition server, or provision an instance of z/OS Connect EE embeddedin CICS. Both IBM z/OS Connect Enterprise Edition V2.0 and IBM z/OS ConnectEnterprise Edition V3.0 can be provisioned by using z/OS PT. Find out more abouthow to provision a stand-alone instance of a z/OS Connect EE server.

Configuration prerequisites for using z/OS Provisioning Toolkit withz/OS Connect Enterprise Edition

In addition to the requirements for z/OS PT, some system configuration is neededto enable z/OS PT to provision instances of z/OS Connect EE.

System requirements

For any specific system requirements to be able to provision instances of z/OSConnect EE by using z/OS PT, see the z/OS Provisioning Toolkit SoftwareCompatibility Report.


Ensure that a data class that is compatible with creating zFS directories exists. Thistable shows an example of a valid data class configuration:

Override Space No

Volume Count 15

Data set Name Type EXTENDED

If Extended PREFERRED

Extended Addressability Yes

Record Access Bias User

Space Constraint Relief No

Reuse No

Initial Load Recovery

RLS CF Cache Value All

RLS Above the 2-GB Bar No

Extent ConstraintRemoval

No

CA Reclaim Yes

Log Replicate No

System DeterminedBlocksize

No




Message suppression

Ensure that message suppression is switched off for the following message:v CWWKF0011I - z/OS Connect EE is started.

This message is used by the z/OS Connect EE workflow and needs to be availableto be sent to an extended MCS console that the workflow uses to determinewhether z/OS Connect EE is started. For more information about suppressingmessages, see Suppressing messages in z/OS.

User ID authorization

Ensure that the user IDs that run the various steps of the provisioning process,have the appropriate security authorizations. For more information, see z/OSProvisioning Toolkit Software Compatibility Report.

Adding a z/OS Connect Enterprise Edition template by using IBMCloud Provisioning and Management for z/OS

This scenario walks you through the steps that are involved in adding a z/OSConnect EE Cloud Provisioning template into z/OSMF and testing that it works.This scenario sets up the template to use the z/OSMF ability to run workflowsunder a set of authorized provisioning user IDs. z/OSMF can dynamically allocateports from a pool of resources, and it can dynamically add and remove securityprofiles to set up security for provisioned environments like z/OS Connect EE.

Before you begin

See the requirements in Chapter 10, “Adding an IBM Cloud Provisioning andManagement for z/OS template for use with z/OS Provisioning Toolkit,” on page39. In addition, you need:v A range of ports in a resource pool. (These ports can then be dynamically

allocated when you run z/OS PT).v A set of user IDs (agreed with your security administrator) that has sufficient

authority to provision an instance of z/OS Connect EE. See “Securityrequirements for provisioning instances of z/OS Connect EE with z/OSProvisioning Toolkit” on page 103 for details.

About this task

This scenario provisions an instance of z/OS Connect Enterprise Edition V2.0 froma template called zosconnect_v2r0. You go through the following steps:1. Copying a template if you want to have more than one variant of it.2. Configuring the properties that z/OSMF uses to process the template.3. Adding the Cloud Provisioning template into z/OSMF.4. Associating the template with a domain and tenant.5. Configuring the network resource pool.6. Approving the template for use.7. Running z/OS PT to provision instances of z/OS Connect EE.





Procedure1. Optional: Duplicate the directory for more than one variant of the template.

For example, the /zosconnect_v2r0 directory) under /templates. Give the newdirectory a different name but keep it in the /templates folder.

2. Configure the zosconnect.properties file that z/OSMF uses to process thetemplate:v z/OS PT includes sample zosconnect.properties for provisioning instances

of z/OS Connect Enterprise Edition V2.0 (zospt/templates/zosconnect_v2r0/zosconnect.properties). The properties file is in codepage ISO-8859-1.

v Add any additional or alternative properties, refer to “Configurationproperties for z/OS Connect Enterprise Edition images” on page 106.

v Make sure that you include properties for the set of user IDs that hassufficient authority to provision a z/OS Connect EE instance.

3. In the z/OSMF Web Interface, load the template into z/OSMF.a. Set the Template Source file as the path to the manifest file for the

template. For example, zospt/templates/zosconnect_v2r0/zosconnect.mf.z/OSMF must have sufficient authority to this directory tree.

b. Name your template. For example, zosconnect_v2r0

Note: The template name is important. It must match the name that isused in an image that is built with zospt.

The template is loaded into z/OSMF.4. In the z/OSMF Web Interface, associate the template with a tenant in the

domain. Select and specify the following properties and values:

Property Setting


Choose a prefix of up to 5 characters; this prefix is used as the first 5 characters of theprovisioned instance's job name.Note: To use z/OS PT, do not check the Create workload management pool check box.

Maximum number ofsoftware servicesinstances.

Specify the maximum number of software services instances that can be allocated.


Specify the maximum number of software services instances that can be allocated by anindividual user.

System selection forprovisioning

Choose the system in the sysplex into which to provision the CICS regions. The default isto provision into the same system on which z/OSMF is running. For more informationabout configuring z/OSMF for provisioning across different systems, see z/OSMFdocumentation.Note: To use z/OS PT, do not choose the option Prompt user for system.

5. In z/OSMF, configure the network resource pool.a. In the Configuration Assistant, select Manage z/OS Cloud Configuration

and click Proceed.b. Select Cloud Domain and click Proceed.c. Select the pool for your template from the Network Resource Pools

table(the pool is named domainname.tenantname.templatename).d. Select Modify from the Actions drop-down. Select Is complete in the

Attributes tab. Select the pool of ports that was agreed with your networkadministrator for use in this template in the Port Allocation tab.

Chapter 22. Provisioning z/OS Connect EE with z/OS PT 101



e. Click Save. Your network resource pool is configured. For moreinformation about configuring the network resource pool, see z/OSMFdocumentation.

6. Ensure that all the steps in your template are approved by the user IDsspecified in the zosconnect.properties file. The template is now ready fortesting with the zospt utility.

7. Set up the environment for z/OS PT. Set the following environment variables:v export zospt_domain=domain_name


8. Run z/OS PT to provision an instance of z/OS Connect EE by using yourtemplate. Issue the command zospt run imageName --draft (where imageNamemight be the same as templateName), for example, zospt run zosconnect_v2r0--draft. The –-draft option is needed to run the template in ‘Draft approved’state.If the properties are all correct, you see output of the steps of the zospt runcommand, ending with the following success message:Created container ZOSCONNECT_ZCON01 with id 031fa6c4-91c4-4035-989e-c898a5cc8049

9. If an error is reported, see Chapter 20, “Troubleshooting z/OS ProvisioningToolkit,” on page 69 for where to find help. If an error results in a change tothe properties for the workflow, adjust the properties, refresh the template andretry:a. Update the properties file. For example, zospt/templates/

zosconnect_v2r0/zosconnect.properties.b. From the z/OSMF Web Interface, refresh the template.c. Reapprove the template for use.d. Retry the zospt run, as described in step 8. Issue the command zospt rm

--force containerName to remove the container that failed to provisioncorrectly.

10. Optional: Publish the template for everyone in the tenant to use. Remove the–-draft option after the template is published.

What to do next

Use z/OS PT to build images from the template that you loaded. See Chapter 12,“Building an image with z/OS Provisioning Toolkit,” on page 43 for details.




Security requirements for provisioning instances of z/OS Connect EEwith z/OS Provisioning Toolkit

The user IDs that are used by z/OSMF to provision instances of z/OS Connect EEwith z/OS PT require certain permissions to run steps of the provisioning process.


ZCON_ADMIN_CONSOLE v Authority to open an MVS console thatis named XXXXXXCN where XXXXXX isthe first six characters of theZCON_ADMIN_CONSOLE user ID.

v Authority to issue console STARTcommand.

v Authority to issue console STOPcommand.

v Ability to issue console command todisplay if job is active.

v Authority to issue console CANCELcommand.

v Starting the z/OS Connect EE instancestarted task.

v Stopping the z/OS Connect EE instancestarted task.

v Checking whether the z/OS Connect EEinstance is running.

ZCON_ADMIN_SECURITY v Permission to run the Rexx scripts fordynamic security and the commandsthat are issued by these Rexx scripts. Bydefault, the scripts immediately exit withreturn code zero and do not modify anysecurity profiles. This default behaviorallows for predefined security profiles tobe used. The scripts can be modified toissue commands to dynamically create,update, and delete the security profilesthat are needed for the provisionedinstance of z/OS Connect EE. For moreinformation, see “Modifying the z/OSConnect Enterprise Edition workflows tosupport dynamic security” on page 104.

v

v Dynamically creating and deleting a SAFcertificate and key ring

v Dynamically creating and deleting SAFsecurity profiles that are required by theprovisioned instance.



ZCON_ADMIN_SERVER v Authority to run zosconnect create tocreate z/OS Connect EE instances.

v Authority to issue standard UNIXSystems Services commands, forexample, chmod, mkdir, iconv, cp, chtag,mv, echo, rmdir, and pax.

v Authority for the started task to rununder this user ID.

v Permission to run the Rexx scripts fordynamic creation and deletion of a SAFkey ring. By default, the scriptsimmediately exit with return code zeroand do not modify any security profiles.This default behavior allows forpredefined security profiles to be used.The scripts can be modified to issuecommands to dynamically create,update, and delete the security profilesthat are needed for the provisionedinstance of z/OS Connect EE. For moreinformation, see “Modifying the z/OSConnect Enterprise Edition workflows tosupport dynamic security.”

v Creating the z/OS Connect EE instancefrom a script

v Copying server configuration files.

v Copying application configuration froman image into the zFS file system.

v Deleting the z/OS Connect EE instance'sdata directory during deprovision.

ZCON_ADMIN_TSO v Authority to copy a default procedurefrom the z/OS Connect EE installationdirectory on zFS.

v Authority to copy the configuredprocedure from zFS into the PROCLIBnamed by the ZCON_ZOS_PROCLIBvariable.

v Authority to delete the procedure fromthe PROCLIB named by theZCON_ZOS_PROCLIB variable.

v Configuring the procedure that is usedto start the z/OS Connect EE instanceand storing the configured procedureinto the PROCLIB.

v Deleting the procedure from thePROCLIB during deprovision.

ZCON_ADMIN_ZFS v ALTER (create/delete/read/write/update) ZCON_FILE_SYSTEM_HLQ.*

v Authority to run TSO MOUNTcommand.

v Authority to run /usr/sbin/unmountcommand.

v Authority to issue chown commands.

v Creating and mounting zFS data set.

v Unmounting and deleting zFS data set.

v Changing the ownership of the zFSdirectory to theZCON_ADMIN_SERVER user ID.

Modifying the z/OS Connect Enterprise Edition workflows to supportdynamic security

The z/OS Connect EE template provides workflows to provision and deprovisionan instance of z/OS Connect EE. Steps in the workflows run Rexx scripts, in whichsecurity profiles can be dynamically added, modified, and deleted. The Rexxscripts enable the provision and deprovision process to dynamically configure thesecurity profiles that are needed for that instance of z/OS Connect EE. Toconfigure security, the workflow steps that are always run as part of provision anddeprovision, but by default they do not make any dynamic security changes.


Before you begin

Four example Rexx scripts are provided with the workflows for provisioning anddeprovisioning instances of z/OS Connect EE. The scripts show example RACFcommands for configuring the necessary security profiles. They can be used as aguide for creating scripts for an alternative SAF provider.v defineSecurity.rexx contains example RACF definitions for dynamically

creating and configuring the profiles that are needed by a z/OS Connect EEserver.

v deleteSecurity.rexx contains example RACF definitions to delete the profilesthat are dynamically created in defineSecurity.rexx.

v defineKeyring.rexx contains example RACF definitions for dynamically creatinga key ring for SSL certificates that are needed by a z/OS Connect EE server.

v deleteKeyring.rexx contains example RACF definitions to delete the profilesthat are dynamically created in defineKeyring.rexx.

All four example Rexx scripts exit immediately without issuing any commands. Touse the scripts, you must move the exit statement to after the commands that youwant to issue.

Note:

Check the return code from each security command for an appropriate response indefineSecurity.rexx. If the Rexx script exits with a nonzero return code,provisioning of the z/OS Connect EE instance fails.

Edit deleteSecurity.rexx to undo any changes that are made indefineSecurity.rexx.

Edit deleteKeyring.rexx to undo any changes that are made indefineKeyring.rexx.

A failure in provisioning an instance of z/OS Connect EE might occur before,during or after any dynamic security configuration is made. AsdeleteSecurity.rexx and deleteKeyring.rexx are always called duringdeprovision, ensure they can complete successfully when they delete securityprofiles that do not exist (either because a failure occurred during provision beforea profile was created, or because the deprovision is being retried and a priorattempt already removed the security profiles).

Procedure1. Locate these Rexx extensions for dynamic security: zospt/workflows/

zosconnect/extensions/defineSecurity.rexx (Run during provision of aninstance of z/OS Connect EE), zospt/workflows/zosconnect/extensions/deleteSecurity.rexx (Run during deprovision of an instance of z/OS ConnectEE), zospt/workflows/zosconnect/extensions/defineKeyring.rexx (Run duringprovision of an instance of z/OS Connect EE), and zospt/workflows/zosconnect/extensions/deleteKeyring.rexx (Run during deprovision of aninstance of z/OS Connect EE).

2. Locate the line at the start of each Rexx script that issues exit 0. Make surethat any security calls are made before this command.

3. Use the sample Rexx scripts as a guide to customize the scripts for yourenvironment.


Configuration properties for z/OS Connect Enterprise Edition imagesYou can configure a number of properties to customize the way that instances ofz/OS Connect EE are provisioned through z/OS PT. Properties for a template arespecified in a zosconnect.properties ISO8859-1 file, ready to load into z/OSMF.

High-level qualifiers for your installation


ZCON_INSTALL_DIR The path to the z/OS Connect EE installation directory onzFS.

Template

User IDs for the configuration

For more information about the steps for which each user ID is used, see “Securityrequirements for provisioning instances of z/OS Connect EE with z/OSProvisioning Toolkit” on page 103.


ZCON_ADMIN_CONSOLE User ID that is used for CONSOLE API commands andneeds to have special OPERPARM configuration.

When the CONSOLE API is used, an MVS console is createdand used to submit console commands. The MVS consolename is the first six characters of theZCON_ADMIN_CONSOLE user ID followed by the letters'CN'. If multiple z/OSMF servers are installed on differentLPARs in a sysplex, the generated MVS console name (thefirst six characters of the DFH_ADMIN_CONSOLE user ID)must be unique on each LPAR.

For more information about authorizations andconfiguration of the z/OS console services, see z/OSconsole services.

Also ensure that message CWWKF0011I is not suppressedby using Message Processing Facility (MPF) as this messageis used to detect when z/OS Connect EE starts.

Template

ZCON_ADMIN_SECURITY User ID under which dynamic SAF security updates aremade during the provisioning process.

By default, no dynamic security updates are made, as the Rscripts that are run immediately exit with return code zero.This default behavior allows for predefined security profilesto be used. The Rexx scripts can be modified to issuecommands to dynamically create, update, and delete thesecurity profiles that are needed for the provisionedinstances of z/OS Connect EE. For more information, see“Modifying the z/OS Connect Enterprise Edition workflowsto support dynamic security” on page 104.

Template





ZCON_ADMIN_SERVER User ID under which the provisioned instance of z/OSConnect EE runs. This user ID owns the data directory onzFS of the instance of z/OS Connect EE.

z/OS Connect EE runs as a started task and its job namematches the instance name of the provisioned z/OS ConnectEE instance in z/OSMF. A SAF security profile must existthat ensures the started task runs under theZCON_ADMIN_SERVER user ID. This profile can either bepredefined, or it can be created dynamically as part of theprovisioning process. For more information, see “Modifyingthe z/OS Connect Enterprise Edition workflows to supportdynamic security” on page 104.

Template

ZCON_ADMIN_TSO User ID that can be used to create the step in the PROCLIBnamed by the ZCON_ZOS_PROCLIB variable for theinstance of z/OS Connect EE.

Template

ZCON_ADMIN_ZFS User ID that has z/FS authority to mount and unmountz/FS file systems that are used by the z/OS Connect EEinstance.

Template

ZCON_APPROVER_CONSOLE Approval user ID of the ZCON_ADMIN_CONSOLE user IDfor issuing MVS console commands.

Template

ZCON_APPROVER_SECURITY Approval user ID of the ZCON_ADMIN_SECURITY user IDfor making dynamic SAF security changes.

Template

ZCON_APPROVER_SERVER Approval user ID of the ZCON_ADMIN_SERVER user IDfor running the instance of z/OS Connect EE.

Template

ZCON_APPROVER_TSO Approval user ID of the ZCON_ADMIN_TSO user ID forcreating the procedure that is used to start the instance ofz/OS Connect EE.

Template

ZCON_APPROVER_ZFS Approval user ID of the ZCON_ADMIN_ZFS user ID forcreating and mounting directories in zFS.

Template

z/OS Connect EE instance configuration


ZCON_FILE_SYSTEM_HLQ Specifies the high-level qualifier for data sets that aredefined during the provisioning of the z/OS Connect EEinstance.

Template

z/OS configuration options


ZCON_ZOS_PROCLIB Names a PROCLIB data set into which the workflow cancreate a procedure for the z/OS Connect EE instance. Thez/OS Connect EE instance runs as a started task. If youspecify a PROCLIB that is a PDSE, it enables concurrentaddition of new procedures to the PROCLIB. If a PDS isused and multiple updates to the PROCLIB are attemptedconcurrently, z/OS abends them with a 213-30 abend code,to avoid data corruption.

Template



ZCON_ZOS_STCJOBS Names the data set into which the workflow can create thesource JCL that defines the job level characteristics of thestarted task for the provisioned instance of z/OS ConnectEE. Only used when ZCON_STC_JOB_CARD is alsospecified. If you specify a data set of type PDSE, it enablesconcurrent addition of new STCJOBS to the data set. If aPDS is used and multiple concurrent updates to the dataset are attempted, z/OS produces a 213-30 abend code, toavoid data corruption.

Template

ZCON_STC_JOB_CARD Specifies the job card to use for the started task of theprovisioned instance of z/OS Connect EE. When specified,ZCON_ZOS_STCJOBS must also be used to indicate thedata set prefix for STCJOBS.

Template

ZCON_ZOS_VSAM_VOLUME VOLUME value that is used in the creation of data sets, forexample, SYSDA. If the value is specified as SMS (StorageManagement Subsystem), the VOLUME parameter isomitted from the VSAM creation.

Template

zFS configuration options


ZCON_ZFS_DATACLASS Specifies a data class that is used to define a zFS data setfor the z/OS Connect EE instance. A data set is defined,formatted for zFS, and mounted into a directory createdwithin the ZCON_ZFS_MOUNTPOINT location.

DATACLASS (a list of data set allocation attributes andtheir values) defined on z/OS that is used to create thezFS data sets. For more information about setup details,see “Configuration prerequisites for using z/OSProvisioning Toolkit with z/OS Connect EnterpriseEdition” on page 99. For non-SMS-managed systems,either remove the ZCON_ZFS_DATACLASS property, ordo not give the property a value. Instead, you can specifya value for ZCON_ZOS_VSAM_VOLUME and this valueis used.

Template

ZCON_ZFS_MOUNTPOINT Specifies a zFS directory into which a data directory forthe provisioned instance of z/OS Connect EE can bedefined.

Template

JVM configuration options


JAVA_HOME Location of the Java installation Template

Security options


ZCON_SAF_AUTHENTICATION Specify whether you want to use SAF authentication. Ifyou specify FALSE, you must manually configure analternative authentication mechanism.

Permitted values are TRUE | FALSE..

Template



ZCON_TLS Permitted values are SAF | JKS | NO.

Specifying SAF means that an HTTPS port is needed forthe instance of z/OS Connect EE and that a SAF key ringis used for transport layer security. When SAF isspecified, the value of theZCON_SERVER_KEYRINGparameter determines whether a predefined key ring isused.

If ZCON_SERVER_KEYRING is specified, it is assumedto be the name of a predefined key ring.

If ZCON_SERVER_KEYRING is not specified, the keyring is created dynamically by running thedefineKeyring.rexx script that is found in theworkflows/extensions folder. To enable the key ring to becreated dynamically, you must modifydefineKeyring.rexx (the default is to exit immediatelywith return code zero and not to make any dynamicprofile updates). The corresponding deleteKeyring.rexxscript must also be modified for your environment.

Specifying JKS means that an HTTPS port is needed forthe instance of z/OS Connect EE and that a Java keystoreis used for transport layer security. The Java keystore isdynamically created by z/OS Connect EE during startup.

Specifying NO means that the instance of z/OS ConnectEE accepts requests over an unsecured HTTP port.

Template

ZCON_SERVER_KEYRING Names an existing SAF key ring to be used whenZCON_TLS=SAF.

Template

ZCON_ZFS_GROUP Specifies the name of a SAF group, which is grantedread, write and execute authority to the z/OS ConnectEE instances data directory. Users of the group are able toadd APIs and services into the file system of the z/OSConnect EE instance.

Template

Provisioning process customizations


ZCON_STOP_TIMEOUT The amount of time to wait for the z/OS Connect EEinstance to stop before a CANCEL command is issued. Thevalid range is 10 - 600 seconds. The default is 30 seconds.

Template

TEMP_DIR The name of a temporary directory into which theZCON_ADMIN_ZFS user ID can create, update, and deletefiles. The default is /tmp. When you are provisioning acrosssystems within a sysplex, this directory must be accessiblefrom the system that is running z/OSMF and the system onwhich the environment is being provisioned.

Template

VALIDATE_PARAMETERS During the provision of an instance of z/OS Connect EE, astep is run to validate some of the configured templatesproperties. When the template is correctly configured, youcan choose not to run this step, which shortens the time thatit takes to provision an instance of z/OS Connect EE.Permitted values are YES | NO. The default is YES.

Template


Chapter 23. Registering existing subsystems in z/OSMF

Use the provided registration workflows to register existing instances of CICS,DB2, and IBM MQ in the z/OSMF Web User Interface. Registered subsystems arethen available to be dynamically linked to during the provision of other containers.

z/OSMF maintains a catalog of provisioned and registered subsystems. You canprovision a container that automatically links to a registered subsystem by usingthe link option on the zospt run command. For more information about how touse the link option, see “Using the --link option” on page 46.

Registering subsystems allows systems that are being provisioned by z/OS PT toconnect to existing subsystems:v with minimal configuration.v without the need to install the correct resources in the registered subsystem.

How to register an existing subsystem

A z/OSMF administrator must give you domain administrator authority to enableyou to add templates into the domain. For more information, see Chapter 10,“Adding an IBM Cloud Provisioning and Management for z/OS template for usewith z/OS Provisioning Toolkit,” on page 39. Upload and publish the registrationworkflow by using the z/OSMF Web User Interface:1. Add the template to z/OSMF by going to Cloud Provisioning > Software

Services and selecting the Templates tab. Click Add Template and specify thefile to be loaded in the Template source file field (this file is the .mf file, foundin the ../zospt/workflows/registration/subsytem folder). Click Load. Thefields for Workflow file, Actions file, and Workflow variables input arepopulated automatically. Give your template a name, and click OK.

2. Associate the template with a tenant. When you do the association, you can setlimits for how many times the container can be provisioned and how manyeach user is allowed to provision. The association automatically creates aresource pool for the template and the network administrator is notified.

3. If you are ready, you can publish the template by selecting Software Servicesand selecting the Templates tab. Select the template that you want to publish,and select Actions > Publish. No approvals are needed to complete this step. Ifyou do not publish the template at this stage, the template remains in draftstate.

Running the template

You can run the template in either of the following ways:v Use z/OS PT to build the image (by using the zospt build command) then run

the image (by using the zospt run command). If the template is in draft state,use the --draft option on the zospt run command. Add the subsystemproperties to the zosptfile. For more information about building and runningimages, see Chapter 12, “Building an image with z/OS Provisioning Toolkit,” onpage 43 and Chapter 13, “Running a z/OS Provisioning Toolkit image,” on page45.

v Use the z/OSMF Web User Interface to run the template by selecting SoftwareServices and selecting the Templates tab. Select the template that you want to


run, and select Actions > Run > . If your template is in draft state, selectActions > Test Run. Select the Associated tenant, and enter the subsystemproperties. Properties that are marked with an asterisk are mandatory.

Supported z/OS PT commands on a registered subsystem

The following zospt commands are supported on registered subsystems:v The zospt run command.v The zospt rm -f(--force) command.v The zospt inspect command.v The zospt ps command.

Further informationv For specific registration information for CICS, see “CICS registration

information.”v For specific registration information for DB2, see “DB2 registration information”

on page 113.v For specific registration information for IBM MQ, see “IBM MQ registration

information” on page 113.

CICS registration informationUse the provided CICS registration workflows (found in ../zospt/workflows/registration/subsystem) to register existing CICS regions in z/OSMF.

Supplying CICS properties

When you register an existing CICS system in z/OSMF, you need to supply certaininformation about the CICS region, for example, its APPLID. If you run thetemplate directly from the z/OSMF Web UI, you are prompted to complete thenecessary fields. Alternatively, you can build a z/OS PT image with theinformation that is specified in the zosptfile. The built image can then be run.The following table shows the CICS properties that you need to add to register anexisting CICS region by using z/OS PT:

Table 6. CICS properties to supply to the z/OSMF template

Property Description Required?

DFH_REGION_APPLID Specify the APPLID of theCICS region that you want toregister.

Yes

DFH_REGION_HOSTNAME Specify the host name of theCICS region that you want toprovision.

Yes

DFH_REGION_IPIC Dynamically allocates anIPIC port during provision.For more information aboutthis property, see“Configuration properties forCICS images” on page 84.

Yes

The properties can be put in a zosptfile (see the following example), which isused to build an image:


FROM scratch

# Define the z/OSMF template to drive for provisioningENV ZOSMF_TEMPLATE=cics_registration_templateENV DFH_REGION_APPLID=<regionApplid>ENV DFH_REGION_HOSTNAME=<regionHostname>ENV DFH_REGION_IPIC=<portNumber>

DB2 registration informationUse the provided DB2 registration workflows (found in ../zospt/workflows/registration/subsystem) to register existing DB2 systems in z/OSMF.

Supplying DB2 properties

When you register an existing DB2 system in z/OSMF, you need to supply certaininformation, for example the DB2 subsystem ID. If you run the template directlyfrom the z/OSMF Web UI, you are prompted to complete the necessary fields.Alternatively, you can build a z/OS PT image with the information that isspecified in the zosptfile. The built image can then be run. The following tableshows the DB2 properties:

Table 7. DB2 properties to supply to the z/OSMF template


DSN_HLQ Location of the DB2 librariesin MVS.

Yes

DSN_SSID The DB2 subsystem ID. No

DSN_GROUPID The DB2 group ID. No

DSN_ZFS_HLQ Location of DB2 directoriesin UNIX System Services.

Yes

The properties can be put in a zosptfile (see the following example), which isused to build an image:FROM scratch

# Define the z/OSMF template to drive for provisioningENV ZOSMF_TEMPLATE=db2_registration_templateENV DSN_HLQ=<db2_hlq>ENV DSN_SSID=<db2_ssid>ENV DSN_ZFS_HLQ=<zfs_hlq>

IBM MQ registration informationUse the provided IBM MQ registration workflows (found in ../zospt/workflows/registration/subsystem) to register existing IBM MQ queue managers in z/OSMF.

Supplying IBM MQ properties

When you register an existing IBM MQ queue manager in z/OSMF, you need tosupply certain information about the IBM MQ queue manager, for example, itssubsystem ID. If you run the template directory from the z/OSMF Web UI, you areprompted to complete the necessary fields. Alternatively, you can build a z/OS PTimage with the information that is specified in the zosptfile. The built image canthen be run. The following table shows the IBM MQ properties that you need toadd to register an existing IBM MQ queue manager by using z/OS PT:

Chapter 23. Registering existing subsystems in z/OSMF 113

Table 8. IBM MQ properties to supply to the z/OSMF template


CSQ_SSID The IBM MQ subsystem ID.Can be set to the name of aqueue-sharing group or thename of a queue manager.

Yes

CSQ_TARG_LIB_HLQ Location of the IBM MQlibraries.

Yes

The properties can be put in a zosptfile (see the following example), which isused to build an image:FROM scratch

# Define the z/OSMF template to drive for provisioningENV ZOSMF_TEMPLATE=mq_registration_templateENV CSQ_SSID=<mq_ssid>ENV CSQ_TARG_LIB_HLQ=<mq_hlq>


Notices

This information was developed for products and services offered in the U.S.A.This material might be available from IBM in other languages. However, you maybe required to own a copy of the product or product version in that language inorder to access it.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property rights maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785United States of America

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESSFOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore this statement maynot apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of thosewebsites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785United States of America

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Programming License Agreement, or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to actual people or business enterprises is entirelycoincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. The sampleprograms are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Trademarks

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at Copyright andtrademark information at www.ibm.com/legal/copytrade.shtml.


http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the followingterms and conditions.

ApplicabilityThese terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal useYou may reproduce these publications for your personal, noncommercialuse provided that all proprietary notices are preserved. You may notdistribute, display or make derivative work of these publications, or anyportion thereof, without the express consent of IBM.

Commercial useYou may reproduce, distribute and display these publications solely withinyour enterprise provided that all proprietary notices are preserved. Youmay not make derivative works of these publications, or reproduce,distribute or display these publications or any portion thereof outside yourenterprise, without the express consent of IBM.

Rights Except as expressly granted in this permission, no other permissions,licenses or rights are granted, either express or implied, to the publicationsor any information, data, software or other intellectual property containedtherein.

IBM reserves the right to withdraw the permissions granted hereinwhenever, in its discretion, the use of the publications is detrimental to itsinterest or, as determined by IBM, the above instructions are not beingproperly followed.

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all UnitedStates export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" ANDWITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED ORIMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIESOF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR APARTICULAR PURPOSE.

Notices 117

IBM®

Printed in USA

u s in g i b m z/o s p r o vi s i o nin g t o o lki t€¦ · chapter 1. what is z/os provisioning...

Documents