Using the GETSHOPZ utility

This section describes how to configure and use the GETSHOPZ utility.

Configuring your system to use GETSHOPZ

The GETSHOPZ utility does not require any special privileges or authorizations to run. However, it is recommended that GETSHOPZ be run while logged on to the MAINTvrm user ID, because the service you obtain will, in general, need to be installed using this user ID. Also, the MAINTvrm 500 disk should be large enough to contain the acquired SERVLINK files for use with the SERVICE command. Make sure you access the MAINTvrm 500 disk before running GETSHOPZ. Use GETSHOPZ's DISK option to specify the 500 disk access file mode.

TCPIP DATA

GETSHOPZ requires a TCPIP DATA file that points to a DNS server that can resolve the host name in the target URL. If you don't already have a properly-customized file on your TCP/IP system disks, consider placing such a file on the MAINT 193 minidisk, where the GETSHOPZ utility is installed.

Note: When using a proxy gateway for z/VM to download the service, the DNS server only needs to resolve the URL of the proxy; the proxy gateway itself will have access to an external DNS that can resolve the URL of the IBM download site.

z/VM TLS Support

The direct-to-host download requires that the root certificate authority (CA) for the IBM SW Order Download Server is installed in the z/VM TLS certificate database for your TCP/IP stack. This certificate is installed automatically into new certificate databases after the PTF for APAR PH56199 is applied to z/VM 7.3.

You can use the CMS Pipelines ftp stage to check for the certificate. For example:

pipe i:fanin|tcpclient deliverycb-bld.dhe.ibm.com 443 secure getsecinfo|take|cons|elastic|i: 
Host deliverycb-bld.dhe.ibm.com validated TLSv1.2 rsa-aes128-sha 128 
time 117.626 ms
Ready; T=0.01/0.02 02:23:30

This test also verifies that you have TLS support in CMS Pipelines and that your DNS lookup works properly.

If you need a secure connection between the browser and your z/VM system, a valid server certificate with associated root CA and intermediate CA must be installed in the z/VM TLS certificate database. Make sure you know the label assigned to the server certificate, if it isn't set as default. If needed, adjust the TLSLABEL setting that is associated with this connection.

Using GETSHOPZ

The GETSHOPZ utility is installed on the MAINT 193 minidisk. Link and access this minidisk, or use the VMLINK command to acquire it:

vmlink maint 193

To start the web interface, issue:

getshopz run

This allows you to navigate the application with a web browser. Additional options might be required, depending on your system configuration. The program displays the URL to point your browser to. For example:

GETSHOPZ v1.0

Web Interface:
 http://vm1.acme.com:37757/

To start a browser session, click on the URL on the 3270 display or copy the URL and paste it into your browser address bar. For IBM Personal Communications, see Settings > Hotspots....

Use F3 to stop the web interface.

Specifying GETSHOPZ options

You can use options to specify the output disk to store the service files, various items related to the network configuration, and settings that cover security and authentication aspects. You can specify options in any order. For example:

