The zospt command syntax

The zospt commands that are used by the z/OS® Provisioning Toolkit, and the available command options, are listed.

Syntax

Usage: 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 image
    images      [-h (--help)]                                            List all images
    inspect     <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 images
    run         <imageName> [--draft]                                    Create and start a new container
                [--link <containerName> | <containerId>:<alias>]
                [--name <containerName>] [-h (--help)] [-q (--quiet)] 
    start       <containerName> | <containerId> ... [-h (--help)]        Start one or more containers
    stop        <containerName> | <containerId> ... [-h (--help)]        Stop one or more containers
    ps          [-a (--all)] [-f (--filter) <filter>] [-h (--help)]      List containers
    create      <imageName> [--draft]                                    Create a new container but do not start it 
                [--link <containerName> | <containerId>:<alias>]
                [--name <containerName>] [-h (--help)] [-q (--quiet)] 

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

Description

To show the syntax of the command, run zospt command --help. If a command fails, use the error messages in the console output and Troubleshooting z/OS Provisioning Toolkit to resolve any issues.

build

Build an image that is used by the zospt run or zospt create command to create and start, or create, containers. The build command has the following parameters:

PATH

The path to the directory that contains the zosptfile to use as input to this build. This parameter is mandatory.

-t (--tag) imageName

The name of the image that this command builds. You cannot start the name with a hyphen (-) character or use the following reserved characters:

: @ / \

This parameter is mandatory.

When you run the zospt build command, z/OS PT operates on local resources, and runs without connecting to z/OSMF.

create

Create a new standard (non-composite) container from an image that was built by using the zospt build command, but do not start the container.

Remember: To create and start a container or composite containers, use the zospt run command.

The create command has the following parameters:

imageName: The name of the image to create a container from. The image must be for a standard (non-composite) template. This parameter is mandatory.
--draft: Create the z/OSMF template in Draft approved state. This parameter is optional. If you omit this parameter, the z/OSMF template must be in Published state.
--link containerName:alias | containerId:alias: Create a container with a connection to one or more other containers. Specify the name or ID of the container to link to. Each container can have an optional alias, which can be used to identify the connection in the created container.
To link to more than one container, specify the --link parameter multiple times in the command.
--name containerName: The name of the container to create. This name must be unique. You can use this parameter to assign a meaningful name to a container, rather than having a container name that is assigned automatically. The maximum name length is 32 characters. The acceptable characters are A-Z a-z 0-9 _ -, but the name must not start with a hyphen (-) character. This parameter is optional.
-q (--quiet): Do not write information messages to the console while the container is created. The only output that is written to stdout is the name of the created container. If an error occurs, the error information is written to stderr.

When you run the zospt create command, you are prompted to enter your password on the console to authorize the connection to z/OSMF. After authorization, z/OS PT uses z/OSMF to create a container from the specified image. The command output returns the progress while it runs in z/OSMF. If the properties are all correct, the output from the zospt create command ends with a message that says the container is created, for example:

Created container CICS_CICPJ006 with id cf91dd2f-9848-4672-af91-5aea7f80a02e on system MV01.

You can then use the zospt commands for managing containers, such as start, stop, ps, inspect, and rm.

To create a CICS® MAS or WUI region, a suitable CMAS must be created and running, otherwise the command fails at the step to create the CICS system definition. See Overview of supported CICS types.

images

List the images that are available to run, with their name, size, and date of creation at the command prompt. This command has no additional parameters.

When you run the zospt images command, z/OS PT operates on local resources, and runs without connecting to z/OSMF.

inspect

Return details, in JSON format, about a specified image or container. The inspect command has the following parameters:

imageName: The name of the image to be inspected. When you run the zospt inspect imageName command, z/OS PT operates on local resources, and runs without connecting to z/OSMF.
containerName: The name of the container to be inspected. When you run the zospt inspect containerName command, z/OS PT operates on remote resources and connects to z/OSMF.
containerId: The ID of the container to be inspected. When you run the zospt inspect containerId command, z/OS PT operates on remote resources and connects to z/OSMF.

It is mandatory to specify one of these parameters.

The following example shows the details that are returned for an image:

{
   "name": "cics_55_liberty",
   "created": "Wed Dec 12 06:45:51 GMT 2018",
   "size": "10240B",
   "FROM": "cics_55",
   "ENV": {
      "ZOSMF_TEMPLATE": "cics_55",
      "DFH_REGION_JVMSERVER": "Liberty",
      "IMAGE_LIBERTY_DIR": "workdir/DFHWLP/wlp/usr/servers/defaultServer"
   }
}

