GETSHOPZ EXEC

RUN/DEFAULTS Options

EXTRACT Options

Notes:

¹ You can specify options in any order.

Purpose

Use the GETSHOPZ utility to start the web interface for downloading of z/VM service packages.

Operands

RUN: starts the web interface and displays the URL that you will click on or paste into the address bar of a supported web browser.
HELP: displays help information for the GETSHOPZ utility.
DEFAULTS: specifies the default options for subsequent use of the GETSHOPZ utility.
EXTRact fileid: Extracts the contents of service files that were transferred to CMS using a method other than GETSHOPZ. The input file (fileid) can optionally be specified with a wildcard to select a set of files to use (S0586978 FILE* A, for example).

Options

DISK filemode: specifies the file mode of the disk on which to store the downloaded service files. The default is to use the R/W file mode with the most available space.
HOSTNAME string: specifies the host name and domain origin when not using TCPIP DATA or reverse lookup.
ISOLATEd: starts a simplified web application that does not require the resources that would otherwise be obtained from external internet sites.
PORT number: specifies the number of the reserved port to use for the web interface when using a reserved port.
PROXY url: specifies the URL of an anonymous proxy server to download the service packages.
SAFE: enables host name validation for service package download.
UNSAFE: disables host name validation for service package download.
SECURE: specifies that the web interface uses a secure TLS/SSL connection with the default server certificate.
TLSLABEL string: specifies that the web interface uses a secure TLS/SSL connection with the named server certificate.
TCPIP userid: specifies the user ID of the TCP/IP server to use for the web interface. When this option is not specified, the user ID is taken from the TCPIP DATA file when available, or TCPIP as the default.
TCPIPEXT userid: specifies the user ID of the TCP/IP server used to download service packages. When the option is not specified, the user ID from the TCPIP option is used.
TOKEN: enables token-based authentication instead of checking the workstation IP address for authentication of the browser.
CLEAN: removes quarantined files when no valid cover letter in the set warrants integrity and authenticity of the files.
LIST: indicates that the input file (S0562114 FILES A, for example) contains the list of files to be processed. The list of files should be in the format filename filetype filemode and should be complete, without the use of wildcards. If the line begins with an asterisk (*), it is treated as a comment line and is not processed as a file.
REPLACE: replaces the existing files with the same file name and file type.

Responses

When a service order is transferred to the z/VM system, the order shows that it is signed, and includes the hash value that can be compared to the hash value in the order email. Each file is listed, with the z/VM file name and the original file name. For example:

Order S7998815 Signed by IBM Corporation, IBM Code Signing                 
Order S7998815 Hash Value: 94847FEB6CC85E4BCC1698536D09081B7A62B882        
S7998815 GIMPAF   B  S7998815 Signed   GIMPAF.XML                          
8815DOCS SERVLINK B  S7998815 Signed   S0001.SHOPZ.S7998815.SHIPDOCS.pax.Z 
S7998815 GIMPAF2  B  S7998815 Signed   GIMPAF2.XML                         
S7998815 GIMPAF2  B  S7998815 Signed   GIMPAF2.XML                         
8815PTFS SERVLINK B  S7998815 Signed   S0002.SHOPZ.S7998815.SHIPTFSS.pax.Z

Usage Notes

The GETSHOPZ utility is run from the default MAINTvrm user ID or equivalent.
The default TCP/IP server user ID is taken from TCPIP DATA when available.
Several options apply only to direct-to-host download and are ignored when using the workstation upload mode in the web interface.
Use the DEFAULTS operand to specify the default options for the RUN command. The set of options specified replaces previously-set options. The DEFAULTS operand without any options is used to display the current set of options.
For token-based authentication, a fresh token is generated each time the web interface is started. The displayed URL with the token must be copied and pasted into the browser address field.
For GETSHOPZ EXTRACT to verify the contents of the package, all files for the order must be processed in a single invocation of GETSHOPZ. The input files are identified by a wildcard file specification, or with the LIST option. The input files are not removed by GETSHOPZ, so additional disk space is required to also hold the extracted (larger) SERVLINK files. Use the DISK option to store the SERVLINK files on another file mode. The SERVLINK files are produced only when the GIMPAF2 file was included and the signature has been verified.
There is no need to retain the set of input files after the SERVLINK files have been created. If you do retain the input files and the SERVLINK files and use the EXTRACT function again, GETSHOPZ will verify the contents of the package and compare them with the SERVLINK file on disk. This could be used as evidence that the SERVLINK file used to apply service was verified.

