GetShopz - Direct to Host Service Download

For z/VM service ordered through IBM Shopz, the GetShopz utility simplifies the download process. When your z/VM system can connect to the IBM download site directly, the direct-to-host mode of GetShopz speeds up the process by eliminating the upload from the workstation to z/VM.

The GetShopz utility runs a built-in Web interface during the data transfer; the user interacts with the application using a web browser. GetShopz reduces the steps required to acquire z/VM service while eliminating the need to store the service on the PC.

This page provides all the information to configure and use the new utility. To see a sample use, review the GetShopz sample screens presentation.

Note: GetShopz currently supports

  • z/VM product orders
  • z/VM PTF/APAR orders
  • z/VM RSU orders
  • z/VM ESO orders

After you have uploaded the service files to the z/VM Host system, you will need to continue with the service instructions provided with your order. The service envelops need to be installed on z/VM.

Ordering and Installing GetShopz

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.

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.

Browser compatibility

The application has been found to work as expected with the following web browsers.

  • Red Hat Linux Workstation
    • Google Chrome - Version 90.0.4430.93
    • Mozilla Firefox - 78.9.0esr
  • Windows 10
    • Microsoft Edge - Version 91.0.864.37
    • Mozilla Firefox - 83.0 (64-bit)
    • Google Chrome - Version 91.0.4472.77
  • MAC
    • Google Chrome

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 token for authentication. To do so, issue the command: 

getshopz run ( token
Output: 
GETSHOPZ v1.0
Web Interface:
http://sample.company.com:37757/?token=FGHSQt9QIxI_etxzRNKKQg
 
Use PF3 to stop the Web interface

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

Usage - Command Syntax

The GETSHOPZ utility is invoked with the GETSHOPZ command. 

              .--RUN----------------------------------------.
>>-GETSHOPZ-------------------------------------------------+--->
              +--HELP-------+-------------------------+-----'
              +--RUN--------+--(--| Options | --+---+-'
              '--DEFAULTs---+                   '-)-'
The RUN sub-command is used to start the Web interface and display the URL to be pasted into a supported Web browser. Additional options may be required, depending on the user system configuration. The program then shows the URL to direct the browser. Some workstation TN3270 applications allow you to click on a URL on the 3270 display to start a browser session (for IBM Personal Communications, see Settings -> Hotspots). 
getshopz run (

Output: 

GETSHOPZ v1.0
Web Interface:
 http://sample.company.com:37757/
 
Use PF3 to stop the Web interface
Paste the provided web interface into a supported web browser. For the list of supported browers, consult the Browser Compatibility section.

Options: 

     +------------------------------+
     v                              |
|------+-------------------------+--+-----------------------+---|
       +-- DEBUG string ---------+
       +-- DISK filemode --------+
       +-- HOSTNAME string-------+
       +-- PORT number ----------+
       +-- PROXY url ------------+
       +-- SAFE -----------------+
       +-- SECURE ---------------+
       +-- TCPIP userid ---------+
       +-- TCPIPEXT userid ------+
       +-- TLSLABEL string ------+
       +-- TOKEN ----------------+
       +-- UNSAFE ---------------+
Options are used 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. Options may be specified in any order.

For Example: 

getshopz run ( disk t secure
The options specified with the RUN sub-command are added to the default kept in GLOBALV.

Use HELP GETSHOPZ for a summary of the various program options.

Default Options

The DEFAULTS sub-command can be used to store a set of options in GLOBALV to use as options on future use of the utility. The DEFAULTS sub-command without any options shows the current defaults.

  • Example to display current defaults, issue: 
    getshopz defaults
    Output: 
    Default options are: ""
Ready; T=0.01/0.01 18:27:35
  • Example to set defaults for DISK to T with the Token option issue: 
    Getshopz defaults ( disk t token
    Output: 
    Default options are: "DISK T TOKEN"
Ready; T=0.01/0.01 18:27:41
  • Example to display current defaults stored in GLOBALV, issue: 
    getshopz defaults
    Output: 
    Default options are: "DISK T TOKEN"
Ready; T=0.01/0.01 18:27:44

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.