ps

List the provisioned containers and containers for which provisioning failed. The ps command has the following parameters:

-a (--all)

Lists all the containers in any of the following states:

being deprovisioned
being provisioned
deprovisioned
deprovisioning failed
provisioned
provisioning failed

This parameter is optional.

A provisioned state includes containers that are not running, for example containers that are created but not started, or stopped but not deprovisioned. You can use the inspect command to obtain more details about the status of a container.

-f (--filter) filter

Lists the returned containers, filtered by the owner, the state of the container, the system on which the container is running, or a combination of filters. The format of filter is:

[OWNER|STATE|SYSTEM]=value: value is the parameter value that you want to filter by.

For multiple filters, specify -f before each filter, for example:

zospt ps -f owner=user02 -f state=provisioned

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

rm

Remove (or deprovision) one or more containers that were provisioned by using the zospt run or zospt create command. The rm command has the following parameters:

containerName|containerId: The name or ID of the container that was returned as a result of a zospt run or zospt create command. It is mandatory to specify one of these parameters. To remove more than one container, specify multiple container names or IDs, each separated by a space.
-f (--force): This parameter is relevant only to provisioning a CICS container. Shuts down the CICS region. This parameter is optional.

When you run the zospt rm command, you are prompted to enter your password on the console to authorize the connection to z/OSMF. After authorization, z/OS PT uses z/OSMF workflows to remove or deprovision the specified container or containers. The command output returns the progress of the workflows while it runs in z/OSMF. Multiple jobs run as part of each command, so they might take several minutes to complete.

If parallel provisioning is enabled in the workflow for CICS templates that use Cloud Provisioning to deprovision a CICS region, some steps run in parallel so that deprovisioning completes faster. Output includes the message This workflow contains parallel steps. See Enabling faster provisioning by using parallel processing.

If you are deprovisioning a MAS or WUI region that was provisioned into an existing CICSplex, see Deprovisioning guidelines for regions in a CICSplex.

rmi

Remove one or more images. The rmi command has the following parameter:

imageName: The name of the image to use as input. To remove more than one image, specify multiple image names, each separated by a space. This parameter is mandatory.

run

Run an image that was built by using the zospt build command to create and start a new container. The run command has the following parameters:

imageName: The name of the image to run. This parameter is mandatory.
--draft: Run the z/OSMF template in Draft approved state. This parameter is optional. If you omit this parameter, the z/OSMF template must be in Published state.
--link containerName:alias | containerId:alias: Provision a container with a connection to one or more other containers. Specify the name or ID of the container to link to. Each container can have an optional alias, which can be used to identify the connection in the provisioned container.
To link to more than one container, specify the --link parameter multiple times in the command.
--name containerName: The name of the container to run. This name must be unique. You can use this parameter to assign a meaningful name to a container, rather than having a container name that is assigned automatically. The maximum name length is 32 characters. The acceptable characters are A-Z a-z 0-9 _ -, but the name must not start with a hyphen (-) character. This parameter is optional.
-q (--quiet): Do not write information messages to the console while the container is created and started. The only output that is written to stdout is the name of the provisioned container. If an error occurs, the error information is written to stderr.

When you run the zospt run command, you are prompted to enter your password on the console to authorize the connection to z/OSMF. After authorization, z/OS PT uses z/OSMF workflows to run the specified image. The command output returns the progress of the workflows while it runs in z/OSMF. Multiple jobs run as part of each command, so they might take several minutes to complete.

If parallel provisioning is enabled in the workflow for CICS templates that use Cloud Provisioning to provision a CICS TS unmanaged region, some steps run in parallel so that provisioning completes faster. Output includes the message This workflow contains parallel steps. See Enabling faster provisioning by using parallel processing.

start

Start one or more containers that were created by the zospt run or zospt create command. The start command has the following parameters:

containerName|containerId: The name or ID of the container that was returned as a result of the zospt run or zospt create command. Only one of these parameters is needed. To start more than one container, specify multiple container names or IDs, each separated by a space.

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

To start a CICS MAS or WUI region, a suitable CMAS must be created and running. See Overview of supported CICS types.

stop

Stops one or more containers that were created by the zospt run or zospt create command. The stop command has the following parameters:

containerName|containerId: The name or ID of the container that was returned as a result of the zospt run or zospt create command. Only one of these parameters is needed. To stop more than one container, specify multiple container names or IDs, each separated by a space.

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