BackBox® H4.00 VTC Scripting Option HP Part Number: 748418-002 Published: March 2014 Edition: G06.24, H06.06 or J06.
Legal Notice © Copyright 2013 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. The information contained herein is subject to change without notice.
Table of Contents Table of Contents ...................................................................... i Introduction ............................................................................. 1 SCRIPTS IN VTCS ............................................................................................. 2 SCRIPT EXECUTION CASES .................................................................................... 4 ENABLING OR NOT THE SCRIPT CONTROLLER...................................................
Detailed description ................................................................. 1 Backup script .............................................................................................. 1 Restore script ............................................................................................. 2 Post-Restore script ...................................................................................... 3 Delete script ..............................................................................
Introduction Introduction This “Scripts in VTC Option” manual documents how to set up and operate Windows scripts to save and restore the disk files containing images of virtual tape volumes. Scripting functionality is installed by the standard BackPak packages, but must be enabled by an option in the BackPak license key before being configured.
Introduction Scripts in VTCs Scripts are available for the Data Store type “WINDISK” for which the VTC Tape Emulator stores two MS-Windows disk files per virtual volume: - A small index file containing metadata (file name *.IND). - A variable length data file, whose size is based on the current content of the volume (file name *.DAT). Scripts send virtual volumes to a back-end Enterprise backup infrastructure in order to: - Have additional copies of virtual volumes for safety.
Introduction Scripts are configured in the BackPak GUI at the Data store level. One to four scripts can be specified, with optional user parameters that are entered through the GUI globally in the Data store. Note: o Backup script: executed to copy the two disk files of a virtual volume to a back-end Backup infrastructure o Restore script: executed to restore the disk files of a virtual volume.
Introduction Script execution cases Event Needed action Executed VTC Script The volume in two Windows disk files must be backed-up Backup script In the BackPak GUI: - Storage Admin page, (“backup all non-backedup files”), - or Volume page for a single volume (“Run script”) The volume in two Windows disk files must be backed-up Backup script The daily batch OBB017 executes the macro BB023_DEL_BACKEDUP Delete backed-up disk files after the time configured in the Volume group The volume mount is req
Introduction Enabling or not the Script controller There are two processing modes for the scripts. 1. The first mode corresponds to a simpler setup, where there is one execution of the script for each virtual volume. 2. The second set is used when scripts are managed by the Script controller. In this case, the first level of scripts just forward backup or restore requests to the VTC Script Controller. These requests are then queued and managed by the Script Controller.
Introduction Overview of script implementation Scripts are implemented by these activities presented in this section.
Introduction - Full control of the Enterprise Backup resources, such as physical tape drives, by the team managing the Enterprise Backup - Note that part of the operational management of the Enterprise Backup can also be reached through scripts, by enabling the optional BackPak Script controller that batches and serializes the execution of scripts.
Introduction Deletion of back-end archives, reuse of physical media Ideally the Enterprise Backup is configured for infinite retention of the archives – or backups, and a BackBox delete script is used to delete the expired stored virtual volume saved in the Enterprise Backup. This way the expiration of a NonStop tape volume in DSM/TC or TMF or QTOS is automatically propagated not only to the online storage in the data Store, but also to the archives in the Enterprise Backup.
Introduction Installing the Enterprise Backup client There is normally a backup software client to install, in all VTCs that are route to the Data Store to configure with scripts. The software must: - be able to save and restore files named by UNC (\\svr\share\dir...\file.
Introduction The VERITAS server name is specified by a user configuration NETB_SERVER set in the VT Controller domain configuration. parameter The policy name is build with the Volume Group name of the volume being processed (BBOX_VOLGROUP). The two file names to backup are specified by %1 and %2.
Introduction Distributed utilities BBOXLOG, BB_ArchiveBit and WAITFILE are distributed Windows programs that can be used in user–writen BackBox scripts. When a script is started, the MS-Windows PATH variable is augmented with the VTC program directory to make these utilities available. BBOXLOG – Logs a message in NonStop EMS BBOXLOG sends a message to the EMS subsystem of a NonStop node. BBOXLOG can be run in scripts triggered by the BackBox software used in a standalone Windows script.
Introduction BB_ArchiveBit – Reset the Windows file Archive bit This program is used at the end of backup scripts archiving Windows files to a Tivoli Storage Manager (TSM). It queries the TSM server to verify the files that have been archived by a previous “dsmc archive” command are actually known by the TSM server. If the archives are known by the TSM server, the Archive bit is reset in the Windows file system, allowing later “Delete Backed-up files” functionality enabled in the Volume groups.
Introduction Errorlevel 40: timeout, the file does not exist or is not available in the allocated time Other values may be set by Windows command line interpreter for severe errors. Syntax: WAITFILE file-name [maximum-number-of-seconds] File-name is the name of the Windows file to wait for. maximum-number-of-seconds is the maximum number of seconds WAITFILE will wait. Default value is 0 seconds, preventing WAITFILE from waiting if the file does not exist or is not available.
Guidelines Guidelines Cross system restores The restore script, as well as the other scripts, must be implemented in a way that any VTC configured as route to the Data Store can execute it, whatever the VTC that originally wrote the disk files storing a virtual volume, including VTC servers that Massive jobs through concurrent NonStop drives If there is a possibility of massive job, running several concurrent NonStop backups or restores accessing sequential media in the Enterprise Backup, the process must
Guidelines Archive bit The Windows file system maintains an Archive bit among other disk file properties. BackBox expects this Archive bit is reset by the backup script or by the Enterprise backup software. When the Archive bit is not reset: - In the BackBox GUI, the Storage Admin page cannot display the number of files that are not backed up yet, and the “Backup all non-backed up files” will backup all Windows files. - The “Delete backed-up files” (disk staging) cannot be used efficiently.
Guidelines %BBOX_VOLGROUP% This contains the Volume Group ID, than can never be modified. %BBOX_VOLUME_CLASS% This contains the Volume Class parameter configured in the Volume Groups. Several Volume groups can specify the same Volume Class. The Volume Class can be updated any time – with the only consequence to provide a different value for the next executions of scripts.
Guidelines For Tivoli Storage Manager (TSM), be sure to install the TSM Backup command line client “dsmc” that will be fetched by the scripts.
Guidelines For non cataloged volumes or unsupported tape catalogs, the infinite retention will not keep more than the last version of each virtual volume. Not using an infinite retention in TSM exposes to mismatched retentions between TSM and NonStop. For example, a NonStop operator might be not aware of a maximum retention in TSM, and expect the retention specified in a backup OBEY file will be considered in TSM.
Guidelines Resetarchiveattribute yes Errorlogretention 90 TXNBYTELIMIT 2097152 TCPBUFFSIZE 32 TCPWINDOWSIZE 63 In this DSM.OPT, three options must be updated or added: - ASNODENAME is the common client name owning the backups in TSM. This is a “proxy node” (also named “target node”). There must be an unique value for all VTCs routes to the Data Store. - NODENAME is the “login node” that must be distinct for each VTC server, but allowed to access the data of the proxy node.
Guidelines 3. Add this BBOX_TSM_MC in the Script Parameters of the Data Store configuration, Advanced properties page *** Customize and run the distributed setup_for_test.cmd to test and finalize the TSM client installation: 1. Enter in “setup_for_test.cmd” the values for three TSM Windows environment variables (DSM_CONFIG. DSM_DIR and DSM_LOG. ) that you added as “Script Parameters” in the BackBox Data Store Advanced configuration. “setup_for_test.
Guidelines Archive processing of '\\nsk_backbox\c$\BPAK\script\delete.cmd' finished without failure. Total number of objects inspected: 3 Total number of objects archived: 3 Total number of objects updated: 0 Total number of objects rebound: 0 Total number of objects deleted: 0 Total number of objects expired: 0 Total number of objects failed: 0 Total number of bytes transferred: 1.75 KB Data transfer time: 0.00 sec Network data transfer rate: 0.00 KB/sec Aggregate data transfer rate: 1.
Guidelines • And the account configured to access the remote file server lacks the right: "Manage auditing and security log". The account running TSM client must have the rights below. For exact reference, refer to the IBM Tivoli Storage Manager documentation.
Script settings in the BackPak UI Script settings in the BackPak UI License option verification In the Configuration, Domain page, License Options link, the scripting for some backend Enterprise Backup must be enabled. 1 BackBox H4.
Script settings in the BackPak UI Data Store configuration in the domain The initial Advanced page of the Data Store configuration is as below Scripting section Specify a Windows command files to be executed following specific tape events, each script is optional. Refer to Script execution cases and Detailed description. The file name must be fully qualified. The script files must be copied in each VTC at the same location. Script type: Select the licensed Enterprise Backup for documentation.
Script settings in the BackPak UI Up to ten parameters can be entered in the domain configuration. These parameters will be passed as Windows environment variables to the shell executing the script, in addition to the parameters generated by the VTC to identify the files to process in the script. Name: Name of the parameter. Do not specify the % sign around the name. Value: Value of the parameter. 3 BackBox H4.
Script settings in the BackPak UI Script submission through the UI Scripts are triggered automatically by the VTC Emulator. But after some error conditions, it might be required to re-submit manually the backup script. This can be done : - for a whole Data Store in the Storage Admin page - for a single virtual tape volume in the Volume Detail page Storage Admin Note about StoreOnce NAS: This functionality is available only for file systems that support the file attribute “Archive Bit”.
Script settings in the BackPak UI Link Back up all non backed-up files The backup script is normally automated and if enabled, the script controller will automatically retry failed backups. Files marked as not backed up are usually either still being backed up or in the script controller input queue. This button is for re-submitting manually the backup scripts that have failed for reason unrelated to the software like communication or power failures.
Script settings in the BackPak UI Volume Detail The script will be executed in the VTC who as written the virtual volume, i.e. “VTC Host Name”, until this VTC is not reachable by IP – then the 1st available VTC will execute the script. Name of the original backed-up files When a restore command is sent to the Enterprise Backup software, two files locations are specified: - The original fully qualified file name that was backed-up. This name is recorded in the BackPak VOLUME file on the NonStop.
Script settings in the BackPak UI 7 BackBox H4.
Detailed description Detailed description Backup script After a virtual volume mounted for output is unloaded, the backup script is executed. This script typically archives the two disk files representing a virtual volume. Preliminary cleanup Before archiving a new virtual volume, the script must first delete previous archive of the same volume – if the enterprise backup software allows the deletion of archives at the file level.
Detailed description Restore script When a virtual volume is loaded and either one or both the disk files representing the volume are missing, the restore script is executed. When the two files are missing, a single script execution can restore both files. The emulator waits for the script completion to complete the volume load.
Detailed description Post-Restore script The main purpose of this script, deleting backed-up files, is obsolete. This functionality is better handled by the macro BB023_DEL_BACKEDUP (see OBB017 obey file), controlled by the ‘Delete backed-up files’ parameters in the Volume groups. This script is still kept for compatibility purpose. This script is called at unload time, only when the Restore script has been executed to satisfy the load request for a NonStop application requesting a tape volume for input.
Detailed description For this purpose, the name of all paths configured in the Data Store is passed in two Windows variables %BBOX_CONF_PATH_NUMBER% and %BBOX_CONF_PATH%. See the table of named variables. This maximum cleanup might consume several minutes depending on the startup time of the backup software and the number of paths to clean.
Detailed description Pre-defined named parameters In addition to the positional parameters, the following variables are passed to the executing scripts: Script named parameters Parameter name %BBOX_BACKUP_HOST% Content Host name of the VTC that executed the last volume write, or the last backup script. Correct value if the volume was written by BackBox V3.10. For volumes written or backed up previously, a default value is extracted from %BBOX_FILE_IND% All scripts.
Detailed description %BBOX_DATA_SIZE% Number of bytes received from the NSK (uncompressed) Currently displayed in the Web UI as ‘Size’, ‘Write byte count’ or User Data Size’ The size includes the tape headers and trailers (less than 1 K) Variable is always set with none zero value. When the original value is not available (ex: in a restore from a RESTRICTED Data Store), the value passed is the maximum volume size configured in the Volume Group converted to bytes.
Detailed description %BBOX_NEW_DIR% Contains the fully qualified directory name of the file to restore. Same value as in the beginning of %2 parameter of the restore script. Restore script. %BBOX_NSK_NODE% Contains the name of the NonStop node where the current tape device is attached Backup, Restore and Post-restore scripts only. %BBOX_ORIG_FILE_DAT% Contains the fully qualified data file name to restore as when it was backed up. Same value as the %2 parameter of the restore script. Restore script.
Detailed description %BBOX_PREV_UNLOAD% Unload time of last time the volume was written; format: yyy-mm-ddThh:mn:ss.0000000Shh:mn GMT time up to S position T is always the letter ‘T’ sub-second value is always ‘0000000’ ‘S:hh:mn’ gives the signed difference with GMT, ex: US Eastern time will have ‘-05:00’ Example: 2009-11-12T14:31:35.0000000-05:00 Available if the volume was written by BackBox V2.
Detailed description %BBOX_VOLGROUP% Name of the current VT Controller Volume Group. All scripts. In addition, the Data Store configuration allows the specification of up to 10 userdefined parameters. Name and value are entered for each parameter. For a userdefined parameter SERVER with value SRV1, the keyword %SERVER% will contain SRV1 at the script execution time. 9 BackBox H4.
Script controller Script controller The script controller is an optional tool to manage Windows backup and restore scripts initiated by the VTC.
Script controller Note that this feature targets environments where numerous scripts are submitted, and where the back-end Enterprise Backup server saves BackBox Windows files on physical sequential media. In simple setups, the retry mechanism is likely to be the only interesting feature.
Script controller Processing summary BBBACKUP/BBRESTORE forwards the backup/restore request, one request per file, usually two requests per virtual volume: one for the *.DAT file, another for the *.IND file. The script controller queues in memory the list of backup/restore requests, and processes them according the parameters passed along the command BBBACKUP or BBRESTORE. Requests in different queue names are processed concurrently.
Script controller When the parameter BBOX_GENERATED_LINE is present, the temporary file contains an Enterprise Backup command per file to process. This file is to be used as standard input of the Enterprise Backup client in the subscript. When the subscript ends, the script manager accesses all the files processed in the subscript. The file existence and Archive bit setting tell if the file was processed correctly. Files not processed are kept in queue on a file-per-file basis for retry.
Script controller BBBACKUP BBBACKUP sends the backup request to the controller BBOX_SCRIPT_TIMEOUT for the backup subscript completion. and waits up to When the timeout is reached, BBBACKUP issues an EMS message although the backup request is still being processed by the Script Controller. The script controller will process the backup requests on a FIFO basis for each queue.
Script controller Maximum number of times the script controller retries the backup of each file. Default value is 0. BBOX_SCRIPT_RETRY_DELAY Number of minutes Artificial delay waited between a failure and a retry. Default value is 10. BBOX_SCRIPT_TEMP_DIR Windows directory used to create temporary files. Default value is current directory.
Script controller BBRESTORE BBRESTORE sends the restore request to the controller and waits up to the timeout value that the restore sub-script completes. In a given queue, the script controller will process the requests in FIFO sequence, until the parameter BBOX_SCRIPT_SORT_MAX_DELAY number-of-minutes is specified. This parameter makes the files be restored in the same sequence they were backed up, in order to minimize the repositioning on the physical media.
Script controller Example: SET BBOX_SCRIPT_TIMEOUT=36000 SET BBOX_SCRIPT_MAX_RETRY=6 SET BBOX_SCRIPT_RETRY_DELAY=5 SET BBOX_SCRIPT_TEMP_DIR=C:\BBOX\script\temp SET BBOX_SCRIPT_MAX_THREADS=1 BBRESTORE MyQueue C:\BBOX\script\sub_restore.cmd Parameters: BBOX_SCRIPT_BK_SOFTWARE Software identifier Type of the Enterprise backup software run by the subscript. Used for querying the backup server and optimize the restore. No default value. Should be set to TSM or omitted.
Script controller Artificial delay waited between a failure and a retry. Default value is 10. BBOX_SCRIPT_TEMP_DIR Windows directory used to create temporary files. Default value is current directory. BBOX_SCRIPT_MAX_THREADS Number of concurrent threads per queue Default value is 1 BBOX_BACKUP_SIZE Number of MB Maximum total size of Windows files to process in a single subscript execution. The goal is only to avoid extraordinary long script executions.
Script controller Default value is OFF. BBOX_GENERATED_LINE Command pattern for the Enterprise Backup command line client, to restore a file. Use #file# as placeholder in the command pattern for the name of the file to restore. Windows variables set by the VTC for the regular restore script are available, ex: %BBOX_DOMAIN%, %BBOX_NEW_DIR%. Windows parameters that vary for each virtual volume must be not used, ex: %BBOX_VOLUME%. Default value is #file#, to produces a file-list.