Examples

To start the web interface, issue:
```
getshopz run
```
To store the downloaded service files on disk T and to specify that the web interface will use a secure TLS/SSL connection with the default server certificate, issue:
```
getshopz run ( disk t secure
```
To display the current defaults, issue:
```
getshopz defaults
```
To add options that store the downloaded service files on disk T and enable token-based authentication, issue:
```
getshopz defaults ( disk T token
```
To get a URL with a token for authentication, issue:
```
getshopz run ( token
```

To specify the URL of an anonymous proxy gateway, issue:

getshopz run ( proxy http://lnxrmh01.vm1.acme.com:3128/

To bypass host name validation, issue:

getshopz run ( proxy https://lnxrmh01.vm1.acme.com:3128/ unsafe

To extract files using a wildcard, issue:
```
getshopz extract S0586978 FILE* B 
```

To extract an order using a list file, issue:

getshopz extract S8011219 FILES B (list

where the list file (S80112219 FILES B) contains:

S8011219 SHIPTFSS B  
S8011219 SHIPDOCS B  
GIMPAF2  XML      B  
GIMPAF   XSL      B  
GIMPAF   XML      B

The output will look something like this:

--------------------  13 Feb 2024 10:12:14  ------------------
Order S8011219 Signed by IBM Corporation, IBM Code Signing
Order S8011219 Hash Value: 289E19DCBB9A6CD55AC192A877ED7BE10E5CFC52
Filename Filetype Fm Order    Security Original filename
1219PTFS SERVLINK B  S8011219 Signed   S8011219 SHIPTFSS B
1219DOCS SERVLINK B  S8011219 Signed   S8011219 SHIPDOCS B
S8011219 GIMPAF2  B  S8011219 Signed   GIMPAF2  XML      B
S8011219 XSL      B  S8011219 Signed   GIMPAF   XSL      B
S8011219 GIMPAF   B  S8011219 Signed   GIMPAF   XML      B
Ready;

To extract an order using a list file to file mode Z, issue:

getshopz extract S0562114 FILES B1 ( list disk z

The output will look something like this:

--------------------  14 Feb 2024 11:24:28  ------------------
Order S0562114 Signed by IBM Corporation, IBM Code Signing 
Order S0562114 Hash Value: 717B4658E7CD8D9507EEEC347E693FCF68C69FD9
Filename Filetype Fm Order    Security Original filename
S0562114 XSL      Z  S0562114 Signed   S0562114 FILE5    B1
S0562114 GIMPAF   Z  S0562114 Signed   S0562114 FILE4    B1
S0562114 GIMPAF2  Z  S0562114 Signed   S0562114 FILE3    B1
2114PTFS SERVLINK Z  S0562114 Signed   S0562114 FILE2    B1
2114DOCS SERVLINK Z  S0562114 Signed   S0562114 FILE1    B1
Ready;

To remove quarantined files, use the CLEAN option. For example, suppose you issue:

getshopz extract S0562114 FILES-3  B1 ( list

And the output looks something like this:

-------------------- 15 Feb 2024 12:36:07 ------------------
Order S0562114 Hash Value: 717B4658E7CD8D9507EEEC347E693FCF68C69FD9
S0562114 XSL      Z  S0562114 Hash     S0562114 FILE5    B1
S0562114 GIMPAF   Z  S0562114 Hash     S0562114 FILE4    B1
ehr3n0eo getshopz Z  S0562114 Hash     S0562114 FILE2    B1
1kmoss4s getshopz Z  S0562114 Hash     S0562114 FILE1    B1
Unable to verify authenticity of 2 files; left in quarantine
Ready;

To remove the quarantined files, issue:

getshopz extract S0562114 FILES-3  B1 ( list clean

The output will look something like this:

-------------------- 15 Feb 2024 12:40:17 ------------------
Order S0562114 Hash Value: 717B4658E7CD8D9507EEEC347E693FCF68C69FD9
S0562114 XSL     Z   S0562114 Hash     S0562114 FILE5    B1
S0562114 GIMPAF  Z   S0562114 Hash     S0562114 FILE4    B1
-- file removed --   S0562114 Hash     S0562114 FILE2    B1
-- file removed --   S0562114 Hash     S0562114 FILE1    B1
Ready;