Performing a Restore
UPSTREAM restores can be initiated from several locations in your enterprise, including:
- From the UPSTREAM Client, using the Client GUI panels.
- From any workstation/server with the Java-based Director interface.
- From your z/OS mainframe using the USTBATCH utility.
The first two options are described in the BMC FDR/UPSTREAM Client documentation. This topic describes the third option - initiation via your z/OS mainframe using the USTBATCH utility.
This section provides information about the following topics:
Building the USTBATCH Job
This section shows how to use the UPSTREAM TSO/ISPF dialogs to generate a USTBATCH batch job to restore a data set. The example restore is performed against the sample backup of TEST, which was created in Performing a Backup. USTBATCH JCL can also be constructed manually (although this is not recommended) as described in z/OS Initiation with USTBATCH.
Step #1 - Select USTBATCH - UPSTREAM z/OS Storage Server Initiated Services
Enter the UPSTREAM TSO/ISPF dialog via your installation defined method (see Make the UPSTREAM ISPF Dialogs Easily Available from the main menu, specify option number 1, “USTBATCH”, and press “ENTER”.
~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- UPSTREAM ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- COMMAND ===> (% class="Red" %)1(%%) V 03.09.04 \\ **1** **USTBATCH** **- Host Initiated Services ** **2** (% class="Red" %)STATUS(%%) - Current Status Information **3** (% class="Red" %)DEFINE(%%) - Define Control Files **4** (% class="Red" %)CONFIGURE(%%) - Main Options **5** (% class="Red" %)PROFILE(%%) - Client Profile Names **6** (% class="Red" %)OPER(%%) - Operator Commands **7** (% class="Red" %)REPORT(%%) - Report **8** (% class="Red" %)REGISTRY(%%) - Name Registry **10** (% class="Red" %)SCHEDULE(%%) - Command Scheduler **11** (% class="Red" %)MANAGEMENT(%%) - Backup Management **12** (% class="Red" style="font-weight: Bold;" %)USTCRYPT(%%) - USTCRYPT Options \\ 11 Active Jobs: \\Sel Jobname System #ACT TCP/IP Address PORT VTAM APL ~-~-- ~-~-~-~-~-~-~-~- ~-~-~-~-~-~-~-~- ~-~-~-~- ~-~-~-~-~-~-~-~-~-~-~-~-~-~-- ~-~-~-~- ~-~-~-~-~-~-~-~- S USTPRODA CPUA 1 192.168.0.1 2001 USTSAAPL USTPRODP CPUA VERSION < 03.09.04 UI CPUB 192.168.0.2 1972 NONE USTEURO CPUE INACTIVE\\ |
Step #2 - USTBATCH Specification#
The next menu to appear allows for the specification of the USTBATCH parameters required for the restore request. The parameters of most interest have a value specified and a description follows on the next page.
-------------------------- FDR/UPSTREAM - USTBATCH ------- * ------------------ COMMAND ===> 2 SCROLL ===> CSR Gen - Generate statements Read/Save/Delete parameter set 1 - Backup 6 - Restart Restore 2 - Restore & Inquiry 7 - Kill Restart Backup 3 - Run a PC Job 8 - Kill Restart Restore 4 - File Transfer 12 - Operator Commands 5 - Restart Backup 13 - Performance Tests Communication parameters between USTBATCH and the UPSTREAM Storage Server HOSTIP ===> HOSTPORT ===> 2003 HOSTDNS ===> YOUR.LPAR.DNS.NAME APPLPREF ===> QUEUE ===> MAXRETRY ===> USAPPL ===> CONV ===> TMAXRETRY ===> TPNAME ===> WTOCOMP ===> APPLRETRY ===> LOGMODE ===> RESTART ===> TASKLIM ===> Communication parameters between UPSTREAM Storage Server & Client Target System TARGNAME ===> SERVER_REG_NAME or DNSname ===> or TCP/IP addr ===> TCP/IP port ===> IPADAPTER addr ===> . ERRWTO . WTOR=> Remote Parameter File: WSPARM ===> USERID ===> | PASSWORD ===> MIXED ===> NO Login Parameters: Client Login Name ===> Client Password ===> |
Supply values to the fields you wish to change and then press the ENTER key to proceed to the next menu.
The parameters specified in the panel above are explained here. For a full description of all parameters, see z/OS Initiation with USTBATCH.
Beginning with UPSTREAM z/OS 3.9.1, the UPSTREAM started task and USTBATCH may now use TCP/IP to initiate requests. The SNA parameters described further below are no longer required but may still be used. They are required for users of UPSTREAM z/OS 3.9.0 and earlier and are listed here for their reference.
USTBATCH to Started Task TCP/IP Parameters (Preferred):
HOSTDNS
The DNS name of the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTIP parameter.
HOSTIP
The IP address of the TCP/IP stack on the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTDNS parameter.
HOSTPORT
The IP port number of the UPSTREAM started task. If omitted, the default is 1972. This parameter may be used with either the HOSTDNS or HOSTIP parameters.
USTBATCH to Started Task VTAM SNA Parameters (UPSTREAM version 3.9.0 and prior):
APPLPREF
The 5-character prefix of the VTAM APPLID to be used by USTBATCH for its communications with the UPSTREAM started task.
USAPPL
The VTAM APPLID of the UPSTREAM z/OS started task.
TPNAME
The Transaction Program Name to be used during LU 6.2 communications.
Additional Parameters. (These parameters are used with any version of UPSTREAM and may be used with either TCP/IP or SNA USTBATCH to Started Task communication.):
LOGMODE
The VTAM LOGMODE to be used for communicating with the UPSTREAM started task.
CONV
This controls whether or not the USTBATCH job should wait for the completion of the request submitted to the started task or end immediately after the request is accepted.
WTOCOMP
Allows a WTO completion message to be issued to the z/OS system operator when the request finishes.
Started Task to Client Target System Parameters:
TCP/IP ADDR
The IP address of the Client to which you wish to restore the file(s).
TCP/IP PORT
The TCP port number of the Client to which you wish to restore the file(s).
ACTION
Controls which UPSTREAM function is to be performed by this set of generated statements. In our preceding example, ACTION=2 specifies a restore request.
Step #3 - Obtaining a List of Backups
In this next menu we have selected the “Inquire backups” option. Press the ENTER key to send this inquiry to the UPSTREAM z/OS started task for a list of the backups that have been recorded for the TEST profile. These backups are displayed on the subsequent menu.
-------------------------- FDR/UPSTREAM - USTBATCH Restore -------------------- COMMAND ===> SCROLL ===> CSR Backup Profile.( TEST ) --Inquire and Restore Files From...----- |( X ) Only Version Specified | |( ) Spec. Version Back to Full | |( ) Spec. Version Back to Oldest | ( x ) Inquire Backups --------------------------------------- Profile Backup Date/Time Type Comp Stor Est. MB # Files Lcl ------------------------------------------------------------------------------ | Default to Latest Backup | | | | | | | | | ------------------------------------------------------------------------------- ( ) File Inquiry ( ) Details ( ) More... OK <enter> Prior panel <PF3> |
Step #4 - Obtaining a List of Backed Up Files within a Backup
In the menu below, which shows the backups previously taken under the TEST backup profile, we have highlighted several parameters:
- We have selected the merge full backup taken at 13:03:05 on 03/06/00.
- We have highlighted the “File Inquiry” parameter to request a list of files contained within that backup.
- We have specified the “Only version specified” option to limit the file search to just the indicated backup.
-------------------------- FDR/UPSTREAM - USTBATCH Restore -------------------- COMMAND ===> SCROLL ===> CSR Backup Profile.( TEST ) --Inquire and Restore Files From...----- |( X ) Only Version Specified | |( ) Spec. Version Back to Full | |( ) Spec. Version Back to Oldest | ( ) Inquire Backups --------------------------------------- Profile Backup Date/Time Type Comp Stor Est. MB # Files Lcl ----------------------------------------------------------------------- MORE - | ( _ ) TEST 09/15/17 22:58:21 MERGE FULL TAPE 181910. 776929 | | ( _ ) TEST 09/18/17 22:35:01 MERGE INCR. TAPE 2329.02 143 | | ( _ ) TEST 09/19/17 22:34:24 MERGE INCR. TAPE 2217.60 148 | | ( _ ) TEST 09/20/17 22:23:58 MERGE INCR. TAPE 2623.91 136 | | ( X ) TEST 09/21/17 22:20:26 MERGE INCR. DISK 2622.39 142 | ------------------------------------------------------------------------------- ( X ) File Inquiry ( ) Details ( ) More... OK <enter> Prior panel <PF3> |
In the Inquire Files section of the resultant display, shown below, we can see the files that were included in the backup. All these files were selected under the “/*” file specification, which we used in our sample backup in Performing a Backup.
-------------------------- UPSTREAM - USTBATCH Restore File Spec ------- COMMAND ===> SCROLL ===> CSR < > Exclusion < > Include Subdirs Destination...( ) Specification.(/* ) ( ) Long names ( _ ) Update Spec Inquire Files Files Selected for Restore ----------------Row 1 of 205---------- MORE + ----------Row 1 of 1------------- | ( _ ) 961230113831 27 ACROGRAF.INI | | | ( _ ) 981211114318 2522 ACROREAD.INI | | | ( _ ) 990423163407 37504 Active Setup Log.B| | | ( _ ) 000120114037 43748 Active Setup Log.t| | | ( _ ) 971114103527 15928 Active Setup.Log | | | ( _ ) 000120113100 34451 AdvpackExt.log | | | ( _ ) 970730145201 817K ArtGalry.cag | | | ( _ ) 960321205020 10656 BARCTL.DLL | | --------------------------------------------- -------------------------------- ( ) File Inquiry ( ) Add Spec ( ) Delete Spec OK <enter> ( ) More... Prior panel <PF3> |
Step #5 - Selecting Files to be Restored
The next step involves selecting the specific files that are to be restored. This is done by adding them to the selection list in the “Files Selected For Restore” box on the right-hand side of the display.
The “UP” and “DOWN” ISPF function keys, usually PFK7 and PFK8 respectively, can be used to scroll through the list of files on the selected backup.
To ADD a file to the restore selection list:
- Place any character in the underlined prefix area immediately to the left of the file.
- Place any character in the “Add Spec” selection field.
- Press the ENTER key.
- The file selected should now appear in the “Files Selected for Restore” box. Repeat this action once for each file you wish to add to the restore specification.
To DELETE an entry from the selection list:
- Place any character in the underlined prefix area immediately to the left of the file specification to be deleted from the “Files Selected for Restore” box.
- Place any character in the “Delete Spec” selection field.
- Press the ENTER key.
- The file specification selected should no longer appear in the “Files Selected for Restore” box. Repeat this action once for each file you wish to delete from the restore specification.
To UPDATE a previously existing line in the “Files Selected for Restore” box:
- Place any character in the underlined prefix area immediately to the left of the file to be selected in the “Inquire Files” box.
- Place any character in the underlined prefix area immediately to the left of the file specification to be updated in the “Files Selected for Restore” box.
- Place any character in the “Update Spec” selection field.
- Press the ENTER key.
- The updated file specification should now appear in the “Files Selected for Restore” box. Repeat this action once for each file specification you wish to update for the restore specification.
In the example screen below, we have used the ADD procedure described previously to select the ACROREAD.INI file and add it to the Files Selected for Restore section.
----------------------- UPSTREAM - USTBATCH Restore File Spec ---------- |
Once you have selected all the files that you wish to restore, press the ISPF EXIT key twice (generally PF3) to return to the original USTBATCH main menu, previously seen in Step #2 - USTBATCH Specification.
Step #7 - Generate the USTBATCH JCL
Having worked through the restore specification menus, we can now generate the z/OS JCL that will be used to invoke the USTBATCH utility program, which will submit your restore request to the UPSTREAM started task for processing. You do this by specifying “GEN” on the command line and pressing the ENTER key.
-------------------------- FDR/UPSTREAM - USTBATCH ------- * ------------------ COMMAND ===> 2 SCROLL ===> CSR Gen - Generate statements Read/Save/Delete parameter set 1 - Backup 6 - Restart Restore 2 - Restore & Inquiry 7 - Kill Restart Backup 3 - Run a PC Job 8 - Kill Restart Restore 4 - File Transfer 12 - Operator Commands 5 - Restart Backup 13 - Performance Tests Communication parameters between USTBATCH and the UPSTREAM Storage Server HOSTIP ===> HOSTPORT ===> 1972 HOSTDNS ===> YOUR.LPAR.DNS.NAME APPLPREF ===> QUEUE ===> MAXRETRY ===> USAPPL ===> CONV ===> TMAXRETRY ===> TPNAME ===> WTOCOMP ===> APPLRETRY ===> LOGMODE ===> RESTART ===> TASKLIM ===> Communication parameters between UPSTREAM Storage Server & Client Target System TARGNAME ===> SERVER_REG_NAME or DNSname ===> or TCP/IP addr ===> TCP/IP port ===> IPADAPTER addr ===> . ERRWTO . WTOR=> Remote Parameter File: WSPARM ===> USERID ===> | PASSWORD ===> MIXED ===> NO Login Parameters: Client Login Name ===> Client Password ===> |
Step #8 - Adding a JOBCARD and STEPLIB
The panel below then allows you to tailor the USTBATCH JCL to match your installation's requirements. As a minimum, you should alter the JCL to provide a valid mainframe JOBCARD. You will also need to include a STEPLIB to point to the UPSTREAM load library if it is not in the Linklist. If you use the DNSNAME option to address the Client, you may also need a SYSTCPD DD statement.
-------------------------- UPSTREAM - USTBATCH ------------------------- |
Step #9 - Editing the USTBATCH Job
Select option 2 (“Edit”) on the command line of the preceding menu (then press ENTER) to review and optionally edit the generated USTBATCH JCL and parameters via a standard ISPF Edit screen.
ISREDDE2 - CRL2.ISP08494.SPFTEMP1.CNTL---------------------------- Columns 00001 00080 Command ===> Scroll ===> CSR ****** ********************************* Top of Data ********************************** 000001 //jobname JOB (job acct data),'job id data',NOTIFY=userid 000002 //* 000003 //* 000004 //* 000005 //USTBATCH EXEC PGM=USTBATCH 000006 //STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib 000007 //SYSUDUMP DD SYSOUT=* 000008 //USTLOG DD SYSOUT=* 000009 //* 000010 //USTPARM DD * 000011 HOSTDNS=YOUR.LPAR.DNS.NAME 000012 HOSTPORT=1972 *DEFAULT 000013 * 000014 TARGNAME=SERVER_REG_NAME 000015 ACTION 0 * RESTORE 000016 BACKUPPROFILE TEST 000017 INQOPTIONS 2 000018 LATESTVERSION N * RESTORE SPECIFIED VERSIONDATE 000019 VERSIONDATE 170117030000 000020 LOGNONFATAL 2 000021 SENDHOSTDETAILS Y 000022 * 000023 SPEC /HOME/USER1/* 000024 DESTINATION /RESTORE/USER1/* 000025 ENDPARM * |
Step #10 - Submitting & Monitoring the USTBATCH Job
The USTBATCH job can then be submitted for batch processing, either immediately, or it can be saved to a member in a PDS for later submission (manually, or through a job scheduling system).
Once it has been initiated, the executing restore request can then be monitored via the UPSTREAM ISPF STATUS panel (Option #2), or via the UPSTREAM STATUS operator command (UPSTREAM Operation).
Restoring from Encrypted Copies of your backups
UPSTREAM Data Encryption describes UPSTREAM's data encryption feature, which allows you to create encrypted copies of some/all your backups when copying the original backup with USTVAULT.
During the USTVAULT copy process, data can be encrypted using a choice of several encryption algorithms, each with an increasing level of strength, but with a corresponding increase in CPU and elapsed time for the USTVAULT copy process.
All of the algorithms use an encryption key, which can either be supplied manually, or (as recommended by BMC) they can be automatically generated. In order to restore data from an encrypted copy of a backup, the encryption key that was used during the encryption process must be supplied.
Although the encryption keys can be manually recorded and then supplied (again manually) to the restore process, this would not be very efficient, especially if many backups are to be restored, as in a disaster recovery. The manual recording of encryption keys would also create a security exposure that would weaken the effect of the encryption.
For these reasons, UPSTREAM automatically stores the encryption keys used by USTVAULT in a special disk-based “key file”, which can be secured against unauthorized access via your z/OS security system (UPSTREAM Data Encryption).
During a restore of an encrypted backup, UPSTREAM then automatically reads the key file to obtain the required encryption key to be used for the decryption process. So, assuming the key file is available to the UPSTREAM restore process, no additional effort is required in order to restore from an encrypted copy of a backup.
However, for “off-site” restores (i.e. during a disaster recovery), the key file must first be restored at the DR site before the UPSTREAM restore process can begin. Disaster Recovery Considerations discusses the various ways that the key file can be securely transported to the DR site without introducing a security exposure.
Once the key file has been restored, the restore process can proceed as normal, again with no further need for manual intervention of supplying of encryption keys.
If, for any reason, the key file is not available for restore, or only a back-dated copy of the key file is available, the required encryption keys (if known) can be manually supplied to the restore process.
UPSTREAM's data encryption also provides an option for using a master key, which is used to create an encrypted copy of the actual key used to encrypt the data. This encrypted key is then saved on the backup data set. The master key can be used to decrypt any copy of a backup that has been encrypted by USTVAULT, in the event that the key file is either not available, or the actual keys cannot be provided manually. Master Keys describes master keys in more detail.
In summary:
- If you have used UPSTREAM's data encryption feature to create encrypted copies of your backups, and assuming that the key file is available during the restore process, no additional effort is required in order to restore from those encrypted backups.
- If the key file is not available, the required keys can be supplied manually, or (if used, the master key can be provided).