getshopz run ( disk t secure

The options specified with the RUN operand are added to the default options kept in GLOBALV. For a summary of the various options, use HELP GETSHOPZ or see GETSHOPZ EXEC.

Default GETSHOPZ options

You can use the DEFAULTS operand to store a set of options in GLOBALV for the subsequent use of GETSHOPZ. The DEFAULTS operand with no options displays the current defaults: For example:

getshopz defaults
Default options are: ""
Ready; T=0.01/0.01 18:27:35

Suppose you need to add extra options. You might issue:

getshopz defaults ( disk T token
Ready; T=0.01/0.01 18:27:41

Then, display the current defaults again:

getshopz defaults
Default options are: "DISK T TOKEN"
Ready; T=0.01/0.01 18:27:44

Workstation connection

Navigation in the GetShopz application is done through a web browser. By default, the GetShopz application uses a random port number for the web interface. The port number is kept in GLOBALV, so future invocations will try to use the same port number (in case you want to keep it in the browser bookmarks). The following options might be necessary, depending on your configuration.

When firewalls between the z/VM system and your workstation require a specific port to be enabled, use the PORT option to specify the port number. You should also reserve that port in the TCPIP configuration to make sure it is not used by other users.
When your configuration uses a different user ID for the z/VM TCP/IP virtual machine and you have not specified that in the TCPIP DATA file, use the TCPIP option to specify the user ID.
The HOSTNAME option identifies the URL the browser connects to the web interface on your z/VM system. By default, the host name is taken from TCPIP DATA or retrieved by reverse lookup in DNS. When using a secure connection, the host name should match the TLS/SSL server certificate.

Browser compatibility

The GetShopz application works with the following web browsers:

Macintosh
- Google Chrome
Red Hat Enterprise Linux Workstation
- Google Chrome - Version 120.0.6099.216
- Mozilla Firefox - 115.7.0esr
Windows 10, Windows 11
- Microsoft Edge - Version 121.0.2277.112 (64-bit)
- Mozilla Firefox - 122.0.1 (64-bit)
- Google Chrome - Version 121.0.6167.161 (64-bit)

User authentication

When the browser connects to the web interface on your z/VM system, the default is to verify that the IP address of the browser matches that of the TN3270 session where the user is logged on. When your security policy does not allow this, or when technical reasons prevent this type of authentication, specify the TOKEN option to get a URL with a token for authentication:

getshopz run ( token
GETSHOPZ v1.0 

Web Interface:
 http://vm1.acme.com:37757/?token=FGHSQt9QIxI_etxzRNKKQg

Use F3 to stop the web interface.

The token is different with each invocation of GETSHOPZ. This means it is not possible to keep the URL as a browser bookmark.

Security

To enable TLS/SSL for the connection between your browser and the web interface, use the SECURE option. This will display an https: URL for the browser to connect to.

getshopz ( secure

When the server certificate is not set as the default in the z/VM SSL certificate database, use the TLSLABEL option to specify the label of the server certificate.

getshopz ( tlslabel zvm2048

Note: The connection with the IBM download site always uses TLS/SSL, independent of the connection between the workstation and z/VM.

z/VM internet connectivity

The direct-to-host mode requires that your z/VM system can connect to the IBM download site. Your network policy might only allow that through a proxy gateway or a different TCP/IP stack.

Proxy gateway

If you need to use a proxy gateway for the z/VM connection to the IBM download site, use the PROXY option to specify the URL of an anonymous proxy gateway. For example:

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

Alternative TCP/IP stack

For installations that use different TCP/IP stacks for internal and external traffic, the TCPIPEXT option can be used to point to the TCP/IP stack that must be used to connect to the IBM download site.

Digital signature verification (DSV) of z/VM service packages

Before applying service to the z/VM system, you can use GETSHOPZ to verify the authenticity and integrity of service packages. The support for DSV of z/VM service packages relies on the following:

For each order, an additional GIMPAF cover letter is provided. This cover letter, which is unique for each order, contains the secure hash values to verify the integrity of all of the parts delivered for the order. The hash value of the cover letter can be verified with the hash stated in the order confirmation email from Shopz.
The GIMPAF2 cover letter contains the digital signature that is used to verify authenticity of the cover letter itself. The cover letter is produced by enhancements in GIMZIP, the utility used to package the parts for the service order. The cryptographic key and certificate to produce the digital signature are also provided.

With this support, GETSHOPZ verifies the integrity of signed service files using the GIMPAF and GIMPAF2 cover letters in flight, leaving a SERVLINK file on disk only when the service is safe to apply. When the required cover letters for the order are not available or not valid, the signed service files (file names and file types in lower case) are put in quarantine to prevent the service from being applied by accident at some later time. The small GIMPAF and GIMPAF2 cover letters are retained as documentation of the received service. It is not possible to verify the integrity of the SERVLINK files without the cover letters.