GETSHOPZ EXEC
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.
- PROXYMODE DIRECT
- specifies that the proxy server implements a Direct Proxy.
- PROXYMODE TUNNEL
- specifies that the proxy server implements an HTTP Tunnel Proxy.
- 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.acme.com:3128/
- To bypass host name validation, issue:
getshopz run ( proxy https://lnxrmh01.acme.com:3128/ unsafe
- To use an HTTP Tunnel Proxy server for direct-to-host transfer, issue:
getshopz run ( proxy http://lnxrmh01.acme.com:3128/ proxymode tunnel
- To extract files using a wildcard, issue:
getshopz extract S0586978 FILE* B
- To extract an order using a list file, issue:
where the list file (S80112219 FILES B) contains:getshopz extract S8011219 FILES B (list
The output will look something like this:S8011219 SHIPTFSS B S8011219 SHIPDOCS B GIMPAF2 XML B GIMPAF XSL B GIMPAF XML B
-------------------- 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:
The output will look something like this:getshopz extract S0562114 FILES B1 ( list disk z
-------------------- 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:
And the output looks something like this:getshopz extract S0562114 FILES-3 B1 ( list
To remove the quarantined files, issue:-------------------- 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;
The output will look something like this:getshopz extract S0562114 FILES-3 B1 ( list clean
-------------------- 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;