VM Education: How to Use GETSHOPZ

Ordering and Installing GetShopz

The GetShopz utility is available with z/VM 7.3.

z/VM 7.3 APAR VM66732 provides digital signature verification of IBM service orders and the new ISOLATED option for running GetShopz in an environment without internet connectivity.

The GetShopz utility is available as z/VM 7.2 APAR VM66540. After this APAR is installed, all future service can be uploaded directly to the z/VM host.

APAR VM66540 contains the following files:

FILE NAME (APAR VM66540)	DESCRIPTION

GetShopz EXEC	Main Program invoked by the user to run the Web interface
GSZUTILX MODULE	Filter package with utility stages used by main program
GETSHOPZ HELPCMS	Summary for HELP GETSHOPZ command

When the APAR is applied, the programs will be installed on the MAINT 193 tools disk. Note that two GSZ* TEXT files will be integrated in the CMS parts — these can be ignored. To run the program, access the 500 disk or a similar disk.

Configuration

The GetShopz program does not require any special privileges or authorizations to run, but it appears convenient to run the utility on MAINT720 since the data will be needed there later to install the service you transferred. The 500 disk on MAINT720 should be large enough to hold the SERVLINK files for the SERVICE command. Access the disk before running GetShopz and specify the file mode with the DISK option.

TCPIP Data

GETSHOPZ requires a TCPIP DATA file pointing to the DNS server that resolves the host name in the URL. If you don't already have a properly customized file on your system disks, you might want to put one on the disk where you installed the GetShopz utility. TCPIP DATA is normally on the TCPMAINT 198 disk. 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.

VM System SSL

The direct-to-host transfer requires that the Root CA for the IBM download server at https://deliverycb-bld.dhe.ibm.com is installed on the VM System SSL Certificate Database. A simple way to check this is with the CMS Pipelines ftp stage; a correct configuration shows something similar to the output below.

pipe ftp ftps://deliverycb-bld.dhe.ibm.com/;type=d | cons
 
FPLFTP1600E FTP error: 530-Login failed. Re-enter your user name and password
FPLMSG003I ... Issued from stage 1 of pipeline 1
FPLMSG001I ... Running "ftp ftps://deliverycb-bld.dhe.ibm.com/;type=d"
Ready(01600); T=0.01/0.01 17:41:45

This also verifies that you have SSL 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 Certificate Database. Make sure to know the label assigned to the server certificate, if it isn't set as the default.

For instructions to obtain and install needed root and intermediate CA certificates, click here

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 conveniently 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 may 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 will also want to reserve that port in the TCPIP configuration to ensure it is not used by other users.
When your configuration uses a different userid for the VM TCP/IP virtual machine, and you have not specified that in the TCPIP DATA file, use the TCPIP option to specify the userid.
The HOSTNAME option determines the URL the browser to connect to the Web interface on your z/VM system. By default, the hostname is taken from TCPIP DATA retrieved by reverse lookup in DNS. When using a secure connection, the hostname should match the TLS/SSL server certificate.

Security Options

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.

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

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

z/VM Internet Connectivity

The GetShopz utility requires that your z/VM system connects to the IBM download site. Your network policy may 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 anonyoumous proxy gateway. For example:

getshopz run ( proxy http://sample.company.com:3128/

Depending on your security policy, the connection between the z/VM system and the proxy can be secured with TLS/SSL. This is enabled with https:// specified for the proxy URL. When the Server Certificate of the proxy does not match the hostname in the URL, you may need to specify the UNSAFE option to bypass hostname validation. For example:

getshopz run ( proxy https://sample.company.com:3128/ unsafe

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.

Navigating the Web Interface

To understand how to use the GetShopz utility and navigate Shopz refer to the GetShopz sample screens.

This utility will automatically verify the origin of the received files using a digital SHA fingerprint. The result of this verification can be found under the 'Status' heading. If the Status shows the files were received from IBM you know the files are authentic. Refer to the GetShopz sample screens link above, to see the example of the output under the 'Status' heading.

The SHA fingerprint referred to as the hash value can also be verified manually using the hash value provided in the download email. The value from the download email can be manually compared to the value of the GIMPAF XML file shipped with the service order. Compare the email hash to the hash value at the bottom of the GIMPAF XML file under the "PKG HASH hash="

Problem Determination

It is possible you will receive errors on the host screen during transfers, these errors may be resolved. Please use the web browser status to verify if the transfer completed successfully. Refer to the 'Transfer' heading for a 'Completed' status. Sample successful download screen

While transfering files you may see CMS Pipeline messages and they can be ignored as long as the browswer shows the transfer completed successfully. Most errors will be displayed on the GetShopz browser page. Getting errors while using GetShopz? Please refer to the Problem Determination page for possible solutions.